# Nucleus — full documentation

> Nucleus is the production desktop layer for Compose Multiplatform — native OS integration and packaging for Kotlin teams.

Source: https://nucleusframework.dev/en/docs

---

# Welcome to Nucleus 2.5

URL: https://nucleusframework.dev/en/docs

Nucleus is the production desktop layer for Compose Multiplatform — native OS integration and packaging for Kotlin teams.

Nucleus is the production desktop layer for Compose Multiplatform apps written in Kotlin. Compose draws
the UI; Nucleus adds native window decorations, operating-system integration, code signing, installers,
and store pipelines. You configure the whole build through a single Gradle DSL, and the runtime runs
either as a GraalVM native image or on the JVM.

If you already ship Android or KMP, Nucleus is how the same team ships desktop — without a second stack.

Paste one prompt into your coding agent (Claude Code, Cursor, Codex, …) — it scans your app,
asks the right questions, and migrates it to Nucleus phase by phase with verification
checkpoints. Zero install: the whole playbook lives at one URL. See
[Migrate with an AI agent](/docs/migrate/ai-agent).

## Features

- **One language across platforms.** Share Kotlin code with your Android, iOS, and web apps, with Compose UI on top.
- **Native windowing (Tao).** Wayland support, multi-touch, pen input, [window scaffold](/docs/tao/window-scaffold), [TextureView](/docs/tao/texture-view) for external GPU frames, and [GPU render context](/docs/tao/gpu-render-context) for in-process renderers.
- **Two runtimes, one DSL.** Run as a GraalVM Native Image, or on the JVM with an AOT cache (JDK 25+).
- **Over 40 OS integration modules.** Notifications, system tray, dock menus, dark mode, global hotkeys, and taskbar integration, each added as an opt-in dependency.
- **18 packaging formats.** DMG, PKG, MSI, AppX, DEB, RPM, AppImage, Snap, and Flatpak among them, with code signing, notarization, and [differential auto-update](/docs/packaging/auto-update#differential-downloads).
- **Native design systems.** [macOS 26](https://github.com/NucleusFramework/compose-macos-26-ui), [Fluent](https://github.com/NucleusFramework/compose-fluent-ui), and [Yaru](https://github.com/NucleusFramework/yaru-compose-ui) on Maven Central, plus Jewel and Material adapters in this repo. See [toolkits](/docs/window/toolkits).

To build your first app, follow the [quickstart](/docs/start/quickstart).

## What's new in 2.5

- **Spell check.** The OS spell engine in Compose text fields — Hunspell, `NSSpellChecker`, Windows Spell Checking — with suggestions in the context menu. See [Spell check](/docs/os/spell-check#check-a-text-field).
- **Native context menus.** One flag swaps the Compose menu for the platform's: `NSMenu`, Fluent, Adwaita, or Breeze. See [Context menus](/docs/window/context-menu#turn-on-the-native-menu).
- **Overlay windows.** Click-through, always-on-bottom, and all-workspaces flags for watermarks and desktop widgets. See [Overlay windows](/docs/tao/overlay-windows#build-a-click-through-watermark).
- **Compose over native views.** The `NativeView` overlay slot now draws in the window's own scene on all three platforms. See [Overlay Compose content](/docs/tao/native-views#overlay-compose-content).
- **Compose 1.12** is required from this line on. See [Compatibility](/docs/start/install#compatibility).

Full list: [Changelog](/docs/changelog).

## Talk with us

The Nucleus channel is `#nucleus` on the official Kotlin Slack. Use it for questions, design
discussion, and bug reports.

If you are not on the Kotlin Slack yet, [request an invite](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up),
then open [#nucleus](https://kotlinlang.slack.com/archives/C0BQYKHBGR0).

## What's next

- [Why Nucleus](/docs/why-nucleus) — what vanilla Compose Desktop leaves open, and what Nucleus fills.
- [Nucleus vs vanilla CMP](/docs/compare/cmp-default) — the decision table for Kotlin teams.
- [Migrate with an AI agent](/docs/migrate/ai-agent) — one prompt, zero install.
- [Migrate from JetBrains Compose Desktop](/docs/migrate/from-jb-compose) — drop-in migration.
- [Quickstart](/docs/start/quickstart) — build and run your first Nucleus desktop app.
- [Architecture](/docs/concepts/architecture) — the layered model behind the framework.

---

# Why Nucleus

URL: https://nucleusframework.dev/en/docs/why-nucleus

What Nucleus adds on top of Compose Multiplatform for Kotlin teams shipping real desktop apps.

Kotlin and Compose already own Android. They reach iOS and the web. On the desktop, Compose Multiplatform
renders the UI — but shipping a real product still means native chrome, OS integration, packaging, signing,
auto-update, and store pipelines that the default plugin does not provide.

Nucleus is that production layer. Same Compose. Same Kotlin team. The rest of the desktop stack, already built.

## The gap Compose Desktop leaves open

Compose Multiplatform is the right UI foundation. It is not a full desktop product stack.

| | Vanilla Compose Desktop | Nucleus |
|---|---|---|
| **UI** | Compose + Skia | Same Compose + Skia |
| **Window chrome** | Basic / Material-looking | Native decorations (Liquid Glass, Fluent, Yaru, Jewel) |
| **OS APIs** | Thin (`Tray`, `Notification`) | 40+ Kotlin modules (tray, dock, hotkeys, media, dark mode, …) |
| **Packaging** | 6 jpackage formats | **18** formats, including store channels |
| **Auto-update** | None | Built-in (`updater-runtime`) |
| **Signing / CI** | DIY | Signing, notarization, reusable GitHub Actions |
| **Runtimes** | JVM | GraalVM Native Image **or** JVM + AOT cache |
| **Migration** | — | Drop-in on the JetBrains Compose plugin |

If you only need a window and a DMG/MSI/DEB, vanilla CMP is enough. The moment you need native look-and-feel,
store distribution, auto-update, or real OS integration without writing JNI per platform — that is Nucleus.

Deep dive: [Nucleus vs vanilla Compose Multiplatform](/docs/compare/cmp-default).

## Built for teams that already write Kotlin

Nucleus is not a new language bet. It is for teams that already ship Android (or KMP) and need a desktop
surface without hiring a second stack.

- **Same hiring pool** — Compose skills transfer. No Rust/JS/Electron team required.
- **Same codebase path** — domain, networking, and much of the UI live in `commonMain`.
- **Same Gradle world** — one DSL, hot reload, familiar CI.
- **Drop-in migration** — rename `compose.desktop.application` → `nucleus.application` and keep shipping.
  See [Migrating from JetBrains Compose Desktop](/docs/migrate/from-jb-compose).

## What Nucleus provides

- **Native decorated window** — a `DecoratedWindow` that follows macOS/Windows/Linux title-bar conventions,
  backed by the [Tao backend](/docs/concepts/backends).
- **Runtime modules** — more than 40 modules covering notifications, system tray, global hotkeys, taskbar
  progress, dark mode, accent colour, dock menus, jump lists, media controls, auto-launch, scheduler,
  auto-update, system info, and file dialogs. Each is optional and written in Kotlin.
- **Two runtimes** — GraalVM Native Image produces a self-contained binary (around 40 MB as an NSIS
  installer with maximum compression, starting in about 0.2 s); JVM with an AOT cache runs on HotSpot for
  long-running workloads. Reachability metadata — for your third-party libraries too — is resolved
  automatically at build time. Switch with one Gradle setting.
- **18 packaging formats** — DMG, PKG, Exe, MSI, NSIS, NSIS Web, Portable, AppX/MSIX, DEB, RPM, AppImage,
  RawAppImage, Pacman, Snap, Flatpak, ZIP, TAR, and 7Z, with signing and notarization.
- **CI support** — reusable GitHub Actions, multi-platform matrix builds, universal macOS binaries, and
  MSIX bundles.

## What's next

- [Nucleus vs vanilla Compose Multiplatform](/docs/compare/cmp-default) — the decision table for Kotlin teams.
- [Migrating from JetBrains Compose Desktop](/docs/migrate/from-jb-compose) — drop-in steps.
- [Quickstart](/docs/start/quickstart) — build and run a Tao window.
- [Architecture](/docs/concepts/architecture) — layers from your app down to the JVM or GraalVM.

---

# Install

URL: https://nucleusframework.dev/en/docs/start/install

Add the Nucleus Gradle plugin to a Kotlin project to build for macOS, Linux, and Windows from a single build.

In this tutorial, you'll add the Nucleus Gradle plugin to a Kotlin project. Once the plugin is
applied, the same build can compile, run, and package a desktop app for macOS, Linux, and Windows.

## Before you start

Nucleus builds on Compose Multiplatform and requires:

- **JDK 17 or later** on your `PATH`.
- **Kotlin 2.4.10 or later** — see [Compatibility](#compatibility) for the version each Nucleus
  line needs.
- **Gradle 8.0 or later**. The Gradle wrapper bundled with new projects is sufficient.

JDK 25 or later is required only to generate the AOT cache (`enableAotCache` in `nativeDistributions`).
Any JDK 17+ works for development.

## Compatibility

| Nucleus Version | Kotlin Version | Compose Version |
|-----------------|----------------|-----------------|
| 2.5.0 – 2.5.18  | 2.4.10+        | 1.12.0          |
| 2.0.0 – 2.4.7   | 2.4.0+         | 1.11.1          |

The Compose version is a requirement, not a floor: `decorated-window-tao` builds against Compose
Multiplatform internals that change between minors, so 2.5.x needs 1.12.0 and will not run on
1.11.x. Pin the Compose plugin to the row that matches your Nucleus version.

The Kotlin version is a minimum. Nucleus is compiled with the version in the table, and an older
compiler cannot read its metadata.

## Apply the plugin

In your module's `build.gradle.kts`, apply the Nucleus plugin alongside the Kotlin and Compose plugins:

```kotlin title="build.gradle.kts"
plugins {
    kotlin("jvm") version "2.4.10"
    id("org.jetbrains.compose") version "1.12.0"
    id("dev.nucleusframework") version "<version>"
}
```

The `plugins` block resolves `dev.nucleusframework` from the Gradle Plugin Portal, so no extra
`pluginManagement` repository is required.

## Add the repositories

Nucleus runtime modules publish to Maven Central under the group `dev.nucleusframework`. Add the
repositories the plugin and its runtime need:

```kotlin title="build.gradle.kts"
repositories {
    mavenCentral()
    google()
}
```

## Verify the plugin is applied

Applying the plugin registers a `nucleus` task group. List its tasks to confirm the plugin loaded:

```shell
./gradlew tasks --group nucleus
```

If the command prints the group's tasks, the plugin is applied and you can start building.

## What's next

- [Quickstart](/docs/start/quickstart) — write a `main` function, run a native Tao window, and package an installer.
- [Project setup](/docs/start/project-setup) — repositories, Gradle properties, JDK toolchains, and multi-module layout.
- [Configuration](/docs/start/configuration) — the full `nucleus { }` DSL.

---

# Quickstart

URL: https://nucleusframework.dev/en/docs/start/quickstart

Build and run your first Nucleus desktop app, then package it as a native installer.

In this tutorial, you'll create a Nucleus desktop app from scratch, run it as a native
Tao window, and package it into an installer for your current operating system. The whole
app is two files: a Gradle build script and a Kotlin `main` function.

## Before you start

Nucleus builds on Compose Multiplatform and requires:

- **JDK 17 or later** on your `PATH`.
- **Kotlin 2.4.10 or later** and **Gradle 8.x**.

## Create the build script

In an empty project directory, create `build.gradle.kts` and apply the Nucleus plugin:

```kotlin title="build.gradle.kts"
plugins {
    kotlin("jvm") version "2.4.10"
    id("org.jetbrains.compose") version "1.12.0"
    id("dev.nucleusframework") version "<version>"
}

repositories {
    mavenCentral()
    google()
}

dependencies {
    implementation(compose.desktop.currentOs)
    // The entry-point module — provides nucleusApplication and DecoratedWindow
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    // Enable the Tao backend (Rust-native windowing)
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}

nucleus.application {
    mainClass = "com.example.MainKt"

    nativeDistributions {
        packageName = "MyApp"
        packageVersion = "1.0.0"
        targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
    }
}
```

Already have a Compose Desktop app? Nucleus extends `org.jetbrains.compose`, so switching is a
rename — drop the vanilla `compose.desktop.application { }` block and point it at Nucleus:

```diff
-compose.desktop.application {
+nucleus.application {
     mainClass = "com.example.MainKt"
     // nativeDistributions { ... } stays the same
 }
```

The entry point in `main` follows the same swap: `application { Window(...) }` becomes
`nucleusApplication { DecoratedWindow(...) }`. See [Migrating from Compose Desktop](/docs/migrate/from-jb-compose).

## Write the application

Create `src/main/kotlin/com/example/Main.kt`:

```kotlin
package com.example

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.NucleusBackend
import dev.nucleusframework.application.nucleusApplication

fun main() = nucleusApplication(backend = NucleusBackend.Tao) {
    DecoratedWindow(
        onCloseRequest = ::exitApplication,
        title = "MyApp",
    ) {
        Box(Modifier.fillMaxSize()) {
            Text("Hello from Nucleus")
        }
    }
}
```

The `nucleusApplication` entry point starts the Nucleus runtime and opens a `DecoratedWindow` —
a Compose window with a native title bar.

`NucleusBackend.Auto` (the default) picks Tao when `decorated-window-tao` is on the classpath,
and falls back to the deprecated AWT backend otherwise. Force a backend with `NucleusBackend.Tao`.
See [Backends](/docs/concepts/backends).

## Run the app

```shell
./gradlew run
```

A native window opens with a custom title bar — drawn by Tao on Linux and Windows, and by
the system on macOS.

## Package the app

```shell
./gradlew packageDistributionForCurrentOS
```

The installer is written to `build/compose/binaries/main/<format>/`: a `.dmg` on macOS, an
`.msi` on Windows, and a `.deb` on Linux. Add formats by extending `targetFormats(...)`.
See [Configuration](/docs/start/configuration).

## What's next

- [Project setup](/docs/start/project-setup) — multi-module layout, Gradle properties, and JDK config.
- [Configuration](/docs/start/configuration) — the full `nucleus { }` DSL.
- [Architecture](/docs/concepts/architecture) — what runs under your `main` function.

---

# Project setup

URL: https://nucleusframework.dev/en/docs/start/project-setup

Configure repositories, the Nucleus plugin, runtime modules, a JDK toolchain, and a multi-module Gradle layout.

In this tutorial, you'll set up a multi-module Nucleus project. You'll configure the
repositories, apply the Gradle plugin, pin the runtime modules, choose a JDK toolchain, and
lay out `:app`, `:ui`, and `:domain` modules so that dependencies flow in one direction.

## Before you start

This tutorial builds on the [Quickstart](/docs/start/quickstart), which fits in a single
module. You need:

- **JDK 17 or later** for a standard build, or **JDK 25** to enable the AOT cache.
- **Kotlin 2.4.10 or later** and **Gradle 8.x**.

## Configure the repositories

Resolve the plugin from the Gradle Plugin Portal and the runtime modules from Maven Central.
Add both to `settings.gradle.kts`:

```kotlin title="settings.gradle.kts"
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
        google()
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}
```

## Apply the plugin

Apply the Nucleus plugin in the module that holds your `main` function:

```kotlin title="app/build.gradle.kts"
plugins {
    kotlin("jvm") version "2.4.10"
    id("org.jetbrains.compose") version "1.12.0"
    id("dev.nucleusframework") version "<version>"
}
```

Compose Hot Reload works out of the box. Apply the `org.jetbrains.compose.hot-reload` plugin,
then run `./gradlew hotRun` — Nucleus resolves the entry point from `nucleus.application.mainClass`
automatically, with no `ComposeHotRun` configuration. `hotDev` without `-PclassName` behaves like
`hotRun`. Hot reload was added in Nucleus 2.1.

## Add the runtime modules

All `dev.nucleusframework:nucleus.*` runtime artifacts publish the same version. Pin it once,
then declare only the modules you use:

```kotlin title="app/build.gradle.kts"
val nucleusVersion = "<version>"

dependencies {
    implementation(compose.desktop.currentOs)
    implementation("dev.nucleusframework:nucleus.nucleus-application:$nucleusVersion")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:$nucleusVersion")
    // Add only the modules you need:
    implementation("dev.nucleusframework:nucleus.notification-common:$nucleusVersion")
    implementation("dev.nucleusframework:nucleus.global-hotkey:$nucleusVersion")
}
```

`nucleus-application` is the entry-point module. It transitively pulls the core runtime, the
AOT runtime, and the GraalVM runtime. Add `decorated-window-tao` for the window backend; every
other module is opt-in.

## Set the JDK toolchain

Pin a JDK toolchain so the build uses a consistent Java version:

```kotlin title="app/build.gradle.kts"
kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(25))
        // Optional: pin the vendor for reproducible builds
        // vendor.set(JvmVendorSpec.JETBRAINS)
    }
}
```

Use JDK 17 if you don't need the AOT cache. Use JDK 25 to enable it with
`enableAotCache = true` inside `nativeDistributions`. For GraalVM native images, set the Java
version with `nucleus.application.graalvm { javaLanguageVersion.set(25) }`. See
[Configuration](/docs/start/configuration) for both.

## Configure gradle.properties

These settings speed up the build and enable the configuration cache, which the Nucleus
plugin supports:

```properties title="gradle.properties"
org.gradle.jvmargs=-Xmx4g -XX:+UseG1GC
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true

kotlin.code.style=official
```

## Lay out the modules

A single module works for small apps. As the app grows, split UI, application wiring, and
business logic into separate modules:

```
my-app/
├── settings.gradle.kts
├── build.gradle.kts             ← shared conventions, no plugins
├── app/                         ← Nucleus entry point + main()
│   └── build.gradle.kts         ← applies dev.nucleusframework
├── ui/                          ← Compose composables, themes
│   └── build.gradle.kts
└── domain/                      ← pure Kotlin: models, repositories, services
    └── build.gradle.kts
```

Follow these rules to keep dependencies flowing in one direction:

- Only `:app` applies `dev.nucleusframework`, and only `:app` declares
  `nucleus.application { … }`.
- `:domain` stays pure Kotlin, so you can share it with Android or iOS later by moving it into
  a Kotlin Multiplatform `commonMain` source set.
- Platform-specific code, such as a macOS dock menu or a Windows jump list, lives next to the
  code that uses it, most often inside `:app`.

## Share code across platforms

The Nucleus runtime modules are JVM-only, but `:domain` and `:ui` can be Kotlin Multiplatform
modules. The `:app` module consumes their JVM target and needs no change when you add other
targets.

## What's next

- [Quickstart](/docs/start/quickstart) — build and run a single-module app first.
- [Configuration](/docs/start/configuration) — the full `nucleus { }` Gradle DSL.
- [Modules](/docs/concepts/modules) — how Nucleus modules compose.
- [Runtimes](/docs/concepts/runtimes) — the core, AOT, and GraalVM runtimes.

---

# Configuration

URL: https://nucleusframework.dev/en/docs/start/configuration

Configure the nucleus { } Gradle DSL — application metadata, packaging formats, per-OS options, GraalVM native image, AOT cache, deep links, file associations, and trusted CA injection.

The `nucleus { }` extension configures how your app is built and packaged, in your `build.gradle.kts`. It extends the Compose Desktop `application` DSL with a GraalVM native-image path, additional packaging formats, an AOT cache, deep-link protocols, and trusted CA injection.

## Configure the application

Use `nucleus.application { }` for a JVM application. The `nativeDistributions { }` block holds all packaging configuration, and the `graalvm { }` block controls the native-image path.

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"
    jvmArgs("-Xmx512m")

    nativeDistributions {
        packageName = "MyApp"
        packageVersion = "1.0.0"
        targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)

        modules("java.sql", "java.net.http")
        cleanupNativeLibs = true

        protocol("MyApp", "myapp")
        fileAssociation(
            mimeType = "application/x-myapp",
            extension = "myapp",
            description = "MyApp Document",
        )

        macOS { /* … */ }
        windows { /* … */ }
        linux { /* … */ }
    }

    graalvm {
        isEnabled.set(false)
    }
}
```

To configure a Kotlin/Native application instead, use `nucleus.nativeApplication { }`.

## Choose a runtime strategy

Nucleus can ship your app as a bundled JVM, a GraalVM native image, or a JVM with an AOT cache.

**Bundled JVM**

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"
    nativeDistributions {
        packageName = "MyApp"
        packageVersion = "1.0.0"
        targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
        cleanupNativeLibs = true
    }
}
```

Bundles a JRE alongside your app. This is the default and requires the least configuration.

**GraalVM native image**

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"
    nativeDistributions {
        packageName = "MyApp"
        packageVersion = "1.0.0"
        targetFormats(TargetFormat.Dmg, TargetFormat.Nsis, TargetFormat.Deb)
    }
    graalvm {
        isEnabled.set(true)
        javaLanguageVersion.set(25)
        imageName.set("myapp")
        march.set(NativeImageMarch.NATIVE)
        buildArgs.add("-O2")
    }
}
```

Compiles the app to a self-contained native binary. Reachability metadata for Nucleus modules is injected automatically.

**JVM with AOT cache**

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"
    nativeDistributions {
        packageName = "MyApp"
        packageVersion = "1.0.0"
        targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
        enableAotCache = true
    }
}
```

Requires JDK 25 or later. The build generates an AOT cache and ships it with the launcher, so classes and profiles are pre-warmed at startup.

## `application { }` reference

| Property | Type | Description |
|---|---|---|
| `mainClass` | `String?` | Entry-point class (FQCN of the file containing `fun main`). |
| `mainJar` | `RegularFileProperty` | Override the main JAR; rarely needed. |
| `javaHome` | `String` | JDK used for packaging the JVM image. |
| `args` | `MutableList<String>` | App arguments at launch. Also `args(vararg String)`. |
| `jvmArgs` | `MutableList<String>` | JVM flags baked into the launcher. Also `jvmArgs(vararg String)`. |
| `nativeDistributions { }` | block | Packaging configuration. |
| `buildTypes { release { proguard { } } }` | block | ProGuard rules for release builds. |
| `graalvm { }` | block | GraalVM native-image configuration. |
| `disableDefaultConfiguration()` | fn | Opt out of the auto-discovered source set. |
| `from(SourceSet \| KotlinTarget)` | fn | Pick a source set or KMP target explicitly. |

## `nativeDistributions { }` reference

| Property / call | Description |
|---|---|
| `targetFormats(...)` | Select packaging formats. See [the format list](#select-packaging-formats) below. |
| `packageName`, `packageVersion`, `description`, `vendor`, `copyright`, `homepage`, `licenseFile` | App metadata. `homepage` is required for Linux DEB. |
| `modules(...)`, `includeAllModules` | JDK modules to include. Default: `java.base`, `java.desktop`, `java.logging`, `java.net.http`, `jdk.accessibility`, `jdk.crypto.ec`, `jdk.unsupported`. |
| `cleanupNativeLibs` | Strip non-target native libraries from dependency JARs. |
| `enableAotCache` | Generate a JDK 25+ AOT cache. |
| `splashImage` | Path (relative to app resources) to a splash PNG. |
| `compressionLevel` | `CompressionLevel.Store`, `Normal`, `Maximum`, or `Ultra` (extra DMG/DEB recompression). Overridable per format via `linux.appImage { compressionLevel }` and `windows.portable { compressionLevel }`. |
| `artifactName` | Template. Default: `${name}-${version}-${os}-${arch}.${ext}`. |
| `trustedCertificates.from(...)` | Extra CA bundles imported into the bundled JDK `cacerts`. |
| `protocol(name, vararg schemes)` | Register a custom URL protocol (deep link). |
| `fileAssociation(mimeType, extension, description, linuxIconFile?, windowsIconFile?, macOSIconFile?)` | Register a file type. Call multiple times for multiple associations. |
| `publish { }` | GitHub Releases, S3, or generic HTTP publishing config. |
| `macOS { }`, `windows { }`, `linux { }` | Per-OS overrides. |

## Select packaging formats

`targetFormats(...)` takes any of the 18 `TargetFormat` values:

| OS | Formats |
|---|---|
| macOS | `Dmg`, `Pkg` |
| Windows | `Msi`, `Exe`, `Nsis`, `NsisWeb`, `Portable`, `AppX` |
| Linux | `Deb`, `Rpm`, `AppImage`, `Pacman`, `Snap`, `Flatpak` |
| Any | `Zip`, `Tar`, `SevenZ`, `RawAppImage` |

```kotlin title="build.gradle.kts"
nativeDistributions {
    targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
}
```

`Pkg`, `AppX`, and `Flatpak` are the store formats. See [Packaging](/docs/packaging) for per-format details.

## Set per-OS options

Each `macOS`, `windows`, and `linux` block overrides metadata and behavior for that target.

```kotlin title="build.gradle.kts"
nativeDistributions {
    macOS {
        bundleID = "com.example.myapp"
        dockName = "MyApp"
        appCategory = "public.app-category.productivity"
        minimumSystemVersion = "12.0"
        iconFile.set(project.file("icons/app.icns"))

        infoPlist {
            extraKeysRawXml = """
                <key>NSCameraUsageDescription</key>
                <string>MyApp needs the camera for QR scanning.</string>
            """.trimIndent()
        }

        signing {
            sign.set(true)
            identity.set("Developer ID Application: My Company (TEAMID)")
        }
        notarization {
            appleID.set(System.getenv("APPLE_ID"))
            password.set(System.getenv("APPLE_APP_PASSWORD"))
            teamID.set("TEAMID")
        }

        // macOS SDK version linked into the launcher
        macOsSdkVersion = "26.0"
    }
    windows {
        packageName = "MyApp"
        upgradeUuid = "00000000-0000-0000-0000-000000000000"
        menu = true
        perUserInstall = true
        iconFile.set(project.file("icons/app.ico"))
        signing {
            // Authenticode signing config
        }
    }
    linux {
        packageName = "myapp"
        appCategory = "Utility"
        menuGroup = "Utility"
        debMaintainer = "ops@example.com"
        iconFile.set(project.file("icons/app.png"))
        rpmLicenseType = "MIT"
    }
}
```

See [Code signing](/docs/packaging/code-signing) for the full signing and notarization surface.

## Register deep links

```kotlin title="build.gradle.kts"
nativeDistributions {
    protocol("MyApp", "myapp")
}
```

This wires `CFBundleURLTypes` on macOS, registry entries on Windows, and `MimeType=x-scheme-handler/myapp` in the Linux `.desktop` file. Receive the URI at runtime through `NucleusApplicationScope.onDeepLink { uri -> … }`. See [Deep links](/docs/lifecycle/deep-links).

## Associate file types

```kotlin title="build.gradle.kts"
nativeDistributions {
    fileAssociation(
        mimeType = "application/x-myapp",
        extension = "myapp",
        description = "MyApp Document",
        linuxIconFile = project.file("icons/file.png"),
        windowsIconFile = project.file("icons/file.ico"),
        macOSIconFile = project.file("icons/file.icns"),
    )
}
```

Call `fileAssociation(...)` once per file type.

## Inject trusted CA certificates

```kotlin title="build.gradle.kts"
nativeDistributions {
    trustedCertificates.from(files("certs/company-proxy-ca.pem"))
}
```

Accepts PEM or DER. The certificates are imported into the bundled JDK's `cacerts` at build time, which is useful behind a corporate proxy. To trust the OS keychain at runtime instead, use [`native-ssl`](/docs/performance/native-ssl).

## Configure a GraalVM native image

| Property | Default | Description |
|---|---|---|
| `isEnabled` | `false` | Master switch. |
| `javaLanguageVersion` | `25` | GraalVM JDK to use. |
| `jvmVendor` | (auto) | Override the toolchain vendor. |
| `imageName` | (auto) | Output binary name. |
| `march` | `NativeImageMarch.COMPATIBILITY` (`NATIVE` on macOS arm64) | Target CPU instruction set. |
| `buildArgs` | `[]` | Extra `native-image` flags. |
| `nativeImageConfigBaseDir` | (build dir) | Where to write reflection and resource configs. |
| `metadataRepository.enabled` | `true` | Use the GraalVM Reachability Metadata Repository. |
| `metadataRepository.version` | `"1.1.4"` | Repository version. |
| `metadataRepository.excludedModules` | `[]` | Skip metadata for specific modules. |
| `macOS.minimumSystemVersion` | `"12.0"` | Minimum macOS target. |
| `macOS.macOsSdkVersion` | `"26.0"` | macOS SDK linked into the launcher. |
| `windows.bundleCRuntime` | `true` | Bundle the MSVC runtime DLLs next to the binary. |

See [GraalVM](/docs/performance/graalvm) for the full walkthrough.

## Enable the AOT cache

```kotlin title="build.gradle.kts"
nativeDistributions {
    enableAotCache = true
}
```

Requires JDK 25 or later. The plugin runs a training pass that boots your app to the first frame, snapshots the JVM's class state, and ships the cache alongside the launcher. See [AOT cache](/docs/performance/aot-cache).

## Shrink release builds with ProGuard

```kotlin title="build.gradle.kts"
buildTypes {
    release {
        proguard {
            isEnabled = true
            optimize = true
            obfuscate = false
            joinOutputJars = true
            configurationFiles.from(project.file("proguard-rules.pro"))
        }
    }
}
```

Release tasks are suffixed `Release`, for example `packageReleaseDmg`.

`CompressionLevel.Maximum` and `Ultra` with AppImage cause very slow startup due to squashfs/FUSE decompression. Use `Normal` or `Store` for AppImage targets — set `linux.appImage { compressionLevel = CompressionLevel.Normal }` when the root level is higher for DEB/DMG.

## What's next

- [Packaging](/docs/packaging) — per-format details, code signing, and store publishing.
- [GraalVM](/docs/performance/graalvm) — reachability metadata, build args, and CI.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — every property and type.

---

# Architecture

URL: https://nucleusframework.dev/en/docs/concepts/architecture

The four layers that make up a Nucleus application and how they fit together.

A Nucleus application is built from four layers: your code, the Nucleus runtime, Compose
Multiplatform, and the JVM or native runtime underneath. Each layer has a distinct job, and each
one can be swapped without rewriting the layer above it. This page describes what each layer does
and how a frame reaches the screen.

## The four layers

### Your application

Compose UI, view-models, and business logic, written in Kotlin. To share this code with Android
and iOS, place it in a Kotlin Multiplatform `commonMain` source set.

```kotlin
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue

// Pure Kotlin — runs on every platform Compose targets.
class CounterViewModel {
    var count by mutableStateOf(0)
        private set

    fun increment() { count++ }
}
```

### The Nucleus runtime

More than 40 runtime modules, grouped by intent:

- **OS integration** — decorated windows (Tao backend), notifications, system tray, dock and
  launcher menus, dark-mode detection, global hotkeys, media controls, and system colors.
- **Performance** — GraalVM Native Image, the AOT cache (JDK 25+), the energy manager, and native
  HTTP/SSL.
- **Distribution** — 18 packaging formats, code signing and notarization, auto-update, deep links,
  auto-launch, and reusable CI actions.

Every module is optional and written in Kotlin. You add the ones you need as Gradle dependencies —
see [Modules](/docs/concepts/modules).

The Gradle plugin (`dev.nucleusframework`) is the build-time half of this layer. It selects
packaging formats, wires up GraalVM, injects reachability metadata, and generates
`nucleus-app.properties` so that `NucleusApp` in `core-runtime` can read your application's
identity at runtime.

### Compose Multiplatform

A type-safe, reactive UI toolkit rendered on Skia, with hot reload, Compose Resources, and a
unified pointer and keyboard event model.

Nucleus does not replace Compose; it plugs into it. Every `DecoratedWindow` is a Compose
`@Composable`, and every Nucleus module that touches the UI — `isSystemInDarkMode()`,
`systemAccentColor()`, `NativeMenuBar`, and others — is a composable too.

### Kotlin Multiplatform

Shared modules, coroutines, `StateFlow`, `kotlinx.serialization`, and Ktor: the same Kotlin
Multiplatform stack you already use for Android and iOS. The Nucleus runtime modules are JVM-only,
but the layers above them stay multiplatform.

### The JVM or native runtime

A Nucleus application runs on one of three runtimes:

- **OpenJDK 17+** — the broadest compatibility, works with the Tao backend on stock JDKs.
- **JetBrains Runtime (JBR)** — an OpenJDK fork required only by the deprecated AWT backend (see
  [Backends](/docs/concepts/backends)).
- **GraalVM Native Image** — a closed-world, ahead-of-time compile that produces a self-contained
  binary with no bundled JRE.

Switching runtimes is a one-line DSL change — see [Runtimes](/docs/concepts/runtimes).

A Nucleus application requires JDK 17 or later. Most runtime modules compile to Java 11 bytecode,
so code that embeds them stays compatible with older toolchains. The Compose-facing ones —
`nucleus-application`, the window backends and the style adapters — target Java 17, and
`decorated-window-jewel` targets Java 25.

## How a frame is drawn

When the user clicks a button:

1. The OS — or the [Tao](/docs/tao) Rust layer — emits an input event.
2. The active backend module ([`decorated-window-tao`](/docs/concepts/backends)) translates it
   into a Compose `PointerEvent`.
3. Compose recomposes, asks Skia to draw the affected layers, and hands the GPU surface back to
   the backend.
4. The backend swaps buffers through the OS compositor (Wayland, DWM, or Quartz).

Your code stays in Kotlin the whole way down.

## What's next

- [Runtimes](/docs/concepts/runtimes) — choosing GraalVM Native Image versus the JVM with the AOT cache.
- [Backends](/docs/concepts/backends) — Tao, and the deprecated AWT backend, under your `DecoratedWindow`.
- [Modules](/docs/concepts/modules) — how the runtime modules compose.

---

# Runtimes

URL: https://nucleusframework.dev/en/docs/concepts/runtimes

Nucleus can run your packaged app as a GraalVM native image or on the JVM with an AOT cache, selected from the Gradle build.

A Nucleus app can run on one of two runtimes: a GraalVM native image, or the JVM with
an ahead-of-time (AOT) cache. Both build from the same code — you choose the runtime in your
Gradle build. This page describes each runtime, the tradeoffs between them, and how to detect
which one your app is running under.

## GraalVM native image

A native image compiles your app ahead of time into a single self-contained binary. It bundles
no JRE, so the installer only ships one executable per operating system.

Enable it in the plugin DSL:

```kotlin title="build.gradle.kts"
nucleus.application {
    graalvm {
        isEnabled.set(true)
    }
}
```

A native image is closed-world: reflection, dynamic class loading, and JNI must be known at
build time. Nucleus resolves reachability metadata automatically — for your third-party
libraries too, not just its own modules — from a curated set, the Oracle repository, and static
bytecode analysis, so most apps compile without hand-written config. See
[automatic metadata resolution](/docs/performance/graalvm/automatic-metadata).

Because there is no JVM warmup, a native image reaches its first frame quickly. The tradeoff is
the closed-world constraint: no runtime class loading, no Java agents, no JFR, and no dynamic
`ScriptEngine`. If your app loads plugins or generates classes at runtime, use the JVM runtime
instead.

## JVM with an AOT cache

The JVM runtime ships the full HotSpot runtime and keeps every dynamic feature: reflection,
dynamic class loading, agents, JFR, and `ScriptEngine`. The AOT cache pre-warms classes and
profiles so the app starts faster than a cold JVM while HotSpot's JIT still compiles hot paths.

Enable the cache under `nativeDistributions`:

```kotlin title="build.gradle.kts"
nucleus.application {
    nativeDistributions {
        enableAotCache = true
    }
}
```

The cache adds a few megabytes to the distribution. See [AOT cache](/docs/performance/aot-cache)
for how training runs produce the cache and what it contains.

## Choosing a runtime

The two runtimes trade startup and binary size against dynamic capability:

| | GraalVM native image | JVM + AOT cache |
|---|---|---|
| Compilation | Ahead-of-time, closed-world | HotSpot JIT, AOT cache warms startup |
| Bundled runtime | None (self-contained binary) | Full HotSpot JRE |
| Dynamic features | Restricted; must be declared as reachability metadata | Available |
| Startup | No JVM warmup | Slower cold, improved by the AOT cache |
| Throughput | AOT-compiled | JIT reaches higher throughput on hot paths |

Use a native image for a fixed app surface where startup and installer size matter most. Use the
JVM runtime for plugin hosts, developer tools, or anything that relies on runtime dynamism.

## Detecting the runtime at runtime

The [`aot-runtime`](/docs/performance/aot-cache) module reports the current AOT mode, and
[`core-runtime`](/docs/lifecycle/executable-type) reports the package format the process was
launched from.

```kotlin
import dev.nucleusframework.aot.runtime.AotRuntime
import dev.nucleusframework.aot.runtime.AotRuntimeMode
import dev.nucleusframework.core.runtime.ExecutableRuntime
import dev.nucleusframework.core.runtime.ExecutableType

when (AotRuntime.mode()) {
    AotRuntimeMode.TRAINING -> { /* AOT training pass — skip user-facing work */ }
    AotRuntimeMode.RUNTIME  -> { /* launched with a warmed AOT cache */ }
    AotRuntimeMode.OFF      -> { /* plain JVM, or a GraalVM native image */ }
}

// Which package format is this process running from?
val type: ExecutableType = ExecutableRuntime.type()
// EXE, MSI, NSIS, NSIS_WEB, PORTABLE, APPX, DMG, PKG, DEB, RPM,
// SNAP, FLATPAK, APPIMAGE, PACMAN, ZIP, TAR, SEVEN_Z, DEV

// Running inside a GraalVM native image?
val isNative: Boolean = ExecutableRuntime.isGraalVmNativeImage
```

`AotRuntime.mode()` returns `OFF` on a plain JVM and inside a native image, since the AOT cache
is a JVM-only mechanism. `AotRuntime.isRuntime()` and `AotRuntime.isTraining()` are shorthands
for the `RUNTIME` and `TRAINING` modes.

## What's next

- [GraalVM](/docs/performance/graalvm) — reachability metadata, build arguments, and CI integration.
- [AOT cache](/docs/performance/aot-cache) — training runs, lifecycle, and what gets cached.
- [Executable type](/docs/lifecycle/executable-type) — the full `ExecutableType` and `ExecutableRuntime` API.
- [Configuration](/docs/start/configuration) — the full Gradle DSL.

---

# Backends

URL: https://nucleusframework.dev/en/docs/concepts/backends

Nucleus draws every window through the Tao backend behind the DecoratedWindow API. The legacy AWT backend is deprecated.

Every Nucleus window is a Compose composable. The backend is the layer beneath it: it runs the
OS event loop, owns the native window handle, and presents Skia's GPU surface on screen. Nucleus
2.0 uses Tao as its backend behind the same `DecoratedWindow` API.

The legacy AWT backend (`decorated-window-jbr` / `decorated-window-jni`) is deprecated and will
be removed in a future Nucleus release. New and existing projects should move to Tao — see
[Migrating from JBR to Tao](/docs/tao/migration-from-jbr).

## The Tao backend

Tao is the Rust windowing layer that also underpins Tauri 2. Nucleus makes it the default for
new projects. Tao replaces the toolkit entirely, so the JVM never loads AWT.

The Tao backend adds:

- **Native Wayland.** No XWayland fallback, with fractional scaling and gestures.
- **Multi-touch and gestures.** Pinch, swipe, and rotate arrive as Compose pointer events that
  carry pressure, tilt, and source.
- **Pen and stylus.** Pressure-sensitive input from devices such as Wacom tablets, the Surface
  Pen, and Apple Pencil.
- **Per-monitor HiDPI.** Mixed-DPI setups are handled as you drag a window between displays.
- **`NativeView`.** Embed any platform-native view inside a Compose window — `NSView` on macOS, `HWND` on Windows, `GtkWidget` on Linux (SwiftUI, Win32/WinUI, WebView2, GTK, and anything else that exposes those handles).

See [Tao](/docs/tao) for the full surface.

## Select a backend

```kotlin
import dev.nucleusframework.application.NucleusBackend
import dev.nucleusframework.application.nucleusApplication

fun main() = nucleusApplication(backend = NucleusBackend.Tao) {
    DecoratedWindow(onCloseRequest = ::exitApplication, title = "MyApp") {
        // your Compose UI
    }
}
```

`NucleusBackend` has three values:

- `Auto` uses Tao when `decorated-window-tao` is on the classpath, otherwise the deprecated AWT
  backend. This is the default.
- `Tao` forces the Tao backend.
- `Awt` forces the deprecated AWT backend, using JBR or JNI depending on which is resolved.

## Reach the native window

The `DecoratedWindow` composable is identical across backends. When you need a backend-specific
call, reach the underlying handle through the window's escape hatches:

- `nucleusWindow.unsafe.taoWindow` returns the Tao-owned `TaoWindow`.
- `nucleusWindow.unsafe.awtWindow` returns the AWT `ComposeWindow` (deprecated backend only).

Each returns `null` on the other backend.

When `decorated-window-tao` is on the classpath, the Gradle plugin injects `-XstartOnFirstThread`
into Hot Reload's `JavaExec` tasks on macOS, because Tao runs the OS event loop on the process main
thread.

## What's next

- [Tao](/docs/tao) — the full backend surface: gestures, pen, Wayland, and `NativeView`.
- [Decorated Window](/docs/window) — the window you compose on top of a backend.
- [Migrating from JBR to Tao](/docs/tao/migration-from-jbr) — a checklist for existing apps.

---

# Modules

URL: https://nucleusframework.dev/en/docs/concepts/modules

How Nucleus splits its runtime into independently versioned Gradle modules and how to add the ones you need.

Nucleus is a set of independently versioned Gradle modules. One umbrella module brings the
runtime essentials, and every other capability is a separate module you add when you need it,
so your build carries only what your app uses.

## The umbrella module

Add `nucleus-application` to pull in the runtime essentials:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
}
```

This pulls in the runtime modules every app needs:

- `core-runtime` — platform detection, [native-library loading](/docs/performance/native-library-loader), the deep-link handler, the single-instance lock, and app metadata.
- `aot-runtime` — AOT cache mode detection.
- `graalvm-runtime` — the SVM substitutions and the initializer called from `nucleusApplication { }`.
- `darkmode-detector` — reactive OS theme, exposed as `api` so `isSystemInDarkMode()` needs no extra dependency.
- `spellcheck` — the [native spell engines](/docs/os/spell-check), also exposed as `api`.

It also brings the shared Compose window code in `decorated-window-core`, so you add only a
window backend on top. `core-runtime` and `graalvm-runtime` are `implementation` dependencies —
present at run time, not on your compile classpath. Everything else is opt-in.

## Window modules

Every app uses exactly one window backend, plus an optional style adapter.

| Module | Role |
|---|---|
| `decorated-window-core` | Shared Compose styling, themes, and icon sets. Pulled in by the others. |
| `decorated-window-tao` | Rust-native backend ([Tao](/docs/concepts/backends)). Default for new projects. |
| `decorated-window-jbr` / `decorated-window-jni` / `decorated-window-awt` | AWT backend. **Deprecated**, will be removed in a future Nucleus release. |
| `decorated-window-jewel` | Style adapter — IntelliJ Platform look. |
| `decorated-window-material2` | Style adapter — Material 2. |
| `decorated-window-material3` | Style adapter — Material 3. |

Full design systems (widgets + theme + optional window) live in **separate repositories**,
versioned independently:

| Design system | Window artifact | Repo |
|---------------|-----------------|------|
| macOS 26 | `dev.nucleusframework:compose-macos-ui` | [compose-macos-26-ui](https://github.com/NucleusFramework/compose-macos-26-ui) |
| Fluent | `dev.nucleusframework.composefluent:decorated-window-fluent` | [compose-fluent-ui](https://github.com/NucleusFramework/compose-fluent-ui) |
| Yaru | `dev.nucleusframework.yarucompose:yaru-decorated-window` | [yaru-compose-ui](https://github.com/NucleusFramework/yaru-compose-ui) |

See [Native design systems](/docs/window/toolkits).

Pick exactly one backend (`-tao`, or one of the deprecated AWT modules). Style adapters and
external design systems are optional.

## OS integration modules

| Capability | Module |
|---|---|
| Notifications (cross-platform DSL) | `notification-common` |
| Notifications (macOS) | `notification-macos` |
| Notifications (Windows Toast) | `notification-windows` |
| Notifications (Linux DBus) | `notification-linux` |
| Dock menu (macOS) | `launcher-macos` |
| Jump lists, taskbar buttons (Windows) | `launcher-windows` |
| Unity quicklist (Linux) | `launcher-linux` |
| Native menu bar (macOS) | `menu-macos` |
| Taskbar progress | `taskbar-progress`, [`taskbar-progress-tao`](/docs/tao/taskbar-progress) |
| Dark-mode detection | `darkmode-detector` |
| System accent color | `system-color` |
| Global hotkeys | `global-hotkey` |
| Media controls (Now Playing / SMTC / MPRIS) | `media-control` |
| System info (CPU, RAM, GPU, batteries) | `system-info` |
| Energy / efficiency mode | `energy-manager` |
| Auto-launch at login | `autolaunch` |
| Scheduler (cron / periodic / boot) | `scheduler` |
| Scheduler testing (virtual clock) | [`scheduler-testing`](/docs/lifecycle/scheduler-testing) |
| File-system watcher | [`fs-watcher`](/docs/lifecycle/fs-watcher) |
| macOS service management | `service-management-macos` |
| Linux HiDPI scale detection | `linux-hidpi` |
| SF Symbols catalogue | [`sf-symbols`](/docs/os/sf-symbols) |
| FreeDesktop icon names | `freedesktop-icons` |

## Performance and networking modules

| Capability | Module |
|---|---|
| Native trust manager (OS keychain CAs) | `native-ssl` |
| `java.net.http.HttpClient` with native trust | `native-http` |
| OkHttp with native trust | [`native-http-okhttp`](/docs/performance/native-http) |
| Ktor with native trust | [`native-http-ktor`](/docs/performance/native-http) |
| Auto-update | `updater-runtime` |

## Add a module

Declare the umbrella, one window backend, and any capability modules you need:

```kotlin title="build.gradle.kts"
val nucleusVersion = "<version>"

dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:$nucleusVersion")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:$nucleusVersion")

    // Add the capabilities you need
    implementation("dev.nucleusframework:nucleus.notification-common:$nucleusVersion")
    implementation("dev.nucleusframework:nucleus.global-hotkey:$nucleusVersion")
    implementation("dev.nucleusframework:nucleus.system-info:$nucleusVersion")
}
```

Pin every `nucleus.*` artifact to the same version. The modules release together.

## How modules compose

Most modules depend on `core-runtime` for platform detection and app metadata. A few
standalone catalogues, such as `sf-symbols` and `freedesktop-icons`, carry no runtime
dependency. Some modules depend on each other: `notification-common` orchestrates the per-OS
notification modules, and `taskbar-progress-tao` depends on `nucleus-application` to add
extension functions on `NucleusWindow`.

The Gradle plugin injects `nucleus-app.properties` into the classpath at build time, so any
module reads your app's identity through `NucleusApp.appId`, `NucleusApp.version`,
`NucleusApp.aumid`, and the other properties without extra wiring.

When the GraalVM build runs, each module's reachability metadata is bundled in automatically,
so there is no reflection config to maintain by hand.

## What's next

- [Architecture](/docs/concepts/architecture) — how the layers fit together.
- [OS integration](/docs/os) — concrete recipes per capability.
- [Reference: Gradle DSL](/docs/reference/gradle-dsl) — full coordinates and version table.

---

# The Tao backend

URL: https://nucleusframework.dev/en/docs/tao

Tao is a Rust-native window backend that runs Compose Desktop without AWT and adds native Wayland, multi-touch, and pen input.

Tao is the Rust windowing crate that also underpins Tauri 2. Nucleus wraps it as a window
backend: Compose Desktop renders into a native OS window, so there is no Swing event-dispatch
thread and no XWayland fallback. Tao is the backend for new Nucleus apps. The legacy AWT
backend is legacy and maintenance-only — see
[migration from JBR](/docs/tao/migration-from-jbr).

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-core:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

The Nucleus Gradle plugin detects `decorated-window-tao` on the classpath and selects the
Tao backend at runtime. To select it explicitly, pass `NucleusBackend.Tao`:

```kotlin
nucleusApplication(backend = NucleusBackend.Tao) {
    // …
}
```

## Create a window

```kotlin
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.NucleusBackend
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.TitleBar
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.rememberWindowState

fun main() = nucleusApplication(backend = NucleusBackend.Tao) {
    DecoratedWindow(
        onCloseRequest = ::exitApplication,
        state = rememberWindowState(size = DpSize(1024.dp, 720.dp)),
        title = "Hello Tao",
    ) {
        TitleBar { state -> /* custom title bar */ }
        MyContent()
    }
}
```

`DecoratedWindow` and `TitleBar` are the same Composables across backends, so your UI code
does not change when you switch backends. For full-window layouts and custom chrome on Tao,
use [`WindowScaffold`](/docs/tao/window-scaffold). To composite decoder or engine frames as
GPU textures inside Compose (z-order, clipping, no CPU copy), use
[`TextureView`](/docs/tao/texture-view). For in-process renderers that can share the scene's
GPU device, use [`TaoGpuRenderContext`](/docs/tao/gpu-render-context).

## How it works

Tao opens a native OS window directly: an `NSWindow` on macOS, an `HWND` on Windows, and a
`wl_surface` (or an X11 window) on Linux. Compose renders into that surface through Skiko —
Metal on macOS, ANGLE GLES over Direct3D 11 on Windows, EGL/GLES on Linux. On Linux the EGL
attach asks for a GL 3.3 compatibility context, then a 3.3 core context, then Mesa llvmpipe
(`LIBGL_ALWAYS_SOFTWARE=1`) so GPUs that only offer core 3.3 still hardware-accelerate, and
machines with neither still open a window. Nothing routes through Swing's event-dispatch
thread.

Compose Desktop's `SwingPanel` does not work on the Tao backend and crashes the app at
runtime. It requires an AWT/Swing window hierarchy that Tao never creates. Embed native
content with [`NativeView`](/docs/tao/native-views) instead, or keep the AWT backend for
windows that still need Swing interop. For passive GPU frames (video, cameras, engines), use
[`TextureView`](/docs/tao/texture-view) rather than a native widget.

The OS event loop runs on the process main thread, so the macOS launcher needs
`-XstartOnFirstThread`. The Nucleus Gradle plugin adds it automatically for `run`, packaged
distributions, and Compose Hot Reload. GraalVM native-image builds start on the main thread
by default.

The `nucleusApplication { }` entry point hides the backend choice from UI code. On the Tao
backend the same window exposes an imperative `TaoWindow` handle underneath, which you reach
through `nucleusWindow.unsafe.taoWindow` when you need to call into the native crate directly.

## API reference

The Tao-specific API lives in `dev.nucleusframework.window.tao`:

- `taoApplication { }` — direct entry point. Prefer `nucleusApplication` for backend portability.
- `TaoWindow` — imperative window handle. Reach it through `LocalTaoWindow` or
  `nucleusWindow.unsafe.taoWindow`.
- `NativeView` — embed any native view (`NSView` / `HWND` / `GtkWidget`) in Compose.
- `TextureView` / `rememberTaoGpuRenderContext` — external GPU frames and in-process GPU
  renderers on the scene's device. See [TextureView](/docs/tao/texture-view) and
  [GPU render context](/docs/tao/gpu-render-context).
- `MacOSStyle` — window chrome on macOS: `Auto` (modern Tahoe chrome on macOS 26+, classic
  chrome otherwise), `Classic` (the default), or `Modern`.
- `TaoCursorIcon`, `TaoTrackpadGesture`, `TaoTrackpadPhase`, `TaoMouseButton`, `TaoEventCode` —
  input constants.
- `TaoDeepLinkBridge.setSink { uri -> … }` — deep link delivery.
- `WindowExceptionHandlerFactory` / `LocalWindowExceptionHandlerFactory` — catch scene
  failures, or let the default factory take the native fatal dialog. See
  [Handle uncaught exceptions](/docs/tao/decorated-window#handle-uncaught-exceptions).

`decorated-window-jbr` and `decorated-window-jni` are legacy and maintenance-only: they still
ship and still work, but new features land on Tao only. Keep one on the classpath and select the
backend with
`NucleusBackend.Awt` only if you still need Swing / AWT interop during migration. See
[migration from JBR](/docs/tao/migration-from-jbr).

## What's next

- [The decorated window](/docs/tao/decorated-window) — the `DecoratedWindow` and `TitleBar` Composables on Tao.
- [Window scaffold and chrome](/docs/tao/window-scaffold) — full-window layouts, materials, drag areas.
- [Multi-touch and gestures](/docs/tao/multi-touch) — trackpad and touch events from `TaoWindow`.
- [Wayland](/docs/tao/wayland) — native Wayland behavior and detection.
- [Quickstart](/docs/start/quickstart) — build and run your first Nucleus app.

---

# DecoratedWindow on Tao

URL: https://nucleusframework.dev/en/docs/tao/decorated-window

Open a Compose Desktop window on the Tao backend with a custom title bar slot and native window controls, without AWT.

`DecoratedWindow` is the same Composable on every Nucleus backend. On Tao it opens a
native OS window, mounts a Skiko rendering surface, and gives you a `TitleBar` slot you
fill with Compose content — including per-OS control-button layouts. This page covers the
Tao-specific behavior of `DecoratedWindow` and the members exposed inside its content lambda.

## Add the dependency

```kotlin title="build.gradle.kts"
plugins {
    id("dev.nucleusframework")
}

dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

`nucleus-application` provides the unified entry point; `decorated-window-tao` provides
the Tao backend. With both on the classpath, `NucleusBackend.Tao` is available.

## Open a window

Start the runtime with `nucleusApplication`, then call `DecoratedWindow` and add a
`TitleBar`:

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.rememberWindowState
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.NucleusBackend
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.NucleusDecoratedWindowTheme
import dev.nucleusframework.window.TitleBar
import dev.nucleusframework.window.macOSLargeCornerRadius
import dev.nucleusframework.window.styling.TitleBarColors
import dev.nucleusframework.window.styling.TitleBarMetrics
import dev.nucleusframework.window.styling.TitleBarStyle

fun main() = nucleusApplication(backend = NucleusBackend.Tao) {
    val titleBarStyle = TitleBarStyle(
        colors = TitleBarColors(
            background = Color(0xFF1A1D24),
            inactiveBackground = Color(0xFF15181D),
            content = Color(0xFFE6E6E6),
            border = Color.Transparent,
        ),
        metrics = TitleBarMetrics(height = 36.dp),
    )

    NucleusDecoratedWindowTheme(isDark = true, titleBarStyle = titleBarStyle) {
        DecoratedWindow(
            onCloseRequest = ::exitApplication,
            state = rememberWindowState(size = DpSize(1024.dp, 720.dp)),
            title = "Tao Demo",
            minimumSize = DpSize(640.dp, 480.dp),
        ) {
            TitleBar(modifier = Modifier.macOSLargeCornerRadius()) { state ->
                Text("Tao Demo", Modifier.align(Alignment.CenterHorizontally))
            }
            Box(Modifier.fillMaxSize()) { /* app content */ }
        }
    }
}
```

The `TitleBar` slot handles title-bar press-and-drag internally, so the window moves when
you drag empty title-bar space. You don't wire up a drag modifier yourself.

For full-window layouts, custom design-system chrome, macOS glass sidebars, or Windows 11
Mica/Acrylic, use [`WindowScaffold`](/docs/tao/window-scaffold) instead of (or around) the
stock `TitleBar`. Existing `TitleBar` call sites stay valid.

## Open a window from composition

`DecoratedWindow` / `DecoratedDialog` are extensions on `NucleusApplicationScope`, a
receiver that only exists at the top of `main()`. Secondary windows usually open from a
navigation destination or a row action, where that receiver is gone.

From 2.3, `nucleusApplication` provides `LocalNucleusApplicationScope` on **both** backends
(and bridges parent locals into each Tao scene). Receiver-less overloads read it:

```kotlin
import androidx.compose.runtime.Composable
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.LocalNucleusApplicationScope

@Composable
fun EditorWindow(onClose: () -> Unit) {
    // No application receiver — reads LocalNucleusApplicationScope
    DecoratedWindow(onCloseRequest = onClose, title = "Editor") {
        EditorContent()
    }
}

@Composable
fun MaterialEditorWindow(onClose: () -> Unit) {
    // Toolkit wrappers still need the scope as a receiver:
    with(LocalNucleusApplicationScope.current) {
        MaterialDecoratedWindow(onCloseRequest = onClose) {
            EditorContent()
        }
    }
}
```

Outside `nucleusApplication { }`, reading the local throws. Prefer the receiver-less
`DecoratedWindow` / `DecoratedDialog` when you only need the core APIs; use
`LocalNucleusApplicationScope.current` explicitly for toolkit wrappers
(`MaterialDecoratedWindow`, Jewel, Fluent, …) that remain scope extensions.

From 2.3.2, each secondary Tao scene also re-provides `LocalTaoWindow` and
`LocalTitleBarInfo` for **that** window after parent locals are bridged in. Title-bar
drag, double-click maximize, and system controls therefore target the child window, not
the parent that opened it. `BasicTitleBar` binds drag with
`Modifier.windowDragArea(window)` so it stays correct even if a parent
`LocalTaoWindow` is still visible in the composition tree.

### Hosted windows

Libraries and navigation layers should not hard-code Compose Desktop's AWT
`androidx.compose.ui.window.Window` / `Dialog` (unsupported under Tao) or a specific
design-system window type. From 2.3.2, `nucleusApplication` also provides
`LocalNucleusWindowHost` and `LocalNucleusDialogHost`. The defaults open a plain
`DecoratedWindow` / `DecoratedDialog`, and take the Tao knobs `popupFor`, `nativePopupLayers`,
`nativeContextMenu`, `hiddenFromDock`, and `alwaysOnBottom`. The remaining overlay flags —
`transparent`, `clickThrough`, `visibleOnAllWorkspaces`, and `forceX11` — are only on
`DecoratedWindow` itself. Call sites use `HostedWindow` / `HostedDialog`:

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.rememberWindowState
import dev.nucleusframework.application.HostedWindow
import dev.nucleusframework.application.LocalNucleusWindowHost
import dev.nucleusframework.window.TitleBar

@Composable
fun DeepSearchDestination(onBack: () -> Unit) {
    HostedWindow(
        onCloseRequest = onBack,
        state = rememberWindowState(size = DpSize(1200.dp, 800.dp)),
        title = "Deep search",
    ) {
        TitleBar { /* … */ }
        DeepSearchContent()
    }
}

// App chrome: one override, every HostedWindow call site picks it up
@Composable
fun AppRoot() {
    CompositionLocalProvider(LocalNucleusWindowHost provides myMaterialHost) {
        NavigationGraph()
    }
}
```

Override the host when the app wraps every secondary window in Material, Jewel, or custom
chrome without teaching every library or navigation destination about that wrapper. Direct
`DecoratedWindow` / `DecoratedDialog` calls remain valid when you want the concrete type.

## How it works

`nucleusApplication { }` resolves the backend and exposes `DecoratedWindow` on
`NucleusApplicationScope`. On Tao, that overload delegates to
`dev.nucleusframework.window.tao.ApplicationScope.DecoratedWindow`, which opens a
`TaoWindow` and mounts a `ComposeScene` against the native surface.

Inside the content lambda you get a `NucleusDecoratedWindowScope`. Its
`nucleusWindow` property returns the backend-agnostic `NucleusWindow` handle: focus
state, minimized / maximized / fullscreen flows, icon, and minimum size. Reach the raw
`TaoWindow` through `nucleusWindow.unsafe.taoWindow` when you need Tao-only behavior.

Title-bar styling is shared with the AWT backends. `TitleBarStyle`, `TitleBarColors`,
and `TitleBarMetrics` live in `decorated-window-core`, and `NucleusDecoratedWindowTheme`
provides them through composition locals. The same theme works whether the dependency is
`-tao`, `-jbr`, or `-jni`.

## API reference

### DecoratedWindow parameters

| Parameter | Type | Notes |
|---|---|---|
| `onCloseRequest` | `() -> Unit` | Fired by the OS close affordance. |
| `state` | `WindowState` | Position, size, placement. An axis set to `Dp.Unspecified` wraps to content after the first composition. |
| `visible` | `Boolean` | Default `true`. |
| `title` | `String` | OS-level window title. |
| `icon` | `Painter?` | Taskbar / dock icon. |
| `resizable` | `Boolean` | Default `true`. |
| `enabled` / `focusable` / `alwaysOnTop` | `Boolean` | Standard window flags. |
| `undecorated` | `Boolean` | Borderless window with no controls. Honored by Tao; ignored by AWT. |
| `isDialog` | `Boolean` | Default `false`. Open as a dialog-class window. |
| `transparent` | `Boolean` | Default `false`. Per-pixel window transparency. Creation-time only. See [Overlay windows](/docs/tao/overlay-windows#build-a-click-through-watermark). |
| `clickThrough` | `Boolean` | Default `false`. Pointer events pass through to whatever is behind. Reactive. |
| `alwaysOnBottom` | `Boolean` | Default `false`. Keep the window below normal windows. Clears `alwaysOnTop`. Reactive. |
| `visibleOnAllWorkspaces` | `Boolean` | Default `false`. Show on every workspace or Space. Reactive. |
| `forceX11` | `Boolean` | Default `false`. Linux only: take an X11 (XWayland) surface for this window alone. Creation-time only. |
| `nativeContextMenu` | `Boolean` | Default `false`. Replace Compose context menus with the platform's. On the backend-agnostic `DecoratedWindow` and `HostedWindow`, not the Tao-scope overload. See [Context menus](/docs/window/context-menu#turn-on-the-native-menu). |
| `macOSStyle` | `MacOSStyle` | Default `MacOSStyle.Classic`. Title-bar treatment on macOS. |
| `compositionLocalContext` | `CompositionLocalContext?` | Composition locals to carry into the new window's composition. |
| `popupFor` | `NucleusWindow?` | Linux/Tao only: attach this window as a popup overlay of another. On native Wayland, positions are in the parent **content** area (hidden-titlebar CSD origin is applied inside `setOuterPosition`). |
| `nativePopupLayers` | `Boolean` | Default `false`. Materialise Compose `Popup` layers as native transparent windows (NSPanel / WS_POPUP HWND). Tao only. |
| `hiddenFromDock` | `Boolean` | Default `false`. Hide this window from the OS taskbar/Dock. Honored by Tao; ignored by AWT. |
| `minimumSize` | `DpSize?` | Enforced after the first layout pass. |
| `onPreviewKeyEvent` / `onKeyEvent` | `(KeyEvent) -> Boolean` | Return `true` to consume the event. |
| `content` | `@Composable NucleusDecoratedWindowScope.() -> Unit` | Title bar slot plus your UI. |

The table above lists the Tao `ApplicationScope.DecoratedWindow` overload. The
backend-agnostic `NucleusApplicationScope.DecoratedWindow` in `nucleus-application` takes the
same window flags — including `transparent`, `clickThrough`, `alwaysOnBottom`,
`visibleOnAllWorkspaces`, and `forceX11` — and adds
[`nativeContextMenu`](/docs/window/context-menu#turn-on-the-native-menu). It does not expose
`macOSStyle`, `isDialog`, or `compositionLocalContext`.

Flags that only the Tao backend can honor are accepted and ignored on AWT, so the same source
compiles and runs on either backend.

### Hiding from the taskbar/Dock

`hiddenFromDock` keeps the window visible and focusable while removing it from the OS-level
window list — useful for HUDs, overlays, and background utility windows that should not clutter
the taskbar or app switcher:

```kotlin
DecoratedWindow(
    onCloseRequest = ::exitApplication,
    hiddenFromDock = true,
) {
    // ...
}
```

The mechanism differs per platform:

- **macOS** — switches the shared `NSApplication` to the accessory activation policy (no Dock
  icon, no menu bar). This is app-wide, not per-window: the last window to apply the flag wins.
- **Windows** — sets `WS_EX_TOOLWINDOW` on the window, which drops its taskbar button and its
  Alt+Tab entry. Per-window.
- **Linux** — sets the GTK skip-taskbar/skip-pager hints (`_NET_WM_STATE_SKIP_TASKBAR`).
  Per-window, and only effective on X11 or XWayland.

On native Wayland, `hiddenFromDock` has no effect — Wayland has no client-side skip-taskbar
protocol (`xdg-shell`, `gtk_shell1`, and the staging layer-shell extensions all lack it, and Mutter
rejects `wlr-layer-shell`). Nucleus logs a warning rather than failing silently. Force XWayland with
`NUCLEUS_TAO_LINUX_RENDERER=x11` if you need the window actually hidden on a Wayland session — see
[Native Wayland](/docs/tao/wayland).

For a menu-bar or tray app that should stay out of the Dock until it opens a real window, pass
`dockIconFollowsWindows = true` to `nucleusApplication` instead of setting `LSUIElement` in
`Info.plist`. The app starts as an accessory; a Dock tile appears only while at least one
`DecoratedWindow` with `hiddenFromDock = false` is visible. Standalone tray popups never count.
The flag is ignored off macOS and on the AWT backend. See
[Hide the Dock icon on macOS](/docs/os/tray-app#hide-the-dock-icon-on-macos).

### Scope members

```kotlin
interface NucleusDecoratedWindowScope : DecoratedWindowScope {
    val nucleusWindow: NucleusWindow
}

interface NucleusWindow {
    val isFocused: Boolean
    val isMinimized: Boolean
    val isMaximized: Boolean
    val isFullscreen: Boolean
    val focusFlow: StateFlow<Boolean>
    fun setMaximized(maximized: Boolean)
    fun setFullscreen(fullscreen: Boolean)
    fun setMinimumSize(size: DpSize?)
    fun setIcon(painter: Painter?)
    fun close()
    val unsafe: NucleusWindowUnsafe   // .taoWindow, .taoHandle
}
```

### Title bar modifiers

- `Modifier.macOSLargeCornerRadius()` — opt into macOS 26+ rounded corners.
- `Modifier.newFullscreenControls()` — relayout the title bar buttons for fullscreen.

### Scaffold and chrome (2.2+)

Prefer these when the stock `TitleBar` layout is too rigid:

- `WindowScaffold` / `TitleBarPlacement` — full-window and overlay chrome layouts.
- `Modifier.windowDragArea` / `noWindowDrag` — declare (or exclude) native move regions.
- `WindowControls` — system min/max/close outside `TitleBar`.
- `WindowBackground` / `WindowAppearance` — clear colour and native light/dark from inside the tree.
- `Modifier.windowGlassRegion` (macOS) / `WindowsBackdrop` (Windows 11) — platform materials.

Full reference: [Window scaffold and chrome](/docs/tao/window-scaffold).

`TitleBar` is a single extension on `DecoratedWindowScope`. The `nucleusApplication` scope
(`NucleusDecoratedWindowScope`) and the Tao-native `taoApplication` scope
(`TaoDecoratedWindowScope`) both implement it, so the same `TitleBar` call works whichever
entry point you start from. The same holds for `WindowScaffold` and the chrome primitives.

## Text input

IME composition (Japanese, Chinese, Korean, and similar) is forwarded into Compose as preedit
on macOS, Windows, and Linux. Keys the IME already consumed — conversion Enter, candidate arrows,
Backspace on the preedit — are dropped so they do not also insert a newline, move the caret, or
delete committed text. The candidate window follows the caret on all three platforms.

Linux resolves the platform input method the way GTK's own text widgets do: ibus or fcitx5
through the GTK immodule on X11, and the text-input-v3 client on Wayland. Linux preedit requires
2.5.6 or later — earlier releases pinned GTK's built-in fallback context, which never reaches a
system input method.

On macOS, whether a held letter repeats or opens the accent picker is left entirely to the
operating system: Nucleus neither reads nor writes `ApplePressAndHoldEnabled`. A pick is applied
from the `replacementRange` AppKit sends with it, so it replaces the base letter without touching
the text around it (2.5.6; earlier releases forced the user default and inferred the picker state).

## Handle uncaught exceptions

From 2.5.8, an exception that escapes a Tao event dispatch no longer vanishes at the JNI
boundary. The default path logs the stack at `SEVERE`, shows a blocking native error dialog,
exits the Tao loop, and rethrows so `nucleusApplication` / `taoApplication` terminate with
exit code 1. The dialog is shown after the loop has exited — a modal pump inside a tao
callback deadlocks the main thread.

From 2.5.9 the dialog carries the full stack in a bounded scrollable monospace view with a
Copy button: an `NSAlert` run by an out-of-process `osascript` child on macOS (compact
`CFUserNotification` fallback), an in-memory `DLGTEMPLATE` on a fresh thread on Windows
(`MessageBoxW` fallback), and a `GtkMessageDialog` on Linux.

Skip the dialog in unattended runs (CI, AOT training) with
`-Dnucleus.tao.fatalErrorDialog=false`. The `SEVERE` log remains.

To keep a window alive after a recoverable failure, provide a
`LocalWindowExceptionHandlerFactory`. It is the Tao mirror of Compose Desktop's AWT factory
and is `@ExperimentalComposeUiApi`. Handlers run on the thread the failure occurred on, and
cover layout, draw, input, IME, accessibility, and `nativePopupLayers` popups of that window:

```kotlin
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.ui.ExperimentalComposeUiApi
import androidx.compose.ui.window.WindowExceptionHandler
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.NucleusBackend
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.tao.LocalWindowExceptionHandlerFactory
import dev.nucleusframework.window.tao.WindowExceptionHandlerFactory

@OptIn(ExperimentalComposeUiApi::class)
fun main() = nucleusApplication(backend = NucleusBackend.Tao) {
    CompositionLocalProvider(
        LocalWindowExceptionHandlerFactory provides WindowExceptionHandlerFactory { _ ->
            WindowExceptionHandler { throwable ->
                // Return normally to drop the frame and keep the window alive.
                // Rethrow to take the fatal dialog and exit.
            }
        },
    ) {
        DecoratedWindow(onCloseRequest = ::exitApplication, title = "Demo") {
            MyContent()
        }
    }
}
```

Returning normally is a real resume for layout, draw, input, IME, and accessibility: the
offending frame is dropped and a new one is requested. A failure *inside composition* is
not recoverable — Compose stops the recomposition loop before the backend sees the exception,
and that loop cannot be restarted. Swallowing one logs at `SEVERE` instead of leaving a
window that silently paints its last frame; close and recreate the window, or rethrow to
take the fatal path. `DefaultWindowExceptionHandlerFactory` always rethrows.

## Notes

- macOS requires `-XstartOnFirstThread`. The Nucleus Gradle plugin adds it for you.
- For multi-window apps, call `DecoratedWindow` several times from the same
  `nucleusApplication` block. Each window gets its own `NucleusWindow`.
- Linux CSD windows draw a native GTK drop shadow (hidden-titlebar pattern) that tracks the
  window during interactive moves.
- Windowed Windows CSD (no Mica/Acrylic) clears the DWM border fill so the Compose frame
  stroke is visible, and draws the Win11 8px rounded contour through DWM so corners are
  not clipped. Backdrop windows keep the system frame.
- `NucleusApplicationScope` implements Compose's `ApplicationScope`, so libraries scoped to the
  plain Compose receiver (for example system-tray composables) resolve inside
  `nucleusApplication { }`.
- From 2.5.14, `DecoratedWindow` / `DecoratedDialog` (and the hosted and Tao variants) are
  `@ComposableOpenTarget(-1)` with a `@UiComposable` content lambda. A non-UI-targeted
  composable called in the `nucleusApplication` block no longer reclassifies the window
  content, so `@UiComposable` calls inside the window stay valid under `-Werror`.

## What's next

- [Window scaffold and chrome](/docs/tao/window-scaffold) — full-window layouts and materials.
- [The Tao backend](/docs/tao) — what the no-AWT backend covers.
- [DecoratedWindow across backends](/docs/window) — the shared window API.
- [Multi-touch and trackpad gestures](/docs/tao/multi-touch) — read Tao input events.
- [Backends](/docs/concepts/backends) — how Nucleus picks Tao or AWT.

---

# Window scaffold and chrome

URL: https://nucleusframework.dev/en/docs/tao/window-scaffold

Build full-window layouts and custom title bars on Tao with WindowScaffold, drag areas, WindowControls, and platform materials.

`DecoratedWindow` + `TitleBar` always laid the main content **below** a fixed chrome band.
That blocked full-window layouts: no list under the toolbar, no glass sidebar that meets the
traffic lights, no design-system headerbar that still drags the window. From 2.2, `WindowScaffold`
and a small set of chrome primitives solve that without throwing away native caption zones,
button order, or drag behaviour.

## Add the dependency

The scaffold APIs ship in `decorated-window-tao` (same artifact as the Tao backend):

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

Existing `DecoratedWindow` + `TitleBar` call sites keep working. The scaffold is additive.

## Quickstart

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.TitleBarPlacement
import dev.nucleusframework.window.WindowBackground
import dev.nucleusframework.window.WindowControls
import dev.nucleusframework.window.WindowScaffold
import dev.nucleusframework.window.windowDragArea

fun main() = nucleusApplication {
    DecoratedWindow(onCloseRequest = ::exitApplication, title = "Scaffold demo") {
        MaterialTheme {
            WindowBackground(MaterialTheme.colorScheme.background)
            WindowScaffold(
                titleBar = {
                    Box(
                        Modifier
                            .fillMaxWidth()
                            .height(48.dp)
                            .windowDragArea()
                            .padding(horizontal = 12.dp),
                    ) {
                        Text("My App", Modifier.align(Alignment.CenterStart))
                        WindowControls(Modifier.align(Alignment.CenterEnd))
                    }
                },
                titleBarPlacement = TitleBarPlacement.Overlay(),
            ) { contentPadding ->
                Box(Modifier.fillMaxSize().padding(contentPadding)) {
                    /* app content — scrolls under the overlay bar when padded */
                }
            }
        }
    }
}
```

## How it works

`WindowScaffold` is the sole intended child of a `DecoratedWindow` content lambda. It:

1. **Measures** the `titleBar` slot and publishes the height to the native layer (macOS traffic-light
   centring, Windows caption zone / touch drag) — replacing the hard-coded
   `TitleBarStyle.metrics.height` contract.
2. **Provides** `LocalWindowChromeInsets` so chrome and content avoid platform-reserved control
   zones (traffic lights, KDE edge padding).
3. In **`Overlay`** mode, lets content fill the full window height behind the bar and hands the
   measured bar height back as top `PaddingValues`.

Nothing is implicitly draggable at the scaffold level. Custom chrome must declare its move surface
with `windowDragArea` — the same path the stock `TitleBar` already uses.

### Title bar placement

| Placement | Behaviour |
|---|---|
| `TitleBarPlacement.Docked` | Classic layout: the bar takes height, content fills the rest. Default. |
| `TitleBarPlacement.Overlay(autoHideInFullscreen = true, passThroughToContent = false)` | Content is `fillMaxSize`; the bar floats on top. Content receives the bar height as top padding. |

`controlButtonsDirection` sets the order and side of the system buttons for the whole scaffold —
`ControlButtonsDirection.Auto` follows the platform, `Rtl` moves them to the leading edge and
flips the macOS traffic lights.

`autoHideInFullscreen` drops the bar while fullscreen so content is fully immersive.
`passThroughToContent` hit-tests presses against content **under** the bar as well, so controls
merged into the title-bar band (a collapsed nav pane's hamburger, a tab strip) stay interactive.
Off by default: with full-bleed content scrolling behind opaque chrome, a click on the bar would
otherwise activate whatever sits underneath.

## Chrome primitives

### Drag areas

```kotlin
Modifier = Modifier
    .windowDragArea(
        enabled = true, // default; false makes the whole modifier a no-op
        doubleClickAction = WindowDoubleClickAction.ToggleMaximize,
    )
```

An unconsumed primary press followed by a move starts the native window move. Interactive children
(buttons, text fields) opt out by consuming the press. Gesture detectors that only claim the pointer
once it moves — scrollbars, sliders, resize handles — leave the press unconsumed, so wrap them:

```kotlin
Scrollbar(Modifier.noWindowDrag())
```

Prefer `Modifier.windowDragArea(window = taoWindow)` when chrome already holds a `TaoWindow`
(title bars, secondary scenes). The no-arg form reads `LocalTaoWindow`; the explicit overload
stays correct if parent-window CompositionLocals are bridged into a child scene (stock title
bars do this from 2.3.2).

`WindowDoubleClickAction.None` disables the double-click → maximize gesture on that area.

### Window controls

`WindowControls` draws the system min / maximize-restore / close strip **outside** `TitleBar`, so a
design system can place it inside its own toolbar:

```kotlin
WindowControls(
    modifier = Modifier.align(Alignment.CenterEnd),
    direction = ControlButtonsDirection.Auto,   // default
    renderer = WindowControlsRenderer.Platform, // default
)
```

Nucleus owns the semantics (maximize ↔ restore; fullscreen swap; close → `onCloseRequest`). The
renderer only draws. `direction` decides the button order and side: `Auto` follows the platform —
including the desktop's own `button-layout` on Linux — and `Rtl` moves them to the leading edge,
which on macOS also flips the AppKit traffic lights. On macOS,
`WindowControlsRenderer.Platform` draws nothing and reserves the traffic-light footprint instead —
pad with **either** `WindowControls` **or** `LocalWindowChromeInsets.controlsInsets`, never both.
In native fullscreen the replacement traffic lights cannot miniaturize the window, so the
minimize button is disabled and no longer looks clickable; close and zoom stay on the same
hover path.

Supply a custom `WindowControlsRenderer` to draw buttons in the design system's own style.

### Chrome insets

```kotlin
val insets = LocalWindowChromeInsets.current
Row(Modifier.padding(insets.controlsInsets)) { /* title bar content */ }
```

`controlsInsets` is the horizontal safe area for system controls; `titleBarHeight` is the measured
slot height (`0.dp` when the bar is hidden).

## Platform materials and appearance

### Window background

Tao gives every window its own `ComposeScene`, so the theme often lives **inside** the window.
`WindowBackground` sets the clear colour from inside that tree — the colour that shows during live
resize, around floating panels, and wherever Compose paints nothing:

```kotlin
WindowBackground(MaterialTheme.colorScheme.background)
```

### Window appearance

Force native surfaces (glass, traffic lights, menus, Windows chrome glyphs) to follow the **app**
theme instead of the OS setting:

```kotlin
WindowAppearance(
    if (dark) WindowAppearanceMode.Dark else WindowAppearanceMode.Light,
)
```

A no-op on Linux. Reverts to system-derived appearance when the composable leaves composition.

### macOS glass regions

`Modifier.windowGlassRegion` hosts a real `NSSplitViewController` pane under the Compose surface so
AppKit applies the wallpaper-tinted System Settings material — desktop shows through, intervening
windows never do:

```kotlin
Box(
    Modifier
        .width(248.dp)
        .fillMaxHeight()
        .windowGlassRegion(WindowGlassRegionKind.Sidebar, cornerRadius = 12.dp),
) { /* sidebar content; leave unpainted areas for the material */ }
```

Kinds: `Sidebar`, `ContentList`, `Inspector` (macOS 14+). The component must not paint a full opaque
background. macOS only; a no-op elsewhere. There is no full-window macOS glass — that is not an
AppKit pattern.

### Windows 11 backdrops

```kotlin
WindowsBackdrop(
    style = WindowsBackdropStyle.Mica,       // or Acrylic, MicaAlt
    tint = Color.Unspecified,                // app tint over the material
    tier = WindowsBackdropTier.Auto,         // Modern / LegacyMica / Windows10Acrylic
)
```

DWM composites the material behind the window wherever the app paints nothing. Leave panels or
margins unpainted to reveal it; a full-bleed opaque background covers it. `WindowBackground` is
suspended while a backdrop is active and restored when it leaves composition.

Degrades on older Windows: pre-22H2 Windows 11 maps Mica styles to the older single-material
attribute; Windows 10 falls back to acrylic when available. Silent no-op on macOS and Linux.

## Transparent and borderless overlays

Full-window transparency is a creation-time flag, implemented by the Tao backend and accepted and
ignored on AWT. It is available on the backend-agnostic `DecoratedWindow`, on the Tao-scope
overload, and on the Material and Jewel window wrappers:

```kotlin
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.nucleusApplication

fun main() = nucleusApplication {
    DecoratedWindow(
        onCloseRequest = ::exitApplication,
        undecorated = true,   // no frame, no DWM shadow
        transparent = true,   // empty client composites the desktop
    ) {
        Box(Modifier.size(48.dp).background(Color(0xFFFF00AA)))
    }
}
```

Hosts clear to alpha-0; opaque `WindowBackground` / title-bar clears are coerced to transparent so
empty regions stay see-through. Semi-transparent tints still apply.

For click-through, always-on-bottom, and all-workspaces overlays built on this flag, see
[Overlay windows](/docs/tao/overlay-windows).

## Notes

- Intended as the sole child of the window content lambda; it fills the remaining window height.
- Stock `TitleBar` still works for apps that do not need full-window layout — no migration required.
- `passThroughToContent` is opt-in for a reason: enable it only when interactive content is meant to
  live under the chrome band.

## What's next

- [DecoratedWindow on Tao](/docs/tao/decorated-window) — window parameters and scope members.
- [Window & toolkits](/docs/window) — shared window API and toolkit themes.
- [Accessibility](/docs/tao/accessibility) — Compose semantics projected to VoiceOver, Narrator, Orca.

---

# Overlay windows

URL: https://nucleusframework.dev/en/docs/tao/overlay-windows

Build watermarks, desktop widgets, and heads-up overlays with transparent, click-through, always-on-bottom, and all-workspaces windows on the Tao backend.

An overlay is a window that sits outside the normal window stack: a watermark that ignores
clicks, a widget pinned below every other window, a badge that follows the user across
workspaces. This page covers the window flags that make those shapes possible and what each one
does per platform.

## Add the dependency

The flags are parameters on `DecoratedWindow` in `nucleus-application`, implemented by the Tao
backend:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

Overlay flags are a Tao feature. On the AWT backends they are accepted and ignored, so the same
source runs there with an ordinary window.

## Build a click-through watermark

A passive overlay is transparent, undecorated, unfocusable, and lets the pointer pass through to
whatever is behind it:

```kotlin
import androidx.compose.ui.Alignment
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.WindowPosition
import androidx.compose.ui.window.rememberWindowState
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.nucleusApplication

fun main(args: Array<String>) = nucleusApplication(args) {
    val state = rememberWindowState(
        position = WindowPosition.Aligned(Alignment.BottomEnd),
        size = DpSize(360.dp, 160.dp),
    )

    DecoratedWindow(
        onCloseRequest = { },
        state = state,
        title = "Watermark",
        resizable = false,
        undecorated = true,
        transparent = true,
        alwaysOnTop = true,
        focusable = false,
        clickThrough = true,
        hiddenFromDock = true,
        visibleOnAllWorkspaces = true,
        forceX11 = true,
    ) {
        Watermark()
    }
}
```

Pair `clickThrough = true` with `focusable = false`: a window that cannot be clicked should not
take keyboard focus either.

## Pin a widget below other windows

A desktop widget is the same shape with the stacking inverted — `alwaysOnBottom` instead of
`alwaysOnTop`, and clicks kept so the widget stays interactive:

```kotlin
DecoratedWindow(
    onCloseRequest = ::exitApplication,
    state = rememberWindowState(
        position = WindowPosition.Aligned(Alignment.BottomEnd),
        size = DpSize(300.dp, 340.dp),
    ),
    title = "Nucleus widget",
    resizable = false,
    undecorated = true,
    transparent = true,
    hiddenFromDock = true,
    nativeContextMenu = true,
    visibleOnAllWorkspaces = true,
    forceX11 = true,
    alwaysOnBottom = true,
) {
    WidgetSurface()
}
```

`alwaysOnTop` and `alwaysOnBottom` are mutually exclusive: setting one clears the other, and the
last one set wins.

Below-stacking is not desktop membership. The window still appears in the taskbar and Alt+Tab
unless you also set `hiddenFromDock`, and it is not a true desktop-type window. On native Wayland
a surface glued to the wallpaper needs `wlr-layer-shell`, which Tao does not implement.

## Toggle flags at run time

`clickThrough`, `alwaysOnBottom`, and `visibleOnAllWorkspaces` are reactive parameters: change the
state they read and the window follows. For imperative control, call the setters on the
`TaoWindow` handle:

```kotlin
import dev.nucleusframework.window.tao.TaoWindow

fun applyOverlayMode(window: TaoWindow, passive: Boolean) {
    window.setIgnoreCursorEvents(passive)
    window.setAlwaysOnBottom(passive)
    window.setVisibleOnAllWorkspaces(passive)
}
```

`transparent` and `forceX11` are creation-time only — they describe the native surface, which
cannot change after the window exists.

## Take an X11 surface on Wayland

Client-side stacking, positioning, and workspace stickiness do not exist in the Wayland
protocols, so overlay flags are no-ops on a native Wayland surface. `forceX11 = true` gives one
window an XWayland surface instead, without pushing the rest of the app off Wayland:

```kotlin
DecoratedWindow(onCloseRequest = { }, forceX11 = true, /* … */) { Watermark() }
```

Read back what the window actually got:

```kotlin
import dev.nucleusframework.core.runtime.Platform
import dev.nucleusframework.window.tao.TaoWindow

fun surfaceLabel(window: TaoWindow?): String? {
    if (window == null || Platform.Current != Platform.Linux) return null
    return if (window.isNativeWaylandSurface) "Wayland" else "X11"
}
```

`isNativeWaylandSurface` reads the live native surface rather than the environment, so a
`forceX11` window reports `false` while its siblings on Wayland report `true`. It is meaningful
only once the window is ready.

To move the whole process onto XWayland instead, set `NUCLEUS_TAO_LINUX_RENDERER=x11` (or
`GDK_BACKEND=x11`) before launch.

When a flag lands on a native Wayland surface, Nucleus logs a warning once per window and per
feature through `java.util.logging`, naming the flag and the reason it cannot work. If `forceX11`
finds no X server on `DISPLAY` — a session with no XWayland — the window stays on Wayland and
says so.

## Platform behavior

**macOS**

`clickThrough` sets `NSWindow.ignoresMouseEvents`. `alwaysOnBottom` uses a window level below
normal, and `visibleOnAllWorkspaces` joins every Space through
`NSWindowCollectionBehaviorCanJoinAllSpaces`.

A transparent window keeps its shadow, because AppKit shapes the shadow to the drawn content.
Floating above another app's full-screen Space needs a window level Tao does not expose.

**Windows**

`clickThrough` applies `WS_EX_TRANSPARENT | WS_EX_LAYERED` and initializes the layer's alpha, so
per-pixel transparency keeps working. `alwaysOnBottom` uses `HWND_BOTTOM`.

`visibleOnAllWorkspaces` is a no-op and is not needed: a window hidden from the taskbar
(`hiddenFromDock = true`) is not tracked by the Virtual Desktop Manager and already shows on
every desktop.

A fully transparent window drops the system shadow and the 1px DWM border, which trace the
rectangular window rather than your content. Hit-testing is unaffected.

**Linux**

`clickThrough` installs an empty GDK input region. `alwaysOnBottom` maps to
`_NET_WM_STATE_BELOW` and `visibleOnAllWorkspaces` to `gtk_window_stick()` — both X11 and
XWayland only.

Transparency itself works on both backends. Stacking, positioning, and workspace flags need X11:
use `forceX11` per window, or `NUCLEUS_TAO_LINUX_RENDERER=x11` for the process.

## API reference

### DecoratedWindow parameters

| Parameter | Default | Reactive | Description |
|---|---|---|---|
| `transparent` | `false` | No | Builds the native surface with an alpha channel; opaque background and title-bar colors are cleared. |
| `clickThrough` | `false` | Yes | The window ignores pointer events; they reach whatever is behind it. |
| `alwaysOnBottom` | `false` | Yes | Keeps the window below normal windows. Clears `alwaysOnTop`. |
| `visibleOnAllWorkspaces` | `false` | Yes | Shows the window on every workspace or Space. |
| `forceX11` | `false` | No | Linux only: request an X11 (XWayland) surface for this window. |

`alwaysOnBottom` is also available on `HostedWindow`. `transparent`, `clickThrough`,
`visibleOnAllWorkspaces`, and `forceX11` are additionally exposed on the Material and Jewel
window wrappers.

### TaoWindow members

| Member | Description |
|---|---|
| `setIgnoreCursorEvents(ignore: Boolean)` | Imperative `clickThrough`. |
| `setAlwaysOnBottom(alwaysOnBottom: Boolean)` | Imperative `alwaysOnBottom`. |
| `setVisibleOnAllWorkspaces(visible: Boolean)` | Imperative `visibleOnAllWorkspaces`. |
| `isNativeWaylandSurface: Boolean` | Whether this window ended up on a native Wayland surface. |

Reach the handle from the window scope with `nucleusWindow.unsafe.taoWindow`.

## Notes

- A mostly transparent window looks better with custom chrome than with the stock `TitleBar`;
  combine `transparent = true` with `undecorated = true` for a borderless overlay.
- Compose scenes are told the window is transparent, so dialog scrims and popups blend against
  the alpha background instead of painting over a grey sheet.
- `WindowPosition.Aligned` cannot be honored on native Wayland — the compositor decides
  placement. Nucleus logs this once per process.

## What's next

- [DecoratedWindow on Tao](/docs/tao/decorated-window) — the rest of the window parameters.
- [Native Wayland](/docs/tao/wayland) — session detection and the X11 fallback.
- [Context menus](/docs/window/context-menu) — the menu an interactive widget needs.

---

# Native views on Tao

URL: https://nucleusframework.dev/en/docs/tao/native-views

Embed any platform-native view — NSView, HWND, or GtkWidget — inside a Compose layout on the Tao backend.

The `NativeView` composable embeds a platform-native view inside a Compose layout on the
Tao backend. It is the Tao equivalent of `AndroidView` on Android and `UIKitView` on
Compose iOS: you supply a `NucleusPlatformView` (`NSView*`, `HWND`, or `GtkWidget*`), and
Nucleus reparents that handle into the Tao window, keeps it sized to the Compose layout
slot, and disposes it when the composable leaves. Anything that exposes one of those
handles works — AppKit/SwiftUI views, Win32 or WinUI controls, WebView2, GTK widgets, and
so on.

## Add the dependency

```kotlin title="build.gradle.kts"
plugins {
    id("dev.nucleusframework")
}

dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

`NativeView` and `NucleusPlatformView` live in `dev.nucleusframework.window.tao`, provided
by `decorated-window-tao`. They are available inside any window opened on the Tao backend.

## Embed a native view

Wrap your platform handle in a `NucleusPlatformView` and pass a `factory` to `NativeView`.
The variant you implement decides the embedding strategy — `NsView` on macOS, `HWnd` on
Windows, `GtkWidget` on Linux:

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import dev.nucleusframework.window.tao.NativeView
import dev.nucleusframework.window.tao.NucleusPlatformView

// A macOS view backed by a raw NSView* handle you obtain from your
// own AppKit / SwiftUI bridge.
class WebPlatformView(private val handle: Long) : NucleusPlatformView.NsView {
    override val nsViewHandle: Long = handle

    override fun dispose() {
        // Release the native view you created in the factory.
    }
}

@Composable
fun BrowserPane(url: String) {
    NativeView(
        factory = { WebPlatformView(createNativeWebView(url)) },
        modifier = Modifier.fillMaxSize(),
    )
}
```

`factory` runs once and its result is remembered for the lifetime of the composable.
Nucleus calls `dispose()` when `NativeView` leaves the composition. The native view
tracks the layout slot's position and size automatically — you don't set frames yourself.

Nucleus does not create the native view for you. `createNativeWebView` above is a
placeholder for your own interop code that returns the platform handle (an `NSView*` on
macOS, an `HWND` on Windows, a `GtkWidget*` on Linux) as a `Long`.

## How it works

`NativeView` reads the variant of the `NucleusPlatformView` returned by `factory` and
routes to the matching embedding path. On macOS the `NsView` is added as a sibling of the
Tao content view; on Windows the `HWnd` is reparented under the main Tao HWND; on Linux
the `GtkWidget` is added to Tao's GTK content widget. Each path tracks the Compose layout
slot with `onGloballyPositioned` and forwards the bounds to the native side, so the
embedded view follows resizes and scrolls with no extra wiring. From 2.5.15, a trackpad
pan over a `NativeView` is consumed and forwarded (`PanStart` / `PanMove` / `PanEnd`) so
the embedded scroll view rubber-bands; the Compose scrollable above does not open a
competing pan session.

If the returned variant doesn't match the current OS — or the platform's scene plumbing
isn't available — `NativeView` renders an empty `Box(modifier)` instead of failing. This
lets you write one call site per platform and rely on the fallback on the others.

The optional `content` slot renders Compose UI on top of the embedded view, in the host window's
own Compose scene on all three platforms — the same hole-punch blending path as later Compose
siblings and in-scene popups. Overlay content claims its own input; anything it does not cover
falls through to the native view, with no marker modifier needed.

## API reference

### Describe the native view

`NucleusPlatformView` is a sealed interface. Implement exactly one platform variant and
expose the corresponding handle as a `Long`:

| Variant | Platform | Handle property |
|---|---|---|
| `NucleusPlatformView.NsView` | macOS | `nsViewHandle` — pointer to your `NSView*` |
| `NucleusPlatformView.HWnd` | Windows | `hwndHandle` — pointer to your `HWND` |
| `NucleusPlatformView.GtkWidget` | Linux | `gtkWidgetHandle` — pointer to your `GtkWidget*` |

The interface also declares lifecycle callbacks with default no-op bodies. Override the ones
your view needs:

| Member | Called when |
|---|---|
| `resize(widthPx, heightPx)` | The embedded view's logical size changes. |
| `setBounds(xPx, yPx, widthPx, heightPx)` | The full frame changes; override when the view's drawing rect is decoupled from its window rect (for example, WebView2). |
| `setCornerRadius(radiusPx)` | The rounded-corner clip changes and the host's generic clip can't reach the view's surface. |
| `clearFocus()` | The host window or a sibling Compose layer takes focus. |
| `dispose()` | Final teardown — release the native resources you own. |

### Embed the view

```kotlin
@Composable
fun NativeView(
    factory: () -> NucleusPlatformView,
    modifier: Modifier = Modifier,
    update: (NucleusPlatformView) -> Unit = {},
    cornerRadius: Dp = Dp.Unspecified,
    content: @Composable () -> Unit = {},
)
```

| Parameter | Notes |
|---|---|
| `factory` | Creates the `NucleusPlatformView`. Runs once; the result is remembered and disposed when the composable leaves. |
| `modifier` | Sizes and positions the layout slot. The embedded view fills it. |
| `update` | Runs on every recomposition with the remembered view. Use it to push new state into the native view. |
| `cornerRadius` | Rounded-corner clip; see below. |
| `content` | Compose overlay rendered on top of the native view. |

### Overlay Compose content

The `content` slot draws Compose UI over the embedded view, in the window's own Compose scene.
Anything you put there is an ordinary composable: it takes pointer events where it is drawn, and
events it does not consume are replayed to the native view underneath.

```kotlin
NativeView(
    factory = { WebPlatformView(createNativeWebView(url)) },
    modifier = Modifier.fillMaxSize(),
) {
    // A Compose toolbar over the web view. The button handles its own clicks;
    // clicks elsewhere reach the web view underneath.
    Button(onClick = { /* reload */ }) {
        Text("Reload")
    }
}
```

Because the overlay lives in the main scene, Compose siblings declared after the `NativeView`
also paint over it, and `Popup`s from inside the scene land above the native view.

`Modifier.consumeOverlayPointerEvents()` is deprecated and no longer needed — overlay content
claims its own input. The `cursor` argument still maps to `Modifier.pointerHoverIcon`; use that
modifier directly instead.

The native view is composited into the scene with a punched hole: Compose clears the view's
rectangle to transparent, and the platform shows the native content through it.

**macOS**

The `NSView` is inserted below the Tao content view, and the Metal layer becomes non-opaque so
Skia clears at alpha 0. Moves are applied in the same frame as the Compose geometry.

**Windows**

The child `HWND` is parented under the window. Win32 children always paint above their parent, so
Compose is re-rendered on top through a DirectComposition overlay clipped to the union of the
live `NativeView` rectangles — Compose still sees events first inside those rectangles.

A `hwndHandle` of `0L` is legal: a view that has no Win32 child window (WebView2 in composition
mode, for example) drives its own visual through `setBounds` and `setCornerRadius`.

**Linux**

The `GtkWidget` is reparented under the window and the GL surface paints above it, so the punched
hole reveals the widget. While a `NativeView` is attached, the surface advertises an empty opaque
region so the compositor keeps blending the GTK content underneath.

This requires Wayland. On the X11 backend a child window's alpha is never blended against its
parent, so the punched rectangle shows the desktop instead of the widget — the widget still runs,
but behind the GL surface.

### Clip to rounded corners

Compose's `Modifier.clip()` does not propagate to embedded native views, the same
limitation as `AndroidView` and `UIKitView`. Use `cornerRadius` instead:

```kotlin
NativeView(
    factory = { WebPlatformView(createNativeWebView(url)) },
    modifier = Modifier.fillMaxSize(),
    cornerRadius = 12.dp,
)
```

Pass `Dp.Infinity` to clip fully circular regardless of size. The default,
`Dp.Unspecified`, applies no clip.

`cornerRadius` has no effect on Linux, where GTK 3 has no per-widget rounded clipping. Draw a
Compose `RoundedCornerShape` border in the `content` slot instead.

## What's next

- [WebView](/docs/webview) — ready-made multiplatform WebView built on this primitive for desktop.
- [TextureView](/docs/tao/texture-view) — external GPU textures in the Compose scene (no CPU copy).
- [The Tao backend](/docs/tao) — what the no-AWT backend covers.
- [DecoratedWindow on Tao](/docs/tao/decorated-window) — open the window that hosts the view.
- [Multi-touch and trackpad gestures](/docs/tao/multi-touch) — read Tao input events.

---

# TextureView

URL: https://nucleusframework.dev/en/docs/tao/texture-view

Composite an externally produced GPU texture into the Compose scene on the Tao backend without a CPU frame copy.

`TextureView` composites an externally produced GPU texture inside the Compose scene on the
Tao backend. Z-order, clipping, `Modifier.graphicsLayer` transforms, and scrolling apply to the
texture the same way they do to any other composable. There is no CPU frame copy: the producer
texture is imported on the window's GPU device (ANGLE shared D3D11 on Windows, Metal/`IOSurface`
on macOS, DMA-BUF/`EGLImage` on Linux).

It is the passive GPU-pixels counterpart of [`NativeView`](/docs/tao/native-views). Prefer
`NativeView` for interactive native widgets; use `TextureView` when you already own a decoder or
renderer that publishes GPU frames (video, camera, game engine, GPU compute). For **in-process**
renderers that can allocate on the scene's own GPU device, use
[`TaoGpuRenderContext`](/docs/tao/gpu-render-context) instead of importing a foreign texture.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

`TextureView`, `TextureViewController`, and the platform source factories live in
`dev.nucleusframework.window.tao`.

## Show a texture

1. Obtain a platform handle from your producer (shared DXGI handle, `IOSurface` pointer,
   DMA-BUF fd, …).
2. Wrap it with the matching factory into a `TextureViewSource`.
3. Place a `TextureView` and, for live content, a `TextureViewController`.
4. After each published frame, call `controller.markFrameAvailable()` (any thread). Only the
   draw pass re-runs — no recomposition.

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.FilterQuality
import androidx.compose.ui.layout.ContentScale
import dev.nucleusframework.window.tao.TextureView
import dev.nucleusframework.window.tao.TextureViewController
import dev.nucleusframework.window.tao.TextureViewSource
import dev.nucleusframework.window.tao.rememberTextureViewController

@Composable
fun VideoPane(source: TextureViewSource?) {
    val controller = rememberTextureViewController()
    DisposableEffect(source) {
        // Start your producer loop; call controller.markFrameAvailable() after each frame.
        onDispose { /* stop producer */ }
    }
    TextureView(
        source = source,
        controller = controller,
        modifier = Modifier.fillMaxSize(),
        contentScale = ContentScale.Fit,
        filterQuality = FilterQuality.Low,
    )
}
```

`filterQuality` and `contentScale` mirror Compose `Image`. Content outside the composable
bounds is clipped. When `source` is `null`, does not match the host platform, or the import
fails, `TextureView` renders an empty `Box(modifier)`.

## Platform sources

Factories return a `TextureViewSource`. Pass only the factory that matches the OS you run on;
other platforms treat an unmatched source as an empty box.

**Windows**

```kotlin
import dev.nucleusframework.window.tao.nucleusD3D11SharedTextureSource

val source = nucleusD3D11SharedTextureSource(
    sharedHandle = dxgiSharedHandle, // IDXGIResource::GetSharedHandle (legacy)
    widthPx = width,
    heightPx = height,
)
```

- Handle must be a **legacy** DXGI shared handle (`GetSharedHandle`). NT handles
  (`D3D11_RESOURCE_MISC_SHARED_NTHANDLE`) are not supported by ANGLE's import path.
- Texture format: `R8G8B8A8_UNORM` (or compatible RGBA8) with premultiplied alpha;
  `widthPx` / `heightPx` must match the D3D texture size.
- Synchronization:
  - `D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX` (recommended) — each `markFrameAvailable` pulls
    under `AcquireSync(0)` / `ReleaseSync(0)` into a staging texture (tear-free, one GPU-GPU
    copy). Bracket producer writes the same way.
  - plain `D3D11_RESOURCE_MISC_SHARED` — true zero-copy; the producer must `Flush()` after each
    frame or a redraw may sample a partial frame.

The [mediafoundation-demo](https://github.com/NucleusFramework/Nucleus/tree/v2.5.18/examples/mediafoundation-demo)
sample shows Media Foundation decode into a shared D3D11 texture.

**macOS**

```kotlin
import dev.nucleusframework.window.tao.nucleusIOSurfaceTextureSource
import dev.nucleusframework.window.tao.nucleusMetalTextureSource

// Shareable buffer (cross-device / cross-process)
val surfaceSource = nucleusIOSurfaceTextureSource(
    ioSurface = ioSurfaceRefAsLong,
    widthPx = width,
    heightPx = height,
)

// Same-process Metal texture (or CVMetalTextureCache output via its IOSurface)
val metalSource = nucleusMetalTextureSource(
    metalTexture = mtlTextureAsLong,
    widthPx = width,
    heightPx = height,
)
```

- Pixel format: 32-bit `BGRA` or `RGBA` (sRGB variants included), premultiplied alpha.
- Surface / texture dimensions must match `widthPx` × `heightPx`.
- Each frame is pulled with one GPU-GPU copy on the window's command queue. Finish producer
  writes (`commit` + `waitUntilCompleted`, or double-buffer) **before**
  `markFrameAvailable`.
- A texture that is neither render-target-capable on the window's Metal device nor
  `IOSurface`-backed cannot be imported; hand over an `IOSurface` source instead.

The [avfoundation-demo](https://github.com/NucleusFramework/Nucleus/tree/v2.5.18/examples/avfoundation-demo)
sample decodes with AVFoundation/VideoToolbox into an `IOSurface`.

**Linux**

```kotlin
import dev.nucleusframework.window.tao.NucleusDmaBufPlane
import dev.nucleusframework.window.tao.NucleusDrmFormat
import dev.nucleusframework.window.tao.NucleusYuvColorSpace
import dev.nucleusframework.window.tao.NucleusYuvFormat
import dev.nucleusframework.window.tao.nucleusDmaBufTextureSource
import dev.nucleusframework.window.tao.nucleusEglImageTextureSource
import dev.nucleusframework.window.tao.nucleusYuvDmaBufTextureSource

// Packed 32-bit RGB DMA-BUF
val rgb = nucleusDmaBufTextureSource(
    fd = dmaBufFd,
    widthPx = width,
    heightPx = height,
    stride = stride,
    fourcc = NucleusDrmFormat.ARGB8888,
    offset = 0,
    modifier = NucleusDrmFormat.MODIFIER_INVALID,
)

// Producer-owned EGLImage on the window's EGLDisplay
val egl = nucleusEglImageTextureSource(eglImage = eglImageAsLong, widthPx = width, heightPx = height)

// Planar YUV (I420 / YV12) — hardware decoder native layout
val yuv = nucleusYuvDmaBufTextureSource(
    widthPx = width,
    heightPx = height,
    format = NucleusYuvFormat.I420,
    planes = listOf(
        NucleusDmaBufPlane(fd = yFd, stride = yStride, offset = 0),
        NucleusDmaBufPlane(fd = uFd, stride = uStride, offset = 0),
        NucleusDmaBufPlane(fd = vFd, stride = vStride, offset = 0),
    ),
    colorSpace = NucleusYuvColorSpace.BT709_LIMITED,
)
```

- Single-plane RGB uses DRM FourCC codes in `NucleusDrmFormat` (`ARGB8888`, `XRGB8888`,
  `ABGR8888`, `XBGR8888`). The driver maps sampling to RGBA for app code.
- `fd` stays owned by the caller; EGL takes its own reference at import time.
- YUV supports **three-plane** 4:2:0 layouts only (`I420`, `YV12`). NV12/NV21 are not supported
  yet (Skia has no two-channel GPU texture mapping for interleaved chroma).
- For acquire fences instead of a CPU-side finish, call
  `controller.markFrameAvailable(acquireFenceFd)` (Linux DMA-BUF only; requires
  `EGL_ANDROID_native_fence_sync`). Elsewhere the fd is ignored and remains yours.

The [gstreamer-demo](https://github.com/NucleusFramework/Nucleus/tree/v2.5.18/examples/gstreamer-demo)
sample feeds GStreamer frames as an `EGLImage`.

## How it works

`TextureView` is a pure drawing surface. The producer owns its device, queue, and allocation;
Nucleus only imports that allocation onto the window's GPU and samples it during Compose's
draw pass. Several `TextureView`s that share one `TextureViewSource` share a single GPU import.

Frame signalling goes through `TextureViewController`:

- `markFrameAvailable()` increments an internal stamp that invalidates **draw only**.
- Safe from any thread (decoder thread, render thread, pool).
- Optional Linux overload `markFrameAvailable(acquireFenceFd)` transfers ownership of a
  `sync_file` fd; the consumer GPU waits before sampling. Pass `TextureViewController.NO_FENCE`
  (`-1`) for no fence.
- `rememberTextureViewController()` releases any held fence when composition leaves.

Input is not handled. Interactive native UI still uses `NativeView`.

Test helpers (`D3D11TestTextureProducer`, `MetalTestTextureProducer`,
`DmaBufTestTextureProducer`) ship in `decorated-window-tao` for demos and CI; production apps
use their own producers and the public factories above.

## API reference

### TextureView

```kotlin
@Composable
fun TextureView(
    source: TextureViewSource?,
    modifier: Modifier = Modifier,
    controller: TextureViewController? = null,
    filterQuality: FilterQuality = FilterQuality.Low,
    contentScale: ContentScale = ContentScale.FillBounds,
    alignment: Alignment = Alignment.Center,
)
```

### TextureViewController

```kotlin
class TextureViewController {
    fun markFrameAvailable()
    fun markFrameAvailable(acquireFenceFd: Int)
    companion object {
        const val NO_FENCE: Int = -1
    }
}

@Composable
fun rememberTextureViewController(): TextureViewController
```

### Source factories

| Factory | Platform | Handle |
|---------|----------|--------|
| `nucleusD3D11SharedTextureSource(sharedHandle, widthPx, heightPx)` | Windows | Legacy DXGI shared handle |
| `nucleusIOSurfaceTextureSource(ioSurface, widthPx, heightPx)` | macOS | `IOSurfaceRef` as `Long` |
| `nucleusMetalTextureSource(metalTexture, widthPx, heightPx)` | macOS | `id<MTLTexture>` as `Long` |
| `nucleusDmaBufTextureSource(fd, widthPx, heightPx, stride, …)` | Linux | Single-plane DMA-BUF |
| `nucleusEglImageTextureSource(eglImage, widthPx, heightPx)` | Linux | Producer-owned `EGLImageKHR` |
| `nucleusYuvDmaBufTextureSource(widthPx, heightPx, format, planes, colorSpace)` | Linux | Planar YUV DMA-BUF |

Supporting types: `NucleusDrmFormat`, `NucleusDmaBufPlane`, `NucleusYuvFormat`
(`I420`, `YV12`), `NucleusYuvColorSpace` (`BT601_*`, `BT709_*`).

## Notes

- **Tao only.** There is no AWT/`SwingPanel` path for external GPU textures.
- Import failure is silent at the UI level (empty box). Check producer logs and that dimensions /
  formats match the contract above.
- Do not call `markFrameAvailable` faster than the display can composite without also pacing
  the producer — the stamp coalesces, but wasted GPU work does not.
- Tray panels and popup layers keep their EGL binding neutral so a `TextureView` inside a
  standalone tray panel still imports correctly.

## What's next

- [GPU render context](/docs/tao/gpu-render-context) — in-process renderers on the scene's device.
- [Native views](/docs/tao/native-views) — embed interactive `NSView` / `HWND` / `GtkWidget` content.
- [DecoratedWindow on Tao](/docs/tao/decorated-window) — open windows that host `TextureView`.
- [Tao backend overview](/docs/tao) — backends, Wayland, and related primitives.

---

# GPU render context

URL: https://nucleusframework.dev/en/docs/tao/gpu-render-context

Give in-process GPU renderers the scene's Skia DirectContext and native device so they can composite without a second GPU or per-frame copy.

`TaoGpuRenderContext` publishes the GPU context of the enclosing Compose surface on the Tao
backend: the Skia `DirectContext` the scene draws with, plus the native device behind it
(Metal on macOS, ANGLE GLES on Windows, native EGL/GLES on Linux). An in-process renderer —
a map engine, 3D viewport, or charting library — allocates its render targets **on that same
device** and lets Compose sample them with no second GPU, no shareable handle, and no per-frame
cross-device copy.

It is the complement of [`TextureView`](/docs/tao/texture-view), not a replacement.
`TextureView` is the contract for **foreign** producers (out-of-process engines, hardware
decoders on their own device). Use `TaoGpuRenderContext` when your renderer can create its
GPU objects on the scene's context.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

Types live in `dev.nucleusframework.window.tao`.

## Obtain the context

Call `rememberTaoGpuRenderContext()` inside a surface that owns a GPU context
(`DecoratedWindow` content, a native popup layer, a `NativeView` overlay, or a tray panel).
It returns `null` during bring-up, teardown, or a non-hardware environment:

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.runtime.withFrameNanos
import dev.nucleusframework.window.tao.TaoGpuRenderContext
import dev.nucleusframework.window.tao.TaoOpenGlRenderContext
import dev.nucleusframework.window.tao.rememberTaoGpuRenderContext

@Composable
fun MapViewport() {
    val renderContext = rememberTaoGpuRenderContext() ?: return
    // Key renderer state on the instance: a rebuilt context is a new identity.
    val renderer = remember(renderContext) { MapEngineRenderer(renderContext) }
    DisposableEffect(renderer) {
        onDispose { renderer.close() }
    }
    LaunchedEffect(renderer) {
        while (true) {
            // GPU work inside withFrameNanos — see Frame pacing below.
            withFrameNanos { renderer.renderFrame() }
        }
    }
    // … sample the engine output in Compose
}
```

## Backends

| Type | Platforms | Extra API |
|------|-----------|-----------|
| `TaoMetalRenderContext` | macOS | `metalDevicePtr` — borrowed `id<MTLDevice>` |
| `TaoOpenGlRenderContext` | Linux, Windows | `withContextCurrent { }` — bind the surface GL context |

Both expose:

| Member | Description |
|--------|-------------|
| `backend: TaoRenderBackend` | `METAL` or `OPENGL` |
| `skiaContext: DirectContext` | Skia context the scene paints with (borrowed) |
| `runOnGpuThread { }` | Exclusive access for Skia / GPU work (Metal hops to the render thread; GL runs inline on the event-loop thread after a thread check) |

On Windows, `OPENGL` is ANGLE-on-D3D11 GLES — not desktop OpenGL. Resolve entry points
through ANGLE's `eglGetProcAddress`, the same way Skia does for the scene.

## Ownership and lifetime

Every handle is **borrowed**. Do not retain, release, or free them. Stop using a context the
moment the surface publishes a different one (or `null`).

`rememberTaoGpuRenderContext()` returns a **new instance** whenever the underlying context is
rebuilt — window detach, a Wayland hide/show cycle (full EGL stack rebuild), popup or tray
panel teardown. Key renderer state on that instance:

```kotlin
val renderer = remember(renderContext) { EngineRenderer(renderContext) }
DisposableEffect(renderContext) {
    onDispose {
        renderContext.runOnGpuThread { renderer.releaseGpuResources() }
    }
}
```

## Frame pacing

Issue GPU work **inside** the `withFrameNanos` callback (or during composition / layout /
draw), not in the code that runs after the suspension:

- On Linux the host hands the EGL context to a swap thread for blocking `eglSwapBuffers`
  right after every frame. A post-frame continuation races that hand-off and gets
  `withContextCurrent → null` almost every vsync.
- The frame callback runs inside the render pass, while the context is bindable.

When the scene has live `TextureView` imports or `TaoGpuRenderContext` consumers, Tao keeps
VSync on through the Windows modal move/resize loop and Linux resize bursts so
frame-clock-driven content stays display-paced instead of running at event-pump speed.

## TextureView vs GPU render context

| | `TextureView` | `TaoGpuRenderContext` |
|--|---------------|------------------------|
| Producer | Foreign / out-of-process | In-process, same device |
| Import | Shared D3D11 / IOSurface / DMA-BUF | Allocate on `skiaContext` |
| Typical use | Video decoder, game engine, camera | MapLibre-style engines, 3D viewports, charts |

## Notes

- Call every member from the composition thread (Tao event-loop thread; process main thread on
  macOS). Hop GPU work through `runOnGpuThread` / `withContextCurrent`.
- Nested `withContextCurrent` is safe; the previous current context is restored afterwards and
  Skia's GL state cache is invalidated so consumers do not need to.
- Each Windows window host owns an unshared ANGLE GLES context. Resize-path GPU cache purges
  bind that host's context first so a sibling window's textures stay intact. macOS and Linux
  popup / tray surfaces may also own private contexts.

## What's next

- [TextureView](/docs/tao/texture-view) — import external GPU frames into the scene.
- [Native views](/docs/tao/native-views) — embed interactive native widgets.
- [DecoratedWindow](/docs/tao/decorated-window) — host Tao windows from composition.
- [The Tao backend](/docs/tao) — architecture and backend selection.

---

# Multi-touch & gestures

URL: https://nucleusframework.dev/en/docs/tao/multi-touch

Read trackpad and touch gestures on the Tao backend through Compose pointer events, or the raw gesture stream.

The Tao backend forwards the operating system's gesture stream into Compose pointer
events, so pinches, rotations, and trackpad scrolls reach your UI through the standard
Compose input APIs. When you need the unprocessed gesture data, `TaoWindow` also exposes
the raw trackpad stream.

## Add the dependency

Gesture support ships with the Tao backend. No extra artifact is required.

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

## Read gestures from Compose

Most gesture handling goes through Compose. Trackpad and touch input arrive as
`PointerInputChange` values, so `detectTransformGestures` and the other pointer-input
modifiers work without any Tao-specific code:

```kotlin
import androidx.compose.foundation.gestures.detectTransformGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.pointerInput

@Composable
fun ZoomCanvas() {
    var scale by remember { mutableStateOf(1f) }

    Box(
        Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                detectTransformGestures { _, _, zoom, _ ->
                    scale *= zoom
                }
            },
    )
}
```

Each `PointerInputChange` also carries the input source and pressure, which lets you branch
on how the event was produced:

```kotlin
import androidx.compose.ui.input.pointer.PointerType

Modifier.pointerInput(Unit) {
    awaitPointerEventScope {
        while (true) {
            val change = awaitPointerEvent().changes.first()
            val source = change.type          // PointerType.Mouse | Touch — Tao emits no Stylus/Eraser
            val pressure = change.pressure    // 1f when the digitizer reports none
            // React to source / pressure.
        }
    }
}
```

## Read trackpad pans from Compose

From 2.5.15 on macOS, two-finger trackpad gestures arrive as `PointerEventType.PanStart` /
`PanMove` / `PanEnd` with `panOffset` in pixels. Mouse-wheel notches stay `Scroll`.
Foundation's `Modifier.scrollable` handles both; a custom `pointerInput` that only listens
for `Scroll` will not see the trackpad:

```kotlin
import androidx.compose.ui.input.pointer.PointerEventType

Modifier.pointerInput(Unit) {
    awaitPointerEventScope {
        while (true) {
            val event = awaitPointerEvent()
            val change = event.changes.first()
            when (event.type) {
                PointerEventType.PanMove -> {
                    val pan = change.panOffset  // pixels; AWT preciseWheelRotation × 10.dp
                    // Apply the pan.
                }
                PointerEventType.Scroll -> {
                    val scroll = change.scrollDelta
                    // Wheel notch or phase-less precise scroll.
                }
                else -> Unit
            }
        }
    }
}
```

Start the process with `-Dnucleus.tao.trackpadPanEvents=false` to receive AWT-style `Scroll`
events for every step instead.

The pan stays open across AppKit's inertial momentum tail. Closing it when the fingers lift
would stack Compose's own fling on top of the platform animation. A `PanEnd` arrives after
the tail, or after a short grace if no tail follows.

## Read the raw gesture stream

To distinguish gesture kinds and phases directly — for example, telling a pinch apart from
a rotate — register a `TrackpadGestureListener` on the current `TaoWindow`:

```kotlin
import dev.nucleusframework.window.tao.LocalTaoWindow
import dev.nucleusframework.window.tao.TaoTrackpadGesture
import dev.nucleusframework.window.tao.TaoTrackpadPhase

val window = LocalTaoWindow.current
window?.onTrackpadGesture { kind, phase, xFixed, yFixed, valueFixed ->
    if (kind == TaoTrackpadGesture.MAGNIFY && phase == TaoTrackpadPhase.CHANGED) {
        val ratio = valueFixed / 10_000f   // magnify delta as a ratio
        // Apply the zoom delta.
    }
}
```

The callback receives fixed-point integers: `xFixed` and `yFixed` are view-relative physical
pixels multiplied by 1024, and `valueFixed` is the delta multiplied by 10000 (a ratio for
magnify, degrees for rotate).

`onTrackpadGesture` replaces the previously registered listener rather than adding one.
Register a single listener per window.

## How it works

On each platform, Tao subscribes to the native high-resolution gesture source — `NSEvent`
magnify and rotate on macOS, precision-touchpad input on Windows, and the Wayland pointer-gesture
protocol on Linux. The Rust bridge reshapes those events and delivers them to the JVM through a
single wire format, which the scene host turns into Compose pointer events.

The raw `TrackpadGestureListener` sits on that same wire, before the pointer-event synthesis.
macOS and Linux emit magnify, rotate, and smart-magnify; Windows emits magnify only. There is no
native source on other configurations, so the listener does not fire there.

Tao reports cursor positions in 1/1024 px, so from 2.5.6 a move under 1 dp from the last
dispatched position is suppressed before it reaches Compose. Without that deadband, a click
drifting a fraction of a pixel between press and release starts a parent drag gesture, which
consumes the change and cancels the tap. Press, release, exit, and scroll dispatch at the last
dispatched position; motion past the deadband keeps its exact sub-pixel position. From the same
release, `viewConfiguration.touchSlop` is density-scaled to 18.dp — AWT and Android parity —
instead of 18 raw pixels, which halved every drag and scroll threshold on 2x displays.

From 2.5.15, macOS trackpad scrolling matches AWT: AppKit already follows the
`MouseScrollDelta` convention, so the extra negation of `scrollingDeltaX` is gone, and
precise deltas are handed over in logical points (AWT never applies the display scale).
Phased steps go through `TaoTrackpadPanRouter` and become Pan events at `10.dp` per AWT
wheel unit — the same factor Compose Desktop's `MacOSCocoaConfig` applies to a notch.
Wheel notches and phase-less precise scrolls stay Scroll. Native views consume the pan
and forward it so the embedded scroll view rubber-bands; popups share the same router as
the window.

## API reference

### Register a gesture listener

```kotlin
// dev.nucleusframework.window.tao.TaoWindow
fun onTrackpadGesture(listener: TrackpadGestureListener)

fun interface TrackpadGestureListener {
    fun onGesture(
        kind: Int,        // TaoTrackpadGesture value
        phase: Int,       // TaoTrackpadPhase value
        xFixed: Int,      // physical pixels × 1024, view-relative
        yFixed: Int,
        valueFixed: Int,  // delta × 10000 (ratio for magnify, degrees for rotate)
    )
}
```

Obtain the window from `LocalTaoWindow.current`, which is `null` outside a Tao window.

### Gesture constants

```kotlin
object TaoTrackpadGesture {
    const val MAGNIFY: Int = 0
    const val ROTATE: Int = 1
    const val SMART_MAGNIFY: Int = 2
}

object TaoTrackpadPhase {
    const val BEGAN: Int = 0
    const val CHANGED: Int = 1
    const val ENDED: Int = 2
    const val CANCELLED: Int = 3
}
```

### Pointer info on every change

```kotlin
// androidx.compose.ui.input.pointer.PointerInputChange
val type: PointerType         // Mouse | Touch | Stylus | Eraser
val pressure: Float           // 0f when the device reports no pressure
val position: Offset          // sub-pixel position
val scrollDelta: Offset       // scroll wheel and phase-less precise scroll
val panOffset: Offset         // trackpad pan (macOS, 2.5.15+); pixels
```

## What's next

- [Pen & stylus](/docs/tao/pen-stylus) — pressure and tilt from stylus devices.
- [Wayland](/docs/tao/wayland) — Linux-specific input and windowing behavior.
- [Decorated window](/docs/tao/decorated-window) — the Tao window and its title bar.
- [Tao backend](/docs/tao) — what the Tao backend provides.

---

# Pen & stylus input

URL: https://nucleusframework.dev/en/docs/tao/pen-stylus

Read pen and touchscreen pressure from Compose pointer events on the Tao backend.

The Tao backend delivers pen, stylus, and touchscreen contacts as Compose pointer events of
type `PointerType.Touch`, each carrying a `pressure` value. You read them with the same
`pointerInput` modifier you use for mouse input. The only pen-specific field is `pressure`.

## Add the dependency

Pen and touch support ships with the Tao backend. There is no separate artifact to add.

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

## Read pressure from pointer events

Read pointer events inside a `pointerInput` modifier. Keep the `PointerType.Touch` contacts —
this is what pen and touchscreen input arrives as on Tao — and use `change.pressure` to size
each stroke:

```kotlin
import androidx.compose.foundation.Canvas
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.pointer.*

@Composable
fun InkSurface() {
    val strokes = remember { mutableStateListOf<Triple<Offset, Offset, Float>>() }
    var last: Offset? by remember { mutableStateOf(null) }

    Canvas(
        Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                awaitPointerEventScope {
                    while (true) {
                        val event = awaitPointerEvent()
                        val change = event.changes.first()
                        if (change.type != PointerType.Touch) {
                            last = null
                            continue
                        }
                        val start = last ?: change.position
                        strokes += Triple(start, change.position, change.pressure)
                        last = if (change.pressed) change.position else null
                        change.consume()
                    }
                }
            }
    ) {
        strokes.forEach { (a, b, p) ->
            drawLine(Color.Black, a, b, strokeWidth = 1f + p * 6f)
        }
    }
}
```

## How it works

Tao reads each operating system's native pointer input and forwards every contact into the
Compose scene. On Windows, pen and touchscreen input arrives through `WM_POINTER` / `WM_TOUCH`;
on Linux, through the Wayland and X11/XWayland touch protocols. Each contact is dispatched as a
`PointerType.Touch` pointer, so at the Compose layer a pen is indistinguishable from a finger
except by its pressure.

The native layer reports pressure as an integer scaled by 10,000, which Tao normalizes to
`change.pressure` in the `[0f, 1f]` range. When the digitizer does not report pressure — the
case for most consumer touchscreens — the contact still reports `1f`. A `1f` reading therefore
means either full pressure or no pressure data, not strictly maximal pressure.

Because a contact surfaces as an ordinary `PointerInputChange`, everything that works for mouse
and touch — hit testing, gesture detectors, `consume()` — works for pen input unchanged.

## API reference

### Pointer fields

```kotlin
val change = event.changes.first()
val type: PointerType = change.type     // Mouse | Touch
val pressure: Float = change.pressure   // in [0f, 1f]
val pressed: Boolean = change.pressed
val position: Offset = change.position
```

`PointerType` and `PointerInputChange` are standard Compose types from
`androidx.compose.ui.input.pointer`. The Tao backend reports pen and touch contacts as
`PointerType.Touch`; it does not produce `PointerType.Stylus` or `PointerType.Eraser`.
`PointerInputChange` carries no tilt or rotation, so those are not available through the event.

### Platform support

| Platform                    | Native source                | Pressure                                  |
|-----------------------------|------------------------------|-------------------------------------------|
| Windows                     | `WM_POINTER` / `WM_TOUCH`    | Reported when the digitizer supports it.  |
| Linux (Wayland, X11/XWayland) | touch protocol             | Reported when the digitizer supports it.  |
| macOS                       | —                            | No touch path; contacts arrive as mouse.  |

## Notes

A contact reports `pressure = 1f` both at full pressure and when the digitizer exposes no
pressure at all. Treat `1f` as "maximal or unavailable", not strictly maximal.

## What's next

- [Multi-touch and trackpad gestures](/docs/tao/multi-touch) — read touch and trackpad input on Tao.
- [Wayland](/docs/tao/wayland) — Linux compositor requirements for touch input.
- [The Tao backend](/docs/tao) — how the no-AWT windowing backend fits together.

---

# Drag and drop

URL: https://nucleusframework.dev/en/docs/tao/drag-and-drop

Receive dropped files on the Tao backend through the standard Compose dragAndDropTarget API.

The Tao backend routes native drag-and-drop into Compose through the standard
`Modifier.dragAndDropTarget` API. When something is dropped on your window,
`DragAndDropEvent.nativeEvent` is a `TaoDragAndDropPayload` carrying the dropped file
paths, and `event.awtTransferable` resolves the same data through the usual
`DataFlavor` path — without initializing the AWT toolkit.

Inbound drops carry files only. Text, HTML, and URL payloads are not delivered yet.

## Add the dependency

Drag and drop ships with the Tao backend. Add the backend artifact to your build:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

No extra configuration is required. Once a window runs on the Tao backend, drop targets
receive events.

## Receive dropped files

Attach a `DragAndDropTarget` to a composable with `Modifier.dragAndDropTarget` and read the
files from the Tao payload in `onDrop`:

```kotlin
import androidx.compose.foundation.draganddrop.dragAndDropTarget
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.draganddrop.DragAndDropEvent
import androidx.compose.ui.draganddrop.DragAndDropTarget
import dev.nucleusframework.window.tao.TaoDragAndDropPayload

@Composable
fun DropZone() {
    val target = remember {
        object : DragAndDropTarget {
            override fun onDrop(event: DragAndDropEvent): Boolean {
                val payload = event.nativeEvent as? TaoDragAndDropPayload
                val files = payload?.files ?: emptyList()
                files.forEach { path -> println("dropped: $path") }
                return files.isNotEmpty()
            }
        }
    }

    Box(
        Modifier
            .fillMaxSize()
            .dragAndDropTarget(
                shouldStartDragAndDrop = { true },
                target = target,
            ),
    )
}
```

`TaoDragAndDropPayload.files` is a `List<String>` of absolute paths. `onDrop` returns `true`
when your target accepts the data.

If you already consume drops through the portable Compose Desktop path, keep using
`event.awtTransferable` and `DataFlavor.javaFileListFlavor` — the Tao backend backs it with the
same paths, so that code works unchanged.

## How it works

There is no AWT `DropTarget` on the input path. The native window reports a drop through the
Rust JNI bridge, and the Tao Compose scene host builds a `DragAndDropEvent` for it. The event's
`nativeEvent` is a `TaoDragAndDropPayload`, and the host also wraps the paths in an internal
`Transferable` so `event.awtTransferable` keeps working. That adapter lives in the
`java.datatransfer` layer and never starts the AWT toolkit.

Inbound routing (a drop into your window) is wired on each platform host, including standalone
tray popups (`TrayApp`) from 2.5.3 on Windows and macOS and from 2.5.4 on Linux. Those popups
are ownerless native panels, not `TaoWindow`s; file drops still arrive through
`Modifier.dragAndDropTarget`. Outbound routing (a drag that leaves your window) is handled by
an internal `PlatformDragAndDropManager` and is opt-in per host: where a platform has no
outbound launcher yet, the gesture is reported as not started. Both paths increment counters on
`TaoDnDDiagnostics`.

From 2.3, starting a drag from Compose `dragAndDropSource` no longer freezes the Tao host for
the duration of the OS modal drag loop. Windows (`DoDragDrop`), macOS (AppKit), and Linux (GTK)
all pump frames through a shared `DragPump` on the native side so Compose keeps painting while
the cursor is outside the window.

## API reference

### Read a dropped payload

`TaoDragAndDropPayload` is the value you get from `DragAndDropEvent.nativeEvent` on the Tao
backend. You never construct it yourself.

| Member         | Type           | Description                          |
|----------------|----------------|--------------------------------------|
| `files`        | `List<String>` | Absolute paths of the dropped files. |

### Inspect the DnD plumbing

`TaoDnDDiagnostics` is an object exposing Compose state counters and a recent-message log. Read
the counters inside a composable to observe the plumbing; they update as events flow.

| Member             | Type                   | Description                                             |
|--------------------|------------------------|---------------------------------------------------------|
| `constructed`      | `MutableIntState`      | Number of drag-and-drop managers constructed.           |
| `isRequiredQueries`| `MutableIntState`      | Times Compose queried whether an outbound transfer is required. |
| `requests`         | `MutableIntState`      | Outbound transfer requests received.                    |
| `transfers`        | `MutableIntState`      | Outbound transfers started.                             |
| `lastMessage`      | `MutableState<String?>`| Most recent diagnostic message, or `null`.              |
| `log(msg: String)` | `Unit`                 | Records a diagnostic message.                           |

```kotlin
import androidx.compose.material.Text
import dev.nucleusframework.window.tao.TaoDnDDiagnostics

@Composable
fun DnDStatus() {
    Text("transfers: ${TaoDnDDiagnostics.transfers.intValue}")
    TaoDnDDiagnostics.lastMessage.value?.let { Text(it) }
}
```

## What's next

- [The Tao backend](/docs/tao) — the no-AWT window backend that delivers these events.
- [Multi-touch](/docs/tao/multi-touch) — trackpad gestures on the same backend.
- [Decorated window](/docs/tao/decorated-window) — windows, title bars, and native handles.

---

# Accessibility

URL: https://nucleusframework.dev/en/docs/tao/accessibility

The Tao accessibility bridge projects your Compose semantics tree onto the native accessibility API of each operating system.

The Tao backend exposes your UI to assistive technology by walking Compose's semantics tree
and projecting it onto the native accessibility API of each operating system: NSAccessibility
on macOS, and AccessKit on both Windows (UI Automation provider) and Linux (AT-SPI). From
2.2, Windows and Linux share the same AccessKit wire and decode path. You author accessibility
with standard Compose semantics; the bridge does the projection. The `TaoA11yNode`,
`TaoA11yRole`, `TaoA11yFlag`, and `TaoA11yAction` types in this module describe what the bridge
emits, so you can inspect or assert on the projected tree.

## Add the dependency

The bridge ships inside the Tao backend — there is no separate artifact. Add
`decorated-window-tao` and the projection is installed per window automatically.

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

The public accessibility types live in `dev.nucleusframework.window.tao`.

## Make your UI accessible

You do not build accessibility nodes by hand. Attach Compose semantics to your composables and
the bridge translates them into native accessibility nodes:

```kotlin
import androidx.compose.foundation.Image
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.semantics.contentDescription
import androidx.compose.ui.semantics.semantics

Button(onClick = { count++ }) {
    Text("Increment")
}

Image(
    painter = painterResource("logo.png"),
    contentDescription = "Company logo",
)

Text(
    "Loading",
    modifier = Modifier.semantics { contentDescription = "Loading, please wait" },
)
```

The `Button` is projected as a `TaoA11yRole.Button` node that advertises the
`TaoA11yAction.CLICK` action; the `Image` becomes a `TaoA11yRole.Image` node with its
`contentDescription` as the label. A screen reader reads these directly with no extra wiring.

Nodes marked `InvisibleToUser` or `HideFromAccessibility` in Compose are pruned before
projection, so they never reach the OS accessibility tree.

## How it works

Each decorated window installs a `SemanticsOwnerListener` when it is created. When the
semantics tree changes, the backend walks the `SemanticsOwner`, produces a flat list of
`TaoA11yNode` values, serializes them to a compact binary wire format, and pushes them to the
native side over JNI. Frame coordinates are window-local logical points with a top-left origin,
matching Compose; the native side converts to each platform's coordinate space on demand.

The walk is debounced and gated. When no assistive technology is attached, the backend skips
the walk entirely so scrolling and animation stay smooth; the first query from a screen reader
activates the projection and seeds the tree. On Linux, subsequent updates are sent as partial
snapshots that carry only the changed nodes. On macOS every update is a full snapshot. Windows
uses the AccessKit UIA provider (with live PropertyChanged for out-of-process .NET clients);
updates follow the same AccessKit tree path as Linux.

Actions travel back the other way. When VoiceOver, Narrator, or Orca invokes an action such as
a click, an increment, or a text edit, the native side calls back into the JVM, which resolves
the target node and runs the matching Compose `SemanticsActions` handler on the UI thread. This
is why authoring standard Compose semantics is sufficient — the action set advertised on each
node (`TaoA11yAction`) is derived from the semantics actions you declared.

## API reference

All types are in `dev.nucleusframework.window.tao`.

### Inspect a projected node

`TaoA11yNode` is the descriptor the bridge produces for a single element. It is a `data class`,
so equality drives the partial-update diff on Linux.

```kotlin
data class TaoA11yNode(
    val nodeId: Long,
    val parentId: Long,
    val role: TaoA11yRole,
    val flags: Int,          // bitmask of TaoA11yFlag
    val extraFlags: Int = 0, // bitmask of TaoA11yExtraFlag
    val actions: Int,        // bitmask of TaoA11yAction
    val frameX: Float,
    val frameY: Float,
    val frameW: Float,
    val frameH: Float,
    val minValue: Float = 0f,
    val maxValue: Float = 0f,
    val numericValue: Float = 0f,
    val selectionStart: Int = 0,
    val selectionEnd: Int = 0,
    val hScrollMax: Float = 0f,
    val hScrollValue: Float = 0f,
    val vScrollMax: Float = 0f,
    val vScrollValue: Float = 0f,
    val label: String = "",
    val valueString: String = "",
    val customActions: List<String> = emptyList(),
    val testTag: String = "",
    val children: List<Long> = emptyList(),
)
```

`label` is the accessible name and `valueString` its spoken value. `customActions` holds the
labels of Compose custom accessibility actions, dispatched back by index. `testTag` carries the
Compose `Modifier.testTag(...)` value; it maps to `AXIdentifier` on macOS,
`UIA_AutomationIdPropertyId` on Windows, and AccessKit's author id on Linux, so UI automation
can find widgets by a stable identifier instead of by visible label.

### Identify the node kind

`TaoA11yRole` is the projected element role. Compose roles and node kinds map onto these values.

```kotlin
enum class TaoA11yRole(val code: Int) {
    Unknown, Group, Button, StaticText, Checkbox, RadioButton, Switch,
    TextField, TextArea, Slider, Progress, Image, ScrollArea, Heading,
    Tab, PopupMenu, Table, Outline, Row, Cell, SpinButton, TabPanel, Tooltip,
}
```

### Read node state

`TaoA11yFlag` holds the state bits packed into `TaoA11yNode.flags`. Test them with a bitwise
`and`.

```kotlin
if (node.flags and TaoA11yFlag.CHECKED != 0) { /* the element is checked */ }
```

| Flag | Meaning |
|---|---|
| `IS_ELEMENT` | Node is an accessibility element, not a pure container. |
| `ENABLED` | Element is enabled. |
| `FOCUSED` | Element currently holds accessibility focus. |
| `SELECTED` | Element is selected. |
| `CHECKED` | Toggle/checkbox is on. |
| `MIXED` | Toggle is in the indeterminate state. |
| `HEADING` | Element is a heading. |
| `PASSWORD` | Text field is a password field. |
| `MULTILINE` | Text field accepts multiple lines. |
| `MODAL` | Container is modal. |
| `LIVE_REGION_POLITE` | Live region announced politely. |
| `LIVE_REGION_ASSERTIVE` | Live region announced assertively. |
| `MULTI_SELECTABLE` | Container allows multiple selection (Linux/AT-SPI only). |
| `EXPANDED_TRUE` | Expandable element is expanded (Linux/AT-SPI only). |
| `EXPANDED_FALSE` | Expandable element is collapsed (Linux/AT-SPI only). |
| `HIDDEN` | Reserved; not currently emitted. |

`TaoA11yExtraFlag` carries additional bits in `TaoA11yNode.extraFlags`.

| Flag | Meaning |
|---|---|
| `READ_ONLY` | Text field is read-only; the `SET_TEXT` action is dropped. |
| `INVALID` | Form field holds an invalid value. |

### Check supported actions

`TaoA11yAction` holds the action bits packed into `TaoA11yNode.actions`. Each bit corresponds to
a Compose semantics action the element declared, and to the callback the native side may invoke.

```kotlin
if (node.actions and TaoA11yAction.CLICK != 0) { /* the element can be activated */ }
```

| Action | Triggered by |
|---|---|
| `CLICK` | Activating the element. |
| `INCREMENT` | Stepping a slider or spin button up. |
| `DECREMENT` | Stepping a slider or spin button down. |
| `SET_TEXT` | Replacing the text of an editable field. |
| `REQUEST_FOCUS` | Moving accessibility focus to the element. |
| `SCROLL_UP` | Scrolling the region up. |
| `SCROLL_DOWN` | Scrolling the region down. |
| `SCROLL_LEFT` | Scrolling the region left. |
| `SCROLL_RIGHT` | Scrolling the region right. |
| `DISMISS` | Dismissing a popup or dialog. |

## What's next

- [Decorated window](/docs/tao/decorated-window) — the Tao window and its title bar.
- [The Tao backend](/docs/tao) — what the Tao backend provides.
- [Wayland](/docs/tao/wayland) — Linux windowing behavior, where AT-SPI is bridged through AccessKit.

---

# Native Wayland

URL: https://nucleusframework.dev/en/docs/tao/wayland

The Tao backend renders Compose Desktop apps directly on Wayland and falls back to X11 automatically.

On Linux, the Tao backend renders Compose Desktop apps directly on Wayland through native Wayland
protocols, rather than through the XWayland compatibility layer. When no Wayland session is
available, it falls back to X11 without any code change. This page covers what the Wayland path
supports, how it works, and how to read the current session from Kotlin.

## Add the dependency

Wayland support ships with the Tao backend. There is no separate artifact.

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

## Detect the session

You rarely branch on the session type — the same Compose code runs on Wayland and X11. Detection is
useful for diagnostics and feature gates, since taskbar progress, badges, and global hotkeys behave
differently per session.

```kotlin
import dev.nucleusframework.core.runtime.LinuxDesktopEnvironment
import dev.nucleusframework.core.runtime.Platform

val onWayland = Platform.isWayland
val desktopEnv = if (Platform.Current == Platform.Linux) LinuxDesktopEnvironment.Current else null
```

## How it works

Tao binds the standard Wayland protocols at startup: `xdg-shell` for windows, `xdg-decoration` to
negotiate server- or client-side decorations, `wp_fractional_scale_v1` for sub-integer scale
factors, `pointer-gestures-unstable-v1` for pinch and swipe, and `wp_tablet_v2` for stylus input.
Skiko renders to an EGL surface attached to the window's `wl_surface`.

When the compositor signals a scale change — for example, when you drag a window from a 1.0 monitor
to a 1.5 monitor — Tao reconfigures the EGL surface and emits a density change to Compose. Your `Dp`
values stay logical and the rendered output stays crisp. See [Per-monitor HiDPI](/docs/tao/hidpi)
for the details.

On an X11 session, or on a Wayland compositor that refuses XDG decorations, Tao falls back to X11
automatically. The Compose code does not change.

## Wayland and X11 differences

| Concern              | Wayland (Tao)                      | X11 (fallback)                   |
|----------------------|------------------------------------|----------------------------------|
| Fractional scaling   | Native, per-output                 | Whole-pixel only                 |
| Window placement     | Compositor-controlled              | Client can set absolute position |
| Global hotkeys       | Compositor-mediated (`xdg-portal`) | `XGrabKey`                       |
| Screen capture       | Portal only                        | Direct                           |
| Pen pressure         | `wp_tablet_v2`                      | Not exposed                      |
| Multi-touch gestures | `pointer-gestures-unstable-v1`     | Limited                          |
| Clipboard            | `wl_data_device` on the window's seat | `CLIPBOARD` selection          |
| Window stacking      | No client-side protocol            | `_NET_WM_STATE_ABOVE` / `BELOW`  |

## Copy and paste

On Linux, Tao reads and writes the clipboard through GDK rather than AWT. AWT's clipboard is
X11-only, so in a Wayland-native window it pasted nothing — the Wayland selection reaches
XWayland only while an X11 window is active — and it threw outright in a session with no
XWayland at all.

Use the standard Compose API; there is nothing Nucleus-specific to call:

```kotlin
import androidx.compose.ui.platform.LocalClipboard

val clipboard = LocalClipboard.current
val scope = rememberCoroutineScope()

scope.launch { clipboard.setClipEntry(entry) }
```

Plain text, images, and file lists are carried in both directions. Images cross as PNG, and file
lists as `text/uri-list` plus the GNOME copied-files target, so pasting into a file manager works.
HTML is not carried in either direction, and only the `CLIPBOARD` selection is used — never
X11's PRIMARY (middle-click) selection.

## Notes

On Wayland you cannot set absolute screen coordinates — the compositor owns window placement.
`WindowState.position` is treated as a hint by some compositors and ignored by others (GNOME ignores
client-requested positions). Design around `Center` or `PlatformDefault`, and persist the last size
rather than the last position.

## API reference

- `Platform.isWayland` — `true` on a Linux session when `XDG_SESSION_TYPE` is `wayland` or
  `WAYLAND_DISPLAY` is set.
- `Platform.Current` — one of `Linux`, `Windows`, `MacOS`, or `Unknown`.
- `LinuxDesktopEnvironment.Current` — one of `Gnome`, `KDE`, `XFCE`, `Cinnamon`, `Mate`, or
  `Unknown`.

## What's next

- [Per-monitor HiDPI](/docs/tao/hidpi) — how fractional scaling maps to Compose density.
- [Multi-touch and gestures](/docs/tao/multi-touch) — pinch, swipe, and rotate on Wayland.
- [Pen and stylus](/docs/tao/pen-stylus) — pressure and tilt through `wp_tablet_v2`.

---

# Per-monitor HiDPI

URL: https://nucleusframework.dev/en/docs/tao/hidpi

The Tao backend tracks a per-window scale factor so Compose layouts stay in Dp while rendering matches each display's pixel density.

The Tao backend tracks the scale factor of each window's current display and reconfigures its render surface when that factor changes. Your Compose layout stays in `Dp`; only the rasterized output changes to match the display's pixel density. Per-monitor HiDPI is part of `decorated-window-tao` and needs no extra setup.

## Read the current density

Read `LocalDensity` inside any composable to get the scale factor of the window it renders in:

```kotlin
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.platform.LocalDensity

@Composable
fun ShowDensity() {
    val density = LocalDensity.current
    Text("Scale: ${density.density}x · font scale: ${density.fontScale}")
}
```

The value updates automatically when the window moves to a display with a different scale factor.

## How it works

When you open a `DecoratedWindow` on Tao, the backend queries the active display for its scale factor and configures the Skiko surface accordingly: `CAMetalLayer.contentsScale` on macOS, an ANGLE GL surface resize at the new scale on Windows, and the EGL buffer scale on Wayland.

The native window receives a `ScaleFactorChanged` event whenever you drag it between displays, plug in an external monitor, or change the system scale. Tao forwards that event to the `ComposeScene`, which propagates a new `LocalDensity` to your composables.

The result: a `Modifier.size(48.dp)` occupies 48 device pixels on a 1.0 display, 96 device pixels on a 2.0 display, and 72 device pixels on a 1.5 fractional Wayland output. The layout does not change — only the rasterized output does.

## linux-hidpi and the AWT backends

The `linux-hidpi` module reads a single global scale from the desktop environment (GSettings, Mutter, `GDK_SCALE`, or `Xft.dpi`) and applies it to JVM properties before AWT initializes, through `applyLinuxHiDpiScale()`. It sets one scale at startup and does not react to per-window changes.

The Tao backend does not use that helper — it observes per-window scale changes at runtime. When you migrate from the AWT backends to Tao on Linux, you can drop the `linux-hidpi` dependency.

Keep `linux-hidpi` only for sessions where you still run the AWT (JBR or JNI) backends.

## API reference

- `LocalDensity.current` — the Compose density of the window the composable renders in.
- `Platform.isWayland` — `true` on a Wayland session, where fractional scaling is per-monitor; `false` on X11.
- `WindowState` — hold window sizes in `Dp`, never in pixels, so they survive a scale change.

## Notes

- On Windows 10 1607 and later, Tao declares Per-Monitor V2 DPI awareness through the application manifest. The Nucleus Gradle plugin writes that manifest for packaged builds. Popups and `DecoratedDialog` pick up the target monitor's DPI and work-area constraints when they open on a different display from the owner.
- On macOS, Retina backing stores are configured automatically.
- Fractional scaling on KDE Plasma works on both X11 and Wayland, but only Wayland reports per-monitor accuracy.

## What's next

- [Tao backend](/docs/tao) — the no-AWT native windowing backend.
- [Wayland](/docs/tao/wayland) — session detection and Wayland-specific behavior.
- [Decorated window](/docs/tao/decorated-window) — the window you render your UI into.

---

# Taskbar progress

URL: https://nucleusframework.dev/en/docs/tao/taskbar-progress

Show determinate, indeterminate, and error progress on the taskbar or dock from a Tao window.

`taskbar-progress-tao` bridges the platform-neutral `TaskbarProgress` API to the Tao backend so a `TaoWindow` can drive its taskbar button (Windows), dock icon (macOS), or launcher entry (Linux). It adds a composable handle bound to the current Tao window and a backend-agnostic façade that works whether your app runs on the Tao or AWT backend.

Use this module when you build against the Tao backend and want to reflect a long-running operation — a download, an export, a build — in the OS taskbar.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.taskbar-progress-tao:<version>")
}
```

The module depends on `taskbar-progress` and `decorated-window-tao`, so both are pulled in transitively.

## Show progress from a composable

Inside a Tao `DecoratedWindow` content lambda, call `rememberTaoTaskbarProgress()` to get a handle bound to the current window, then drive it from your state:

```kotlin
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import dev.nucleusframework.taskbarprogress.tao.rememberTaoTaskbarProgress

// Inside DecoratedWindow { ... }
var progress by remember { mutableStateOf(0.0) }
val taskbar = rememberTaoTaskbarProgress()

LaunchedEffect(progress) {
    taskbar?.showProgress(progress)
    if (progress >= 1.0) taskbar?.hideProgress()
}
```

`rememberTaoTaskbarProgress()` returns a `TaoTaskbarProgressScope?`. It is `null` when called outside a Tao `DecoratedWindow`, so guard the calls with `?.`. The `value` passed to `showProgress` and `setProgress` is a fraction in the `0.0..1.0` range.

Progress is a visual hint. `isAvailable()` reports `false` on platforms or environments without taskbar-progress support (for example, a Linux desktop that exposes no matching `.desktop` file), and the calls become no-ops.

## How it works

`TaoTaskbarProgress` resolves the native window handle from the `TaoWindow` before each call. On Windows it reads the HWND from `TaoWindow.nativeHandle`. On macOS the dock icon is application-wide and on Linux the launcher entry is keyed by the `.desktop` filename, so the window argument is not used on those platforms and the call delegates straight to the matching platform branch.

`rememberTaoTaskbarProgress()` reads `LocalTaoWindow` and remembers a `TaoTaskbarProgressScope` keyed to that window. The scope is a thin wrapper: each of its methods forwards to `TaoTaskbarProgress` with the bound window, so you never pass the window explicitly.

`NucleusTaskbarProgress` is the backend-agnostic entry point. It takes a `NucleusWindow` and dispatches to the AWT `TaskbarProgress` or to `TaoTaskbarProgress` depending on how the window is backed, which lets a project switch backends without touching call sites. Every call is offloaded to a dedicated daemon thread, because the underlying Windows API can block the caller if invoked while the owning event loop is shutting down. As a result the returned `Boolean` reports best-effort dispatch (queued or not possible), not completion.

## API reference

### Check availability

```kotlin
TaoTaskbarProgress.isAvailable(): Boolean
```

Returns `true` when the current platform supports taskbar progress. Check it once before wiring up progress if you want to skip the work entirely on unsupported systems.

### Show determinate progress

From a `TaoTaskbarProgressScope`:

```kotlin
scope.showProgress(value: Double)   // sets NORMAL state, then the value
scope.setProgress(value: Double)    // updates the value only
scope.setState(state: TaskbarProgress.State)
```

`showProgress` sets the state to `NORMAL` and applies the fraction in one call. Use `setProgress` to update the value while the state stays the same. `TaskbarProgress.State` has `NO_PROGRESS`, `INDETERMINATE`, `NORMAL`, `ERROR`, and `PAUSED`.

### Signal indeterminate, error, or paused

```kotlin
scope.showIndeterminate()           // pulsing bar, no fixed value
scope.showError(value: Double = 1.0)
scope.showPaused(value: Double = 1.0)
```

`showIndeterminate` shows a pulsing bar for work with no measurable fraction. `showError` and `showPaused` set the matching state and a full bar by default; pass a `value` to keep the current fraction visible.

### Clear progress

```kotlin
scope.hideProgress()                // sets NO_PROGRESS
```

Call this when the operation finishes to remove the overlay.

### Request user attention

```kotlin
scope.requestAttention(type: TaskbarProgress.AttentionType = TaskbarProgress.AttentionType.INFORMATIONAL)
scope.stopAttention()
```

`requestAttention` flashes the taskbar button on Windows or bounces the dock icon on macOS. `AttentionType` is `INFORMATIONAL` (a brief flash or single bounce) or `CRITICAL` (flash or bounce until the app gets focus). `stopAttention` cancels an ongoing request.

### Drive progress without a composable

When you hold a `TaoWindow` directly, call the `TaoTaskbarProgress` object and pass the window:

```kotlin
TaoTaskbarProgress.showProgress(window, 0.5)
TaoTaskbarProgress.hideProgress(window)
```

The object exposes the same operations as the scope: `setProgress`, `setState`, `showProgress`, `showError`, `showIndeterminate`, `showPaused`, `hideProgress`, `requestAttention`, and `stopAttention`.

### Stay backend-agnostic

If your code works with a `NucleusWindow` and should run on either backend, use `NucleusTaskbarProgress` or its `NucleusWindow` extensions:

```kotlin
import dev.nucleusframework.taskbarprogress.tao.showTaskbarProgress
import dev.nucleusframework.taskbarprogress.tao.hideTaskbarProgress

nucleusWindow.showTaskbarProgress(0.5)
nucleusWindow.hideTaskbarProgress()
```

The extensions mirror the scope: `setTaskbarProgress`, `setTaskbarState`, `showTaskbarProgress`, `showTaskbarError`, `showTaskbarIndeterminate`, `showTaskbarPaused`, `hideTaskbarProgress`, `requestTaskbarAttention`, and `stopTaskbarAttention`. Each returns a `Boolean` reporting best-effort dispatch, not completion.

## What's next

- [Taskbar progress (AWT)](/docs/lifecycle/taskbar-progress) — the platform-neutral `TaskbarProgress` API and the AWT backend.
- [The Tao backend](/docs/tao) — the no-AWT Rust window backend and its window model.
- [Decorated windows on Tao](/docs/tao/decorated-window) — the `DecoratedWindow` that provides `LocalTaoWindow`.

---

# Migrate from JBR to Tao

URL: https://nucleusframework.dev/en/docs/tao/migration-from-jbr

Switch an existing Nucleus app from the AWT backend to the Tao backend and retest the platform integrations that change.

In this tutorial, you'll move an existing Nucleus app from the AWT backend
(`decorated-window-jbr` or `decorated-window-jni`) to the Tao backend
(`decorated-window-tao`). The `DecoratedWindow` and `TitleBar` APIs are identical on both
backends, so the move is a dependency swap and a backend flag. The rest of the tutorial
covers the integrations you need to retest afterward.

On the same machine, running the same app as a GraalVM native image, moving from the AWT
backend to Tao measurably cuts both startup time and memory:

- **Startup** (launch → first window): **~0.7 s → ~0.12 s**, roughly **6× faster**.
- **RAM** (private working set, idle with window open): **~155 MB → ~100 MB**, about **35% lower**.

Tao drops the AWT/Swing window hierarchy and its native libraries entirely — that is what
removes the startup and memory overhead. Figures are from an internal Nucleus app; your
results vary with app size and platform.

## Before you start

- An existing app that runs on `NucleusBackend.Awt`, using `decorated-window-jbr` or
  `decorated-window-jni`.
- JDK 17 or later.
- Familiarity with the [backend concept](/docs/concepts/backends): a Nucleus app ships
  exactly one window runtime module, and `NucleusBackend` selects it.

## Swap the dependency

Replace the AWT window runtime with `decorated-window-tao`. Keep the
`nucleus.nucleus-application` entry point unchanged.

**Before (AWT)**

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-jbr:<version>")
}
```

**After (Tao)**

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

## Switch the backend flag

Pass `backend = NucleusBackend.Tao` to `nucleusApplication`. The window content stays
identical.

**Before (AWT)**

```kotlin
nucleusApplication {
    DecoratedWindow(onCloseRequest = ::exitApplication, title = "MyApp") {
        TitleBar { state -> /* … */ }
        MyContent()
    }
}
```

**After (Tao)**

```kotlin
nucleusApplication(backend = NucleusBackend.Tao) {
    DecoratedWindow(onCloseRequest = ::exitApplication, title = "MyApp") {
        TitleBar { state -> /* … */ }
        MyContent()
    }
}
```

`NucleusBackend.Auto` (the default) picks Tao when `decorated-window-tao` is on the
classpath and falls back to the AWT backend otherwise. Set the flag explicitly to pin the
choice per build.

## Retest the platform integrations

The APIs above are stable across backends, but the code paths underneath change. Retest
each of these after the swap:

- **Drag-and-drop.** Payloads arrive as `TaoDragAndDropPayload` instead of an AWT
  `TransferHandler`. Rewrite any handler that reads AWT transfer data.
- **Deep links.** Register with `onDeepLink { uri -> … }` as before — the callback API is
  unchanged, only the bridge behind it differs (`TaoDeepLinkBridge` on Tao).
- **File dialogs.** Tao has no AWT, so any direct `JFileChooser` call stops working. Switch
  to a native file dialog library such as FileKit — see
  [Native file dialogs](/docs/ecosystem/file-dialog), which runs on both backends.
- **Native views.** Embedded AWT `Canvas` instances no longer work under Tao. Compose
  Desktop's `SwingPanel` also stops working and crashes the app at runtime, since Tao never
  creates the AWT/Swing window hierarchy it needs. Embed native content with `NativeView`
  instead.
- **Window placement on Linux.** Wayland compositors may ignore absolute positions. See
  [Wayland](/docs/tao/wayland).
- **Multi-window flows.** These are unchanged: one `nucleusApplication { }` block with one
  `DecoratedWindow` call per window, each exposing its own `NucleusWindow`.

## Compare the backends

| Concern                | AWT (JBR / JNI)                     | Tao                                   |
|------------------------|-------------------------------------|---------------------------------------|
| Startup (native image) | ~0.7 s to first window              | ~0.12 s to first window (~6× faster)  |
| RAM (idle, window open)| ~155 MB private working set         | ~100 MB private working set (~35% lower) |
| Underlying window      | `ComposeWindow` (extends `JFrame`)  | `TaoWindow` (native handle)           |
| Event dispatch         | AWT EDT                             | Tao event loop on the main thread     |
| `unsafe` accessor      | `unsafe.awtWindow`                  | `unsafe.taoWindow`                    |
| Native file dialogs    | AWT / Swing                         | [FileKit](/docs/ecosystem/file-dialog) (xdg portals / native panels) |
| Drag-and-drop          | AWT `TransferHandler`               | `TaoDragAndDropPayload`               |
| Deep links             | AWT / AppKit                        | `TaoDeepLinkBridge` (same `onDeepLink` API) |
| Native embedding       | AWT `Canvas`                        | `NativeView`                          |
| Wayland                | XWayland                            | Native                                |
| macOS main thread      | Not required                        | Requires `-XstartOnFirstThread`       |

## Decide whether to keep JBR

Stay on the AWT backend when your app:

- ships a Swing-based module,
- embeds an AWT `Canvas` you have not ported to `NativeView` yet, or
- depends on a library that needs `ComposeWindow` directly.

Nucleus publishes `decorated-window-jbr`, `decorated-window-jni`, and
`decorated-window-tao` from the same version, so you can defer the switch and pin the
backend per build with `NucleusBackend.Awt` or `NucleusBackend.Tao`.

## What's next

- [Backends](/docs/concepts/backends) — how `NucleusBackend` selects the window runtime.
- [Decorated window](/docs/tao/decorated-window) — the `DecoratedWindow` and `TitleBar` APIs on Tao.
- [Native file dialogs](/docs/ecosystem/file-dialog) — file pickers that run without AWT.
- [Wayland](/docs/tao/wayland) — Linux window placement and compositor behavior.

---

# Window & toolkits

URL: https://nucleusframework.dev/en/docs/window

How Nucleus opens native desktop windows from Compose through the DecoratedWindow composable, the TitleBar slot, and the toolkit modules that restyle them.

Nucleus opens native desktop windows from Compose through a single composable, `DecoratedWindow`.
It draws the OS window frame, gives you a `TitleBar` slot you fill with Compose content, and hands
back a `NucleusWindow` handle that behaves the same whether the Tao backend or the deprecated
AWT backend runs underneath.

This section covers the windowing entry point and the toolkit modules that change how it looks.

## The DecoratedWindow composable

`DecoratedWindow` lives in `nucleus-application`. You pair it with one backend module and call it
from inside `nucleusApplication { }`:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
}
```

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.rememberWindowState
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.nucleusApplication

fun main() = nucleusApplication {
    val state = rememberWindowState(size = DpSize(1100.dp, 720.dp))

    DecoratedWindow(
        onCloseRequest = ::exitApplication,
        state = state,
        title = "Sample",
        minimumSize = DpSize(640.dp, 480.dp),
    ) {
        TitleBar { _ ->
            Text("My App", Modifier.padding(8.dp))
        }
        Box(Modifier.fillMaxSize()) { /* app content */ }
    }
}
```

Each call to `DecoratedWindow` manages its own state, handle, and close request, so you open a
second window by calling it again. There are two overloads: one on `NucleusApplicationScope`, and
a receiverless top-level one that resolves the scope from `LocalNucleusApplicationScope` — use
that to open a window from a navigation destination or a row action, without threading the
receiver through.

Beyond the Compose Desktop parameters, `DecoratedWindow` takes the Nucleus window flags:
`undecorated`, `popupFor`, `nativePopupLayers`, `hiddenFromDock`,
[`nativeContextMenu`](/docs/window/context-menu#turn-on-the-native-menu), and the overlay flags
`transparent`, `clickThrough`, `visibleOnAllWorkspaces`, `forceX11` and `alwaysOnBottom`. See
[DecoratedWindow parameters](/docs/tao/decorated-window#decoratedwindow-parameters) and
[Overlay windows](/docs/tao/overlay-windows).

## The title bar slot

Inside the content lambda, `TitleBar` is a Compose composable rather than a native widget. Its
content lambda receives the current `DecoratedWindowState`, so you can react to focus and maximized
state, and place buttons, a search field, or any other content across the bar:

```kotlin
TitleBar { state ->
    Text(if (state.isActive) "My App" else "My App (inactive)")
}
```

`DecoratedDialog` is the dialog counterpart and pairs with `DialogTitleBar` for modal or detached
panels.

For full-window layouts, custom design-system chrome, macOS glass regions, or Windows 11 Mica /
Acrylic, use [`WindowScaffold`](/docs/tao/window-scaffold) on the Tao backend. Existing `TitleBar`
call sites stay valid; the scaffold is additive.

## The window handle

The content lambda runs in a `NucleusDecoratedWindowScope`, which carries a `nucleusWindow` handle.
Use it to read window state, observe changes, and drive the window without touching the native
object:

```kotlin
DecoratedWindow(onCloseRequest = ::exitApplication, title = "Editor") {
    TitleBar { _ -> Text("Editor") }

    val focused by nucleusWindow.focusFlow.collectAsState()

    Button(onClick = { nucleusWindow.setMaximized(true) }) {
        Text(if (focused) "Maximize" else "(unfocused)")
    }
}
```

`NucleusWindow` exposes the intersection of `ComposeWindow` (deprecated AWT backend) and
`TaoWindow` (Tao): the boolean
properties `isFocused`, `isMinimized`, `isMaximized`, and `isFullscreen`; a matching `StateFlow` for
each; `boundsOnScreen()`; and imperative calls such as `setMaximized`, `setMinimumSize`, `toFront`,
and `close`. The same handle is available anywhere in the tree through `LocalNucleusWindow`.

When you need the underlying native object, `nucleusWindow.unsafe` is the escape hatch. The accessor
matching the active backend returns a value; the others return `null`:

```kotlin
interface NucleusWindowUnsafe {
    val awtWindow: ComposeWindow?   // null on Tao
    val awtDialog: ComposeDialog?
    val taoWindow: TaoWindow?       // null on AWT
    val taoHandle: Long?
}
```

## Styling and toolkits

The visual style — title bar height, colors, button icons — lives in `TitleBarStyle` and
`DecoratedWindowStyle` in `decorated-window-core`. Wrap your app in `NucleusDecoratedWindowTheme`
to apply a style directly, or add a toolkit module for a ready-made native look. The composable you
call stays the same; only the theme changes.

Native design systems are available today: [macOS 26](/docs/window/toolkit-macos),
[Fluent](/docs/window/toolkit-fluent), and [Yaru](/docs/window/toolkit-yaru) ship as separate Maven
artifacts with Nucleus-backed windows; Jewel and Material adapters live in this repository. See
[Toolkits](/docs/window/toolkits).

## Backends

`nucleusApplication { }` detects the active backend — Tao when `decorated-window-tao` is on the
classpath, otherwise the deprecated AWT backend — and sets up the platform integrations before
running your windows. `LocalNucleusBackend` reports the resolved value, one of
`NucleusBackend.Auto`, `.Awt`, or `.Tao`. Because `nucleusWindow` mirrors both backends, the same
window code runs on either.

`nucleusApplication` acquires a single-instance lock by default. Pass `enableSingleInstance = false`
to allow multiple processes.

## What's next

- [Toolkits](/docs/window/toolkits) — change the window's look with a prebuilt native theme.
- [Window scaffold and chrome](/docs/tao/window-scaffold) — full-window layouts, drag areas, materials.
- [The Tao backend](/docs/tao/decorated-window) — the no-AWT windowing backend in detail.
- [Backends](/docs/concepts/backends) — Tao and the deprecated AWT backend.

---

# Native design systems

URL: https://nucleusframework.dev/en/docs/window/toolkits

macOS 26, Fluent, Yaru, Jewel and Material restyle the same Nucleus window for each desktop design language.

Nucleus opens the OS window; design systems style the chrome and the widgets. macOS 26, Fluent
and Yaru ship as separate open-source Compose Multiplatform libraries on Maven Central, each with
a Nucleus-backed decorated window for desktop. Jewel and Material adapters stay inside the
Nucleus repository.

## The toolkits

| Toolkit | Native to | Artifacts / module | Status |
|---------|-----------|--------------------|--------|
| [macOS 26](https://github.com/NucleusFramework/compose-macos-26-ui) | macOS Tahoe | `dev.nucleusframework:compose-macos-ui` | Available (v1.0.0) |
| [Fluent](https://github.com/NucleusFramework/compose-fluent-ui) | Windows 11 | `dev.nucleusframework.composefluent:fluent` + `decorated-window-fluent` | Available (v1.0.0) |
| [Yaru](https://github.com/NucleusFramework/yaru-compose-ui) | Ubuntu / GNOME | `dev.nucleusframework.yarucompose:yaru` + `yaru-decorated-window` | Available (v1.0.1) |
| Jewel | Cross-platform | `nucleus.decorated-window-jewel` | Available (with Nucleus) |
| Material 2 | Fallback | `nucleus.decorated-window-material2` | Available (with Nucleus) |
| Material 3 | Fallback | `nucleus.decorated-window-material3` | Available (with Nucleus) |

The three design-system repos version **independently** of Nucleus. Pin them separately; they
depend on Nucleus 2.2+ for the Tao window on desktop.

Live galleries:

- [compose-macos-26-ui](https://nucleusframework.github.io/compose-macos-26-ui/)
- [compose-fluent-ui](https://nucleusframework.github.io/compose-fluent-ui/)
- [yaru-compose-ui](https://nucleusframework.github.io/yaru-compose-ui/)

## Choose a toolkit

**macOS 26**

```kotlin title="build.gradle.kts"
plugins {
    id("dev.nucleusframework")
}
dependencies {
    implementation("dev.nucleusframework:compose-macos-ui:1.0.0")
}
```

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.macoscompose.window.MacosDecoratedWindow

fun main() = nucleusApplication {
    MacosDecoratedWindow(onCloseRequest = ::exitApplication, title = "Mail") {
        // MacosTheme + components live inside the window content
        App()
    }
}
```

See the [macOS 26 toolkit](/docs/window/toolkit-macos) page and the
[repo README](https://github.com/NucleusFramework/compose-macos-26-ui).

**Fluent**

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework.composefluent:fluent:1.0.0")
    implementation("dev.nucleusframework.composefluent:decorated-window-fluent:1.0.0")
}
```

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.fluent.FluentDecoratedWindow
import dev.nucleusframework.window.fluent.FluentTitleBar
import io.github.composefluent.FluentTheme

fun main() = nucleusApplication {
    FluentTheme {
        FluentDecoratedWindow(onCloseRequest = ::exitApplication, title = "Settings") {
            FluentTitleBar { /* … */ }
            App()
        }
    }
}
```

See the [Fluent toolkit](/docs/window/toolkit-fluent) page and
[compose-fluent-ui](https://github.com/NucleusFramework/compose-fluent-ui).

**Yaru**

```kotlin title="build.gradle.kts"
dependencies {
    // Pulls yaru + Nucleus Tao transitively.
    implementation("dev.nucleusframework.yarucompose:yaru-decorated-window:1.0.1")
}
```

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.yarucompose.window.YaruDecoratedWindow

fun main() = nucleusApplication {
    YaruDecoratedWindow(onCloseRequest = ::exitApplication, title = "Settings") {
        // YaruTheme must be inside the window content
        App()
    }
}
```

See the [Yaru toolkit](/docs/window/toolkit-yaru) page and
[yaru-compose-ui](https://github.com/NucleusFramework/yaru-compose-ui).

**Jewel**

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-jewel:<version>")
}
```

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.darkmodedetector.isSystemInDarkMode
import dev.nucleusframework.window.jewel.JewelDecoratedWindow
import dev.nucleusframework.window.jewel.JewelTitleBar
import org.jetbrains.jewel.intui.standalone.theme.IntUiTheme

fun main() = nucleusApplication {
    IntUiTheme(isDark = isSystemInDarkMode()) {
        JewelDecoratedWindow(onCloseRequest = ::exitApplication, title = "Tools") {
            JewelTitleBar { state -> /* … */ }
            MyContent()
        }
    }
}
```

**Material 3**

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-material3:<version>")
}
```

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.material.MaterialDecoratedWindow
import dev.nucleusframework.window.material.MaterialTitleBar

fun main() = nucleusApplication {
    MaterialDecoratedWindow(onCloseRequest = ::exitApplication, title = "App") {
        MaterialTitleBar { state -> /* … */ }
        MyContent()
    }
}
```

## How it works

macOS, Fluent and Yaru are **full design systems** (widgets, theme, icons) plus an optional
desktop window module that wraps Nucleus `DecoratedWindow` / Tao. Jewel and Material in this
repo are **window chrome adapters** only — you still pick the widget library yourself.

Where the theme goes depends on the pack. Fluent, Jewel and Material derive the window chrome
from the **ambient** theme, so wrap the window call — `FluentTheme { FluentDecoratedWindow { … } }`
— and they re-provide the theme inside the content themselves. `JewelDecoratedWindow` reads
`JewelTheme.globalColors` and throws without a provider. The macOS 26 and Yaru wrappers take
their theme **inside** the window content instead.

For full-window layouts and custom chrome without a design-system pack, use
[`WindowScaffold`](/docs/tao/window-scaffold) on Tao.

## What's next

- [macOS 26 toolkit](/docs/window/toolkit-macos)
- [Fluent toolkit](/docs/window/toolkit-fluent)
- [Yaru toolkit](/docs/window/toolkit-yaru)
- [Jewel for tooling](/docs/window/toolkit-jewel)
- [Material 2 / 3](/docs/window/toolkit-material)
- [Window scaffold](/docs/tao/window-scaffold)

---

# Context menus

URL: https://nucleusframework.dev/en/docs/window/context-menu

Replace Compose-drawn context menus with the OS-looking menu — NSMenu on macOS, a Fluent flyout on Windows, and Adwaita or Breeze on Linux.

By default, Compose Desktop draws its own context menus, which do not match the desktop they run
on. Nucleus can replace them with the platform menu: a real `NSMenu` on macOS, and a Compose
flyout styled as Fluent on Windows, Adwaita on GTK desktops, or Breeze on Qt desktops. This page
covers the opt-in, the item types, and how items reach the menu.

## Turn on the native menu

Set `nativeContextMenu` on the window:

```kotlin
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.nucleusApplication

fun main() = nucleusApplication {
    DecoratedWindow(
        onCloseRequest = ::exitApplication,
        title = "MyApp",
        nativeContextMenu = true,
    ) {
        // Text fields now show the OS-looking Cut/Copy/Paste menu
    }
}
```

This covers `ContextMenuArea`, the text-field Cut/Copy/Paste menu, and
[spellcheck suggestions](/docs/os/spell-check). The parameter is also available on `HostedWindow`.

The native menu is a [Tao backend](/docs/tao) feature. On the AWT backends the parameter is
accepted and ignored, so the same code keeps Compose menus there.

You do not choose a style. The menu follows the platform, and on Linux it follows the session's
toolkit — Breeze on Qt desktops, Adwaita everywhere else.

## Add your own items

Build items with `NucleusContextMenuItem`, which extends Compose's `ContextMenuItem` with an icon
and a shortcut label:

```kotlin
import androidx.compose.foundation.ContextMenuArea
import androidx.compose.foundation.ContextMenuItem
import dev.nucleusframework.application.contextmenu.ContextMenuIcon
import dev.nucleusframework.application.contextmenu.NucleusContextMenuDivider
import dev.nucleusframework.application.contextmenu.NucleusContextMenuItem

ContextMenuArea(
    items = {
        listOf(
            NucleusContextMenuItem(
                label = "Reveal in Finder",
                icon = ContextMenuIcon.Folder,
                onClick = { revealInFileManager(path) },
            ),
            NucleusContextMenuDivider,
            NucleusContextMenuItem(
                label = "Delete",
                icon = ContextMenuIcon.Delete,
                shortcut = "Del",
                onClick = { delete(path) },
            ),
        )
    },
) {
    FileRow(path)
}
```

`NucleusContextMenuDivider` is the separator, and `NucleusContextMenuSubmenu` nests a group. Its
`items` lambda is evaluated when the menu opens, so a submenu can list something that changes:

```kotlin
import dev.nucleusframework.application.contextmenu.NucleusContextMenuSubmenu

NucleusContextMenuSubmenu(label = "Open recent") { recentFiles.map { fileItem(it) } }
```

## Show keyboard shortcuts

An item with a stock icon gets the platform shortcut label for free — `⌘C` on macOS, `Ctrl+C`
elsewhere:

```kotlin
NucleusContextMenuItem(label = "Copy", icon = ContextMenuIcon.Copy, onClick = ::copy)
```

Pass `shortcut` to override the label, or `shortcut = ""` to suppress the stock one.
`ContextMenuIcon.stockShortcut()` returns the label used for a given icon.

Shortcut labels are drawn by the Windows and Linux flyouts. macOS `NSMenu` does not render this
field yet.

## Detect the Linux toolkit

The Linux menu style is picked from the session, which you can also read yourself — for example
to match an unrelated widget to the desktop:

```kotlin
import dev.nucleusframework.core.runtime.LinuxUiToolkit

when (LinuxUiToolkit.Current) {
    LinuxUiToolkit.Qt -> // KDE Plasma, LXQt, Deepin, …
    LinuxUiToolkit.Gtk -> // GNOME, Xfce, Cinnamon, MATE, …
}
```

`LinuxUiToolkit.Current` reads `XDG_CURRENT_DESKTOP`, `DESKTOP_SESSION`, and
`XDG_SESSION_DESKTOP`, then falls back to `KDE_FULL_SESSION` and `QT_QPA_PLATFORMTHEME`. Unknown
desktops and bare tiling window managers resolve to `Gtk`.

## How it works

Turning on `nativeContextMenu` installs two Compose representations for the window subtree:
`NativeContextMenuRepresentation` for `ContextMenuArea`, and `NativeTextContextMenu` for text
fields. Both walk the `ContextMenuItem` list Compose hands them and convert it to a
`ContextMenuEntry` tree through the `ContextMenuItemInterpreter` in scope.

That tree is then rendered per platform. macOS builds a real `NSMenu` through
[`menu-macos`](/docs/os/menu-macos) and pops it up; Windows and Linux draw a Compose flyout at OS
density, so the menu keeps system scale even inside a subtree that overrides `LocalDensity`.

Items arrive from independent contributors — the field's own Cut/Copy/Paste, your extras, the
spellcheck suggestions — so the entry list is normalized before it is shown: leading, trailing,
and consecutive separators are dropped, recursively into submenus. An empty list closes the menu
instead of flashing an empty frame.

## API reference

Package `dev.nucleusframework.application.contextmenu`, shipped in `nucleus-application`.

### Build items

| Symbol | Description |
|---|---|
| `NucleusContextMenuItem(label, enabled, icon, shortcut, onClick)` | A `ContextMenuItem` with an optional icon and shortcut label. |
| `NucleusContextMenuDivider` | Separator item. |
| `NucleusContextMenuSubmenu(label) { items }` | Nested group; `items` is evaluated when the menu opens. |
| `ContextMenuIcon` | `Cut`, `Copy`, `Paste`, `SelectAll`, `Delete`, `Folder`, `SfSymbol(name)`. |
| `ContextMenuIcon.stockShortcut()` | Platform shortcut label for the editing icons, else `null`. |

### Control the menu

| Symbol | Description |
|---|---|
| `NativeContextMenuProvider(enabled) { }` | Installs the native menu for a subtree, without going through the window parameter. |
| `isNativeContextMenuSupported` | Whether this platform can show it. |
| `LocalNativeContextMenu` | Whether the subtree currently uses the native menu. |
| `LocalContextMenuDivider` | The separator the active renderer draws, or `null`. Read it when you assemble item lists. |
| `NativeContextMenuRepresentation` / `NativeTextContextMenu` | The representations installed by the provider. |

### Interpret items

| Symbol | Description |
|---|---|
| `ContextMenuEntry` | `Item(label, enabled, icon, onClick, shortcut)`, `Separator`, `Submenu(label, items)`. |
| `ContextMenuItemInterpreter` | Maps a Compose `ContextMenuItem` to a `ContextMenuEntry`. |
| `DefaultContextMenuItemInterpreter` | The default mapping. |
| `LocalContextMenuItemInterpreter` | Override the mapping for a subtree. |

### macOS popup primitives

Package `dev.nucleusframework.menu.macos`, shipped in `menu-macos`.

| Symbol | Description |
|---|---|
| `NativePopupMenuItem` | `Entry(title, enabled, icon, onClick)`, `Separator`, `Submenu(title, items)`. |
| `isNativePopupMenuAvailable` | Whether the native bridge loaded. |
| `popUpNativeMenu(items)` | Shows an `NSMenu` at the cursor. |

Call `popUpNativeMenu` off the Tao UI thread. AppKit runs a nested tracking loop while the menu
is open, and inside a Tao event callback that loop starves the event loop — animations,
`Dispatchers.Main`, and `delay` all stop until the menu closes.

## Notes

- Icons render differently per platform: Breeze draws 16 dp vectors, Fluent uses Segoe Fluent
  Icons glyphs, and Adwaita follows the GTK convention of no icons in context menus.
  `ContextMenuIcon.SfSymbol` applies to macOS only.
- The flyout closes when the owning window loses focus. Outside-click monitoring only sees this
  process, so focus is the one signal every backend reports — and it also covers Alt+Tab and
  clicks on the taskbar.
- On macOS the menu needs the `menu-macos` native library; if it fails to load,
  `isNativeContextMenuSupported` is `false` and Compose menus are used.

## What's next

- [Spell check](/docs/os/spell-check) — suggestions inside these menus.
- [macOS menu bar](/docs/os/menu-macos) — the application menu, same native layer.
- [DecoratedWindow on Tao](/docs/tao/decorated-window) — the window that hosts the menu.

---

# macOS 26 design system

URL: https://nucleusframework.dev/en/docs/window/toolkit-macos

Compose Multiplatform macOS 26 UI with Liquid Glass materials and a Nucleus-backed decorated window.

[compose-macos-26-ui](https://github.com/NucleusFramework/compose-macos-26-ui) is a Compose
Multiplatform design system for the macOS 26 look: components, theme tokens, icons, and a
desktop `MacosDecoratedWindow` on the Nucleus Tao backend. It targets Android, iOS, desktop JVM,
and web (JS/Wasm). Versioned independently of Nucleus (current release **1.0.0**).

Live gallery: [nucleusframework.github.io/compose-macos-26-ui](https://nucleusframework.github.io/compose-macos-26-ui/).

## Add the dependency

```kotlin title="build.gradle.kts"
plugins {
    id("dev.nucleusframework")
}

dependencies {
    implementation("dev.nucleusframework:compose-macos-ui:1.0.0")
    // optional:
    // implementation("dev.nucleusframework:compose-macos-ui-icons-extended:1.0.0")
    // implementation("dev.nucleusframework:compose-macos-ui-markdown:1.0.0")
}
```

`compose-macos-ui` already exposes `nucleus.nucleus-application` and
`nucleus.decorated-window-tao` as `api` on the JVM target.

## Open a decorated window

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.macoscompose.theme.MacosTheme
import dev.nucleusframework.macoscompose.window.MacosDecoratedWindow

fun main() = nucleusApplication {
    MacosDecoratedWindow(
        onCloseRequest = ::exitApplication,
        title = "Mail",
    ) {
        MacosTheme(darkTheme = false) {
            App()
        }
    }
}
```

Put `MacosTheme` **inside** the window content so native surfaces (traffic lights, glass, clear
colour) follow the app theme.

## How it works

On desktop, `MacosDecoratedWindow` wraps Nucleus `DecoratedWindow` (Tao): full-size content
view, large corner radius via a hidden `NSToolbar`, traffic lights recentred against
`titleBarHeight`, and native materials. Windows and Linux use an undecorated frame with
platform controls drawn in the same band.

## What's next

- [Native design systems](/docs/window/toolkits)
- [Window scaffold](/docs/tao/window-scaffold) — full-window layouts without this pack
- [Repo README](https://github.com/NucleusFramework/compose-macos-26-ui)

---

# Fluent design system

URL: https://nucleusframework.dev/en/docs/window/toolkit-fluent

Windows 11 Fluent UI for Compose Multiplatform, with a Nucleus-backed FluentDecoratedWindow.

[compose-fluent-ui](https://github.com/NucleusFramework/compose-fluent-ui) is a maintained fork
of the Fluent Design library for Compose Multiplatform (desktop, Android, iOS, web). The
`decorated-window-fluent` module adds a Nucleus/Tao client-side decorated window with native
Mica / Acrylic on Windows. Versioned independently of Nucleus (current release **1.0.0**).

Live gallery: [nucleusframework.github.io/compose-fluent-ui](https://nucleusframework.github.io/compose-fluent-ui/).

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework.composefluent:fluent:1.0.0")
    implementation("dev.nucleusframework.composefluent:fluent-icons-extended:1.0.0") // optional
    // Desktop: Nucleus/Tao window
    implementation("dev.nucleusframework.composefluent:decorated-window-fluent:1.0.0")
}
```

## Open a Fluent window

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.fluent.FluentDecoratedWindow
import dev.nucleusframework.window.fluent.FluentTitleBar
import io.github.composefluent.FluentTheme

fun main() = nucleusApplication {
    FluentTheme {
        FluentDecoratedWindow(onCloseRequest = ::exitApplication, title = "Settings") {
            FluentTitleBar { /* search, breadcrumbs, … */ }
            App()
        }
    }
}
```

Widgets live under `io.github.composefluent.component`; theme entry point is `FluentTheme()`.

## How it works

`decorated-window-fluent` maps Fluent theme colours onto Nucleus chrome and wires
`WindowsBackdrop` for real DWM Mica / Acrylic on Windows. The component library itself is KMP;
only the window module is JVM/desktop.

## What's next

- [Native design systems](/docs/window/toolkits)
- [Windows backdrops on Tao](/docs/tao/window-scaffold#windows-11-backdrops)
- [Repo README](https://github.com/NucleusFramework/compose-fluent-ui)

---

# Yaru design system

URL: https://nucleusframework.dev/en/docs/window/toolkit-yaru

Ubuntu Yaru widgets and themes for Compose Multiplatform, with a Nucleus-backed YaruDecoratedWindow.

[yaru-compose-ui](https://github.com/NucleusFramework/yaru-compose-ui) ports
[yaru.dart](https://github.com/ubuntu/yaru.dart) to Compose Multiplatform: 50+ widgets, accent
variants, light/dark/high-contrast themes, and a GNOME-style `YaruDecoratedWindow` on Nucleus
Tao. Versioned independently of Nucleus (current release **1.0.1**).

Live gallery: [nucleusframework.github.io/yaru-compose-ui](https://nucleusframework.github.io/yaru-compose-ui/).

## Add the dependency

Design system only (no native windowing):

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework.yarucompose:yaru:1.0.1")
}
```

Desktop window (pulls `yaru` + Nucleus Tao transitively):

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework.yarucompose:yaru-decorated-window:1.0.1")
}
```

## Open a Yaru window

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.yarucompose.themes.YaruTheme
import dev.nucleusframework.yarucompose.themes.YaruVariant
import dev.nucleusframework.yarucompose.window.YaruDecoratedWindow

fun main() = nucleusApplication {
    YaruDecoratedWindow(onCloseRequest = ::exitApplication, title = "Settings") {
        YaruTheme(isDark = false, variant = YaruVariant.Orange) {
            App()
        }
    }
}
```

`YaruTheme` must sit **inside** the window content so chrome tracks the resolved colour scheme
and layout direction (including RTL).

## How it works

`yaru` is design-only and talks to windowing through optional composition locals.
`yaru-decorated-window` fulfils those contracts with Nucleus and ships the native binaries;
leave it out if you draw into a plain Compose `Window` or a non-JVM target.

## What's next

- [Native design systems](/docs/window/toolkits)
- [Window scaffold](/docs/tao/window-scaffold)
- [Repo README](https://github.com/NucleusFramework/yaru-compose-ui)

---

# Jewel — IntelliJ Platform

URL: https://nucleusframework.dev/en/docs/window/toolkit-jewel

Style a DecoratedWindow with Jewel colors and metrics so the title bar and chrome match the IntelliJ Platform look.

Jewel is JetBrains' design system for the IntelliJ Platform. The Nucleus Jewel toolkit styles
`DecoratedWindow` with Jewel colors and metrics, so the title bar and window chrome match the
IntelliJ look on macOS, Windows, and Linux. It runs on the Tao backend behind the same API
(the AWT backend is also supported, but deprecated).

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-jewel:<version>")
    // A Jewel theme module — pick the one that matches your target IDE build.
    implementation("org.jetbrains.jewel:jewel-int-ui-standalone-243:<version>")
}
```

The toolkit depends on `decorated-window-core` and a backend module. Pair it with `-tao` for
the Rust-native windowing backend; the `-jbr` / `-jni` AWT modules are deprecated.

## Create a Jewel-styled window

Wrap the window content in a Jewel theme, then open a `JewelDecoratedWindow`:

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.darkmodedetector.isSystemInDarkMode
import dev.nucleusframework.window.jewel.JewelDecoratedWindow
import dev.nucleusframework.window.jewel.JewelTitleBar
import org.jetbrains.jewel.intui.standalone.theme.IntUiTheme

fun main() = nucleusApplication {
    IntUiTheme(isDark = isSystemInDarkMode()) {
        JewelDecoratedWindow(
            onCloseRequest = ::exitApplication,
            title = "Tools",
        ) {
            JewelTitleBar { /* title bar content */ }
            Box(Modifier.fillMaxSize()) {
                // Jewel widgets go here
            }
        }
    }
}
```

The window reads the current Jewel theme and derives its title bar and chrome from it, so
switching `isDark` flips the whole window between the light and dark IntelliJ palettes.

`JewelDecoratedWindow` reads `JewelTheme.globalColors`, so you must call it inside a Jewel
theme such as `IntUiTheme`. Without one, the composable has no colors to derive its style from.

## How it works

`JewelDecoratedWindow` is a Composable wrapper around `DecoratedWindow`. It reads
`JewelTheme.globalColors`, derives a `DecoratedWindowStyle` and a `TitleBarStyle` from the
active Jewel theme, and installs them through `NucleusDecoratedWindowTheme` before opening the
window. Inside the window you compose regular Jewel widgets — `Text`, `DefaultButton`,
`OutlinedButton`, lazy lists, and the rest.

There are two overloads. The one on `NucleusApplicationScope` — used above inside
`nucleusApplication { }` — is backend-agnostic and works on both the Tao and AWT backends from
the same call site. The overload on Compose's `ApplicationScope` is AWT-backed (JBR/JNI) and is
meant for a plain `application { }` entry point.

`rememberJewelWindowStyle()` and `rememberJewelTitleBarStyle()` expose the derived styles
directly. Use them when you build your own wrapper — for example, a single composable that
switches between Jewel and another toolkit at runtime.

## API reference

### Open a window or dialog

- `JewelDecoratedWindow(...)` — a Jewel-styled window. Available on `NucleusApplicationScope`
  (backend-agnostic) and on `ApplicationScope` (AWT-backed). The `NucleusApplicationScope`
  overload also takes `undecorated`, `popupFor`, `nativeContextMenu`, `hiddenFromDock`,
  `titleBarStyle`, and the Tao-only flags `transparent`, `clickThrough`,
  `visibleOnAllWorkspaces` and `forceX11`; the AWT overload does not.
- `JewelDecoratedDialog(...)` — the modal dialog variant. A top-level function is AWT-backed;
  the `NucleusApplicationScope` overload is backend-agnostic.

### Add a title bar

- `DecoratedWindowScope.JewelTitleBar(...)` — the title bar slot for a window.
- `DecoratedDialogScope.JewelDialogTitleBar(...)` — the title bar slot for a dialog.

### Read the derived styles

- `rememberJewelWindowStyle(): DecoratedWindowStyle` — the window chrome style derived from the
  active Jewel theme.
- `rememberJewelTitleBarStyle(): TitleBarStyle` — the title bar style derived from the active
  Jewel theme.

## What's next

- [Material toolkit](/docs/window/toolkit-material) — Material 2 and Material 3 styling for `DecoratedWindow`.
- [DecoratedWindow](/docs/window) — the underlying window and title bar API.
- [Backends](/docs/concepts/backends) — Tao and the deprecated AWT backend.

---

# Material 2 & Material 3

URL: https://nucleusframework.dev/en/docs/window/toolkit-material

Theme a Nucleus DecoratedWindow from a Compose MaterialTheme, using either the Material 2 or Material 3 adapter.

The Material toolkits theme a Nucleus `DecoratedWindow` from a Compose `MaterialTheme`, so the
title bar and window controls follow your app's color scheme on every backend. Nucleus ships two
adapters: `decorated-window-material2` for `androidx.compose.material` and
`decorated-window-material3` for `androidx.compose.material3`.

## Add the dependency

Add the Nucleus runtime, a backend, and the Material adapter that matches the Compose Material
version you use. Pair it with `decorated-window-tao` for the Tao backend.

**Material 3**

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-material3:<version>")
    implementation(compose.material3)
}
```

**Material 2**

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:<version>")
    implementation("dev.nucleusframework:nucleus.decorated-window-material2:<version>")
    implementation(compose.material)
}
```

The Material 3 artifact is `nucleus.decorated-window-material3`, but its Kotlin package is
`dev.nucleusframework.window.material` — with no `3`. Material 2 lives in
`dev.nucleusframework.window.material2`.

## Create a Material window

Wrap `MaterialDecoratedWindow` in a `MaterialTheme`. The window inherits the theme's colors, and
`MaterialTitleBar` draws a title bar styled to match.

**Material 3**

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.lightColorScheme
import androidx.compose.ui.Modifier
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.material.MaterialDecoratedWindow
import dev.nucleusframework.window.material.MaterialTitleBar

fun main() = nucleusApplication {
    MaterialTheme(colorScheme = lightColorScheme()) {
        MaterialDecoratedWindow(onCloseRequest = ::exitApplication, title = "Material 3") {
            MaterialTitleBar { Text("Material 3") }
            Surface(Modifier.fillMaxSize()) { /* content */ }
        }
    }
}
```

**Material 2**

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material.MaterialTheme
import androidx.compose.material.Surface
import androidx.compose.material.Text
import androidx.compose.material.lightColors
import androidx.compose.ui.Modifier
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.window.material2.MaterialDecoratedWindow
import dev.nucleusframework.window.material2.MaterialTitleBar

fun main() = nucleusApplication {
    MaterialTheme(colors = lightColors()) {
        MaterialDecoratedWindow(onCloseRequest = ::exitApplication, title = "Material 2") {
            MaterialTitleBar { Text("Material 2") }
            Surface(Modifier.fillMaxSize()) { /* content */ }
        }
    }
}
```

Swap `lightColorScheme()` / `lightColors()` for the dark variant to switch the whole window,
chrome included. To follow the operating system, drive the color scheme from `isSystemInDarkMode()`
in the `nucleus.darkmode-detector` artifact.

## How it works

Inside `nucleusApplication { }`, `MaterialDecoratedWindow` reads the current `MaterialTheme`,
derives a `DecoratedWindowStyle` and a `TitleBarStyle` from it, and wraps the window in
`NucleusDecoratedWindowTheme`. The title bar background, content color, and window-control button
colors are taken from your `ColorScheme` (Material 3) or `Colors` (Material 2), so the chrome
updates whenever the theme switches to a dark palette.

Material 3 exposes the color mapping as public helpers you can call yourself:

```kotlin
val windowStyle = rememberMaterialWindowStyle(colorScheme)
val titleBarStyle = rememberMaterialTitleBarStyle(colorScheme)
```

Pass a `TitleBarStyle` to the `titleBarStyle` parameter of `MaterialDecoratedWindow` to override the
derived title bar; the window style is always resolved from the active `ColorScheme`. Material 2
derives the same styles internally, but those helpers are `internal` and not part of its public API.

## API reference

### Material 3

- `ApplicationScope.MaterialDecoratedWindow(...)` and `NucleusApplicationScope.MaterialDecoratedWindow(...)` — the `NucleusApplicationScope` overload also takes `nativePopupLayers`, `nativeContextMenu`, `hiddenFromDock`, `titleBarStyle`, `undecorated`, and the Tao-only flags `transparent`, `clickThrough`, `visibleOnAllWorkspaces` and `forceX11` (Material 2 has the same set minus `nativePopupLayers`)
- `ApplicationScope.MaterialDecoratedDialog(...)` and `NucleusApplicationScope.MaterialDecoratedDialog(...)`
- `DecoratedWindowScope.MaterialTitleBar(...)`
- `DecoratedDialogScope.MaterialDialogTitleBar(...)`
- `rememberMaterialWindowStyle(colorScheme: ColorScheme): DecoratedWindowStyle`
- `rememberMaterialTitleBarStyle(colorScheme: ColorScheme): TitleBarStyle`

### Material 2

- `MaterialDecoratedWindow(...)` and `NucleusApplicationScope.MaterialDecoratedWindow(...)`
- `MaterialDecoratedDialog(...)`
- `DecoratedWindowScope.MaterialTitleBar(...)`
- `DecoratedDialogScope.MaterialDialogTitleBar(...)`

The Material adapters run on every backend. Pair them with `decorated-window-tao` for the Tao
backend, or with the deprecated `-jbr` / `-jni` AWT modules.

## What's next

- [Window and toolkits](/docs/window) — the `DecoratedWindow` API the Material adapters wrap.
- [Choosing a toolkit](/docs/window/toolkits) — compare Material with the native looks.
- [Jewel toolkit](/docs/window/toolkit-jewel) — IDE-style chrome built on Jewel.

---

# PDF reader

URL: https://nucleusframework.dev/en/docs/pdf

Render PDFs, extract text, and select or copy content from Compose, with one API across Android, iOS, web, and desktop.

The PDF reader is a Kotlin Multiplatform library that renders PDF pages, extracts text, and drives selection, search, links, and thumbnails from Compose. The public API is the same on every target: you write against `PdfReaderState` and `PdfPage` once, and the library binds to the native PDF stack of each platform underneath.

The PDF reader ships from its own repository with its own release cycle, like the [system tray](/docs/os/system-tray). Its version number is **independent of Nucleus** — pin it separately. The artifact is `dev.nucleusframework:pdfium`, published to Maven Central.

## One API instead of one per platform

Each platform has its own PDF engine, with its own API, threading model, and coordinate conventions:

| Platform | Native PDF stack |
| -------- | ---------------- |
| Android  | `PdfRenderer` (`android.graphics.pdf`) |
| iOS      | PDFKit (`PDFView`, `PDFDocument`) |
| Web      | PDF.js |
| Desktop  | PDFBox and other JVM libraries |

Without a shared layer, a multiplatform app integrates and maintains four of these. The PDF reader replaces them with a single Compose surface backed by [PDFium](https://pdfium.googlesource.com/pdfium/) on all four, so rendering, text extraction, and selection behave identically everywhere.

## Add the dependency

```kotlin title="build.gradle.kts"
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.nucleusframework:pdfium:<version>")
        }
    }
}
```

The `:pdfium` module uses a JVM toolchain of 17. PDFium binaries are fetched at build time from [bblanchon/pdfium-binaries](https://github.com/bblanchon/pdfium-binaries); no manual native setup is required.

## Show a PDF

Hoist a `PdfReaderState`, open the document bytes, and drop `PdfReader` into your layout:

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.Modifier
import dev.nucleusframework.pdfium.PdfReader
import dev.nucleusframework.pdfium.rememberPdfReaderState

@Composable
fun HelloPdf(bytes: ByteArray) {
    val reader = rememberPdfReaderState()
    LaunchedEffect(bytes) { reader.open(bytes) }
    PdfReader(state = reader, modifier = Modifier.fillMaxSize())
}
```

`PdfReader` stacks every page in a `LazyColumn`. `rememberPdfReaderState` disposes the native handles automatically when it leaves composition.

## Supported targets

| Target  | Backend                                         |
| ------- | ----------------------------------------------- |
| JVM     | JNI + Skia (Skiko)                              |
| Android | JNI (NDK `AndroidBitmap_*`)                     |
| iOS     | Kotlin/Native cinterop + Skia (Skiko)           |
| Web     | `pdfium.wasm` in a Web Worker + Skiko           |

JVM covers linux-x64/arm64, macos-x64/arm64, and win-x64/arm64. Android covers arm64-v8a, armeabi-v7a, x86, and x86_64. Web covers Kotlin/WasmJS and Kotlin/JS (IR).

## How it works

`commonMain` holds the whole public API — `PdfReaderState`, `PdfPage`, `PdfThumbnail`, and `PdfReader` — over an `expect class PdfDocument`. Each source set provides the `actual`: JNI glue on JVM and Android, a Kotlin/Native cinterop on iOS, and a `pdfium.wasm` worker on the web.

Rendering uses a zero-copy path where the platform allows it. On JVM and iOS, PDFium writes pixels straight into a Skia bitmap's memory; on Android it locks the `android.graphics.Bitmap`; on the web the worker's pixel `ArrayBuffer` is written into Skia's wasm heap without an intermediate Kotlin `ByteArray`.

PDFium is single-threaded per document — it relies on FreeType's non-thread-safe `FT_Library` — so each `PdfDocument` runs on its own single-threaded dispatcher. Rendering is serialised inside a document.

## What the library covers

- Compose composables: drop `PdfReader`, `PdfPage`, or `PdfThumbnail` into any Compose UI.
- Progressive rendering (preview to full) with a debounced size flow.
- A two-tier LRU cache for reader bitmaps and thumbnails, with off-screen prefetch.
- Text extraction: per-page UTF-8 text, line-level rectangles, and per-character boxes.
- A selectable-text overlay driven by PDFium's per-character boxes.
- Clickable links: URI and internal GoTo annotations, plus URLs and e-mail addresses detected in the page text.
- Password-protected documents through `PdfError.PasswordRequired`.

PDFium is dual-licensed BSD-3-Clause / Apache-2.0, and bblanchon's binaries carry that license forward. If you ship an app built on this library, include the upstream PDFium notices.

## What's next

- [Getting started](/docs/pdf/getting-started) — load bytes, handle loading state, enable selection, links, thumbnails, and zoom.
- [API reference](/docs/pdf/api-reference) — every public type, its parameters, and defaults.
- [WebView](/docs/webview) — another Nucleus component shipped from its own repository.
- [System tray](/docs/os/system-tray) — tray icons and menus from a separate repository.

---

# Getting started

URL: https://nucleusframework.dev/en/docs/pdf/getting-started

Load PDF bytes, react to loading state, and enable text selection, links, thumbnails, and zoom.

In this tutorial, you'll open a PDF from a file picker, react to its loading state, and turn on text selection, links, a thumbnail sidebar, and zoom. Every snippet drops into a Compose Multiplatform `commonMain` source set.

## Before you start

Add the dependency described in the [PDF reader overview](/docs/pdf):

```kotlin title="build.gradle.kts"
commonMain.dependencies {
    implementation("dev.nucleusframework:pdfium:<version>")
}
```

## Load the PDF bytes

`PdfReaderState.open` takes a `ByteArray` — how you obtain it is up to you. To pick a file with a native dialog, use [FileKit](/docs/ecosystem/file-dialog):

```kotlin
@Composable
fun PdfPicker() {
    val reader = rememberPdfReaderState()
    val scope = rememberCoroutineScope()
    val picker = rememberFilePickerLauncher(
        type = FileKitType.File(extensions = listOf("pdf")),
    ) { file ->
        if (file != null) scope.launch { reader.open(file.readBytes()) }
    }
    Column(Modifier.fillMaxSize()) {
        Button(onClick = { picker.launch() }) { Text("Open PDF…") }
        if (reader.pageCount > 0) {
            PdfReader(state = reader, modifier = Modifier.fillMaxSize())
        }
    }
}
```

To load from a URL, pass the bytes from any HTTP client:

```kotlin
val client = remember { HttpClient() }
LaunchedEffect(url) { reader.open(client.get(url).readRawBytes()) }
```

## React to loading state and errors

`PdfReaderState` exposes snapshot state you can read in any composable — `isLoading`, `error`, `metadata`, and `pageCount`:

```kotlin
Box(Modifier.fillMaxSize()) {
    when {
        reader.isLoading -> CircularProgressIndicator(Modifier.align(Alignment.Center))

        reader.error is PdfError.PasswordRequired -> PasswordPrompt { password ->
            scope.launch { reader.open(bytes, password) }
        }
        reader.error is PdfError.InvalidFormat -> Text("Not a valid PDF")
        reader.error != null -> Text("Couldn't open: ${reader.error?.message}")

        reader.pageCount > 0 -> {
            Column {
                Text(reader.metadata.title ?: "Untitled")
                PdfReader(state = reader, modifier = Modifier.weight(1f))
            }
        }
    }
}
```

## Enable text selection

Set `selectableText = true` on `PdfPage`. Drag on desktop, long-press on mobile, and copy with Ctrl/Cmd+C:

```kotlin
PdfPage(
    state = reader,
    pageIndex = pageIndex,
    modifier = Modifier.fillMaxWidth(),
    selectableText = true,
)
```

Hit-testing uses PDFium's per-character boxes (`FPDFText_GetCharBox`), so selection tracks the rendered glyphs rather than Compose's own font metrics.

## Handle links

Links are enabled by default on `PdfPage` and `PdfReader`. Link annotations and URLs or e-mail addresses detected in the page text become clickable regions. External URIs open through `LocalUriHandler`; inside `PdfReader`, internal GoTo links scroll to the destination page.

Intercept clicks with `onLinkClick` — return `true` to consume the click and skip the default handling:

```kotlin
PdfReader(
    state = reader,
    onLinkClick = { link ->
        if (link.uri?.startsWith("mailto:") == true) {
            openCustomComposer(link.uri)
            true
        } else {
            false
        }
    },
)
```

## Add a thumbnail sidebar

`PdfThumbnail` renders at `RenderQuality.PREVIEW` and keeps its own LRU, so scrolling a long strip never evicts the reader's full-quality bitmaps:

```kotlin
Row(Modifier.fillMaxSize()) {
    LazyColumn(Modifier.width(160.dp).fillMaxHeight()) {
        items(reader.pageCount) { i ->
            PdfThumbnail(state = reader, pageIndex = i, modifier = Modifier.clickable { /* jumpToPage(i) */ })
        }
    }
    PdfReader(state = reader, modifier = Modifier.weight(1f).fillMaxHeight())
}
```

## Zoom and fit-to-width

`PdfReaderState.renderScale` is a plain `Float` that every `PdfPage` observes. `1.0` is fit-to-width; change it to re-render the visible pages at the new size:

```kotlin
var scale by remember { mutableStateOf(1f) }
LaunchedEffect(scale) { reader.renderScale = scale }

Slider(value = scale, onValueChange = { scale = it }, valueRange = 0.5f..3f)
```

## Extract text programmatically

`pageText` returns the Unicode of a single page; `pageTextLayout` returns line-level rectangles for search and highlighting:

```kotlin
scope.launch {
    val text = reader.pageText(pageIndex = 0)
    println(text)
}
```

The library's sample app wires a picker, sidebar, zoom, and selection into a full reader screen. See the repository's `:example` module for a complete reference.

## What's next

- [API reference](/docs/pdf/api-reference) — every public type, its parameters, and defaults.
- [PDF reader overview](/docs/pdf) — supported targets and how the render path works.
- [Native file dialogs](/docs/ecosystem/file-dialog) — the FileKit picker used above.

---

# API reference

URL: https://nucleusframework.dev/en/docs/pdf/api-reference

PdfReaderState, PdfPage, PdfThumbnail, PdfReader, and the supporting data types.

The public API lives under `dev.nucleusframework.pdfium`. Coordinates in text-layout results are in PDF page points (1 pt = 1/72 inch), with the origin at the bottom-left of the page.

## PdfReaderState

The state holder tied to a single document. Hoist it with `rememberPdfReaderState()`.

```kotlin
@Stable
class PdfReaderState {
    // Snapshot state
    val pageCount: Int        // 0 until a document is open
    val isLoading: Boolean    // true during open()
    val error: PdfError?      // last open() error, if any
    val metadata: PdfMetadata
    var renderScale: Float    // 1.0 = fit-to-width

    // Intents
    suspend fun open(bytes: ByteArray, password: String? = null)
    suspend fun pageSize(pageIndex: Int): PageSize?
    suspend fun pageText(pageIndex: Int): String
    suspend fun pageTextLayout(pageIndex: Int): PageTextLayout?

    // Render ahead-of-display; best-effort, populates the cache
    fun prefetch(pageIndex: Int, widthPx: Int, quality: RenderQuality = RenderQuality.FULL)

    // Release native handles + cached bitmaps (called by rememberPdfReaderState)
    fun dispose()

    companion object {
        const val DEFAULT_CACHE_BYTES: Long = 64L * 1024 * 1024
        const val DEFAULT_THUMBNAIL_CACHE_BYTES: Long = 12L * 1024 * 1024
    }
}

@Composable
fun rememberPdfReaderState(
    cacheBytes: Long = PdfReaderState.DEFAULT_CACHE_BYTES,
    thumbnailCacheBytes: Long = PdfReaderState.DEFAULT_THUMBNAIL_CACHE_BYTES,
): PdfReaderState
```

Bitmaps are keyed by `(pageIndex, quantized_width)`. Both cache budgets are tunable on `rememberPdfReaderState(...)`.

## PdfPage

Renders a single page. Handles progressive rendering (low-res preview to full quality on settle) and debounces size changes internally.

```kotlin
@Composable
fun PdfPage(
    state: PdfReaderState,
    pageIndex: Int,
    modifier: Modifier = Modifier,
    contentScale: ContentScale = ContentScale.Fit,
    background: Color = Color.White,
    selectableText: Boolean = false,
    linksEnabled: Boolean = true,
    onLinkClick: ((PdfLink) -> Boolean)? = null,
)
```

- `modifier` controls the layout width; the composable derives the aspect ratio from the PDF page and sets its own height.
- `selectableText = true` enables the pointer-driven selection overlay.
- A standalone `PdfPage` has no list to scroll, so internal GoTo links are only actionable through `onLinkClick`.

## PdfThumbnail

A low-resolution preview of a single page. Renders at `RenderQuality.PREVIEW`, shares the `PdfReaderState` cache, and sizes itself to the modifier-provided width.

```kotlin
@Composable
fun PdfThumbnail(
    state: PdfReaderState,
    pageIndex: Int,
    modifier: Modifier = Modifier,
    background: Color = Color.White,
)
```

## PdfReader

A convenience composable — a vertical `LazyColumn` that stacks every page of the document.

```kotlin
@Composable
fun PdfReader(
    state: PdfReaderState,
    modifier: Modifier = Modifier,
    contentPadding: PaddingValues = PaddingValues(12.dp),
    pageSpacing: Dp = 16.dp,
)
```

## RenderQuality

```kotlin
enum class RenderQuality {
    // No annotations, no LCD text. Used for thumbnails and progressive previews.
    PREVIEW,

    // Annotations on, no LCD text. Balanced default for on-screen viewing.
    FULL,
}
```

## PageSize, PdfMetadata, PdfError

```kotlin
data class PageSize(val widthPoints: Float, val heightPoints: Float) {
    val aspectRatio: Float // widthPoints / heightPoints, or 1f for degenerate pages
}

data class PdfMetadata(
    val title: String? = null,
    val author: String? = null,
    val subject: String? = null,
    val keywords: String? = null,
    val creator: String? = null,
    val producer: String? = null,
)

sealed class PdfError(open val message: String, open val cause: Throwable? = null) {
    data class InvalidFormat(...) : PdfError(...)
    data class PasswordRequired(...) : PdfError(...)
    data class NativeFailure(...) : PdfError(...)
    data class Io(...) : PdfError(...)
}
```

## PageTextLayout

Returned by `PdfReaderState.pageTextLayout(...)` for building custom text overlays and highlighting tools.

```kotlin
@Immutable
class PageTextLayout {
    val pageIndex: Int
    val pageSize: PageSize
    val rectCount: Int
    val charCount: Int

    // Rect-level (line-level runs from FPDFText_GetRect)
    fun left(i: Int): Float       // in PDF points, origin bottom-left
    fun bottom(i: Int): Float
    fun right(i: Int): Float
    fun top(i: Int): Float
    fun text(i: Int): String      // UTF-8 Unicode

    // Char-level (FPDFText_GetCharBox / FPDFText_GetUnicode)
    fun codepoint(i: Int): Int
    fun charLeft(i: Int): Float
    fun charBottom(i: Int): Float
    fun charRight(i: Int): Float
    fun charTop(i: Int): Float
}
```

To map a rectangle to a rendered bitmap of pixel dimensions `W × H`:

```
scaleX = W / pageSize.widthPoints
scaleY = H / pageSize.heightPoints

screenX = left × scaleX
screenY = H - top × scaleY       // flip Y (PDF is bottom-up)
screenW = (right - left)   × scaleX
screenH = (top   - bottom) × scaleY
```

## What's next

- [Getting started](/docs/pdf/getting-started) — the same API used across a full reader screen.
- [PDF reader overview](/docs/pdf) — supported targets and the render path.

---

# WebView

URL: https://nucleusframework.dev/en/docs/webview

Embed a native web engine in Compose with one API across Android, iOS, web, and desktop.

The WebView library embeds each platform's native web engine in Compose. You write against `WebView`, `WebViewState`, and `WebViewNavigator` once; the library binds to Android WebView, WKWebView, WebView2, WebKit2GTK, or an iframe underneath.

The public API and the Android/iOS implementations follow [compose-webview-multiplatform](https://github.com/KevinnZou/compose-webview-multiplatform). ComposeNativeWebView adds a WasmJs target and a desktop path on the [Tao `NativeView`](/docs/tao/native-views) stack.

WebView ships from [`NucleusFramework/ComposeNativeWebview`](https://github.com/NucleusFramework/ComposeNativeWebview) with its own release cycle, like the [system tray](/docs/os/system-tray) and the [PDF reader](/docs/pdf). Its version number is **independent of Nucleus** — pin it separately. The artifact is `dev.nucleusframework:composewebview`, published to Maven Central.

## One API instead of one per platform

| Platform | Native web engine |
| -------- | ----------------- |
| Android  | `android.webkit.WebView` |
| iOS      | WKWebView |
| WasmJs   | `HTMLIFrameElement` |
| Desktop (Linux) | WebKit2GTK via Tao `NativeView` |
| Desktop (macOS) | WKWebView via Tao `NativeView` |
| Desktop (Windows) | WebView2 CompositionController via Tao `NativeView` |

Without a shared layer, a multiplatform app integrates and maintains each engine separately. ComposeNativeWebView replaces that with a single Compose surface and the same navigation, cookie, and JavaScript model on every target.

## Add the dependency

```kotlin title="build.gradle.kts"
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.nucleusframework:composewebview:<version>")
        }
    }
}
```

The same artifact covers Android, iOS, Desktop (JVM), and WasmJs.

## Show a page

Hoist a `WebViewState` and drop `WebView` into your layout:

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import dev.nucleusframework.webview.web.WebView
import dev.nucleusframework.webview.web.rememberWebViewState

@Composable
fun HelloWeb() {
    val state = rememberWebViewState("https://example.com")
    WebView(state = state, modifier = Modifier.fillMaxSize()) {
        // Optional Compose overlay on top of the native surface
    }
}
```

The trailing `content` lambda draws Compose UI over the embedded engine — the same role as the content slot on Tao [`NativeView`](/docs/tao/native-views).

## Supported targets

| Target  | Backend |
| ------- | ------- |
| Android | `android.webkit.WebView` |
| iOS     | WKWebView |
| WasmJs  | IFrame |
| JVM desktop | Tao + platform native library |

Desktop requires a Nucleus Tao window (`nucleusApplication` and `decorated-window-tao`). Windows also needs the [WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2/) (or Edge). Native libraries ship inside the artifact under `nucleus/native/…`.

## What the library covers

- Content loading: URL (with headers), inline HTML, and HTML from app resources.
- Navigation: back, forward, reload, stop, with `canGoBack` / `canGoForward` as Compose state.
- Observable state: `isLoading`, `loadingState`, `lastLoadedUrl`, `pageTitle`, and per-request errors.
- A unified cookie manager across platforms.
- `evaluateJavaScript` and a callback-based JS ↔ Kotlin bridge (`window.kmpJsBridge`).
- A `RequestInterceptor` for navigator-initiated main-frame navigations.

## Limitations

- `RequestInterceptor` does not intercept sub-resources (images, XHR, scripts).
- **Desktop** needs the Tao backend; the library does not embed a browser on the AWT path.
- **WasmJs**: history back/forward is unavailable in the iframe; CORS must allow embedding; JavaScript runs only on the same origin; cookies apply only when the iframe destination matches the parent origin.

## What's next

- [Getting started](/docs/webview/getting-started) — load URLs and HTML, navigate, evaluate JS, intercept requests.
- [API reference](/docs/webview/api-reference) — every public type, its parameters, and defaults.
- [PDF reader](/docs/pdf) — another Nucleus component shipped from its own repository.
- [Native views on Tao](/docs/tao/native-views) — the desktop embedding primitive used under the hood.

---

# Getting started

URL: https://nucleusframework.dev/en/docs/webview/getting-started

Load URLs and HTML, navigate the history stack, evaluate JavaScript, and intercept requests from Compose.

In this tutorial, you'll open a URL in a multiplatform WebView, react to loading state, navigate the history stack, evaluate JavaScript, and intercept navigations. Every snippet drops into a Compose Multiplatform `commonMain` source set.

## Before you start

Add the dependency described in the [WebView overview](/docs/webview):

```kotlin title="build.gradle.kts"
commonMain.dependencies {
    implementation("dev.nucleusframework:composewebview:<version>")
}
```

On **desktop**, open the window with Nucleus Tao (`nucleusApplication` and `decorated-window-tao`). The WebView embeds through [`NativeView`](/docs/tao/native-views) and does not run on the AWT backend.

## Load a URL

Hoist a `WebViewState` with `rememberWebViewState` and place `WebView` in the layout:

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import dev.nucleusframework.webview.web.WebView
import dev.nucleusframework.webview.web.rememberWebViewState

@Composable
fun Browser(url: String) {
    val state = rememberWebViewState(url) {
        customUserAgentString = "MyApp/1.0"
    }
    WebView(state = state, modifier = Modifier.fillMaxSize())
}
```

The trailing lambda on `rememberWebViewState` is a `WebSettings` receiver — set user agent, zoom, JavaScript, and platform-specific options there.

## Load HTML

For inline HTML, use `rememberWebViewStateWithHTMLData`. For a file packaged with the app, use `rememberWebViewStateWithHTMLFile`:

```kotlin
val htmlState = rememberWebViewStateWithHTMLData(
    data = """
        <html><body><h1>Hello</h1></body></html>
    """.trimIndent(),
    baseUrl = null,
)

val fileState = rememberWebViewStateWithHTMLFile(
    fileName = "index.html",
    readType = WebViewFileReadType.ASSET_RESOURCES,
)
```

`WebViewFileReadType.ASSET_RESOURCES` reads platform asset roots; `COMPOSE_RESOURCE_FILES` reads Compose Multiplatform resources.

## React to loading state

`WebViewState` exposes snapshot state you can read in any composable — `isLoading`, `loadingState`, `lastLoadedUrl`, `pageTitle`, and `errorsForCurrentRequest`:

```kotlin
Box(Modifier.fillMaxSize()) {
    WebView(state = state, modifier = Modifier.fillMaxSize())
    if (state.isLoading) {
        LinearProgressIndicator(
            progress = {
                (state.loadingState as? LoadingState.Loading)?.progress ?: 0f
            },
            modifier = Modifier.fillMaxWidth().align(Alignment.TopCenter),
        )
    }
    state.pageTitle?.let { title ->
        Text(title, Modifier.align(Alignment.BottomCenter))
    }
}
```

`LoadingState` is a sealed class: `Initializing`, `Loading(progress)`, or `Finished`.

## Navigate with a navigator

Hoist a `WebViewNavigator` when you need toolbar actions or programmatic loads:

```kotlin
val state = rememberWebViewState("https://example.com")
val navigator = rememberWebViewNavigator()

Column(Modifier.fillMaxSize()) {
    Row {
        IconButton(
            onClick = { navigator.navigateBack() },
            enabled = navigator.canGoBack,
        ) { Icon(Icons.Default.ArrowBack, contentDescription = "Back") }
        IconButton(
            onClick = { navigator.navigateForward() },
            enabled = navigator.canGoForward,
        ) { Icon(Icons.Default.ArrowForward, contentDescription = "Forward") }
        IconButton(onClick = { navigator.reload() }) {
            Icon(Icons.Default.Refresh, contentDescription = "Reload")
        }
        IconButton(onClick = {
            navigator.loadUrl("https://kotlinlang.org")
        }) { Text("Kotlin") }
    }
    WebView(state = state, navigator = navigator, modifier = Modifier.weight(1f))
}
```

Navigator commands include `loadUrl`, `loadHtml`, `loadHtmlFile`, `evaluateJavaScript`, `navigateBack`, `navigateForward`, `reload`, and `stopLoading`.

## Evaluate JavaScript

```kotlin
navigator.evaluateJavaScript("document.title") { title ->
    println("Page title: $title")
}
```

## Bridge JavaScript to Kotlin

Pass a `WebViewJsBridge` to `WebView`. Handlers register under a method name; the page calls `window.kmpJsBridge.callNative(...)` after load:

```kotlin
val navigator = rememberWebViewNavigator()
val bridge = rememberWebViewJsBridge(navigator)

LaunchedEffect(bridge) {
    bridge.register(object : IJsMessageHandler {
        override fun methodName() = "echo"
        override fun handle(
            message: JsMessage,
            navigator: WebViewNavigator?,
            callback: (String) -> Unit,
        ) {
            callback(message.params)
        }
    })
}

WebView(
    state = state,
    navigator = navigator,
    webViewJsBridge = bridge,
    modifier = Modifier.fillMaxSize(),
)
```

From the page:

```js
window.kmpJsBridge.callNative("echo", JSON.stringify({ hello: "world" }), function (result) {
  console.log(result);
});
```

## Intercept navigations

Attach a `RequestInterceptor` when creating the navigator. It runs only for **navigator-initiated** main-frame loads — not for sub-resources:

```kotlin
val navigator = rememberWebViewNavigator(
    requestInterceptor = object : RequestInterceptor {
        override fun onInterceptUrlRequest(
            request: WebRequest,
            navigator: WebViewNavigator,
        ): WebRequestInterceptResult {
            if (request.url.contains("blocked.example")) {
                return WebRequestInterceptResult.Reject
            }
            return WebRequestInterceptResult.Allow
        }
    },
)
```

Return `Allow`, `Reject`, or `Modify(request)` to rewrite the URL or headers.

## Manage cookies

```kotlin
scope.launch {
    state.cookieManager.setCookie(
        url = "https://example.com",
        cookie = Cookie(name = "session", value = "abc", domain = "example.com"),
    )
    val cookies = state.cookieManager.getCookies("https://example.com")
    state.cookieManager.removeCookies("https://example.com")
    state.cookieManager.removeAllCookies()
}
```

## Desktop notes

- Linux needs WebKit2GTK available on the system (`libwebkit2gtk`).
- Windows needs the WebView2 Runtime or a recent Edge install.
- macOS uses the system WKWebView; no extra runtime package is required.
- Open the host window on Tao. See [DecoratedWindow on Tao](/docs/tao/decorated-window).

The repository's e2e hosts (`e2e-desktop`, `e2e-android`, `e2e-wasmJs`, `iosApp`) run the same visual suite against a real WebView on each platform. Use them as a complete reference for wiring.

## What's next

- [API reference](/docs/webview/api-reference) — every public type, its parameters, and defaults.
- [WebView overview](/docs/webview) — supported targets and platform backends.
- [Native views on Tao](/docs/tao/native-views) — how desktop embeds the native surface.

---

# API reference

URL: https://nucleusframework.dev/en/docs/webview/api-reference

WebView, WebViewState, WebViewNavigator, settings, cookies, JS bridge, and request interception.

The public API lives under `dev.nucleusframework.webview`. Platform packages re-export the same types from `commonMain`.

## WebView

The multiplatform composable. Draws the native engine and an optional Compose overlay.

```kotlin
@Composable
fun WebView(
    state: WebViewState,
    modifier: Modifier = Modifier,
    navigator: WebViewNavigator = rememberWebViewNavigator(),
    webViewJsBridge: WebViewJsBridge? = null,
    onCreated: (NativeWebView) -> Unit = {},
    onDispose: (NativeWebView) -> Unit = {},
    content: @Composable () -> Unit = {},
)
```

- `content` is Compose UI drawn **over** the native surface (Tao `NativeView` content slot on desktop; a layered sibling elsewhere).
- `onCreated` / `onDispose` receive the platform `NativeWebView` handle when the engine is attached or released.

## WebViewState

State holder for one embedded engine. Create it with the `rememberWebViewState*` helpers.

```kotlin
@Stable
class WebViewState(webContent: WebContent) {
    var lastLoadedUrl: String?           // last committed URL
    var content: WebContent              // drives loads when reassigned
    var loadingState: LoadingState       // Initializing | Loading | Finished
    val isLoading: Boolean               // true until Finished
    var pageTitle: String?
    val errorsForCurrentRequest: SnapshotStateList<WebViewError>
    val webSettings: WebSettings
    val cookieManager: CookieManager
    var webView: IWebView?               // set after the platform view attaches
}
```

```kotlin
@Composable
fun rememberWebViewState(
    url: String,
    additionalHttpHeaders: Map<String, String> = emptyMap(),
    extraSettings: WebSettings.() -> Unit = {},
): WebViewState

@Composable
fun rememberWebViewStateWithHTMLData(
    data: String,
    baseUrl: String? = null,
    encoding: String = "utf-8",
    mimeType: String? = null,
    historyUrl: String? = null,
): WebViewState

@Composable
fun rememberWebViewStateWithHTMLFile(
    fileName: String,
    readType: WebViewFileReadType,
): WebViewState
```

## WebContent

```kotlin
sealed class WebContent {
    data class Url(
        val url: String,
        val additionalHttpHeaders: Map<String, String> = emptyMap(),
    ) : WebContent()

    data class Data(
        val data: String,
        val baseUrl: String? = null,
        val encoding: String = "utf-8",
        val mimeType: String? = null,
        val historyUrl: String? = null,
    ) : WebContent()

    data class File(
        val fileName: String,
        val readType: WebViewFileReadType,
    ) : WebContent()

    data object NavigatorOnly : WebContent()
}

enum class WebViewFileReadType {
    ASSET_RESOURCES,
    COMPOSE_RESOURCE_FILES,
}
```

## LoadingState and WebViewError

```kotlin
sealed class LoadingState {
    data object Initializing : LoadingState()
    data class Loading(val progress: Float) : LoadingState()
    data object Finished : LoadingState()
}

@Immutable
data class WebViewError(
    val code: Int,
    val description: String,
    val isFromMainFrame: Boolean,
)
```

## WebViewNavigator

Programmatic navigation and script evaluation. Hoist with `rememberWebViewNavigator`.

```kotlin
@Stable
class WebViewNavigator(
    val coroutineScope: CoroutineScope,
    val requestInterceptor: RequestInterceptor? = null,
) {
    var canGoBack: Boolean
    var canGoForward: Boolean

    fun loadUrl(url: String, additionalHttpHeaders: Map<String, String> = emptyMap())
    fun loadHtml(
        html: String,
        baseUrl: String? = null,
        mimeType: String? = null,
        encoding: String? = "utf-8",
        historyUrl: String? = null,
    )
    fun loadHtmlFile(
        fileName: String,
        readType: WebViewFileReadType = WebViewFileReadType.ASSET_RESOURCES,
    )
    fun evaluateJavaScript(script: String, callback: ((String) -> Unit)? = null)
    fun navigateBack()
    fun navigateForward()
    fun reload()
    fun stopLoading()
}

@Composable
fun rememberWebViewNavigator(
    coroutineScope: CoroutineScope = rememberCoroutineScope(),
    requestInterceptor: RequestInterceptor? = null,
): WebViewNavigator
```

Bare HTTP(S) host URLs without a path gain a trailing slash before load (browser-style normalization).

## WebSettings

```kotlin
@Stable
class WebSettings {
    var isJavaScriptEnabled: Boolean          // default true
    var customUserAgentString: String?
    var zoomLevel: Double                     // default 1.0
    var supportZoom: Boolean                  // default true
    var allowFileAccessFromFileURLs: Boolean  // default false
    var allowUniversalAccessFromFileURLs: Boolean // default false
    var logSeverity: KLogSeverity             // default None
    var backgroundColor: Color                // default Transparent

    val androidWebSettings: PlatformWebSettings.AndroidWebSettings
    val desktopWebSettings: PlatformWebSettings.DesktopWebSettings
    val iOSWebSettings: PlatformWebSettings.IOSWebSettings
    val wasmJSWebSettings: PlatformWebSettings.WasmJSWebSettings
}
```

Each platform applies the subset it supports. Use the nested `*WebSettings` objects for engine-specific knobs.

## Cookies

```kotlin
interface CookieManager {
    suspend fun setCookie(url: String, cookie: Cookie)
    suspend fun getCookies(url: String): List<Cookie>
    suspend fun removeAllCookies()
    suspend fun removeCookies(url: String)
}

data class Cookie(
    val name: String,
    val value: String,
    val domain: String? = null,
    val path: String? = null,
    val expiresDate: Long? = null,
    val isSessionOnly: Boolean = false,
    val sameSite: Cookie.HTTPCookieSameSitePolicy? = null,
    val isSecure: Boolean? = null,
    val isHttpOnly: Boolean? = null,
    val maxAge: Long? = null,
)
```

Access the manager through `state.cookieManager`.

## Request interception

```kotlin
interface RequestInterceptor {
    fun onInterceptUrlRequest(
        request: WebRequest,
        navigator: WebViewNavigator,
    ): WebRequestInterceptResult
}

data class WebRequest(
    val url: String,
    val headers: MutableMap<String, String> = mutableMapOf(),
    val isForMainFrame: Boolean = false,
    val isRedirect: Boolean = false,
    val method: String = "GET",
)

sealed interface WebRequestInterceptResult {
    data object Allow : WebRequestInterceptResult
    data object Reject : WebRequestInterceptResult
    class Modify(val request: WebRequest) : WebRequestInterceptResult
}
```

Interception applies to navigator-driven main-frame navigations only.

## JS bridge

```kotlin
@Immutable
open class WebViewJsBridge(
    val navigator: WebViewNavigator? = null,
    val jsBridgeName: String = "kmpJsBridge",
) {
    fun register(handler: IJsMessageHandler)
    fun unregister(handler: IJsMessageHandler)
    fun clear()
}

interface IJsMessageHandler {
    fun methodName(): String
    fun handle(
        message: JsMessage,
        navigator: WebViewNavigator?,
        callback: (String) -> Unit,
    )
}

@Composable
fun rememberWebViewJsBridge(navigator: WebViewNavigator? = null): WebViewJsBridge
```

After each finished load (or URL change), the library injects `window.<jsBridgeName>` with `callNative(methodName, params, callback)`. Register handlers before or after attach; clear happens when `WebView` leaves composition.

## What's next

- [Getting started](/docs/webview/getting-started) — the same API used across a full browser chrome.
- [WebView overview](/docs/webview) — supported targets and platform backends.

---

# OS integration

URL: https://nucleusframework.dev/en/docs/os

Kotlin modules that expose native macOS, Windows, and Linux desktop capabilities such as notifications, system tray, global hotkeys, media controls, dark mode, and system colors.

The OS integration modules expose native desktop capabilities from Kotlin: notifications,
system tray, global hotkeys, media controls, dark mode, and system colors. Each capability is a
separate Gradle artifact, so you depend only on the modules you use.

## Coverage

| Feature | Module | macOS | Windows | Linux |
| --- | --- | --- | --- | --- |
| Cross-platform notifications | `notification-common` | yes | yes | yes |
| Native notifications (per OS) | `notification-macos` / `notification-windows` / `notification-linux` | yes | yes | yes |
| System tray | `composenativetray` | yes | yes | yes |
| Tray-anchored popup apps | `composenativetray-app` | yes | yes | yes |
| Global hotkeys | `global-hotkey` | yes | yes | yes |
| Media controls | `media-control` | yes | yes | yes |
| Dark mode | `darkmode-detector` | yes | yes | yes |
| Accent color and high contrast | `system-color` | yes | yes | yes |
| Hardware and OS info | `system-info` | yes | yes | yes |
| macOS menu bar | `menu-macos` | yes | — | — |
| Spell check | `spellcheck` | yes | yes | yes |
| FreeDesktop icon names | `freedesktop-icons` | — | — | yes |

Modules published by Nucleus use the group `dev.nucleusframework` and the artifact name
`nucleus.<module-name>`. The `composenativetray` module ships from a separate repository under
the same group, without the `nucleus.` prefix. From 2.1.0, `composenativetray` is the icon and
menu; `composenativetray-app` is `TrayApp` and depends on the Tao window backend.

## Cross-platform modules and platform modules

Some capabilities come in two forms. The cross-platform modules — `notification-common`,
`media-control`, and `darkmode-detector` — expose the intersection of what all three systems
support behind a single API. The platform modules, such as `notification-macos`,
`notification-windows`, and `notification-linux`, expose each system's native API directly, so
their surfaces differ from one platform to the next. Depend on a platform module when you need a
platform-specific feature, such as Windows toast progress bars, macOS interruption levels, or
MPRIS volume on Linux.

## How it works

Each module wraps its platform's native API through a JNI bridge that Nucleus ships and loads
for you. Notifications use the UserNotifications framework (`UNUserNotificationCenter`) on macOS,
WinRT toast notifications on Windows, and the FreeDesktop notification specification
(`org.freedesktop.Notifications`) over D-Bus on Linux. Media controls use SMTC on Windows and
MPRIS on Linux. Dark mode and accent color read reactively through `@Composable` functions, so
they participate in Compose recomposition when the system state changes.

## What's next

- [Cross-platform notifications](/docs/os/notifications) — send notifications from a single API on all three systems.
- [System tray](/docs/os/system-tray) — Compose-rendered tray icons and menus.
- [Global hotkeys](/docs/os/global-hotkey) — register shortcuts that fire even when your app is unfocused.
- [Dark mode](/docs/os/dark-mode) — read the system theme and observe changes.

---

# Cross-platform notifications

URL: https://nucleusframework.dev/en/docs/os/notifications

Send desktop notifications on macOS, Windows, and Linux from a single Kotlin API.

`notification-common` lets you send a desktop notification from Kotlin without writing per-platform code. It exposes one `notification(...)` function and a `NotificationManager` that detects the current OS at runtime and delegates to the matching native backend on macOS, Windows, or Linux.

The common API covers the shared subset: title, body text, a large image, a small icon, up to five action buttons, and lifecycle callbacks. For platform-specific features such as scheduling, categories, progress bars, or hero images, use the per-OS module directly.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.notification-common:<version>")
}
```

This pulls in the three platform modules transitively. Only the module matching the host OS is loaded at runtime.

## Send a notification

```kotlin
import dev.nucleusframework.notification.common.NotificationManager
import dev.nucleusframework.notification.common.notification

NotificationManager.initialize()

val n = notification(
    title = "Download complete",
    message = "report.pdf has been saved",
    onActivated = { openFile() },
) {
    button("Open") { openFile() }
    button("Show in folder") { showInFolder() }
}

n.send()
```

`title` and `message`, along with the callbacks, are parameters of the `notification(...)` function. The trailing lambda block declares action buttons with `button(title, onClick)` and, from 2.3, optional per-platform option blocks.

## Platform-specific options

Semantics that differ across OS stay in `linux { }`, `macos { }`, and `windows { }` blocks
inside the builder. Each block is applied only when the notification is delivered on that OS;
on every other platform it is a no-op. Shared fields (title, message, image, buttons, callbacks)
remain the base.

```kotlin
import dev.nucleusframework.notification.InterruptionLevel
import dev.nucleusframework.notification.common.notification
import dev.nucleusframework.notification.linux.Urgency
import dev.nucleusframework.notification.windows.ToastDuration
import dev.nucleusframework.notification.windows.ToastScenario

val n = notification(
    title = "Build failed",
    message = "see logs",
    onActivated = { openLogs() },
) {
    button("Open") { openLogs() }

    linux {
        urgency = Urgency.CRITICAL
        transient = true
        category = "device.error"
    }
    macos {
        interruptionLevel = InterruptionLevel.TIME_SENSITIVE
        relevanceScore = 0.9
        subtitle = "CI"
    }
    windows {
        scenario = ToastScenario.URGENT
        duration = ToastDuration.LONG
    }
}

n.send()
```

| Block | Scope type | Properties |
|-------|------------|------------|
| `linux { }` | `LinuxNotificationScope` | `urgency` (`Urgency`), `category`, `transient`, `resident`, `expireTimeout` (ms; `0` = never, unset/`-1` = server default) |
| `macos { }` | `MacNotificationScope` | `interruptionLevel` (`InterruptionLevel`), `relevanceScore` (`0.0..1.0`), `subtitle` |
| `windows { }` | `WindowsNotificationScope` | `scenario` (`ToastScenario`), `duration` (`ToastDuration`) |

`TIME_SENSITIVE` and `CRITICAL` on macOS require the matching Apple entitlement; without it the
system falls back to `ACTIVE`. `ToastScenario.URGENT` needs Windows 11+ to break through Focus
Assist. For deeper platform APIs (scheduling, progress bars, categories), use the
[macOS](/docs/os/notification-macos), [Windows](/docs/os/notification-windows), or
[Linux](/docs/os/notification-linux) modules directly.

## How it works

`NotificationManager` resolves the active platform on first use and delegates to the matching native bridge. Calling `NotificationManager.initialize()` sets the subsystem up eagerly; otherwise initialization happens lazily on the first `send()`.

The `notification(...)` function builds a `Notification` value. Calling `send()` on it forwards to `NotificationManager.send(notification)` and returns a `NotificationResult`. The same `Notification` instance can be sent more than once; each call produces a new OS notification.

Lifecycle callbacks are not guaranteed to run on a UI thread, so marshal back to your UI dispatcher before touching Compose state.

**macOS**

Delegates to [`notification-macos`](/docs/os/notification-macos). Requires user authorization and a bundled, signed app. Run the packaged binary during testing (`./gradlew runDistributable`).

**Windows**

Delegates to [`notification-windows`](/docs/os/notification-windows), which shows WinRT toasts.

**Linux**

Delegates to [`notification-linux`](/docs/os/notification-linux), which uses `org.freedesktop.Notifications` over D-Bus. Works on any desktop that runs a notification daemon, including GNOME, KDE, and Cinnamon.

## API reference

### Build a notification

Pass content and callbacks as function parameters, and declare buttons in the block:

```kotlin
val n = notification(
    title = "New message from Alice",
    message = "Have you seen the latest build?",
    onActivated = { openConversation() },
    onDismissed = { reason -> log.info("dismissed: $reason") },
    onFailed = { log.warn("notification failed to display") },
) {
    button("Reply") { /* … */ }
    button("Mute") { /* … */ }
}
```

- `onActivated: (() -> Unit)?` — the user clicked the notification body.
- `onDismissed: ((DismissReason) -> Unit)?` — the notification was dismissed. `DismissReason` is one of `USER_DISMISSED`, `TIMED_OUT`, `APPLICATION`, `UNKNOWN`.
- `onFailed: (() -> Unit)?` — the notification failed to display.

You can add up to five buttons; adding more throws. Platform blocks may be called more than
once; later calls merge into the same scope instance for that platform.

### Send

`send()` returns a `NotificationResult`:

```kotlin
when (val result = n.send()) {
    is NotificationResult.Success -> result.handle.dismiss()
    is NotificationResult.Failure -> log.warn(result.reason)
}
```

`NotificationResult.Success` carries a `NotificationHandle`; call `handle.dismiss()` to close the notification programmatically while it is still visible. `NotificationResult.Failure` carries a `reason` string.

### Check availability

```kotlin
if (!NotificationManager.isAvailable()) {
    // The current OS or sandbox does not allow notifications.
}
```

macOS silently drops notifications from unbundled apps. Always test against the packaged binary.

## What's next

- [macOS notifications](/docs/os/notification-macos) — authorization, scheduling, categories, and attachments.
- [Windows notifications](/docs/os/notification-windows) — toast content, progress bars, and history.
- [Linux notifications](/docs/os/notification-linux) — urgency hints, actions, and the D-Bus daemon.

---

# Notifications on macOS

URL: https://nucleusframework.dev/en/docs/os/notification-macos

Kotlin bindings for Apple's UserNotifications framework, covering authorization, categories, attachments, text input, schedules, and interruption levels.

The `notification-macos` module lets you drive Apple's UserNotifications framework from Kotlin.
You request authorization, schedule notifications, register action categories with text input,
attach media, and handle user responses through `NotificationCenter` and a typed delegate.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.notification-macos:<version>")
}
```

## Send a notification

Request authorization, then submit a `NotificationRequest` with `NotificationCenter.add`:

```kotlin
import dev.nucleusframework.notification.*

NotificationCenter.requestAuthorization(
    setOf(AuthorizationOption.ALERT, AuthorizationOption.SOUND, AuthorizationOption.BADGE),
) { granted, error ->
    if (!granted) return@requestAuthorization

    NotificationCenter.add(
        NotificationRequest(
            identifier = "greeting",
            content = NotificationContent(
                title = "Hello",
                body = "Welcome to Nucleus",
                sound = NotificationSound.Default,
                interruptionLevel = InterruptionLevel.TIME_SENSITIVE,
            ),
            trigger = NotificationTrigger.TimeInterval(interval = 5.0),
        ),
    )
}
```

To deliver immediately, leave `trigger` unset (it defaults to `null`).

macOS only delivers notifications from a bundled, bundle-identified app. During development,
run `./gradlew runDistributable` or `./gradlew runGraalvmNative` — a plain `./gradlew run`
produces an un-bundled JVM process that the system ignores silently.

## How it works

Each API is a typed wrapper over the matching UserNotifications call, reached through a JNI
bridge. `NotificationCenter` is a singleton that forwards `UNUserNotificationCenterDelegate`
callbacks to the `NotificationCenterDelegate` you register. On non-macOS platforms every method
is a no-op; check `NotificationCenter.isAvailable` first.

Categories let you register reusable sets of action buttons — including text-input actions —
ahead of time, then reference them by identifier from a `NotificationContent`. The system stores
the category set, so each request only carries the `categoryIdentifier` string.

Delegate callbacks are not dispatched on AWT or Swing threads. Marshal to the active UI
dispatcher before you touch UI state from `willPresent` or `didReceive`.

## API reference

### Check availability

```kotlin
if (NotificationCenter.isAvailable) {
    // running on macOS with a loaded native bridge and an app bundle
}
```

### Request authorization

`requestAuthorization` takes a set of `AuthorizationOption` values and a callback reporting the
result:

```kotlin
NotificationCenter.requestAuthorization(
    setOf(AuthorizationOption.ALERT, AuthorizationOption.SOUND, AuthorizationOption.BADGE),
) { granted, error -> /* … */ }
```

Available options: `BADGE`, `SOUND`, `ALERT`, `CRITICAL_ALERT`,
`PROVIDES_APP_NOTIFICATION_SETTINGS`, `PROVISIONAL`, `TIME_SENSITIVE`.

### Register categories with action buttons

Build a `NotificationCategory` from `NotificationAction` or `TextInputNotificationAction`
entries, then register the full set with `setNotificationCategories`:

```kotlin
val category = NotificationCategory(
    identifier = "MESSAGE",
    actions = listOf(
        TextInputNotificationAction(
            identifier = "REPLY",
            title = "Reply",
            textInputButtonTitle = "Send",
            textInputPlaceholder = "Type a reply…",
        ),
    ),
    options = setOf(CategoryOption.CUSTOM_DISMISS_ACTION),
)
NotificationCenter.setNotificationCategories(setOf(category))
```

Reference the category from a notification through `NotificationContent.categoryIdentifier`.

### Attach media

`NotificationAttachment.url` is a file-path string, not a `java.net.URI`:

```kotlin
val request = NotificationRequest(
    identifier = "screenshot",
    content = NotificationContent(
        title = "Screenshot saved",
        body = "Click to preview",
        attachments = listOf(
            NotificationAttachment(identifier = "img", url = imageFile.absolutePath),
        ),
    ),
)
```

### Schedule with triggers

| Trigger | Use case |
| --- | --- |
| `trigger = null` (default) | fire now |
| `NotificationTrigger.TimeInterval(interval, repeats)` | delay or recurring (repeats require `interval >= 60`) |
| `NotificationTrigger.Calendar(dateComponents, repeats)` | "every Monday at 9 am" via `DateComponents` |

### Handle responses with a delegate

Implement `NotificationCenterDelegate` to control foreground presentation and react to taps,
action selections, and text-input responses:

```kotlin
NotificationCenter.setDelegate(object : NotificationCenterDelegate {
    override fun willPresent(notification: DeliveredNotification): Set<PresentationOption> =
        setOf(PresentationOption.BANNER, PresentationOption.SOUND)

    override fun didReceive(response: NotificationResponse) { /* … */ }
})
```

`willPresent` returns the presentation options to use while the app is in the foreground; return
an empty set to handle the notification silently. `NotificationResponse.userText` carries the
text a user typed into a `TextInputNotificationAction`.

### Inspect and remove notifications

`getPendingNotifications` and `getDeliveredNotifications` take callbacks and report what is queued
or on screen. Remove entries with `removePendingNotifications(ids)` /
`removeAllPendingNotifications()` and `removeDeliveredNotifications(ids)` /
`removeAllDeliveredNotifications()`.

## Notes

- Sandboxed apps need the notifications entitlement. Point the macOS `entitlementsFile` property
  in the Nucleus Gradle DSL at a `.entitlements` file that declares it.
- For alerts that bypass Focus modes, set `interruptionLevel = InterruptionLevel.CRITICAL` and
  request `AuthorizationOption.CRITICAL_ALERT`.
- A bundle identifier mismatch is the most common cause of silent failure — verify that
  `NucleusApp.appId` matches the bundle id in the packaged `.app`.

## What's next

- [Cross-platform notifications](/docs/os/notifications) — the shared `NotificationManager` API.
- [Notifications on Windows](/docs/os/notification-windows) — toast notifications via `WindowsNotificationCenter`.
- [Notifications on Linux](/docs/os/notification-linux) — freedesktop notifications via `LinuxNotificationCenter`.
- [Code signing](/docs/packaging/code-signing) — sign and bundle the app so macOS delivers its notifications.

---

# Notifications on Windows

URL: https://nucleusframework.dev/en/docs/os/notification-windows

Send Windows toast notifications from Kotlin with adaptive layouts, images, buttons, text input, and progress bars.

`notification-windows` lets you send Windows 10/11 toast notifications from Kotlin. It wraps the WinRT `ToastNotificationManager` API in a DSL that covers adaptive text, images, progress bars, selection boxes, text inputs, and headers, and works for both MSIX-packaged and unpackaged (EXE/MSI) apps.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.notification-windows:<version>")
}
```

## Send a notification

Call `initialize()` once before showing any toast, then build content with the `toast { }` DSL and pass it to `show`:

```kotlin
import dev.nucleusframework.notification.windows.*

WindowsNotificationCenter.initialize()

WindowsNotificationCenter.show(
    toast {
        visual {
            text("Build finished")
            text("artifact-2.0.0.zip uploaded")
            heroImage("https://example.com/hero.png")
        }
        actions {
            button("Open", arguments = "open")
            button("Show in folder", arguments = "folder")
        }
    },
)
```

Every method is a no-op on non-Windows platforms. Check `WindowsNotificationCenter.isAvailable` before calling if you share code across operating systems.

## How it works

A toast on Windows is an XML payload dispatched through `ToastNotificationManager` and identified by an AUMID (Application User Model ID). The library resolves the AUMID for you based on how the app is packaged.

- **MSIX / APPX**: the AUMID resolves automatically from the package identity.
- **Unpackaged (EXE/MSI/dev)**: Nucleus derives the AUMID from `NucleusApp.aumid` and registers it on the current process.
- Override it with `WindowsNotificationCenter.initialize(aumid = "Vendor.App")`.

Unpackaged apps need a Start Menu `.lnk` shortcut whose AUMID property matches the one used at runtime. Without it, toasts may fail to appear or to persist in Action Center. `initialize` picks the policy automatically: `ShortcutPolicy.REQUIRE_CREATE` for installed apps and `REQUIRE_NO_CREATE` in dev mode, where no shortcut is created and a warning is logged. Pass `shortcutPolicy = ShortcutPolicy.REQUIRE_CREATE` to force it. The Nucleus Gradle plugin sets the shortcut up when you build the Windows installer formats.

## API reference

### Build adaptive content

The `toast { }` builder exposes `visual`, `actions`, `audio`, and `header` blocks. Enum values are `UPPER_SNAKE_CASE`.

```kotlin
toast {
    visual {
        text("Sync in progress")
        appLogo("logo.png", crop = AdaptiveImageCrop.CIRCLE)
        progressBar(
            status = "Uploading",
            title = "report.pdf",
            valueStringOverride = "3 of 5 files",
            value = 0.6,
        )
    }
    actions {
        button("Pause", arguments = "pause")
        button("Cancel", arguments = "cancel", activationType = ActivationType.BACKGROUND)
    }
    audio(ToastAudioSource.REMINDER)
    scenario = ToastScenario.REMINDER
}
```

`ToastActionsBuilder` provides `textBox`, `selectionBox`, `button`, and `contextMenuItem`. The `status` string is the only required argument of `progressBar`.

### Listen for events

Register a listener with `addListener`. The callbacks receive flat parameters, not event-argument objects:

```kotlin
WindowsNotificationCenter.addListener(object : ToastNotificationListener {
    override fun onActivated(
        tag: String,
        group: String,
        arguments: String,
        userInputs: Map<String, String>,
    ) { /* ... */ }

    override fun onDismissed(tag: String, group: String, reason: DismissalReason) { /* ... */ }

    override fun onFailed(tag: String, group: String, errorCode: Int) { /* ... */ }
})
```

Remove a listener with `WindowsNotificationCenter.removeListener(listener)`.

### Update an existing toast

Show a toast with a `tag` and `group`, then push new data-bound values with `update`. This drives progress bars without replacing the toast:

```kotlin
WindowsNotificationCenter.update(
    tag = "upload",
    group = "transfers",
    data = ToastNotificationData(
        sequenceNumber = 1,
        values = mapOf("progressValue" to "0.8"),
    ),
)
```

`ToastNotificationData` takes `sequenceNumber` first (a monotonically increasing number that avoids races) and the `values` map second.

### Read the Action Center history

`getHistory` delivers the toasts currently in Action Center through a callback. Each `HistoryEntry` exposes `tag` and `group`:

```kotlin
WindowsNotificationCenter.getHistory { entries, error ->
    entries.forEach { entry -> println("${entry.tag} / ${entry.group}") }
}
```

### Remove toasts

- `remove(tag, group)` removes a single toast.
- `removeGroup(group)` removes every toast in a group.
- `clearAll()` clears the app's Action Center entries.
- `uninitialize()` releases native resources on shutdown.

## Notes

- Keep the AUMID consistent across the Start Menu shortcut, your `nucleus { }` Gradle config, and runtime. A mismatch is the usual cause of a toast that appears once and then never again.
- `tag` and `group` are limited to 16 characters each.
- Hero images and app logos accept remote `http(s)://` URLs in unpackaged apps as long as the URL resolves quickly. For offline-safe behavior, ship a local file via `ms-appx:///` (MSIX) or `file:///` (unpackaged).

## What's next

- [Notifications overview](/docs/os/notifications) — the cross-platform notification DSL.
- [Notifications on macOS](/docs/os/notification-macos) — `UNUserNotificationCenter` from Kotlin.
- [Notifications on Linux](/docs/os/notification-linux) — Freedesktop notifications over D-Bus.

---

# Notifications on Linux

URL: https://nucleusframework.dev/en/docs/os/notification-linux

Send freedesktop desktop notifications over D-Bus from Kotlin, with urgency, hints, sounds, and action callbacks.

`notification-linux` sends desktop notifications through the `org.freedesktop.Notifications`
D-Bus service, which GNOME, KDE, Cinnamon, Xfce, and other desktops implement. It maps the
freedesktop Desktop Notifications specification to Kotlin over GIO/GDBus, with no JNA or
Java D-Bus dependency.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.notification-linux:<version>")
}
```

This pulls in [`freedesktop-icons`](/docs/os/freedesktop-icons) transitively for typesafe icon names.

## Send a notification

Build a `Notification` and pass it to `LinuxNotificationCenter.notify`, which returns the
server-assigned ID:

```kotlin
import dev.nucleusframework.notification.linux.LinuxNotificationCenter
import dev.nucleusframework.notification.linux.Notification
import dev.nucleusframework.notification.linux.NotificationAction
import dev.nucleusframework.notification.linux.NotificationHints
import dev.nucleusframework.notification.linux.Urgency
import dev.nucleusframework.freedesktop.icons.FreedesktopIcon

val id: Int = LinuxNotificationCenter.notify(
    Notification(
        appName = "MyApp",
        summary = "Build finished",
        body = "myapp-2.0.0.zip is ready",
        appIcon = FreedesktopIcon.Status.DIALOG_INFORMATION,
        hints = NotificationHints(urgency = Urgency.NORMAL),
        actions = listOf(NotificationAction("open", "Open")),
    ),
)
```

`notify` returns an ID greater than `0` on success, or `0` on failure.

Check `LinuxNotificationCenter.isAvailable` before sending. It returns `false` on non-Linux
platforms or when the native library could not be loaded.

## How it works

`LinuxNotificationCenter` talks to `org.freedesktop.Notifications` over D-Bus through JNI.
Each call to `notify` invokes the `Notify` method and returns the ID the server assigns.
Passing a non-zero `replacesId` atomically replaces an existing notification with that ID.

Action clicks and close events arrive later as D-Bus signals. Register a
`LinuxNotificationListener` to receive them; signal monitoring starts when the first listener is
added and stops when the last is removed. Callbacks are dispatched on the Swing EDT.

The specification is uniform, but servers differ in what they render. GNOME Shell in particular
is unreliable about `appIcon`; set `hints.imagePath` for consistent iconography. Call
`getServerInformation()` at startup to log the active server, and `getCapabilities()` to see
what the server supports.

## API reference

### Set urgency

```kotlin
hints = NotificationHints(urgency = Urgency.CRITICAL)
```

`Urgency` is `LOW`, `NORMAL`, or `CRITICAL`. Critical notifications typically bypass
do-not-disturb and do not auto-expire.

### Add action buttons

Each `NotificationAction` has a `key` and a `label`. Use `NotificationAction.DEFAULT_KEY`
for the action bound to clicking the notification body.

```kotlin
val notification = Notification(
    appName = "MyApp",
    summary = "New message",
    actions = listOf(
        NotificationAction("reply", "Reply"),
        NotificationAction("archive", "Archive"),
    ),
)
```

### Receive callbacks

```kotlin
import dev.nucleusframework.notification.linux.CloseReason
import dev.nucleusframework.notification.linux.LinuxNotificationListener

LinuxNotificationCenter.addListener(object : LinuxNotificationListener {
    override fun onActionInvoked(notificationId: Int, actionKey: String) { /* … */ }
    override fun onClosed(notificationId: Int, reason: CloseReason) { /* … */ }
})
```

`CloseReason` is `EXPIRED`, `DISMISSED`, `CLOSED`, or `UNDEFINED`. Remove a listener with
`removeListener`.

### Embed inline image data

Use `ImageData` when you have raw pixels rather than a file path — for example, a generated
avatar. The bytes must be in RGB or RGBA order:

```kotlin
import dev.nucleusframework.notification.linux.ImageData

hints = NotificationHints(
    imageData = ImageData(
        width = width,
        height = height,
        rowstride = width * 4,
        hasAlpha = true,
        data = bytes,
    ),
)
```

`channels` defaults to `4` when `hasAlpha` is `true` and `3` otherwise, and `bitsPerSample`
defaults to `8`.

### Play a sound

```kotlin
import dev.nucleusframework.notification.linux.NotificationSound

hints = NotificationHints(
    soundName = NotificationSound.Notification.DIALOG_INFORMATION,
)
```

Sound names are grouped by category (`Alert`, `Notification`, `Action`, `InputFeedback`,
`Game`); use `NotificationSound.Custom("x-myapp-…")` for names outside the specification.

### Close a notification

```kotlin
LinuxNotificationCenter.closeNotification(id)
```

## Notes

- Under `Xvfb` or a headless CI, `notify` returns without error, but no daemon displays the
  notification.
- If notifications work in development but not under Flatpak, check the
  `org.freedesktop.Notifications` portal permission in your manifest.

## What's next

- [freedesktop-icons](/docs/os/freedesktop-icons) — typesafe icon names for `appIcon` and `imagePath`.
- [Notifications overview](/docs/os/notifications) — the cross-platform notification API.
- [Notifications on macOS](/docs/os/notification-macos) and [Windows](/docs/os/notification-windows).

---

# System tray

URL: https://nucleusframework.dev/en/docs/os/system-tray

Render a tray icon and a native context menu from Compose on macOS, Windows, and Linux.

The system tray API draws a tray icon and its native context menu from Compose on macOS,
Windows, and Linux. The icon is anything Compose can draw, the menu is a Kotlin DSL, and both
react to Compose state. `Tray()` is a single composable that hands the rendered icon and menu
to the native tray API of the current OS.

System tray ships from [`NucleusFramework/ComposeNativeTray`](https://github.com/NucleusFramework/ComposeNativeTray) with its own release cycle. Pin it separately from Nucleus. From 2.1.0 the library is two artifacts:

- `dev.nucleusframework:composenativetray` — `Tray` and the menu DSL. Works in Compose Desktop's `application { }` and in `nucleusApplication { }`.
- `dev.nucleusframework:composenativetray-app` — `TrayApp`. Requires `nucleusApplication { }`. See [Tray apps](/docs/os/tray-app).

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:composenativetray:<version>")
}
```

Add `composenativetray-app` only when you use [`TrayApp`](/docs/os/tray-app).

## Add a tray icon

`Tray` is a plain composable. Call it from `nucleusApplication` (or from Compose Desktop's `application`):

```kotlin
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.composenativetray.tray.api.Tray
import kotlin.system.exitProcess

fun main() = nucleusApplication {
    Tray(
        icon = Icons.Default.Favorite,
        tooltip = "My App",
        primaryAction = { showWindow() },
    ) {
        Item(label = "Show window") { showWindow() }
        Divider()
        Item(label = "Quit") { exitProcess(0) }
    }
}
```

## How it works

`Tray()` is a composable. Its icon is rasterised from Compose whenever the slot's state
changes, then handed to the native tray API of the current OS. The menu lambda runs inside a
DSL scope that re-evaluates on recomposition, so adding, removing, or relabelling items follows
the usual Compose recomposition rules.

The tray participates in your Compose state tree: it updates through recomposition, without
explicit rebuild calls or separate `.ico`/`.png`/`.icns` files to maintain.

Each platform maps to its native tray mechanism:

**macOS**

Backed by `NSStatusItem` in the menu bar. Vector icons render at native DPI, with optional tinting via the `tint` parameter.

**Windows**

Backed by `Shell_NotifyIcon`. Vector input is rasterised to a 32×32 `.ico` per scale factor. Pass a hand-authored `.ico` via `windowsIcon` for exact control.

**Linux (GNOME)**

Uses StatusNotifierItem (KStatusNotifierItem). On stock GNOME this requires the AppIndicator extension; on Ubuntu it works out of the box.

**Linux (KDE)**

StatusNotifierItem is native to Plasma. Hover tooltips and badges work where Plasma supports them.

## Set the icon source

The `icon` parameter accepts an `ImageVector`, a `Painter`, or a Compose Multiplatform
`DrawableResource`. For full control, use `iconContent` to draw the icon with any composable:

```kotlin
// ImageVector
Tray(icon = Icons.Default.Notifications, tint = Color.White, tooltip = "App") { /* … */ }

// Painter
Tray(icon = painterResource("icon.png"), tooltip = "App") { /* … */ }

// Compose Multiplatform DrawableResource
Tray(icon = Res.drawable.app_icon, tooltip = "App") { /* … */ }

// Fully custom — any composable
Tray(
    iconContent = {
        Box(Modifier.size(24.dp).background(Color.Red, CircleShape)) {
            Text("3", color = Color.White, modifier = Modifier.align(Alignment.Center))
        }
    },
    tooltip = "3 notifications",
) { /* … */ }
```

## Use platform-specific icons

To use a native `.ico` on Windows and a vector elsewhere, set `windowsIcon` and `macLinuxIcon`:

```kotlin
Tray(
    windowsIcon = painterResource("icon.ico"),
    macLinuxIcon = Icons.Default.Notifications,
    tint = Color.White,
    tooltip = "My App",
) { /* menu */ }
```

## Handle the primary action

`primaryAction` fires on left-click (macOS/Windows) or single click (Linux, desktop-dependent).
Without it, the menu opens on every click.

```kotlin
Tray(
    icon = Icons.Default.Favorite,
    tooltip = "My App",
    primaryAction = { showWindow() },
) {
    Item(label = "Quit") { exitProcess(0) }
}
```

## What's next

- [Tray menu DSL](/docs/os/tray-menu-dsl) — items, checkables, submenus, dividers, and reactive composition.
- [Tray apps](/docs/os/tray-app) — make the tray icon open a Compose popup window.
- [WebView](/docs/webview) — another Nucleus component shipped from its own repository.
- [PDF reader](/docs/pdf) — one PDF API across Android, iOS, web, and desktop.

---

# Tray menu DSL

URL: https://nucleusframework.dev/en/docs/os/tray-menu-dsl

Build the tray context menu from Kotlin with items, checkable items, submenus, dividers, and conditional content.

The tray menu DSL lets you build the tray context menu from Kotlin, inside the `Tray()`
trailing lambda. It ships in `composenativetray` — no extra artifact. The menu participates in
Compose recomposition: when a `mutableStateOf` changes, the labels, checkmarks, icons, and
entire branches update in the native menu.

The DSL provides four item types — `Item`, `CheckableItem`, `SubMenu`, and `Divider`. Every
item type accepts an icon as an `ImageVector`, `Painter`, `DrawableResource`, or `@Composable`.
Because the menu is ordinary Kotlin code, you can use `if` branches and computed values directly.

## Add menu items

Add an `Item` for each action. Pass `isEnabled = false` to disable an item, and `icon` to show
a leading icon:

```kotlin
Tray(icon = Icons.Default.Favorite, tooltip = "App") {
    Item(label = "Open settings") { openSettings() }
    Item(label = "Disabled", isEnabled = false) {}
    Item(label = "Export", icon = Icons.Default.Upload) { export() }
}
```

## Add checkable items

Use `CheckableItem` for toggles. Each platform renders its native checkmark style. The
`checked` parameter reflects the current state, and the trailing lambda receives the new value:

```kotlin
var notifications by remember { mutableStateOf(true) }
var darkMode by remember { mutableStateOf(false) }

Tray(icon = Icons.Default.Favorite, tooltip = "App") {
    CheckableItem(label = "Notifications", checked = notifications, onCheckedChange = {
        notifications = it
    })
    CheckableItem(label = "Dark mode", icon = Icons.Default.DarkMode, checked = darkMode, onCheckedChange = {
        darkMode = it
    })
}
```

## Add submenus

Nest a `SubMenu` to group related items. Submenus can nest to any depth:

```kotlin
Tray(icon = Icons.Default.Favorite, tooltip = "App") {
    SubMenu(label = "Tools", icon = Icons.Default.Build) {
        Item(label = "Terminal") { openTerminal() }
        Item(label = "File manager") { openFiles() }
        SubMenu(label = "More") {
            Item(label = "Calculator") { openCalc() }
        }
    }
}
```

## Add dividers

Insert a `Divider` to separate groups of items:

```kotlin
Tray(icon = Icons.Default.Favorite, tooltip = "App") {
    Item(label = "Show window") { show() }
    Divider()
    Item(label = "Settings") { settings() }
    Item(label = "About") { about() }
    Divider()
    Item(label = "Quit") { exitProcess(0) }
}
```

## Build a reactive menu

Because the DSL is Compose code, you can show items conditionally and compute labels from
state. Write the menu like any other Compose tree:

```kotlin
var isConnected by remember { mutableStateOf(false) }
var showAdvanced by remember { mutableStateOf(false) }

Tray(icon = Icons.Default.Wifi, tooltip = "Network") {
    Item(label = if (isConnected) "Disconnect" else "Connect") {
        isConnected = !isConnected
    }

    CheckableItem(label = "Advanced options", checked = showAdvanced, onCheckedChange = {
        showAdvanced = it
    })

    if (showAdvanced) {
        Divider()
        SubMenu(label = "Advanced") {
            Item(label = "DNS settings") {}
            Item(label = "Proxy") {}
        }
    }

    Divider()
    Item(label = "Quit") { exitProcess(0) }
}
```

## How it works

The native menu rebuilds itself when the state it reads mutates. You do not call `refresh()`
and you do not diff the menu yourself — Compose tracks the state reads and Nucleus applies the
changes to the platform menu.

## What's next

- [System tray](/docs/os/system-tray) — icon types, primary action, and platform-specific icons.
- [Tray apps](/docs/os/tray-app) — show a popup window instead of, or alongside, the menu.

---

# Tray-anchored apps

URL: https://nucleusframework.dev/en/docs/os/tray-app

TrayApp anchors a Compose popup window to a system tray icon so you can build menu bar apps in Kotlin.

`TrayApp` anchors a full Compose window to a system tray icon: left-click the icon to open the
window beside it, and click away to close it. It implements the menu bar app pattern used by
tools such as Bartender, iStat Menus, and Hidden Bar.

From 2.1.0, `TrayApp` lives in `composenativetray-app`, not in the core tray artifact.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:composenativetray-app:<version>")
}
```

`composenativetray-app` pulls in [`composenativetray`](/docs/os/system-tray) and the Nucleus Tao
window backend. `TrayApp` is an extension on `NucleusApplicationScope` — launch with
`nucleusApplication { }`.

## Create a tray app

Pass an icon, a tooltip, a window size, and the Compose content to render in the popup:

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material.MaterialTheme
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Dashboard
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.composenativetray.trayapp.TrayApp

fun main() = nucleusApplication {
    TrayApp(
        icon = Icons.Default.Dashboard,
        tooltip = "Quick dashboard",
        windowSize = DpSize(300.dp, 400.dp),
    ) {
        Column(Modifier.fillMaxSize().padding(16.dp)) {
            Text("Dashboard", style = MaterialTheme.typography.h6)
            Spacer(Modifier.height(8.dp))
            Text("CPU: 42%")
            Text("RAM: 8.2 GB")
        }
    }
}
```

## How it works

`TrayApp` is a tray icon plus a transparent, undecorated, always-on-top Compose window. The
library tracks the tray icon's screen position and places the window next to it with the correct
offset for each operating system.

Click-outside-to-dismiss is wired to the OS focus-loss event, so the popup closes the way native
menu bar windows do on each desktop.

## Control visibility and size with state

Hold a `TrayAppState` to show, hide, resize, or change the dismiss mode from your own code:

```kotlin
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Dashboard
import androidx.compose.foundation.layout.Column
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.composenativetray.trayapp.TrayApp
import dev.nucleusframework.composenativetray.trayapp.TrayWindowDismissMode
import dev.nucleusframework.composenativetray.trayapp.rememberTrayAppState

fun main() = nucleusApplication {
    val state = rememberTrayAppState(
        initialWindowSize = DpSize(350.dp, 500.dp),
        initiallyVisible = false,
        initialDismissMode = TrayWindowDismissMode.AUTO,
    )

    TrayApp(
        icon = Icons.Default.Dashboard,
        tooltip = "Dashboard",
        state = state,
    ) {
        Column {
            Text("Dashboard")
            Button(onClick = { state.hide() }) { Text("Close") }
            Button(onClick = { state.setWindowSize(500.dp, 600.dp) }) { Text("Resize") }
        }
    }
}
```

## Add a context menu

Left-click opens the popup; right-click opens a classic menu:

```kotlin
import androidx.compose.material.Text
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Dashboard
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.composenativetray.trayapp.TrayApp
import kotlin.system.exitProcess

fun main() = nucleusApplication {
    TrayApp(
        icon = Icons.Default.Dashboard,
        tooltip = "Dashboard",
        menu = {
            Item(label = "Settings") { openSettings() }
            Divider()
            Item(label = "Quit") { exitProcess(0) }
        },
    ) {
        Text("Popup content")
    }
}
```

## Hide the Dock icon on macOS

On the Tao backend, do not set `LSUIElement` in `Info.plist`. Pass
`dockIconFollowsWindows = true` to `nucleusApplication` instead:

```kotlin
fun main() = nucleusApplication(dockIconFollowsWindows = true) {
    TrayApp(
        icon = Icons.Default.Dashboard,
        tooltip = "Dashboard",
    ) {
        Text("Popup content")
    }
}
```

The app starts as an accessory (no Dock icon, no menu bar). A Dock tile appears only while at
least one `DecoratedWindow` with `hiddenFromDock = false` is visible. `TrayApp` popups are
standalone panels and never count, so a tray-only app stays out of the Dock. The flag is
ignored off macOS and on the AWT backend. See
[Hiding from the taskbar/Dock](/docs/tao/decorated-window#hiding-from-the-taskbardock).

## API reference

### TrayApp window options

| Parameter | Default | Notes |
| --- | --- | --- |
| `windowSize` | `DpSize(300.dp, 200.dp)` | initial size |
| `visibleOnStart` | `false` | show immediately |
| `enterTransition` / `exitTransition` | platform default | animations |
| `undecorated` | `true` | no chrome |
| `resizable` | `false` | user resize |
| `windowsTitle` | `""` | window title (used on Linux and when decorated) |
| `horizontalOffset` / `verticalOffset` | 0 / platform default | nudge against the tray anchor |

### TrayAppState

| API | Description |
| --- | --- |
| `isVisible: StateFlow<Boolean>` | current visibility |
| `show() / hide() / toggle()` | imperative control |
| `setWindowSize(size)` | resize on the fly |
| `setDismissMode(mode)` | `AUTO` (click outside closes) or `MANUAL` |
| `onVisibilityChanged(cb)` | observe transitions |

## Notes

- From 2.1.0, `getTrayPosition()` and `TrayPosition` live in `composenativetray-app`
  (`dev.nucleusframework.composenativetray.trayapp`). They need the Tao backend for screen
  geometry. Prefer `TrayApp` if you only need a popup next to the icon.
- The popup is a standalone native panel, not a `DecoratedWindow`. File drops reach Compose
  `dragAndDropTarget` the same way as a regular window (Windows and macOS from 2.5.3, Linux
  from 2.5.4). Wheel and trackpad scroll uses the same AWT mapping as the main window (Windows
  from 2.5.2, macOS from 2.5.4, Linux from 2.5.6). A hidden Windows popup no longer submits GPU
  frames (2.5.2). A frame scheduled from inside a scene pass — a scrollbar drag subcomposing new
  lazy items, for example — is posted to the main queue instead of rendered inline, so it cannot
  re-enter measure and layout (2.5.7).
- On macOS the panel is stationary and joins all spaces, so "Click wallpaper to reveal desktop"
  on Sonoma and later leaves it in place and `TrayApp` dismisses it itself (2.5.5). Clicks on the
  status item and on its context menu do not count as clicks outside the popup, so a right-click
  opens the menu instead of hiding the popup (2.5.5).

## What's next

- [System tray](/docs/os/system-tray) — the tray icon API that `TrayApp` builds on.
- [Tray menu DSL](/docs/os/tray-menu-dsl) — build the right-click menu.
- [Single instance](/docs/lifecycle/single-instance) — re-launching from a `.app` re-shows the popup instead of starting a second process.

---

# Global hotkeys

URL: https://nucleusframework.dev/en/docs/os/global-hotkey

Register OS-wide keyboard shortcuts that fire even when your app does not have focus.

`global-hotkey` lets you register system-wide keyboard shortcuts from Kotlin on macOS, Windows, and Linux. A global hotkey fires when its key combination is pressed, regardless of which window has focus, which is what media players, screen-capture tools, and accessibility utilities rely on.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.global-hotkey:<version>")
}
```

## Register a hotkey

Initialize the manager once, register a combination, and keep the returned handle to unregister it later:

```kotlin
import dev.nucleusframework.globalhotkey.GlobalHotKeyManager
import dev.nucleusframework.globalhotkey.HotKeyModifier
import java.awt.event.KeyEvent

GlobalHotKeyManager.initialize()

val handle = GlobalHotKeyManager.register(
    keyCode = KeyEvent.VK_F12,
    modifiers = HotKeyModifier.CONTROL + HotKeyModifier.SHIFT,
) { keyCode, modifiers ->
    println("Hotkey pressed")
}

// later
GlobalHotKeyManager.unregister(handle)
GlobalHotKeyManager.shutdown()
```

`register` returns a `Long` handle, or `-1` if the binding could not be registered. The listener receives the `keyCode` and `modifiers` bitmask that triggered it.

To scope a hotkey to a Composable's lifetime, register in `DisposableEffect` and unregister in `onDispose`:

```kotlin
DisposableEffect(Unit) {
    GlobalHotKeyManager.initialize()
    val handle = GlobalHotKeyManager.register(
        keyCode = KeyEvent.VK_K,
        modifiers = 0 + HotKeyModifier.META,
    ) { _, _ ->
        showQuickSwitcher()
    }

    onDispose {
        GlobalHotKeyManager.unregister(handle)
    }
}
```

## How it works

`GlobalHotKeyManager` is a thread-safe singleton. `initialize()` loads the native bridge for the current platform and starts its message loop: `RegisterHotKey` on Windows, Carbon `RegisterEventHotKey` on macOS, and `XGrabKey` (X11) or the `org.freedesktop.portal.GlobalShortcuts` D-Bus portal (Wayland) on Linux.

Each `register(...)` call maps the portable `modifiers` bitmask to the native modifier flags and returns a handle you pass back to `unregister`. When a registration fails, `register` returns `-1` and sets `lastError` to a description of the failure.

Listeners are invoked from the native message loop, not the UI thread. Marshal back to your UI or audio thread yourself before touching shared state.

### Linux portal registrations

On Wayland, the portal persists grants by `(app_id, shortcut_id)`. From 2.3 the Linux path
derives a **stable** `shortcut_id` from modifiers + keyCode (`nucleus_m{mods}_k{keyCode}`) so
the same chord keeps the same id across launches and registration order — without that, each
start re-prompted the user.

`register(...)` calls are also **debounced** into a single `BindShortcuts` dialog. After a
loop of registrations, either wait for the flush or call `commitRegistrations()` to force it:

```kotlin
val a = GlobalHotKeyManager.register(KeyEvent.VK_K, 0 + HotKeyModifier.CONTROL) { _, _ -> /* … */ }
val b = GlobalHotKeyManager.register(KeyEvent.VK_L, 0 + HotKeyModifier.CONTROL) { _, _ -> /* … */ }
GlobalHotKeyManager.commitRegistrations() // one portal dialog for both

// Debug: portal id for a handle (Linux only; null elsewhere)
val id: String? = GlobalHotKeyManager.portalShortcutId(a)
```

## API reference

### Register a key combination

```kotlin
fun register(
    keyCode: Int,
    modifiers: Int = 0,
    description: String? = null,
    listener: HotKeyListener,
): Long
```

`keyCode` is an AWT virtual key code such as `KeyEvent.VK_F12`. `modifiers` is a bitmask built from `HotKeyModifier` values; use `0` for no modifiers. `description` is a user-readable label shown in the system shortcut dialog on Linux/Wayland and ignored elsewhere. Returns the registration handle, or `-1` on failure.

### Combine modifiers

`HotKeyModifier` has four values: `ALT`, `CONTROL`, `SHIFT`, and `META`. On macOS, `ALT` is Option and `META` is Command; on Windows and Linux, `META` is the Win/Super key. Combine them with `+`, which produces the `Int` bitmask that `register` expects:

```kotlin
val modifiers = HotKeyModifier.CONTROL + HotKeyModifier.SHIFT
```

### Handle the callback

`HotKeyListener` is a functional interface with a single method:

```kotlin
fun onHotKey(keyCode: Int, modifiers: Int)
```

Because it is a `fun interface`, you can pass a two-parameter lambda wherever a `HotKeyListener` is expected.

### Register a media key

```kotlin
GlobalHotKeyManager.register(MediaKey.PLAY_PAUSE) { _, _ -> player.togglePlayPause() }
GlobalHotKeyManager.register(MediaKey.NEXT_TRACK) { _, _ -> player.skipNext() }
```

`MediaKey` has four values: `PLAY_PAUSE`, `STOP`, `NEXT_TRACK`, and `PREV_TRACK`.

Media keys are not supported on macOS. On macOS this overload returns `-1` and sets `lastError` to `"Media keys are not supported on macOS"`.

### Check availability

```kotlin
if (!GlobalHotKeyManager.isAvailable) {
    // The native bridge is not loaded on this platform.
}
```

`isAvailable` reports whether the native library is loaded and functional on the current platform.

### Unregister and shut down

`unregister(handle: Long): Boolean` releases a single binding and returns whether it succeeded. `shutdown()` unregisters every hotkey and stops the native message loop; call it on app exit.

## Notes

On macOS the user may be prompted to grant your app **Input Monitoring** (and sometimes **Accessibility**) under System Settings → Privacy & Security. Until they accept, callbacks never fire. Link to `x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent` from your prompt.

- Linux Wayland compositors generally disallow global key grabs from arbitrary apps. The library uses the `org.freedesktop.portal.GlobalShortcuts` portal where available, which requires a reverse-DNS `.desktop` file and the app launched from it; on other compositors the binding may not fire.
- Read `GlobalHotKeyManager.lastError` after a failed call to find out why a registration was rejected.

## What's next

- [Media control](/docs/os/media-control) — expose playback state and respond to system media events.
- [System info](/docs/os/system-info) — query OS, CPU, memory, and battery details from Kotlin.
- [OS integration overview](/docs/os) — the full set of platform integration modules.

---

# Media controls

URL: https://nucleusframework.dev/en/docs/os/media-control

Publish now-playing metadata to the system media center and handle playback commands on macOS, Windows, and Linux from Kotlin.

Media controls lets you publish track metadata to the operating system's media center and
receive playback commands from Kotlin. A single `MediaControlService` object wraps the
MPRIS D-Bus interface on Linux, `MPNowPlayingInfoCenter` / `MPRemoteCommandCenter` on macOS,
and the System Media Transport Controls (SMTC) on Windows.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.media-control:<version>")
}
```

## Publish now-playing metadata

Check that the native backend loaded, configure the player identity, then push metadata and
playback state:

```kotlin
import dev.nucleusframework.media.control.MediaControlService
import dev.nucleusframework.media.control.MediaMetadata
import dev.nucleusframework.media.control.MediaPlaybackState
import dev.nucleusframework.media.control.MediaPlaybackStatus

if (MediaControlService.isAvailable()) {
    MediaControlService.configure()

    MediaControlService.setMetadata(
        MediaMetadata(
            title = "Strobe",
            artist = "deadmau5",
            album = "For Lack of a Better Name",
            coverUrl = "file:///tmp/cover.png",
            duration = 10 * 60 * 1_000L,
        ),
    )

    MediaControlService.setPlaybackState(
        MediaPlaybackState(status = MediaPlaybackStatus.PLAYING, positionMs = 0),
    )
}
```

`duration` and `positionMs` are in milliseconds. On Linux, a `coverUrl` pointing at a local
file must use the `file://` scheme. On Windows, a local cover (`file://` or a bare path)
appears in the SMTC flyout; remote `http`/`https` URLs work as well.

## Handle playback commands

Register a listener with `attach` to receive commands from the OS media center. The callback
is dispatched on the Swing EDT, so you can mutate Compose or Swing state directly:

```kotlin
import dev.nucleusframework.media.control.MediaControlEvent

MediaControlService.attach { event ->
    when (event) {
        MediaControlEvent.Play -> player.play()
        MediaControlEvent.Pause -> player.pause()
        MediaControlEvent.Toggle -> player.toggle()
        MediaControlEvent.Next -> player.skipToNext()
        MediaControlEvent.Previous -> player.skipToPrevious()
        MediaControlEvent.Stop -> player.stop()
        is MediaControlEvent.SeekBy -> player.seekBy(event.offsetMs)
        is MediaControlEvent.SetPosition -> player.seekTo(event.positionMs)
        else -> {}
    }
}
```

Only one listener is active at a time — calling `attach` again replaces the previous one.
Call `detach()` to stop receiving events and unregister from the media center.

## How it works

`MediaControlService` is a singleton that delegates to a per-OS native bridge. `isAvailable()`
returns `true` only when that bridge loaded successfully on the current platform; when it
returns `false`, every call is a no-op, so you can guard setup with a single check.

`configure()` sets the player identity. On Linux it registers the MPRIS bus name (default
`org.mpris.MediaPlayer2.<suffix>`, where `<suffix>` is `NucleusApp.appId` sanitized into a legal
D-Bus name); on macOS the identity comes
from the host app bundle; on Windows it uses the application's AUMID. Both parameters are
defaulted, so `configure()` with no arguments is the common case.

After configuring, push metadata and playback state as your player changes. Incoming commands
are parsed from the native bridge and delivered to your listener on the Swing EDT.

The commands the OS can send back differ by platform:

- **Linux (MPRIS)** emits every `MediaControlEvent` variant.
- **macOS** emits `Play`, `Pause`, `Toggle`, `Next`, `Previous`, `Stop`, and `SetPosition`.
- **Windows (SMTC)** emits `Play`, `Pause`, `Next`, `Previous`, `Stop`, `SeekBy`, and `SetPosition`.

## API reference

### Set metadata

```kotlin
MediaControlService.setMetadata(
    MediaMetadata(
        title = "Track",
        artist = "Artist",
        album = "Album",
        coverUrl = "file:///tmp/cover.png",
        duration = 3 * 60 * 1_000L,
    ),
)
```

Every `MediaMetadata` field is nullable and defaults to `null`. `duration` is in milliseconds.

### Set playback state

```kotlin
MediaControlService.setPlaybackState(
    MediaPlaybackState(
        status = MediaPlaybackStatus.PLAYING,
        positionMs = currentPositionMs,
    ),
)
```

`status` is one of `MediaPlaybackStatus.STOPPED`, `PAUSED`, or `PLAYING`. `positionMs` is
optional and defaults to `null`. Push a state update on every play, pause, stop, and seek so
the system seek bar stays accurate.

### Set volume

```kotlin
MediaControlService.setVolume(0.5)
```

`volume` is clamped to the range `0.0`–`1.0`.

### Attach and detach

```kotlin
MediaControlService.attach { event -> /* handle */ }
MediaControlService.detach()
```

### Per-platform notes

**macOS**

Set `LSApplicationCategoryType` to `public.app-category.music` in `Info.plist` so the Now
Playing widget treats the app as a media player. Hardware media keys deliver Play, Pause,
Next, and Previous when the app is the active now-playing client.

**Windows**

SMTC integration is automatic once you call `configure()`. The system treats the most recent
publisher as the current now-playing source, and the identity resolves through the app's AUMID.
A local `coverUrl` (`file://` or a bare path) shows in the flyout; `http`/`https` URLs are
fetched by the system.

**Linux**

`configure()` registers the MPRIS bus name `org.mpris.MediaPlayer2.<suffix>`, where `<suffix>` is
`NucleusApp.appId` sanitized into a legal D-Bus name: illegal characters become `_`, elements that
start with a digit get an `_` prefix, empty elements are dropped, and the suffix is truncated to
keep the name under the 255-character D-Bus limit. `playerctl` and desktop indicators discover the
player by enumerating that prefix. Pass a custom `dbusName` to override it.

## Notes

- `setVolume(...)` is a no-op on macOS — Now Playing has no per-app volume channel.
- On Linux, `isAvailable()` only reports whether the native library loaded. If the session bus is unreachable or the MPRIS name is invalid, registration is skipped: `attach` returns without blocking and logs a warning, while `isAvailable()` still returns `true`.

## What's next

- [Global hotkeys](/docs/os/global-hotkey) — bind media keys and other shortcuts system-wide.
- [System info](/docs/os/system-info) — query the OS, CPU, battery, and displays from Kotlin.
- [Quickstart](/docs/start/quickstart) — build and run your first Nucleus app.

---

# Dark mode detector

URL: https://nucleusframework.dev/en/docs/os/dark-mode

Detect the operating system's dark mode from Kotlin and recompose your Compose UI when the theme changes.

`darkmode-detector` reports whether the operating system is in dark mode and notifies you when
that changes. It provides an `isSystemInDarkMode()` composable that recomposes on theme changes,
plus an imperative `IDarkModeDetector` for use outside Compose. macOS, Windows, and Linux are
supported.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.darkmode-detector:<version>")
}
```

## Detect dark mode in Compose

Call `isSystemInDarkMode()` and use the result to select your color scheme. The composable
recomposes when the system theme changes:

```kotlin
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable
import dev.nucleusframework.darkmodedetector.isSystemInDarkMode

@Composable
fun App() {
    val isDark = isSystemInDarkMode()
    MaterialTheme(
        colorScheme = if (isDark) darkColorScheme() else lightColorScheme(),
    ) {
        // Content recomposes when the OS theme flips.
    }
}
```

Compose Desktop's own `isSystemInDarkTheme()` only reads `LocalSystemTheme`, whose default is a
non-reactive Skiko snapshot — it does not update when the user switches themes at runtime.
`isSystemInDarkMode()` returns the current value and registers a listener that triggers
recomposition on every change.

### Bridge to Compose `isSystemInDarkTheme`

From 2.3, `nucleusApplication` provides Compose's `LocalSystemTheme` from
`isSystemInDarkMode()` on both AWT and Tao entry points (Tao windows inherit it through the
scene local bridge). Official `androidx.compose.foundation.isSystemInDarkTheme()` — and any
library that calls it — then tracks live OS theme changes under the DSL, without calling
Nucleus APIs at every call site.

`darkmode-detector` is an **`api`** dependency of `nucleus-application`, so the detector is on
the consumer classpath whenever you use the application entry point. You still add the
coordinate explicitly when you use the detector outside `nucleusApplication`.

```kotlin
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.lightColorScheme
import dev.nucleusframework.application.nucleusApplication

fun main() = nucleusApplication {
    // isSystemInDarkTheme() recomposes when the OS theme flips
    val dark = isSystemInDarkTheme()
    MaterialTheme(colorScheme = if (dark) darkColorScheme() else lightColorScheme()) {
        DecoratedWindow(onCloseRequest = ::exitApplication) { /* … */ }
    }
}
```

Use `isSystemInDarkMode()` when you need Nucleus's API outside Compose or when you are not
inside `nucleusApplication`. Prefer `isSystemInDarkTheme()` for stock Material / third-party
composables that already depend on it.

Inside a `@Preview` (when `LocalInspectionMode` is `true`), `isSystemInDarkMode()` delegates to
Compose's `isSystemInDarkTheme()` so previews render without a running detector.

## How it works

Each platform reads the system theme through a native JNI bridge and watches the OS for changes.
No polling is involved; the detector reacts to change notifications from the OS itself.

- **macOS**: reads the `AppleInterfaceStyle` system preference and registers an observer through
  `NSDistributedNotificationCenter`.
- **Windows**: reads the registry value
  `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize\AppsUseLightTheme`
  and watches it with `RegNotifyChangeKeyValue` on a native background thread.
- **Linux**: reads the XDG Desktop Portal `color-scheme` preference over the
  `org.freedesktop.portal.Settings` D-Bus interface; a value of `1` means prefer-dark.

On unsupported platforms, `getPlatformDarkModeDetector()` returns `NoopDarkModeDetector`, which
always reports light and ignores listeners.

## API reference

### Read the current theme

`getPlatformDarkModeDetector()` returns the `IDarkModeDetector` for the current platform. Call
`isDark()` for a one-shot read:

```kotlin
import dev.nucleusframework.darkmodedetector.getPlatformDarkModeDetector

val detector = getPlatformDarkModeDetector()
val dark: Boolean = detector.isDark()
```

### Listen for changes

Register a `java.util.function.Consumer<Boolean>` to be notified when the theme changes, and
remove it when you are done:

```kotlin
import dev.nucleusframework.darkmodedetector.getPlatformDarkModeDetector
import java.util.function.Consumer

val detector = getPlatformDarkModeDetector()

val listener = Consumer<Boolean> { isDark ->
    println("dark mode: $isDark")
}
detector.registerListener(listener)

// Later, stop receiving updates.
detector.removeListener(listener)
```

The full interface:

```kotlin
interface IDarkModeDetector {
    fun isDark(): Boolean
    fun registerListener(listener: Consumer<Boolean>)
    fun removeListener(listener: Consumer<Boolean>)
}
```

### Use a no-op detector

`NoopDarkModeDetector` implements `IDarkModeDetector` without touching the OS. It always returns
`false` from `isDark()` and ignores listeners — useful in tests or headless environments:

```kotlin
import dev.nucleusframework.darkmodedetector.IDarkModeDetector
import dev.nucleusframework.darkmodedetector.NoopDarkModeDetector

val detector: IDarkModeDetector = NoopDarkModeDetector
```

## What's next

- [System colors](/docs/os/system-color) — read the system accent color and high-contrast state.
- [System info](/docs/os/system-info) — query the OS, CPU, memory, and battery from Kotlin.
- [OS integration](/docs/os) — the rest of the desktop OS APIs.

---

# System accent colour

URL: https://nucleusframework.dev/en/docs/os/system-color

Read the user's OS accent colour and high-contrast setting as reactive Compose state.

The `system-color` module reads the user's OS accent colour and high-contrast setting from
Kotlin. Both are exposed as reactive Compose state that recomposes when the user changes them
in system settings, so you can feed the accent straight into a Compose color scheme. Supported
on macOS, Windows, and Linux.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.system-color:<version>")
}
```

## Read the system accent colour

Call `systemAccentColor()` inside a composable. It returns a `Color?` and recomposes whenever
the user picks a different accent. Fall back to your own palette when it returns `null`:

```kotlin
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.runtime.Composable
import dev.nucleusframework.systemcolor.systemAccentColor

@Composable
fun App() {
    val accent = systemAccentColor()

    val scheme = when {
        accent != null -> darkColorScheme(primary = accent)
        else -> darkColorScheme()
    }

    MaterialTheme(colorScheme = scheme) {
        // The UI recomposes when the accent colour changes.
    }
}
```

Read the high-contrast setting the same way with `isSystemInHighContrast()`:

```kotlin
import androidx.compose.runtime.Composable
import dev.nucleusframework.systemcolor.isSystemInHighContrast

@Composable
fun AppContent() {
    val highContrast = isSystemInHighContrast()
    // Adjust borders, elevation, or contrast tokens when highContrast is true.
}
```

## How it works

On each supported platform, a native JNI bridge starts observing the OS accent-colour and
contrast change notifications and forwards them to registered listeners.

`systemAccentColor()` and `isSystemInHighContrast()` subscribe to that bridge and hold the
current value in Compose state. Any composable that reads them recomposes when the value
changes, so there is no polling and no manual refresh.

`systemAccentColor()` returns `null` when the platform cannot supply an accent colour. That
includes any platform other than macOS, Windows, or Linux. Treat `null` as "use your own brand
colour".

Not every OS or configuration exposes an accent colour. Always handle the `null` case and fall
back to your own palette.

## API reference

### Check platform support

```kotlin
fun isSystemAccentColorSupported(): Boolean
```

Returns `true` when the current platform can report an accent colour. This is a plain function,
not a composable, so you can call it outside composition — for example, to enable or disable a
settings toggle.

### Read the accent colour

```kotlin
@Composable
fun systemAccentColor(): Color?
```

Returns the current accent colour, or `null` when the platform does not support it. Recomposes
when the accent changes.

### Read the high-contrast flag

```kotlin
@Composable
fun isSystemInHighContrast(): Boolean
```

Returns `true` when the OS is in high-contrast mode. Recomposes when the user toggles the
accessibility contrast setting.

## What's next

- [Dark mode detection](/docs/os/dark-mode) — pair with the accent colour to derive a full OS-driven theme.
- [System info](/docs/os/system-info) — read the OS, hardware, and battery details from Kotlin.
- [OS integration](/docs/os) — the rest of the native platform modules.

---

# System info

URL: https://nucleusframework.dev/en/docs/os/system-info

Read host details — OS, CPU, memory, disks, GPUs, batteries, network, processes, and users — through the SystemInfo object.

`SystemInfo` lets you read host details from Kotlin: the operating system, CPU, memory, disks,
GPUs, batteries, network interfaces, processes, and users. Each reading is a snapshot taken at
call time, backed by a per-platform native library on macOS, Windows, and Linux.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.system-info:<version>")
}
```

## Read the host

`SystemInfo` is an `object`. Call its methods directly and check for `null`: a value that
cannot be retrieved on a given host returns `null` rather than a guess.

```kotlin
import dev.nucleusframework.systeminfo.SystemInfo

fun main() {
    val os = SystemInfo.osInfo() ?: return
    println("OS: ${os.longOsVersion} (${os.cpuArch})")

    val mem = SystemInfo.memoryInfo()
    println("Memory: ${mem?.usedMemory?.div(1024 * 1024)} MB / ${mem?.totalMemory?.div(1024 * 1024)} MB")

    SystemInfo.gpus().forEach { gpu ->
        println("GPU: ${gpu.name} — ${gpu.dedicatedVideoMemory / 1024 / 1024} MB")
    }

    val battery = SystemInfo.batteryInfo()
    println("Battery: ${battery?.let { "${(it.stateOfCharge * 100).toInt()}% (${it.state})" } ?: "none"}")
}
```

Call `SystemInfo.isAvailable()` first when you need to know whether the native library loaded on
the current platform.

## How it works

Each method delegates to a native library, one per operating system, loaded through JNI. The
library reads the underlying platform APIs and returns plain Kotlin data classes.

The API is snapshot-oriented: each call reads the current values and returns immediately. There
is no polling or subscription. To display readings on a refresh interval, call the method again
and cache the result yourself.

Nullable returns and empty lists mean the value was unavailable, not that an error was thrown.
List methods such as `disks()` and `gpus()` return an empty list when nothing could be read;
single-value methods such as `cpuInfo()` return `null`.

## API reference

### Operating system

```kotlin
val os = SystemInfo.osInfo()
// name, osVersion, longOsVersion, kernelVersion, distributionId,
// hostName, cpuArch, uptime, bootTime
```

`osInfo()` returns `OsInfo?`.

### CPU

```kotlin
val cpu = SystemInfo.cpuInfo()   // CpuGlobalInfo?
cpu?.cpus?.forEach { core ->
    println("${core.brand}: ${core.frequency} MHz, usage ${core.cpuUsage}%")
}
println("Global usage: ${cpu?.globalCpuUsage}%")
```

`cpuInfo()` returns a `CpuGlobalInfo?` holding `globalCpuUsage`, `physicalCoreCount`, and a
`cpus: List<CpuInfo>` with one entry per logical core.

### Memory and disks

```kotlin
SystemInfo.memoryInfo()   // MemoryInfo? — total, free, available, used, and swap counters
SystemInfo.disks()        // List<DiskInfo> — name, fileSystem, mountPoint, totalSpace, availableSpace
```

### GPUs, batteries, and network

```kotlin
SystemInfo.gpus()             // List<GpuInfo>
SystemInfo.batteryInfo()      // BatteryInfo? — stateOfCharge, state, cycleCount, health, …
SystemInfo.networks()         // List<NetworkInterfaceInfo>
SystemInfo.connectivityInfo() // ConnectivityInfo? — isConnected, meteredStatus
```

`BatteryInfo.state` is a `BatteryState` enum: `Charging`, `Discharging`, `Full`, or `Unknown`.
`ConnectivityInfo.meteredStatus` is a `MeteredStatus` enum: `NOT_AVAILABLE`, `UNKNOWN`,
`UNMETERED`, or `METERED`.

### Processes and users

```kotlin
SystemInfo.processes()    // List<ProcessInfo> — every running process
SystemInfo.process(pid)   // ProcessInfo? — a single process by pid: Long
SystemInfo.users()        // List<UserInfo>
```

### Other readings

```kotlin
SystemInfo.components()    // List<ComponentInfo> — temperature sensors
SystemInfo.motherboard()   // MotherboardInfo?
SystemInfo.product()       // ProductInfo?
SystemInfo.idleTime()      // Long — seconds since last user input, or -1 if unavailable
```

## Notes

- Some readings are platform-specific. Temperature sensors through `components()` are sparse on
  Windows, and `motherboard()` is most complete on Linux.
- `processes()` walks every process and can be expensive on a busy host. Use `process(pid)` when
  you only need one.

`idleTime()` returns `-1` when the platform library did not load, the same value
`isAvailable()` reports as `false`.

## What's next

- [System color](/docs/os/system-color) — read the system accent and high-contrast state.
- [Dark mode](/docs/os/dark-mode) — detect and observe the system light/dark setting.
- [Modules](/docs/concepts/modules) — the full list of Nucleus modules and their artifacts.

---

# macOS menu bar

URL: https://nucleusframework.dev/en/docs/os/menu-macos

Build the native macOS menu bar from Compose, with items, keyboard shortcuts, icons, badges, and submenus that react to state.

`menu-macos` lets you build the native macOS menu bar — the strip at the top of the
screen, not inside your window — from Compose. You declare menus and items as a tree,
and the native `NSMenu` is rebuilt whenever the state it reads changes.

This module only does anything on macOS. `NativeMenuBar` is a no-op on other platforms,
so you can leave the call in shared code.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.menu-macos:<version>")
}
```

This pulls in the [`sf-symbols`](https://developer.apple.com/sf-symbols/) constants
transitively, so you can reference symbols by name without misspelling them.

## Build a menu bar

Call `NativeMenuBar` from a composable near your application root. The first `Menu`
call becomes the application menu (the bold entry named after your app).

```kotlin
import androidx.compose.runtime.Composable
import dev.nucleusframework.menu.macos.*
import dev.nucleusframework.sfsymbols.SFSymbolObjectsAndTools
import kotlin.system.exitProcess

@Composable
fun App() {
    NativeMenuBar {
        Menu("MyApp") {
            Item("About MyApp") { showAbout() }
            Separator()
            Item("Quit", shortcut = NativeKeyShortcut("q")) { exitProcess(0) }
        }

        Menu("File") {
            Item(
                "New",
                shortcut = NativeKeyShortcut("n"),
                icon = NsMenuItemImage.SystemSymbol(SFSymbolObjectsAndTools.DOCUMENT_BADGE_PLUS),
            ) { newDocument() }

            Item(
                "Open…",
                shortcut = NativeKeyShortcut("o"),
                icon = NsMenuItemImage.SystemSymbol(SFSymbolObjectsAndTools.FOLDER),
            ) { open() }
        }

        MenuHelp("Help") {
            Item("Documentation") { openDocs() }
        }
    }
    // … window content
}
```

## How it works

`NativeMenuBar` saves the current menu bar on first composition, then installs a new
`NSMenu` built from your DSL. The builder lambda is a normal composable body: it runs
during composition, and the native menu is rebuilt whenever a state read inside it
changes. When the composable leaves the composition, the saved menu bar is restored.

Because the menu is tied to the composition, host `NativeMenuBar` from your application
root rather than from a window's content. That way the menu survives when windows open
and close.

Menus declared with `MenuWindow` and `MenuHelp` are handed to AppKit as the well-known
Window and Help menus. macOS then populates them itself — the window list and "Bring All
to Front" for Window, and a search field at the top of Help.

## API reference

### Add menus and submenus

`Menu` adds a top-level menu at the bar level, or a submenu inside another menu. Submenus
nest to any depth.

```kotlin
NativeMenuBar {
    Menu("Edit") {
        Item("Undo", shortcut = NativeKeyShortcut("z")) { undo() }
        Item("Redo", shortcut = NativeKeyShortcut("z", shift = true)) { redo() }
        Separator()
        Menu("Find") {
            Item("Find…", shortcut = NativeKeyShortcut("f")) { find() }
            Item("Find Next", shortcut = NativeKeyShortcut("g")) { findNext() }
        }
    }
}
```

Use `MenuWindow` and `MenuHelp` for the standard Window and Help menus. Their content is
optional — macOS fills them in.

### Add items

`Item` adds a regular menu item. The trailing lambda is the click callback, dispatched on
the Swing event dispatch thread. Common parameters: `enabled`, `shortcut`, `icon`,
`state`, `badge`, `subtitle`, `toolTip`, and `tag`.

```kotlin
Item(
    "Export…",
    shortcut = NativeKeyShortcut("e", shift = true),
    subtitle = "Save a copy as PDF",
    enabled = document != null,
) { export() }
```

### Add checkboxes and radio buttons

`CheckboxItem` and `RadioButtonItem` map their boolean state to the item's checkmark for
you. Manage the selection yourself.

```kotlin
var darkMode by remember { mutableStateOf(false) }

NativeMenuBar {
    Menu("View") {
        CheckboxItem(
            "Dark mode",
            checked = darkMode,
            onCheckedChange = { darkMode = it },
        )
        Separator()
        RadioButtonItem("Light", selected = !darkMode, onClick = { darkMode = false })
        RadioButtonItem("Dark", selected = darkMode, onClick = { darkMode = true })
    }
}
```

If you need finer control, `Item` accepts a `state` of `NsMenuItemState.OFF`,
`NsMenuItemState.ON`, or `NsMenuItemState.MIXED` directly.

### Add separators, section headers, and search

```kotlin
Menu("History") {
    SearchField(placeholder = "Search history")
    SectionHeader("Today")
    Item("nucleusframework.dev") { open(url) }
    Separator()
    SectionHeader("Earlier")
    Item("developer.apple.com") { open(url) }
}
```

`SearchField` filters the menu's other items by title as you type. `SectionHeader`
requires macOS 14+ and falls back to a disabled item on older systems.

### Set keyboard shortcuts

`NativeKeyShortcut` defaults to the Command (⌘) modifier. Add `shift`, `option`,
`control`, or `function` as needed, and use `NativeKey` constants for non-printable keys.

```kotlin
Item("Save", shortcut = NativeKeyShortcut("s")) { save() }
Item("Save As…", shortcut = NativeKeyShortcut("s", shift = true)) { saveAs() }
Item("Cancel", shortcut = NativeKeyShortcut(NativeKey.ESCAPE, command = false)) { cancel() }
```

### Add icons

`NsMenuItemImage` sources an item's image from an SF Symbol, a named AppKit image, or a
file path.

```kotlin
Item("Settings", icon = NsMenuItemImage.SystemSymbol(SFSymbolGeneral.GEAR)) { openSettings() }
```

The `sf-symbols` module exposes each symbol category — `SFSymbolGeneral`,
`SFSymbolObjectsAndTools`, `SFSymbolPower`, and more — as typed constants.
`NsMenuItemImage.SystemSymbol` also accepts a raw symbol name string.

### Add badges

`NsMenuItemBadge` shows a system-styled badge to the right of an item (macOS 14+). Use
`Count` for a plain number, `Text` for a custom string, or `Alerts`, `NewItems`, and
`Updates` for system-localized labels.

```kotlin
Item("Inbox", badge = NsMenuItemBadge.Count(unreadCount)) { openInbox() }
Item("Software Update", badge = NsMenuItemBadge.Updates(pendingUpdates)) { openUpdates() }
```

## What's next

- [System tray](/docs/os/system-tray) — a menu-bar status item and its context menu.
- [Dark mode](/docs/os/dark-mode) — detect the system appearance to drive a checkable menu item.
- [Freedesktop icons](/docs/os/freedesktop-icons) — the equivalent named-icon set for Linux.

---

# Spell check

URL: https://nucleusframework.dev/en/docs/os/spell-check

Check spelling in Compose text fields through each operating system's native engine — Hunspell on Linux, NSSpellChecker on macOS, and the Windows Spell Checking API.

The `spellcheck` module checks spelling from Kotlin through the spell-check engine each operating
system already ships. It exposes a Compose wrapper that adds suggestions to a text field's
context menu, and an engine API you can call without Compose.

## Add the dependency

`nucleus-application` exposes `spellcheck` as an `api` dependency, so the Compose integration is
already on the classpath of any Nucleus app:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
}
```

Add the module explicitly only when you want the engine without the Compose layer:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.spellcheck:<version>")
}
```

## Check a text field

Wrap the field in `SpellcheckContextMenu`. Right-clicking a misspelled word lists suggestions
and an "Add to dictionary" entry above or below the standard Cut/Copy/Paste items:

```kotlin
import androidx.compose.foundation.text.BasicTextField
import dev.nucleusframework.application.spellcheck.SpellcheckContextMenu

@Composable
fun NoteField(value: String, onValueChange: (String) -> Unit) {
    SpellcheckContextMenu(text = value, onTextChange = onValueChange) {
        BasicTextField(value = value, onValueChange = onValueChange, singleLine = true)
    }
}
```

Picking a suggestion replaces the clicked word and calls `onTextChange` with the new text.

There is a second overload for the state-based text fields, which manages the text itself:

```kotlin
import androidx.compose.foundation.text.input.rememberTextFieldState
import dev.nucleusframework.application.spellcheck.SpellcheckContextMenu

val state = rememberTextFieldState("helo world")

SpellcheckContextMenu(state = state) {
    TextField(state = state)
}
```

## Choose the check language

Without arguments, the session uses `Locale.getDefault()`. Pass `locale` to check one field in a
different language:

```kotlin
SpellcheckContextMenu(
    text = value,
    onTextChange = onValueChange,
    locale = Locale.FRENCH,
) {
    BasicTextField(value = value, onValueChange = onValueChange)
}
```

To switch the whole process, assign `SpellChecker.locale`. Loading a dictionary touches the disk,
so warm the session off the main thread:

```kotlin
import dev.nucleusframework.spellcheck.SpellChecker
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

LaunchedEffect(locale) {
    SpellChecker.locale = locale
    withContext(Dispatchers.IO) { SpellChecker.ensureSession(locale) }
}
```

Assigning `locale` drops the current session; the next access builds one for the new language.
When you pass both `session` and `locale` to the composable, `session` wins.

## Place the menu items

`menuPlacement` decides whether suggestions land above or below the editing commands:

```kotlin
import dev.nucleusframework.application.spellcheck.SpellcheckMenuPlacement

SpellcheckContextMenu(
    text = value,
    onTextChange = onValueChange,
    menuPlacement = SpellcheckMenuPlacement.Top,
) {
    BasicTextField(value = value, onValueChange = onValueChange)
}
```

| Value | Order |
|---|---|
| `Bottom` (default) | Cut/Copy/Paste, separator, suggestions |
| `Top` | Suggestions, separator, Cut/Copy/Paste |

## How it works

Each platform has a spell-check engine, reached over JNI. macOS uses `NSSpellChecker`, Windows
uses the Spell Checking API (`ISpellChecker`), and Linux loads Hunspell with `dlopen` — so there
is no compile-time dependency on a distro package.

A `SpellcheckSession` owns one loaded dictionary for one locale. `SpellChecker` keeps a
process-wide session and rebuilds it when you change `locale`. Words you add through
"Add to dictionary" are appended to `~/.config/nucleus/spellcheck/<tag>.dic` (honoring
`XDG_CONFIG_HOME`); the OS-level learned-word lists on macOS and Windows are left untouched.

When no engine is available — an unsupported platform, a missing Hunspell library, or no matching
dictionary — every operation is a no-op instead of an error: `check` and `addToDictionary` return
`false`, `suggest` returns an empty list, and `SpellcheckContextMenu` renders its content
unchanged.

**Linux**

Hunspell is loaded at run time from the first soname that resolves: `libhunspell-1.7.so.0`,
`libhunspell-1.7.so`, `libhunspell.so.0`, `libhunspell-1.6.so.0`, then `libhunspell.so`.

Dictionaries are `<tag>.aff` + `<tag>.dic` pairs, searched in `$DICPATH` (colon-separated) first,
then `/usr/share/hunspell`, `/usr/share/myspell/dicts`, `/usr/share/myspell`,
`/usr/local/share/hunspell`, and `$XDG_DATA_HOME/hunspell` (default `~/.local/share/hunspell`).

The tag is resolved as `lang_COUNTRY`, then language-only, then through aliases — `en` tries
`en_US`, `en_GB`, `en`; `fr` tries `fr_FR`. End users need their distro's `hunspell` runtime
library and a dictionary package.

**macOS**

`NSSpellChecker` provides the engine and the language list. No dictionary files are needed, and
the requested locale is matched against the languages macOS reports as available.

**Windows**

The Windows Spell Checking API (`ISpellChecker`) provides the engine. No dictionary files are
needed; languages come from the installed Windows language packs.

## API reference

### Compose integration

Package `dev.nucleusframework.application.spellcheck`, shipped in `nucleus-application`.

| Symbol | Description |
|---|---|
| `SpellcheckContextMenu(text, onTextChange, session?, locale?, menuPlacement, content)` | Adds suggestions to the context menu of the field in `content`. |
| `SpellcheckContextMenu(state, session?, locale?, menuPlacement, content)` | Same, for a `TextFieldState`-based field. |
| `SpellcheckMenuPlacement` | `Top`, `Bottom`. |
| `NucleusSpellcheckInstaller.menuItems(word, session, onSuggestion, onAddToDictionary, separator?, menuPlacement)` | Builds the suggestion items to merge into a menu you assemble yourself. |
| `drawMisspellingSquiggles(drawScope, layout, ranges, color)` | Draws underlines for the given ranges in a custom text renderer. |

### Engine

Package `dev.nucleusframework.spellcheck`, shipped in `spellcheck`.

| Symbol | Description |
|---|---|
| `SpellChecker` | Process-wide singleton: `locale`, `session`, `sessionIfReady`, `isAvailable`, `ensureSession()`, `check()`, `suggest()`, `addToDictionary()`, `misspellings()`. |
| `SpellcheckSession(locale, osName, dictionaryDirectories, userDictionaryFile)` | One loaded dictionary. `AutoCloseable`; exposes `locale`, `isAvailable`, `dictionaryTag`, `check`, `suggest`, `addToDictionary`, `misspellings`. |
| `SpellcheckSession.defaultUserDictionaryFile(locale)` | Path of the user dictionary for a locale. |
| `DictionaryLocator.defaultDirectories()` / `find(locale, directories)` | Where dictionaries are searched, and the pair that matches a locale. |
| `DictionaryFiles(aff, dic, tag)` | A resolved dictionary pair. |
| `SpellcheckWord(start, end, word)` | A token and its range in the text. |

### Text helpers

| Function | Description |
|---|---|
| `iterateWords(text)` | Every token in the text. |
| `misspellingRanges(text) { isCorrect }` | Ranges rejected by the predicate. |
| `wordAt(text, offset)` | The token containing an offset, or `null`. |
| `replaceWord(text, word, replacement)` | Text with one token replaced. |
| `buildSpellcheckMenuModel(word, session, range?, maxSuggestions)` | Suggestions plus the localized "Add to dictionary" label. |
| `applySuggestion(text, model, suggestion)` | Text with the model's range replaced. |

`SpellcheckMenuModel.localizedAddToDictionaryLabel(locale)` translates the label; the fallback is
`DEFAULT_ADD_TO_DICTIONARY_LABEL`.

## Notes

- Tokens are Unicode letters with internal apostrophes. Hyphens split words, and all-digit
  tokens or tokens longer than 64 characters are skipped.
- `SpellChecker.session` blocks on first access while the dictionary loads. Use
  `sessionIfReady` on a frame path, or warm it with `ensureSession()` from a background
  dispatcher.
- Under Jewel, `JewelDecoratedWindow` and `JewelDecoratedDialog` install
  `ProvideJewelSpellcheckMenu` so the items match Jewel's menu chrome.

## What's next

- [Context menus](/docs/window/context-menu) — the menu chrome the suggestions appear in.
- [Native access](/docs/performance/native-access) — how Nucleus binds to native libraries.
- [Ecosystem](/docs/ecosystem) — JVM libraries that cover the rest of your app.

---

# SF Symbols

URL: https://nucleusframework.dev/en/docs/os/sf-symbols

Type-safe Kotlin constants for Apple SF Symbol names used by macOS APIs.

`sf-symbols` provides Apple's [SF Symbols](https://developer.apple.com/sf-symbols/) names as
typed Kotlin constants. macOS APIs that draw a symbol take its name as a string; instead of
writing `"scissors"` by hand, you reference `SFSymbolObjectsAndTools.SCISSORS` and let the
compiler check it. Other Nucleus macOS modules accept these constants wherever they take an icon.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.sf-symbols:<version>")
}
```

`menu-macos` exposes `sf-symbols` through `api()`. If you already depend on `menu-macos`, the
constants are on your classpath without a separate declaration.

## Reference a symbol

Every symbol is a value of the sealed interface `SFSymbol`. Pick a constant from the category
enum that matches the symbol's context:

```kotlin
import dev.nucleusframework.sfsymbols.SFSymbolGeneral
import dev.nucleusframework.sfsymbols.SFSymbolMedia
import dev.nucleusframework.sfsymbols.SFSymbolObjectsAndTools

val gear = SFSymbolGeneral.GEAR
val play = SFSymbolMedia.PLAY
val scissors = SFSymbolObjectsAndTools.SCISSORS
```

Each constant carries its SF Symbols name in `symbolName`. Pass the constant straight to a macOS
API that takes a symbol — for example, a native menu item icon:

```kotlin
import dev.nucleusframework.menu.macos.NsMenuItemImage
import dev.nucleusframework.sfsymbols.SFSymbolObjectsAndTools

val icon = NsMenuItemImage.SystemSymbol(SFSymbolObjectsAndTools.SCISSORS)
```

For a name not covered by the constants, or to target a symbol from a newer SF Symbols release,
use `SFSymbol.Custom`:

```kotlin
import dev.nucleusframework.sfsymbols.SFSymbol

val custom = SFSymbol.Custom("my.custom.symbol")
```

## How it works

Every constant exposes a `symbolName` string that holds its SF Symbols name — `GEAR` resolves to
`"gear"`, `PLAY` to `"play"`. `Custom` wraps an arbitrary string in the same type, so any
`SFSymbol` is ultimately a name that macOS can look up with `NSImage.imageWithSystemSymbolName`.

When you hand an `SFSymbol` to a macOS module, only the `symbolName` reaches the native layer. The
system resolves that name to the installed SF Symbols glyph at render time, so the symbol follows
the user's system appearance without shipping any image assets.

The constants are plain strings, so the module compiles on any platform. SF Symbols themselves
require macOS 11 or later; on earlier macOS or other operating systems, a name resolves to nothing.

## API reference

### Categories

`SFSymbol` is a sealed interface. Each category is an enum whose entries map to SF Symbols names;
`Custom` is a value class for everything else. All 21 category enums implement `SFSymbol`, so any
constant is usable wherever an `SFSymbol` is expected.

| Category | Symbols | Examples |
| --- | --- | --- |
| `SFSymbolGeneral` | 1362 | `GEAR`, `GEARSHAPE` |
| `SFSymbolHuman` | 596 | `ACCESSIBILITY`, `BRAIN` |
| `SFSymbolShapes` | 542 | `APP`, `APP_BADGE` |
| `SFSymbolArrows` | 535 | `ARROW_LEFT`, `ARROW_CLOCKWISE` |
| `SFSymbolTransportation` | 417 | `AIRPLANE`, `AIRPLANE_ARRIVAL` |
| `SFSymbolObjectsAndTools` | 358 | `SCISSORS`, `FOLDER`, `TRASH` |
| `SFSymbolDevices` | 349 | `DESKTOPCOMPUTER`, `KEYBOARD` |
| `SFSymbolNumbers` | 301 | `_0_CIRCLE`, `_0_CIRCLE_FILL` |
| `SFSymbolWeather` | 286 | `CLOUD`, `SUN_MAX`, `BOLT` |
| `SFSymbolStatus` | 273 | `CHECKMARK`, `INFO_CIRCLE` |
| `SFSymbolCommerce` | 264 | `BAG`, `BAG_BADGE_PLUS` |
| `SFSymbolMedia` | 238 | `PLAY`, `PAUSE`, `STOP` |
| `SFSymbolLetters` | 142 | `A_CIRCLE`, `A_SQUARE` |
| `SFSymbolTextFormatting` | 117 | `BOLD`, `CHARACTER` |
| `SFSymbolCommunication` | 101 | `ENVELOPE`, `PHONE`, `MESSAGE` |
| `SFSymbolPower` | 76 | `POWER`, `POWER_CIRCLE` |
| `SFSymbolSecurity` | 62 | `KEY`, `KEY_FILL` |
| `SFSymbolHealth` | 57 | `ALLERGENS`, `BASEBALL` |
| `SFSymbolLocation` | 47 | `FLAG`, `COMPASS_DRAWING` |
| `SFSymbolTime` | 45 | `ALARM`, `ALARM_FILL` |
| `SFSymbolConnectivity` | 27 | `CABLE_COAXIAL`, `CABLE_CONNECTOR` |

Number symbols begin with a digit, which is not a valid Kotlin identifier, so their constants are
prefixed with an underscore: `SFSymbolNumbers._0_CIRCLE` maps to `"0.circle"`.

### Build a custom symbol

`SFSymbol.Custom(symbolName: String)` is an inline value class. Its `symbolName` is used verbatim,
so use it for symbols outside the predefined constants or from a newer SF Symbols version:

```kotlin
SFSymbol.Custom("bird.fill")
SFSymbol.Custom("my.custom.symbol")
```

### Use a symbol with menu-macos

`NsMenuItemImage.SystemSymbol` has an overload that takes an `SFSymbol` directly, so a constant
becomes a menu item icon without touching its `symbolName`:

```kotlin
import dev.nucleusframework.menu.macos.NsMenuItemImage
import dev.nucleusframework.sfsymbols.SFSymbolGeneral

NsMenuItemImage.SystemSymbol(SFSymbolGeneral.GEAR)
```

## What's next

- [Native menu bar](/docs/os/menu-macos) — attach `SystemSymbol` icons to menu items.
- [FreeDesktop icon names](/docs/os/freedesktop-icons) — the equivalent typed icon constants for Linux.
- [OS integration](/docs/os) — the rest of the desktop OS modules.

---

# FreeDesktop icon names

URL: https://nucleusframework.dev/en/docs/os/freedesktop-icons

Typed Kotlin constants for the names defined by the FreeDesktop Icon Naming Specification.

`freedesktop-icons` provides the standard icon names from the
[FreeDesktop Icon Naming Specification](https://specifications.freedesktop.org/icon-naming/latest/)
as typed Kotlin constants. Linux icon themes resolve icons by name: instead of shipping
`info.png`, you reference `dialog-information` and the active theme renders its own version.
Other Nucleus Linux modules accept these constants wherever they take an icon.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.freedesktop-icons:<version>")
}
```

`notification-linux` and `launcher-linux` expose `freedesktop-icons` through `api()`. If you
already depend on either, the constants are on your classpath without a separate declaration.

## Reference an icon

Each icon is a value of the sealed interface `FreedesktopIcon`. Pick a constant from the
category enum that matches the icon's context:

```kotlin
import dev.nucleusframework.freedesktop.icons.FreedesktopIcon

val info = FreedesktopIcon.Status.DIALOG_INFORMATION
val open = FreedesktopIcon.Action.DOCUMENT_OPEN
val printer = FreedesktopIcon.Device.PRINTER
```

For names outside the spec, a file path, or a `file://` URI, use `FreedesktopIcon.Custom`:

```kotlin
val named = FreedesktopIcon.Custom("my-app-icon")           // theme lookup by name
val path = FreedesktopIcon.Custom("/home/user/icon.png")    // absolute path
val uri = FreedesktopIcon.Custom("file:///home/user/icon.png")
```

`FreedesktopIcon.flag` builds a country flag name from an ISO 3166-1 alpha-2 code:

```kotlin
val flag = FreedesktopIcon.flag("fr")   // FreedesktopIcon.Custom("flag-fr")
```

## How it works

Every constant carries a `value` string that holds its spec name — `DIALOG_INFORMATION`
resolves to `"dialog-information"`. `Custom` and `flag` wrap arbitrary strings in the same
type, so any `FreedesktopIcon` is ultimately a name that a theme can look up.

When you hand a `FreedesktopIcon` to a Linux module — notifications, launcher quicklists — the
`value` is sent over D-Bus or written into a `.desktop` file as plain text. The system's active
icon theme turns that name into a concrete image at render time, so the app follows the user's
theme without shipping any bitmaps.

The constants are plain strings, so they compile on any platform. Off Linux they resolve to
nothing visible, since no FreeDesktop theme is present.

## API reference

### Categories

`FreedesktopIcon` is a sealed interface. Each category is an enum whose entries map to spec
names; `Custom` is a value class for everything else.

| Category | Examples |
| --- | --- |
| `FreedesktopIcon.Action` | `DOCUMENT_OPEN`, `EDIT_COPY`, `MEDIA_PLAYBACK_START` |
| `FreedesktopIcon.Animation` | `PROCESS_WORKING` |
| `FreedesktopIcon.Application` | `ACCESSORIES_TEXT_EDITOR`, `MULTIMEDIA_VOLUME_CONTROL`, `UTILITIES_TERMINAL` |
| `FreedesktopIcon.Category` | `APPLICATIONS_INTERNET`, `PREFERENCES_DESKTOP`, `SYSTEM_HELP` |
| `FreedesktopIcon.Device` | `PRINTER`, `CAMERA_PHOTO`, `INPUT_KEYBOARD` |
| `FreedesktopIcon.Emblem` | `IMPORTANT`, `FAVORITE`, `SHARED` |
| `FreedesktopIcon.Emote` | `FACE_SMILE`, `FACE_SAD`, `FACE_WINK` |
| `FreedesktopIcon.MimeType` | `TEXT_X_GENERIC`, `IMAGE_X_GENERIC`, `X_OFFICE_DOCUMENT` |
| `FreedesktopIcon.Place` | `FOLDER`, `USER_HOME`, `NETWORK_SERVER` |
| `FreedesktopIcon.Status` | `DIALOG_INFORMATION`, `DIALOG_WARNING`, `BATTERY_LOW` |
| `FreedesktopIcon.Custom` | value class for raw names, file paths, or `file://` URIs |

### Build a custom icon

`FreedesktopIcon.Custom(value: String)` is an inline value class. Its `value` is used verbatim,
whether it is a theme name, an absolute path, or a `file://` URI.

### Build a country flag

`FreedesktopIcon.flag(countryCode: String)` lowercases the code and returns
`Custom("flag-<code>")`:

```kotlin
FreedesktopIcon.flag("us")   // Custom("flag-us")
FreedesktopIcon.flag("jp")   // Custom("flag-jp")
```

## Notes

- Not every theme implements every icon name. Sticking to the canonical FreeDesktop set gives
  the highest chance of a match.
- Flag icons are not part of the FreeDesktop spec and depend on the theme shipping `flag-<code>`
  names.

## What's next

- [Linux notifications](/docs/os/notification-linux) — pass a `FreedesktopIcon` as the notification icon.
- [Linux launcher](/docs/lifecycle/launcher-linux) — reuse the same constants in `.desktop` actions.
- [System tray](/docs/os/system-tray) — set a per-theme tray icon by name.

---

# App lifecycle, from cold launch to sleep

URL: https://nucleusframework.dev/en/docs/lifecycle

The lifecycle modules connect a Nucleus app to the OS events and services that outlive any single window.

The lifecycle modules connect a Nucleus app to the operating-system events and services
that outlive any single window: cold launch and instance locking, deep links, dock and
taskbar integration, launch at login, background scheduling, and energy management. Each
stage is a separate module, and you add only the ones you need.

## Modules by lifecycle stage

Each stage maps to a module and a page. The two foundations, `core-runtime` and
`nucleus-application`, back several of the rows below.

| Stage | Module | Page |
|---|---|---|
| Cold start and instance locking | `core-runtime` (`SingleInstanceManager`) | [Single instance](/docs/lifecycle/single-instance) |
| URL and file associations | `core-runtime` (`DeepLinkHandler`) + plugin DSL | [Deep links](/docs/lifecycle/deep-links) |
| Bundle id, version, and vendor at runtime | `core-runtime` (`NucleusApp`) | [App metadata](/docs/lifecycle/app-metadata) |
| How the app was packaged | `core-runtime` (`ExecutableRuntime`) | [Executable type](/docs/lifecycle/executable-type) |
| Dock menu (macOS) | `launcher-macos` | [Launcher: macOS](/docs/lifecycle/launcher-macos) |
| Taskbar overlays and jump list (Windows) | `launcher-windows` | [Launcher: Windows](/docs/lifecycle/launcher-windows) |
| Unity launcher and quicklist (Linux) | `launcher-linux` | [Launcher: Linux](/docs/lifecycle/launcher-linux) |
| Launch at login | `autolaunch` | [Auto-launch](/docs/lifecycle/auto-launch) |
| Periodic and cron background work | `scheduler` | [Scheduler](/docs/lifecycle/scheduler) |
| `SMAppService` agents (macOS) | `service-management-macos` | [Service management](/docs/lifecycle/service-management) |
| Energy efficiency and keep-awake | `energy-manager` | [Energy manager](/docs/lifecycle/energy-manager) |
| Progress in the dock or taskbar | `taskbar-progress` | [Taskbar progress](/docs/lifecycle/taskbar-progress) |

## How it works

Each module wraps the native API for its stage — `SMAppService`, `ITaskbarList3`,
`NSDockTile`, `com.canonical.Unity.LauncherEntry`, systemd timers, and others — behind a
Kotlin surface, so you keep a single codebase while the app still integrates with each OS
through its own mechanisms. The modules are independent: add only the ones you need, and
each degrades to a no-op on platforms it does not support.

Two modules underpin the rest. `core-runtime` provides the runtime primitives:
`Platform`, `NucleusApp`, `SingleInstanceManager`, `DeepLinkHandler`, and
`ExecutableRuntime`. `nucleus-application` provides the `nucleusApplication { }` entry
point, which starts the runtime and initializes those primitives. Read those two pages
first, then the module that matches the behavior you need.

Deep link schemes are declared in the Gradle build with the `protocol(name, schemes...)`
DSL, which the plugin translates into macOS Apple Events, Windows registry entries, and
Linux `.desktop` MIME associations at package time.

## What's next

- [Single instance](/docs/lifecycle/single-instance) — enforce one running instance and forward launch arguments to it.
- [Deep links](/docs/lifecycle/deep-links) — register custom URL schemes and handle incoming URLs.
- [Architecture](/docs/concepts/architecture) — what `core-runtime` and `nucleus-application` set up under your `main` function.

---

# One app, one process

URL: https://nucleusframework.dev/en/docs/lifecycle/single-instance

Enforce a single running instance of your app and forward a second launch's arguments to the primary process.

`SingleInstanceManager` restricts your app to one running instance. When a second launch is
detected, it forwards that invocation — CLI arguments or a deep-link URI — to the running
process instead of starting a duplicate. It ships in `core-runtime` and uses the same mechanism
on macOS, Windows, and Linux.

## Add the dependency

`SingleInstanceManager` ships in `core-runtime`, which `nucleus-application` already depends on.
Add it explicitly only when you use it without `nucleus-application`:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.core-runtime:<version>")
}
```

## Enforce a single instance

When you start your app with `nucleusApplication`, single-instance enforcement is on by default.
The second launch exits immediately and the primary window returns to the foreground:

```kotlin
import dev.nucleusframework.application.nucleusApplication

fun main(args: Array<String>) = nucleusApplication(args) {
    DecoratedWindow(onCloseRequest = ::exitApplication) { /* ... */ }
}
```

`enableSingleInstance` defaults to `true`. When the app also handles deep links, the secondary
instance's URI is forwarded to the primary through [`DeepLinkHandler`](/docs/lifecycle/deep-links)
without extra wiring.

## Wire it manually

When you drive Compose's `application { }` yourself, call `SingleInstanceManager.isSingleInstance`
and exit when it returns `false`:

```kotlin
import dev.nucleusframework.core.runtime.SingleInstanceManager

fun main() = application {
    var restoreRequested by remember { mutableStateOf(false) }

    val isPrimary = remember {
        SingleInstanceManager.isSingleInstance(
            onRestoreFileCreated = {
                // Runs on the second instance. `this` is the restore-request Path;
                // write whatever you want the primary to read.
            },
            onRestoreRequest = {
                // Runs on the primary instance when another launch is detected.
                restoreRequested = true
            },
        )
    }

    if (!isPrimary) {
        exitApplication()
        return@application
    }

    Window(onCloseRequest = ::exitApplication) {
        LaunchedEffect(restoreRequested) {
            if (restoreRequested) {
                window.toFront()
                window.requestFocus()
                restoreRequested = false
            }
        }
    }
}
```

`onRestoreFileCreated` is optional. Omit it when the second launch has no payload to hand off.

## How it works

`SingleInstanceManager` holds a lock file in `Configuration.lockFilesDir` (the system temp
directory by default) and acquires it with `java.nio.channels.FileLock`. The lock is
kernel-backed and released when the JVM exits or crashes, so a force-killed primary does not
lock the app out.

When the lock is already held, the second launch writes a restore-request file next to the lock.
The primary watches that directory with a `WatchService` and calls `onRestoreRequest` when the
file appears. This is one mechanism across all three platforms — there is no macOS LaunchServices,
Windows named mutex, or Linux D-Bus name ownership to wire up per OS.

The two callbacks form the IPC channel. `onRestoreFileCreated` runs on the second instance and
receives the restore-request `Path` as its receiver, so it writes a payload — typically a
deep-link URI via [`DeepLinkHandler.writeUriTo`](/docs/lifecycle/deep-links). `onRestoreRequest`
runs on the primary with the same `Path` and reads it back.

## API reference

### SingleInstanceManager

| Member | Signature | Notes |
|---|---|---|
| `isSingleInstance` | `(onRestoreFileCreated: (Path.() -> Unit)? = null, onRestoreRequest: Path.() -> Unit): Boolean` | Returns `true` on the primary, `false` when another instance holds the lock. `onRestoreFileCreated` runs on the secondary; `onRestoreRequest` runs on the primary. |
| `configuration` | `var Configuration` | Assign it before the first `isSingleInstance` call; changing it afterwards throws `IllegalStateException`. |

### Configuration

`Configuration` is a `data class` with two constructor parameters. The file names and paths are
derived from them and are read-only.

| Property | Type / default | Description |
|---|---|---|
| `lockFilesDir` | `Path` = `java.io.tmpdir` | Directory holding the lock and restore-request files. |
| `lockIdentifier` | `String` = `AppIdProvider.appId()` | Base name used to derive the file names. Change it to isolate the lock. |
| `lockFileName` | `String` (derived) | `"$lockIdentifier.lock"`. |
| `restoreRequestFileName` | `String` (derived) | `"$lockIdentifier.restore_request"`. |
| `lockFilePath` / `restoreRequestFilePath` | `Path` (derived) | The two file names resolved under `lockFilesDir`. |

## Notes

- Opt out with `nucleusApplication(args, enableSingleInstance = false)`.
- The default `lockIdentifier` is the app ID resolved by `AppIdProvider.appId()` — the same ID the
  Gradle plugin injects via `nucleus.app.id`, so two apps never share a lock.
- The lock file lives under the per-user temp directory, so two users on the same machine can each
  run the app.
- If the lock file is stale or unreadable, `SingleInstanceManager` deletes it and retries once. If
  the retry finds the lock still held, the process is a secondary and sends a restore request.
  Only an unrecoverable error makes it fail open and continue as the primary.

## What's next

- [Deep links](/docs/lifecycle/deep-links) — forward `myapp://...` URLs from a second launch to the primary.
- [App metadata](/docs/lifecycle/app-metadata) — where the app ID that names the lock comes from.
- [Lifecycle overview](/docs/lifecycle) — the rest of the runtime lifecycle APIs.

---

# Deep links and URL schemes

URL: https://nucleusframework.dev/en/docs/lifecycle/deep-links

Register a custom URL scheme at packaging time and receive the incoming deep-link URI in your Nucleus app at runtime.

Deep links let you register a custom `myapp://` URL scheme and receive the incoming URI in Kotlin. The Nucleus Gradle plugin registers the scheme with the OS at packaging time, and `DeepLinkHandler` in `core-runtime` delivers the URI at runtime, whether it arrives through macOS Apple Events or command-line arguments.

## Add the dependency

`DeepLinkHandler` ships in `core-runtime`, which `nucleus-application` pulls in transitively. If you already depend on `nucleus-application`, you have it. Otherwise add the module directly:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.core-runtime:<version>")
}
```

## Declare the URL scheme

Register the scheme in the `nativeDistributions` block of the Nucleus plugin. The plugin writes the platform registration into each installer it builds:

```kotlin title="build.gradle.kts"
nucleus.application {
    nativeDistributions {
        // protocol(name, vararg schemes)
        // name is shown in the OS UI; schemes are the URL prefixes (without "://").
        protocol("MyApp", "myapp")
    }
}
```

## Handle inbound URIs

Inside `nucleusApplication { }`, register a callback with `onDeepLink`. It selects the delivery path for the active backend (AWT or Tao) and fires for both the cold-start URI and later activations:

```kotlin
import java.net.URI

fun main(args: Array<String>) = nucleusApplication(args) {
    onDeepLink { uri: URI ->
        // Route on uri.host / uri.path / query parameters.
        navigateTo(uri)
    }

    DecoratedWindow(onCloseRequest = ::exitApplication) {
        // ...
    }
}
```

Without the `nucleusApplication` entry point, wire `DeepLinkHandler` yourself. `setHandler` is safe on every backend; on macOS you also install the AWT Apple Events handler:

```kotlin
import dev.nucleusframework.core.runtime.DeepLinkHandler

fun main(args: Array<String>) {
    DeepLinkHandler.setHandler(args) { uri -> navigateTo(uri) }
    // macOS only, and only for AWT-driven launches.
    DeepLinkHandler.installAwtAppleEventHandler()

    application {
        // ...
    }
}
```

`installAwtAppleEventHandler` initializes AWT. On the Tao backend (`decorated-window-tao`), AWT and Tao each create their own `NSApp` and deadlock the event loop on macOS. Use `nucleusApplication { onDeepLink { … } }`, which picks the right path per backend.

## How it works

Each OS delivers URLs differently:

| OS | Mechanism |
|---|---|
| macOS | Apple Events. The running app receives `GetURL` events, exposed through `Desktop.setOpenURIHandler` on the AWT backend. The plugin registers the scheme in `Info.plist` under `CFBundleURLTypes`. |
| Windows | A registry entry under `HKCU\Software\Classes\<scheme>`. Opening a `myapp://...` URL launches your `.exe` with the URL as the first command-line argument — a new process. |
| Linux | A `.desktop` file with `MimeType=x-scheme-handler/myapp;` plus an `xdg-mime` association. Activation passes the URL as a command-line argument. |

`setHandler(args, onDeepLink)` reconciles the difference. On the AWT path, `installAwtAppleEventHandler` registers an Apple Events handler so the callback fires while the app is already running; on Windows and Linux, `setHandler` scans `args` for the first deep-link-shaped entry. From 2.2 it accepts both authority forms (`myapp://path`) and opaque scheme-only forms such as `myapp:?query=…` (common from `xdg-open` on Linux). Windows drive paths (`C:\…`, `D:/…`) are rejected so they never look like schemes. The cold-start URI is delivered to the handler once per process, so registering from a Compose scope that re-runs on recomposition does not re-fire it.

Windows and Linux start a new process for each activation. Combine with `SingleInstanceManager` to forward the URI to the already-running instance: the secondary process records its URI with `captureFromArgs` and writes it with `writeUriTo(path)` before exiting, and the primary reads it back with `readUriFrom(path)`.

The plugin generates every static registration — `Info.plist` entries, Windows registry keys, and `.desktop` files. You declare the scheme once.

## API reference

### Gradle DSL

```kotlin
nativeDistributions {
    protocol(name: String, vararg schemes: String)
}
```

### DeepLinkHandler

`object DeepLinkHandler` in `dev.nucleusframework.core.runtime`.

| Member | Signature | Notes |
|---|---|---|
| `setHandler` | `(args: Array<String>, onDeepLink: (URI) -> Unit)` | Registers the callback and delivers the cold-start URI once. Safe on every backend. |
| `captureFromArgs` | `(args: Array<String>)` | Records a URI from `args` into `uri` without installing a callback or touching AWT. Used by the single-instance secondary bootstrap. |
| `installAwtAppleEventHandler` | `()` | macOS only. Installs the AWT Apple Events handler and initializes AWT. |
| `writeUriTo` | `(path: Path)` | Writes the current `uri` to a file. Pair with `SingleInstanceManager`. |
| `readUriFrom` | `(path: Path)` | Reads a URI from a file and fires the callback. |
| `deliver` | `(newUri: URI)` | Injects a URI into the handler chain. Used by alternative delivery paths and tests. |
| `uri` | `URI?` (read-only) | The most recently received URI, including the cold-start one. |

### NucleusApplicationScope.onDeepLink

```kotlin
nucleusApplication { onDeepLink { uri -> /* ... */ } }
```

Registers a `DeepLinkHandler` callback that defers until the application is running and selects the backend-appropriate delivery path.

## Notes

- `DeepLinkHandler.register(args, onDeepLink)` is deprecated: it always installs the AWT handler and is incompatible with the Tao backend on macOS. Use `onDeepLink { … }` or `setHandler`.
- Test in development with `xdg-open myapp://test` (Linux), `open myapp://test` (macOS), or `start myapp://test` (Windows). Registration through the installer only applies to packaged builds — see [Launcher: Windows](/docs/lifecycle/launcher-windows).
- The cold-start URI is also stored in `DeepLinkHandler.uri`; read it after your handler is registered.
- For file associations (opening a `.csv` with your app), use the plugin's `fileAssociation(...)` DSL instead.

## What's next

- [Single instance](/docs/lifecycle/single-instance) — forward a deep link from a relaunched process to the running one.
- [Launcher: macOS](/docs/lifecycle/launcher-macos) — the `Info.plist` and Apple Events integration.
- [Launcher: Windows](/docs/lifecycle/launcher-windows) — registry registration and jump-list entries.

---

# App metadata at runtime

URL: https://nucleusframework.dev/en/docs/lifecycle/app-metadata

Read your app's id, version, vendor, display name, and Windows AUMID from Kotlin at runtime.

`NucleusApp` lets you read your application's metadata — id, version, vendor, display name, and
Windows AUMID — from Kotlin at runtime. The values come from what you configure in the Nucleus
Gradle plugin and are injected at build time, so you don't hardcode them or read them off disk
yourself.

## Add the dependency

`NucleusApp` lives in the `core-runtime` module, which the Nucleus Gradle plugin already pulls in.
Add the coordinate explicitly only when you read metadata from a module that does not depend on it:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.core-runtime:<version>")
}
```

## Read the metadata

`NucleusApp` is an object. Read its properties directly:

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import dev.nucleusframework.core.runtime.NucleusApp

@Composable
fun AboutDialog() {
    Column {
        Text(NucleusApp.appName ?: NucleusApp.appId)
        NucleusApp.version?.let { Text("Version $it") }
        NucleusApp.vendor?.let { Text("by $it") }
    }
}
```

Each property resolves once and is cached, so reading it repeatedly is cheap.

Use `isConfigured` to tell whether the Nucleus plugin injected metadata at all:

```kotlin
if (NucleusApp.isConfigured) {
    // Running as a packaged app
    initAutoUpdater()
}
```

`isConfigured` is `true` under `./gradlew run` too, because the plugin injects `nucleus.app.id`
into the `run` task. To gate auto-update, telemetry, or anything else you don't want firing in
development, test `ExecutableRuntime.isDev()` instead.

## How it works

The Gradle plugin delivers metadata to `NucleusApp` through two channels. Each property resolves
from them in order, and the first non-blank value wins:

1. **System properties** during `./gradlew run` — the plugin injects `-Dnucleus.app.id` and
   `-Dnucleus.executable.type`. `NucleusApp` reads the other `nucleus.app.*` properties only if
   you set them yourself.
2. **A classpath resource** in packaged builds — `nucleus/nucleus-app.properties`, baked into the
   application jar.

For `appId` only, a third step applies: when neither source provides a value, `appId` derives from
the main class name through `AppIdProvider`, falling back to `NucleusApp` if that too is missing.

A single block in `build.gradle.kts` therefore flows into every runtime module without manual
wiring. The same values back the single-instance lock identifier, the Windows AUMID used for toast
notifications and badge counts, and the MSIX startup task id — all read through `NucleusApp`.

## API reference

### NucleusApp

An object exposing the injected metadata as read-only properties.

| Property | Type | Value |
|---|---|---|
| `appId` | `String` | Application id. Matches the plugin's `packageName`. Falls back to the main class name. |
| `appName` | `String?` | Display name, or `null` if not configured. |
| `version` | `String?` | Application version, or `null` if not configured. |
| `vendor` | `String?` | Application vendor, or `null` if not configured. |
| `description` | `String?` | Application description, or `null` if not configured. |
| `aumid` | `String` | Windows Application User Model ID. Falls back to `appId` when not set. |
| `startupTaskId` | `String?` | MSIX startup task id, injected when `appx { addAutoLaunchExtension = true }`. Used by [Auto-launch](/docs/lifecycle/auto-launch). `null` otherwise. |
| `isConfigured` | `Boolean` | `true` when the plugin injected metadata through the `nucleus.app.id` system property or the classpath resource. |

## Notes

- `appId` and `aumid` are non-null; every other value is nullable. Guard nullable reads or supply
  your own fallback.
- `isConfigured` checks the `nucleus.app.id` system property and the classpath resource, not the
  other individual properties.

## What's next

- [Auto-launch](/docs/lifecycle/auto-launch) — start your app at login using `startupTaskId`.
- [Executable type](/docs/lifecycle/executable-type) — distinguish a DMG, Flatpak, or `./gradlew run` at runtime.
- [Single instance](/docs/lifecycle/single-instance) — the single-instance lock keyed on your app id.

---

# How was I launched?

URL: https://nucleusframework.dev/en/docs/lifecycle/executable-type

Detect at runtime how the app was packaged and launched, from a DMG or Snap to a plain ./gradlew run.

`ExecutableRuntime` reports how the current process was packaged and launched: a DMG, an APPX,
a Flatpak, a Snap, an AppImage, an `.exe` installer, or a plain `./gradlew run`. Read it when
your code needs to branch on the packaging format, for example to pick an auto-update channel,
resolve a writable path, or detect a sandbox.

## Add the dependency

`ExecutableRuntime` and `ExecutableType` ship in `core-runtime`, which the Nucleus umbrella
already pulls in. Add it explicitly only when you depend on the module on its own:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.core-runtime:<version>")
}
```

The `aot-runtime` module re-exports both types as type aliases, so AOT-only code can depend on
it alone.

## Detect the packaging format

Call `ExecutableRuntime.type()` and branch on the returned `ExecutableType`:

```kotlin
import dev.nucleusframework.core.runtime.ExecutableRuntime
import dev.nucleusframework.core.runtime.ExecutableType

when (ExecutableRuntime.type()) {
    ExecutableType.APPX    -> showMicrosoftStoreUpdate()
    ExecutableType.SNAP    -> showSnapStoreUpdate()
    ExecutableType.FLATPAK -> showFlathubUpdate()
    ExecutableType.PKG     -> showMacAppStoreUpdate()
    else                   -> checkForUpdatesDirectly()
}
```

For a single format, use the matching `is*()` check:

```kotlin
if (ExecutableRuntime.isAppX()) {
    // Sandboxed: write to per-package state, not arbitrary HOME paths
}
```

## How it works

The Nucleus Gradle plugin records the packaging format at build time. For packaged JVM apps it
sets `-Dnucleus.executable.type=<kind>` in the launcher's `.cfg` file; for GraalVM native-image
builds, where that system property is unavailable, it writes a `.nucleus-executable-type` marker
file next to the executable.

`ExecutableRuntime.type()` reads the system property first and falls back to the marker file.
Detection matches your packaging pipeline exactly, and does not rely on filesystem heuristics
such as checking whether `/snap/` is in the path.

When neither source is present, as with `./gradlew run` or any unpackaged run, `type()` returns
`ExecutableType.DEV`. Treat that as your dev-mode signal.

Features that need accurate packaging detection short-circuit in dev mode to avoid false
positives. For example, [`AutoLaunch.wasStartedAtLogin(args)`](/docs/lifecycle/auto-launch)
returns `false` whenever `ExecutableRuntime.isDev()` is `true`.

## API reference

### ExecutableRuntime

| Member | Returns | Notes |
|---|---|---|
| `type()` | `ExecutableType` | Reads the `nucleus.executable.type` property, then the marker file. |
| `type(propertyName)` | `ExecutableType` | Reads the format from a custom system property. |
| `parseType(rawValue)` | `ExecutableType` | Parses a raw string; unknown input maps to `DEV`. |
| `markerVersion()` | `String?` | App version from the marker file (native-image builds). |
| `isGraalVmNativeImage` | `Boolean` | `true` when running as a GraalVM native image. |
| `isExe()`, `isMsi()`, `isNsis()`, `isNsisWeb()`, `isPortable()`, `isAppX()`, `isDmg()`, `isPkg()`, `isDeb()`, `isRpm()`, `isSnap()`, `isFlatpak()`, `isAppImage()`, `isPacman()`, `isZip()`, `isTar()`, `isSevenZ()`, `isDev()` | `Boolean` | One check per `ExecutableType` value. |

### ExecutableType

An enum with one value per supported packaging format:

- Windows: `EXE`, `MSI`, `NSIS`, `NSIS_WEB`, `PORTABLE`, `APPX`
- macOS: `DMG`, `PKG`
- Linux: `DEB`, `RPM`, `SNAP`, `FLATPAK`, `APPIMAGE`, `PACMAN`
- Archives: `ZIP`, `TAR`, `SEVEN_Z`
- Dev: `DEV`

## Notes

- `DEV` covers `./gradlew run` and any other unpackaged run. It is also the fallback for an
  unknown or missing type, so a `DEV` result does not distinguish "in the IDE" from
  "misconfigured packaging".
- `ExecutableRuntime` only knows the packaging format, not the app contents. For the running
  version, use [`NucleusApp.version`](/docs/lifecycle/app-metadata).

## What's next

- [App metadata](/docs/lifecycle/app-metadata) — read the app id, version, and vendor at runtime.
- [Auto-launch](/docs/lifecycle/auto-launch) — start the app at login, gated on the packaging format.
- [Auto-update](/docs/packaging/auto-update) — choose an update strategy per distribution channel.

---

# Launcher (macOS)

URL: https://nucleusframework.dev/en/docs/lifecycle/launcher-macos

Populate the Dock right-click menu of a macOS app with items, submenus, and separators, and handle clicks from Kotlin.

`launcher-macos` lets you populate the Dock right-click menu of a macOS app from Kotlin. You
define the menu entries — including submenus, separators, and disabled items — and receive a
callback on the Swing EDT when the user clicks one.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.launcher-macos:<version>")
}
```

## Populate the Dock menu

Call `MacOsDockMenu.setDockMenu(...)` with the items to display, then set a `listener` to
handle clicks. Each item carries a numeric `id` that the listener receives.

```kotlin
import dev.nucleusframework.launcher.macos.DockMenuItem
import dev.nucleusframework.launcher.macos.DockMenuListener
import dev.nucleusframework.launcher.macos.MacOsDockMenu

MacOsDockMenu.setDockMenu(listOf(
    DockMenuItem(id = 1, title = "New Window"),
    DockMenuItem(id = 2, title = "Open File..."),
    DockMenuItem.separator(id = 3),
    DockMenuItem(
        id = 4,
        title = "Recent",
        children = listOf(
            DockMenuItem(id = 41, title = "project.kt"),
            DockMenuItem(id = 42, title = "build.gradle.kts"),
        ),
    ),
    DockMenuItem(id = 5, title = "Preferences"),
))

MacOsDockMenu.listener = DockMenuListener { id ->
    when (id) {
        1 -> openNewWindow()
        2 -> openFile()
        in 40..49 -> openRecent(id)
        5 -> showPreferences()
    }
}
```

Call `MacOsDockMenu.clearDockMenu()` to remove the menu and restore the default Dock behavior.

All methods are no-ops off macOS and when the native library fails to load. Check
`MacOsDockMenu.isAvailable` before you build the menu.

## How it works

The first call to `setDockMenu(...)` installs a method swizzle on the running
`NSApplicationDelegate` to intercept `applicationDockMenu:`. From then on, AppKit asks Nucleus
for the menu whenever the user right-clicks (or Ctrl-clicks) the Dock tile.

Click callbacks are delivered on the Swing EDT, so you can mutate Compose state directly from
the listener without dispatching to another thread.

macOS strips images from Dock menu items. Only text, separators, submenus, and the
enabled/disabled state are rendered — the Dock process owns the drawing, not your app.

For dragging files onto the Dock icon, AWT already exposes `Desktop.setOpenFileHandler` (and
`Desktop.setOpenURIHandler` for deep links). `launcher-macos` does not duplicate that.

## API reference

### `MacOsDockMenu`

The entry point. A single object with one global listener.

| Member | Notes |
|---|---|
| `isAvailable: Boolean` | `false` off macOS or when the native library failed to load. |
| `listener: DockMenuListener?` | One global listener; dispatch by `id` inside it. |
| `setDockMenu(items: List<DockMenuItem>)` | Replaces the menu. Installs the swizzle on the first call. |
| `clearDockMenu()` | Removes the menu; the OS default returns. |

### `DockMenuItem`

A `data class` describing one entry.

| Property | Default | Notes |
|---|---|---|
| `id: Int` | required, `> 0` | Identifier passed to the listener. |
| `title: String` | `""` | Display text. |
| `enabled: Boolean` | `true` | Whether the item is clickable. |
| `children: List<DockMenuItem>` | `emptyList()` | A non-empty list makes the item a submenu. |

`DockMenuItem.separator(id)` builds a separator entry.

### `DockMenuListener`

A `fun interface` with a single method, `onItemClicked(itemId: Int)`, invoked on the Swing EDT.

## Notes

- Test from a packaged build or `runDistributable`. The `java` launcher icon shown by
  `./gradlew run` uses no bundle identifier and will not display the menu meaningfully.
- ProGuard / GraalVM: keep `dev.nucleusframework.launcher.macos.NativeMacOsDockMenuBridge`
  reachable. The module ships the metadata.

## What's next

- [Taskbar progress](/docs/lifecycle/taskbar-progress) — Dock badge, bounce, and progress state.
- [Deep links](/docs/lifecycle/deep-links) — handle `Desktop.setOpenURIHandler` URL events.
- [Launcher (Windows)](/docs/lifecycle/launcher-windows) — taskbar jump lists and thumbnail toolbars.

---

# Launcher (Windows)

URL: https://nucleusframework.dev/en/docs/lifecycle/launcher-windows

Drive the Windows taskbar from Kotlin with overlay icons, jump lists, thumbnail toolbar buttons, and badges.

The `launcher-windows` module exposes four parts of the Windows shell from Kotlin: overlay
icons on the taskbar button, jump lists in its right-click menu, buttons in the taskbar
thumbnail preview, and numeric or glyph badges. Each part is a separate `object` you call
directly; use only the ones you need.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.launcher-windows:<version>")
}
```

## Set an overlay icon

An overlay icon is a 16x16 status marker in the bottom-right corner of the taskbar button.
Pass the AWT `Window` and an icon source:

```kotlin
import dev.nucleusframework.launcher.windows.StockIcon
import dev.nucleusframework.launcher.windows.TaskbarIconSource
import dev.nucleusframework.launcher.windows.WindowsOverlayIcon

WindowsOverlayIcon.setIcon(
    window,
    TaskbarIconSource.FromStock(StockIcon.WARNING),
    description = "1 unread message",
)

// later
WindowsOverlayIcon.clearIcon(window)
```

Overlay icons work with every packaging type. Each call returns `true` on success; check
`WindowsOverlayIcon.isAvailable` first if you support non-Windows platforms.

## Build a jump list

A jump list groups items in the taskbar right-click menu. `setJumpList` replaces the whole
list atomically:

```kotlin
import dev.nucleusframework.launcher.windows.JumpListCategory
import dev.nucleusframework.launcher.windows.JumpListItem
import dev.nucleusframework.launcher.windows.WindowsJumpListManager

WindowsJumpListManager.setJumpList(
    categories = listOf(
        JumpListCategory("Recent", items = listOf(
            JumpListItem("Project A", arguments = "myapp://open?project=a"),
            JumpListItem("Project B", arguments = "myapp://open?project=b"),
        )),
    ),
    tasks = listOf(
        JumpListItem("New window", arguments = "myapp://new"),
        JumpListItem.SEPARATOR,
        JumpListItem("Settings", arguments = "myapp://settings"),
    ),
)
```

For unpackaged apps (NSIS, MSI, distributable), call `WindowsJumpListManager.setProcessAppId()`
once at the very start of `main()`, before any window is created. APPX/MSIX apps skip this —
Windows uses the package identity.

When the user clicks a jump list item, Windows launches a new process with the item's
`arguments` on the command line. Pair it with
[`SingleInstanceManager`](/docs/lifecycle/single-instance) to forward those arguments to the
already-running instance.

## Add thumbnail toolbar buttons

The thumbnail toolbar adds up to 7 clickable buttons to the window's taskbar thumbnail preview.
Register them once per window with `setButtons`:

```kotlin
import dev.nucleusframework.launcher.windows.TaskbarIconSource
import dev.nucleusframework.launcher.windows.ThumbnailToolbarButton
import dev.nucleusframework.launcher.windows.WindowsThumbnailToolbar

WindowsThumbnailToolbar.setButtons(
    window,
    buttons = listOf(
        ThumbnailToolbarButton(id = 0, tooltip = "Previous", icon = TaskbarIconSource.FromFile("icons/prev.ico")),
        ThumbnailToolbarButton(id = 1, tooltip = "Play",     icon = TaskbarIconSource.FromFile("icons/play.ico")),
        ThumbnailToolbarButton(id = 2, tooltip = "Next",     icon = TaskbarIconSource.FromFile("icons/next.ico")),
    ),
    onClick = { buttonId -> handleTransport(buttonId) },
)
```

Windows does not allow adding buttons after the first registration. To change a button's icon,
tooltip, or state later, call `updateButtons(window, buttons)` with the same ids. Call
`unregister(window)` when the window closes.

## Show a badge

Badges show a numeric count or a status glyph on the taskbar button and Start tile. They rely
on an Application User Model ID that Windows grants only to packaged apps, so the badge API
works under APPX/MSIX only. Call `initialize()` once before setting a badge:

```kotlin
import dev.nucleusframework.launcher.windows.BadgeGlyph
import dev.nucleusframework.launcher.windows.WindowsBadgeManager

WindowsBadgeManager.initialize()

WindowsBadgeManager.setGlyph(BadgeGlyph.NEW_MESSAGE)
// or a numeric count
WindowsBadgeManager.setCount(5)

// clear
WindowsBadgeManager.clear()
```

`setCount` shows 1–99 as the number and 99+ above that; `setCount(0)` clears it. Call
`uninitialize()` on shutdown.

## How it works

Overlay icons and the thumbnail toolbar use the COM `ITaskbarList3` interface, keyed by the
HWND of your `java.awt.Window`. COM is initialized lazily on the first call, and thumbnail
button clicks are delivered on the AWT event dispatch thread.

Jump lists use `ICustomDestinationList`. Windows owns the menu, so clicks never reach your
running process — the OS starts a fresh executable with the item's `arguments` appended to the
command line. That is why jump list actions carry data through `arguments` rather than a
callback.

Badges use WinRT and require an AUMID, which Windows only grants to packaged apps.
`WindowsBadgeManager.isAvailable` only reports whether the native library loaded — it is `true` on
any Windows box. `initialize()` is what fails outside APPX/MSIX, so check its return value. Under
APPX/MSIX the AUMID is left empty and Windows uses the package identity; pass an explicit `aumid`
to `initialize` to override it.

## API reference

### Overlay icon

| Member | Description |
|---|---|
| `WindowsOverlayIcon.setIcon(window, icon, description = "")` | Sets the overlay icon. Returns `Boolean`. |
| `WindowsOverlayIcon.clearIcon(window)` | Removes the overlay icon. Returns `Boolean`. |
| `WindowsOverlayIcon.isAvailable` | Whether the native library is loaded on this platform. |
| `WindowsOverlayIcon.lastError` | Message from the last failed call, or `null`. |

### Jump list

| Member | Description |
|---|---|
| `WindowsJumpListManager.setProcessAppId(aumid = null)` | Sets the process AUMID; call at the start of `main()` for unpackaged apps. |
| `WindowsJumpListManager.setJumpList(categories, tasks, knownCategories)` | Replaces the whole jump list. All parameters default to empty. |
| `WindowsJumpListManager.clearJumpList()` | Removes all entries. |

Supporting types:

| Type | Use |
|---|---|
| `JumpListCategory(name, items)` | A named group of items. |
| `JumpListItem(title, arguments, description, icon, isSeparator)` | A click-to-launch entry; all parameters have defaults. |
| `JumpListItem.SEPARATOR` | A visual separator (user tasks only). |
| `KnownCategory.FREQUENT` / `KnownCategory.RECENT` | Shell-managed lists populated from your file associations. |

### Thumbnail toolbar

| Member | Description |
|---|---|
| `WindowsThumbnailToolbar.setButtons(window, buttons, onClick = null)` | Registers up to 7 buttons. Callable once per window. |
| `WindowsThumbnailToolbar.updateButtons(window, buttons)` | Updates icon, tooltip, and flags of already-registered buttons. |
| `WindowsThumbnailToolbar.unregister(window)` | Removes the click callback and restores the window procedure. |

`ThumbnailToolbarButton(id, tooltip, icon, enabled, hidden, noBackground, dismissOnClick, nonInteractive)` —
`id` must be 0–6, `tooltip` at most 259 characters. The `onClick` handler is a
`ThumbBarClickListener` receiving the clicked button's `id`.

### Badge

| Member | Description |
|---|---|
| `WindowsBadgeManager.initialize(aumid = null)` | Prepares the badge subsystem. Required before any badge call; APPX/MSIX only. |
| `WindowsBadgeManager.setCount(count)` | Sets a numeric badge; `0` clears it. |
| `WindowsBadgeManager.setGlyph(glyph)` | Sets a status glyph; `BadgeGlyph.NONE` clears it. |
| `WindowsBadgeManager.clear()` | Clears the badge. |
| `WindowsBadgeManager.uninitialize()` | Releases native resources. |

`BadgeGlyph` values: `NONE`, `ACTIVITY`, `ALARM`, `ALERT`, `ATTENTION`, `AVAILABLE`, `AWAY`,
`BUSY`, `ERROR`, `NEW_MESSAGE`, `PAUSED`, `PLAYING`, `UNAVAILABLE`.

### Icon sources

Every API that takes an icon accepts a `TaskbarIconSource`:

- `TaskbarIconSource.FromStock(stockIcon)` — one of 93 `StockIcon` values (`WARNING`, `ERROR`,
  `INFO`, `SHIELD`, `FOLDER`, ...). No files needed.
- `TaskbarIconSource.FromFile(path)` — an `.ico` file on disk.
- `TaskbarIconSource.FromResource(dllPath, index)` — an icon index inside a resource DLL such
  as `shell32.dll` or `imageres.dll`.

## Notes

- Jump list items need a real executable. They do not fire under `./gradlew run`, where the
  process is `java.exe` — test from `runDistributable` or a packaged build.
- For a progress bar inside the taskbar button itself, rather than an icon overlay, use
  [`taskbar-progress`](/docs/lifecycle/taskbar-progress).

## What's next

- [Launcher (macOS)](/docs/lifecycle/launcher-macos) — the dock menu equivalent on macOS.
- [Launcher (Linux)](/docs/lifecycle/launcher-linux) — launcher entries and quicklists on Linux.
- [Taskbar progress](/docs/lifecycle/taskbar-progress) — progress bars in the taskbar button.
- [Single instance](/docs/lifecycle/single-instance) — forward jump list arguments to a running app.

---

# Launcher (Linux)

URL: https://nucleusframework.dev/en/docs/lifecycle/launcher-linux

Set count badges, progress bars, urgency flags, and right-click quicklist menus on the Linux launcher from Kotlin.

`launcher-linux` maps the `com.canonical.Unity.LauncherEntry` D-Bus interface and the
`com.canonical.dbusmenu` protocol to Kotlin. Use it to draw count badges, progress bars, and
urgency flags on your launcher icon, and to attach a right-click quicklist menu. Desktop
shells that implement the interface include Unity, KDE Plasma, Plank, and budgie-panel.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.launcher-linux:<version>")
}
```

## Set badges and progress

Build the launcher URI from your `.desktop` file id, then set individual properties or push
them all in one signal:

```kotlin
import dev.nucleusframework.launcher.linux.LauncherProperties
import dev.nucleusframework.launcher.linux.LinuxLauncherEntry

val appUri = LinuxLauncherEntry.appUri("myapp.desktop")

// Badge count
LinuxLauncherEntry.setCount(appUri, 42)

// Progress bar (0.0..1.0)
LinuxLauncherEntry.setProgress(appUri, 0.65)

// Set several properties in one signal
LinuxLauncherEntry.update(
    appUri,
    LauncherProperties(
        count = 5,
        countVisible = true,
        progress = 0.8,
        progressVisible = true,
        urgent = false,
    ),
)
```

`setCount` and `setProgress` are wrappers over `update`, so a single call that sets several
properties emits one D-Bus signal.

## Add a quicklist menu

A quicklist is the right-click menu on the launcher icon. Create a `LinuxQuicklist` on a D-Bus
object path, set a click listener, install the menu, then point the launcher entry at the
quicklist path:

```kotlin
import dev.nucleusframework.freedesktop.icons.FreedesktopIcon
import dev.nucleusframework.launcher.linux.DbusmenuItem
import dev.nucleusframework.launcher.linux.LauncherProperties
import dev.nucleusframework.launcher.linux.LinuxLauncherEntry
import dev.nucleusframework.launcher.linux.LinuxQuicklist

val quicklist = LinuxQuicklist("/com/example/MyApp/Menu")

quicklist.listener = LinuxQuicklist.Listener { id ->
    when (id) {
        1 -> openNewWindow()
        2 -> openFile()
        8 -> exitApp()
    }
}

quicklist.setMenu(
    listOf(
        DbusmenuItem(id = 1, label = "New Window", icon = FreedesktopIcon.Action.WINDOW_NEW),
        DbusmenuItem(id = 2, label = "Open File", icon = FreedesktopIcon.Action.DOCUMENT_OPEN),
        DbusmenuItem.separator(id = 3),
        DbusmenuItem(
            id = 8,
            label = "Quit",
            icon = FreedesktopIcon.Action.APPLICATION_EXIT,
            disposition = DbusmenuItem.Disposition.ALERT,
        ),
    ),
)

LinuxLauncherEntry.update(appUri, LauncherProperties(quicklist = quicklist.objectPath))
```

Icons use [`freedesktop-icons`](/docs/os/freedesktop-icons) for symbolic names.

Clear the quicklist and release the D-Bus server on shutdown:

```kotlin
LinuxLauncherEntry.update(appUri, LauncherProperties(quicklist = ""))
quicklist.dispose()
```

## How it works

The Unity Launcher API is a D-Bus signal protocol. You emit an `Update` signal on
`com.canonical.Unity.LauncherEntry` carrying your `.desktop` file URI and a dictionary of
properties (count, progress, urgent, quicklist path). Desktop shells subscribe to the signal
and render the changes on your launcher icon. Nucleus talks to D-Bus through GIO/GDBus over a
single native bridge, without a Java D-Bus library.

Each `LinuxQuicklist` registers its own `com.canonical.dbusmenu` object. The shell queries that
object for the layout, and item clicks are dispatched back on the Swing event dispatch thread
with `SwingUtilities.invokeLater`.

The `.desktop` filename determines which launcher icon receives the signals. `launcher-linux`
never derives it for you — always pass it explicitly, as in
`LinuxLauncherEntry.appUri("myapp.desktop")`. (Auto-detection from the running process is a
[taskbar-progress](/docs/lifecycle/taskbar-progress) feature.)

## API reference

### Update the launcher entry

`LinuxLauncherEntry` is an object.

| Member | Description |
|---|---|
| `isAvailable: Boolean` | `false` outside Linux or when the native library failed to load. |
| `appUri(desktopFileId: String): String` | Builds the `application://<id>` URI used as the signal subject. |
| `update(appUri, properties: LauncherProperties): Boolean` | Emits one `Update` signal with every non-null field. |
| `setCount` / `clearCount` / `setProgress` / `clearProgress` / `setUrgent` / `setUpdating` | Wrappers over `update`. |
| `registerQueryHandler(appUri)` / `unregister()` | Register a `Query` handler for the entry state, then release it on shutdown. |

### Describe properties

`LauncherProperties` has `count`, `countVisible`, `progress`, `progressVisible`, `urgent`,
`quicklist` (the object path of the menu server, or an empty string to unset it), and
`updating`. All fields are nullable, and null fields are skipped when the signal is emitted.

### Build a quicklist

| Member | Description |
|---|---|
| `objectPath: String` | The D-Bus path you bound. Pass it to `LauncherProperties(quicklist = ...)`. |
| `listener: Listener?` | Click callback; `Listener` is a `fun interface` with `onItemClicked(itemId: Int)`. |
| `setMenu(items: List<DbusmenuItem>): Boolean` | Replaces the menu layout and registers the D-Bus object. |
| `dispose()` | Tears down the D-Bus server. |

### Build a menu item

`DbusmenuItem` has `id`, `label` (`_` marks a mnemonic), `icon` (a `FreedesktopIcon`),
`enabled`, `visible`, `type` (`ItemType.STANDARD` or `ItemType.SEPARATOR`), `toggleType`
(`ToggleType.NONE`, `CHECKBOX`, or `RADIO`), `toggleState` (`-1` indeterminate, `0` unchecked,
`1` checked), `shortcut`, `disposition` (`Disposition.NORMAL`, `INFORMATIONAL`, `WARNING`, or
`ALERT`), and `children`.

`DbusmenuItem.separator(id)` builds a separator.

## Notes

- The dbusmenu protocol is stateless on the server side; the shell re-queries the layout on
  every open. To change a toggle's check state, call `setMenu(...)` again with the new
  `toggleState`.
- For cross-platform progress bars, see [`taskbar-progress`](/docs/lifecycle/taskbar-progress),
  which delegates to `launcher-linux` on Linux.
- XFCE without the `docklike-plugin` doesn't implement the Unity API. Detection succeeds, but
  nothing is rendered.

## What's next

- [Taskbar progress](/docs/lifecycle/taskbar-progress) — cross-platform progress and badges.
- [Freedesktop icons](/docs/os/freedesktop-icons) — symbolic icon names for menu items.
- [Launcher (macOS)](/docs/lifecycle/launcher-macos) — the Dock menu equivalent on macOS.

---

# Launch at login

URL: https://nucleusframework.dev/en/docs/lifecycle/auto-launch

Enable, disable, and query start-at-login from Kotlin with a single API that resolves the backend for the current packaging format.

The `autolaunch` module lets you enable, disable, and query start-at-login from Kotlin without
writing per-OS code. It resolves the backend for the current packaging format at runtime — MSIX
startup tasks, the Win32 registry, macOS `SMAppService`, Linux systemd user services, and the
Flatpak background portal — and respects states the user set outside your app.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.autolaunch:<version>")
}
```

On macOS, the JNI bridge in `nucleus.service-management-macos` is pulled in transitively, so you
do not declare it separately.

## Check and toggle auto-launch

Read the current state with `AutoLaunch.state()` and branch on it. Call `enable()` or `disable()`
to change it, and `openSystemSettings()` when the user must act in system UI:

```kotlin
import dev.nucleusframework.autolaunch.AutoLaunch
import dev.nucleusframework.autolaunch.AutoLaunchState

when (AutoLaunch.state()) {
    AutoLaunchState.ENABLED          -> {}
    AutoLaunchState.DISABLED         -> AutoLaunch.enable()
    AutoLaunchState.DISABLED_BY_USER -> AutoLaunch.openSystemSettings()
    AutoLaunchState.UNSUPPORTED      -> { /* macOS < 13, unsupported Linux environment */ }
    else -> {}
}
```

Never loop on `BLOCKED_BY_USER`. When the user disables the app through Task Manager or System
Settings, `enable()` returns `BLOCKED_BY_USER` and keeps refusing until the user re-enables it
manually. Send them to `openSystemSettings()` instead.

To wire a toggle in Compose, drive it from `state()`:

```kotlin
Switch(
    checked = AutoLaunch.state() == AutoLaunchState.ENABLED,
    enabled = AutoLaunch.state() != AutoLaunchState.DISABLED_BY_USER,
    onCheckedChange = { on ->
        if (on) AutoLaunch.enable() else AutoLaunch.disable()
    },
)
```

## Detect a login launch

`wasStartedAtLogin(args)` reports whether the current process was spawned by the login mechanism
rather than started by hand. Check it at your `main()` entry point to skip a splash screen or start
minimized:

```kotlin
fun main(args: Array<String>) {
    if (AutoLaunch.wasStartedAtLogin(args)) {
        startMinimized = true
    }
    // ...
}
```

On macOS the login AppleEvent is delivered after `NSApplication.run()` starts, so the first call
from `main()` usually returns `false`. The method caches positive results, so it is safe to poll it
from a `LaunchedEffect` once the Compose loop is up.

## How it works

The runtime selects a backend from the operating system and the detected executable type — no
per-OS conditional code on your side:

| Packaging | Backend |
|---|---|
| MSIX | WinRT `Windows.ApplicationModel.StartupTask`. The plugin injects the manifest extension when `appx { addAutoLaunchExtension = true }`. |
| Win32 (MSI / NSIS) | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`, reading `StartupApproved\Run` to detect a user disable. |
| macOS DMG / PKG (13+) | `SMAppService.mainApp`. Appears under System Settings → General → Login Items. |
| Linux (host: deb / rpm / AppImage) | systemd user service under `~/.config/systemd/user/`. |
| Linux (Flatpak) | XDG Desktop Portal `org.freedesktop.portal.Background`. |

Three invariants the module enforces, which you should not work around:

1. **User choices are final.** Once the user disables auto-launch through system UI, the state is
   `DISABLED_BY_USER` and `enable()` returns `BLOCKED_BY_USER` until the user re-enables it.
2. **Silent updates do not reset state.** The Win32 backend writes to `Run` only on `enable()` and
   touches `StartupApproved` only on `disable()`.
3. **MSIX requires the manifest extension.** Without `<uap5:StartupTask>` in
   `Package.appxmanifest`, the API returns `UNSUPPORTED`. Set `addAutoLaunchExtension = true` in the
   plugin block and the plugin adds it.

## API reference

### AutoLaunch

`AutoLaunch` is an object; all methods are static.

| Method | Returns | Notes |
|---|---|---|
| `state()` | `AutoLaunchState` | Current auto-launch state. |
| `enable()` | `AutoLaunchResult` | Requests auto-launch on. |
| `disable()` | `AutoLaunchResult` | Requests auto-launch off. |
| `openSystemSettings()` | `Boolean` | Opens `ms-settings:startupapps` (Windows) or System Settings → General → Login Items (macOS). `true` if the UI launched. |
| `wasStartedAtLogin(args)` | `Boolean` | Whether this process was spawned by login. Returns `false` in dev mode. |
| `isEnabled()` | `Boolean` | `true` for `ENABLED` or `ENABLED_BY_POLICY`. |
| `isUserLocked()` | `Boolean` | `true` when the state is `DISABLED_BY_USER`. |
| `diagnostic()` | `String` | Human-readable backend trace for support tickets. |
| `preload()` | `Unit` | Eagerly resolves the backend and loads its JNI library. Call from a background thread to avoid a first-call stall on macOS. |

### AutoLaunchState

`ENABLED`, `DISABLED`, `DISABLED_BY_USER`, `DISABLED_BY_POLICY`, `ENABLED_BY_POLICY`, `UNSUPPORTED`.

`DISABLED_BY_POLICY` and `ENABLED_BY_POLICY` are read-only Group Policy states (MSIX only).

### AutoLaunchResult

`OK`, `UNCHANGED`, `BLOCKED_BY_USER`, `BLOCKED_BY_POLICY`, `UNSUPPORTED`, `ERROR`.

### AutoLaunchConfig

Override the defaults before the first `AutoLaunch` call:

| Property | Affects |
|---|---|
| `taskId` | MSIX startup task id; must match `<uap5:StartupTask TaskId="...">`. |
| `executablePath` | Win32 `HKCU\...\Run` path. Resolved from the running process when `null`. |
| `autostartArgument` | CLI marker appended to the registered command (default `--nucleus-autostart`). |
| `registryValueName` | Win32 `HKCU\...\Run` value name. |
| `backgroundReason` | Reason string shown in the Flatpak portal prompt. |

## Notes

- On MSIX, toggling auto-launch programmatically does not refresh the Task Manager "Startup apps"
  tab live — Windows updates that view after the next login. The stored state is correct; only the
  display lags.
- macOS login detection reads the `keyAELaunchedAsLogInItem` marker from the AppleEvent that
  `loginwindow` dispatches at login. Apple ships no public API for this.
- The generated Linux unit is ordered after `gnome-session-x11-services-ready.target` as well as
  `graphical-session.target` (2.5.6). `graphical-session.target` alone is reached before
  `gsd-xsettings` publishes `Xft.dpi`, so a toolkit that samples the display scale once at startup
  froze at 1.0 and rendered a HiDPI app at half size when it was started at login. systemd ignores
  ordering on units it has not loaded, so the dependency is inert outside GNOME.
- `wasStartedAtLogin()` returns `false` in dev mode (`ExecutableRuntime.isDev()`) to avoid false
  positives from environment variables inherited from the parent shell. Production builds must set
  the `nucleus.executable.type` system property or ship the `.nucleus-executable-type` marker file,
  or `ExecutableRuntime` defaults to `DEV` and the method always returns `false`.

## What's next

- [Executable type](/docs/lifecycle/executable-type) — how the runtime detects the packaging format that drives backend selection.
- [Service management](/docs/lifecycle/service-management) — register login items, agents, and daemons on macOS.
- [Single instance](/docs/lifecycle/single-instance) — route login launches into an already-running process.
- [Scheduler](/docs/lifecycle/scheduler) — run background work after a login launch.

---

# Scheduler — cron jobs that survive reboots

URL: https://nucleusframework.dev/en/docs/lifecycle/scheduler

Run periodic, calendar, and on-boot background tasks from Kotlin that the OS fires on schedule even when your app is closed.

The scheduler module lets you run background tasks on a schedule from Kotlin, even when your
app is closed. You register a task once and the OS — launchd on macOS, Task Scheduler on
Windows, systemd user timers on Linux — fires it on time and handles wakeups and persistence.
Tasks come in three shapes: periodic, calendar, and on-boot.

`DesktopTaskScheduler` is not supported in sandboxed Mac App Store builds (`.pkg`), because it
writes launchd plists at runtime, which the sandbox forbids. Use
[Service Management](/docs/lifecycle/service-management) there instead.

## Add the dependency

```kotlin title="build.gradle.kts"
plugins {
    kotlin("plugin.serialization") version "<kotlin version>"
}

dependencies {
    implementation("dev.nucleusframework:nucleus.scheduler:<version>")
}
```

`kotlinx-serialization-json` is exposed transitively, so you can annotate task input with
`@Serializable` without adding it yourself.

## Schedule a task

### 1. Define a task and a registry

Implement `DesktopTask`, give it a `TaskId`, and register a factory for it. The OS relaunches
your binary to run a task, so the registry is how the receiver maps an ID back to your code.

```kotlin
import dev.nucleusframework.scheduler.DesktopTask
import dev.nucleusframework.scheduler.TaskContext
import dev.nucleusframework.scheduler.TaskId
import dev.nucleusframework.scheduler.TaskRegistry
import dev.nucleusframework.scheduler.TaskResult

val SyncId = TaskId("sync")

class SyncTask : DesktopTask {
    override suspend fun doWork(context: TaskContext): TaskResult {
        performSync()
        return TaskResult.Success
    }
}

val registry = TaskRegistry.Builder()
    .register(SyncId) { SyncTask() }
    .build()
```

### 2. Handle scheduler invocations in main()

When the OS fires a task, it relaunches your binary with a scheduler flag. Check for that at
the top of `main()` and hand control to `DesktopBootReceiver`, which runs the task and exits.

```kotlin
import dev.nucleusframework.scheduler.DesktopBootReceiver

fun main(args: Array<String>) {
    if (DesktopBootReceiver.isSchedulerInvocation(args)) {
        DesktopBootReceiver.handle(args = args, registry = registry)
        return
    }

    // Normal UI startup
    nucleusApplication(args) { /* ... */ }
}
```

This check must come before any UI is built. Otherwise every scheduler fire opens a window.

### 3. Enqueue a request

Build a `TaskRequest` with one of the three factories and enqueue it. Enqueuing is idempotent
by default — see [`ExistingTaskPolicy`](#taskrequest) to change that.

```kotlin
import dev.nucleusframework.scheduler.CronExpression
import dev.nucleusframework.scheduler.DesktopTaskScheduler
import dev.nucleusframework.scheduler.TaskRequest
import java.time.LocalTime
import kotlin.time.Duration.Companion.hours

val scheduler = DesktopTaskScheduler.getInstance()

// Every hour, from enqueue time
scheduler.enqueue(TaskRequest.periodic(SyncId, 1.hours))

// Every day at 09:00, wall-clock
scheduler.enqueue(TaskRequest.calendar(ReportId, CronExpression.everyDayAt(LocalTime.of(9, 0))))

// At system/user login
scheduler.enqueue(TaskRequest.onBoot(StartupCheckId))
```

## How it works

The OS schedulers can't run a Kotlin function — they only run binaries. So the scheduler
registers your application binary with the platform's timer/job system and passes
`--nucleus-scheduler-run <taskId>` on the command line. When that fires, your `main()` runs,
`DesktopBootReceiver.isSchedulerInvocation(args)` returns `true`, and the receiver:

1. Loads the persisted `TaskContext` (input data and attempt count) from the per-task metadata file.
2. Checks any registered constraints against current system state via [`system-info`](/docs/os/system-info).
3. If they are satisfied, calls your `doWork(context)`.
4. Records the outcome — `Success`, `Failure`, `Retry`, or `ConstraintsNotMet` — and, on `Retry`, schedules a single re-run about 5 minutes later.

| Platform | Mechanism | Plist / unit location |
|---|---|---|
| macOS | launchd plists | `~/Library/LaunchAgents/dev.nucleusframework.<appId>.<taskId>.plist` |
| Linux | systemd user service + timer via D-Bus to `org.freedesktop.systemd1.Manager` | `~/.config/systemd/user/nucleus-<appId>-<taskId>.{service,timer}` |
| Windows | Task Scheduler 2.0 COM API (`ITaskService`) | `\Nucleus\<appId>\<taskId>` |

On Linux and Windows, the scheduler doesn't register the app binary directly — it writes a
small wrapper (`.sh` / `.vbs`) that checks the binary still exists. If the user uninstalls the
app without cleaning up, the wrapper self-destructs: it unregisters the timer/task, deletes its
metadata, and removes itself. macOS doesn't get this trick, because the launchd entry must point
directly at the binary to show up correctly in System Settings. Orphan cleanup there relies on
you calling `DesktopTaskScheduler.cancelAll()` from your sign-out or reset flows.

## API reference

### DesktopTaskScheduler

Obtain the singleton with `DesktopTaskScheduler.getInstance()`, or call the methods on the
object directly.

| Method | Returns | Description |
|---|---|---|
| `isAvailable()` | `Boolean` | Whether the platform backend is wired up. |
| `enqueue(request)` | `Boolean` | Registers a task; `true` if scheduled or already present. |
| `cancel(taskId)` | `Boolean` | Removes a task; `true` if it was found. |
| `cancelAll()` | `Unit` | Removes every task this app registered. |
| `isScheduled(taskId)` | `Boolean` | Whether the task is currently scheduled. |
| `getTaskInfo(taskId)` | `TaskInfo?` | State, last/next run, run count, and last result. |
| `getAllTasks()` | `List<TaskInfo>` | Info for every task this app registered. |

### TaskRequest

Create requests with the factories `periodic(taskId, interval)`, `calendar(taskId, expression)`,
and `onBoot(taskId)`. Each takes an optional builder lambda:

```kotlin
import dev.nucleusframework.scheduler.ExistingTaskPolicy
import dev.nucleusframework.scheduler.NetworkType
import dev.nucleusframework.scheduler.RetryPolicy
import kotlin.time.Duration.Companion.hours
import kotlin.time.Duration.Companion.minutes

TaskRequest.periodic(SyncId, 1.hours) {
    inputData(SyncInput(endpoint = "https://api.example.com"))
    retryPolicy(RetryPolicy.ExponentialBackoff(initialDelay = 30.minutes, maxAttempts = 3))
    runImmediately()
    constraints {
        requiredNetworkType = NetworkType.UNMETERED
        requiresBatteryNotLow = true
    }
    existingTaskPolicy(ExistingTaskPolicy.REPLACE)
}
```

The minimum periodic interval is 15 minutes; a shorter value throws.

| Builder method | Description |
|---|---|
| `inputData(value)` | Attach a `@Serializable` payload, persisted as JSON. |
| `retryPolicy(policy)` | `RetryPolicy.Linear` or `RetryPolicy.ExponentialBackoff`. Recorded on the request; the platform backends currently retry at a fixed delay regardless of the policy. |
| `runImmediately()` | Run once on registration, in addition to the interval (periodic only). |
| `constraints { ... }` | Network, charging, idle, and storage conditions. |
| `existingTaskPolicy(policy)` | `KEEP` (default), `UPDATE_DATA`, or `REPLACE`. |

### CronExpression

`everyDayAt(time)`, `everyWeekdayAt(time)` (Monday–Friday), `everyWeekdayAt(day, time)`, and
`everyHour()`. Times use `java.time.LocalTime`; days use `java.time.DayOfWeek`. Expressions map
to systemd `OnCalendar=` syntax on all platforms.

### TaskResult

Return one of these from `doWork`:

- `TaskResult.Success`
- `TaskResult.Failure(message)` — permanent, no retry.
- `TaskResult.Retry(message)` — schedules one re-run about 5 minutes later. The configured `RetryPolicy` is not applied by the platform backends yet.

### Constraints

Set on the `constraints { }` block; all are checked at execution time.

| Property | Type | Description |
|---|---|---|
| `requiredNetworkType` | `NetworkType` | `NOT_REQUIRED`, `CONNECTED`, or `UNMETERED`. |
| `requiresBatteryNotLow` | `Boolean` | Requires battery above 15 %. |
| `requiresCharging` | `Boolean` | Requires the device to be plugged in. |
| `requiresDeviceIdle` | `Boolean` | Requires no user input for at least 5 minutes. |
| `minimumStorageBytes` | `Long?` | Minimum free disk space on the app partition. |

An unsatisfied periodic fire is silently skipped and re-checked on the next trigger. An
unsatisfied calendar or on-boot fire bumps the attempt counter and schedules a single re-run about 5 minutes later.

### SchedulerConfig

Every backend invokes the current executable, resolved from
`ProcessHandle.current().info().command()`. If your app boots through a custom launcher, point
the scheduler at that launcher instead:

```kotlin
import dev.nucleusframework.scheduler.SchedulerConfig

SchedulerConfig.executablePath = "/opt/myapp/myapp-launcher"
SchedulerConfig.executableArguments = listOf("--background")
```

The resulting command is `<executablePath> <executableArguments…> --nucleus-scheduler-run <taskId>`.

| Property | Type | Default | Behavior |
|---|---|---|---|
| `executablePath` | `String?` | `null` | Absolute path to the program the OS scheduler invokes. `null` or blank resolves the current executable. |
| `executableArguments` | `List<String>` | `emptyList()` | Arguments inserted before the `--nucleus-scheduler-run` flag. |

`executablePath` must be absolute: the generated wrapper scripts check that the file still
exists and unregister the task when it is gone, for example after an uninstall.

Set both properties before the first `enqueue` call. The values are baked into the generated
plist, unit, or task at enqueue time, so a later change only affects tasks scheduled afterwards.

## Notes

- Don't put secrets in `inputData` — it's persisted as plain JSON in the per-task metadata file.
  Store references there and resolve credentials from the keychain at run time.
- `CronExpression.everyHour()` means the wall-clock top of the hour, not "one hour from enqueue".
  For a fixed cadence relative to enqueue time, use `TaskRequest.periodic(id, 1.hours)`.
- For tests, the `scheduler-testing` module ships `TestTaskRunner` for isolated unit tests and
  `TestDesktopTaskScheduler` with virtual time, execution history, and a `TestConstraintChecker`.

## What's next

- [Service Management](/docs/lifecycle/service-management) — background agents and daemons for sandboxed macOS builds.
- [System info](/docs/os/system-info) — the signals the scheduler reads to evaluate constraints.
- [Auto-launch](/docs/lifecycle/auto-launch) — start your app itself at login, not just a task.

---

# Scheduler testing

URL: https://nucleusframework.dev/en/docs/lifecycle/scheduler-testing

Test doubles for the scheduler that run background tasks in memory, with virtual time and controllable constraints.

The scheduler-testing module provides test doubles for the [scheduler](/docs/lifecycle/scheduler)
so you can exercise background tasks in unit and integration tests without touching the OS
scheduler. It runs your `DesktopTask` implementations in memory, advances a virtual clock to
fire periodic schedules, and lets you simulate constraint failures.

## Add the dependency

Add the artifact on the test classpath. It brings in the `scheduler` module transitively.

```kotlin title="build.gradle.kts"
dependencies {
    testImplementation("dev.nucleusframework:nucleus.scheduler-testing:<version>")
}
```

## Test a task in isolation

To unit-test a single task, call `TestTaskRunner.runTask()`. It invokes your task's `doWork()`
with a fabricated `TaskContext` and returns the `TaskResult`, with no scheduler or OS involved.

```kotlin
import dev.nucleusframework.scheduler.TaskData
import dev.nucleusframework.scheduler.TaskId
import dev.nucleusframework.scheduler.TaskResult
import dev.nucleusframework.scheduler.testing.TestTaskRunner
import kotlin.test.Test
import kotlin.test.assertEquals

class SyncTaskTest {
    @Test
    fun `sync succeeds`() = runTest {
        val result = TestTaskRunner.runTask(
            task = SyncTask(),
            taskId = TaskId("sync"),
            inputData = TaskData.of(SyncInput(endpoint = "https://test.api")),
        )
        assertEquals(TaskResult.Success, result)
    }
}
```

`taskId`, `inputData`, and `runAttemptCount` all have defaults, so a bare
`TestTaskRunner.runTask(task = SyncTask())` works when your `doWork()` reads none of them. Set
`runAttemptCount` to exercise retry-aware logic.

## How it works

`TestDesktopTaskScheduler` implements the same internal `PlatformScheduler` interface that the
real backend uses. Calling `install()` routes every `DesktopTaskScheduler` call — `enqueue()`,
`cancel()`, `getTaskInfo()`, and the rest — to the in-memory instance instead of launchd, Task
Scheduler, or systemd. `uninstall()` (also called by `close()`) restores the platform default.

The test scheduler holds its own virtual clock. Enqueuing records the task and its enqueue
time; `advanceTimeBy()` walks the clock forward and fires each periodic task at every interval
boundary crossed, in chronological order. Each firing runs `doWork()` through the same code path
as `runTask()` and appends an `ExecutionRecord` to the task's history, so you can assert on run
counts, attempt numbers, and results after the fact.

`TestConstraintChecker` replaces the production constraint checker with mutable fields that
stand in for system state — network, battery, charging, idle time, and storage. When a task
carries `Constraints`, the checker decides whether `doWork()` runs or the firing is recorded as
`LastTaskResult.ConstraintsNotMet`.

## API reference

### Test a single task's doWork()

`TestTaskRunner` is an object with one function.

| Member | Signature | Behavior |
|---|---|---|
| `runTask(...)` | `suspend (task: DesktopTask, taskId: TaskId = TaskId("test-task"), inputData: TaskData = TaskData.EMPTY, runAttemptCount: Int = 1): TaskResult` | Runs `task.doWork()` with a `TaskContext` built from the arguments and returns its result. |

### Run tasks through the scheduler

`TestDesktopTaskScheduler(constraintChecker: TestConstraintChecker? = null)` implements the
scheduler backend and is `Closeable`. Use it with `use { }` so the platform default is always
restored.

```kotlin
import dev.nucleusframework.scheduler.DesktopTaskScheduler
import dev.nucleusframework.scheduler.LastTaskResult
import dev.nucleusframework.scheduler.TaskRequest
import dev.nucleusframework.scheduler.testing.TestDesktopTaskScheduler
import kotlin.time.Duration.Companion.hours

TestDesktopTaskScheduler().use { testScheduler ->
    testScheduler.install()

    DesktopTaskScheduler.enqueue(TaskRequest.periodic(SyncId, 2.hours))

    // Advance six hours — the 2-hour task fires three times
    val fired = testScheduler.advanceTimeBy(6.hours, registry)
    assertEquals(3, fired.size)

    val history = testScheduler.getExecutionHistory(SyncId)
    assertEquals(LastTaskResult.Success, history.last().result)
}
```

| Member | Signature | Behavior |
|---|---|---|
| `install()` | `Unit` | Routes `DesktopTaskScheduler` calls to this instance. Installs `constraintChecker` if set. |
| `uninstall()` | `Unit` | Restores the platform default backend (and constraint checker). Called by `close()`. |
| `runTask(taskId, registry)` | `suspend (TaskId, TaskRegistry): TaskResult?` | Runs one enqueued task now. Returns `null` and records `ConstraintsNotMet` if its constraints fail. Throws if the task is not enqueued. |
| `advanceTimeBy(duration, registry)` | `suspend (Duration, TaskRegistry): List<ExecutionRecord>` | Advances virtual time and fires every periodic task whose interval elapsed. Skips calendar and on-boot tasks. |
| `currentVirtualTimeMs` | `Long` | The current virtual time. |
| `getExecutionHistory(taskId)` | `(TaskId): List<ExecutionRecord>` | Chronological execution history for one task. |
| `getAllExecutionHistory()` | `(): List<ExecutionRecord>` | Chronological execution history across all tasks. |
| `getEnqueuedRequest(taskId)` | `(TaskId): TaskRequest?` | The stored request for a task, or `null`. |
| `getEnqueuedRequests()` | `(): List<TaskRequest>` | Every currently enqueued request. |
| `constraintChecker` | `TestConstraintChecker?` | The checker passed to the constructor, if any. |

Each `ExecutionRecord` is a data class exposing `taskId: TaskId`, `result: LastTaskResult`,
`runAttemptCount: Int`, and `virtualTimeMs: Long`.

`advanceTimeBy()` only fires periodic tasks. Trigger a calendar or on-boot task explicitly with
`runTask(taskId, registry)`.

### Simulate constraints

`TestConstraintChecker()` is a `Closeable` checker with mutable fields for the system state that
`Constraints` are evaluated against. Pass it to `TestDesktopTaskScheduler` to have its lifecycle
co-managed, or call `install()` / `uninstall()` yourself.

```kotlin
import dev.nucleusframework.scheduler.testing.TestConstraintChecker
import dev.nucleusframework.scheduler.testing.TestDesktopTaskScheduler

val checker = TestConstraintChecker()
TestDesktopTaskScheduler(constraintChecker = checker).use { testScheduler ->
    testScheduler.install()
    checker.networkConnected = false

    // A task that requires network is skipped and recorded as ConstraintsNotMet
    val result = testScheduler.runTask(SyncId, registry)
    assertNull(result)
}
```

| Field | Type | Default | Meaning |
|---|---|---|---|
| `networkConnected` | `Boolean` | `true` | Whether any network is active. |
| `networkUnmetered` | `Boolean` | `true` | Whether the active network is unmetered (only when connected). |
| `batteryLevel` | `Float?` | `1.0f` | Charge level `0.0`–`1.0`; `null` simulates no battery. |
| `isCharging` | `Boolean` | `false` | Whether the device is plugged in. |
| `idleTimeSeconds` | `Long` | `0L` | User idle time in seconds; `-1` simulates unavailable. |
| `availableStorageBytes` | `Long` | `Long.MAX_VALUE` | Free disk space in bytes. |

## What's next

- [Scheduler](/docs/lifecycle/scheduler) — register tasks, build requests, and configure constraints and retries.
- [Lifecycle overview](/docs/lifecycle) — the rest of the OS-facing lifecycle modules.

---

# Service Management (macOS)

URL: https://nucleusframework.dev/en/docs/lifecycle/service-management

Register login items, launch agents, and launch daemons through the macOS SMAppService API from Kotlin.

`service-management-macos` lets you register login items, launch agents, and launch daemons
through Apple's `SMAppService` API (macOS 13+) from Kotlin. It pairs with the Gradle plugin's
`launchAgents { }` DSL, which embeds the corresponding plists in the app bundle at build time,
so the services also work inside the Mac App Store sandbox where writing plists at runtime is
not allowed.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.service-management-macos:<version>")
}
```

`AppServiceManager.isAvailable` returns `false` on macOS versions below 13 and when the native
library is not loaded. Check it before you register a service.

## Launch the app at login

`MainApp` registers the app itself as a login item. It maps to `SMAppService.mainApp`, so no
plist is required:

```kotlin
import dev.nucleusframework.servicemanagement.AppService
import dev.nucleusframework.servicemanagement.AppServiceManager
import dev.nucleusframework.servicemanagement.AppServiceStatus

AppServiceManager.register(AppService.MainApp)

when (AppServiceManager.status(AppService.MainApp)) {
    AppServiceStatus.ENABLED -> { /* launches at next login */ }
    AppServiceStatus.REQUIRES_APPROVAL -> AppServiceManager.openSystemSettingsLoginItems()
    else -> {}
}
```

For a cross-platform "launch at login", use [`AutoLaunch`](/docs/lifecycle/auto-launch) — it
routes to `AppService.MainApp` on macOS. Use `service-management-macos` directly when you need
agents or daemons.

## Register a background agent

A launch agent runs in the user session on a schedule, independent of the main app window.

1. Declare the agent in `build.gradle.kts`:

   ```kotlin title="build.gradle.kts"
   nucleus.application {
       nativeDistributions {
           macOS {
               launchAgents {
                   agent("com.myapp.background-sync") {
                       arguments("--sync")
                       startInterval(900) // 15 minutes
                   }
               }
           }
       }
   }
   ```

   The plugin generates `com.myapp.background-sync.plist` and embeds it in
   `Contents/Library/LaunchAgents/`.

2. Handle the agent argument in `main()`:

   ```kotlin
   fun main(args: Array<String>) {
       if ("--sync" in args) {
           performSync()
           return
       }
       nucleusApplication(args) { /* ... */ }
   }
   ```

3. Register the agent from your UI. macOS does not run the embedded plist until the app
   registers it and the user approves it:

   ```kotlin
   val agent = AppService.Agent("com.myapp.background-sync")
   AppServiceManager.register(agent)
   ```

The first registration shows a system notification ("MyApp wants to run in the background").
The user approves it there, or later from System Settings → General → Login Items.

## How it works

`SMAppService` replaces the deprecated `SMLoginItemSetEnabled` and direct `launchctl` plist
writes. Every background item is gated by user approval, listed in System Settings, and tied to
a plist that ships inside the app bundle, so the entry is removed when the user deletes the app.

The Gradle plugin's `launchAgents { }` DSL writes the plist with the expected keys (`Label`,
`ProgramArguments`, `StartInterval` or `StartCalendarInterval`, `RunAtLoad`, `KeepAlive`,
`ProcessType`) to `Contents/Library/LaunchAgents/<label>.plist`. The bundle program path is
resolved from `packageName` when you omit `bundleProgram`.

Calendar intervals map to a `StartCalendarInterval` array. Call `calendar { ... }` more than
once to fire on several wall-clock moments (launchd weekday convention: 0 = Sunday, 1 = Monday):

```kotlin
agent("com.myapp.weekly-cleanup") {
    arguments("--cleanup")
    calendar { weekday = 1; hour = 18; minute = 0 } // Monday at 18:00
    calendar { weekday = 5; hour = 18; minute = 0 } // Friday at 18:00
}
```

Compared to the [scheduler](/docs/lifecycle/scheduler), this approach works inside the App Store
sandbox because the plists are embedded at build time rather than written at runtime. In return
it has no constraints DSL, no input-data layer, and the set of agents is fixed at build time. Use
the scheduler for dynamic schedules outside the sandbox, and service management for static,
sandboxed services.

## API reference

### Register and query a service

| Member | Returns | Description |
|---|---|---|
| `isAvailable` | `Boolean` | `true` on macOS 13+ with the native library loaded. |
| `register(service)` | `Result<Unit>` | Registers the service so it is eligible to run. |
| `unregister(service, callback)` | `Unit` | Unregisters the service asynchronously; `callback` receives an error string, or `null` on success. |
| `status(service)` | `AppServiceStatus` | Current registration state. |
| `openSystemSettingsLoginItems()` | `Boolean` | Opens the Login Items pane in System Settings. |

### Service kinds — `AppService`

| Variant | Use |
|---|---|
| `MainApp` | The app itself as a login item. No plist required. |
| `LoginItem(bundleIdentifier)` | Helper app under `Contents/Library/LoginItems/`. |
| `Agent(label)` | Launch agent under `Contents/Library/LaunchAgents/`. The `.plist` suffix is added if missing. |
| `Daemon(label)` | Launch daemon under `Contents/Library/LaunchDaemons/`. The `.plist` suffix is added if missing. |

### Registration state — `AppServiceStatus`

`NOT_REGISTERED`, `ENABLED`, `REQUIRES_APPROVAL`, `NOT_FOUND`. Approval is user-driven through
System Settings; call `openSystemSettingsLoginItems()` when `status` returns `REQUIRES_APPROVAL`.

### Declare an agent — `launchAgents { agent(label) { ... } }`

| Method | Description |
|---|---|
| `bundleProgram(path)` | Executable inside the bundle. Resolved from `packageName` when omitted. |
| `arguments(vararg)` | Extra arguments passed to the program. |
| `startInterval(seconds)` | Fixed interval in seconds (recommended minimum 900 = 15 minutes). |
| `calendar { ... }` | Wall-clock trigger (`month`, `day`, `weekday`, `hour`, `minute`). Call multiple times for an array. |
| `runAtLoad(enabled)` | Run the agent immediately when launchd loads it. |
| `keepAlive(enabled)` | Restart the agent if it exits. |
| `processType(type)` | `"Background"` (default), `"Standard"`, or `"Adaptive"`. |

## Notes

- Use the same label in `AppService.Agent("...")` and the Gradle `agent("...")` block.
- Bundle layout: agent plists live at `MyApp.app/Contents/Library/LaunchAgents/`, daemons under
  `LaunchDaemons/`, and login-item helpers under `LoginItems/`.
- ProGuard: keep the runtime types with `-keep class dev.nucleusframework.servicemanagement.** { *; }`.

## What's next

- [Auto-launch](/docs/lifecycle/auto-launch) — cross-platform launch at login.
- [Scheduler](/docs/lifecycle/scheduler) — dynamic background tasks with constraints.
- [Gradle DSL](/docs/reference/gradle-dsl) — the full `nucleus { }` configuration.
- [Packaging for macOS](/docs/packaging/macos) — signing and distributing the bundle.

---

# Energy manager

URL: https://nucleusframework.dev/en/docs/lifecycle/energy-manager

Lower your app's OS scheduling priority and keep the display awake from Kotlin.

The `energy-manager` module lets you control two forms of power behavior from Kotlin: lowering
your app's CPU, I/O, and timer priority when it runs in the background, and preventing the
display and system from sleeping during a long task. Both work on Windows, macOS, and Linux
through the `EnergyManager` object.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.energy-manager:<version>")
}
```

## Throttle a background window

Efficiency mode comes in two levels. Light mode deprioritizes CPU scheduling only; full mode
also throttles I/O and, on macOS, network. Tie them to window state — light mode when the
window loses focus, full mode when it is minimized:

```kotlin
import dev.nucleusframework.energymanager.EnergyManager

LaunchedEffect(state.isMinimized, isWindowFocused) {
    when {
        state.isMinimized -> {
            EnergyManager.disableLightEfficiencyMode()
            EnergyManager.enableEfficiencyMode()       // full — CPU and I/O throttled
        }
        !isWindowFocused -> {
            EnergyManager.disableEfficiencyMode()
            EnergyManager.enableLightEfficiencyMode()  // CPU only — I/O stays normal
        }
        else -> {
            EnergyManager.disableEfficiencyMode()
            EnergyManager.disableLightEfficiencyMode()
        }
    }
}
```

## Run a coroutine with reduced priority

`withEfficiencyMode` runs a block on a dedicated background-priority thread and disposes the
thread when the block returns. `withLightEfficiencyMode` applies process-level light QoS for
the duration of the block, without pinning it to a thread:

```kotlin
// Dedicated low-priority thread (thread-level efficiency), I/O not throttled
val report = EnergyManager.withEfficiencyMode {
    computeHeavyReport()
}

// Process-level light QoS for the block — useful for batch I/O work
EnergyManager.withLightEfficiencyMode {
    syncDataFromServer()
    writeToDatabase()
}
```

Both helpers restore the previous mode when the block returns, including when it throws. Manual
`enable`/`disable` calls are not balanced for you, so pair them yourself.

## Keep the system awake

Prevent sleep while a task or presentation runs, then release the request when it finishes.
Choose whether the **display** must stay on:

```kotlin
import dev.nucleusframework.energymanager.AwakeMode
import dev.nucleusframework.energymanager.EnergyManager

// Presentation / kiosk — screen stays on (default)
EnergyManager.keepAwake(AwakeMode.SYSTEM_AND_DISPLAY)

// Long export / sync — machine stays awake; screen saver and display sleep behave normally
EnergyManager.keepAwake(AwakeMode.SYSTEM_ONLY)

// ... work completes
EnergyManager.releaseAwake()
```

| Mode | System sleep | Display / screen saver |
|------|--------------|------------------------|
| `SYSTEM_AND_DISPLAY` (default) | Blocked | Blocked — screen stays on |
| `SYSTEM_ONLY` | Blocked | Allowed — screen can blank or lock |

Calling `keepAwake` while a request is already active replaces it with the new mode.
`keepScreenAwake()` / `releaseScreenAwake()` / `isScreenAwakeActive()` remain as deprecated
forwarders to `keepAwake()` / `releaseAwake()` / `isAwakeActive()`.

## Hold several awake requests at once

`keepAwake` owns a single slot: the last caller wins, and one `releaseAwake()` drops the
request for everybody. When independent features each need the machine awake — a video player,
a download, a presentation view — acquire a handle per feature instead:

```kotlin
import dev.nucleusframework.energymanager.AwakeMode
import dev.nucleusframework.energymanager.EnergyManager

val playback = EnergyManager.acquireAwake(AwakeMode.SYSTEM_AND_DISPLAY)
val download = EnergyManager.acquireAwake(AwakeMode.SYSTEM_ONLY)

playback.close() // the machine stays awake: `download` is still held
download.close() // last handle gone — the OS request is released
```

`AwakeHandle` implements `AutoCloseable`, so `use { }` scopes a request to a block:

```kotlin
EnergyManager.acquireAwake(AwakeMode.SYSTEM_ONLY).use {
    exportProject()
}
```

Handles coexist with each other and with `keepAwake`. The OS request uses the strongest mode
any live handle asked for, and is released only once every handle is closed and no unmatched
`keepAwake` is left. `close()` is idempotent and thread-safe.

## Keep the screen on from a composable

`Modifier.keepScreenOn()` is Compose Multiplatform's own modifier, and on the
[Tao backend](/docs/tao) it now takes effect: while the modifier is attached, the display stays
awake.

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.keepScreenOn

@Composable
fun VideoSurface() {
    Box(Modifier.keepScreenOn()) {
        Player()
    }
}
```

Prefer it over the imperative calls for anything tied to a piece of UI: the request lives exactly
as long as the composable is in the composition, so there is no release to forget.

Under the hood it is refcounted process-wide and backed by one
`acquireAwake(AwakeMode.SYSTEM_AND_DISPLAY)` handle, so several windows or popups can ask at the
same time without releasing each other, and none of them disturbs a `keepAwake` slot your app
owns. If the request cannot be honored the modifier degrades silently and logs at `FINE`.

The AWT backends do not implement the platform hook, so the modifier composes but has no effect
there.

## How it works

Efficiency mode has two levels. Light mode leaves the app fully functional in the background:
CPU scheduling is deprioritized through QoS hints, but I/O and network run at normal speed, so
sync jobs and downloads still make progress. Full mode is meant for a minimized window where
there is no UI to render — it adds I/O throttling and drops the process to the lowest priority
class. Both are reversible immediately.

Thread-level efficiency applies the same mechanism to the calling thread only. It confines one
heavy coroutine to the slow lane without slowing the rest of the process, which keeps a
responsive UI alongside background work. The `withEfficiencyMode` helper builds on this by
running its block on a single pinned thread.

Each platform maps these levels to native OS facilities:

| OS | Full mode | Light mode | `SYSTEM_AND_DISPLAY` | `SYSTEM_ONLY` |
|---|---|---|---|---|
| Windows 11+ | `SetProcessInformation` EcoQoS + `IDLE_PRIORITY_CLASS` (green leaf in Task Manager 22H2+) | EcoQoS only | `SetThreadExecutionState(ES_SYSTEM_REQUIRED \| ES_DISPLAY_REQUIRED)` | `ES_SYSTEM_REQUIRED` only |
| macOS | `setpriority(PRIO_DARWIN_BG)` + `task_policy_set` QoS Tier 5 (E-core confinement, I/O and network throttling on Apple Silicon) | `task_policy_set` Tier 5 only — CPU deprioritized, I/O unaffected | `IOPMAssertion(kIOPMAssertPreventUserIdleDisplaySleep)` | `kIOPMAssertPreventUserIdleSystemSleep` (like `caffeinate -i`; lid close still sleeps) |
| Linux | `nice +19` + `ioprio` IDLE + `timerslack 100ms` | `nice +10` only | GNOME SessionManager / PowerManagement / logind / X11 | Suspend-only session inhibitor (no X11 screen-saver fallback) |

Thread-level mode uses the per-thread form of these primitives on Linux,
`pthread_set_qos_class_self_np(QOS_CLASS_BACKGROUND)` on macOS, and
`SetThreadInformation`/`THREAD_PRIORITY_IDLE` on Windows.

## API reference

### EnergyManager

| Method | Description |
|---|---|
| `isAvailable(): Boolean` | Whether the native bridge loaded on this platform. |
| `enableEfficiencyMode()` / `disableEfficiencyMode()` | Full process mode. |
| `enableLightEfficiencyMode()` / `disableLightEfficiencyMode()` | Light process mode. |
| `enableThreadEfficiencyMode()` / `disableThreadEfficiencyMode()` | Per-thread; affects the calling thread only. |
| `withEfficiencyMode { }` (suspend) | Runs the block on a dedicated thread with thread-level efficiency; the thread is disposed when the block returns. |
| `withLightEfficiencyMode { }` (suspend) | Applies process-level light QoS for the block's lifetime; no thread pinning. |
| `keepAwake(mode)` / `releaseAwake()` | Prevent and restore system (and optionally display) sleep. One shared slot; the last mode wins. |
| `acquireAwake(mode): AwakeHandle` | Independent awake request released by `AwakeHandle.close()`. |
| `isAwakeActive(): Boolean` | Whether an awake request is currently held. |
| `keepScreenAwake()` / `releaseScreenAwake()` / `isScreenAwakeActive()` | Deprecated forwarders to the `keepAwake` / `releaseAwake` / `isAwakeActive` APIs. |

### AwakeMode

| Value | Description |
|---|---|
| `SYSTEM_AND_DISPLAY` | Block system and display sleep (default). |
| `SYSTEM_ONLY` | Block system sleep only; display and screen saver behave normally. |

### AwakeHandle

| Member | Description |
|---|---|
| `mode: AwakeMode` | The mode this handle requested. |
| `isActive: Boolean` | `false` after `close()`. |
| `close()` | Drops this request. Idempotent and thread-safe. |

Every `enable`/`disable` call and `keepAwake`/`releaseAwake` returns an
`EnergyManager.Result` with `success: Boolean`, `errorCode: Int`, and `message: String`. On an
unsupported platform the result is `success = false` with `errorCode = -1`.

## Notes

- On Linux, `libdbus-1`, `libX11`, and `libXss` are loaded through `dlopen()` at runtime.
  Missing libraries degrade gracefully, and a private DBus connection is used so the module
  does not interfere with the JVM's accessibility bus. `SYSTEM_ONLY` needs a session bus
  (GNOME, PowerManagement) or systemd-logind; the X11 screen-saver fallback cannot serve that mode.
- On Windows 10 1709+, EcoQoS applies only on battery; Windows 11+ honors it on AC power too.
- For a long task that must also wake the device, hold `keepAwake(…)` alongside a job from
  the [scheduler](/docs/lifecycle/scheduler).

## What's next

- [Scheduler](/docs/lifecycle/scheduler) — run deferred and periodic background work.
- [Taskbar progress](/docs/lifecycle/taskbar-progress) — surface long-running task progress on the taskbar.
- [Auto-launch](/docs/lifecycle/auto-launch) — start your app at login.

---

# Taskbar progress

URL: https://nucleusframework.dev/en/docs/lifecycle/taskbar-progress

Draw progress bars and attention requests on the dock, taskbar button, or Unity launcher entry from Kotlin.

The `taskbar-progress` module draws a progress bar and an attention state on the dock icon,
the taskbar button, or the Unity launcher entry from Kotlin. It wraps `NSDockTile` on macOS,
`ITaskbarList3` on Windows, and the `com.canonical.Unity.LauncherEntry` D-Bus protocol on
Linux behind one API that works with both the AWT and Tao backends.

## Add the dependency

For the AWT, JBR, and JNI backends, add the base artifact. Its methods take a `java.awt.Window`.

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.taskbar-progress:<version>")
}
```

For the Tao backend, add the Tao variant. It depends on `nucleus-application` and exposes the
same operations as extension functions on `NucleusWindow`.

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.taskbar-progress-tao:<version>")
}
```

When the native bridge is missing or the desktop environment is unsupported, every call returns
`false` instead of throwing.

## Show progress

`TaskbarProgress` is an object. Each method takes the target `Window` and returns `Boolean`.

```kotlin
import dev.nucleusframework.taskbarprogress.TaskbarProgress
import java.awt.Window

TaskbarProgress.showProgress(window, 0.75)   // normal bar at 75%
TaskbarProgress.showIndeterminate(window)    // pulsing bar
TaskbarProgress.showError(window, 1.0)       // red bar
TaskbarProgress.hideProgress(window)         // clear
```

To request user attention, flash the taskbar button or bounce the dock icon:

```kotlin
TaskbarProgress.requestAttention(window, TaskbarProgress.AttentionType.INFORMATIONAL)
TaskbarProgress.stopAttention(window)
```

## Drive progress from Compose

Pass the AWT window to the composable, update the progress as the work advances, and clear it
when the composable leaves the tree:

```kotlin
import androidx.compose.runtime.*
import dev.nucleusframework.taskbarprogress.TaskbarProgress
import java.awt.Window

@Composable
fun DownloadScreen(window: Window) {
    var progress by remember { mutableStateOf(0.0) }

    DisposableEffect(window) {
        onDispose { TaskbarProgress.hideProgress(window) }
    }

    LaunchedEffect(window) {
        TaskbarProgress.showIndeterminate(window)
        downloadFlow.collect { chunk ->
            progress = chunk.fraction
            TaskbarProgress.showProgress(window, progress)
        }
        TaskbarProgress.hideProgress(window)
    }
}
```

## Use the Tao backend

With `taskbar-progress-tao`, the same operations are extension functions on `NucleusWindow`,
so you call them on the `nucleusWindow` available in a `NucleusDecoratedWindowScope`:

```kotlin
import dev.nucleusframework.taskbarprogress.tao.*

// Inside a NucleusDecoratedWindowScope
nucleusWindow.setTaskbarProgress(0.42)
nucleusWindow.showTaskbarIndeterminate()
nucleusWindow.showTaskbarError()
nucleusWindow.hideTaskbarProgress()
nucleusWindow.requestTaskbarAttention()
```

For declarative use, `rememberTaoTaskbarProgress()` returns a `TaoTaskbarProgressScope?` bound
to the current Tao window, or `null` when called outside a Tao `DecoratedWindow` content lambda:

```kotlin
val taskbar = rememberTaoTaskbarProgress()
taskbar?.setProgress(0.5)
```

## How it works

Each backend maps the same `State` and progress value onto the platform's native mechanism.

| OS | Mechanism |
|---|---|
| Windows | The `ITaskbarList3` COM interface (`SetProgressValue`, `SetProgressState`), plus `FlashWindowEx` for attention. |
| macOS | `NSDockTile` with a custom `NSProgressIndicator`, and `requestUserAttention` for attention. |
| Linux | The `com.canonical.Unity.LauncherEntry` D-Bus protocol, shared with [`launcher-linux`](/docs/lifecycle/launcher-linux). |

macOS shows a single progress indicator per application. The `window` parameter is accepted for
API consistency, but the indicator applies to the app's dock tile, not to a specific window.

The Tao variant routes each call to the same native bridge as the AWT variant; only the window
handle type differs. Calls are dispatched on a dedicated worker thread, so the `Boolean` return
value reports best-effort dispatch, not visual completion.

On Linux the module needs your `.desktop` filename. It is auto-detected from `NucleusApp.appId`,
the `GIO_LAUNCHED_DESKTOP_FILE` and `BAMF_DESKTOP_FILE_HINT` environment variables, the executable
name, and a scan of the XDG application directories. Override detection by setting
`TaskbarProgress.linuxDesktopFilename = "myapp.desktop"`.

## API reference

### `TaskbarProgress`

Every method takes a `java.awt.Window` and returns `Boolean`.

| Method | Effect |
|---|---|
| `isAvailable(): Boolean` | Whether taskbar progress is supported on this platform. |
| `setProgress(window, value: Double)` | Sets the progress fraction; `value` is clamped to `0.0..1.0`. |
| `setState(window, state: State)` | Sets the progress state. |
| `showProgress(window, value)` | `NORMAL` state at `value`. |
| `showError(window, value = 1.0)` | `ERROR` state at `value`. |
| `showIndeterminate(window)` | `INDETERMINATE` state. |
| `showPaused(window, value = 1.0)` | `PAUSED` state at `value`. |
| `hideProgress(window)` | `NO_PROGRESS` state. |
| `requestAttention(window, type = AttentionType.INFORMATIONAL)` | Flashes the taskbar button or bounces the dock icon. |
| `stopAttention(window)` | Cancels an active attention request. |

### `TaskbarProgress.State`

| State | Windows | macOS | Linux |
|---|---|---|---|
| `NO_PROGRESS` | No overlay | Removed | `progress-visible: false` |
| `INDETERMINATE` | Pulsing bar | Static bar at the current value | Same as `NORMAL` — the Unity Launcher protocol has no indeterminate mode |
| `NORMAL` | Green bar | Blue bar | Accent bar |
| `ERROR` | Red bar | Red bar | Progress stays visible; no `urgent` flag — use `requestAttention` |
| `PAUSED` | Yellow bar | Yellow bar | Mapped to progress |

### `TaskbarProgress.AttentionType`

| Value | Windows | macOS |
|---|---|---|
| `INFORMATIONAL` | Flashes the button four times | Bounces the dock icon once |
| `CRITICAL` | Flashes until the app gets focus | Bounces until the app is activated |

### Tao extensions on `NucleusWindow`

`setTaskbarProgress`, `setTaskbarState`, `showTaskbarProgress`, `showTaskbarError`,
`showTaskbarIndeterminate`, `showTaskbarPaused`, `hideTaskbarProgress`,
`requestTaskbarAttention`, and `stopTaskbarAttention`. Each returns `Boolean`.

`rememberTaoTaskbarProgress(): TaoTaskbarProgressScope?` provides the same operations as a
Compose-scoped helper bound to the current window.

## Notes

- On AWT, obtain the `Window` from your `Window` or `DecoratedWindow` scope and pass it to the API.
- Clear the progress in an `onDispose` block so a stale bar does not remain after the composable leaves the tree.
- For Linux quicklists or count badges that are not progress-related, use [`launcher-linux`](/docs/lifecycle/launcher-linux) directly.

## What's next

- [Linux launcher](/docs/lifecycle/launcher-linux) — quicklists, count badges, and urgency on the Unity launcher entry.
- [Windows launcher](/docs/lifecycle/launcher-windows) — overlay icons, jump lists, and thumbnail toolbars.
- [macOS launcher](/docs/lifecycle/launcher-macos) — dock menus and dock tile integration.
- [Energy manager](/docs/lifecycle/energy-manager) — keep the screen awake during long-running work.

---

# Filesystem watcher

URL: https://nucleusframework.dev/en/docs/lifecycle/fs-watcher

Watch files and directories for changes from Kotlin and receive create, modify, remove, and move events as a coroutine Flow.

The fs-watcher module lets you watch files and directories for changes from Kotlin. You create
a watcher, register the paths you care about, and collect create, modify, remove, and move
events from a coroutine `Flow`. The watcher is backed by a native bridge on macOS, Windows, and
Linux, with an optional polling fallback.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.fs-watcher:<version>")
}
```

The module exposes `kotlinx-coroutines-core` transitively, so `Flow` and its operators are on
the classpath without adding coroutines yourself.

## Watch a directory

Check support, create a watcher, start collecting, then register a path. `FsWatchers` and the
event types live in `dev.nucleusframework.fswatcher`.

```kotlin
import dev.nucleusframework.fswatcher.FsWatchEvent
import dev.nucleusframework.fswatcher.FsWatchers
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import java.nio.file.Path

suspend fun watchDownloads() = coroutineScope {
    if (!FsWatchers.isSupported()) return@coroutineScope

    val watcher = FsWatchers.create()

    // Start collecting before you register, so no early events are missed.
    launch {
        watcher.events.collect { event ->
            when (event) {
                is FsWatchEvent.Created -> println("created ${event.path}")
                is FsWatchEvent.Modified -> println("modified ${event.path}")
                is FsWatchEvent.Removed -> println("removed ${event.path}")
                is FsWatchEvent.Moved -> println("moved ${event.from} -> ${event.to}")
                is FsWatchEvent.Overflow -> println("events dropped, rescan needed")
                is FsWatchEvent.Other -> println("other ${event.paths}")
            }
        }
    }

    val home = Path.of(System.getProperty("user.home"))
    watcher.watch(home.resolve("Downloads"), recursive = true)
}
```

`watch` returns an `FsWatchRegistration` you can close to stop watching one path. Closing the
`FsWatcher` closes every registration and releases the native watcher.

`events` and `errors` are hot flows with no replay. Collect them before calling `watch`, or you
may miss changes that happen between registration and the first collector subscribing.

## How it works

Each `FsWatcher` owns one native watcher handle. macOS uses FSEvents, Windows uses
`ReadDirectoryChangesW`, and Linux uses inotify, all reached through a single JNI bridge.
Polling is opt-in via `FsWatchBackendStrategy.Polling` and runs inside that same native library.
There is no JVM-side fallback: when the native library is unavailable, `isSupported()` returns
`false` and `create()` throws `FsWatchException` for every strategy.

Registrations are coalesced. If you watch a directory recursively and then watch a file already
inside it, both share one native watch; events are still routed to each logical registration and
reported against its `FsWatchSource`. Paths are reported relative to the root you registered, so
a symlinked or resolved root still surfaces the path you asked for.

On macOS, FSEvents always reports **canonical** paths. From 2.3, a root reached *through* a
symlink (for example `Files.createTempDirectory()` under `/var` → `/private/var`) is treated as
the same directory for event routing — matching no longer depends on `followSymlinks`. Without
that, watches on temp dirs silently never fired.

Events flow through a bounded buffer (`eventBufferCapacity`, default 64) and errors through a
separate one (`errorBufferCapacity`, default 32). When a buffer fills — or the native backend
reports it dropped notifications — the watcher emits `FsWatchEvent.Overflow` with
`needsRescan = true`, your cue to re-list the affected tree instead of trusting the stream.
By default events are debounced over a 150 ms window; switch to `FsWatchDeliveryMode.Raw` to
receive every native notification unmerged.

## API reference

### Create a watcher

`FsWatchers` is the entry point.

| Member | Returns | Description |
|---|---|---|
| `create(config)` | `FsWatcher` | Builds a watcher. `config` defaults to `FsWatcherConfig()`. Throws `FsWatchException` if no backend is available for the config. |
| `isSupported(config)` | `Boolean` | Whether a backend is available for the given config. Call this before `create`. |

### Watch and collect

`FsWatcher : AutoCloseable` is the watcher itself.

| Member | Type | Description |
|---|---|---|
| `events` | `Flow<FsWatchEvent>` | Hot flow of filesystem events across all registrations. |
| `errors` | `Flow<FsWatchError>` | Hot flow of backend errors, watcher- or path-scoped. |
| `registrations` | `Set<FsWatchSource>` | The paths currently registered. |
| `watch(path, recursive, name)` | `FsWatchRegistration` | Registers `path`. `recursive` defaults to `true`; `name` is an optional label. |
| `close()` | `Unit` | Closes all registrations and the native watcher. |

`FsWatchRegistration : AutoCloseable` represents one registered path. It exposes `source:
FsWatchSource`, `active: Boolean`, and `close()` to stop watching that path alone.

### Configure the watcher

`FsWatcherConfig` is a data class; every field has a default.

| Field | Type | Default | Description |
|---|---|---|---|
| `followSymlinks` | `Boolean` | `false` | Also match events under a root's resolved (real) path. |
| `backend` | `FsWatchBackendStrategy` | `Auto` | Backend selection (see below). |
| `eventBufferCapacity` | `Int` | `64` | Event buffer size; must be `> 0`. |
| `errorBufferCapacity` | `Int` | `32` | Error buffer size; must be `> 0`. |
| `deliveryMode` | `FsWatchDeliveryMode` | `Debounced(150 ms)` | How events are coalesced. |

`FsWatchBackendStrategy` is a sealed interface:

- `FsWatchBackendStrategy.Auto` — the native backend. Currently identical to `NativeOnly`; neither degrades to polling.
- `FsWatchBackendStrategy.NativeOnly` — require the native backend.
- `FsWatchBackendStrategy.Polling(interval, compareContents)` — poll on an interval
  (default 2 s); set `compareContents = true` to detect changes by content rather than metadata.

`FsWatchDeliveryMode` is a sealed interface:

- `FsWatchDeliveryMode.Raw` — deliver every native notification unmerged.
- `FsWatchDeliveryMode.Debounced(window)` — merge bursts within `window` (default 150 ms).

### Handle events

`FsWatchEvent` is a sealed interface. Every variant carries `source: FsWatchSource?` (the
registration it belongs to) and `needsRescan: Boolean`.

| Variant | Fields | Meaning |
|---|---|---|
| `Created` | `path`, `isDirectory` | A file or directory was created. |
| `Modified` | `path`, `isDirectory` | Contents or metadata changed. |
| `Removed` | `path`, `isDirectory` | A file or directory was removed. |
| `Moved` | `from`, `to`, `isDirectory` | An entry was renamed or moved. |
| `Overflow` | — | Events were dropped; re-list the tree. `needsRescan` is `true`. |
| `Other` | `paths`, `isDirectory` | A backend event that doesn't map to the above. |

`isDirectory` is `Boolean?` — `null` when the backend didn't report it.

### Inspect errors

`FsWatchError` is a data class with `message: String`, `source: FsWatchSource?` (null for
watcher-level errors), `recoverable: Boolean`, and `cause: Throwable?`. `FsWatchException`
extends `RuntimeException` and is thrown by `FsWatchers.create` and by `watch` when a
registration fails.

## Notes

- `events` and `errors` have no replay. A late collector sees only events emitted after it
  subscribes, so start collecting before you register paths.
- Treat `FsWatchEvent.Overflow` as a signal to re-scan the affected directory; the stream is not
  a guaranteed-complete log.
- `FsWatcher` and `FsWatchRegistration` are `AutoCloseable`. Close registrations you no longer
  need, and close the watcher on shutdown to release the native handle.

## What's next

- [System info](/docs/os/system-info) — query platform and hardware state from the same runtime.
- [Single instance](/docs/lifecycle/single-instance) — coordinate a single running copy of your app.
- [Scheduler](/docs/lifecycle/scheduler) — run background tasks on a schedule, even when the app is closed.

---

# Performance and native runtimes

URL: https://nucleusframework.dev/en/docs/performance

Nucleus builds the same Kotlin source into two runtimes — a GraalVM native image or a JDK 25 image with an AOT cache — selected from one Gradle DSL.

Nucleus compiles the same Kotlin source into two runtimes, and you choose which one to
produce at build time: a GraalVM native image, or a standard JDK 25 image with an ahead-of-time
(AOT) cache. Both are driven by the same Gradle DSL, so switching between them changes the
build output, not your code.

## The two runtimes

The runtimes differ in how the application is compiled and what it ships with, which leads to
different startup and throughput characteristics.

|                    | GraalVM Native Image             | JDK 25 + AOT cache               |
|--------------------|----------------------------------|----------------------------------|
| Compilation        | Ahead-of-time, closed world      | JIT at runtime, open world       |
| Java runtime       | None; self-contained binary      | Bundled JRE plus AOT cache       |
| Reflection and JNI | Static metadata only             | Dynamic, no restrictions         |
| Artifact           | `nucleus.graalvm-runtime`        | `nucleus.aot-runtime`            |

A GraalVM native image starts quickly and holds a smaller resident set, because it is compiled
ahead of time and bundles no JVM. The JDK runtime reaches higher sustained throughput once
HotSpot's JIT has warmed up on hot paths; the AOT cache shortens that warmup by reusing
class-loading and compilation work from a previous run.

## Choose a runtime

- **GraalVM Native Image** — background utilities, menu-bar apps, CLI-style desktop tools, and
  sandboxed targets such as the App Store or MSIX. Startup is fast, the installer is small, and
  no Java runtime ships with the app.
- **JDK 25 + AOT cache** — long-running, IDE-like tools, data-heavy workloads, plugin hosts, and
  anything that relies on dynamic behavior such as scripting engines, ByteBuddy, or custom
  class loaders. HotSpot's JIT pays off once hot paths warm up, and the AOT cache removes most
  of the warmup cost.
- **Both** — the two can coexist in one project. A team might ship a GraalVM build to the App
  Store and a JDK build with an AOT cache for direct download.

## Switch between runtimes

Both runtimes are configured in the `nucleus.application` block. Enabling `graalvm` produces a
native image; setting `enableAotCache` produces a JDK image with an AOT cache.

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"

    // Produce a GraalVM native image.
    graalvm {
        isEnabled = true
        imageName = "myapp"
    }

    // Or produce a JDK 25 image with an AOT cache.
    nativeDistributions {
        enableAotCache = true
    }
}
```

Both blocks can be present at once. Select which runtime a build produces per build type or per
CI matrix entry, or produce both and let users choose.

## Supporting modules

The native builds rely on a few modules that supply platform metadata and OS integration:

- [Native access](/docs/performance/native-access) — how Nucleus supplies GraalVM's reflection,
  resource, and JNI metadata so you don't hand-write JSON.
- [Native code in Kotlin](/docs/performance/native-code) — write the native side in Kotlin/Native
  and call it from the JVM through a generated FFM bridge.
- [Native library loader](/docs/performance/native-library-loader) — how JNI shared libraries
  from module JARs are loaded and cached.
- [Native HTTP](/docs/performance/native-http) — `HttpClient`, OkHttp, and Ktor wired to the OS
  trust store.
- [Native SSL](/docs/performance/native-ssl) — the OS keychain as the trust-anchor source.

## What's next

- [GraalVM Native Image](/docs/performance/graalvm) — the full Gradle DSL, automatic metadata,
  Gradle tasks, and CI wiring.
- [AOT cache](/docs/performance/aot-cache) — JDK 25's Project Leyden, connected to Gradle in one
  line.
- [Runtimes](/docs/concepts/runtimes) — the architecture behind the two backends.

---

# Benchmarks

URL: https://nucleusframework.dev/en/docs/performance/benchmarks

Measured cross-runtime benchmark results — one Geekbench-style suite run inside a real Compose desktop app across JVM JIT, GraalVM Native Image, SwiftUI, Tauri, and Flutter.

The [`benchmark-demo`](https://github.com/NucleusFramework/Nucleus/tree/main/examples/benchmark-demo)
example runs one Geekbench-style suite — 13 CPU kernels, geometric render ramps, and a list-load
bench — inside a real Compose desktop app, then re-implements the same kernels byte-for-byte in
SwiftUI, Tauri, and Flutter. Every variant runs the identical suite on the same machine, so the
numbers are directly comparable. This page presents the measured results.

## Setup

- **Date:** 2026-07-16
- **Machine:** Apple M4, 10 cores, AC power, thermally stable
- **Toolchains:** Oracle GraalVM 25.1.3+9.1 (Java 25.0.3), OpenJDK 26.0.1, Gradle daemon JBR 21
- **Protocol:** each variant self-runs its suite (3 discarded warmups, then best-of-5 over the CPU kernels). Runs are strictly sequential, one app at a time; peak RSS is sampled during each run. Built-in self-checks pass everywhere.

Composite scores are only comparable within an identical suite. Every value below comes from the
same suite and the same machine session. CPU and GFX: higher is better. list, peak RAM, and app
size: lower is better.

## Summary

Sorted by composite CPU score.

| # | Variant | Runtime | CPU | GFX | list (ms) | Peak RAM | App size |
|---|---------|---------|----:|----:|----------:|---------:|---------:|
| 1 | **jvm-graal** | GraalVM 25.0.3 JIT + ProGuard | 146.7 | 13041 | 21.0 | 695 MB | 160 MB |
| 2 | **tauri** | Rust + WebView (WKWebView) | 142.2 | 15013 | 233.0 | 794 MB † | 5.6 MB ‡ |
| 3 | **jvm-c2-pg** | OpenJDK 26 C2 + ProGuard | 140.4 | 13041 | 20.9 | 616 MB | 119 MB |
| 4 | **swiftui** | Swift/LLVM + SwiftUI | 138.7 | 15254 | 14.4 | 268 MB | 0.34 MB ‡ |
| 5 | **jvm-c2** | OpenJDK 26 C2 (no ProGuard) | 138.5 | 13041 | 21.6 | 620 MB | 136 MB |
| 6 | **aot-o3-pgo** | GraalVM Native `-O3` + PGO | 132.7 | 13859 | 17.1 | 269 MB | 129 MB |
| 7 | **aot-o3** | GraalVM Native `-O3` (ML-inferred) | 100.8 | 13859 | 17.1 | 297 MB | 174 MB |
| 8 | **aot-o2** | GraalVM Native `-O2` | 86.9 | 11239 | 17.2 | 278 MB | 150 MB |
| 9 | **aot-os** | GraalVM Native size-opt (`-Os`) | 80.1 | 10433 | 17.3 | 326 MB | 129 MB |
| 10 | **flutter** | Dart AOT + Impeller | 57.3 | 15133 | 17.2 | 196 MB | 37 MB |

## Key takeaways

- **Raw CPU.** GraalVM JIT leads (146.7). The LLVM baselines (Tauri 142, SwiftUI 139) and OpenJDK C2 (138–140) are bunched together. GraalVM Native only catches the JVM/LLVM pack **with PGO** (100.8 → 132.7); without a profile, `matmul` collapses (3877 vs 12225 MFLOP/s). `-O2` and `-Os` trail further behind.
- **The PGO sweet spot.** `aot-o3-pgo` reaches near-JVM CPU (132.7) with **2.5× lower RAM** (269 MB vs 616–695 MB), a compact `.app` (129 MB), and fast startup. The cost is the PGO flow: instrumented build → GUI run → rebuild. PGO also shrinks the image (174 MB → 129 MB).
- **RAM.** Flutter is the leanest (196 MB), ahead of SwiftUI (268) and GraalVM Native (269–326). The JVMs sit at 616–695 MB. Tauri is the heaviest (794 MB) once the WebKit process tree is counted (†).
- **Startup / list.** Native ~17 ms, JVM ~21 ms, SwiftUI 14 ms (best), Tauri 233 ms (WebView DOM/canvas list rendering — an order of magnitude slower).
- **Lowest CPU is Flutter** (57.3): `raytracer` at a quarter of the pack, weak `matmul`/`sha`/`sieve` — but it compensates with top-tier rendering (GFX 15133).

Tauri/WKWebView is multi-process on macOS. The canvas and JS run in separate WebKit processes
(`com.apple.WebKit.WebContent`, `.GPU`, `.Networking`), not in the app binary. The main-process
RSS alone is 177 MB, but the real footprint — summing the WebKit process tree — is 794 MB, making
Tauri the heaviest variant in RAM, not the lightest. (Summing RSS slightly overcounts shared
`WebKit.framework` pages, so 794 MB is an upper bound; the 177→794 gap is large and real.)

The self-contained variants ship their own runtime, so their weight is the full `.app` (runtime +
Skiko/dylibs + jars/binary): JVM (jlink), GraalVM Native, Flutter. SwiftUI and Tauri rely on the OS
runtime — SwiftUI on the system SwiftUI/AppKit, Tauri on the system WebKit — so their binaries
(0.34 / 5.6 MB) exclude the engine macOS provides. The two size classes are not directly comparable.

## Per-kernel CPU

Throughput, higher is better.

| Kernel | jvm-graal | tauri | jvm-c2-pg | swiftui | jvm-c2 | aot-o3-pgo | aot-o3 | aot-o2 | aot-os | flutter |
|--------|----:|----:|----:|----:|----:|----:|----:|----:|----:|----:|
| mandelbrot | 4.09 | 4.13 | 4.33 | 3.92 | 3.99 | 1.98 | 3.32 | 1.97 | 3.27 | 3.61 |
| nbody | 700.6 | 693.2 | 639.6 | 659.4 | 691.3 | 694.7 | 683.0 | 654.8 | 678.3 | 608.7 |
| raytracer | 17.2 | 19.8 | 18.9 | 19.8 | 19.0 | 17.5 | 15.8 | 14.0 | 7.0 | 4.2 |
| matmul | 14217 | 16224 | 16690 | 16215 | 16724 | 12225 | 3877 | 3244 | 3105 | 3054 |
| blur | 93.4 | 44.5 | 59.7 | 80.7 | 49.2 | 91.5 | 49.5 | 46.6 | 36.5 | 30.0 |
| sha256 | 332.9 | 442.1 | 361.2 | 360.3 | 361.7 | 326.9 | 296.8 | 294.9 | 268.2 | 192.4 |
| sieve | 708.5 | 642.3 | 565.9 | 603.6 | 599.9 | 725.9 | 467.2 | 463.2 | 484.4 | 268.6 |
| fft | 407.8 | 452.7 | 441.5 | 436.9 | 441.1 | 363.9 | 369.6 | 376.3 | 356.8 | 366.9 |
| pi | 0.09 | 0.11 | 0.11 | 0.11 | 0.10 | 0.10 | 0.09 | 0.09 | 0.09 | 0.08 |
| mandelbrot_mt | 15.5 | 16.5 | 15.6 | 16.1 | 16.1 | 14.5 | 14.1 | 7.5 | 12.2 | 10.6 |
| raytracer_mt | 74.5 | 81.2 | 68.6 | 75.0 | 67.2 | 71.4 | 60.2 | 49.9 | 25.5 | 13.7 |
| matmul_mt | 62088 | 69442 | 64038 | 33013 | 63925 | 60113 | 19988 | 17255 | 15956 | 9731 |
| blur_mt | 345.0 | 188.4 | 244.1 | 261.7 | 238.3 | 285.9 | 203.5 | 194.4 | 155.1 | 40.0 |

The Graal compiler signature (JIT and AOT+PGO alike) is strong `blur`/`sieve`, dull `fft`/`sha`. The
known PGO regression on `mandelbrot` reproduces (1.98 with the profile vs 3.32 without).

## Render ramps

Maximum sustained load at ≥ 55 fps, higher is better.

| Variant | Particles | Stars | Texts |
|---------|----:|----:|----:|
| swiftui | 125000 | 18175 | 3906 |
| aot-o3 / o3-pgo | 75000 | 14540 | 6102 |
| jvm (×3) | 50000 | 18175 | 6102 |
| flutter | 50000 | 18175 | 9533 |
| aot-o2 | 50000 | 11632 | 6102 |
| aot-os | 50000 | 9306 | 6102 |
| tauri | 25000 | 18175 | 18618 |

## Reproduce

```bash title="terminal"
cd examples/benchmark-demo

# JVM + native matrix (homogeneous RAM):
JAVA_HOME=<jbr-21> GRAALVM_HOME=<graalvm-25> JDK_C2_HOME=<jdk-26> \
  ONLY="jvm-c2 jvm-c2-pg jvm-graal aot-os aot-o2 aot-o3 aot-o3-pgo" ./run-all.sh

# ports:
ONLY="swiftui tauri flutter" ./run-all.sh
```

Native builds must run with `JAVA_HOME=<graalvm>` (the current JVM must be GraalVM). Otherwise a
stale Gradle-provisioned Oracle JDK 25 without `native-image` can match the `vendor=ORACLE`,
`version=25` spec and get selected, failing the compile. Each variant writes a result JSON; the
full per-variant appendix lives in the example's `RESULTS.md`.

## What's next

- [GraalVM overview](/docs/performance/graalvm) — what native-image gives a Nucleus app.
- [Configuration](/docs/performance/graalvm/configuration#optimize-with-a-pgo-profile) — set up the PGO profile behind the `aot-o3-pgo` result.
- [AOT cache](/docs/performance/aot-cache) — JDK 25+ startup on the JVM path.

---

# GraalVM Native Image

URL: https://nucleusframework.dev/en/docs/performance/graalvm

GraalVM Native Image compiles a Nucleus app ahead of time into a self-contained native binary, with reflection, resource, and JNI metadata generated for every Nucleus module.

GraalVM Native Image ahead-of-time compiles a Compose Desktop app into a single self-contained binary that runs without a JVM. The trade-off is the closed-world assumption: no dynamic class loading, no agents, and every reflective call declared at build time. Nucleus generates that metadata for you, so the same source that builds a JVM app also builds a native image.

## When to use GraalVM Native Image

- Background services, menu-bar apps, and system-tray tools that stay idle but must remain responsive. Daemons and CLIs can set `graalvm { headless = true }` to drop AWT/Skiko from the image — see [Build a headless image](/docs/performance/graalvm/configuration#build-a-headless-image).
- Utilities and launchers where startup time matters.
- Store distribution (App Store, MSIX, Snap) and small self-contained installers that ship no separate JRE.
- Memory-constrained environments such as sandboxes and low-spec hardware.

## Trade-offs

- **No JIT.** A native image runs ahead-of-time compiled code with no just-in-time optimization, so sustained CPU-heavy workloads run slower than on the JVM. For those, use the [AOT cache](/docs/performance/aot-cache) instead.
- **Closed world.** No runtime `Class.forName` driven by dynamic values, no custom classloaders, no scripting engines, no runtime bytecode generation. Libraries that rely on these — Spring, Groovy, ByteBuddy-based mocking, heavy JNA use — are not compatible; ship them with the AOT cache.
- **Per-platform builds.** A native image must be compiled on each target OS, so producing binaries for macOS, Windows, and Linux requires a CI matrix.

Most idiomatic Kotlin libraries — Ktor, kotlinx.serialization, Coil, SQLite, Jewel, Compose, SLF4J — work without extra configuration.

## Requirements

### GraalVM toolchain

Nucleus downloads and caches **GraalVM Community Edition** automatically on the first native
build — you no longer install a toolchain yourself. A `GRAALVM_HOME` environment variable takes
precedence if you want to point at your own. See [Provision the toolchain](/docs/performance/graalvm/configuration#provision-the-toolchain).

GraalVM CE is the default because it is licensed under GPLv2 with the Classpath Exception,
which places no restriction on shipping it inside a paid application. Switch to Oracle GraalVM
with `toolchain { distribution = GraalvmDistribution.ORACLE }` when you need its exclusive
optimizations — Profile-Guided Optimization, `-O3`, ML-inferred profiles and advanced
obfuscation. Oracle GraalVM is free for production use under the GraalVM Free Terms and
Conditions, but the GFTC forbids charging any fee associated with redistributing it, so review
the terms before shipping a paid app. The **deprecated AWT backend** still requires a local
BellSoft Liberica NIK install for its AWT/Swing native-image support.

### Platform toolchains

| Platform | Required |
|----------|----------|
| **macOS** | Xcode Command Line Tools |
| **Windows** | MSVC (Visual Studio Build Tools) |
| **Linux** | GCC, `patchelf`, and `xvfb` for headless compilation |

## How Nucleus builds the native image

Three modules cooperate to produce a native image from the same source as a JVM build:

- **`nucleus.graalvm-runtime`** — the runtime support library. It provides SVM `@TargetClass` substitutions for the AWT internals that don't work as-is under native image (the Fontconfig and Win32 font managers, font creation, the splash screen, and the X11 toolkit WMClass), registers app resources, and exposes `GraalVmInitializer`.
- **The Nucleus Gradle plugin** — generates the reachability metadata (reflection, resources, JNI) for your dependencies and wires the `packageGraalvmNative` task graph.
- **`nucleus.nucleus-application`** — calls `GraalVmInitializer.initialize()` for you and exposes the same `DecoratedWindow` / `NucleusWindow` API as the JVM path, so one source tree produces both artifacts.

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"
    graalvm {
        isEnabled = true
        imageName = "my-app"
    }
}
```

`nucleusApplication` calls `GraalVmInitializer.initialize()` at startup. If you write your own `main()` without it, call `GraalVmInitializer.initialize()` yourself before any AWT or Compose code runs.

## What's next

- [Configuration](/docs/performance/graalvm/configuration) — the full `graalvm { }` DSL and recommended build arguments.
- [Automatic metadata](/docs/performance/graalvm/automatic-metadata) — how reflection, resources, and JNI are resolved for you.
- [Tasks and CI](/docs/performance/graalvm/tasks-ci) — Gradle tasks, output locations, and the GitHub Actions matrix.

---

# Configuration

URL: https://nucleusframework.dev/en/docs/performance/graalvm/configuration

Reference for the graalvm { } DSL block that configures GraalVM native-image builds, including toolchain, image name, build arguments, metadata repository, and per-OS settings.

The `graalvm { }` block inside `nucleus.application { }` configures GraalVM native-image
builds: the toolchain, the output binary, the arguments passed to `native-image`, the
reachability metadata, and the macOS and Windows settings. Every property is lazy and
`Property`-typed. The block is defined on `JvmApplication`, so it sits alongside `mainClass`
and `nativeDistributions`.

## Enable a native image

Set `isEnabled = true`. Nucleus provisions the toolchain for you — a minimal configuration
looks like this:

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"

    graalvm {
        isEnabled = true
        imageName = "myapp"

        // Optional: optimize the image for size instead of the default -O2.
        optimization = NativeImageOptimization.SIZE

        metadataRepository {
            enabled = true           // default
            version = "1.1.4"        // default
            excludedModules.add("com.example:my-lib")
        }
    }
}
```

The toolchain is downloaded automatically (see below) and defaults to GraalVM Community
Edition, `march` and `optimization` are now type-safe enums, and Profile-Guided Optimization is
built in. In 2.0 you installed a GraalVM toolchain yourself and passed size flags through
`buildArgs`.

## Build a headless image

Default is a GUI image: Nucleus registers AWT/Java2D/Skiko reachability metadata and copies
companion native libs (`libawt`, `libfontmanager`, Skiko, …) next to the binary. JNI
registration of AWT types then makes `native-image` pull `libawt` / `libawt_xawt` even when
app code never references `java.awt`.

For a daemon or CLI, set `headless = true`:

```kotlin title="build.gradle.kts"
graalvm {
    isEnabled = true
    headless = true
}
```

That skip list is:

- Level 3 platform metadata (`sun.awt.windows.*` / `sun.lwawt.macosx.*` / `sun.awt.X11.*`,
  Java2D pipelines, font managers). The `main` class reflection entry is still written.
- Always-on Level 1 packs: `jdk-awt`, `jdk-fonts`, `jdk-graphics2d`, Skiko, Compose, tray,
  media player, webview.
- Copying companion GUI native libs into the packaged output.
- Bakes `-Djava.awt.headless=true` into the image.

Leave it `false` for any app that opens a window, a tray, or otherwise needs AWT/Skiko.

## Provision the toolchain

By default Nucleus downloads and caches **GraalVM Community Edition** under
`<gradle-user-home>/nucleus/graalvm` — no local install and no `graalvm/setup-graalvm` step
needed. The download happens only when a native-image task actually runs: listing tasks or
syncing the IDE never pulls a JDK. A `GRAALVM_HOME` environment variable takes precedence,
provided it matches the requested distribution. The `toolchain { }` sub-block maps to
`GraalvmToolchainSettings`.

```kotlin title="build.gradle.kts"
graalvm {
    toolchain {
        autoDownload = true                              // default
        distribution = GraalvmDistribution.COMMUNITY     // default
        channel = GraalvmChannel.INNOVATION              // default; LTS for the long-term-support line
        // version = "25"                                // optional; overrides channel
    }
}
```

| Property | Type | Default | Notes |
|----------|------|---------|-------|
| `autoDownload` | `Property<Boolean>` | `true` | Set `false` to resolve via Gradle's toolchain machinery (`javaLanguageVersion` / `jvmVendor`) instead. |
| `distribution` | `Property<GraalvmDistribution>` | `COMMUNITY` | `COMMUNITY` (GraalVM CE) or `ORACLE` (Oracle GraalVM). See the licensing note below. |
| `channel` | `Property<GraalvmChannel>` | `INNOVATION` | `INNOVATION` (latest release) or `LTS`. Used only when `version` is unset. Applies to both distributions. |
| `version` | `Property<String>` | unset | Overrides `channel`. Accepts `"25i3"`, `"25"`, or a pinned `"25.0.1"`. From 2.5.1, `INNOVATION` resolves to GraalVM **25.3** (`25i3`). |
| `macosIntelFallback` | `Property<Boolean>` | `true` | On Intel Macs (dropped by both distributions after 25.0.1), fall back to BellSoft Liberica NIK. |
| `installDir` | `DirectoryProperty` | `<gradle-user-home>/nucleus/graalvm` | Cache location for the downloaded toolchain. |

### Choose a distribution

GraalVM CE is licensed under GPLv2 with the Classpath Exception, which places no restriction on
shipping it inside a paid application. Oracle GraalVM is governed by the
[GraalVM Free Terms and Conditions](https://www.oracle.com/downloads/licenses/graal-free-license.html)
(GFTC), which permit production and commercial use but only allow redistributing the Program
"provided that You do not charge Your licensees any fees associated with such distribution or
use". Nucleus copies GraalVM runtime libraries (`libjvm`, `libawt`, …) next to the packaged
executable, so this clause applies to your app bundle. Selecting `ORACLE` logs a build warning.
Review the GFTC before shipping a paid application.

Opt into Oracle GraalVM when you need its exclusive optimizations — Profile-Guided
Optimization, `optimization = NativeImageOptimization.LEVEL_3` (`-O3`), ML-inferred profiles,
and `advancedObfuscation`:

```kotlin title="build.gradle.kts"
graalvm {
    toolchain {
        distribution = GraalvmDistribution.ORACLE
    }
}
```

Under the default community toolchain those Oracle-only features degrade gracefully: `-O3`,
`--pgo` and `-H:AdvancedObfuscation` are skipped with a warning instead of failing the build,
and the `runWithPgoInstrument` task is not registered at all.

Install directories embed the distribution (`graalvm-community-jdk-*` vs `graalvm-jdk-*`), so
switching never reuses the other build's download, and a `GRAALVM_HOME` whose distribution
disagrees with the DSL is ignored with a warning.

To build on another community toolchain (Liberica NIK, Mandrel), point `GRAALVM_HOME` at it, or
set `autoDownload = false` and pick a `jvmVendor`.

## graalvm { } reference

| Property | Type | Default | Notes |
|----------|------|---------|-------|
| `isEnabled` | `Property<Boolean>` | `false` | Master switch for the native-image build. |
| `headless` | `Property<Boolean>` | `false` | Daemons/CLIs: skip GUI metadata and native libs. See [Build a headless image](#build-a-headless-image). |
| `imageName` | `Property<String>` | package name | Output binary name. |
| `march` | `Property<NativeImageMarch>` | per-platform | `NATIVE` targets the build CPU; `COMPATIBILITY` targets older CPUs. Unset defaults to `COMPATIBILITY`, except Apple-Silicon macOS which defaults to `NATIVE`. |
| `optimization` | `Property<NativeImageOptimization>` | native-image `-O2` | `QUICK_BUILD` (`-Ob`), `NONE`, `LEVEL_1`..`LEVEL_3`, `SIZE` (`-Os`). `LEVEL_3` is Oracle GraalVM only. |
| `allCharsets` | `Property<Boolean>` | `false` | `true` emits `-H:+AddAllCharsets` (embed every JDK charset; only for legacy encodings). |
| `mlProfileInference` | `Property<Boolean>` | `true` | `false` emits `-H:-MLProfileInference` on **Oracle** toolchains only. On Community, the flag is unrecognized and is skipped with a warning (CE already has no ML pass). |
| `advancedObfuscation` | `Property<Boolean>` | `false` | `true` emits `-H:AdvancedObfuscation=`, renaming symbols inside the binary. Oracle GraalVM only; ignored with a warning elsewhere. |
| `autoIncludeResources` | `Property<Boolean>` | `true` | Bundle the project's own resources (and `project(...)` module resources) into the image. |
| `maxHeapSizePercent` | `Property<Int>` | `25` | Default max heap as a percent of physical RAM. Follows the selected collector (`MaximumHeapSizePercent` for Serial/Epsilon, `MaxRAMPercentage` for G1). |
| `maxHeapSize` | `Property<String>` | unset | Absolute max heap (e.g. `"2g"`, `"512m"`). Takes precedence over `maxHeapSizePercent`. |
| `garbageCollector` | `Property<NativeImageGarbageCollector>` | unset | Bakes `--gc=` (`SERIAL`, `G1`, `EPSILON`). Unset keeps native-image Serial. `G1` is Oracle GraalVM + Linux only and degrades to a warning elsewhere. |
| `exactReachabilityMetadata` | `Property<ExactReachabilityMetadata>` | `APP_PACKAGES` | Dev-loop only (`runGraalvmNative`). See [Exact reachability](#exact-reachability-on-the-dev-loop). |
| `detectOrphanProjectClasses` | `Property<Boolean>` | `true` | Register public no-arg `<init>` for project classes only loaded by naming convention. See [Automatic metadata](/docs/performance/graalvm/automatic-metadata#detect-orphan-project-classes). |
| `reflectionForProjectClasses` | `Property<Boolean>` | `false` | Opt-in sledgehammer: every project class with a public no-arg constructor. |
| `buildArgs` | `ListProperty<String>` | empty | Extra arguments passed to `native-image` (win over the properties above). |
| `javaLanguageVersion` | `Property<Int>` | `25` | Toolchain language version — used only when `toolchain { autoDownload = false }`. |
| `jvmVendor` | `Property<JvmVendorSpec>` | unset | Toolchain vendor — used only when `toolchain { autoDownload = false }`. |
| `nativeImageConfigBaseDir` | `DirectoryProperty` | — | Directory of app-specific `reachability-metadata.json`. Rarely needed. |
| `toolchain` | `GraalvmToolchainSettings` | auto-download | Toolchain provisioning (see above). |
| `pgo` | `GraalvmPgoSettings` | enabled | Profile-Guided Optimization (see below). |
| `macOS` | `GraalvmMacOSSettings` | — | macOS sub-block (see below). |
| `windows` | `GraalvmWindowsSettings` | — | Windows sub-block (see below). |
| `metadataRepository` | `MetadataRepositorySettings` | enabled | Oracle Reachability Metadata Repository (see below). |

## Exact reachability on the dev loop

`exactReachabilityMetadata` enables GraalVM's `--exact-reachability-metadata` on
**`runGraalvmNative` only** (the quick-build loop). Unregistered reflective lookups then throw
`MissingReflectionRegistrationError` naming the missing element, instead of a nested
`ClassNotFoundException` chain. Distributable tasks
(`createGraalvmNativeDistributable`, `packageGraalvmNativeDistributionForCurrentOS`,
`runGraalvmNativeDistributable`) never get the flag — optional-dependency probes in third-party
code would stop taking their fallback path under exact mode.

```kotlin title="build.gradle.kts"
graalvm {
    // Default: scope to the package of mainClass (and subpackages)
    exactReachabilityMetadata = ExactReachabilityMetadata.APP_PACKAGES

    // Multi-root app:
    // exactReachabilityMetadata = ExactReachabilityMetadata.packages(
    //     "io.github.acme",
    //     "com.acme.shared",
    // )

    // Opt out:
    // exactReachabilityMetadata = ExactReachabilityMetadata.OFF
}
```

At run time, pass `-Pnucleus.graalvm.missingRegistration=warn|exit|throw` (default `warn`) so one
dev run surfaces every missing registration. Pre-JDK 23 toolchains degrade to
`-H:ThrowMissingRegistrationErrors=` or skip with a warning.

## Choose a garbage collector

The collector is fixed at build time for native images. Leave it unset for Serial (the right
default for a desktop-sized heap). Set G1 only when the heap outgrows what Serial can collect
without visible pauses, and only on Oracle GraalVM Linux:

```kotlin title="build.gradle.kts"
nucleus.application {
    // HotSpot JVM distribution (launcher + run task)
    garbageCollector = GarbageCollector.Z

    graalvm {
        // Baked into the native image (--gc=)
        garbageCollector = NativeImageGarbageCollector.G1
    }
}
```

| `NativeImageGarbageCollector` | Flag | Notes |
|-------------------------------|------|-------|
| `SERIAL` | `--gc=serial` | Default. Small heaps, pauses grow with heap size. |
| `G1` | `--gc=G1` | Oracle GraalVM + Linux only. Elsewhere: warning + Serial. |
| `EPSILON` | `--gc=epsilon` | No reclamation — benchmarks / short-lived processes only. |

JVM-side `GarbageCollector` values: `SERIAL`, `PARALLEL`, `G1`, `Z`, `SHENANDOAH`, `EPSILON`.
Flags are prepended so an explicit `-XX:+Use…GC` in `jvmArgs` still wins. Unset keeps the
JDK's own ergonomics.

## Set build arguments

`buildArgs` are forwarded verbatim to `native-image` and win over the type-safe properties.
Prefer `optimization` over a raw `-Os`/`-O*` and `allCharsets` over `-H:+AddAllCharsets`; reach
for `buildArgs` for anything without a dedicated property:

| Argument | Purpose |
|----------|---------|
| `-Djava.awt.headless=false` | Enables GUI support. Prefer `graalvm { headless = false }` (the default) over this raw flag; use `headless = true` for daemons. |
| `-H:-IncludeMethodData` | Drops method metadata, reducing binary size by several MB. |

Nucleus does **not** force SLF4J to initialize at build time. The API and the app-selected
backend both initialize at run time, so provider discovery, log levels, and environment-dependent
configuration stay under app control. Forcing `--initialize-at-build-time=org.slf4j` from a
shared runtime module parks SLF4J 2.x backend objects in the image heap while their classes stay
run-time initialized. If you have a fixed, tested backend and want build-time init, opt in
explicitly:

```kotlin title="build.gradle.kts"
graalvm {
    buildArgs.add("--initialize-at-build-time=org.slf4j")
}
```

On Linux and macOS the main native executable is now stripped automatically, reclaiming tens
of MB. Combine with `optimization = NativeImageOptimization.SIZE` for the smallest image.

## Optimize with a PGO profile

Profile-Guided Optimization (Oracle GraalVM only) records how the app actually runs and feeds
that profile back into the next build. It requires
`toolchain { distribution = GraalvmDistribution.ORACLE }`; under the default community
toolchain `runWithPgoInstrument` is not registered. The `pgo { }` sub-block maps to
`GraalvmPgoSettings`.

```kotlin title="build.gradle.kts"
graalvm {
    pgo {
        enabled = true                                                    // default
        profile = layout.projectDirectory.file("graalvm/pgo/default.iprof") // default
    }
}
```

1. Record: `./gradlew runWithPgoInstrument` builds an instrumented image, runs it, and writes
   the profile to `profile` on exit. Exercise the hot paths before quitting.
2. Commit the `.iprof` file. Later full builds (`createGraalvmNativeDistributable`,
   `runGraalvmNativeDistributable`, packaging tasks) apply it automatically as
   `--pgo=<profile>`. The quick-build `runGraalvmNative` path skips PGO and advanced
   obfuscation.

Disable a recorded profile for one build with `-Pnucleus.graalvm.pgo=off`. On community
toolchains (GraalVM CE, Liberica NIK, Mandrel) `--pgo` is unavailable: a recorded profile is
ignored with a warning, and the `runWithPgoInstrument` task does not exist.

| Property | Type | Default | Notes |
|----------|------|---------|-------|
| `enabled` | `Property<Boolean>` | `true` | Apply the profile automatically when the file exists. |
| `profile` | `RegularFileProperty` | `graalvm/pgo/default.iprof` | Recorded profile location. |

## Configure the metadata repository

The Nucleus plugin downloads the
[Oracle GraalVM Reachability Metadata Repository](https://github.com/oracle/graalvm-reachability-metadata)
and resolves entries for every runtime dependency on the classpath. The `metadataRepository { }`
sub-block maps to `MetadataRepositorySettings`.

| Property | Type | Default | Notes |
|----------|------|---------|-------|
| `enabled` | `Property<Boolean>` | `true` | Set to `false` to skip the repository entirely. |
| `version` | `Property<String>` | `"1.1.4"` | Repository artifact version. |
| `excludedModules` | `SetProperty<String>` | empty | `group:artifact` coordinates to skip. |
| `moduleToConfigVersion` | `MapProperty<String, String>` | empty | Pins the metadata directory version for a given module. |

```kotlin title="build.gradle.kts"
metadataRepository {
    moduleToConfigVersion.put("io.ktor:ktor-client-core", "3.0.0")
    excludedModules.add("group:noisy-lib")
}
```

## Configure macOS settings

On macOS (arm64), native images on the default Tao backend build on the auto-provisioned
toolchain (GraalVM CE by default). The deprecated AWT backend still requires BellSoft Liberica
NIK. Intel Macs fall back to Liberica NIK.

The `macOS { }` sub-block maps to `GraalvmMacOSSettings`.

| Property | Type | Default | Notes |
|----------|------|---------|-------|
| `cStubsSrc` | `RegularFileProperty` | — | File of additional C stubs linked into the binary. |
| `minimumSystemVersion` | `Property<String>` | `"12.0"` | Patches the Mach-O `LC_VERSION_MIN_MACOSX` load command. |
| `macOsSdkVersion` | `Property<String>` | `"26.0"` | SDK version stamped into the launcher's Mach-O headers, which controls Liquid Glass eligibility. |

## Configure Windows settings

The `windows { }` sub-block maps to `GraalvmWindowsSettings`. GraalVM native images on
Windows are dynamically linked against the Visual C++ runtime, which is not part of a clean
Windows install. Bundling the runtime DLLs next to the executable lets the app start without
the Visual C++ Redistributable.

| Property | Type | Default | Notes |
|----------|------|---------|-------|
| `bundleCRuntime` | `Property<Boolean>` | `true` | Copies the MSVC runtime DLLs next to the `.exe`. |
| `dlls` | `ListProperty<String>` | `vcruntime140.dll`, `vcruntime140_1.dll`, `msvcp140.dll` | DLL file names copied when `bundleCRuntime` is enabled. |
| `sourceDir` | `DirectoryProperty` | toolchain `bin` | Directory the DLLs are copied from. Point it at the MSVC redistributable if a DLL is missing from the toolchain. |

```kotlin title="build.gradle.kts"
graalvm {
    windows {
        bundleCRuntime = true
        dlls.add("vcruntime140.dll")
    }
}
```

## No release variant

Unlike the JVM build types, GraalVM has no release variant: there is no
`packageReleaseGraalvmNative` and no `runReleaseGraalvmNative`. The public native tasks
follow the JVM pipeline (`runGraalvmNative`, `createGraalvmNativeDistributable`, …). This
is intentional:

- ProGuard's dead-code elimination is redundant. `native-image` already does closed-world
  dead-code elimination at compile time.
- ProGuard can rename classes that are still referenced by `reachability-metadata.json`,
  which breaks the build silently.

Use `optimization = NativeImageOptimization.SIZE` for size optimization instead of ProGuard.

Nucleus ships all generic and platform-specific metadata automatically. You only need
`nativeImageConfigBaseDir` for app-specific entries the automatic layers don't cover, which
is rare. See [Automatic metadata](/docs/performance/graalvm/automatic-metadata) for the five layers.

## What's next

- [GraalVM overview](/docs/performance/graalvm) — what native-image gives a Nucleus app.
- [Automatic metadata](/docs/performance/graalvm/automatic-metadata) — the five metadata layers Nucleus assembles for you.
- [Tasks and CI](/docs/performance/graalvm/tasks-ci) — the Gradle tasks and CI setup for native builds.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — the full `nucleus { }` surface.

---

# Automatic metadata resolution

URL: https://nucleusframework.dev/en/docs/performance/graalvm/automatic-metadata

How Nucleus resolves and merges GraalVM reachability metadata at build time so native images compile without hand-written configuration.

Nucleus resolves and merges GraalVM reachability metadata at build time, so
`packageGraalvmNative` produces a working native binary without you writing reflection,
resource, or JNI configuration by hand. The metadata comes from five sources. Each is
generated into its own directory and passed to `native-image`, and the module's own metadata
is discovered from the classpath.

## Level 1 — per-library metadata

The plugin ships 29 metadata files curated for the Kotlin desktop ecosystem, covering Compose,
Skiko, ktor (including client plugins, server, and websockets), kotlinx.serialization,
SQLite JDBC, `androidx.sqlite` bundled, Coil, JNA, FileKit, SLF4J, Sentry, and others.
Each file may declare a `matchPackages` condition. The `filterGraalvmLibraryMetadata` task reads
these files from the plugin JAR and includes a file only when the corresponding packages are on
the runtime classpath; files without a condition are always included. Libraries in the curated
set are covered without extra configuration. With `graalvm { headless = true }`, the always-on
GUI packs (`jdk-awt`, `jdk-fonts`, `jdk-graphics2d`, Skiko, Compose, tray, media player,
webview) are skipped even when they have no `matchPackages` filter. See
[Build a headless image](/docs/performance/graalvm/configuration#build-a-headless-image).

## Level 2 — GraalVM Reachability Metadata Repository

The `resolveGraalvmReachabilityMetadata` task resolves entries from the
[Oracle GraalVM Reachability Metadata Repository](https://github.com/oracle/graalvm-reachability-metadata)
for each dependency on your runtime classpath. Resolution is enabled by default and uses
repository version `1.1.4`.

Configure this source with the `metadataRepository { }` block: `enabled`, `version`,
`excludedModules`, and `moduleToConfigVersion`. See
[Configuration](/docs/performance/graalvm/configuration).

## Level 3 — platform-specific metadata

The `generateGraalvmPlatformMetadata` task writes reflection metadata for the current operating
system: `sun.awt.windows.*` on Windows, `sun.lwawt.macosx.*` on macOS, and `sun.awt.X11.*` on
Linux, along with Java2D pipelines, font managers, and security providers. It also injects a
reflection entry for your `main` class. No per-platform configuration is required in your build
script. With `graalvm { headless = true }`, the AWT/Java2D platform file is not copied; only
the `main` class reflection entry is written.

## Level 4 — static bytecode analysis

The `analyzeGraalvmStaticMetadata` task scans every compiled class on the runtime classpath,
including your own module's classes, and detects:

- Native methods and their parameter and return types (JNI metadata).
- `Class.forName()` and `MethodHandles.Lookup.findClass()` calls with literal class names
  (reflection metadata).
- `getResource()` and `getResourceAsStream()` calls with literal paths (resource metadata).
- JNI callback parameters — classes passed to native code that call back into Java.
- JNI superclass chains — parent classes needed for field access from native code.
- `@Serializable` classes — emits the `Companion.serializer()` reflection entry.

### Detect orphan project classes

Annotation processors and naming-convention loaders (Room `*_Impl`, Dagger/Hilt `*_Factory`,
Moshi adapters, …) produce classes that **no classpath bytecode references**. Literal
`Class.forName` analysis and L1–L3 metadata never see them. From 2.3, a single pass inside the
bytecode analyzer registers a public no-arg `<init>` for those orphans when:

- the class is concrete and public with a public no-arg constructor, and
- a supertype other than `Object` (or an interface) is referenced by app code.

```kotlin title="build.gradle.kts"
graalvm {
    detectOrphanProjectClasses = true    // default
    // reflectionForProjectClasses = true  // opt-in: every project class with a public no-arg ctor
}
```

Build logs emit `[orphan] fqcn` for each registration. Prefer the default detector; only enable
`reflectionForProjectClasses` when you need a temporary sledgehammer (image growth is measurable).

From 2.3.1 the detector resolves project class directories from the **application target's**
compilation outputs (for example `jvm("desktop")` → `desktopMainClasses`) instead of hardcoded
`jvm`/`main` paths, so KMP named JVM targets are covered. Nest-internal reference edges no longer
hide real Room `*_Impl` classes that contain nested types.

## Level 5 — bundled runtime metadata

The `nucleus.graalvm-runtime` module bundles GraalVM metadata inside its JAR:

- A `reachability-metadata.json` with serialization entries.
- A `reachability-metadata.json` whose `resources` section registers the globs `**/*.svg`,
  `**/*.ttf`, `**/*.otf`, `composeResources/**`, `nucleus/**`, and `META-INF/services/**`.
- A `native-image.properties` carrying only `-H:+SharedArenaSupport`, which has no metadata
  equivalent.
- SVM substitutions for the AWT font managers, the splash screen, and the X11 window class.

`native-image` discovers all of it from the classpath, so no configuration is needed.

## How the sources merge

`packageGraalvmNative` runs the generation tasks and then passes each resulting directory to
`native-image` through repeated `-H:ConfigurationFileDirectories=` arguments — the per-library
output (Level 1), the resolved repository directories (Level 2), the platform metadata
(Level 3), and the static-analysis output (Level 4). Any manual entries in your project's own
config directory are included as well. Level 5 is read from the classpath by `native-image`
itself. Most apps compile to a native binary without any hand-written metadata.

## Fill gaps with the tracing agent

The static sources can miss reflection driven by runtime values, dynamically loaded classes, or
unusual library patterns. Run the agent once before a release to catch them:

```shell
./gradlew runWithNativeAgent
```

Exercise every screen and feature. The agent records reflection, JNI, resource, and proxy
accesses into a temporary directory and merges them into your config without overwriting
existing entries. In many cases it finds nothing new.

## Clean up manual entries

If you accumulated manual entries that the automatic sources now cover, remove the redundant
ones:

```shell
./gradlew cleanupGraalvmMetadata
```

The task compares your manual `reachability-metadata.json` against the combined baseline of
Levels 1–4 and removes anything already managed, reporting which entries were removed and which
remain.

From 2.3 it also **reports** entries whose types resolve nowhere on the runtime classpath
(typical agent noise: `kotlin.Any`, `kotlin.Int`, …). Default is report-only. To prune them:

```shell
./gradlew cleanupGraalvmMetadata -Pnucleus.graalvm.cleanup.removeUnresolvable=true
# Analyze without rewriting:
./gradlew cleanupGraalvmMetadata -Pnucleus.graalvm.cleanup.dryRun=true
```

From 2.3.1, well-known Kotlin tracing-agent phantoms (`kotlin.Any` / `Int` / `FunctionN` /
collections mapped types) are **always removed** during cleanup, without requiring
`removeUnresolvable`.

Types under the configured `exactReachabilityMetadata` packages are never removed — a missing
registration under exact mode is what restores a clear error. Remaining manual entries are listed
as `kept — not covered by any managed source`.

## What's next

- [Native access](/docs/performance/native-access) — resource patterns and font substitutions on top of this metadata system.
- [Tasks & CI](/docs/performance/graalvm/tasks-ci) — the full GraalVM task graph.

---

# Tasks & CI

URL: https://nucleusframework.dev/en/docs/performance/graalvm/tasks-ci

The Gradle tasks the Nucleus plugin adds for GraalVM native image, where their output lands, and how to run them on each OS in CI.

The Nucleus Gradle plugin registers a task graph for building and packaging your app
as a GraalVM native image. From 2.2 the public task surface mirrors the JVM distribution
pipeline (`run` / `createDistributable` / `runDistributable` /
`packageDistributionForCurrentOS`), plus per-format packaging tasks (`packageGraalvmDeb`,
`packageGraalvmDmg`, `packageGraalvmNsis`). Most tasks are wired as dependencies of the
internal `packageGraalvmNative` assembler and run automatically. This page lists the tasks,
shows where their output lands, and covers running them on each target OS in CI.

## Gradle tasks

### Public surface (aligned with the JVM pipeline)

| Task | JVM counterpart | Description |
|------|-----------------|-------------|
| `runGraalvmNative` | `run` | Fast dev loop: forces native-image quick-build (`-Ob`), then runs the binary. Overrides the configured `optimization`. From 2.3, enables `--exact-reachability-metadata` scoped by `exactReachabilityMetadata` (default app packages). |
| `createGraalvmNativeDistributable` | `createDistributable` | Build the self-contained native app folder for the current OS (no installer). |
| `runGraalvmNativeDistributable` | `runDistributable` | Build with the configured optimization (full packaging) and run the app folder. |
| `packageGraalvmNativeDistributionForCurrentOS` | `packageDistributionForCurrentOS` | Package the native distribution for the current OS. |

`runGraalvmNative` and the distributable tasks record a `quickBuild` compile input, so
switching between them re-compiles rather than serving a stale binary from the other mode.

### Metadata, installers, and helpers

| Task | Description |
|------|-------------|
| `packageGraalvmNative` | Internal assembler: compile the image and layout the app folder (binary + Skiko/AWT libs + icons + `appResources`). Prefer the public tasks above. |
| `runWithNativeAgent` | Run the app with the GraalVM `native-image-agent` to collect reflection metadata. Sets `compose.application.resources.dir` to the prepared `appResources`. |
| `resolveGraalvmReachabilityMetadata` | Resolve reachability metadata from the Oracle repository for runtime dependencies. Runs automatically. |
| `analyzeGraalvmStaticMetadata` | Statically analyze bytecode to detect reflection, JNI, and resource usage. Runs automatically. |
| `filterGraalvmLibraryMetadata` | Filter and merge per-library metadata against the runtime classpath. Runs automatically. |
| `generateGraalvmPlatformMetadata` | Generate platform-specific metadata for the current OS. Runs automatically. |
| `cleanupGraalvmMetadata` | Remove entries from your manual `reachability-metadata.json` that automatic metadata already covers. |
| `packageGraalvmDeb` | Package the native image as a `.deb` installer (Linux). |
| `packageGraalvmDmg` | Package the native image as a `.dmg` installer (macOS). |
| `packageGraalvmNsis` | Package the native image as an NSIS `.exe` installer (Windows). |

The four metadata tasks run as dependencies of `packageGraalvmNative`, so you rarely
invoke them directly. The `packageGraalvm<Format>` tasks use electron-builder, which
requires Node.js on the runner.

The packaging tasks exist only for target formats you request in `nativeDistributions.targetFormats`.
A task name is the format's enum constant, so `TargetFormat.Deb` produces `packageGraalvmDeb`,
`TargetFormat.Nsis` produces `packageGraalvmNsis`, and so on.

## Run the tasks

```shell
# Fast local iteration (quick-build -Ob)
./gradlew runGraalvmNative

# Full-optimization app folder, then run it
./gradlew runGraalvmNativeDistributable

# Build the self-contained native app folder only
./gradlew createGraalvmNativeDistributable

# Package for the current OS
./gradlew packageGraalvmNativeDistributionForCurrentOS

# Platform installers
./gradlew packageGraalvmDeb     # Linux
./gradlew packageGraalvmDmg     # macOS
./gradlew packageGraalvmNsis    # Windows

# Collect reflection metadata before a release
./gradlew runWithNativeAgent

# Remove redundant manual metadata
./gradlew cleanupGraalvmMetadata
```

The plugin defaults the native-image target architecture (`graalvm.march`) per platform
(`COMPATIBILITY` everywhere, `NATIVE` on Apple-Silicon macOS). To force a portable binary
everywhere, set the type-safe enum:

```kotlin title="build.gradle.kts"
nucleus.application {
    graalvm {
        march = NativeImageMarch.COMPATIBILITY
    }
}
```

The Nucleus sample builds map `graalvm.march` to a Gradle property so you can override it
on the command line. With that wiring,
`./gradlew packageGraalvmNative -PnativeMarch=compatibility` selects the portable target.
The `-PnativeMarch` flag only works if your build script reads the property.

## Output locations

The native app folder lands next to the JVM distributable layout (from 2.2):

```
<project>/build/compose/binaries/<app>/graalvm-app/
```

| Platform | Output |
|----------|--------|
| **macOS** | `graalvm-app/<packageName>/<app>.app/` — full `.app` bundle with `Info.plist`, icons, and signed dylibs |
| **Windows** | `graalvm-app/<packageName>/<app>.exe` plus companion DLLs |
| **Linux** | `graalvm-app/<packageName>/<app>` plus companion `.so` files |

Per-format installers land under the binaries directory, one folder per format:

```
<project>/build/compose/binaries/<app>/graalvm-<format>/
```

`<format>` is the format id, for example `graalvm-deb`, `graalvm-dmg`, or `graalvm-nsis`.

## Build in CI with GitHub Actions

A native image must be compiled on each target OS — you cannot cross-compile. Run a
matrix over `ubuntu-latest`, `macos-latest`, and `windows-latest`, and provision the
toolchain with the `setup-nucleus` action:

```yaml
name: GraalVM release

on:
  push:
    tags: ["v*"]

jobs:
  build-natives:
    uses: ./.github/workflows/build-natives.yaml

  graalvm:
    needs: build-natives
    name: GraalVM - ${{ matrix.name }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        include:
          - { name: Linux x64,    os: ubuntu-latest }
          - { name: macOS ARM64,  os: macos-latest  }
          - { name: Windows x64,  os: windows-latest }

    steps:
      - uses: actions/checkout@v4

      # Download pre-built JNI native libs from the build-natives job here.

      - name: Set up Nucleus (GraalVM)
        uses: NucleusFramework/Nucleus/.github/actions/setup-nucleus@main
        with:
          graalvm: 'true'
          setup-gradle: 'true'
          setup-node: 'true'   # required for packageGraalvm<Format>

      - name: Build the GraalVM native package
        shell: bash
        run: |
          case "$RUNNER_OS" in
            Linux)   ./gradlew :myapp:packageGraalvmDeb  -PnativeMarch=compatibility --no-daemon ;;
            macOS)   ./gradlew :myapp:packageGraalvmDmg  -PnativeMarch=compatibility --no-daemon ;;
            Windows) ./gradlew :myapp:packageGraalvmNsis -PnativeMarch=compatibility --no-daemon ;;
          esac

      - uses: actions/upload-artifact@v4
        with:
          name: graalvm-${{ runner.os }}
          path: myapp/build/compose/binaries/**/graalvm-*/**
```

Native builds download and cache GraalVM Community Edition automatically, so you no longer need
to provision a GraalVM toolchain in CI — `setup-nucleus` installing the JBR is enough. Set
`graalvm: 'true'` only to pin your own toolchain (it provisions BellSoft Liberica NIK and
exports `GRAALVM_HOME`, which takes precedence over the auto-download when it matches the
configured distribution). `setup-gradle: 'true'`
configures Gradle, and `setup-node: 'true'` installs Node.js for the electron-builder packaging
tasks. See [CI/CD](/docs/packaging/ci-cd) for the full release workflow, including publishing to
GitHub Releases.

### Cache the Gradle build

`setup-gradle: 'true'` runs `gradle/actions/setup-gradle`, which caches Gradle's
dependency and build outputs. That already covers the Oracle reachability metadata
repository — it is resolved as a normal dependency — and the outputs of the metadata
tasks. GraalVM native-image compilation is the long step (roughly 5–15 minutes per
platform) and runs from scratch on each build; it is not incrementally cached.

## Debug missing reflection at runtime

Run the native binary from a terminal. Reflection failures produce clear messages such
as `ClassNotFoundException` or `NoSuchFieldException`. To capture the missing entries:

1. Run `./gradlew runWithNativeAgent` and exercise the failing code path so the agent
   records the entry.
2. The agent merges its output into your metadata without overwriting manually enriched
   entries, so only genuinely new entries are added.
3. Rebuild with `./gradlew packageGraalvmNative`.

`packageGraalvmDeb` fails unless `homepage` is set in `nativeDistributions` — electron-builder
requires it for DEB packaging. See [Configuration](/docs/start/configuration).

## What's next

- [GraalVM configuration](/docs/performance/graalvm/configuration) — the `graalvm { }` DSL and its properties.
- [Automatic metadata](/docs/performance/graalvm/automatic-metadata) — how reflection metadata is resolved for you.
- [CI/CD](/docs/packaging/ci-cd) — the full release workflow with signing and publishing.
- [Configuration](/docs/start/configuration) — `nativeDistributions` and the `homepage` property.

---

# AOT cache

URL: https://nucleusframework.dev/en/docs/performance/aot-cache

Generate a Project Leyden AOT cache at build time and bundle it with your installer to skip JVM warmup at launch.

Nucleus can generate a [Project Leyden](https://openjdk.org/projects/leyden/) AOT cache while it builds your app and bundle that cache into every installer. At launch the JVM replays pre-recorded class loading and JIT profiles instead of warming up from scratch, so the app reaches a responsive UI sooner. HotSpot C2 stays the JIT — the cache removes the warmup, not the compiler.

This page covers enabling the cache, writing a training run, and the platform constraints that apply.

## Add the dependency

`nucleus.aot-runtime` is pulled in transitively by [`nucleus.nucleus-application`](/docs/start/project-setup). Add it explicitly only if you don't use the umbrella artifact:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.aot-runtime:<version>")
}
```

## Enable the cache

Set one flag in the `nativeDistributions` block:

```kotlin title="build.gradle.kts"
nucleus.application {
    mainClass = "com.example.MainKt"
    nativeDistributions {
        enableAotCache = true
    }
}
```

AOT cache generation requires JDK 25 or later. Older toolchains fail the build.

That is the entire build-side setup. When the flag is on, the plugin:

1. Runs your app in training mode after `createDistributable`.
2. Records class loading and JIT compilation into `app.aot` with `-XX:AOTCacheOutput`.
3. Injects `-XX:AOTCache=$APPDIR/app.aot` into the launcher configuration.
4. Bundles the cache with every installer (`.dmg`, `.msi`, `.deb`, and so on).

## Write a training run

During training the JVM watches a real run of your app and writes the cache when the process exits. Your code must exit cleanly, or the build waits until the 300 s safety timeout force-kills it. With `nucleusApplication { … }`, arm the self-exit timer in one line:

```kotlin
import dev.nucleusframework.application.aotTraining
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.application.DecoratedWindow
import kotlin.time.Duration.Companion.seconds

fun main(args: Array<String>) = nucleusApplication(args) {
    // No-op outside training. Calls exitApplication() after 45 seconds.
    aotTraining(duration = 45.seconds)

    if (isAotTraining) {
        // The more real screens the training run touches, the more methods
        // get profiled. Walk the navigation graph and preload assets.
        preloadNavigationScreens()
        preloadFontsAndImages()
    }

    DecoratedWindow(onCloseRequest = ::exitApplication, title = "MyApp") {
        App()
    }
}
```

If you call Compose's `application { … }` directly, read the mode and drive the timer yourself:

```kotlin
import androidx.compose.ui.window.application
import dev.nucleusframework.aot.runtime.AotRuntime
import dev.nucleusframework.aot.runtime.AotRuntimeMode

fun main() {
    if (AotRuntime.mode() == AotRuntimeMode.TRAINING) {
        Thread({ Thread.sleep(45_000); System.exit(0) }, "aot-timer").start()
        preloadNavigationScreens()
        preloadFontsAndImages()
    }
    application { /* ... */ }
}
```

## How it works

The plugin sets the `nucleus.aot.mode` system property to `training` during cache generation and to `runtime` when the cache is loaded. `AotRuntime.mode()` reads that property and returns `AotRuntimeMode.TRAINING`, `AotRuntimeMode.RUNTIME`, or `AotRuntimeMode.OFF` when the property is unset.

A training run must:

- Exit with code 0. The `aotTraining` DSL handles this by calling `exitApplication()` once the timer fires.
- Finish before the 300 s safety timeout.
- Be representative of a real session. The more real screens it touches, the more methods get profiled, and the faster the post-cache cold start.

On headless Linux the plugin starts Xvfb automatically when `DISPLAY` is unset.

## Pin the platform and JDK

The AOT cache is platform- and JDK-specific. A cache built on macOS ARM64 with JBR 25 does not work on Linux x64 or with a different JDK build.

- Build on each target platform. A CI matrix is the cleanest setup.
- The plugin trains with the bundled JDK from `createDistributable`, so the runtime JDK matches the training JDK byte-for-byte.
- `setup-nucleus` pins the same JBR version across OS runners. See [CI/CD](/docs/packaging/ci-cd).

## API reference

### Gradle DSL

| Property | Default | Notes |
|----------|---------|-------|
| `nativeDistributions.enableAotCache` | `false` | Single switch. Triggers training and bundling. |

### AotRuntime

`dev.nucleusframework.aot.runtime.AotRuntime` resolves the mode from the `nucleus.aot.mode` system property.

| API | Returns |
|-----|---------|
| `AotRuntime.mode()` | `AotRuntimeMode.OFF`, `TRAINING`, or `RUNTIME` |
| `AotRuntime.isTraining()` | `true` during a training pass |
| `AotRuntime.isRuntime()` | `true` when the cache is loaded |

### nucleusApplication scope

Available inside a `nucleusApplication { … }` block.

| Member | Equivalent |
|--------|------------|
| `aotMode` | `AotRuntime.mode()` |
| `isAotTraining` | `aotMode == AotRuntimeMode.TRAINING` |
| `isAotRuntime` | `aotMode == AotRuntimeMode.RUNTIME` |
| `aotTraining(duration, onTimeout)` | Self-exit timer for training runs (default `duration` 15 s, `onTimeout` calls `exitApplication()`) |

### Measuring cold start

Measure from the OS-level process spawn (`time ./MyApp` on Linux and macOS, `Measure-Command` on Windows) to the first visible frame. Compare a build with `enableAotCache = false` against one with it on, using the same JDK and a representative training run.

## Notes

- The cache is per binary — every release ships a fresh one. Don't share caches across versions.
- If you need a smaller resident set or a shorter cold start, use the [GraalVM native image path](/docs/performance/graalvm) instead. The AOT cache keeps HotSpot's throughput; GraalVM trades some throughput for startup time and size.

## What's next

- [Project setup](/docs/start/project-setup) — the umbrella artifact and module layout.
- [GraalVM native image](/docs/performance/graalvm) — the alternative path for the smallest, fastest cold start.
- [CI/CD](/docs/packaging/ci-cd) — build a per-platform cache in a CI matrix.

---

# Native access — reflection metadata, resolved for you

URL: https://nucleusframework.dev/en/docs/performance/native-access

Nucleus generates the reflection, resource, and JNI metadata a GraalVM Native Image build needs, merging it from several sources so the build compiles without hand-written JSON.

GraalVM Native Image uses a closed-world model: every reflective `Class.forName`, every
`getResource` pattern, and every JNI call has to be declared in JSON at build time. Nucleus
generates that metadata for you. It collects entries from five sources and hands them to
`native-image`, so `./gradlew packageGraalvmNative` produces a working binary without a
hand-written `reachability-metadata.json`.

## Add the dependency

The build tasks come from the Nucleus Gradle plugin. Add the runtime baseline so its bundled
metadata, resource patterns, and AWT substitutions are on the classpath:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.graalvm-runtime:<version>")
}
```

## Build a native image

```shell
./gradlew packageGraalvmNative
```

The task assembles metadata from every source below, passes each directory to `native-image`
via `-H:ConfigurationFileDirectories=`, and packages the resulting binary for the current OS.

## How the metadata is assembled

Nucleus draws reachability metadata from five sources and merges them at build time:

| Source | What it covers | How it gets in |
|--------|----------------|----------------|
| **L1 — Per-library metadata** | 29 curated files: Compose UI, Skiko, ktor, kotlinx.serialization, SQLite, androidx-sqlite-bundled, Coil, JNA, FileKit, SLF4J, the JDK/AWT baseline, and more | Shipped in the plugin JAR. Files that declare `matchPackages` are included only when that library is on the runtime classpath. |
| **L2 — Oracle Reachability Metadata Repository** | SLF4J, Logback, and hundreds of other community libraries | Resolved from the [official repository](https://github.com/oracle/graalvm-reachability-metadata) for each runtime dependency. |
| **L3 — Platform metadata** | `sun.awt.windows.*`, `sun.lwawt.macosx.*`, `sun.awt.X11.*`, Java2D pipelines, font managers, and security providers | Written to the build directory at compile time for the current target OS. |
| **L4 — Static bytecode analysis** | `Class.forName`, `MethodHandles.Lookup.findClass`, `getResource[AsStream]`, JNI native methods with their field and parameter chains, `ServiceLoader` calls, and `@Serializable` types | The `analyzeGraalvmStaticMetadata` task scans every compiled class on the runtime classpath. |
| **L5 — Runtime baseline** | Resource-include patterns, AWT font-path substitutions, and serialization entries | Shipped inside `nucleus.graalvm-runtime`. Auto-detected from the JAR's `META-INF/native-image` directory. |

L1 through L4 and your own manual config are each passed as a `-H:ConfigurationFileDirectories=`
entry. The `nucleus.graalvm-runtime` baseline (L5) is picked up through GraalVM's standard
classpath detection. `native-image` merges all of them.

## Included resources

The `graalvm-runtime` JAR registers seven resource globs in the `resources` section of its
`reachability-metadata.json`:

| Glob | Covers |
|---------|--------|
| `**/*.svg`, `**/*.ttf`, `**/*.otf` | SVG icons and fonts on the classpath — Jewel, IntelliJ Platform icons, Compose resources, and your own |
| `composeResources/**` | Compose Multiplatform resources loaded through `Res.*` |
| `nucleus/**` | Nucleus JNI shared libraries and bundled runtime resources |
| `META-INF/services/**` | `ServiceLoader` descriptors (ktor engines, Coil fetchers, SLF4J providers, …) |
| `META-INF/services/javax.sound.sampled.spi.MixerProvider` | The audio mixer provider descriptor |

These patterns are broad on purpose. If you pull in the IntelliJ Platform icons library and
binary size matters, override the icon glob with a tighter `resource-config.json` of your own.

## Font substitutions

The `graalvm-runtime` JAR ships `@TargetClass` substitutions that fix AWT font handling under
native image:

- `FontCreateFontSubstitution` — buffers `Font.createFont(int, InputStream)` to a temp file
  before delegating, avoiding `IOException: Problem reading font data` on Windows and Linux.
- `Win32FontManagerSubstitution` — replaces the native `sun.awt.Win32FontManager.getFontPath`
  with a pure-Java version, avoiding `InternalError: platform encoding not initialized`.
- `FcFontManagerSubstitution` — the same fix for `sun.awt.FcFontManager.getFontPath` on Linux.

The `native-image` compiler picks these up automatically; no configuration is needed.

## Collect missing metadata with the tracing agent

Static analysis cannot see reflection driven by runtime values or classes loaded dynamically.
For those cases, run the app once under the GraalVM native-image agent:

```shell
./gradlew runWithNativeAgent
```

Exercise every screen and feature. The agent records reflection, JNI, resource, and proxy
accesses to a temp directory, then merges the new entries into your config without overwriting
manually enriched ones.

## Remove redundant manual metadata

If you have accumulated manual entries that the automatic sources now cover, prune them:

```shell
./gradlew cleanupGraalvmMetadata
```

The task compares your `reachability-metadata.json` against L1, L2, L3, and the static analysis
output, removes every entry already managed by Nucleus, and reports what it removed.

## When automatic metadata isn't enough

Some libraries make GraalVM impractical regardless of metadata:

- Heavy JNA users (dynamic function-call proxies)
- Full-text search engines (Lucene, the Elasticsearch client)
- Embedded scripting runtimes (Groovy, JRuby, Nashorn)
- Runtime annotation processing (Spring)
- OSGi and custom classloaders
- Runtime bytecode generation (ByteBuddy, cglib, ASM-based mocking)

If you depend on any of these, ship the [AOT cache build](/docs/performance/aot-cache) instead.

## Write native code in Kotlin

To call a platform API that no Nucleus runtime module covers (CoreGraphics, IOKit, Win32,
GTK4, …), write that side in Kotlin/Native and let [NucleusNativeAccess](/docs/performance/native-code)
generate the FFM bridge, the JVM proxies, and the GraalVM metadata for you. The
`reflect-config.json`, `resource-config.json`, and `reachability-metadata.json` it emits for the
generated proxies are picked up by the pipeline above transparently.

## What's next

- [Native code in Kotlin](/docs/performance/native-code) — call Kotlin/Native from the JVM through a generated FFM bridge.
- [Native library loader](/docs/performance/native-library-loader) — how JNI shared libraries under `nucleus/native/` are loaded at runtime.
- [Automatic metadata](/docs/performance/graalvm/automatic-metadata) — the full task graph behind these sources.
- [GraalVM tasks and CI](/docs/performance/graalvm/tasks-ci) — the Gradle task reference for native builds.
- [AOT cache](/docs/performance/aot-cache) — the fallback when a dependency rules out native image.

---

# Native code in Kotlin

URL: https://nucleusframework.dev/en/docs/performance/native-code

Write the native side in Kotlin/Native and call it from the JVM as a plain Kotlin API. NucleusNativeAccess generates the FFM bridge, the JVM proxies, and the GraalVM metadata for you.

When a platform API has no Nucleus runtime module (CoreGraphics, IOKit, Win32, GTK4, a C library on the system), you write that side in Kotlin/Native and call it from the JVM as if it were a normal Kotlin dependency. NucleusNativeAccess parses your `nativeMain` API, generates the C bridge and the JVM proxy classes over the Foreign Function & Memory API (FFM), and bundles the compiled shared libraries into your JAR — no hand-written JNI, no C boilerplate.

Native access ships from [`NucleusFramework/NucleusNativeAccess`](https://github.com/NucleusFramework/NucleusNativeAccess) with its own release cycle, like the [system tray](/docs/os/system-tray), the [PDF reader](/docs/pdf), and the [WebView](/docs/webview). It is a Gradle plugin, `dev.nucleusframework.nna`, versioned independently from Nucleus and licensed MIT.

## Add the plugin

```kotlin title="build.gradle.kts"
plugins {
    kotlin("multiplatform") version "2.3.20"
    id("dev.nucleusframework.nna") version "<version>"
}

kotlin {
    jvmToolchain(25) // FFM is stable since JDK 22; 25 is recommended
    jvm()
    linuxX64()
    // macosArm64()
    // mingwX64()
}

kotlinNativeExport {
    nativeLibName = "mylib" // produces libmylib.so / .dylib / .dll
    buildType = "release"   // "release" (default) or "debug"
}
```

The plugin targets `linuxX64()`, `macosArm64()`, and `mingwX64()`. The JVM side needs JDK 22+ (FFM was finalized in JEP 454) and `--enable-native-access=ALL-UNNAMED` at runtime, which is wired in automatically for tests.

## Write once, call across the boundary

Write the native class in `nativeMain`. Only the public API is exported:

```kotlin title="src/nativeMain/kotlin/com/example/Calculator.kt"
package com.example

class Calculator(initial: Int = 0) {
    private var acc = initial

    fun add(value: Int): Int { acc += value; return acc }
    fun subtract(value: Int): Int { acc -= value; return acc }
    val current: Int get() = acc
    fun describe(): String = "Calculator(current=$acc)"
}
```

Call it from `jvmMain` as a plain Kotlin object. The proxy is `AutoCloseable`; closing it releases the native object:

```kotlin title="src/jvmMain/kotlin/com/example/Main.kt"
package com.example

fun main() {
    Calculator(0).use { calc -> // allocates the native object
        calc.add(5)             // FFM downcall into native
        calc.add(3)
        println(calc.current)   // 8
        println(calc.describe()) // "Calculator(current=8)"
    }                           // releases the native object
}
```

## How it works

The plugin runs a build-time pipeline over your native sources:

1. Parses the `nativeMain` public API with Kotlin PSI.
2. Generates `@CName` bridge functions on the native side, tracking object lifetime with `StableRef`.
3. Generates JVM proxy classes that call across the boundary through FFM `MethodHandle` downcalls.
4. Compiles to a shared library (`.so` / `.dylib` / `.dll`) and bundles it under `kne/native/{os}-{arch}/` in the JAR.
5. Emits GraalVM reachability metadata for the generated proxies.

At runtime the JVM loads the library through a three-tier strategy — `java.library.path` first, then extraction from the JAR to `~/.cache/kne/`, then the GraalVM native-image loader lookup. Native objects are released when you close the proxy, and any leaked handle is cleaned up through a `Cleaner`.

## What crosses the boundary

The bridge handles far more than primitives:

| Category | Support |
| -------- | ------- |
| Primitives | `Int`, `Long`, `Double`, `Float`, `Boolean`, `Byte`, `Short` — direct, zero conversion |
| `String` | UTF-8, null-terminated buffers both ways |
| Collections | `List`, `Set`, `Map` (pointer + count encoding), nullable via a `-1`/sentinel count |
| Data classes & enums | Field decomposition by value; enums map by ordinal |
| Nullability | Sentinel-based (e.g. `Long.MIN_VALUE` for a null `Long?`) |
| Objects | Opaque handles via `StableRef`, GC-cleaned through `Cleaner` |
| `suspend fun` | Mapped to JVM `suspend fun`, bidirectional cancellation |
| `Flow<T>` | `channelFlow` over `onNext`/`onError`/`onComplete` callbacks, auto-cancel on collection stop |
| Callbacks / lambdas | `(T) -> R` cross via FFM upcall stubs |
| Exceptions | Propagated as `KotlinNativeException` on the JVM |

Classes, inheritance, interfaces, sealed classes, companion objects, constructors with default parameters, and extension functions all carry over. Not supported: generics, interface or sealed *return* types (return concrete types), operator overloading, infix functions, `ByteArray` inside collections, and subclassing a native type from the JVM.

## Wrap a C library

Because the native side is Kotlin/Native, you can pull in a C library with `cinterop` and expose it to the JVM through the same generated bridge — this is how you reach CoreGraphics, Win32, GTK4, or any system library from JVM code:

```kotlin title="build.gradle.kts"
kotlin {
    linuxX64().compilations["main"].cinterops {
        val libnotify by creating {
            defFile(project.file("src/nativeInterop/cinterop/libnotify.def"))
        }
    }
}
```

Write a thin Kotlin/Native wrapper over the C bindings in `nativeMain`, and the plugin exports it to the JVM like any other native class.

## GraalVM

The plugin writes reachability metadata under `META-INF/native-image/kne/{libName}/`:

- `reflect-config.json` — the generated proxy classes and their constructors.
- `resource-config.json` — the bundled native libraries under `kne/native/…`.
- `reachability-metadata.json` — FFM downcall and upcall descriptors, plus reflection and resources.

The Nucleus GraalVM pipeline picks these up as one more metadata source (see [native access](/docs/performance/native-access)), so `./gradlew packageGraalvmNative` links the shared library and its descriptors without any hand-written JSON.

## What's next

- [Native access](/docs/performance/native-access) — how Nucleus assembles reachability metadata, including the descriptors this plugin emits.
- [Native library loader](/docs/performance/native-library-loader) — how Nucleus modules load their own JNI libraries (separate from this plugin's `kne/` cache).
- [System tray](/docs/os/system-tray) — another Nucleus component shipped from its own repository.
- [PDF reader](/docs/pdf) — one PDF API across Android, iOS, web, and desktop.
- [WebView](/docs/webview) — one WebView API across Android, iOS, web, and desktop.

---

# Native library loader

URL: https://nucleusframework.dev/en/docs/performance/native-library-loader

How Nucleus loads JNI shared libraries from the module JARs — system path first, then a content-addressed cache under the OS cache directory.

Most Nucleus runtime modules ship a small JNI shared library next to their Kotlin code
(dark mode, system color, notifications, taskbar progress, auto-launch, and more).
`NativeLibraryLoader` is the single loader those modules use. It lives in `core-runtime`
and is pulled in by `nucleus-application`.

You rarely call it yourself. Document it here if you are writing a custom JNI bridge that
should behave like the rest of Nucleus, or if you need to debug a library that failed to
load or clear a stuck cache.

## Where it comes from

```kotlin title="build.gradle.kts"
dependencies {
    // Via the umbrella:
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")

    // Or directly:
    implementation("dev.nucleusframework:nucleus.core-runtime:<version>")
}
```

```kotlin
import dev.nucleusframework.core.runtime.NativeLibraryLoader
```

## Load a library

```kotlin
private const val LIBRARY_NAME = "nucleus_systemcolor"

private val loaded = NativeLibraryLoader.load(
    LIBRARY_NAME,
    NativeWindowsSystemColorBridge::class.java,
)

val isAvailable: Boolean get() = loaded
```

`load` returns `true` when the library is on the process, `false` when it is missing for
this platform or extraction failed. It never throws for a missing platform binary: modules
treat that as "not available" and fall back or no-op.

| Parameter | Default | Role |
|-----------|---------|------|
| `libraryName` | (required) | Base name without `lib` / extension, e.g. `"nucleus_systemcolor"` |
| `callerClass` | (required) | A class from the same JAR as the native resource, used to locate it |
| `resourcePrefix` | `"/nucleus/native"` | Root path inside the JAR |
| `sidecarFiles` | `emptyList()` | Extra files extracted next to the main library before it is loaded |

A second call with the same `libraryName` is a no-op and returns `true` if the first call
succeeded.

## How loading works

Two steps, in order:

1. **System path** — `System.loadLibrary(libraryName)`. This is the path for a packaged app
   whose installer put the `.so` / `.dylib` / `.dll` on `java.library.path`.
2. **JAR extraction** — if step 1 fails, the loader looks up
   `{resourcePrefix}/{os}-{arch}/{mappedFileName}` on the caller's JAR, extracts it into a
   persistent cache, and calls `System.load` on the absolute path.

### JAR layout

Platform folder and file name are derived from the OS and architecture:

| OS | Arch | Resource directory | File for `foo` |
|----|------|--------------------|----------------|
| macOS | x64 / aarch64 | `darwin-x64` / `darwin-aarch64` | `libfoo.dylib` |
| Linux | x64 / aarch64 | `linux-x64` / `linux-aarch64` | `libfoo.so` |
| Windows | x64 / aarch64 | `win32-x64` / `win32-aarch64` | `foo.dll` |

Full path inside the JAR (default prefix):

```text
/nucleus/native/darwin-aarch64/libnucleus_systemcolor.dylib
/nucleus/native/linux-x64/libnucleus_systemcolor.so
/nucleus/native/win32-x64/nucleus_systemcolor.dll
```

If the resource is absent, the loader logs at `FINE` and returns `false`. That is how a
macOS-only module stays quiet on Linux.

### Cache directory

Extracted libraries land under the OS user cache, not a temp directory that disappears every
run:

| Platform | Path |
|----------|------|
| macOS | `~/Library/Caches/nucleus/native/` |
| Linux | `$XDG_CACHE_HOME/nucleus/native/` or `~/.cache/nucleus/native/` |
| Windows | `%LOCALAPPDATA%\nucleus\native\` (fallback: `%USERPROFILE%\AppData\Local\nucleus\native\`) |

Layout under that root:

```text
<os-cache-root>/nucleus/native/<os>-<arch>/<fingerprint>/<library file>
```

### Content-addressed fingerprints

The fingerprint is built from the JAR entry's CRC-32 and size (read from ZIP headers, no
stream I/O). For `file:` URLs in IDE runs, size and last-modified are used instead. Sidecar
files contribute to the same fingerprint string, so the main library and its helpers share
one directory and one cache key.

Because different library versions produce different fingerprints, two processes using two
versions of the same artifact never share an extraction path. That avoids a race where one
process could replace a file another process was about to `System.load` (issue #304). If the
target file already exists, extraction is skipped entirely — the content is assumed correct
for that fingerprint.

Extraction writes to a temp file in the same directory, then renames it (atomic move when the
filesystem allows). Concurrent extractors that lose the rename race reuse the winner's file
or, as a last resort, load from their own temp copy.

## Sidecar files

Some native code needs helper DLLs next to the main library so the dynamic linker can resolve
them (Windows `LoadLibrary`, Linux `$ORIGIN`, macOS `@loader_path`). Pass those filenames
exactly as they appear in the JAR resource directory (platform-bare names for Windows, full
names for Unix-style libs):

```kotlin
NativeLibraryLoader.load(
    "sample_tao_webview",
    SampleWebViewWindowsBridge::class.java,
    sidecarFiles = listOf("WebView2Loader.dll"),
)
```

Sidecars are extracted into the same content-addressed directory before the main library is
loaded. Tao's GLES bridge uses the same pattern for `libGLESv2.dll` on Windows.

## GraalVM

Shared libraries under `nucleus/native/…` are covered by the `nucleus/.*` resource-include
pattern shipped in `graalvm-runtime`. See [Native access](/docs/performance/native-access).
You do not register each `.so` / `.dylib` / `.dll` by hand for a normal Nucleus module.

Under a native image, prefer shipping the library on the image's library path so
`System.loadLibrary` succeeds in step 1; the JAR extraction path still works when resources
are included.

## Debugging

| Situation | What to check |
|-----------|----------------|
| Module reports `isAvailable == false` | Is there a binary for this `os-arch` under `/nucleus/native/` in the dependency JAR? |
| Load fails after an upgrade | Clear `…/nucleus/native/` and relaunch; a corrupt partial extract is rare but possible |
| Packaged app works, IDE run fails | Confirm the module that embeds the native resource is on the runtime classpath |
| Log line `Failed to load … native library` | Enable fine logging for `NativeLibraryLoader` (JDK `java.util.logging`) |

Modules that wrap the loader usually expose `isAvailable` or a similar flag. Prefer that over
calling `NativeLibraryLoader` from application code.

## Related loaders

[Native code in Kotlin](/docs/performance/native-code) (NucleusNativeAccess) uses a similar
three-tier strategy, but a different cache root (`~/.cache/kne/…`) and resource prefix
(`kne/native/…`). The two loaders are independent.

## What's next

- [Modules](/docs/concepts/modules) — `core-runtime` and the rest of the module map.
- [Native access](/docs/performance/native-access) — GraalVM resource and JNI metadata.
- [Native code in Kotlin](/docs/performance/native-code) — write native side in Kotlin/Native
  instead of hand-written JNI.
- [Troubleshooting](/docs/reference/troubleshooting) — packaging and runtime failures.

---

# Native HTTP — the OS trust store, pre-wired

URL: https://nucleusframework.dev/en/docs/performance/native-http

Preconfigure java.net.http.HttpClient, OkHttp, or Ktor with the operating system trust store through NativeTrustManager.

The native HTTP modules preconfigure a Kotlin HTTP client with the operating system trust
store through [`NativeTrustManager`](/docs/performance/native-ssl). HTTPS connections to hosts
whose certificates come from corporate roots, MDM profiles, or SSL-inspection proxies then
succeed without extra trust configuration. Nucleus ships three adapters, one each for
`java.net.http.HttpClient`, OkHttp, and Ktor.

## Add the dependency

Choose the adapter that matches your HTTP client:

| Module | Artifact | Client |
|--------|----------|--------|
| `native-http` | `dev.nucleusframework:nucleus.native-http` | `java.net.http.HttpClient` (JDK 11+) |
| `native-http-okhttp` | `dev.nucleusframework:nucleus.native-http-okhttp` | OkHttp 4 |
| `native-http-ktor` | `dev.nucleusframework:nucleus.native-http-ktor` | Ktor client (engine-agnostic) |

Each module declares `native-ssl` as an `api` dependency, so it is pulled in transitively. You
do not add `native-ssl` yourself.

## Use the JDK HttpClient

Add `native-http`:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.native-http:<version>")
}
```

`NativeHttpClient.create()` returns a `java.net.http.HttpClient` that trusts the OS store and
follows redirects. To apply native trust to your own builder, use the `withNativeSsl()`
extension:

```kotlin
import dev.nucleusframework.nativehttp.NativeHttpClient
import dev.nucleusframework.nativehttp.NativeHttpClient.withNativeSsl
import java.net.http.HttpClient
import java.time.Duration

// Ready-to-use client — follows redirects
val client = NativeHttpClient.create()

// Or compose native trust into an existing builder
val custom = HttpClient.newBuilder()
    .withNativeSsl()
    .connectTimeout(Duration.ofSeconds(30))
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build()
```

`withNativeSsl()` is a member extension on `NativeHttpClient`. It sets the SSL context to
`NativeTrustManager.sslContext` and disables client-certificate requests. Import it as shown to
bring it into scope.

`HttpClient.Builder` does not follow redirects by default. `NativeHttpClient.create()` sets
`Redirect.NORMAL` for you, but when you call `withNativeSsl()` on your own builder, add
`.followRedirects(HttpClient.Redirect.NORMAL)` yourself — otherwise any host that returns a 302
looks like a failure.

## Use OkHttp

Add `native-http-okhttp`. It declares OkHttp 4 as an `api` dependency, so you get it
transitively:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.native-http-okhttp:<version>")
}
```

```kotlin
import dev.nucleusframework.nativehttp.okhttp.NativeOkHttpClient
import dev.nucleusframework.nativehttp.okhttp.NativeOkHttpClient.withNativeSsl
import okhttp3.OkHttpClient
import java.util.concurrent.TimeUnit

val client = NativeOkHttpClient.create()

// Or apply native trust to your own builder
val custom = OkHttpClient.Builder()
    .withNativeSsl()
    .callTimeout(30, TimeUnit.SECONDS)
    .build()
```

`NativeOkHttpClient.create()` calls `sslSocketFactory(NativeTrustManager.sslSocketFactory,
NativeTrustManager.trustManager)` on the builder.

## Use Ktor

Add `native-http-ktor` and exactly one Ktor engine. The engine artifacts are `compileOnly` in
the module, so only the engine you declare needs to be on the runtime classpath:

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.native-http-ktor:<version>")
    // Pick one engine
    implementation("io.ktor:ktor-client-cio:<ktor-version>")
    // or ktor-client-java, ktor-client-okhttp, ktor-client-apache5
}
```

```kotlin
import dev.nucleusframework.nativehttp.ktor.installNativeSsl
import io.ktor.client.HttpClient
import io.ktor.client.engine.cio.CIO

val client = HttpClient(CIO) {
    installNativeSsl()
}
```

`installNativeSsl()` is a top-level extension on `HttpClientConfig`. It inspects the active
engine configuration and applies the matching SSL surface:

| Engine | What it configures |
|--------|--------------------|
| CIO | `https { trustManager = NativeTrustManager.trustManager }` |
| Java | `config { sslContext(NativeTrustManager.sslContext) }` |
| OkHttp | `config { sslSocketFactory(NativeTrustManager.sslSocketFactory, NativeTrustManager.trustManager) }` |
| Apache5 | `sslContext = NativeTrustManager.sslContext` |

Each branch is guarded against a missing engine class, so declaring one engine does not require
the others on the classpath.

## How it works

Every module is a thin adapter over `native-ssl`. On first use, `NativeTrustManager` reads the
OS trust store (Keychain on macOS, Crypt32 stores on Windows, the standard PEM bundle paths on
Linux) and merges those anchors with the JVM defaults. The result is a single
`X509TrustManager` that accepts both the platform root program and any certificate your IT
department or user has added. See [Native SSL](/docs/performance/native-ssl) for the
per-platform details.

The adapters do not replace your HTTP client — they replace its trust manager. Connection
pooling, HTTP/2, interceptors, and timeouts remain under your control.

## API reference

| API | Description |
|-----|-------------|
| `NativeHttpClient.create(): HttpClient` | `java.net.http.HttpClient` with native trust and redirect-following |
| `HttpClient.Builder.withNativeSsl(): HttpClient.Builder` | Applies native trust to a `java.net.http` builder |
| `NativeOkHttpClient.create(): OkHttpClient` | `OkHttpClient` with native trust |
| `OkHttpClient.Builder.withNativeSsl(): OkHttpClient.Builder` | Applies native trust to an OkHttp builder |
| `HttpClientConfig<T>.installNativeSsl()` | Applies native trust to a Ktor client, per engine |

## What's next

- [Native SSL](/docs/performance/native-ssl) — how the OS trust store is read and merged.
- [Native access](/docs/performance/native-access) — GraalVM native-image support for the runtime.
- [Quickstart](/docs/start/quickstart) — build and run your first Nucleus app.

---

# Native SSL

URL: https://nucleusframework.dev/en/docs/performance/native-ssl

Read trusted certificates from the operating system store and merge them with the JVM defaults into a single trust manager.

`native-ssl` lets you build TLS trust from the operating system's certificate store instead of only the `cacerts` bundled with your JRE. It reads the trusted roots the OS knows about on macOS, Windows, and Linux, merges them with the JVM defaults, and exposes the result as a single `X509TrustManager`.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.native-ssl:<version>")
}
```

## Build a trust manager

`NativeTrustManager` is an object with three lazily initialized properties. Read whichever one your HTTP stack expects:

```kotlin
import dev.nucleusframework.nativessl.NativeTrustManager
import javax.net.ssl.SSLContext
import javax.net.ssl.SSLSocketFactory
import javax.net.ssl.X509TrustManager

val trustManager: X509TrustManager = NativeTrustManager.trustManager
val sslContext: SSLContext = NativeTrustManager.sslContext
val sslSocketFactory: SSLSocketFactory = NativeTrustManager.sslSocketFactory
```

If your client is `java.net.http`, OkHttp, or Ktor, use the [Native HTTP](/docs/performance/native-http) adapters
instead. They read these properties and wire them into the client for you.

## How it works

The first read of any `NativeTrustManager` property builds a combined `X509TrustManager` once, lazily and thread-safely, then caches it. The build collects the JVM default accepted issuers, adds the certificates reported by the OS, and loads both sets into a fresh `KeyStore` that backs the returned trust manager. If the OS reports no certificates, the JVM defaults are used unchanged.

The OS certificates include roots installed by enterprise policy, an MDM, or a TLS-inspection proxy — roots a bundled JRE's `cacerts` does not contain, which is why HTTPS handshakes to those hosts otherwise fail.

Certificate collection is platform-specific. macOS and Windows use a JNI bridge shipped inside the JAR; Linux reads certificate bundles from disk with no native library.

### macOS

The Security framework is called through `libnucleus_ssl.dylib` (bundled for `arm64` and `x86_64`), in two passes:

1. **System anchors** — `SecTrustCopyAnchorCertificates()` returns every Apple-shipped root.
2. **User and admin domains** — `SecTrustSettingsCopyCertificates()` enumerates certificates with explicit trust settings. Each candidate is evaluated with logic mirroring [JetBrains jvm-native-trusted-roots](https://github.com/JetBrains/jvm-native-trusted-roots):
   - User trust settings are checked first, then admin.
   - No trust settings means live evaluation through `SecTrustEvaluateWithError`.
   - An empty trust settings array counts as trusted, per Apple's documentation.
   - `kSecTrustSettingsResult` must be `TrustRoot`, and the certificate must be self-signed (DN equality and a signature verified against its own key).
   - `kSecTrustSettingsPolicy`, when present, must be `kSecPolicyAppleSSL`.
   - Unknown constraint keys reject the certificate, failing closed rather than relaxing the rules silently.

### Windows

Crypt32 is called through `nucleus_ssl.dll` (bundled for `x64` and `ARM64`). It scans two store types across several store locations:

| Store type | Inclusion rule |
|------------|----------------|
| `ROOT` | Trusted root CAs, included unconditionally |
| `CA` | Intermediate CAs, validated via `CertGetCertificateChain` and `CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_BASE)` with cache-only revocation |

The locations scanned are `CURRENT_USER`, `LOCAL_MACHINE`, `CURRENT_USER_GROUP_POLICY`, `LOCAL_MACHINE_GROUP_POLICY`, and `LOCAL_MACHINE_ENTERPRISE`. Certificates distributed by Group Policy and Active Directory land in stores that `SunMSCAPI` does not reach.

Inside the native bridge, deduplication is by SHA-1 thumbprint (`CERT_HASH_PROP_ID`). If the JNI library fails to load, the module falls back to `SunMSCAPI`'s `Windows-ROOT`, `Windows-CA`, and `Windows-MY` keystores.

### Linux

Pure JVM, with no shared library. It reads the same paths Go's `crypto/x509` does:

| Path | Distribution |
|------|--------------|
| `/etc/ssl/certs/ca-certificates.crt` | Debian, Ubuntu, Gentoo |
| `/etc/pki/tls/certs/ca-bundle.crt` | Fedora, RHEL 6 |
| `/etc/ssl/ca-bundle.pem` | openSUSE |
| `/etc/pki/tls/cacert.pem` | OpenELEC |
| `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` | CentOS, RHEL 7 |
| `/etc/ssl/cert.pem` | Alpine |
| `/etc/ssl/certs/` *(dir)* | SLES 10, SLES 11 |
| `/etc/pki/tls/certs/` *(dir)* | Fedora, RHEL |
| `/system/etc/security/cacerts/` *(dir)* | Android |

On Linux, certificates are deduplicated by DER content across all sources.

## API reference

`NativeTrustManager` is the only public entry point. It exposes three read-only properties and no methods.

| Property | Description |
|----------|-------------|
| `NativeTrustManager.trustManager: X509TrustManager` | Combined trust manager (JVM defaults plus OS-native roots) |
| `NativeTrustManager.sslContext: SSLContext` | `TLS` context initialized with the trust manager |
| `NativeTrustManager.sslSocketFactory: SSLSocketFactory` | Socket factory derived from `sslContext` |

Certificate collection is internal and dispatches on the current platform. There is no public plug-in point for supplying a custom certificate source.

## Notes

### ProGuard

The JNI bridge classes must be kept on macOS and Windows. The Nucleus Gradle plugin adds these rules automatically; add them yourself if you maintain ProGuard config manually:

```proguard
-keep class dev.nucleusframework.nativessl.mac.NativeSslBridge {
    native <methods>;
}
-keep class dev.nucleusframework.nativessl.windows.WindowsSslBridge {
    native <methods>;
}
```

### Logging

Debug logs are tagged `NativeCertificateProvider`, `NativeSslBridge`, `WindowsCertificateProvider`, and `LinuxCertificateProvider`. They are off by default. Turn them on with:

```kotlin
import dev.nucleusframework.core.runtime.tools.allowNucleusRuntimeLogging

allowNucleusRuntimeLogging = true
```

## What's next

- [Native HTTP](/docs/performance/native-http) — wire the native trust manager into `java.net.http`, OkHttp, and Ktor.
- [Modules](/docs/concepts/modules) — the full list of Nucleus modules and what each one provides.

---

# One DSL, eighteen installers

URL: https://nucleusframework.dev/en/docs/packaging

Declare the desktop distribution formats you need in the Gradle plugin's DSL and build each one the host operating system supports.

Nucleus declares every desktop distribution format in one `nucleus { }` Gradle block. You choose the
formats with `targetFormats(...)`, and a single task builds each one the host operating system can
produce. `TargetFormat` defines 18 formats, covering direct installers, store packages, and plain
archives.

## Declare the formats

The packaging DSL ships with the Gradle plugin, so there is no separate dependency to add:

```kotlin title="build.gradle.kts"
plugins {
    id("dev.nucleusframework") version "<version>"
}
```

List the formats you want inside `nativeDistributions`:

```kotlin title="build.gradle.kts"
nucleus {
    application {
        mainClass = "com.example.MainKt"

        nativeDistributions {
            targetFormats(
                TargetFormat.Dmg, TargetFormat.Pkg,
                TargetFormat.Exe, TargetFormat.Nsis, TargetFormat.Msi, TargetFormat.AppX,
                TargetFormat.Deb, TargetFormat.Rpm, TargetFormat.AppImage, TargetFormat.Pacman,
                TargetFormat.Snap, TargetFormat.Flatpak,
                TargetFormat.Zip,
            )
            packageName = "MyApp"
            packageVersion = "1.0.0"
        }
    }
}
```

## Build the installers

```shell
./gradlew packageDistributionForCurrentOS
```

Every format requested for the host operating system is written under `build/compose/binaries/`.

Formats the host operating system cannot produce are skipped silently. The same build script runs
unchanged on macOS, Windows, and Linux, which suits matrix CI.

## Supported formats

`TargetFormat` defines 18 constants. The table groups them by how you ship each build:

| OS | Direct distribution | Store | Archives |
|----|---------------------|-------|----------|
| macOS | DMG | PKG (Mac App Store) | ZIP, TAR, 7z |
| Windows | Exe, NSIS, MSI, Portable | AppX (Microsoft Store) | ZIP, TAR, 7z |
| Linux | DEB, RPM, AppImage, Pacman | Snap, Flatpak | ZIP, TAR, 7z |

The full set of enum constants is `RawAppImage`, `Pkg`, `Deb`, `Rpm`, `Dmg`, `Exe`, `Msi`, `Nsis`,
`NsisWeb`, `Portable`, `AppX`, `AppImage`, `Pacman`, `Snap`, `Flatpak`, `Zip`, `Tar`, and `SevenZ`.
Pass any of them to `targetFormats(...)`. The declaring type is
`dev.nucleusframework.desktop.application.dsl.TargetFormat`.

## How it works

Nucleus runs jpackage to produce a platform `app-image`, then hands that image to electron-builder's
`--prepackaged` mode to drive each installer format. The hybrid keeps jpackage's JVM runtime tuning
while using electron-builder for the formats jpackage does not support, such as NSIS, AppX, Snap,
Flatpak, and AppImage.

When you mix direct-distribution formats with store formats, Nucleus runs two pipelines: a regular
`createDistributable` for formats like DMG, NSIS, and DEB, and a `createSandboxedDistributable` for
the store formats PKG, AppX, and Flatpak. The sandboxed pipeline pre-extracts native libraries,
injects sandbox-aware JVM arguments, and applies the matching entitlements. See
[Sandboxing](/docs/packaging/sandboxing).

## Configure each platform

Per-OS settings live under `nativeDistributions.macOS { }`, `windows { }`, and `linux { }`:

- [Building for macOS](/docs/packaging/macos) — DMG, PKG, universal binaries, and layered icons.
- [Building for Windows](/docs/packaging/windows) — Exe, NSIS, MSI, AppX, and Portable.
- [Building for Linux](/docs/packaging/linux) — DEB, RPM, AppImage, Pacman, Snap, and Flatpak.

## What's next

- [Code signing](/docs/packaging/code-signing) — sign and notarize builds for each platform.
- [Publishing](/docs/packaging/publishing) — push installers to GitHub Releases, S3, or a generic host.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — the full `nucleus { }` DSL.

---

# Building for macOS

URL: https://nucleusframework.dev/en/docs/packaging/macos

Package a Nucleus app for macOS as a DMG or a Mac App Store PKG, then sign and notarize the build.

In this tutorial, you'll configure the `macOS { }` block to package a Nucleus app two ways:
a `Dmg` for direct distribution and a `Pkg` for the Mac App Store. You'll sign and notarize
the build, control the DMG layout, enable Liquid Glass on SDK 26, and build a universal binary.

## Before you start

macOS packaging runs on a macOS host and relies on Apple's command-line tooling:

- **A macOS build host** with Xcode Command Line Tools. `vtool`, `notarytool`, `productbuild`,
  and (for layered icons) `actool` come from that toolchain.
- **An Apple Developer account** with the signing certificates you need: **Developer ID Application**
  for a DMG, and the **3rd Party Mac Developer** certificates plus a provisioning profile for a PKG.
- **A Nucleus project** with the Gradle plugin applied. See the [Quickstart](/docs/start/quickstart).

## Configure the macOS block

In `build.gradle.kts`, declare the target formats and configure `macOS { }` inside
`nativeDistributions`:

```kotlin title="build.gradle.kts"
nucleus {
    application {
        nativeDistributions {
            targetFormats(TargetFormat.Dmg, TargetFormat.Pkg, TargetFormat.Zip)

            macOS {
                bundleID = "com.example.myapp"
                dockName = "MyApp"
                appCategory = "public.app-category.utilities"
                minimumSystemVersion = "12.0"

                iconFile.set(project.file("icons/app.icns"))
                layeredIconDir.set(project.file("icons/MyApp.icon")) // macOS 26+
            }
        }
    }
}
```

`bundleID` is the app's identifier across Apple's ecosystem and uses reverse-DNS notation.
`layeredIconDir` points at a `.icon` bundle and takes effect only on macOS build hosts with
`actool` from Xcode Command Line Tools 26 or later; without that tooling the build logs a
warning and falls back to `iconFile`.

## Sign and notarize the build

Add `signing { }` and `notarization { }` to the `macOS` block:

```kotlin title="build.gradle.kts"
macOS {
    signing {
        sign.set(true)
        identity.set("Developer ID Application: My Company (TEAMID)")
    }
    notarization {
        appleID.set("dev@example.com")
        password.set(System.getenv("MAC_NOTARIZATION_PASSWORD"))
        teamID.set("TEAMID")
    }
}
```

`notarization { }` supports three mutually exclusive authentication modes: Apple ID plus an
app-specific `password` and `teamID`; a `notarytool` `keychainProfile` (with an optional
`keychainPath`); or an App Store Connect API key (`apiKey`, `apiKeyId`, `apiIssuer`). Configure
exactly one — combining modes is rejected at validation.

Signing and notarization values also read from Gradle properties, so you can keep secrets out
of the build script. See [Code signing](/docs/packaging/code-signing).

## Package a DMG

```shell
./gradlew packageDmg
```

`Dmg` uses the standard `createDistributable` flow: a non-sandboxed bundle signed with the
**Developer ID Application** certificate, notarized through `xcrun notarytool`, and stapled in
place. When a `notarization { }` block is present, `packageDmg` notarizes automatically.

Control the DMG window with the `dmg { }` sub-block — window size, icon size, background image,
and the positions of the app bundle and the drag-to-`/Applications` link:

```kotlin title="build.gradle.kts"
macOS {
    dmg {
        title = "\${productName} \${version}"
        iconSize = 128
        window { x = 400; y = 100; width = 540; height = 380 }
        background.set(project.file("packaging/dmg-bg.png"))

        content(x = 130, y = 220, type = DmgContentType.File, name = "MyApp.app")
        content(x = 410, y = 220, type = DmgContentType.Link, path = "/Applications")
    }
}
```

Set `nativeDistributions.compressionLevel = CompressionLevel.Ultra` to recompress the finished
DMG with LZMA (ULMO), roughly 20% smaller than the default. It re-signs and refreshes the
auto-update checksums afterward, and requires `minimumSystemVersion >= 10.15` and an unpinned
`dmg.format`.

## Package for the Mac App Store

```shell
./gradlew packagePkg
```

`Pkg` is always built as a Mac App Store target — there is no `appStore` flag to set. Nucleus
builds a separate sandboxed `.app`, signs it with the **3rd Party Mac Developer Application**
certificate, embeds the provisioning profile, and produces the final `.pkg` through `productbuild`
with the **3rd Party Mac Developer Installer** certificate.

Point the block at your entitlements and provisioning profiles:

```kotlin title="build.gradle.kts"
macOS {
    entitlementsFile.set(project.file("packaging/sandbox-entitlements.plist"))
    runtimeEntitlementsFile.set(project.file("packaging/sandbox-runtime-entitlements.plist"))
    provisioningProfile.set(project.file("packaging/MyApp.provisionprofile"))
    runtimeProvisioningProfile.set(project.file("packaging/MyApp_Runtime.provisionprofile"))
}
```

Under the hood, PKG triggers the sandboxed pipeline: native libraries are extracted into
`Contents/Frameworks/`, JVM arguments redirect JNI loading there, each `.dylib` is signed
individually, and App Sandbox entitlements are applied. See [Sandboxing](/docs/packaging/sandboxing).

## Enable Liquid Glass on SDK 26

macOS 26 enables Liquid Glass only when the launcher's `LC_BUILD_VERSION` reports SDK 26.0.
The plugin patches that Mach-O header with `vtool` before signing, so any JDK works — you don't
need one compiled with Xcode 26. The `nucleusPatchMacJvm` task caches a patched JVM under
`build/nucleus/patched-jvm/`, so the `run` task keeps full debugger support.

Patching is on by default. Change the target SDK or disable it with `macOsSdkVersion`:

```kotlin title="build.gradle.kts"
macOS {
    macOsSdkVersion = "26.0" // default; set to null to disable patching
}
```

GraalVM native-image builds take the SDK version from the system linker rather than from
`vtool`. Select Xcode 26 on the build host instead.

## Build a universal binary

A universal binary is built in two passes: compile `arm64` and `x86_64` separately, merge them
with `lipo`, then re-sign inside-out (dylibs, then executables, then the runtime, then the app
bundle). The `build-macos-universal` composite action runs this in CI. See [CI/CD](/docs/packaging/ci-cd).

## Customize Info.plist and launch agents

Append raw XML to `Info.plist` with `infoPlist { }`, and declare login-time launch agents with
`launchAgents { }`:

```kotlin title="build.gradle.kts"
macOS {
    infoPlist {
        extraKeysRawXml = """
            <key>NSMicrophoneUsageDescription</key>
            <string>Required for voice notes.</string>
        """.trimIndent()
    }
    launchAgents {
        agent("com.example.myapp.indexer") {
            bundleProgram("Contents/MacOS/indexer")
            arguments("--background")
            startInterval(3600)
        }
    }
}
```

Launch agents are embedded at `Contents/Library/LaunchAgents/` and registered at runtime with
`SMAppService`. `bundleProgram`, `arguments`, `startInterval`, `runAtLoad`, `keepAlive`,
`processType`, and `calendar` are functions on the agent block, not assignable properties.

## Reference

The `macOS { }` block exposes: `iconFile`, `layeredIconDir`, `bundleID`, `dockName`,
`setDockNameSameAsPackageName`, `appCategory`, `minimumSystemVersion`, `installationPath`,
`packageName`, `packageVersion`, `packageBuildVersion`, `dmgPackageVersion`, `pkgPackageVersion`,
`entitlementsFile`, `runtimeEntitlementsFile`, `provisioningProfile`, `runtimeProvisioningProfile`,
and `macOsSdkVersion`, plus the sub-blocks `signing { }`, `notarization { }`, `dmg { }`,
`launchAgents { }`, and `infoPlist { }`. See the full per-property list in the
[Gradle DSL reference](/docs/reference/gradle-dsl).

`installationPath` has no default. It applies only to PKG and to the target of the DMG
drag-to-`/Applications` link.

## What's next

- [Code signing](/docs/packaging/code-signing) — signing and notarization credentials in detail.
- [Sandboxing](/docs/packaging/sandboxing) — the Mac App Store pipeline behind PKG builds.
- [CI/CD](/docs/packaging/ci-cd) — universal binaries and signing on GitHub Actions.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — every `macOS { }` property.

---

# Building for Windows

URL: https://nucleusframework.dev/en/docs/packaging/windows

Package a Nucleus app for Windows as an NSIS, MSI, MSIX/AppX, or Portable build and sign it for distribution.

In this tutorial, you'll package a Nucleus app for Windows in one or more of six formats —
NSIS, NSIS Web, MSI, MSIX/AppX, and Portable — and sign the result for distribution.

## Before you start

Windows packaging is part of the Nucleus Gradle plugin, so no extra dependency is required.
You do need:

- The Nucleus plugin applied to your build. It provides the `windows { }` block used below.
- **Windows Developer Mode** enabled to build an AppX package locally
  (Settings → System → For developers). GitHub-hosted Windows runners already have it on.
- A `.pfx`/`.p12` certificate or Azure Artifact Signing credentials to sign a build.

## Configure the Windows build

Add the formats you want to `targetFormats(...)`, then configure the `windows { }` block:

```kotlin title="build.gradle.kts"
nucleus {
    application {
        nativeDistributions {
            targetFormats(
                TargetFormat.Nsis,
                TargetFormat.Msi,
                TargetFormat.AppX,
                TargetFormat.Portable,
            )

            windows {
                iconFile.set(project.file("icons/app.ico"))
                upgradeUuid = "d24e3b8d-3e9b-4cc7-a5d8-5e2d1f0c9f1b"
                perUserInstall = true
                menuGroup = "My Company"

                signing {
                    enabled = true
                    certificateFile.set(file("certs/certificate.pfx"))
                    certificatePassword = System.getenv("WIN_CSC_KEY_PASSWORD")
                    algorithm = SigningAlgorithm.Sha256
                    timestampServer = "http://timestamp.digicert.com"
                }
            }
        }
    }
}
```

The six Windows formats are:

- `TargetFormat.Nsis` — the standard Windows installer.
- `TargetFormat.NsisWeb` — an NSIS downloader stub that fetches the payload at install time.
- `TargetFormat.Msi` — a Windows Installer package for enterprise deployment.
- `TargetFormat.AppX` — an MSIX/AppX package for the Microsoft Store and sideloading.
- `TargetFormat.Portable` — a single executable that runs without installation.
- `TargetFormat.Exe` — a bare electron-builder `.exe` target.

## Customize the NSIS installer

Nucleus exposes the electron-builder NSIS options: one-click or assisted installs, per-user or
per-machine placement, a language picker, custom header and sidebar bitmaps, a license dialog,
and a `script` / `includeScript` escape hatch for custom NSIS sources.

```kotlin
windows {
    nsis {
        oneClick = false
        allowElevation = true
        perMachine = true
        allowToChangeInstallationDirectory = true
        createDesktopShortcut = true
        runAfterFinish = true

        // Start-menu folder, from 2.5.11; windows.menuGroup is the default
        menuCategory = "My Company"
        shortcutName = "My App"

        multiLanguageInstaller = true
        installerLanguages = listOf("en_US", "fr_FR", "de_DE", "ja_JP")

        installerHeader.set(project.file("packaging/header.bmp"))
        installerSidebar.set(project.file("packaging/sidebar.bmp"))
        license.set(project.file("LICENSE"))
    }
}
```

From 2.5.11, `menuCategory` and `shortcutName` are available on the NSIS targets as well
(`nsis` and `nsis-web`). Both default to `null` — the shortcut lands in the start menu root
and carries the application name — and `windows.menuGroup` is the default `menuCategory`, so
the group you already declare for jpackage-era packaging keeps working.

## Build an MSI for enterprise deployment

The MSI target is enabled by `TargetFormat.Msi`. Set `upgradeUuid` to a fixed value so Windows
matches successor versions during an upgrade. Without a stable UUID, every new build is treated
as a separate product.

Install scope uses the same shape as NSIS — `windows.msi { perMachine }` maps 1:1 to
electron-builder's `msi.perMachine`. MSI installs **per-machine** by default
(`perMachine = true`). Prefer this over the deprecated inverted `windows.perUserInstall`
flag; when `msi.perMachine` is unset, `perUserInstall` still applies for compatibility:

```kotlin title="build.gradle.kts"
windows {
    upgradeUuid = "d24e3b8d-3e9b-4cc7-a5d8-5e2d1f0c9f1b"
    menuGroup = "My Company" // MSI start-menu folder from 2.5.10
    msi {
        perMachine = false // per-user MSI (Program Files → user-local)
        oneClick = false   // assisted wizard (jpackage-style)
        runAfterFinish = false
        createDesktopShortcut = true
        createStartMenuShortcut = true
        // menuCategory = "My Company" // optional; windows.menuGroup is the default
        // shortcutName = "My App"
    }
}
```

From 2.5.10 the remaining installer options reach electron-builder. Defaults match
electron-builder (`oneClick`, `runAfterFinish`, and both shortcut flags are `true`). Set
`oneClick = false` for the assisted wizard jpackage used to produce. `windows.menuGroup` is
the default `menuCategory`, so a start-menu folder you already declare for NSIS applies to
MSI as well. `windows.menu` / `windows.shortcut` are not mapped: their jpackage defaults
(`false`) are the opposite of electron-builder's (`true`).

## Build an AppX or MSIX package

AppX targets produce an `.appx` (or a `.msixbundle` via CI). The Desktop Bridge runs with
`runFullTrust`, so the app is not sandboxed in the Windows sense, but the format is accepted by
the Microsoft Store and supports clean install and uninstall.

```kotlin
windows {
    appx {
        // Sideload identity — any CN that matches your signing certificate
        identityName = "MyCompany.MyApp"
        publisher = "CN=D541E802-6D30-446A-864E-2E8ABD2DAA5E"
        publisherDisplayName = "My Company"
        applicationId = "MyApp"

        languages = listOf("en-US", "fr-FR")
        backgroundColor = "#001F3F"
        storeLogo.set(project.file("packaging/appx/StoreLogo.png"))
        square44x44Logo.set(project.file("packaging/appx/Square44x44Logo.png"))
        square150x150Logo.set(project.file("packaging/appx/Square150x150Logo.png"))
        wide310x150Logo.set(project.file("packaging/appx/Wide310x150Logo.png"))

        // Store requires MinVersion > 10.0.17134.0
        minVersion = "10.0.17763.0"
        maxVersionTested = "10.0.22621.0"
    }
}
```

Local AppX builds need Windows Developer Mode enabled (Settings → System → For developers).
GitHub-hosted Windows runners already have it on.

For Microsoft Store submissions, `identityName`, `publisher`, and `publisherDisplayName` must
match the values Partner Center assigned to your reservation; the Store rejects mismatches at
upload time. `publisher` is the `CN=<GUID>` issued by Partner Center, not your local signing
certificate's CN.

## Enable Portable mode

`TargetFormat.Portable` produces a single executable that unpacks to a temporary directory at
launch. No installer UI, no admin rights, no registry entries — useful for thumb-drive
distribution.

Portable packages are self-extracting archives: higher `compressionLevel` values shrink the
download but slow first launch while the payload unpacks. From 2.3.1, override only the
portable format when the root level is set high for DEB/DMG:

```kotlin title="build.gradle.kts"
nativeDistributions {
    compressionLevel = CompressionLevel.Ultra
    windows {
        portable {
            compressionLevel = CompressionLevel.Normal
        }
    }
}
```

## Add file associations and deep links

Declare associations and URL protocols on `nativeDistributions`; they propagate into every
Windows format:

```kotlin
nativeDistributions {
    protocol("MyApp", "myapp")  // myapp://… deep links
    fileAssociation(
        mimeType = "application/x-myapp",
        extension = "myapp",
        description = "MyApp Document",
    )
}
```

For a Windows-specific file icon, call `windows.fileAssociation(...)` instead.

## Reference

The `windows { }` block exposes `iconFile`, `packageName`, `console`, `dirChooser`,
`perUserInstall` (deprecated), `shortcut`, `menu`, `menuGroup`, `upgradeUuid`,
`msiPackageVersion`, and `exePackageVersion`, plus the sub-blocks `nsis { }`, `msi { }`,
`appx { }`, `portable { }`, and `signing { }`. See the
[Gradle DSL reference](/docs/reference/gradle-dsl) for every property.

## Notes

- The MSI installer is built by electron-builder's WiX wrapper. For enterprise MSI
  customization beyond installation paths (custom dialogs, registry tweaks), use NSIS instead.
- `latest.yml` (Windows update metadata) is generated for NSIS, MSI, and Portable. AppX is
  store-managed and has no auto-update YML.
- `WindowsJumpListManager.setProcessAppId()` is called automatically on Windows during startup,
  so taskbar grouping and AUMID-aware notifications work without extra configuration.

## What's next

- [Code signing](/docs/packaging/code-signing) — PFX and Azure Artifact Signing for Windows builds.
- [Publishing](/docs/packaging/publishing) — push releases to GitHub, S3, or a generic server.
- [CI/CD](/docs/packaging/ci-cd) — build and sign Windows packages on GitHub Actions.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — the full `nucleus { }` configuration surface.

---

# Building for Linux

URL: https://nucleusframework.dev/en/docs/packaging/linux

Configure a Nucleus app to build DEB, RPM, AppImage, and pacman packages and publish to the Snap and Flatpak stores.

In this tutorial, you'll configure a Nucleus app to produce every Linux package
format — DEB, RPM, AppImage, and pacman for direct distribution, plus Snap and
Flatpak for the stores — from a single `linux { }` block, then build and inspect
the output.

## Before you start

- The Nucleus Gradle plugin is applied to your project. See [Project setup](/docs/start/project-setup).
- You are on a **Linux build host**. DEB, RPM, AppImage, pacman, Snap, and Flatpak
  are Linux-only formats and do not cross-build from macOS or Windows.
- Format-specific tooling is installed as noted in each step (for example `libfuse2`
  for AppImage, `snapcraft` for Snap, `flatpak-builder` for Flatpak).

## Configure the target formats

In `build.gradle.kts`, list the Linux formats you want in `targetFormats(...)` and
describe the package in the `linux { }` block:

```kotlin title="build.gradle.kts"
nucleus {
    application {
        nativeDistributions {
            targetFormats(
                TargetFormat.Deb,
                TargetFormat.Rpm,
                TargetFormat.AppImage,
                TargetFormat.Pacman,
                TargetFormat.Snap,
                TargetFormat.Flatpak,
            )
            homepage = "https://myapp.example.com"

            linux {
                iconFile.set(project.file("icons/app.png"))
                packageName = "myapp"
                shortcut = true
                appCategory = "Utility"
                menuGroup = "Development"

                debMaintainer = "Your Name <dev@example.com>"
                debDepends = listOf("libfuse2", "libgtk-3-0", "libasound2")

                rpmLicenseType = "MIT"
                rpmRequires = listOf("gtk3", "libX11", "alsa-lib")

                pacmanDepends = listOf("gtk3", "libx11", "alsa-lib")
            }
        }
    }
}
```

`homepage` is required for DEB and RPM builds. The packaging task fails without it.

## Build DEB and RPM packages

Each format has its own Gradle task named after the `TargetFormat` constant:

```shell
./gradlew packageDeb
./gradlew packageRpm
```

The plugin writes a `.desktop` entry into each package with the correct
`Categories=`, `MimeType=`, `StartupWMClass=`, and `Exec=` lines. If your app's
window class doesn't match what the window manager reports, set `startupWMClass`
explicitly:

```kotlin title="build.gradle.kts"
linux {
    startupWMClass = "com-example-MyApp"
}
```

When `startupWMClass` is unset, Nucleus derives it from `mainClass` by replacing
dots with hyphens.

## Build an AppImage

An AppImage is a single portable executable that runs on most distributions
without installation:

```shell
./gradlew packageAppImage
```

The build host needs `libfuse2`:

```shell
sudo apt-get install -y libfuse2
```

Configure the desktop metadata in the `appImage { }` sub-block:

```kotlin title="build.gradle.kts"
linux {
    appImage {
        category = AppImageCategory.Utility
        genericName = "My Application"
        synopsis = "A short description"
        desktopEntries = mapOf("Keywords" to "editor;text;")
    }
}
```

Output size and build time depend on `nativeDistributions.compressionLevel`:

| `CompressionLevel` | Output | Build time |
|--------------------|--------|------------|
| `Store`            | Largest | Fastest |
| `Normal` (default) | Balanced | Moderate |
| `Maximum`          | Small | Slow |
| `Ultra`            | Smallest | Slowest |

`Ultra` additionally rebuilds the `.deb` at maximum xz effort (`xz -9e`), roughly 25% smaller
than `Maximum`. RPM and pacman already use xz -9 and are unaffected.

Prefer `Normal` or `Store` for AppImage: `Maximum` / `Ultra` map to electron-builder
`maximum` and make cold starts very slow (squashfs/FUSE decompression). From 2.3.1 you can
override only the AppImage while leaving DEB/DMG on a higher global level:

```kotlin title="build.gradle.kts"
nativeDistributions {
    compressionLevel = CompressionLevel.Ultra
    linux {
        appImage {
            // Snappy FUSE cold start; DEB still uses Ultra above.
            compressionLevel = CompressionLevel.Normal
        }
    }
}
```

## Package for Arch Linux

`TargetFormat.Pacman` produces a pacman archive for Arch Linux and derivatives:

```shell
./gradlew packagePacman
```

Set Arch-specific dependencies and, if needed, an independent version string:

```kotlin title="build.gradle.kts"
linux {
    pacmanDepends = listOf("gtk3", "libx11", "alsa-lib")
    pacmanPackageVersion = "2.0.0"
}
```

## Add install and remove scripts

Deb, Rpm, and Pacman packages run maintainer scripts as root. Point `linux { }` at your
own files; Nucleus concatenates the after-scripts after its own template (desktop
integration, AppArmor, optional polkit silent-update helper) and passes the before-scripts
raw to fpm. GraalVM native-image packages honor the same properties.

```kotlin title="build.gradle.kts"
linux {
    afterInstall.set(project.file("packaging/linux/after-install.sh"))
    afterRemove.set(project.file("packaging/linux/after-remove.sh"))
    beforeInstall.set(project.file("packaging/linux/before-install.sh"))
    beforeRemove.set(project.file("packaging/linux/before-remove.sh"))
    // Pacman only: the install/remove scripts do not run on an upgrade
    afterUpgrade.set(project.file("packaging/linux/after-upgrade.sh"))
    beforeUpgrade.set(project.file("packaging/linux/before-upgrade.sh"))
}
```

| Property | When it runs | How it is wired |
|----------|--------------|-----------------|
| `afterInstall` | After the payload is unpacked | Concatenated after Nucleus's template, then electron-builder |
| `afterRemove` | After the payload is deleted | Concatenated after Nucleus's template, then electron-builder |
| `beforeInstall` | Before the payload is unpacked | Passed raw to fpm (`--before-install`) |
| `beforeRemove` | Before the payload is deleted | Passed raw to fpm (`--before-remove`) |
| `afterUpgrade` | After a Pacman upgrade swaps the payload | Passed raw to fpm (`--after-upgrade`) |
| `beforeUpgrade` | Before a Pacman upgrade swaps the payload | Passed raw to fpm (`--before-upgrade`) |

Typical use: install a systemd unit that ships under `appResourcesRootDir`, then enable it
from `afterInstall`. Stop the unit in `beforeInstall` so binaries under `/opt` can be
replaced, and disable it in `afterRemove`.

The payload is installed under `/opt/<packageName>` (`linux.packageName`, falling back to
`packageName`), never under the display `appName`, so the path contains no spaces and is
safe in unquoted `ExecStart=` lines.

electron-builder substitutes `${sanitizedProductName}` and `${executable}` in
`afterInstall` / `afterRemove` **only when the token is single-quoted**:

```shell title="packaging/linux/after-install.sh"
systemctl enable '${executable}-daemon.service'
systemctl start '${executable}-daemon.service'
```

A double-quoted `"${executable}"` is left as literal text, so
`systemctl enable "${executable}.service"` silently no-ops instead of failing. `beforeInstall`,
`beforeRemove`, `afterUpgrade`, and `beforeUpgrade` get no macro substitution at all —
hardcode unit and path names there.

When Pacman replaces an installed package with a newer version, its `.INSTALL` calls only
`pre_upgrade` / `post_upgrade`. None of `afterInstall`, `afterRemove`, `beforeInstall`, or
`beforeRemove` run, and there is no fallback to them. Stop the unit in `beforeUpgrade` and
re-enable or restart it in `afterUpgrade`, or an upgrade leaves the service dead. Deb and
Rpm ignore both upgrade properties: their install scriptlets already fire on upgrades.

AppImage, Snap, and Flatpak do not run these scripts. AppImage is not installed; Snap and
Flatpak have their own hook surfaces.

## Publish to the Snap Store

Snap targets the [Snap Store](https://snapcraft.io/). The default `plugs` cover
desktop integration, X11 and Wayland, networking, audio playback, and OpenGL.
Override `confinement` when your app needs filesystem access beyond `home`:

```kotlin title="build.gradle.kts"
linux {
    snap {
        confinement = SnapConfinement.Strict
        grade = SnapGrade.Stable
        base = "core22"
        plugs = listOf(
            SnapPlug.Desktop,
            SnapPlug.Home,
            SnapPlug.Wayland,
            SnapPlug.Network,
            SnapPlug.AudioPlayback,
        )
        compression = SnapCompression.Xz
    }
}
```

```shell
./gradlew packageSnap
```

The build host needs `snapd` and `snapcraft --classic`.

## Publish to Flathub with Flatpak

Flatpak is sandboxed. Declare the permissions your app needs through `finishArgs`.
The defaults are `--share=ipc`, `--socket=x11`, `--socket=wayland`,
`--socket=pulseaudio`, and `--device=dri`; setting `finishArgs` replaces them, so
include everything you need:

```kotlin title="build.gradle.kts"
linux {
    flatpak {
        runtime = "org.freedesktop.Platform"
        runtimeVersion = "23.08"
        sdk = "org.freedesktop.Sdk"

        finishArgs = listOf(
            "--share=ipc",
            "--socket=wayland",
            "--socket=pulseaudio",
            "--device=dri",
            "--filesystem=home",
            "--share=network",
        )
    }
}
```

```shell
./gradlew packageFlatpak
```

Flatpak is a store format and runs through the
[sandboxed pipeline](/docs/packaging/sandboxing): native libraries are
pre-extracted and JVM arguments are redirected. If `flatpak-builder` or the
runtime isn't installed, the task is skipped rather than failed.

## Register deep links and file associations

Top-level `protocol(...)` and `fileAssociation(...)` entries are merged into the
generated `.desktop` file as `MimeType=` values:

```kotlin title="build.gradle.kts"
nativeDistributions {
    protocol("MyApp URL", "myapp")
    fileAssociation(
        mimeType = "application/x-myapp",
        extension = "myapp",
        description = "MyApp Document",
    )
}
```

This produces:

```ini
MimeType=x-scheme-handler/myapp;application/x-myapp;
```

No manual `desktopEntries` override is needed.

## Configuration reference

`linux { }` exposes `iconFile`, `packageVersion`, `shortcut`, `startupWMClass`,
`packageName`, `appRelease`, `appCategory`, `menuGroup`, `debMaintainer`,
`debPackageVersion`, `debDepends`, `rpmLicenseType`, `rpmPackageVersion`,
`rpmRequires`, `pacmanPackageVersion`, `pacmanDepends`, `afterInstall`,
`afterRemove`, `beforeInstall`, `beforeRemove`, `afterUpgrade`, and `beforeUpgrade`. Sub-blocks are
`appImage { }`, `snap { }`, `flatpak { }`, and `signing { }`.

`appRelease` sets the package release number — the digit after the `-` in DEB and
RPM versions. Bump it when you re-release without changing `packageVersion`. See
the full [Gradle DSL reference](/docs/reference/gradle-dsl).

Snap and Flatpak layer their own desktop files into the user environment and
ignore the traditional `.desktop` install paths used by DEB and RPM.

## What's next

- [Code signing](/docs/packaging/code-signing) — sign DEB and RPM packages with GPG.
- [Sandboxing](/docs/packaging/sandboxing) — how the Flatpak pipeline repackages your app.
- [Publishing](/docs/packaging/publishing) — release built artifacts to GitHub, S3, or a generic server.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — every `linux { }` property.

---

# Code signing

URL: https://nucleusframework.dev/en/docs/packaging/code-signing

Sign and notarize your app's installers on macOS, sign with a PFX certificate or Azure Artifact Signing on Windows, and GPG-sign DEB/RPM packages on Linux.

In this tutorial, you'll sign your Nucleus app's installers on macOS, Windows, and Linux, and
notarize the macOS build with Apple. Signing is configured in the same `nativeDistributions { }`
DSL that drives packaging: one `signing { }` block per operating system, or a single unified
block for all three.

## Before you start

Signing ships with the Gradle plugin, so there is nothing extra to install. What you need depends
on the platform you target:

- **macOS** — an Apple Developer account with a *Developer ID Application* certificate, plus
  notarization credentials (an Apple ID app-specific password, a `notarytool` keychain profile,
  or an App Store Connect API key).
- **Windows** — a `.pfx`/`.p12` code-signing certificate, or an Azure Trusted Signing account.
- **Linux** — a GPG key pair. No paid certificate or authority is required.

## Sign and notarize on macOS

Direct-distribution formats (DMG, ZIP) are signed with a *Developer ID Application* identity and
then submitted to Apple for notarization. Configure the identity in `signing { }` and the
credentials in `notarization { }`:

```kotlin title="build.gradle.kts"
macOS {
    signing {
        sign.set(true)
        identity.set("Developer ID Application: My Company (TEAMID)")
    }
    notarization {
        appleID.set("dev@example.com")
        password.set(System.getenv("MAC_NOTARIZATION_PASSWORD"))
        teamID.set("TEAMID")
    }
}
```

Mac App Store builds (PKG) follow a separate path: a *3rd Party Mac Developer Application*
certificate with provisioning profiles, and no notarization — Apple reviews the upload through
Transporter.

### Choose a notarization mode

Notarization supports three mutually exclusive authentication modes. Configuring more than one in
the same build is rejected at validation, so pick one.

1. Apple ID and an app-specific password:

   ```kotlin
   notarization {
       appleID.set("dev@example.com")
       password.set(System.getenv("MAC_NOTARIZATION_PASSWORD"))
       teamID.set("TEAMID")
   }
   ```

2. A `notarytool` keychain profile. Store the credentials once with
   `xcrun notarytool store-credentials AC_PASSWORD …`, then reference the profile:

   ```kotlin
   notarization {
       keychainProfile.set("AC_PASSWORD")
   }
   ```

3. An App Store Connect API key, which is the recommended mode for CI:

   ```kotlin
   notarization {
       apiKey.set("/path/to/AuthKey_ABC123.p8")
       apiKeyId.set("ABC123")
       apiIssuer.set("12345678-90ab-cdef-1234-567890abcdef")
   }
   ```

### Sign universal binaries

`lipo` invalidates every existing code signature, so universal builds re-sign after the merge in a
strict inside-out order: `.dylib` and `.jnilib` files with runtime entitlements, main executables
with app entitlements, then the runtime bundle, then the `.app` itself. All `codesign` invocations
use `--options runtime --timestamp`. The `build-macos-universal` composite action handles this in
CI — see [CI/CD](/docs/packaging/ci-cd).

## Sign on Windows

Use a `.pfx` or `.p12` certificate, optionally password-protected, with a timestamp server. The
algorithm defaults to `SigningAlgorithm.Sha256`:

```kotlin title="build.gradle.kts"
windows {
    signing {
        enabled = true
        certificateFile.set(file(System.getenv("WIN_CSC_LINK") ?: "certs/certificate.pfx"))
        certificatePassword = System.getenv("WIN_CSC_KEY_PASSWORD")
        algorithm = SigningAlgorithm.Sha256
        timestampServer = "http://timestamp.digicert.com"
    }
}
```

Common timestamp servers are DigiCert (`http://timestamp.digicert.com`), Sectigo
(`http://timestamp.sectigo.com`), and GlobalSign (`http://timestamp.globalsign.com`).

To sign with a cloud HSM instead of a local certificate file, use Azure Artifact Signing:

```kotlin title="build.gradle.kts"
windows {
    signing {
        enabled = true
        publisherName = "My Publisher"
        azureTenantId = System.getenv("AZURE_TENANT_ID")
        azureEndpoint = "https://eastus.codesigning.azure.net"
        azureCertificateProfileName = "my-profile"
        azureCodeSigningAccountName = "my-account"
    }
}
```

## Sign on Linux

Linux has no OS gatekeeper. Signing lets anyone who downloads your `.deb`/`.rpm` directly — outside
an apt/dnf repository — verify that it came from you and was not tampered with. You sign with your
own GPG key, so no paid certificate or authority is involved.

1. Generate a key once, if you don't already have one:

   ```shell
   gpg --full-generate-key          # RSA 4096, your name and email
   gpg --list-secret-keys --keyid-format=long
   # sec   rsa4096/AB12CD34EF56 ...  the key id is "AB12CD34EF56"
   ```

2. Enable signing with that key id:

   ```kotlin title="build.gradle.kts"
   linux {
       signing {
           enabled.set(true)
           keyId.set("AB12CD34EF56")
           // passphrase.set(System.getenv("LINUX_GPG_PASSPHRASE"))  // only if the key has one
       }
   }
   ```

   The key is read from your local GPG keyring. In CI, point `keyFile` at an exported key
   instead — see [Manage signing secrets in CI](#manage-signing-secrets-in-ci).

3. Build. Each package comes out signed, with its public key written alongside it:

   ```text
   MyApp-1.0.0-linux-x64.deb
   MyApp-1.0.0-linux-x64.deb.asc        # detached signature (DEB)
   MyApp-1.0.0-linux-x64.deb.pub.asc    # your public key
   MyApp-1.0.0-linux-x64.rpm            # signature embedded in the RPM header
   MyApp-1.0.0-linux-x64.rpm.pub.asc
   ```

   Publish each package together with its `.pub.asc` (and the `.deb.asc` for DEB) on your download
   page.

4. Users verify a download before trusting it:

   ```shell
   # DEB — detached signature
   gpg --import MyApp-1.0.0-linux-x64.deb.pub.asc
   gpg --verify MyApp-1.0.0-linux-x64.deb.asc MyApp-1.0.0-linux-x64.deb
   # Good signature from "Your Name <you@example.com>"

   # RPM — header signature
   sudo rpm --import MyApp-1.0.0-linux-x64.rpm.pub.asc
   rpm -K MyApp-1.0.0-linux-x64.rpm
   # digests signatures OK
   ```

Signing does not change installation. A signed package installs exactly like an unsigned one, with
or without the key imported. Verification is an optional step the user runs before installing, and
becomes mandatory only when the user enforces it (for example, a `debsig-verify` policy or strict
RPM signature checking).

### Choose a DEB signing method

`debMethod` selects how the DEB is signed, using a `DebSignMethod` value:

- `Detached` (default) writes a detached `<pkg>.deb.asc`, verified with
  `gpg --verify <pkg>.deb.asc <pkg>.deb`. It needs only `gpg`, so it works on every distribution.
  It is the default because `dpkg-sig` was removed from recent Debian and Ubuntu releases.
- `DpkgSig` embeds an `_gpgorigin` member through `dpkg-sig`, verified with a plain
  `gpg --verify <pkg>.deb`. It requires `dpkg-sig` at build time.
- `Debsig` embeds an `_gpgorigin` member through `debsigs`, verified with `debsig-verify`. It also
  requires a per-key policy and keyring on the client.

```kotlin title="build.gradle.kts"
linux {
    signing {
        enabled.set(true)
        keyId.set("AB12CD34EF56")
        debMethod = DebSignMethod.Detached   // Detached | DpkgSig | Debsig
    }
}
```

The signing key never touches your real keyring during the build: Nucleus imports `keyFile` into a
throwaway `GNUPGHOME` and discards it afterwards.

### Enable passwordless self-update

Once your packages are signed, the app can apply updates without a root password prompt, because
the install is gated on the signature. Add `silentUpdate.set(true)` to the Linux signing block; see
[passwordless updates](/docs/packaging/auto-update#set-up-passwordless-updates-on-linux) for the full flow
and security model.

## Configure all platforms in one block

To keep signing in a single entry point, wrap the per-OS blocks in one `signing { }` under
`nativeDistributions`. It delegates to the same `macOS.signing`, `windows.signing`, and
`linux.signing` instances, so you can mix the two styles freely:

```kotlin title="build.gradle.kts"
nativeDistributions {
    signing {
        macOS   { sign.set(true); identity.set("Developer ID Application: My Company (TEAMID)") }
        windows { enabled = true; certificateFile.set(file("certs/certificate.pfx")) }
        linux   { enabled.set(true); keyId.set("AB12CD34EF56") }
    }
}
```

## Manage signing secrets in CI

Never commit certificates or private keys. In GitHub Actions, base64-encode the PFX and decode it at
build time. For macOS, the `setup-macos-signing` composite action creates a temporary keychain and
imports certificates from secrets — see [CI/CD](/docs/packaging/ci-cd).

For Linux, export the private key and store it as a secret:

```shell
gpg --armor --export-secret-keys AB12CD34EF56   # paste into the LINUX_GPG_PRIVATE_KEY secret
```

Add `LINUX_GPG_PRIVATE_KEY`, `LINUX_GPG_KEY_ID`, and (if set) `LINUX_GPG_PASSPHRASE`. The release
workflow writes a temporary key file and passes these to the build through the
`compose.desktop.linux.signing.*` properties; when the secrets are absent, the build is left
unsigned. Configure the build to read them:

```kotlin title="build.gradle.kts"
linux {
    signing {
        enabled.set(true)
        keyId.set(System.getenv("LINUX_GPG_KEY_ID"))
        keyFile.set(file(System.getenv("LINUX_GPG_KEY_FILE") ?: "build/signing-key.asc"))
        passphrase.set(System.getenv("LINUX_GPG_PASSPHRASE"))
    }
}
```

## Reference

- `macOS.signing { }` — `sign`, `identity`, `keychain`, `prefix`
- `macOS.notarization { }` — `appleID` + `password` + `teamID`, or `keychainProfile`
  (+ `keychainPath`), or `apiKey` + `apiKeyId` + `apiIssuer`
- `windows.signing { }` — `enabled`, `certificateFile`, `certificatePassword`, `certificateSha1`,
  `certificateSubjectName`, `algorithm`, `timestampServer`, plus the Azure fields
- `linux.signing { }` — `enabled`, `keyId`, `keyFile`, `passphrase`, `debMethod`
  (`Detached` | `DpkgSig` | `Debsig`), `silentUpdate`
- `signing { macOS { } windows { } linux { } }` — unified block over the same per-OS settings

The full DSL is documented in the [Gradle DSL reference](/docs/reference/gradle-dsl).

## Notes

- **Entitlements for the hardened runtime.** The minimal JVM entitlements are
  `com.apple.security.cs.allow-jit`, `com.apple.security.cs.allow-unsigned-executable-memory`, and
  `com.apple.security.cs.allow-dyld-environment-variables`. See
  [sandboxing](/docs/packaging/sandboxing) for the sandboxed PKG entitlements.
- **Equivalent Gradle properties.** Every notarization field has a
  `compose.desktop.mac.notarization.<name>` Gradle property, which is useful when you pass secrets
  with `-P` instead of environment variables. Linux signing exposes `compose.desktop.linux.sign` and
  `compose.desktop.linux.signing.{keyId,keyFile,passphrase}`.
- **Linux signing is opt-in.** It stays off until `linux.signing.enabled` is `true` and a `keyId` is
  set. Repository-level signing (apt/dnf `Release.gpg`, `InRelease`) is a separate concern and out of
  scope — this signs the standalone package for direct download.
- **PFX rotation.** Update the certificate at least 30 days before it expires. A signed-but-expired
  binary fails SmartScreen until a fresh, timestamped signature is applied.

## What's next

- [CI/CD](/docs/packaging/ci-cd) — sign builds in GitHub Actions with the composite actions.
- [Auto-update](/docs/packaging/auto-update) — ship signed updates, including passwordless updates on Linux.
- [Sandboxing](/docs/packaging/sandboxing) — entitlements and store-format builds.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — the full `nativeDistributions { }` surface.

---

# Trusted CA certificates

URL: https://nucleusframework.dev/en/docs/packaging/trusted-certificates

Import private root CA certificates into the JDK bundled with your packaged app so its HTTPS calls trust them.

Nucleus can import private CA certificates into the `cacerts` keystore of the JDK it bundles
with your packaged app. You declare the certificate files in the Gradle DSL, and Nucleus imports
them at packaging time so the shipped app trusts them without any change to the user's machine.

This applies when your app runs behind a corporate proxy, a ZTNA gateway, or a filtering service
that terminates TLS with a private root CA the default JDK trust store does not recognize. Without
the certificate, every HTTPS call fails with `SSLHandshakeException`.

## Declare the certificates

Add the certificate files to `nativeDistributions.trustedCertificates`:

```kotlin title="build.gradle.kts"
nucleus {
    application {
        nativeDistributions {
            trustedCertificates.from(
                files(
                    "certs/company-ca.pem",
                    "certs/vpn-root.crt",
                ),
            )
        }
    }
}
```

Both PEM (`-----BEGIN CERTIFICATE-----`) and DER (binary) files are accepted. The feature is part
of the Nucleus Gradle plugin, so there is no extra dependency to add.

## How it works

After `createRuntimeImage` produces the JLink runtime, Nucleus copies it to `runtime-patched/`
and runs `keytool -import -trustcacerts` against the copy's `cacerts` for each certificate. The
original runtime image is never modified in place. The patched copy is then used by both
`createDistributable` and `createSandboxedDistributable`, so every packaging format embeds the
same trusted root.

Each certificate gets a stable alias derived from its file name and content: the file name is
lowercased, non-alphanumeric characters become `-`, it is truncated to 32 characters, and the
first 8 hex characters of the content's SHA-256 hash are appended. For example, `company-ca.crt`
becomes `company-ca-3a1f8b2c`. Because the alias includes the content hash, importing the same
certificate twice produces the same alias; `keytool` reports that the alias already exists and
Nucleus skips it, so re-running the build never duplicates entries.

The `keytool` binary comes from the JDK set through the application's `javaHome`. When `javaHome`
is unset, Nucleus uses the JVM that runs the build. The keystore is opened with the standard
`cacerts` password `changeit`.

The `patchCaCertificates` task is registered only when `trustedCertificates` is non-empty. It runs
automatically as part of packaging; you do not invoke it directly.

## API reference

| Symbol | Type | Description |
| --- | --- | --- |
| `nativeDistributions.trustedCertificates` | `ConfigurableFileCollection` | CA certificate files (PEM or DER) to import into the bundled JDK's `cacerts`. |
| `patchCaCertificates` | Gradle task | Copies the runtime image and imports each certificate. Registered only when `trustedCertificates` is non-empty. |

## Notes

- Only the **bundled** JDK is patched. The JDK on the user's machine and the JDK running the build
  are untouched.
- `trustedCertificates` covers CAs known at build time, shipped to every user. To trust CAs that
  end users install themselves at runtime (Keychain on macOS, CryptoAPI on Windows, NSS or system
  PEM stores on Linux), use the [`native-ssl` module](/docs/performance/native-ssl) instead.

The two approaches are complementary. Ship build-time CAs with `trustedCertificates`, and read the
user's already-installed CAs with `native-ssl`.

## What's next

- [Code signing](/docs/packaging/code-signing) — sign and notarize the packaged app.
- [native-ssl](/docs/performance/native-ssl) — trust the operating system's certificate stores at runtime.
- [Gradle DSL reference](/docs/reference/gradle-dsl) — the full `nucleus { }` configuration surface.

---

# Sandboxing

URL: https://nucleusframework.dev/en/docs/packaging/sandboxing

How Nucleus builds sandboxed distributions for the App Store, Flatpak, and MSIX store formats.

Three store formats require a sandboxed build: `Pkg` (macOS App Sandbox), `Flatpak` (Linux), and `AppX` (Windows MSIX). Sandboxed apps cannot extract native libraries to a temporary directory at runtime or load arbitrary code, so Nucleus runs a second build pipeline for these formats. This page describes what that pipeline does and how to configure the parts that need per-project values.

## Request a store format

Add a store format to `targetFormats`. The sandboxed pipeline is enabled automatically when at least one store format is present.

```kotlin title="build.gradle.kts"
nucleus {
    application {
        nativeDistributions {
            targetFormats(
                // Non-sandboxed pipeline
                TargetFormat.Dmg,
                TargetFormat.Nsis,
                TargetFormat.Deb,
                // Sandboxed pipeline
                TargetFormat.Pkg,
                TargetFormat.AppX,
                TargetFormat.Flatpak,
            )
        }
    }
}
```

Run the standard packaging task. Both pipelines run in the same invocation:

```shell
./gradlew packageDistributionForCurrentOS
```

## How it works

| Format    | OS      | Sandbox model |
|-----------|---------|---------------|
| `Pkg`     | macOS   | [App Sandbox](https://developer.apple.com/documentation/security/app-sandbox) |
| `AppX`    | Windows | MSIX — full trust, but with packaging constraints |
| `Flatpak` | Linux   | [Flatpak sandbox](https://docs.flatpak.org/en/latest/sandbox-permissions.html) |

When at least one store format is configured, Nucleus registers additional Gradle tasks that:

1. Scan dependency JARs for `.dylib`, `.jnilib`, `.so`, and `.dll` files and extract them — into `Contents/Frameworks/` on macOS, and into `resources/` on Windows and Linux.
2. Rewrite the JARs without those native entries to avoid duplicating them.
3. Merge your `appResources` with the extracted libraries.
4. Inject JVM arguments so `java.library.path`, `jna.library.path`, and `jna.boot.library.path` point at the signed extraction directory. JNA also receives `nounpack=true` and `nosys=true`.
5. Sign each native binary in `Contents/Frameworks/` individually with `codesign` (macOS).
6. Rewire Skiko and `icudtl.dat` to the same directory.

The non-sandboxed pipeline keeps running in parallel, so `Dmg`, `Nsis`, and `Deb` are built unchanged.

### AOT cache and sandboxing

When generating an AOT cache for a sandboxed build, Nucleus strips `jspawnhelper`'s code signature during the training phase — macOS terminates sandboxed forked processes otherwise — and re-applies it with the runtime entitlements before packaging.

### Windows AppX

`AppX` runs at full trust and has the same system access as a regular Win32 app. It joins the sandboxed pipeline only because MSIX packaging forbids extracting DLLs to a temporary directory at runtime.

## Configure macOS entitlements

Nucleus ships default entitlements for both sandboxed and non-sandboxed builds.

Non-sandboxed builds (`Dmg`, `Zip`):

```xml
<key>com.apple.security.cs.allow-jit</key>                        <true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key> <true/>
<key>com.apple.security.cs.disable-library-validation</key>       <true/>
```

Sandboxed builds (`Pkg`):

```xml
<key>com.apple.security.app-sandbox</key>                         <true/>
<key>com.apple.security.cs.allow-jit</key>                        <true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key> <true/>
<key>com.apple.security.cs.disable-library-validation</key>       <true/>
<key>com.apple.security.network.client</key>                      <true/>
<key>com.apple.security.files.user-selected.read-write</key>      <true/>
```

The runtime entitlements applied to the bundled JVM binaries are stricter: no network and no file access. Only your app code declares capabilities. Override either set per build:

```kotlin title="build.gradle.kts"
macOS {
    entitlementsFile.set(project.file("packaging/entitlements.plist"))
    runtimeEntitlementsFile.set(project.file("packaging/runtime-entitlements.plist"))
}
```

## Embed provisioning profiles

Mac App Store submission requires provisioning profiles embedded at `Contents/embedded.provisionprofile`:

```kotlin title="build.gradle.kts"
macOS {
    provisioningProfile.set(project.file("packaging/MyApp.provisionprofile"))
    runtimeProvisioningProfile.set(project.file("packaging/MyApp_Runtime.provisionprofile"))
}
```

## Configure the Flatpak sandbox

Flatpak permissions are declared through `finishArgs`:

```kotlin title="build.gradle.kts"
linux {
    flatpak {
        finishArgs = listOf(
            "--share=ipc",
            "--socket=wayland",
            "--socket=pulseaudio",
            "--device=dri",
            "--filesystem=home",
            "--share=network",
        )
    }
}
```

See [Linux targets](/docs/packaging/linux) for the remaining Flatpak options.

## Tasks

These tasks are registered only when a store format is requested.

| Task | Purpose |
|------|---------|
| `extractNativeLibsForSandboxing` | Extract `.dylib`, `.so`, and `.dll` files from dependency JARs. |
| `stripNativeLibsFromJars` | Rewrite the JARs without their native entries. |
| `prepareSandboxedAppResources` | Merge `appResources` with the extracted libraries. |
| `createSandboxedDistributable` | Build the app image with the sandbox JVM arguments. |
| `generateSandboxedAotCache` | Train the AOT cache inside the sandbox. |

## Notes

`appStore` is deprecated and ignored. `Pkg` is always treated as an App Store build: Nucleus applies the 3rd Party Mac Developer certificates and sandbox entitlements automatically.

- A single `./gradlew packageReleaseDistributionForCurrentOS` builds both pipelines in CI. Sandboxed artifacts are written to `<format>-sandboxed/` subdirectories.
- The sandboxed pipeline builds on the inside-out signing order used for universal macOS binaries. See [Code signing](/docs/packaging/code-signing).

## What's next

- [Code signing](/docs/packaging/code-signing) — sign and notarize macOS, Windows, and Linux builds.
- [macOS targets](/docs/packaging/macos) — entitlements, provisioning profiles, and DMG layout.
- [Linux targets](/docs/packaging/linux) — Flatpak, Snap, and AppImage configuration.

---

# Auto-update

URL: https://nucleusframework.dev/en/docs/packaging/auto-update

Check for, download, verify, and install application updates from Kotlin, without a third-party service.

The `updater-runtime` module checks for, downloads, verifies, and installs application updates
from Kotlin. It has a build-time half — `latest-*.yml` metadata generated next to your installers
— and a runtime half, the `NucleusUpdater` class. The metadata format is compatible with
electron-builder's update format.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("dev.nucleusframework:nucleus.updater-runtime:<version>")
    // Optional, for corporate networks with a private root CA:
    implementation("dev.nucleusframework:nucleus.native-http:<version>")
}
```

## Check and install an update

Create a `NucleusUpdater`, check the configured provider, then download and install:

```kotlin
import dev.nucleusframework.updater.NucleusUpdater
import dev.nucleusframework.updater.UpdateResult
import dev.nucleusframework.updater.provider.GitHubProvider
import java.io.File

val updater = NucleusUpdater {
    provider = GitHubProvider(owner = "myorg", repo = "myapp")
}

when (val result = updater.checkForUpdates()) {
    is UpdateResult.Available -> {
        var installer: File? = null
        updater.downloadUpdate(result.info).collect { progress ->
            println("${progress.percent.toInt()}%")
            progress.file?.let { installer = it }
        }
        // installAndRestart launches the installer, exits, and relaunches
        installer?.let(updater::installAndRestart)
    }
    UpdateResult.NotAvailable -> println("Up to date")
    is UpdateResult.Error -> println("Error: ${result.exception.message}")
}
```

`checkForUpdates()` is a `suspend` function; call it from a coroutine.

## Supported formats

The runtime updates in-place formats and leaves store-managed formats to their store.

| Platform | Updatable | Managed by the store |
|----------|-----------|----------------------|
| macOS | DMG, ZIP | PKG |
| Windows | NSIS, NSIS Web, MSI | AppX/MSIX |
| Linux | DEB, RPM, AppImage | Snap, Flatpak |

The updater replaces the `.app` silently from the ZIP; the DMG is only for the first install. Add
`TargetFormat.Zip` next to `TargetFormat.Dmg` so both ship in the same release — `latest-mac.yml`
references both.

## How it works

### Metadata

The plugin writes one YAML file per platform, listing every installer with its SHA-512 and size.
Multi-arch or multi-platform releases need a single YAML per platform that lists every
architecture; CI merges them in the release job. A `latest-mac.yml` looks like this:

```yaml
version: 1.2.3
files:
  - url: MyApp-1.2.3-macos-arm64.dmg
    sha512: VkJl1gDqcBHYbYhMb0HRI...
    size: 102400000
  - url: MyApp-1.2.3-macos-arm64.zip
    sha512: qJ8a5gFDCwv0R2rW6lM3k...
    size: 98000000
releaseDate: '2026-03-01T12:00:00.000Z'
```

### Channels

The version tag drives the channel: `v1.0.0` maps to `latest`, `v1.0.0-beta.1` to `beta`, and
`v1.0.0-alpha.1` to `alpha`. Each channel has its own `*-mac.yml`, `*.yml`, and `*-linux.yml`.
Users on `beta` see `latest` and `beta`; users on `alpha` see all three.

### Hosting

Hosting is configured in `nativeDistributions.publish { }` (see
[publishing](/docs/packaging/publishing)):

- **GitHub Releases** — the [release workflow](/docs/packaging/ci-cd#publish-the-release) handles it end to end.
- **S3** — set credentials via environment variables; the plugin uploads alongside the YAML.
- **Generic HTTPS** — upload to any static host yourself; the updater fetches `<baseUrl>/latest-*.yml`.
  The base URL must be `https` (see [Providers](#providers)).

The `publish { }` block only generates electron-builder config — it does not upload. CI does the upload.

### Differential downloads

From 2.3, `downloadUpdate` tries a **differential** download before a full fetch. It matches
electron-builder block maps of the new artifact against a cached copy of the previous one,
copies unchanged blocks from disk, and fetches the rest with HTTP range requests. Blocks are
matched by content, so jumps such as 1.0 → 1.7 are differential too — no pairwise delta files
are ever produced.

The Nucleus Gradle plugin already publishes the maps the runtime needs:

| Format | Block map |
|--------|-----------|
| NSIS, macOS ZIP / DMG | Standalone gzipped `<artifact>.blockmap` next to the installer |
| AppImage | Map appended in the AppImage trailer (`blockMapSize` in `latest-linux.yml`) |

Behaviour:

- **AppImage** — the running executable *is* the previous artifact, so the first update can
  already be differential.
- **Other formats** — the updater caches each successful download (and its map) under
  `cacheDir` (default `%LOCALAPPDATA%/nucleus/updates/<appId>` on Windows,
  `~/.cache/nucleus/updates/<appId>` elsewhere). The second update on is differential.
- Any missing map, range-request failure, or digest mismatch **silently falls back** to a full
  download.

```kotlin
val updater = NucleusUpdater {
    provider = GitHubProvider(owner = "myorg", repo = "myapp")
    differentialDownload = true   // default
    // cacheDir = File("/var/cache/myapp/updates")  // optional override
}

updater.downloadUpdate(info).collect { progress ->
    val kind = if (progress.isDifferential) "differential" else "full"
    println(
        "${progress.percent.toInt()}% " +
            "(${progress.bytesDownloaded}/${progress.totalBytes}, $kind)",
    )
    progress.file?.let { installer = it }
}
```

`DownloadProgress.bytesDownloaded` / `totalBytes` count **bytes transferred**, so for a
differential download `totalBytes` is smaller than the artifact size and `percent` tracks
wait time faithfully. `isDifferential` is `true` when the differential path completed.

Set `differentialDownload = false` to force full downloads (for example when a CDN does not
support HTTP ranges).

### Post-update detection

After `installAndRestart` or `installAndQuit`, the updater writes a marker file in the platform's
app-data directory (resolved from `NucleusApp.appId`). On the next launch, `wasJustUpdated()`
returns `true` and `consumeUpdateEvent()` yields an `UpdateEvent(previousVersion, newVersion,
updateLevel)` you can use for a "What's new" banner.

## Configure enterprise networks

If your users sit behind a corporate proxy with a private root CA, the default
`java.net.http.HttpClient` fails the TLS handshake. Inject a `NativeHttpClient` that reads the OS
trust store:

```kotlin
import dev.nucleusframework.nativehttp.NativeHttpClient

val updater = NucleusUpdater {
    provider = GitHubProvider(owner = "myorg", repo = "myapp")
    httpClient = NativeHttpClient.create()
}
```

See [`native-ssl`](/docs/performance/native-ssl) for the trust-manager details.

## Set up passwordless updates on Linux

By default, applying a DEB or RPM update runs through `pkexec`, which shows a PolicyKit password
dialog. You can let the app install verified updates without a password, gated on a signature check.

This builds on [Linux code signing](/docs/packaging/code-signing#sign-on-linux).
Enable it on the signing block:

```kotlin title="build.gradle.kts"
linux {
    signing {
        enabled.set(true)
        keyId.set("AB12CD34EF56")
        silentUpdate.set(true)   // requires enabled = true
    }
}
```

The package payload and post-install scripts set up passwordless updates as follows:

1. A root-owned update helper **shipped inside the package** at
   `/opt/<App>/nucleus-update-helper` (so `dpkg -S` / `rpm -qf` attribute it to the package).
   afterInstall only hardens permissions and installs a polkit policy scoped to that exact
   binary (`allow_active=yes`); afterRemove removes the policy.
2. Your signing public key, bundled at `/opt/<App>/resources/nucleus-update.pub.asc`.
3. At update time the runtime downloads the package and its detached `<file>.asc` signature
   (CI uploads `*.asc` next to the packages when Linux GPG secrets are present), resolves the
   helper by walking up from `bin/`, then runs `pkexec <helper> <file>`.
4. The helper verifies the signature against the bundled key, checks that the package name matches
   the installed app, and only then runs `dpkg -i` or `rpm -U`.

AppImage updates replace the binary in place while the previous FUSE mount still holds the old
inode, wait for the old process to exit (single-instance lock), and relaunch with a cleaned
environment (`APPDIR`, `APPIMAGE`, `LD_LIBRARY_PATH`, … unset) so the new image is not bound to
the unmounted squashfs.

The polkit `allow_active=yes` rule is scoped to the single helper binary, and the helper refuses any
package whose signature does not verify against the bundled key, so a passwordless install cannot
install an arbitrary package — an attacker would need your private signing key. If the helper or the
`<file>.asc` is missing, the runtime falls back to the password-prompting `pkexec` install and logs
the reason. Passwordless install requires an active local session.

## API reference

### Runtime methods

`NucleusUpdater` exposes:

- `suspend fun checkForUpdates(): UpdateResult` — returns `Available(info, level)`, `NotAvailable`,
  or `Error(exception)`.
- `fun downloadUpdate(info: UpdateInfo): Flow<DownloadProgress>` — emits progress; the final
  emission has `file != null`. Preferential differential path when maps and cache allow; see
  [Differential downloads](#differential-downloads).
- `fun installAndRestart(file: File)` — launches the installer, exits the process, relaunches after
  install (AppImage: replace-in-place + clean relaunch).
- `fun installAndQuit(file: File)` — silent install, no relaunch. The update applies on the next
  manual launch.
- `fun isUpdateSupported(): Boolean` — whether the current executable type can auto-update.
- `fun wasJustUpdated(): Boolean` and `fun consumeUpdateEvent(): UpdateEvent?` — post-update detection.

### Result and level types

- `UpdateResult.Available(info: UpdateInfo, level: UpdateLevel)`
- `UpdateResult.NotAvailable`
- `UpdateResult.Error(exception: UpdateException)`

`UpdateLevel` reports how large the jump is: `MAJOR`, `MINOR`, `PATCH`, or `PRE_RELEASE`. Branch your
UI on it — force a dialog for major bumps, install patches silently.

### Builder fields

`NucleusUpdater { }` configures a `UpdaterConfig`:

| Field | Default | Notes |
|-------|---------|-------|
| `currentVersion` | from `NucleusApp` / jpackage / marker | Used for channel and compare |
| `provider` | required | `GitHubProvider`, `GenericProvider`, … |
| `channel` | `"latest"` | Release channel name |
| `allowDowngrade` | `false` | |
| `allowPrerelease` | `false` | Also true when `currentVersion` contains `-` |
| `executableType` | auto | Override detected package type |
| `httpClient` | JDK client with redirects | Use `NativeHttpClient` for private CAs |
| `differentialDownload` | `true` | Assemble from cache + range requests; safe to leave on |
| `cacheDir` | platform default under `nucleus/updates/<appId>` | Previous artifact + block map |

### Providers

- `GitHubProvider(owner, repo, token? = null)`
- `GenericProvider(baseUrl)` — the `baseUrl` must use `https`. A non-`https` origin throws
  `IllegalArgumentException` at construction. `http` is accepted only for loopback hosts
  (`localhost`, `127.0.0.0/8`, `::1`) so integration tests can serve fixtures without TLS.

Custom auth headers come from the provider's `authHeaders()`, not from the config.

The manifest, the checksums, and the artifact all come from that one origin, so plain `http`
would let an on-path attacker rewrite the three together — the SHA-512 in the manifest protects
nothing if the attacker also writes the manifest.

### Installer commands

| OS | Format | Command |
|----|--------|---------|
| Linux | DEB | `pkexec dpkg -i <file>` |
| Linux | RPM | `pkexec rpm -U <file>` |
| Linux | AppImage | replace in place |
| macOS | DMG/ZIP | `open <file>` / extract |
| Windows | NSIS/EXE | `<file> /S` |
| Windows | MSI | `msiexec /i <file> /passive` |

### Exceptions

`UpdateException` is the base type. Subtypes: `NetworkException`, `ChecksumException`,
`NoMatchingFileException`, `ParseException`.

## Notes

- SHA-512 checksums are verified after download; a failed check deletes the file and surfaces an error.
- Passwordless Linux updates (`signing.silentUpdate`) add a second, stronger check: a GPG signature
  verified against the key bundled in the app.
- GitHub tokens are sent in the `Authorization` header, never in URL parameters.
- The detached installer script runs from a fresh owner-only directory (POSIX `0700`) created per
  update, not from a fixed path in the shared temp directory.
- For Mac App Store, Microsoft Store, Snapcraft, and Flathub, the store handles updates; skip
  `updater-runtime` entirely.

## What's next

- [Publishing](/docs/packaging/publishing) — configure providers in `nativeDistributions.publish { }`.
- [CI/CD](/docs/packaging/ci-cd#publish-the-release) — the release workflow that generates and uploads metadata.
- [Code signing](/docs/packaging/code-signing) — GPG signing for DEB/RPM and passwordless updates.

---

# Publishing

URL: https://nucleusframework.dev/en/docs/packaging/publishing

Configure Nucleus to publish signed installers and auto-update metadata to GitHub Releases, S3, or a generic HTTP host.

In this tutorial, you'll configure a publishing backend so your signed installers and their
auto-update metadata land in one place — GitHub Releases, an S3 bucket, or any HTTP host. You'll
pick a release channel and type, control when publishing runs, and see what each desktop store
expects for submission. The configuration lives in the same `nucleus { }` DSL as the rest of your
build.

## Before you start

- Working installers for your target platforms. See [Configuration](/docs/start/configuration)
  for the `targetFormats(...)` setup.
- Signed builds for the platforms you distribute. See [code signing](/docs/packaging/code-signing).
- A hosting target: a GitHub repository, an S3 bucket, or an HTTP server you control.

## Configure a publishing backend

Add a `publish { }` block inside `nativeDistributions { }` and enable one backend. The block only
generates configuration and the update YAML; the upload itself runs in CI.

**GitHub Releases**

```kotlin title="build.gradle.kts"
nucleus {
    application {
        nativeDistributions {
            publish {
                github {
                    enabled = true
                    owner = "myorg"
                    repo = "myapp"
                    token = System.getenv("GITHUB_TOKEN")
                    channel = ReleaseChannel.Latest
                    releaseType = ReleaseType.Release
                }
            }
        }
    }
}
```

A release ends up with the installers and their auto-update YAML side by side:

```
v1.0.0 (Release)
├── MyApp-1.0.0-macos-arm64.dmg
├── MyApp-1.0.0-macos-universal.dmg
├── MyApp-1.0.0-windows-amd64.exe
├── MyApp-1.0.0-windows.msixbundle
├── MyApp-1.0.0-linux-amd64.deb
├── MyApp-1.0.0-linux-amd64.AppImage
├── latest-mac.yml
├── latest.yml
└── latest-linux.yml
```

The token needs the `contents: write` permission. In GitHub Actions, set `permissions: contents: write`
on the job.

**S3**

Use an S3 bucket, optionally fronted by a CDN, for self-hosted distribution:

```kotlin title="build.gradle.kts"
publish {
    s3 {
        enabled = true
        bucket = "my-updates-bucket"
        region = "us-east-1"
        path = "releases/myapp"
        acl = "public-read"
    }
}
```

Provide `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` in the environment.

**Generic HTTP**

Any static host works — Nginx, Caddy, Cloudflare R2, or S3 with public access. The plugin
generates the YAML metadata for your base URL; you upload the files yourself:

```kotlin title="build.gradle.kts"
publish {
    generic {
        enabled = true
        url = "https://updates.example.com/releases/"
        channel = ReleaseChannel.Latest
        useMultipleRangeRequest = true
    }
}
```

`useMultipleRangeRequest` enables differential downloads and works only if your server honors
HTTP `Range` requests.

## Choose a release channel and type

The channel selects which YAML file the auto-updater reads, and the tag pattern it maps to:

| Channel | YAML | Tag pattern |
|---------|------|-------------|
| `ReleaseChannel.Latest` | `latest-*.yml` | `v1.0.0` |
| `ReleaseChannel.Beta` | `beta-*.yml` | `v1.0.0-beta.1` |
| `ReleaseChannel.Alpha` | `alpha-*.yml` | `v1.0.0-alpha.1` |

For GitHub Releases, the release type controls visibility:

| Type | Behavior |
|------|----------|
| `ReleaseType.Release` | Public on the releases page |
| `ReleaseType.Draft` | Hidden until manually published |
| `ReleaseType.Prerelease` | Marked as a pre-release |

## Set the publish mode

`publishMode` decides when publishing runs. It defaults to `PublishMode.Never`:

```kotlin title="build.gradle.kts"
publish {
    publishMode = PublishMode.Auto
    // github { ... }
}
```

- `PublishMode.Never` — do not publish. The `latest-*.yml` metadata is still generated locally for
  every updatable format.
- `PublishMode.Auto` — publish when the build runs from a git tag.
- `PublishMode.Always` — publish on every build, tag or not.

The `publish { }` block writes electron-builder publisher settings; it does not upload anything by
itself. The actual upload runs in your CI workflow (`gh release create` for GitHub, `aws s3 cp` for
S3, your own copy step for generic). See [release CI](/docs/packaging/ci-cd#publish-the-release) for the standard
path.

## Submit to a desktop store

Store distribution goes through each vendor's portal rather than the `publish { }` block. Build the
store format, then upload the artifact:

- **Mac App Store** — submit the PKG via Transporter or `xcrun altool`. Provisioning profiles
  ([sandboxing](/docs/packaging/sandboxing)) and the store category (`appCategory`) are set at build
  time. Apple reviews the build; App Store builds are not notarized.
- **Microsoft Store** — upload the `.msixbundle` to [Partner Center](https://partner.microsoft.com/).
  The identity must match the reservation (`identityName`, `publisher = CN=<GUID>`,
  `publisherDisplayName`). See [Windows targets](/docs/packaging/windows#build-an-appx-or-msix-package).
- **Snapcraft** — run `snapcraft upload` from CI. The Snap Store accepts `strict` and `classic`
  confinement; `classic` requires approval. Set the grade with `linux.snap { grade = SnapGrade.Stable }`.
- **Flathub** — submit a manifest pull request to the [Flathub repo](https://github.com/flathub/flathub).
  Your `flatpak` block produces the bundle; Flathub builds from source via your manifest.
- **GitHub Releases / direct download** — the default path. Pair it with
  [auto-update](/docs/packaging/auto-update) for self-distributed apps.

## Reference

- `publish { publishMode = … }`
- `publish.github { enabled, owner, repo, token, channel, releaseType }`
- `publish.s3 { enabled, bucket, region, path, acl }`
- `publish.generic { enabled, url, channel, useMultipleRangeRequest }`
- `enum class PublishMode { Never, Auto, Always }`
- `enum class ReleaseChannel { Latest, Beta, Alpha }`
- `enum class ReleaseType { Release, Draft, Prerelease }`

See the [Gradle DSL reference](/docs/reference/gradle-dsl) for the full surface.

## What's next

- [Auto-update](/docs/packaging/auto-update) — how the published YAML drives in-app updates.
- [Release CI](/docs/packaging/ci-cd) — the workflow that builds, signs, and uploads.
- [Code signing](/docs/packaging/code-signing) — sign builds before you publish them.

---

# CI/CD

URL: https://nucleusframework.dev/en/docs/packaging/ci-cd

Build, sign, and publish a Nucleus desktop app across macOS, Windows, and Linux with the composite GitHub Actions shipped in the Nucleus repository.

In this tutorial, you'll set up a GitHub Actions release pipeline for a Nucleus desktop app.
You'll build installers on a per-OS, per-architecture matrix, merge the macOS builds into a
universal binary, bundle the Windows builds for the Microsoft Store, generate auto-update
metadata, and publish everything to a GitHub Release.

Nucleus ships seven composite actions in the [`NucleusFramework/Nucleus`](https://github.com/NucleusFramework/Nucleus)
repository. You reference them by path from your own workflow — there is nothing to copy into
your project.

## Before you start

- Your project is hosted on GitHub and applies the Nucleus Gradle plugin. See
  [Quickstart](/docs/start/quickstart).
- The release workflow needs `permissions: contents: write` to create releases and upload assets.
- Installers are not cross-compiled. Each OS/architecture must be built on a matching runner.

The composite actions are addressed as `NucleusFramework/Nucleus/.github/actions/<name>@<ref>`.
Use `@main` while experimenting and pin to a tag such as `@v2.5.18` for production runs.

## Reference an action

Add a step that points at an action in the Nucleus repository:

```yaml
- uses: NucleusFramework/Nucleus/.github/actions/setup-nucleus@main
```

The seven actions are:

| Action | What it does |
|--------|--------------|
| `setup-nucleus` | Installs a JDK (Microsoft Build of OpenJDK on Windows, Temurin elsewhere), Linux packaging tools, Gradle, and Node. |
| `setup-macos-signing` | Creates a temporary keychain and imports a `.p12` certificate for `codesign`. |
| `build-macos-universal` | Merges arm64 and x64 `.app` bundles with `lipo`, re-signs, and repackages as ZIP, DMG, and PKG. |
| `build-windows-appxbundle` | Combines amd64 and arm64 `.appx` files into a `.msixbundle` and signs it. |
| `generate-update-yml` | Computes SHA-512 hashes and emits the `latest-*.yml` metadata the auto-updater reads. |
| `publish-release` | Creates the GitHub Release with `gh release create` and uploads the installers and YAML. |
| `validate-release-ref` | Checks that a release tag was cut from the branch that owns it. |

## Build on every platform

Create `.github/workflows/release.yaml`. Trigger on version tags, run a matrix across the six
runners, set up the environment with `setup-nucleus`, package for the current OS, and upload the
result as an artifact:

```yaml title=".github/workflows/release.yaml"
name: Release
on:
  push:
    tags: ['v*']

permissions:
  contents: write

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - { os: ubuntu-latest,    arch: amd64 }
          - { os: ubuntu-24.04-arm, arch: arm64 }
          - { os: windows-latest,   arch: amd64 }
          - { os: windows-11-arm,   arch: arm64 }
          - { os: macos-latest,     arch: arm64 }
          - { os: macos-15-intel,   arch: amd64 }
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: NucleusFramework/Nucleus/.github/actions/setup-nucleus@main
        with:
          java-version: '25'
          packaging-tools: 'true'
          flatpak: 'true'
          snap: 'true'
      - run: ./gradlew packageReleaseDistributionForCurrentOS --stacktrace --no-daemon
      - uses: actions/upload-artifact@v4
        with:
          name: release-assets-${{ runner.os }}-${{ matrix.arch }}
          path: build/compose/binaries/main/**/*
```

Later jobs download these artifacts by their `release-assets-<os>-<arch>` names, so keep that
naming scheme.

## Set up the build environment

`setup-nucleus` provisions the whole toolchain in one step. On Linux with `packaging-tools: 'true'`
it installs `xvfb`, `rpm`, `fakeroot`, `libarchive-tools`, `libdbus-1-dev`, `libglib2.0-dev`,
`libx11-dev`, `libgtk-3-dev`, and `patchelf`, and starts a virtual display. It also sets up
Gradle with caching and installs Node for electron-builder.

Inputs:

| Input | Default | Purpose |
|-------|---------|---------|
| `java-version` | `25` | JDK used to run Gradle and bundled by jpackage. A bare LTS major resolves to the latest per-OS build. |
| `java-package` | `jdk` | JDK package variant (`jdk`, `jre`). |
| `packaging-tools` | `true` | Install the Linux packaging tools (Linux only). |
| `flatpak` | `false` | Install Flatpak and the Freedesktop Platform/SDK 24.08 (Linux only). |
| `snap` | `false` | Install snapd and Snapcraft (Linux only). |
| `graalvm` | `false` | Prepare a native-image build: native build tools (Xcode/MSVC) and the toolchain cache. |
| `graalvm-version` | `25i3` | Toolchain version — cache-key component only. Keep in sync with `graalvm { toolchain { } }`. |
| `graalvm-distribution` | `community` | Toolchain distribution — cache-key component only (`community` or `oracle`). |
| `setup-gradle` | `true` | Set up Gradle via `gradle/actions/setup-gradle`. |
| `setup-node` | `true` | Set up Node.js. |
| `node-version` | `24` | Node.js version. |

The Nucleus plugin downloads and caches the GraalVM JDK itself, so `graalvm: 'true'` never
installs a JDK. It only prepares what the plugin cannot: it selects Xcode 26 on macOS, sets up
MSVC on Windows via `ilammy/msvc-dev-cmd@v1`, and caches the toolchain directory. The two
`graalvm-*` inputs feed the cache key only — keep them in sync with your
`graalvm { toolchain { } }` block so switching distribution does not restore the wrong cache.

## Sign macOS builds

`setup-macos-signing` decodes a base64 `.p12`, imports it into a temporary keychain, and unlocks
it for `codesign`. It exposes the keychain path as an output that `build-macos-universal` consumes:

```yaml
- uses: NucleusFramework/Nucleus/.github/actions/setup-macos-signing@main
  id: signing
  with:
    certificate-base64: ${{ secrets.MAC_CERTIFICATES_P12 }}
    certificate-password: ${{ secrets.MAC_CERTIFICATES_PASSWORD }}
```

End-to-end macOS signing and notarization use these repository secrets:

| Secret | Purpose |
|--------|---------|
| `MAC_CERTIFICATES_P12` | Base64-encoded `.p12` bundle. |
| `MAC_CERTIFICATES_PASSWORD` | `.p12` password. |
| `MAC_DEVELOPER_ID_APPLICATION` | Developer ID Application identity (DMG/ZIP). |
| `MAC_APP_STORE_APPLICATION` | 3rd Party Mac Developer Application identity (sandboxed PKG). |
| `MAC_APP_STORE_INSTALLER` | 3rd Party Mac Developer Installer identity (PKG). |
| `MAC_PROVISIONING_PROFILE` | Base64 provisioning profile for the sandboxed app. |
| `MAC_RUNTIME_PROVISIONING_PROFILE` | Base64 provisioning profile for the JVM runtime. |
| `MAC_NOTARIZATION_APPLE_ID`, `MAC_NOTARIZATION_PASSWORD`, `MAC_NOTARIZATION_TEAM_ID` | `notarytool` credentials. |

Without the `MAC_*` secrets the pipeline falls back to ad-hoc signing — the same result as an
unsigned local build. See [Code signing](/docs/packaging/code-signing) for how to produce and
store each secret.

## Merge the universal macOS binary

`build-macos-universal` takes the per-architecture `.app` bundles, merges every Mach-O binary
with `lipo`, re-signs the result inside-out (`.dylib` and `.jnilib` files first with runtime
entitlements, then executables, then the runtime, then the bundle), and repackages a universal
ZIP, DMG, and PKG:

```yaml
- uses: NucleusFramework/Nucleus/.github/actions/build-macos-universal@main
  with:
    arm64-path: artifacts/release-assets-macOS-arm64
    x64-path: artifacts/release-assets-macOS-amd64
    output-path: artifacts/release-assets-macOS-universal
    signing-identity: ${{ secrets.MAC_DEVELOPER_ID_APPLICATION }}
    app-store-identity: ${{ secrets.MAC_APP_STORE_APPLICATION }}
    installer-identity: ${{ secrets.MAC_APP_STORE_INSTALLER }}
    keychain-path: ${{ steps.signing.outputs.keychain-path }}
```

Notarization runs as separate workflow steps with `xcrun notarytool submit --wait`. The DMG is
stapled; the ZIP is notarized but not stapled, so re-zipping never invalidates the blockmap the
[auto-updater](/docs/packaging/auto-update) relies on.

On **private** repositories, macOS runners bill at a 10× minute multiplier against your monthly
quota, and `--wait` keeps the runner active while it polls Apple's notarization service — you pay
for that idle time at the macOS rate. Public repositories are free. To cut costs on a private
repo, run the signing and notarization steps on a self-hosted macOS runner, which GitHub does not
bill for minutes.

## Bundle Windows for the Microsoft Store

`build-windows-appxbundle` combines the amd64 and arm64 `.appx` files into a single
`.msixbundle` with `MakeAppx`, then signs it with SignTool — one artifact for Store submission:

```yaml
- uses: NucleusFramework/Nucleus/.github/actions/build-windows-appxbundle@main
  with:
    amd64-path: artifacts/release-assets-Windows-amd64
    arm64-path: artifacts/release-assets-Windows-arm64
    output-path: artifacts/release-assets-Windows-bundle
```

## Generate auto-update metadata

`generate-update-yml` walks every downloaded installer, computes its SHA-512, and writes one YAML
file per platform. The channel determines the filename prefix — `latest`, `beta`, or `alpha` —
producing `<channel>-mac.yml`, `<channel>.yml` (Windows), and `<channel>-linux.yml`:

```yaml
- uses: NucleusFramework/Nucleus/.github/actions/generate-update-yml@main
  with:
    artifacts-path: artifacts
    version: ${{ env.VERSION }}
    channel: ${{ env.CHANNEL }}
```

## Publish the release

`publish-release` runs `gh release create` with the tag, uploads the installers and YAML, and
applies the release type. Pass `prerelease` to mark the release as a pre-release:

```yaml
- uses: NucleusFramework/Nucleus/.github/actions/publish-release@main
  with:
    artifacts-path: artifacts
    tag: ${{ env.TAG }}
    release-type: ${{ env.RELEASE_TYPE }}
```

## Use the reference workflow

The Nucleus repository ships a complete pipeline that wires all six actions together, at
[`.github/workflows/release-desktop.yaml`](https://github.com/NucleusFramework/Nucleus/blob/main/.github/workflows/release-desktop.yaml).
It builds the matrix, then fans out into a universal-macOS job and a Windows-bundle job before
publishing:

```mermaid
flowchart TB
    tag["Tag push v1.0.0"] --> build
    subgraph build ["Build (6 parallel runners)"]
      ubuntu["Ubuntu amd64 / arm64"]
      windows["Windows amd64 / arm64"]
      macos["macOS arm64 / x64"]
    end
    build --> macos_sign["Universal macOS + sign + notarize"]
    build --> msix["Windows MSIX bundle"]
    macos_sign --> publish["GitHub Release + update YML"]
    msix --> publish
```

That workflow marks a release as a pre-release when the version contains `-alpha` or `-beta`, and
selects the matching update channel. A separate `validate-release-ref` step enforces that
`v2.x.y-alpha`, `-beta`, and `-rc` tags point to a commit on the `nucleus-2.0` branch.

## What's next

- [Code signing](/docs/packaging/code-signing) — produce and store the macOS, Windows, and Linux signing secrets.
- [Publishing](/docs/packaging/publishing) — the `publish { }` DSL that drives GitHub, S3, and generic targets.
- [Auto-update](/docs/packaging/auto-update) — how the client consumes the generated `latest-*.yml` metadata.

---

# Compare

URL: https://nucleusframework.dev/en/docs/compare

How Nucleus compares with vanilla Compose Multiplatform — and, secondarily, with other desktop stacks.

Nucleus extends Compose Multiplatform for teams that already write Kotlin and need to **ship** a desktop
app — not just draw a window. The primary comparison is against **vanilla Compose Desktop**. Packaging
tools and web-based stacks sit further down the page for context.

## Nucleus vs vanilla Compose Multiplatform

Compose Multiplatform is the foundation. Nucleus is the production layer on top: native chrome, OS modules,
broader packaging, auto-update, and store pipelines. Migration is a [drop-in](/docs/migrate/from-jb-compose).

| | **Nucleus** | Vanilla CMP |
|--|------------|-------------|
| Language | Kotlin | Kotlin |
| UI | Compose + Skia GPU | Compose + Skia GPU |
| Window decorations | Native (Liquid Glass, Fluent, Yaru, Jewel) | Limited |
| OS APIs | 40+ Kotlin modules | Thin (`Tray`, `Notification`) |
| Packaging formats | **18** | 6 (jpackage) |
| Auto-update | Built-in (`updater-runtime`) | None |
| Store pipelines | PKG, MSIX, Snap, Flatpak (+ sandbox) | No dedicated path |
| Cold start | ~0.2 s (GraalVM) · ~1.0 s (JVM+AOT) | 1–2 s |
| Binary size | ~40 MB (GraalVM) · ~60 MB (JVM)* | 80–120 MB |
| Gradle shape | `nucleus.application { … }` (mirrors CMP) | `compose.desktop.application { … }` |

Full decision guide: [Nucleus vs vanilla Compose Multiplatform](/docs/compare/cmp-default).

### When to stay on vanilla CMP

- You only need DMG / MSI / DEB from jpackage.
- You do not need auto-update, store channels, GraalVM packaging, or native window decorations.
- You already own bespoke signing and upload scripts you do not want to displace.

### When to switch to Nucleus

- You want store-ready packaging (Mac App Store, Microsoft Store, Snapcraft, Flathub).
- You want auto-update, GraalVM Native Image, or JDK AOT cache wiring.
- You want native decorations and 40+ OS modules without writing JNI per platform.
- You already have a Compose Desktop project and want a [drop-in migration](/docs/migrate/from-jb-compose).

## Packaging tools (JVM ecosystem)

How Nucleus packaging compares with jpackage, Conveyor, install4j, and others — formats, auto-update,
signing, CI, stores:

→ [Packaging — Nucleus vs the rest](/docs/compare/packaging)

## Other desktop stacks (Electron, Tauri)

Electron and Tauri answer a different question: *how do I build desktop when my team is JavaScript?*
Nucleus answers: *how does my Kotlin team ship desktop on top of Compose?*

| | **Nucleus** | Electron | Tauri |
|--|------------|----------|-------|
| Language(s) | Kotlin | JS + Node (+ C++ for natives) | JS + Rust |
| UI tech | Compose + Skia GPU | Chromium (Blink + V8) | OS WebView |
| OS APIs | 40+ Kotlin modules, single process | Node native modules / IPC | Rust commands over IPC |
| Shared with mobile | Same Kotlin as Android / iOS | Web bundle | Web bundle |
| Packaging formats | **18** | 5–7 via electron-builder | 5 via tauri-bundler |
| Cold start | ~0.2 s (GraalVM) | 2–3 s | &lt; 1 s |
| RAM idle | 30–120 MB* | 200–500 MB | ~87 MB* |

Choose **Electron** when shipping speed and a JS hiring pool matter more than RAM or native feel.
Choose **Tauri** when you accept platform WebViews and a Rust/JS split for smaller binaries.
Choose **Nucleus** when the team is already Kotlin and you want Compose end-to-end with real OS and shipping tooling.

### Measured: startup, RAM, and process count

Same Hello-World window, four stacks, identical protocol on one Windows 11 machine — wall-clock from
process launch to first window handle, and **private working set** once the window settled.

| Hello-World | Stack | Cold start | Warm start | RAM (private WS) | Processes |
|--|--|--|--|--|--|
| **Nucleus (Tao)** | GraalVM native image | ~0.17 s | ~0.10 s | **~30 MB** | 1 |
| WinUI 3 | .NET 9 + Windows App SDK | ~0.20 s | ~0.28 s | ~32 MB | 1 |
| Flutter | Dart AOT + Skia | ~0.28 s | ~0.28 s | ~33 MB | 1 |
| Tauri | Rust + WebView2 | ~0.74 s | ~0.12 s | ~87 MB | 7 |

- **Task Manager under-reports WebView2 apps.** The Tauri process itself shows ~4 MB — the real footprint
  (~87 MB) lives in six `msedgewebview2.exe` helpers. Nucleus is a single process.
- **Nucleus lands in the same ~30 MB class as native WinUI 3 and Flutter** while staying pure
  Kotlin/Compose.

#### macOS

Same protocol on macOS 26 (Apple silicon) — wall-clock to first on-screen window, and total **RSS across
every process the app spawns**. RSS includes shared framework pages; compare within the table only.

| Hello-World | Stack | Cold start | Warm start | RAM (RSS, all processes) | Processes |
|--|--|--|--|--|--|
| **Nucleus (Tao)** | GraalVM native image | ~0.32 s | ~0.20 s | ~115 MB | 1 |
| SwiftUI | native reference | ~0.14 s | ~0.14 s | ~78 MB | 1 |
| Flutter | Dart AOT + Skia | ~0.79 s | ~0.17 s | ~100 MB | 1 |
| Tauri | Rust + WKWebView | ~0.91 s | ~0.19 s | ~173 MB | 4 |

## Notes

Performance numbers are typical for a Hello-World class app. Real-world cold start and RAM scale with
what your app loads. Nucleus has two runtime targets: GraalVM native image for cold start and binary
size, and JVM + AOT cache for throughput. See [performance](/docs/performance).

In the comparison tables, Electron figures are drawn from public benchmarks. Nucleus, WinUI 3, Tauri,
and related numbers — including Tauri RAM — were measured first-hand on a single Windows 11 machine
(warm runs unless noted); see the **Measured** section.
*Nucleus RAM was measured on Windows 11 with a Hello World build; binary size is the NSIS installer
with maximum compression.

## What's next

- [Nucleus vs vanilla Compose Multiplatform](/docs/compare/cmp-default) — what Nucleus adds on top of CMP.
- [Packaging — 18 formats vs the rest](/docs/compare/packaging) — packaging pipeline comparison.
- [Why Nucleus](/docs/why-nucleus) — product narrative for Kotlin teams.
- [Migrating from JetBrains Compose Desktop](/docs/migrate/from-jb-compose) — drop-in steps.

---

# Nucleus vs vanilla Compose Multiplatform

URL: https://nucleusframework.dev/en/docs/compare/cmp-default

What Nucleus adds on top of JetBrains Compose Desktop — the decision table for Kotlin teams shipping production desktop apps.

If you already write Kotlin and Compose, vanilla Compose Multiplatform is the default path to a
desktop window. Nucleus is what you add when that window has to look native, talk to the OS, and
ship to stores — without leaving the JetBrains plugin model.

Nucleus is a superset of the JetBrains `org.jetbrains.compose` Desktop packaging plugin. It keeps the same DSL shape and Gradle tasks, and adds a wider format catalog, packaging for store channels, and runtime libraries the official plugin does not ship. Migration is a [drop-in](/docs/migrate/from-jb-compose).

## What's the same

| | Nucleus | CMP default |
|--|---------|-------------|
| Compose UI runtime | Same | Same |
| Skia rendering | Same | Same |
| Gradle plugin shape | `nucleus { application { … } }` mirrors `compose.desktop.application { … }` | — |
| Hot reload | Works out of the box | Works out of the box |
| `compose.desktop.currentOs` dependency | Used | Used |

Migrating preserves your `mainClass`, `nativeDistributions { … }`, `buildTypes`, `modules`, and every existing Gradle task.

## What Nucleus adds

### Format catalog

| Format | CMP default | Nucleus |
|--------|:-----------:|:-------:|
| DMG, PKG, MSI, EXE, RawAppImage (jpackage), DEB, RPM | Y | Y |
| NSIS, NSIS Web | — | Y |
| MSIX / AppX | — | Y |
| Portable | — | Y |
| AppImage | — | Y |
| Pacman | — | Y |
| Snap | — | Y |
| Flatpak | — | Y |
| ZIP, TAR, 7Z | — | Y |

Eighteen formats against six. The plugin uses jpackage to build the app-image, then hands it to electron-builder's `--prepackaged` mode for everything else.

### Store pipeline

PKG, AppX, and Flatpak trigger a parallel [sandboxed pipeline](/docs/packaging/sandboxing) that pre-extracts JNI libs, signs each `.dylib`, injects sandbox-aware JVM args, and applies the right entitlements. The default CMP plugin has no notion of this.

### Auto-update

`updater-runtime` ships `latest-*.yml` metadata and a Kotlin client compatible with electron-builder's update format. See [auto-update](/docs/packaging/auto-update).

### GraalVM Native Image

The plugin can compile your Compose Desktop app to a GraalVM Native Image and package the resulting binary as DMG, NSIS, or DEB. Cold start is around 0.2 s and RAM around 30 MB (measured on Windows 11 with a Hello World build). The default CMP plugin does not handle Native Image.

### AOT cache

The JDK 25+ AOT cache is wired through the `enableAotCache = true` flag, with training and runtime modes detected via `nucleus.aot.mode`. See [AOT cache](/docs/performance/aot-cache).

### Code signing

Nucleus extends signing to Windows (PFX or Azure Artifact Signing) and adds the macOS inside-out signing pipeline for universal binaries via the `build-macos-universal` CI action.

### Deep links and file associations

`protocol("MyApp", "myapp")` and `fileAssociation(...)` propagate to NSIS, MSI, AppX, DEB/RPM `.desktop` files, and the macOS `Info.plist`. The default CMP plugin requires per-OS configuration.

### Runtime libraries

None of these ship with vanilla CMP:

- `core-runtime` — `NucleusApp`, `DeepLinkHandler`, `SingleInstanceManager`, `ExecutableRuntime`.
- `nucleus-application` — the `nucleusApplication { }` umbrella entry point, automatic single-instance, deep-link delivery, GraalVM init.
- Decorated windows — Liquid Glass / Fluent / Yaru / Jewel, on the Tao backend.
- OS toolkits — notifications, system tray, global hotkeys, media controls, taskbar progress, energy manager, system info, scheduler, autolaunch, native SSL, native HTTP, and more.

## What stays unchanged

- `mainClass`, `jvmArgs`, `modules()` / `includeAllModules`.
- `buildTypes` / ProGuard.
- The `compose.desktop.currentOs` dependency.
- Existing Gradle tasks (`run`, `packageDmg`, `packageDeb`, …).
- Compose Hot Reload — Nucleus auto-propagates `nucleus.application.mainClass` to `compose.desktop.application.mainClass`, so `hotRun` and `hotSnapshotMain` work without extra config.

## Set homepage for DEB packages

Unlike jpackage, electron-builder requires `homepage` for DEB. Set it on `nativeDistributions`:

```kotlin title="build.gradle.kts"
nativeDistributions {
    homepage = "https://myapp.example.com"
}
```

Without `homepage`, `packageDeb` and `packageGraalvmDeb` fail with `Please specify project homepage`.

## When to stay on vanilla CMP

- You only need DMG/MSI/DEB and you're satisfied with jpackage as the back end.
- You don't need auto-update, GraalVM, store distribution, or native window decorations.
- Your build pipeline already has bespoke signing and upload scripts you don't want to displace.

## When to switch to Nucleus

- You want packaging for store channels (Mac App Store PKG, Microsoft Store MSIX, Snapcraft, Flathub).
- You want auto-update or GraalVM Native Image.
- You want native window decorations with the Tao backend's multi-touch, pen, and native Wayland support.
- You want the 40+ OS integration modules without building them yourself.

## What's next

- [Migrating from JetBrains Compose Desktop](/docs/migrate/from-jb-compose) — the step-by-step migration.
- [Sandboxing](/docs/packaging/sandboxing) — the store distribution pipeline.
- [Auto-update](/docs/packaging/auto-update) — updater metadata and the Kotlin client.
- [AOT cache](/docs/performance/aot-cache) — JDK 25+ AOT cache wiring.

---

# Packaging — Nucleus vs the rest

URL: https://nucleusframework.dev/en/docs/compare/packaging

How Nucleus compares with jpackage, Compose Multiplatform, Conveyor, install4j, and other JVM packaging tools across formats, auto-update, signing, CI, and store distribution.

This page compares Nucleus packaging with the other tools that build native installers
for JVM desktop apps: jpackage, Compose Multiplatform, Conveyor, install4j, jDeploy, and
JavaPackager. It covers distributable formats, auto-update, code signing, CI/CD, GraalVM
Native Image, and store distribution.

Nucleus builds 18 distributable formats and packages auto-update, signing, sandboxing,
CI actions, and GraalVM Native Image output in one Gradle plugin under an Apache/MIT
license. jpackage covers six formats and nothing around them, install4j is proprietary,
and Conveyor covers a different set but does not produce DMG or PKG.

## Format coverage

| Tool | DMG | PKG | NSIS | MSI | MSIX/AppX | Portable | DEB | RPM | AppImage | Snap | Flatpak | Archives | Total |
|------|:---:|:---:|:----:|:---:|:---------:|:--------:|:---:|:---:|:--------:|:----:|:-------:|:--------:|:-----:|
| **Nucleus** | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | ZIP, TAR, 7Z | **18** |
| Conveyor | — | — | — | — | Y | — | Y | — | — | — | — | ZIP, TAR + custom EXE | 6 |
| install4j | Y | — | — | Y | — | — | Y | Y | — | — | — | TAR, shell | 7 |
| jpackage | Y | Y | — | Y | — | — | Y | Y | — | — | — | — | 6 |
| jDeploy | — | — | — | — | — | — | Y | — | — | — | — | EXE, TAR | 4 |
| Compose MP | Y | Y | — | Y | — | — | Y | Y | — | — | — | — | 6 |
| JavaPackager | Y | Y | — | Y | — | — | Y | Y | Y | — | — | ZIP | 8 |

Nucleus reaches the higher format count by combining two build steps: jpackage builds the
app-image, then electron-builder's `--prepackaged` mode produces every installer flavor from
it — including the formats jpackage does not support, such as NSIS, MSIX, Snap, Flatpak, and
AppImage. This hybrid build path is specific to Nucleus in the JVM ecosystem.

Nucleus's total also counts four formats not broken out as their own columns above: `Exe`
(a jpackage-native Windows installer, distinct from NSIS), `Pacman` (Arch Linux), `NsisWeb`
(a web-installer variant of NSIS), and `RawAppImage` (the intermediate jpackage app-image,
also selectable directly as a `targetFormats` entry).

## Auto-update

| Tool | Runtime lib | Channels | Verification |
|------|-------------|----------|--------------|
| **Nucleus** | `NucleusUpdater` | 3 (latest/beta/alpha) | SHA-512 |
| Conveyor | OS-native (Sparkle 2 / MSIX / apt) | Yes | Yes |
| install4j | Updater API | Yes | Yes |
| jDeploy | Built-in | No | No |
| jpackage / Compose MP | None | — | — |

Both Nucleus and Conveyor support delta updates. Nucleus (from 2.3) does differential
downloads: it matches electron-builder block maps of the new artifact against a cached copy
of the previous one, copies unchanged blocks from disk, and fetches the rest with HTTP range
requests — jumps such as 1.0 → 1.7 are differential too, with no pairwise delta files ever
produced. Conveyor ships delta updates via Sparkle 2 (about 31 KB on macOS). Nucleus also
exposes a runtime API for progress flow, channel switching, post-update detection, and
restart-on-update.

## Code signing and notarization

Every compared tool signs and notarizes macOS builds. Windows signing differs:

- **Nucleus** — `.pfx` and Azure Artifact Signing.
- **Conveyor** — the widest set of signing backends: Azure Key Vault, AWS KMS, SSL.com
  eSigner, DigiCert ONE, Google Cloud KMS, and SafeNet/YubiKey HSMs.
- **install4j** — `.pfx` only.
- **jpackage** — macOS only.

## CI/CD integration

- **Nucleus** — six composite GitHub Actions: `setup-nucleus`, `setup-macos-signing`,
  `build-macos-universal`, `build-windows-appxbundle`, `generate-update-yml`, and
  `publish-release`.
- **Conveyor** — examples only; single-machine builds.
- **install4j** — CLI only.
- **jpackage / Compose MP** — none.

## GraalVM Native Image packaging

Nucleus packages GraalVM Native Image output end to end, producing DMG, NSIS, and DEB for the
resulting binary. A packaged binary starts in about 0.2 s, uses about 30 MB of RAM (measured
on Windows 11 with a Hello World build), and is about 40 MB in size as an NSIS installer with
maximum compression. See [performance / GraalVM](/docs/performance/graalvm). Other tools route
Native Image binaries through generic packaging pipelines that do not account for the JDK-less
output.

## Store distribution

Nucleus, Conveyor, and Compose Multiplatform each produce store-acceptable artifacts. Nucleus
produces all four store formats from one DSL: PKG (Mac App Store), AppX/MSIX (Microsoft Store),
Snap (Snap Store), and Flatpak (Flathub).

## Trade-offs

| Where Nucleus is strong | Where competitors win |
|-------------------------|----------------------|
| Most formats. Auto-update, signing, and CI in one plugin. Built-in GraalVM Native Image packaging. Apache 2 / MIT. | Conveyor: broader HSM signing, single-machine builds. install4j: stable, paid, long-running support. jpackage: no new dependency. |

Nucleus builds each OS on its own CI runner — there is no cross-compilation. It is Gradle-only
and younger than Conveyor and install4j.

## When to pick what

- A small CLI or single-window app that needs the widest HSM signing backends and single-machine builds — **Conveyor**.
- An enterprise installer with custom dialogs and paid support — **install4j**.
- A DMG, MSI, or DEB straight from jpackage — **Compose Multiplatform** or **jpackage** directly.
- One Kotlin codebase covering every format and store, with auto-update, AOT, and GraalVM —
  **Nucleus**.

## What's next

- [Auto-update](/docs/packaging/auto-update) — configure `NucleusUpdater` and release channels.
- [Code signing](/docs/packaging/code-signing) — sign and notarize builds per OS.
- [CI/CD](/docs/packaging/ci-cd) — the composite GitHub Actions for building and publishing.
- [GraalVM Native Image](/docs/performance/graalvm) — package a JDK-less native binary.

---

# Thirty years of mature libraries, native to your app

URL: https://nucleusframework.dev/en/docs/ecosystem

Nucleus apps run on the JVM, so any library on Maven Central is a Gradle dependency away; this page groups the common desktop choices by task.

Nucleus apps run on the JVM, so your code shares a process and a heap with any library published to Maven Central. There is no foreign-function bridge, no out-of-process daemon, and no per-platform native build to maintain: a library is one `implementation` line in `build.gradle.kts`. This page groups the libraries you are most likely to reach for on the desktop, by task.

## AI and machine learning

Run inference locally, call remote models, or embed an LLM in the app.

- **DJL** — Deep Java Library, multi-engine model serving.
- **ONNX Runtime Java** — ONNX inference.
- **LangChain4j** — agent, RAG, and tool-use scaffolding.
- **llama.cpp** via FFM bindings — local LLM inference.
- **TensorFlow Java** — the JVM port of TensorFlow.

## Search and indexing

Lucene is the engine behind Elasticsearch, Solr, and OpenSearch. You can embed it directly instead of running a separate service.

- **Apache Lucene** — embedded full-text search.
- **OpenSearch client**, **Elasticsearch client** — connect to clusters.
- **Tantivy** via JNI — Rust full-text engine.
- **Quickwit** — cloud-native search.

## Data and analytics

Columnar, in-process, and distributed engines are all available on the JVM.

- **Apache Arrow** — columnar in-memory format.
- **DuckDB JDBC** — embedded OLAP.
- **Apache Parquet** — on-disk columnar format.
- **jOOQ** — type-safe SQL builder.
- **Apache Spark** — in-process for medium-sized data.

## Documents and parsing

Parse files that users drag into the app without shelling out to native binaries.

- **Apache Tika** — 1000+ formats.
- **Apache PDFBox** — PDF read and write.
- **Apache POI** — Office documents.
- **Jsoup** — HTML parsing.
- **commonmark-java** — Markdown.

## Imaging and vision

Image processing and computer vision run in the same process as your Compose UI.

- **BoofCV** — computer vision in Java.
- **JavaCV** — OpenCV bindings.
- **TwelveMonkeys** — 40+ image formats.
- **Skia** — GPU 2D rendering, already present in the Compose process.
- **FFmpeg** via JavaCV — video.

## Networking and RPC

HTTP clients and servers, RPC frameworks, and real-time media are all on the JVM.

- **Netty** — asynchronous I/O.
- **Ktor** — Kotlin HTTP client and server.
- **gRPC Java** — RPC framework.
- **OkHttp** — HTTP client.
- **WebRTC Java** — real-time media.

For HTTP specifically, Nucleus provides the [`native-ssl`](/docs/performance/native-ssl) and [`native-http`](/docs/performance/native-http) modules, which wire the operating system's trust store into any client (`java.net.http`, OkHttp, Ktor). Corporate proxies and user-installed certificate authorities are picked up without extra configuration.

## The rest of Maven Central

Every other artifact on Maven Central — roughly 500,000 libraries — is available on the same terms: one Gradle dependency line, the same as your test framework. No FFI bridge, no native compilation, and no per-OS maintainers.

## Where Nucleus stops

One common desktop need has no Nucleus module, because an existing library already covers it:

- [File dialogs](/docs/ecosystem/file-dialog) — use FileKit.

The Nucleus Gradle plugin ships GraalVM reachability metadata for FileKit, so it works under Native Image with no manual configuration.

## What's next

- [File dialogs](/docs/ecosystem/file-dialog) — native open and save dialogs through FileKit.
- [Spell check](/docs/os/spell-check) — the system spell checker, with Compose context-menu integration.
- [`native-ssl`](/docs/performance/native-ssl) — route HTTPS trust through the OS trust store.
- [`native-http`](/docs/performance/native-http) — use the OS-managed HTTP stack.

---

# Native file dialogs

URL: https://nucleusframework.dev/en/docs/ecosystem/file-dialog

Use FileKit for native open, save, and folder pickers, with GraalVM metadata bundled by the Nucleus plugin.

Compose Multiplatform doesn't include file dialogs, and Nucleus doesn't add its own. Use [FileKit](https://github.com/vinceglb/FileKit) for native open, save, and folder pickers. The Nucleus Gradle plugin ships GraalVM reachability metadata for FileKit, so the pickers run under `native-image` without extra configuration.

## Add the dependency

```kotlin title="build.gradle.kts"
dependencies {
    implementation("io.github.vinceglb:filekit-compose:<version>")
}
```

## Show a file picker

Create a launcher with `rememberFilePickerLauncher` and call `launch()` from a click handler:

```kotlin
val launcher = rememberFilePickerLauncher(
    type = PickerType.File(extensions = listOf("png", "jpg")),
    title = "Pick an image",
) { file ->
    // file: PlatformFile?
}

Button(onClick = { launcher.launch() }) {
    Text("Pick image")
}
```

The callback receives a `PlatformFile?`, which is null when the user cancels. `PlatformFile` is FileKit's cross-platform file handle, with read, write, and metadata helpers.

## How it works

FileKit calls the native dialog on each operating system:

- **macOS** — `NSOpenPanel` and `NSSavePanel` through Cocoa.
- **Windows** — `IFileOpenDialog` and `IFileSaveDialog` through JNA COM.
- **Linux** — the xdg-desktop-portal `FileChooser`, with GTK and zenity fallbacks.

It supports type filters with descriptions; single-file, multi-file, folder, and save modes; and a Compose API (`rememberFilePickerLauncher`) built around the `PlatformFile` handle.

## Parent a dialog to the Tao window

From 2.3.1, Tao exposes the platform identities FileKit and native dialogs need so pickers
attach to your window instead of floating independently:

| Platform | API | Value |
|----------|-----|-------|
| Linux X11 / XWayland | `TaoWindow.x11PortalParent` or `xdgPortalParent()` | `x11:<lowercase-hex-xid>` |
| Linux Wayland | `TaoWindow.xdgPortalParent()` / `exportXdgForeignHandle()` | `wayland:<xdg_foreign token>` |
| macOS | `TaoWindow.nsWindowHandle` | owning `NSWindow*` (not the Compose `NSView*`) |
| Windows | `TaoWindow.nativeHandle` | `HWND` |

```kotlin
// Prefer the backend-agnostic helper on Linux:
val parent = window.xdgPortalParent()
// X11 → XdgPortalParent.X11(xid); Wayland → XdgPortalParent.Wayland(export)
// Keep a Wayland export open until the portal dialog completes, then close it.
(parent as? AutoCloseable)?.close()

// macOS sheet parent (once FileKit accepts an NSWindow parent):
// window.nsWindowHandle?.let { FileKitDialogParent.macos(it) }
```

On Wayland, `exportXdgForeignHandle()` / `XdgPortalParent.Wayland` wraps an
`XdgForeignExport` that must stay open for the lifetime of any portal dialog that borrows
its handle. A raw `wl_surface*` or the Compose `NSView*` is not a valid portal / sheet parent.

## Run under GraalVM native image

The Nucleus Gradle plugin bundles reachability metadata for FileKit as part of its [library metadata bundle](/docs/performance/graalvm/automatic-metadata). The metadata is included only when `io.github.vinceglb.filekit` is on the runtime classpath, and covers:

- macOS Foundation proxy and callback types (`FoundationLibrary`, `ID`, runnable callbacks).
- Windows JNA COM bindings (`FileDialog`, `FileOpenDialog`, `FileSaveDialog`, `ShellItem`, `Shell32`, `COMDLG_FILTERSPEC`, `PROPERTYKEY`).
- The Linux xdg-desktop-portal D-Bus proxy (`FileChooserDbusInterface`).

When you build with the Nucleus plugin and target `native-image`, the dialogs run without a manual `reachability-metadata.json` or a tracing-agent pass.

## Notes

FileKit already wraps each native dialog and integrates with Compose state, so Nucleus depends on it instead of reimplementing the same surface.

## What's next

- [Automatic GraalVM metadata](/docs/performance/graalvm/automatic-metadata) — how the plugin bundles reachability metadata for known libraries.
- [Spell check](/docs/os/spell-check) — the platform spell-check engines, in Compose text fields.
- [Ecosystem overview](/docs/ecosystem) — libraries that pair with Nucleus.

---

# Migrate with an AI agent

URL: https://nucleusframework.dev/en/docs/migrate/ai-agent

Point any AI coding agent at one URL and it analyzes your app, asks the right questions, and migrates it to Nucleus step by step.

The fastest way to migrate an existing JetBrains Compose Desktop app is to let an AI coding
agent do it, guided by our migration playbook. Nothing to install: the whole playbook —
detection script, API references, checkpoints — lives in a single file your agent fetches.

## One prompt, that's all

Open your agent (Claude Code, Cursor, Codex, …) inside the app you want to migrate and paste:

```text
Fetch https://nucleusframework.dev/nucleus-migrate.md and follow its instructions to
analyze this app and migrate it to Nucleus step by step.
```

## What the agent does

1. **Scans your project** with a bundled detector: AWT/Swing usage (file dialogs, tray,
   clipboard, `SwingPanel`…), custom title bars, Material 2/3/Jewel, notifications, hand-rolled
   updaters and single-instance locks, JNA, packaging formats (MSI…), GraalVM feasibility
   signals, and your CI workflows.
2. **Interviews you**: Tao or AWT backend, design system for the window chrome, which native
   features to adopt (notifications, tray, auto-update, deep links, taskbar progress…),
   MSI→NSIS, GraalVM now or later, CI migration.
3. **Migrates one phase at a time** — Gradle DSL, window shell, AWT removal, feature adoption,
   packaging, GraalVM, CI — each phase ending with a verifiable checkpoint (`./gradlew run`,
   a visual check, a packaged installer) before moving on.
4. **Reports** what changed, what was deliberately kept, and what to do next.

The playbook encodes the DSL renames, threading rules, and the costliest gotchas learned from
real-world migrations (overload ambiguity on `NucleusApplicationScope`, theme-wraps-window,
`HostedWindow` for library code, Linux `Desktop.browse` deadlocks…), all verified against the
plugin and runtime sources.

## Claude Code users: install it as a skill (optional)

The same playbook is packaged as a reusable skill with progressive loading (the agent only
reads the reference it needs per phase). Download
[nucleus-migrate.skill](https://nucleusframework.dev/nucleus-migrate.skill), then unzip it into
your skills directory:

```bash
cd ~/.claude/skills && unzip ~/Downloads/nucleus-migrate.skill
```

From any project, run `/nucleus-migrate` — or just say "migrate this app to Nucleus" and the
skill triggers itself.

## Prefer doing it by hand?

Follow the manual guides: [build migration from JetBrains Compose Desktop](/docs/migrate/from-jb-compose)
and, coming from Nucleus 1.x, the [1.x to 2.0 guide](/docs/migrate/from-1.x).

---

# Migrating from JetBrains Compose Desktop

URL: https://nucleusframework.dev/en/docs/migrate/from-jb-compose

Add Nucleus to an existing JetBrains Compose Desktop project and move its build configuration to the Nucleus DSL.

In this tutorial, you'll migrate a project that uses the JetBrains Compose Desktop plugin to
Nucleus. Nucleus extends `org.jetbrains.compose` rather than replacing it, so your existing
configuration keeps working: you add the Nucleus plugin alongside it, move the application block
to the Nucleus DSL, and optionally enable the packaging and runtime features Nucleus adds.

An AI coding agent can run this whole migration for you — including the window-shell and
AWT-removal work this build-focused guide doesn't cover. One prompt, zero install:
[Migrate with an AI agent](/docs/migrate/ai-agent).

## Before you start

You need an existing project that applies the `org.jetbrains.compose` plugin and builds with
JDK 17 or later.

## Add the plugin

Apply the Nucleus plugin next to the JetBrains Compose plugin. Do not remove the JetBrains plugin —
Nucleus extends it.

```diff
 plugins {
     id("org.jetbrains.kotlin.jvm") version "2.4.10"
     id("org.jetbrains.kotlin.plugin.compose") version "2.4.10"
     id("org.jetbrains.compose") version "1.12.0"
+    id("dev.nucleusframework") version "<version>"
 }
```

## Update the imports

Replace the JetBrains Compose DSL imports with the Nucleus equivalents:

```diff
-import org.jetbrains.compose.desktop.application.dsl.TargetFormat
+import dev.nucleusframework.desktop.application.dsl.TargetFormat
```

The same applies to `CompressionLevel`, `SigningAlgorithm`, and the other DSL types.

## Move to the Nucleus DSL

Rename the `compose.desktop.application { }` block to `nucleus.application { }`. Every setting
inside it stays the same:

```diff
-compose.desktop.application {
+nucleus.application {
     mainClass = "com.example.MainKt"

     nativeDistributions {
         targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
         packageName = "MyApp"
         packageVersion = "1.0.0"

         macOS {
             bundleID = "com.example.myapp"
             iconFile.set(project.file("icons/app.icns"))
         }

         windows {
             iconFile.set(project.file("icons/app.ico"))
         }

         linux {
             iconFile.set(project.file("icons/app.png"))
         }
     }
 }
```

Nucleus propagates `nucleus.application.mainClass` to `compose.desktop.application.mainClass`, so
[Compose Hot Reload](https://kotlinlang.org/docs/multiplatform/compose-hot-reload.html) tasks
(`hotRun`, `hotSnapshotMain`) resolve the entry point without extra configuration. On macOS with
`decorated-window-tao`, `-XstartOnFirstThread` is injected into Hot Reload's `JavaExec` tasks
automatically.

## Enable Nucleus features

The following settings are opt-in. Add the ones you need:

```kotlin
nucleus.application {
    mainClass = "com.example.MainKt"

    nativeDistributions {
        targetFormats(
            TargetFormat.Dmg, TargetFormat.Nsis, TargetFormat.Deb,
            TargetFormat.AppImage, TargetFormat.Snap, TargetFormat.Flatpak, // new
        )
        packageName = "MyApp"
        packageVersion = "1.0.0"
        homepage = "https://myapp.example.com" // required for DEB

        cleanupNativeLibs = true
        enableAotCache = true
        splashImage = "splash.png"
        compressionLevel = CompressionLevel.Maximum
        artifactName = "\${name}-\${version}-\${os}-\${arch}.\${ext}"

        // Deep links
        protocol("MyApp", "myapp")

        // File associations
        fileAssociation(
            mimeType = "application/x-myapp",
            extension = "myapp",
            description = "MyApp Document",
        )

        // Publishing
        publish {
            github { enabled = true; owner = "myorg"; repo = "myapp" }
        }

        // NSIS customization
        windows {
            nsis {
                oneClick = false
                allowToChangeInstallationDirectory = true
                createDesktopShortcut = true
            }
        }
    }
}
```

## Add the runtime libraries

The runtime libraries are also opt-in. Add the ones matching the features you enabled:

```kotlin
dependencies {
    implementation(compose.desktop.currentOs)

    implementation("dev.nucleusframework:nucleus.core-runtime:<version>")
    implementation("dev.nucleusframework:nucleus.aot-runtime:<version>")           // if enableAotCache
    implementation("dev.nucleusframework:nucleus.updater-runtime:<version>")       // if publishing
    implementation("dev.nucleusframework:nucleus.taskbar-progress:<version>")
    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")   // for nucleusApplication { }
}
```

To use the unified `nucleusApplication { }` entry point with single-instance handling, deep links,
and AOT wiring, see the [Nucleus 1.x to 2.0 guide](/docs/migrate/from-1.x). The same
`application { } → nucleusApplication { }` swap applies whether you come from 1.x or vanilla
Compose Multiplatform.

## Set the homepage for DEB packages

Nucleus packages with electron-builder rather than jpackage, and electron-builder requires
`homepage` for DEB. Without it, the build fails:

```
Please specify project homepage, see https://electron.build/configuration
```

Set it on `nativeDistributions`:

```kotlin
nativeDistributions {
    homepage = "https://myapp.example.com"
}
```

This also applies to GraalVM Native Image DEB packaging (`packageGraalvmDeb`).

## What changes

| Feature | Before (compose) | After (nucleus) |
|---------|------------------|-----------------|
| DSL entry point | `compose.desktop.application` | `nucleus.application` |
| DSL imports | `org.jetbrains.compose.desktop.application.dsl.*` | `dev.nucleusframework.desktop.application.dsl.*` |
| Target formats | DMG, PKG, MSI, EXE, DEB, RPM | + NSIS, AppX, Portable, AppImage, Snap, Flatpak, archives |
| Native lib cleanup | Manual | `cleanupNativeLibs = true` |
| AOT cache | Not available | `enableAotCache = true` |
| Splash screen | Manual | `splashImage = "splash.png"` |
| Deep links | Manual, per-OS | `protocol("name", "scheme")` |
| File associations | Limited | Cross-platform `fileAssociation()` |
| NSIS config | Not available | Full `nsis { }` DSL |
| AppX config | Not available | Full `appx { }` DSL |
| Snap config | Not available | Full `snap { }` DSL |
| Flatpak config | Not available | Full `flatpak { }` DSL |
| Store pipeline | Not available | Sandboxed pipeline for PKG, AppX, Flatpak |
| Auto-update | Not available | Built-in with YAML metadata |
| Code signing | macOS only | + Windows PFX / Azure Artifact Signing |
| DMG appearance | Not customizable | Full `dmg { }` DSL ([details](/docs/packaging/macos#package-a-dmg)) |
| Artifact naming | Fixed | Template with `artifactName` |

## What stays the same

- `mainClass`, `jvmArgs`.
- The `nativeDistributions` block (metadata, icons, resources).
- `buildTypes` / ProGuard.
- `modules()` / `includeAllModules`.
- All existing Gradle tasks (`run`, `packageDmg`, `packageDeb`, and so on).
- The `compose.desktop.currentOs` dependency.
- Source set configuration.
- [Compose Hot Reload](https://kotlinlang.org/docs/multiplatform/compose-hot-reload.html) — works without extra configuration.

## What's next

- [Windowing](/docs/window) and [Tao](/docs/tao) — native window decorations and the Tao backend.
- [Auto-update](/docs/packaging/auto-update) — ship updates with YAML metadata.
- [GraalVM](/docs/performance/graalvm) — GraalVM Native Image packaging.
- [From 1.x](/docs/migrate/from-1.x) — migrate a full 1.x codebase with the same plugin swap.

---

# Migrating from Nucleus 1.x to 2.0

URL: https://nucleusframework.dev/en/docs/migrate/from-1.x

Port a Nucleus 1.x desktop app to 2.0 by renaming the project namespace and moving bootstrap into nucleusApplication.

In this tutorial, you'll migrate a Nucleus 1.x desktop app to 2.0. Nucleus 2.0 uses a single
entry point, `nucleusApplication`, and moves the project namespace to `dev.nucleusframework`.
The migration is mostly mechanical: rename the namespace, then move your `application { }` block
into `nucleusApplication(args) { }`, which removes about 30 lines of bootstrap from a typical `main()`.

## Before you start

Nucleus 2.0 needs two build changes before you touch any application code.

### Set the JDK toolchain to 25 (only if you use Jewel)

The core 2.0 artifacts — `core-runtime`, `nucleus-application`, `decorated-window-core`,
`decorated-window-material3`, `decorated-window-tao` — target a JDK 17 baseline. The **Jewel** stack
is the exception: `decorated-window-jewel` and the IntelliJ platform libraries it pulls are
published for **JDK 25**. So the toolchain bump is a Jewel requirement, not a blanket Nucleus one.

If your app uses `JewelDecoratedWindow` / `JewelDecoratedDialog`, set the toolchain on **every**
module that pulls the Jewel stack:

```kotlin title="build.gradle.kts"
kotlin { jvmToolchain(25) }
```

The failing module is where Jewel is on the classpath — often a shared UI module, not just the
desktop app. In a Kotlin Multiplatform project the `jvm()` target defaults to your Gradle JDK
(commonly 21), so set the toolchain in the `shared` module too:

```kotlin title="shared/build.gradle.kts"
kotlin {
    jvmToolchain(25)     // the jvm() target needs it; the Android target keeps its own bytecode level
    // ...
}
```

Skip this and dependency resolution fails with (the version is whatever toolchain you're on today —
often 21): `Dependency resolution is looking for a library compatible with JVM runtime version 21,
but 'dev.nucleusframework:nucleus.decorated-window-jewel' is only compatible with JVM runtime
version 25 or newer.`

If you don't use Jewel, you can stay on your current toolchain (JDK 17 or newer).

### Add the IntelliJ snapshots repository

Nucleus 2.x pulls Jewel `0.39.1-262.9437.29`, which lives only in the IntelliJ snapshots
repository. Add it to `settings.gradle.kts`:

```kotlin title="settings.gradle.kts"
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://www.jetbrains.com/intellij-repository/releases")
        maven("https://www.jetbrains.com/intellij-repository/snapshots") // new
    }
}
```

If you declare Jewel directly, pin it to the same coordinate Nucleus brings in transitively:

```toml
intellijIcons = "262.9437.16"
jewel        = "0.39.1-262.9437.29"
```

## What changed in 2.0

| Area | 1.x | 2.0 |
|---|---|---|
| Plugin ID | `io.github.kdroidfilter.nucleus` | `dev.nucleusframework` |
| Maven group | `io.github.kdroidfilter` | `dev.nucleusframework` |
| Kotlin package root | `io.github.kdroidfilter.nucleus.*` | `dev.nucleusframework.*` |
| Entry point | `application { }` | `nucleusApplication(args) { }` |
| Window | `Window(...)` | `DecoratedWindow(...)` |
| GraalVM bootstrap | Manual `GraalVmInitializer.initialize()` | Automatic |
| Single instance | Manual `SingleInstanceManager.isSingleInstance(...)` | Automatic |
| Restore on second launch | Manual `LaunchedEffect` + `toFront()` | Automatic |
| AOT training timer | Manual `Thread` + `exitProcess` | `aotTraining(duration = ...)` |
| AutoLaunch cache prime | Manual | Automatic |
| Windows AUMID | Manual | Automatic |

## Update the plugin ID and Maven coordinates

Change the plugin ID and version:

```diff
 plugins {
-    id("io.github.kdroidfilter.nucleus") version "1.3.0"
+    id("dev.nucleusframework") version "<version>"
 }
```

Update the dependency coordinates:

```diff
 dependencies {
-    implementation("io.github.kdroidfilter:nucleus.core-runtime:1.3.0")
-    implementation("io.github.kdroidfilter:nucleus.nucleus-application:1.3.0")
+    implementation("dev.nucleusframework:nucleus.core-runtime:<version>")
+    implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")
 }
```

Update any Gradle DSL imports:

```diff
-import io.github.kdroidfilter.nucleus.desktop.application.dsl.TargetFormat
+import dev.nucleusframework.desktop.application.dsl.TargetFormat
```

## Rename the Kotlin imports

Run a project-wide find and replace:

```
io.github.kdroidfilter.nucleus  →  dev.nucleusframework
```

No classes are renamed — only the package prefix changes.

## Switch to nucleusApplication

In 1.x you wrapped Compose Desktop's `application { }` in Nucleus init helpers. In 2.0,
`nucleusApplication` runs the bootstrap in the correct order and exposes a unified
`NucleusApplicationScope`.

### Before: main() in 1.x

```kotlin
fun main(args: Array<String>) {
    GraalVmInitializer.initialize()
    AutoLaunch.wasStartedAtLogin(args)
    if (Platform.Current == Platform.Windows) {
        WindowsJumpListManager.setProcessAppId()
    }

    if (AotRuntime.isTraining()) {
        Thread({ Thread.sleep(45_000); exitProcess(0) }, "aot-timer")
            .apply { isDaemon = false }.start()
    }

    application {
        val isFirstInstance = remember {
            SingleInstanceManager.isSingleInstance(
                onRestoreFileCreated = { DeepLinkHandler.writeUriTo(this) },
                onRestoreRequest = { /* hand-rolled restore state */ },
            )
        }
        if (!isFirstInstance) { exitApplication(); return@application }

        DeepLinkHandler.register(args) { uri -> handleDeepLink(uri) }

        Window(onCloseRequest = ::exitApplication, title = "My App") { App() }
    }
}
```

### After: main() in 2.0

```kotlin
import dev.nucleusframework.application.nucleusApplication
import dev.nucleusframework.application.aotTraining
import kotlin.time.Duration.Companion.seconds

fun main(args: Array<String>) = nucleusApplication(args) {
    aotTraining(duration = 45.seconds)

    onDeepLink { uri -> handleDeepLink(uri) }

    MaterialDecoratedWindow(onCloseRequest = ::exitApplication, title = "My App") {
        App()
    }
}
```

### Keep early exits above nucleusApplication

`nucleusApplication` runs the full bootstrap: GraalVM init, the single-instance lock, and the
Compose loop. For invocation modes that must bypass all of that — a desktop scheduler re-launch
or a boot receiver — keep the check above the call:

```kotlin
fun main(args: Array<String>) {
    if (DesktopBootReceiver.isSchedulerInvocation(args)) {
        DesktopBootReceiver.handle(args, registry = MyTaskRegistry.registry)
        exitProcess(0)
    }

    nucleusApplication(args) { /* ... */ }
}
```

Putting these checks inside the scope acquires the single-instance lock first — the opposite of
what you want for a bypass path.

### What nucleusApplication runs, in order

1. `GraalVmInitializer.initialize()` — fonts, charsets, HiDPI, `java.home`.
2. The AOT training timer, when `-Dnucleus.aot.mode=training` is set and you call `aotTraining(…)`.
3. The single-instance lock. A second instance relays its CLI deep link to the primary and exits with code 0.
4. Platform priming: the `AutoLaunch.wasStartedAtLogin(args)` cache is warmed, and on Windows
   `WindowsJumpListManager.setProcessAppId()` runs before any window. Both are reflective — they
   fire only if the modules are on the classpath.
5. Backend resolution: `NucleusBackend.Auto` picks AWT or Tao.
6. The Compose application loop.

**Don't initialize COM on the main thread before `nucleusApplication` (Tao / Windows).** The Tao
backend runs the Win32 message loop as a single-threaded COM apartment (STA) on the main thread.
If something already put that thread into a multithreaded apartment (MTA) — a common culprit is
calling `WindowsNotificationCenter.initialize()` yourself in `main()` — Tao's `OleInitialize` fails
and the process aborts natively:

```
thread '<unnamed>' panicked at tao/.../windows/window.rs:
OleInitialize failed! Result was: `RPC_E_CHANGED_MODE`.
```

The bootstrap already primes the AUMID and notification center on the right thread, so drop the
manual call in the GUI path. If a headless bypass path (a scheduler invocation) still needs it,
keep that call there — it has no Tao window to conflict with.

## Replace Window with DecoratedWindow

Pick the variant that matches your design system:

| Composable | Module |
|---|---|
| `DecoratedWindow(…)` | `nucleus.decorated-window-core` |
| `MaterialDecoratedWindow(…)` | `nucleus.decorated-window-material3` |
| `JewelDecoratedWindow(…)` | `nucleus.decorated-window-jewel` |

All three expose `nucleusWindow` inside their content — a backend-agnostic handle for `show()`,
`toFront()`, `setMinimized()`, and similar calls.

### Window composables are extension functions now

This is the most common breakage. In 1.x, `JewelDecoratedWindow` was a plain `@Composable`. In
2.0 it is an extension on `NucleusApplicationScope`:

```kotlin
fun NucleusApplicationScope.JewelDecoratedWindow(
    onCloseRequest: () -> Unit, ...,
    content: @Composable NucleusDecoratedWindowScope.() -> Unit,
)
```

Any wrapper composable you wrote in 1.x must become an extension on the same scope:

```diff
 @Composable
-fun MyOnboardingWindow(vmFactory: ViewModelFactory) {
+fun NucleusApplicationScope.MyOnboardingWindow(vmFactory: ViewModelFactory) {
     JewelDecoratedWindow(onCloseRequest = {}, title = "...") { /* ... */ }
 }
```

The call site inside `nucleusApplication { … }` does not change — the receiver is implicit.

### Dialogs follow the same rule

| Receiver | Backend support |
|---|---|
| `JewelDecoratedDialog(…)` (no receiver) | AWT only. Its implementation module isn't on the Tao classpath, so it fails at render with `ClassNotFoundException: dev.nucleusframework.window.DecoratedDialogKt`. |
| `NucleusApplicationScope.JewelDecoratedDialog(…)` | Backend-agnostic. Dispatches to AWT or Tao. |

Both overloads exist, so the plain call still **compiles** — it only fails at runtime on Tao. Use
the scoped variant for anything composed inside `nucleusApplication { … }`.

The catch: dialogs are usually opened deep in your UI tree (an event editor, a settings sheet),
far from the `NucleusApplicationScope` receiver. Rather than thread the scope through every
signature, expose it with a `CompositionLocal`:

```kotlin
// 1. Declare it once.
val LocalNucleusApplicationScope = staticCompositionLocalOf<NucleusApplicationScope> {
    error("LocalNucleusApplicationScope not provided")
}

fun main(args: Array<String>) = nucleusApplication(args) {
    val nucleusScope = this
    JewelDecoratedWindow(onCloseRequest = ::exitApplication, title = "My App") {
        // 2. Provide it inside the window content.
        CompositionLocalProvider(LocalNucleusApplicationScope provides nucleusScope) {
            App()
        }
    }
}

// 3. Read it at the dialog call site. The explicit receiver also disambiguates the two overloads.
@Composable
fun SettingsDialog(/* ... */) {
    LocalNucleusApplicationScope.current.JewelDecoratedDialog(onCloseRequest = { /* ... */ }) {
        // JewelDialogTitleBar and other DecoratedDialogScope extensions work here:
        // NucleusDecoratedDialogScope extends DecoratedDialogScope.
    }
}
```

### CompositionLocals propagate across the Tao scene

The Tao backend opens a fresh `ComposeScene` per window and dialog. As of 2.0, the full parent
`CompositionLocalContext` is bridged automatically, so you no longer need to wrap content twice:

```kotlin
// Before — needed on Tao
IntUiTheme(theme, styling) {
    JewelDecoratedWindow(...) {
        IntUiTheme(theme, styling) { /* duplicate */ }
    }
}

// After — a single wrap is enough on every backend
IntUiTheme(theme, styling) {
    JewelDecoratedWindow(...) { /* content */ }
}
```

## Remove the manual single-instance block

Single instance is automatic in 2.0. Delete the 1.x manual block:

```diff
-val isFirstInstance = remember {
-    SingleInstanceManager.isSingleInstance(...)
-}
-if (!isFirstInstance) { exitApplication(); return@application }
```

The primary instance restores its `DecoratedWindow` (`show()` + `setMinimized(false)` +
`toFront()` + `requestFocus()`) on every second launch. The secondary instance's CLI deep link is
delivered to the primary through `onDeepLink { }`, then it exits with code 0.

Opt out for editor-style apps that allow multiple windows:

```kotlin
nucleusApplication(args, enableSingleInstance = false) { /* ... */ }
```

## Move AOT training into aotTraining

```diff
-if (AotRuntime.isTraining()) {
-    Thread({ Thread.sleep(45_000); exitProcess(0) }, "aot-timer")
-        .apply { isDaemon = false }.start()
-}

 nucleusApplication(args) {
+    aotTraining(duration = 45.seconds)
+
+    if (isAotTraining) {
+        preloadNavigationScreens()
+        preloadFontsAndImages()
+    }
 }
```

`aotTraining` is a no-op outside training mode. The scope also exposes `aotMode`, `isAotTraining`,
and `isAotRuntime`. See [AOT cache](/docs/performance/aot-cache).

## Register deep links with onDeepLink

```diff
-DeepLinkHandler.register(args) { uri -> handleDeepLink(uri) }
+onDeepLink { uri -> handleDeepLink(uri) }
```

URIs delivered before the handler is registered are buffered and replayed. `DeepLinkHandler`
remains public for low-level work.

## Drop the explicit GraalVmInitializer call

```diff
-GraalVmInitializer.initialize()
-application { /* ... */ }
+nucleusApplication(args) { /* ... */ }
```

It runs as the first bootstrap step now.

## Review the final result

```kotlin
fun main(args: Array<String>) = nucleusApplication(args) {
    remember {
        AutoLaunch.wasStartedAtLogin(args)
        if (Platform.Current == Platform.Windows) {
            WindowsJumpListManager.setProcessAppId()
        }
        true
    }

    aotTraining(duration = 45.seconds)
    onDeepLink { uri -> handleDeepLink(uri) }

    MaterialDecoratedWindow(onCloseRequest = ::exitApplication, title = "My App") {
        App()
    }
}
```

No ordered init list, no `SingleInstanceManager` plumbing, and no restore counter with a
`LaunchedEffect` to bring the window back.

## Troubleshooting

- **Imports won't resolve after the rename.** Search for `io.github.kdroidfilter.nucleus` — anything
  left is stale. Replace it with `dev.nucleusframework`.
- **`nucleusApplication` is unresolved.** Add `implementation("dev.nucleusframework:nucleus.nucleus-application:<version>")`.
- **The window doesn't restore on second launch with a plain `Window`.** That behavior lives in
  `DecoratedWindow`. Switch to a `DecoratedWindow` variant.
- **`Unresolved reference 'JewelDecoratedWindow'`.** The composable became a scope extension.
  Propagate the receiver — see [Replace Window with DecoratedWindow](#replace-window-with-decoratedwindow).
- **`ClassNotFoundException: …DecoratedDialogKt` at render on Tao.** You're calling the AWT-only
  dialog (it compiles, but its impl module isn't on the Tao classpath). Use
  `NucleusApplicationScope.JewelDecoratedDialog` — see [Dialogs follow the same rule](#dialogs-follow-the-same-rule).
- **Native abort `OleInitialize failed! RPC_E_CHANGED_MODE` / exit code `0xC0000409` on Windows.**
  Something initialized COM in MTA on the main thread before Tao. Don't call
  `WindowsNotificationCenter.initialize()` (or other COM setup) in the GUI `main()` path — the
  bootstrap handles it. See the callout in [What nucleusApplication runs, in order](#what-nucleusapplication-runs-in-order).
- **`Could not find org.jetbrains.jewel:jewel-foundation:0.37.…`** The IntelliJ snapshots repository
  is missing. See [Before you start](#before-you-start).
- **`Dependency resolution is looking for a library compatible with JVM runtime version 21`ish.** A
  module that pulls the Jewel stack isn't on the JDK 25 toolchain (check shared/UI modules and the
  KMP `jvm()` target). See [Set the JDK toolchain to 25](#set-the-jdk-toolchain-to-25-only-if-you-use-jewel).

## What's next

- [Quickstart](/docs/start/quickstart) — build and run a Nucleus app from scratch with the 2.0 DSL.
- [Configuration](/docs/start/configuration) — the full `nucleus { }` DSL.
- [AOT cache](/docs/performance/aot-cache) — how `aotTraining` primes startup.
- [Backends](/docs/concepts/backends) — how `NucleusBackend.Auto` chooses AWT or Tao.

---

# Gradle DSL reference

URL: https://nucleusframework.dev/en/docs/reference/gradle-dsl

Every property and sub-block of the nucleus { } Gradle extension, verified against the plugin source.

The Nucleus Gradle plugin (`id("dev.nucleusframework")`) exposes a single top-level extension, `nucleus`, for configuring packaging, signing, publishing, and GraalVM native builds from Kotlin. It builds on the JetBrains Compose Desktop DSL and adds Nucleus-specific formats, signing surfaces, and GraalVM settings. This page lists every property in the order it appears in the plugin source.

## Top-level: `nucleus { }`

`dev.nucleusframework.NucleusExtension`:

- `val application: JvmApplication` — JVM app configuration (`nucleus { application { … } }`).
- `val nativeApplication: NativeApplication` — Kotlin/Native macOS targets.
- `val dependencies: NucleusPlugin.Dependencies` — runtime module coordinates and notations.

## `application { }` — `JvmApplication`

- `from(SourceSet)` / `from(KotlinTarget)`
- `disableDefaultConfiguration()`
- `dependsOn(vararg tasks: Task | String)`
- `fromFiles(vararg files: Any)`
- `var mainClass: String?`
- `val mainJar: RegularFileProperty`
- `var javaHome: String`
- `val args: MutableList<String>` / `args(vararg args: String)`
- `val jvmArgs: MutableList<String>` / `jvmArgs(vararg jvmArgs: String)` — Nucleus adds `--enable-native-access=ALL-UNNAMED` to the defaults (run task and packaged launcher) for JDK 24+ (JEP 472)
- `var garbageCollector: GarbageCollector?` — HotSpot collector for the JVM distribution (`SERIAL`, `PARALLEL`, `G1`, `Z`, `SHENANDOAH`, `EPSILON`). Unset keeps JDK ergonomics. Flags are prepended so an explicit `-XX:+Use…GC` in `jvmArgs` still wins.
- `val nativeDistributions: JvmApplicationDistributions` — see below
- `val buildTypes: JvmApplicationBuildTypes`
- `val graalvm: GraalvmSettings` — see [GraalVM](#graalvm--graalvmsettings)

## `nativeDistributions { }` — `JvmApplicationDistributions`

| Property | Type | Notes |
|----------|------|-------|
| `modules: ArrayList<String>` | — | Defaults: `java.base, java.desktop, java.logging, java.net.http, jdk.accessibility, jdk.crypto.ec` |
| `var includeAllModules: Boolean` | — | Bundle every JDK module |
| `var cleanupNativeLibs: Boolean` | — | Strip non-target native libs |
| `var splashImage: String?` | — | Splash image path |
| `var enableAotCache: Boolean` | — | JDK 25+ AOT cache |
| `var artifactName: String` | default `"${name}-${version}-${os}-${arch}.${ext}"` | Output template |
| `var compressionLevel: CompressionLevel?` | — | Default for electron-builder packages: `Store`, `Normal`, `Maximum`, `Ultra`. Overridden per format by `linux.appImage.compressionLevel` and `windows.portable.compressionLevel` when set. Prefer `Normal`/`Store` for AppImage. |
| `val trustedCertificates: ConfigurableFileCollection` | — | CA certificates → bundled JDK `cacerts` (see [trusted certs](/docs/packaging/trusted-certificates)) |
| `val protocols: MutableList<UrlProtocol>` | — | Deep-link protocols |
| `targetFormats: …` | inherited | The 18 [target formats](#targetformat-enum) |
| `val linux: LinuxPlatformSettings` | — | See [Linux](#linux--linuxplatformsettings) |
| `val macOS: JvmMacOSPlatformSettings` | — | See [macOS](#macos--jvmmacosplatformsettings) |
| `val windows: WindowsPlatformSettings` | — | See [Windows](#windows--windowsplatformsettings) |
| `val publish: PublishSettings` | — | See [publish](#publish--publishsettings) |
| `val aotCache: AotCacheSettings` | — | JVM AOT cache settings; also `aotCache { }` |
| `val sandboxing: SandboxingSettings` | — | Sandbox settings such as `keepNativeLibsInJars`; also `sandboxing { }` |
| `fun signing(Action<UnifiedSigningSettings>)` | — | One block that configures signing for all three OSes |

Methods:

- `fun fileAssociation(mimeType, extension, description, linuxIconFile?, windowsIconFile?, macOSIconFile?)`
- `fun protocol(name, vararg schemes)`
- Common (from `AbstractPlatformSettings`): `iconFile`, `packageVersion`, `fileAssociation(...)`

### `TargetFormat` enum

18 formats, in source order:

`RawAppImage`, `Pkg`, `Deb`, `Rpm`, `Dmg`, `Exe`, `Msi`, `Nsis`, `NsisWeb`, `Portable`, `AppX`, `AppImage`, `Pacman`, `Snap`, `Flatpak`, `Zip`, `Tar`, `SevenZ`.

`RawAppImage` is the intermediate jpackage app-image; every other format is produced by electron-builder. `Pkg`, `AppX`, and `Flatpak` are store formats and require sandboxing.

## `macOS { }` — `JvmMacOSPlatformSettings`

Extends `AbstractMacOSPlatformSettings`. Identification:

- `packageName: String?`, `bundleName: String?`, `packageVersion`, `packageBuildVersion`
  — `bundleName` names the `.app` directory across DMG/ZIP/PKG/app-image/GraalVM, defaulting to `appName` then `packageName`
- `dmgPackageVersion`, `dmgPackageBuildVersion`, `pkgPackageVersion`, `pkgPackageBuildVersion`
- `dockName: String?`, `setDockNameSameAsPackageName: Boolean = true`
- `bundleID: String?`, `appCategory: String?`, `minimumSystemVersion: String?`
- `installationPath: String? = null` — macOS install location; when unset the build defaults it to `/Applications`
- `iconFile`, `layeredIconDir` (macOS 26+ `.icon` directory)

Signing and sandbox:

- `entitlementsFile: RegularFileProperty`, `runtimeEntitlementsFile`
- `provisioningProfile: RegularFileProperty`, `runtimeProvisioningProfile`
- `signing { … }` — see [Signing](#macos--signing--macossigningsettings)
- `notarization { … }` — see [Notarization](#macos--notarization--macosnotarizationsettings)

macOS 26:

- `macOsSdkVersion: String? = "26.0"` — `vtool` patches the launcher Mach-O `LC_BUILD_VERSION` to gate Liquid Glass at SDK 26.

Composition:

- `launchAgents { agent(plistName) { bundleProgram; arguments; startInterval } }`
- `infoPlist { extraKeysRawXml }`
- `dmg { … }` — see [DMG](#macos--dmg--dmgsettings)

### `macOS.signing { }` — `MacOSSigningSettings`
- `sign: Property<Boolean>` (default `false`)
- `identity: Property<String>`
- `keychain: Property<String>`
- `prefix: Property<String>`

### `macOS.notarization { }` — `MacOSNotarizationSettings`
Three mutually exclusive modes:

- Apple ID: `appleID`, `password`, `teamID`
- `notarytool` keychain profile: `keychainProfile`, optional `keychainPath`
- App Store Connect API key: `apiKey`, `apiKeyId`, `apiIssuer`

### `macOS.dmg { }` — `DmgSettings`
- `title: String?`, `iconSize: Int?`, `iconTextSize: Int?`
- `format: DmgFormat?` (`UDRW`, `UDRO`, `UDCO`, `UDZO`, `UDBZ`, `ULFO`)
- `size: String?`, `shrink: Boolean?`, `sign: Boolean`
- `background: RegularFileProperty`, `backgroundColor: String?`
- `icon: RegularFileProperty`, `badgeIcon: RegularFileProperty`
- `window { x; y; width; height }`
- `content(x, y, type: DmgContentType?, name: String?, path: String?)` — `DmgContentType` is `File`, `Link`, `Dir`

## `windows { }` — `WindowsPlatformSettings`

- `iconFile`, `packageName`
- `console: Boolean`, `dirChooser: Boolean`
- `perUserInstall: Boolean` — **deprecated**; inverted vs electron-builder (`true` ≡ per-user). Prefer `msi { perMachine }` / `nsis { perMachine }`. Still applied when `msi.perMachine` is unset.
- `shortcut`, `menu`, `menuGroup`
- `upgradeUuid: String?`, `msiPackageVersion`, `exePackageVersion`
- `nsis { … }` — see [NSIS](#windows--nsis--nsissettings)
- `msi { … }` — see [MSI](#windows--msi--msisettings)
- `appx { … }` — see [AppX](#windows--appx--appxsettings)
- `portable { … }` — see [Portable](#windows--portable--portablesettings)
- `signing { … }` — see [Signing](#windows--signing--windowssigningsettings)

### `windows.portable { }` — `PortableSettings`
- `compressionLevel: CompressionLevel?` — overrides root `nativeDistributions.compressionLevel` for the portable EXE only

### `windows.msi { }` — `MsiSettings`
- `perMachine: Boolean` — install per-machine (Program Files, all users). Default `true`. Maps 1:1 to electron-builder `msi.perMachine`.
- `oneClick: Boolean` — skip the wizard. Default `true`. Set `false` for an assisted installer.
- `runAfterFinish: Boolean` — launch the app when the installer finishes. Default `true`.
- `createDesktopShortcut: Boolean` — default `true`.
- `createStartMenuShortcut: Boolean` — default `true`.
- `menuCategory: String?` — start-menu submenu (and Program Files subdirectory). Default `null`; when unset, `windows.menuGroup` is used.
- `shortcutName: String?` — shortcut label. Defaults to the application name.

### `windows.nsis { }` — `NsisSettings`
- `oneClick: Boolean`
- `allowElevation: Boolean`, `perMachine: Boolean`
- `allowToChangeInstallationDirectory: Boolean`
- `createDesktopShortcut: Boolean`, `createStartMenuShortcut: Boolean`
- `menuCategory: String?` — start-menu submenu (and Program Files subdirectory). Default `null`; when unset, `windows.menuGroup` is used.
- `shortcutName: String?` — shortcut label. Defaults to the application name.
- `runAfterFinish: Boolean`, `deleteAppDataOnUninstall: Boolean`
- `multiLanguageInstaller: Boolean`, `installerLanguages: List<String>`
- `installerIcon`, `uninstallerIcon`, `installerHeader`, `installerSidebar`
- `license`, `script`, `includeScript`

### `windows.appx { }` — `AppXSettings`
- `applicationId`, `publisherDisplayName`, `displayName`, `publisher`, `identityName`
- `languages: List<String>`
- `backgroundColor: String?`, `showNameOnTiles: Boolean`
- `storeLogo`, `square44x44Logo`, `square150x150Logo`, `wide310x150Logo`
- `minVersion: String?`, `maxVersionTested: String?`
- `addAutoLaunchExtension: Boolean`, `setBuildNumber: Boolean`

### `windows.signing { }` — `WindowsSigningSettings`
- `enabled: Boolean`
- `certificateFile`, `certificatePassword`, `certificateSha1`, `certificateSubjectName`
- `algorithm: SigningAlgorithm` (`Sha1`, `Sha256`, `Sha512`)
- `timestampServer: String?`
- Azure Artifact Signing: `publisherName`, `azureTenantId`, `azureEndpoint`, `azureCertificateProfileName`, `azureCodeSigningAccountName`

## `linux { }` — `LinuxPlatformSettings`

- `iconFile`, `shortcut: Boolean`, `packageName`, `packageVersion`
- `appRelease: String?`, `appCategory: String?`, `menuGroup: String?`
- `startupWMClass: String?`
- `debMaintainer: String?`, `debPackageVersion`, `debDepends: List<String>`
- `rpmLicenseType: String?`, `rpmPackageVersion`, `rpmRequires: List<String>`
- `pacmanPackageVersion: String?`, `pacmanDepends: List<String>` — for the `Pacman` (Arch Linux) target
- `afterInstall: RegularFileProperty`, `afterRemove: RegularFileProperty` — concatenated after Nucleus's template, then electron-builder. Macros (`${executable}`, `${sanitizedProductName}`) substitute **only when single-quoted**. Deb / Rpm / Pacman only. See [install and remove scripts](/docs/packaging/linux#add-install-and-remove-scripts)
- `beforeInstall: RegularFileProperty`, `beforeRemove: RegularFileProperty` — passed raw to fpm (`--before-install` / `--before-remove`); no electron-builder macro substitution. Not called on a Pacman upgrade — use `afterUpgrade` / `beforeUpgrade`
- `afterUpgrade: RegularFileProperty`, `beforeUpgrade: RegularFileProperty` — passed raw to fpm (`--after-upgrade` / `--before-upgrade`); no macro substitution. Pacman only: the only hooks that run when Pacman upgrades an installed package. Deb / Rpm ignore them
- `appImage { … }` — see [AppImage](#linux--appimage--appimagesettings)
- `snap { … }` — see [Snap](#linux--snap--snapsettings)
- `flatpak { … }` — see [Flatpak](#linux--flatpak--flatpaksettings)
- `signing { … }` — see [Signing](#linux--signing--linuxsigningsettings)

### `linux.signing { }` — `LinuxSigningSettings`
GPG-signs DEB/RPM for distribution outside a store. See [Code signing](/docs/packaging/code-signing#sign-on-linux).
- `enabled: Property<Boolean>` (default `false`)
- `keyId: Property<String>` — GPG key id, fingerprint or email
- `keyFile: RegularFileProperty` — ASCII-armored private key, imported into a throwaway keyring (optional if the key is already in the signing keyring)
- `passphrase: Property<String>`
- `debMethod: DebSignMethod` (default `Detached`; also `DpkgSig`, `Debsig`)
- `silentUpdate: Property<Boolean>` (default `false`) — passwordless signature-verified self-update; requires `enabled`. See [passwordless updates](/docs/packaging/auto-update#set-up-passwordless-updates-on-linux).

Defaults read from `compose.desktop.linux.sign` and `compose.desktop.linux.signing.{keyId,keyFile,passphrase,silentUpdate}`.

### `linux.appImage { }` — `AppImageSettings`
- `category: AppImageCategory?` (`AudioVideo`, `Development`, `Education`, `Game`, `Graphics`, `Network`, `Office`, `Science`, `Settings`, `System`, `Utility`)
- `genericName: String?`, `synopsis: String?`
- `desktopEntries: Map<String, String>`
- `compressionLevel: CompressionLevel?` — overrides root `nativeDistributions.compressionLevel` for AppImage only; prefer `Normal` or `Store` (FUSE cold start)

### `linux.snap { }` — `SnapSettings`
- `confinement: SnapConfinement` (default `Strict`; also `Classic`, `Devmode`)
- `grade: SnapGrade` (default `Stable`; also `Devel`)
- `summary: String?`, `base: String?`
- `plugs: List<SnapPlug>` — 11 defaults
- `autoStart: Boolean`
- `compression: SnapCompression?` (`Xz`, `Lzo`)

`SnapPlug`: `Desktop`, `DesktopLegacy`, `Home`, `X11`, `Wayland`, `Unity7`, `BrowserSupport`, `Network`, `NetworkBind`, `Gsettings`, `AudioPlayback`, `AudioRecord`, `Opengl`, `RemovableMedia`, `Cups`.

### `linux.flatpak { }` — `FlatpakSettings`
- `runtime: String = "org.freedesktop.Platform"`
- `runtimeVersion: String = "23.08"` — note: the `setup-nucleus` CI action installs the Freedesktop Platform/SDK **24.08**; set `runtimeVersion = "24.08"` when building Flatpaks in CI
- `sdk: String = "org.freedesktop.Sdk"`
- `branch: String = "master"`
- `finishArgs: List<String>` — defaults: `--share=ipc`, `--socket=x11`, `--socket=wayland`, `--socket=pulseaudio`, `--device=dri`
- `license: RegularFileProperty`

## `publish { }` — `PublishSettings`

- `publishMode: PublishMode` (`Never`, `Auto`, `Always`)
- `github { enabled, owner, repo, token, channel, releaseType }`
- `s3 { enabled, bucket, region, path, acl }`
- `generic { enabled, url, channel, useMultipleRangeRequest }`

`ReleaseChannel`: `Latest`, `Beta`, `Alpha`.
`ReleaseType`: `Release`, `Draft`, `Prerelease`.

## GraalVM — `GraalvmSettings`

- `isEnabled: Property<Boolean>` (default `false`)
- `headless: Property<Boolean>` (default `false`) — daemons/CLIs: skip L3 AWT/Java2D platform metadata, always-on L1 GUI packs, and companion GUI native libs; bake `-Djava.awt.headless=true`. See [Build a headless image](/docs/performance/graalvm/configuration#build-a-headless-image)
- `imageName: Property<String>`
- `march: Property<NativeImageMarch>` — `NATIVE` / `COMPATIBILITY`; unset defaults per-platform (`COMPATIBILITY`, or `NATIVE` on Apple-Silicon macOS)
- `optimization: Property<NativeImageOptimization>` — `QUICK_BUILD`, `NONE`, `LEVEL_1`..`LEVEL_3`, `SIZE`; unset keeps `-O2`
- `allCharsets: Property<Boolean>` (default `false`)
- `mlProfileInference: Property<Boolean>` (default `true`) — `false` only emits `-H:-MLProfileInference` on Oracle toolchains; Community skips with a warning
- `advancedObfuscation: Property<Boolean>` (default `false`) — Oracle GraalVM only
- `autoIncludeResources: Property<Boolean>` (default `true`) — include the project's own resources in the image
- `maxHeapSizePercent: Property<Int>` (default `25`) — follows the selected collector (`MaximumHeapSizePercent` or `MaxRAMPercentage` under G1)
- `maxHeapSize: Property<String>` — absolute max heap (e.g. `"2g"`); takes precedence over percent
- `garbageCollector: Property<NativeImageGarbageCollector>` — `SERIAL` / `G1` / `EPSILON`; unset keeps Serial. `G1` is Oracle GraalVM + Linux only
- `exactReachabilityMetadata: Property<ExactReachabilityMetadata>` (default `APP_PACKAGES`) — `--exact-reachability-metadata` on `runGraalvmNative` only; `OFF` / `APP_PACKAGES` / `packages(...)`
- `detectOrphanProjectClasses: Property<Boolean>` (default `true`) — register public no-arg `<init>` for naming-convention reflective types
- `reflectionForProjectClasses: Property<Boolean>` (default `false`) — opt-in: every project class with a public no-arg constructor
- `buildArgs: ListProperty<String>` — SLF4J is **not** forced to build-time init; add `--initialize-at-build-time=org.slf4j` yourself if needed
- `javaLanguageVersion: Property<Int>` (default `25`) — only when `toolchain.autoDownload = false`
- `jvmVendor: Property<JvmVendorSpec>` — only when `toolchain.autoDownload = false`
- `nativeImageConfigBaseDir: DirectoryProperty`
- `val toolchain: GraalvmToolchainSettings`:
  - `autoDownload: Property<Boolean> = true`
  - `distribution: Property<GraalvmDistribution> = COMMUNITY` — `COMMUNITY` / `ORACLE`; `ORACLE` logs a GFTC licensing warning
  - `channel: Property<GraalvmChannel> = INNOVATION` — `INNOVATION` (defaults to `25i3` / GraalVM 25.3 from 2.5.1) / `LTS`
  - `version: Property<String>` — overrides `channel` (`"25i3"`, `"25"`, `"25.0.1"`, …)
  - `macosIntelFallback: Property<Boolean> = true`
  - `installDir: DirectoryProperty` — default `<gradle-user-home>/nucleus/graalvm`
- `val pgo: GraalvmPgoSettings` — Oracle GraalVM only; `runWithPgoInstrument` is not registered under `COMMUNITY`:
  - `enabled: Property<Boolean> = true`
  - `profile: RegularFileProperty` — default `graalvm/pgo/default.iprof`
- `val macOS: GraalvmMacOSSettings` — `cStubsSrc`, `minimumSystemVersion = "12.0"`, `macOsSdkVersion = "26.0"`
- `val windows: GraalvmWindowsSettings`:
  - `bundleCRuntime: Property<Boolean> = true` — copy the MSVC runtime DLLs next to the native `.exe`
  - `dlls: ListProperty<String>` — defaults: `vcruntime140.dll`, `vcruntime140_1.dll`, `msvcp140.dll`
  - `sourceDir: DirectoryProperty` — directory the DLLs are copied from (defaults to the GraalVM toolchain `bin`)
- `val metadataRepository: MetadataRepositorySettings`:
  - `enabled: Boolean = true`
  - `version: String = "1.1.4"`
  - `excludedModules: SetProperty<String>`
  - `moduleToConfigVersion: MapProperty<String, String>`

## Native app — `NativeApplication`

Currently macOS Kotlin/Native only.

- `targets(vararg targets: KotlinTarget)` — must be `KotlinNativeTarget` on `Family.OSX`
- `val distributions: NativeApplicationDistributions`

## Annotations

- `@ExperimentalNucleusLibrary` — opt-in marker for unstable plugin DSL surface.

## Other types
- `class FileAssociation(mimeType, extension, description, iconFile?)`
- `class UrlProtocol(name, schemes: List<String>)`
- `class LaunchAgentSettings`
- `class JvmApplicationBuildTypes`
- `class ProguardSettings`
- `enum class CompressionLevel` — `Store`, `Normal`, `Maximum`, `Ultra`
- `enum class GraalvmChannel` — `INNOVATION` (`25i3`), `LTS`
- `enum class GraalvmDistribution` — `COMMUNITY`, `ORACLE`
- `class ExactReachabilityMetadata` — `OFF`, `APP_PACKAGES`, `packages(...)`
- `enum class NativeImageMarch` — `NATIVE`, `COMPATIBILITY`
- `enum class NativeImageOptimization` — `QUICK_BUILD`, `NONE`, `LEVEL_1`, `LEVEL_2`, `LEVEL_3`, `SIZE`
- `enum class SigningAlgorithm`
- `enum class ReleaseType`, `enum class ReleaseChannel`, `enum class PublishMode`
- `enum class SnapGrade`, `enum class SnapConfinement`, `enum class SnapCompression`
- `enum class AppImageCategory`
- `enum class DmgFormat`, `enum class DmgContentType`

## Notes

The plugin injects a `nucleus/nucleus-app.properties` resource into the packaged app containing `app.id`, `app.version`, `app.vendor`, `app.aumid`, `startup.task.id`, and similar keys. The `NucleusApp` runtime object reads these at startup, which is how the DSL configuration reaches the runtime library.

## What's next

- [Configuration](/docs/start/configuration) — the `nucleus { }` DSL in a working build script.
- [Packaging formats](/docs/packaging) — what each `TargetFormat` produces.
- [Code signing](/docs/packaging/code-signing) — the macOS, Windows, and Linux signing blocks.
- [Publishing](/docs/packaging/publishing) — the `publish { }` block and release channels.

---

# Troubleshooting

URL: https://nucleusframework.dev/en/docs/reference/troubleshooting

Common build, packaging, signing, and runtime problems in Nucleus, with the cause and fix for each.

This page lists recurring problems when building, packaging, signing, and shipping a
Nucleus app. Entries are grouped by area, and each one states the symptom, the cause, and
the fix.

## macOS signing and notarization

### Notarization fails: "does not include a secure timestamp"

**Symptom.** `xcrun notarytool submit` returns `Invalid` with a status detail about a
missing or invalid timestamp.

**Cause.** Code signing ran without `--timestamp`, or the machine could not reach Apple's
timestamp server at sign time.

**Fix.** Nucleus signs with `--options runtime --timestamp` by default. If you added a
custom `codesign` step (for example, to sign `lipo`-merged universal binaries outside the
`build-macos-universal` action), pass `--timestamp` and re-sign. Verify with
`codesign -dv --verbose=4 <Your.app>` and check for a `Timestamp=` entry.

### Notarization fails: "does not include a hardened runtime"

**Symptom.** `Status: Invalid`, with the log referencing the hardened runtime.

**Cause.** A custom `codesign` step is missing `--options runtime`.

**Fix.** Add `--options runtime` to every `codesign` invocation. The default Nucleus
pipeline already does this, so only custom CI scripts hit this error.

### Notarization fails: "code object is not signed at all"

**Symptom.** `packageGraalvmDmg` (or `notarizeGraalvmDmg`) with
`compose.desktop.mac.sign=true` aborts with
`code object is not signed at all` in subcomponent
`<App>.app/Contents/MacOS/.nucleus-executable-type`. Or the bundle notarizes, but
`spctl -a -t exec` answers a bare `rejected`.

**Cause.** Before 2.5.17, GraalVM bundles put non-code files under `Contents/MacOS/`: the
executable-type marker and `lib/fontconfig.bfc`. `codesign` treats every file there as
nested code, and Gatekeeper rejects non-Mach-O files anywhere under `Contents/MacOS/`. The
GraalVM dylibs there also kept their ad-hoc signature.

**Fix.** Upgrade to 2.5.17 or later. The marker and `fontconfig.bfc` now live in
`Contents/Resources/`, and every dylib under `Contents/MacOS/` is re-signed with your
Developer ID. Files you add through `appResourcesRootDir` still land in `Contents/MacOS/`
on macOS — ship only Mach-O binaries there, or Gatekeeper rejects the notarized bundle the
same way.

## Microsoft Store

### Upload rejected: "MinVersion &lt;= 10.0.17134.0"

**Symptom.** Partner Center rejects the upload:

> Package acceptance validation error: bundle is not valid. You can't upload
> msix/msixbundle/msixupload packages that target Windows with a
> MinVersion &lt;= 10.0.17134.0.

**Cause.** No explicit `minVersion` is set in `appx { }`. The default is `10.0.14316.0`,
which is below the Store's floor.

**Fix.** Set a `minVersion` at or above the Store's floor:

```kotlin title="build.gradle.kts"
appx {
    minVersion = "10.0.17763.0"        // Windows 10 1809
    maxVersionTested = "10.0.22621.0"  // Windows 11 22H2
}
```

### Upload rejected: publisher or identity mismatch

**Symptom.** Upload validation fails with an identity mismatch.

**Cause.** `identityName`, `publisher`, or `publisherDisplayName` do not match the Partner
Center reservation.

**Fix.** Copy the exact values from Partner Center under Product identity. `publisher` is
the `CN=<GUID>` issued by the Store, not the CN of your local signing certificate. See
[Windows targets](/docs/packaging/windows).

## Networking

### SSLHandshakeException on a corporate network

**Symptom.** HTTPS calls from the app fail with
`SSLHandshakeException: PKIX path building failed`.

**Cause.** A corporate proxy or VPN gateway intercepts TLS with a private root CA that the
bundled JDK trust store does not know.

**Fix.** Use either approach, or both.

Ship the CA inside the bundled JDK's `cacerts` at build time:

```kotlin title="build.gradle.kts"
nativeDistributions {
    trustedCertificates.from(files("certs/corp-ca.pem"))
}
```

See [trusted certificates](/docs/packaging/trusted-certificates).

Or route HTTPS through the OS trust store at runtime with `native-ssl` and `native-http`:

```kotlin title="build.gradle.kts"
implementation("dev.nucleusframework:nucleus.native-ssl:<version>")
implementation("dev.nucleusframework:nucleus.native-http:<version>")
```

`NativeHttpClient.create()` returns a `java.net.http.HttpClient` backed by the OS trust
store. For OkHttp or Ktor, use the `nucleus.native-http-okhttp` and
`nucleus.native-http-ktor` integrations.

## Auto-update

### "no matching file" on macOS

**Symptom.** A check returns `UpdateResult.Error` wrapping a `NoMatchingFileException` on
macOS.

**Cause.** The release contains only a `.dmg`. Auto-update on macOS downloads a ZIP.

**Fix.** Add `TargetFormat.Zip` alongside `TargetFormat.Dmg`. Both belong in the same
release, and `latest-mac.yml` references both. See [auto-update](/docs/packaging/auto-update).

## GraalVM native image

### ClassNotFoundException or NoSuchMethodError at runtime

**Symptom.** The app runs on the JVM but crashes under `native-image` with reflection
errors or missing methods.

**Cause.** GraalVM uses closed-world analysis. Reflection, resources, and dynamic proxies
must be registered ahead of time.

**Fix.** The Nucleus plugin ships GraalVM reachability metadata for itself, FileKit, and
other common libraries (see [automatic metadata](/docs/performance/graalvm/automatic-metadata)).
For your own code:

1. Run with `-agentlib:native-image-agent=config-output-dir=...` on a representative
   workload.
2. Commit the generated `reachability-metadata.json` next to `META-INF/native-image/`.

For unsupported libraries, see [GraalVM configuration](/docs/performance/graalvm/configuration).

## Linux packaging

### AppImage takes about 60 seconds to start

**Symptom.** The app opens quickly in development but takes about a minute when packaged
as an AppImage.

**Cause.** `compressionLevel = CompressionLevel.Maximum` or `Ultra`. AppImage uses squashfs,
and maximum compression triggers FUSE decompression on every launch.

**Fix.** Use `CompressionLevel.Normal` (the default) for AppImage. Prefer a format-local
override so DEB/DMG can stay on a higher global level:

```kotlin title="build.gradle.kts"
nativeDistributions {
    compressionLevel = CompressionLevel.Ultra
    linux {
        appImage {
            compressionLevel = CompressionLevel.Normal
        }
    }
}
```

### DEB or RPM fails: "Please specify project homepage"

**Symptom.** `packageDeb` or `packageGraalvmDeb` fails immediately.

**Cause.** Unlike jpackage, electron-builder requires `homepage` for DEB.

**Fix.** Set the homepage on the distribution:

```kotlin title="build.gradle.kts"
nativeDistributions {
    homepage = "https://myapp.example.com"
}
```

### Flatpak task skips silently

**Symptom.** `packageFlatpak` reports "skipped" with no error.

**Cause.** `flatpak-builder` or the `org.freedesktop.Platform//23.08` runtime is missing
on the build host.

**Fix.** Install the tooling and runtime:

```shell
sudo apt-get install -y flatpak flatpak-builder
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install -y flathub org.freedesktop.Platform//23.08
flatpak install -y flathub org.freedesktop.Sdk//23.08
```

In CI, use `setup-nucleus` with `flatpak: 'true'`.

### Snap fails: "snapcraft: command not found"

**Symptom.** `packageSnap` fails before producing anything.

**Cause.** `snapd` or `snapcraft` is missing on the build host.

**Fix.** Install both:

```shell
sudo apt-get install -y snapd
sudo snap install snapcraft --classic
```

In CI, use `setup-nucleus` with `snap: 'true'`.

## Native libraries

### Module reports `isAvailable == false` or silent no-ops

**Symptom.** System tray, system color, notifications, or another OS-integration module
does nothing on a platform where you expect it to work. Public APIs return `null` /
`false`, or `isAvailable` is `false`.

**Cause.** The JNI shared library for that module did not load. Common reasons: no binary
for this OS/arch in the dependency JAR, the module is missing from the runtime classpath,
or extraction into the content-addressed cache failed.

**Fix.** Confirm the module dependency is on the runtime classpath and that the JAR
contains `/nucleus/native/<os>-<arch>/…` for your platform. Clear the loader cache and
relaunch if an upgrade left a partial extract:

| Platform | Cache path |
|----------|------------|
| macOS | `~/Library/Caches/nucleus/native/` |
| Linux | `~/.cache/nucleus/native/` (or `$XDG_CACHE_HOME/nucleus/native/`) |
| Windows | `%LOCALAPPDATA%\nucleus\native\` |

See [Native library loader](/docs/performance/native-library-loader) for the full load
order, JAR layout, and sidecar rules.

### Native library fails to load on an older Linux distribution

**Symptom.** On Ubuntu 22.04, Debian 12, Devuan 5, or another distribution older than
Ubuntu 24.04, the app crashes at launch or a module reports `isAvailable == false`. stderr
shows `version 'GLIBC_2.3x' not found` for a `libnucleus_*.so` library.

**Cause.** Up to 2.5.17 the Linux natives were built on `ubuntu-latest` (Ubuntu 24.04), so
they required glibc 2.39.

**Fix.** Upgrade to 2.5.18 or later. The natives are built on Ubuntu 22.04 and need
glibc 2.35 or newer. Check your system's version with `ldd --version`.

## Rendering

### Wayland on NVIDIA: black window or garbled output

**Symptom.** The Compose UI renders incorrectly under Wayland on NVIDIA drivers.

**Cause.** NVIDIA's GBM and EGLStream support for Wayland is inconsistent, and Compose
Desktop on the AWT/JBR backend does not handle it reliably.

**Fix.** Switch to the [Tao backend](/docs/tao). `decorated-window-tao` renders through
native Skia surfaces on Wayland without going through AWT. To stay on AWT, set
`WLR_NO_HARDWARE_CURSORS=1` or run under XWayland.

### Crash on launch with an older Linux GPU

**Symptom.** A Tao window aborts at open on Linux. stderr mentions a failed GL 3.3 context,
or the process exits from `TaoComposeSceneHostLinux` with a `require()` failure.

**Cause.** Linux EGL attach used to request only a GL 3.3 **compatibility** profile. Some
drivers (Mesa r600 on AMD RV610, for example) cap the compat profile at 3.0 while the
**core** profile reaches 3.3, so the request could never succeed and the window aborted.

**Fix.** Upgrade to 2.5.16 or later. Attach now tries 3.3 compat, then 3.3 core, then Mesa
llvmpipe (`LIBGL_ALWAYS_SOFTWARE=1`, one-shot, skipped if you already set that variable).
Both fallbacks log one line on stderr. Hardware that already accepts the compat request is
unchanged. Force software rendering yourself with `LIBGL_ALWAYS_SOFTWARE=1` if you want
llvmpipe without waiting for the fallback.

## Migration to 2.0

### Unresolved reference 'JewelDecoratedWindow'

**Symptom.** The import is correct and the IDE resolves the function, but compilation
fails.

**Cause.** In 2.0, the composable is an extension on `NucleusApplicationScope`. A wrapper
composable written for 1.x does not propagate the receiver.

**Fix.** Make your wrapper an extension as well:

```kotlin
fun NucleusApplicationScope.MyOnboardingWindow() {
    JewelDecoratedWindow(/* ... */) { /* content */ }
}
```

See [migrate from 1.x](/docs/migrate/from-1.x).

### NoClassDefFoundError: DecoratedDialogKt on Tao

**Symptom.** The dialog crashes on Tao but works on AWT.

**Cause.** The code calls the AWT-only `JewelDecoratedDialog` (no receiver) under
`NucleusBackend.Tao`.

**Fix.** Make the host composable an extension on `NucleusApplicationScope` so the call
resolves to `NucleusApplicationScope.JewelDecoratedDialog`, which dispatches per backend.

### Dependency requires JVM runtime version 11

**Symptom.** Gradle fails to resolve the Jewel artifact with a message about JVM runtime
version 11.

**Cause.** The toolchain is not set to 25.

**Fix.** Set the Kotlin JVM toolchain:

```kotlin title="build.gradle.kts"
kotlin { jvmToolchain(25) }
```

See [migrate from 1.x](/docs/migrate/from-1.x).

## What's next

- [Packaging](/docs/packaging) — per-OS packaging, signing, and store targets.
- [Performance](/docs/performance) — GraalVM native image and AOT details.
- [Migrate from 1.x](/docs/migrate/from-1.x) — namespace and scope changes after upgrading.

---

# Roadmap

URL: https://nucleusframework.dev/en/docs/roadmap

What shipped in Nucleus 2.0–2.5, the modules planned next, and features under consideration.

Nucleus 2.0 provides the runtime and packaging foundation. Later releases add
OS-integration modules for capabilities that JVM desktop apps otherwise reach through
JavaScript or hand-written native code. This page lists what has shipped, what is planned,
and what is still speculative.

## Shipped in 2.0

- `nucleusApplication { }` unified entry point — single-instance, deep links, AOT, GraalVM init, AutoLaunch priming, Windows AUMID — all automatic.
- Tao backend — Wayland-native, multi-touch, pen pressure + tilt, native popups, embedded `NativeView`, drag-and-drop with diagnostics.
- 18 packaging formats from one Gradle DSL.
- `updater-runtime` — electron-builder-compatible auto-update, channels, post-update detection.
- GraalVM Native Image — end-to-end packaging pipeline (DMG, NSIS, DEB), static bytecode reflection analyzer, per-library reachability metadata.
- macOS Liquid Glass on SDK 26 — `vtool` patching means any JDK works.
- 40+ runtime modules: notifications, system tray, global hotkeys, media controls, taskbar progress, energy manager, system info, scheduler, autolaunch, dark mode, system color, native SSL, native HTTP, filesystem watcher, decorated windows with four toolkits.

## Shipped in 2.1

Tooling and native-image work, no new runtime modules:

- **GraalVM Community Edition is the default toolchain** (from 2.1.7) — auto-downloaded and cached; no redistribution-for-a-fee clause. Opt into Oracle GraalVM for PGO, `-O3`, ML-inferred profiles, and advanced obfuscation. Only the deprecated AWT backend still needs a local BellSoft Liberica NIK install for AWT/Swing native-image support.
- 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`. Supported on the AWT and Tao backends.
- Profile-Guided Optimization — record a profile with `runWithPgoInstrument`, commit it, and later full native builds apply it automatically. Oracle GraalVM only.
- Smaller native images — `optimization = NativeImageOptimization.SIZE` (`-Os`), type-safe `march`, automatic executable stripping, desktop-appropriate max heap, and advanced obfuscation (Oracle).
- CPU-portable AOT cache by default (metadata-only) with an explicit `aotCache { }` block.
- `CompressionLevel.Ultra` — extra post-processing recompression (LZMA DMG, `xz -9e` DEB) for smaller installers.
- `--enable-native-access=ALL-UNNAMED` in default JVM args and native images for JDK 24+ (JEP 472).

## Shipped in 2.2

Window chrome, accessibility, and tooling parity:

- **Window scaffold and chrome primitives** — `WindowScaffold` with `TitleBarPlacement.Docked` / `Overlay`, `windowDragArea` / `noWindowDrag`, `WindowControls`, macOS `windowGlassRegion`, Windows 11 `WindowsBackdrop` (Mica / Acrylic / MicaAlt), `WindowBackground`, `WindowAppearance`. See [Window scaffold](/docs/tao/window-scaffold).
- **Full-window transparency on Tao** — `DecoratedWindow(transparent = true)` for ghost overlays (pair with `undecorated`).
- **AccessKit on Windows** — Windows and Linux share the AccessKit accessibility path (UIA + AT-SPI).
- **GraalVM task surface aligned with the JVM pipeline** — `runGraalvmNative` (quick-build), `createGraalvmNativeDistributable`, `runGraalvmNativeDistributable`, `packageGraalvmNativeDistributionForCurrentOS`.
- **Type-safe garbage collector selection** — `GarbageCollector` on the JVM path and `NativeImageGarbageCollector` for native images.
- **`NucleusApplicationScope` implements Compose `ApplicationScope`** — libraries scoped to plain `ApplicationScope` resolve inside `nucleusApplication { }`.
- Scheme-only deep links (`myapp:?query=…`), consistent macOS `.app` bundle names, native GTK CSD shadow.

## Shipped in 2.3

GPU textures, update bandwidth, and application-scope polish:

- **`TextureView`** — external GPU textures in the Compose scene (Windows D3D11, macOS Metal/`IOSurface`, Linux DMA-BUF/`EGLImage` + planar YUV). See [TextureView](/docs/tao/texture-view).
- **Differential auto-update** — block-map range downloads; AppImage relaunch; hardened silent DEB/RPM helper packaging. See [Auto-update](/docs/packaging/auto-update).
- **Notification platform DSL** — `linux { }` / `macos { }` / `windows { }` on the common API. See [Notifications](/docs/os/notifications#platform-specific-options).
- **`LocalNucleusApplicationScope`** — open windows from deep composition without threading the receiver. See [DecoratedWindow](/docs/tao/decorated-window#open-a-window-from-composition).
- **System theme bridge** — `isSystemInDarkTheme()` tracks OS changes under `nucleusApplication`. See [Dark mode](/docs/os/dark-mode#bridge-to-compose-issystemindarktheme).
- **GraalVM** — innovation default **25.2**, exact reachability on `runGraalvmNative`, orphan project-class detection, safer SLF4J lifecycle, metadata input fingerprinting.

## Shipped in 2.5

Spell check, platform context menus, and overlay windows:

- **`spellcheck`** — Hunspell / `NSSpellChecker` / Windows Spell Checking behind a Compose text-field wrapper. See [Spell check](/docs/os/spell-check#check-a-text-field).
- **Native context menus** — `nativeContextMenu = true` swaps the Compose menu for `NSMenu`, Fluent, Adwaita, or Breeze. See [Context menus](/docs/window/context-menu#turn-on-the-native-menu).
- **Overlay window flags** — `clickThrough`, `alwaysOnBottom`, `visibleOnAllWorkspaces`, `forceX11`. See [Overlay windows](/docs/tao/overlay-windows#build-a-click-through-watermark).
- **Compose over native views** — single-scene blending on macOS, Windows, and Linux. See [Overlay Compose content](/docs/tao/native-views#overlay-compose-content).
- **Linux GTK clipboard** — images and file lists, working on native Wayland. See [Copy and paste](/docs/tao/wayland#copy-and-paste).
- **Compose 1.12** — required from this line on. See [Compatibility](/docs/start/install#compatibility).
- **`SchedulerConfig`** — point the OS scheduler at a custom launcher. See [SchedulerConfig](/docs/lifecycle/scheduler#schedulerconfig).
- **`EnergyManager.acquireAwake`** — independent awake handles, and the Tao implementation behind Compose's `Modifier.keepScreenOn`. See [Hold several awake requests at once](/docs/lifecycle/energy-manager#hold-several-awake-requests-at-once).

## Shipped in 2.4

In-process GPU, power control, packaging DSL, and a frozen public ABI:

- **`TaoGpuRenderContext`** — scene Skia `DirectContext` + native device for in-process renderers. See [GPU render context](/docs/tao/gpu-render-context).
- **`AwakeMode`** — `keepAwake(SYSTEM_ONLY)` without forcing the display on. See [Energy manager](/docs/lifecycle/energy-manager#keep-the-system-awake).
- **`windows.msi { perMachine }`** — install-scope DSL aligned with NSIS. See [Windows packaging](/docs/packaging/windows#build-an-msi-for-enterprise-deployment).
- **Public ABI freeze** — `explicitApi()` + binary-compatibility-validator on published runtime modules.
- Tao resize / frame-pacing and popup stability fixes across macOS, Windows, and Linux.

## Coming next

Security and identity modules (still planned; not part of the 2.5 line):

| Module | Description | macOS | Windows | Linux |
|--------|-------------|-------|---------|-------|
| `secure-storage` | Hardware-backed secret storage for tokens, passwords, keys | Keychain | Credential Manager / DPAPI | Secret Service (`libsecret`) |
| `biometric-auth` | Prompt for fingerprint / face authentication | `LocalAuthentication` (Touch ID / Face ID) | Windows Hello | `fprintd` via D-Bus / polkit |

OS-level events and IO:

| Module | Description | macOS | Windows | Linux |
|--------|-------------|-------|---------|-------|
| `share-sheet` | OS share sheet (URL, file, text) | `NSSharingService` | Windows `DataTransferManager` | xdg-desktop-portal `Share` |
| `power-events` | Sleep / wake / lock / unlock / screen-off / battery state | `NSWorkspace` notifications | `WM_POWERBROADCAST` / `WTSRegisterSessionNotification` | `org.freedesktop.login1` D-Bus signals |

## Under consideration

Speculative — no commitment, no ETA. Open an issue if you want one of these earlier:

| Module | Description | macOS | Windows | Linux |
|--------|-------------|-------|---------|-------|
| `clipboard` | Rich clipboard — HTML and RTF flavors, plus a change watcher. Text, images and file lists already work on Linux — see [copy and paste](/docs/tao/wayland#copy-and-paste). | `NSPasteboard` | `OleGetClipboard` / Clipboard History API | GDK selections |
| `screen-capture` | Native screenshot / screen recording | `CGDisplayCreateImage` / ScreenCaptureKit | Windows Graphics Capture / DXGI | xdg-desktop-portal `Screenshot` |

## Influence the order

Open an issue describing your use case, link a sample app that needs the module, or sponsor
a specific platform's implementation. Native modules are bounded mostly by JNI bridge
complexity per OS — the more people that need one, the sooner it ships.

## What's next

- [Changelog](/docs/changelog) — released versions and what each one contains.
- [Modules](/docs/concepts/modules) — how runtime modules are structured and added to a build.
- [Ecosystem](/docs/ecosystem) — the modules available today.

---

# Changelog

URL: https://nucleusframework.dev/en/docs/changelog

Release notes for every Nucleus release, newest first.

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.5.18

**Released: 2026-09-23**

### Bug fixes

- **Linux natives require glibc 2.39** (#699) — the Linux JNI libraries (Tao, decorated
  window, notifications, tray helpers, …) were built on `ubuntu-latest`, which GitHub moved
  to Ubuntu 24.04, so every published `.so` needed glibc 2.39 and failed to load on
  still-supported distributions such as Ubuntu 22.04 LTS (2.35), Debian 12, and Devuan 5
  (2.36). The native build is now pinned to `ubuntu-22.04` / `ubuntu-22.04-arm`, bringing
  the floor back to glibc 2.35. See
  [Native library fails to load on an older Linux distribution](/docs/reference/troubleshooting#native-library-fails-to-load-on-an-older-linux-distribution).

---

## v2.5.17

**Released: 2026-09-22**

### New features

- **Pacman upgrade hooks** (#685) — `linux { }` gains `afterUpgrade` and `beforeUpgrade`
  file properties, passed raw to fpm (`--after-upgrade` / `--before-upgrade`). On Pacman,
  an upgrade runs only `pre_upgrade` / `post_upgrade`: none of the four install/remove
  scripts fire, so a service set up in `afterInstall` died on the first upgrade. Register or
  restart it in `afterUpgrade` too. Deb and Rpm ignore both properties — their install
  scriptlets already run on upgrades. See
  [Add install and remove scripts](/docs/packaging/linux#add-install-and-remove-scripts).

### Bug fixes

- **Linux install directory no longer contains spaces** (#685) — Deb, Rpm, and Pacman
  installed the payload under `/opt/${sanitizedProductName}`, derived from `appName`.
  electron-builder's sanitizer keeps spaces, so a display name such as `My App` broke every
  unquoted path in install scripts and systemd `ExecStart=` lines. On Linux the product name
  now comes from `linux.packageName ?: packageName`, so the payload lands in
  `/opt/<packageName>`. Scripts that hardcode the old `/opt/<App Name>` path must be updated.
- **Developer ID signing of GraalVM macOS bundles** (#692) — `packageGraalvmDmg` with
  `compose.desktop.mac.sign=true` aborted with `code object is not signed at all` on
  `Contents/MacOS/.nucleus-executable-type`, and even a manually fixed bundle was rejected by
  Gatekeeper after notarization. Three fixes: the executable-type marker is written to
  `Contents/Resources/` (the runtime still reads the old location); every dylib and
  executable under `Contents/MacOS/` is re-signed with the Developer ID identity; and
  `fontconfig.bfc` moves from `Contents/MacOS/lib/` to `Contents/Resources/`, with
  `sun.awt.fontconfig` pointed at it at startup. JVM (jpackage) bundles are unaffected. See
  [Notarization fails: "code object is not signed at all"](/docs/reference/troubleshooting#notarization-fails-code-object-is-not-signed-at-all).

---

## v2.5.16

**Released: 2026-09-17**

### New features

- **Linux install and remove scripts** (#664) — `linux { }` now takes `afterInstall`,
  `afterRemove`, `beforeInstall`, and `beforeRemove` file properties. User after-scripts
  are concatenated after Nucleus's own template (desktop integration, AppArmor, optional
  polkit silent-update helper) and run through electron-builder for Deb, Rpm, and Pacman;
  before-scripts are passed raw to fpm (`--before-install` / `--before-remove`). GraalVM
  native-image packages honor the same four properties. electron-builder substitutes
  `${sanitizedProductName}` / `${executable}` only in single-quoted tokens; a double-quoted
  `"${executable}"` is left literal, so a systemd `systemctl enable "${executable}.service"`
  line silently no-ops. Pacman `pre_remove` does not get deb-style `$1=upgrade` — stop and
  disable the unit unconditionally and re-enable it in `afterInstall`. See
  [Add install and remove scripts](/docs/packaging/linux#add-install-and-remove-scripts).
- **Headless GraalVM images** (#665) — `graalvm { headless = true }` skips L3 AWT/Java2D
  platform metadata, the always-on L1 GUI packs (`jdk-awt`, `jdk-fonts`, `jdk-graphics2d`,
  Skiko/Compose/tray), and the companion GUI native libs (`libawt`, `libfontmanager`,
  Skiko, …), and bakes `-Djava.awt.headless=true`. Default is `false` (GUI). Without this,
  JNI registration of AWT types makes `native-image` pull `libawt` / `libawt_xawt` even
  when app code never references `java.awt`. Use it for daemons and CLIs. See
  [Build a headless image](/docs/performance/graalvm/configuration#build-a-headless-image).

### Bug fixes

- **Linux EGL crash on GPUs without GL 3.3 compatibility** (#670) — the X11 and Wayland
  attach paths asked for one thing only: a GL 3.3 compatibility-profile context. Mesa's
  r600 driver on AMD RV610 caps the compat profile at 3.0 (core reaches 3.3), so the
  request failed and the app aborted. Attach now tries 3.3 compat, then 3.3 core
  (hardware-accelerated on that GPU), then Mesa llvmpipe via `LIBGL_ALWAYS_SOFTWARE=1`
  (Mesa reads that variable at `eglInitialize`, so the display is terminated and attach
  re-enters once). Existing hardware that accepts the compat request is untouched. Both
  fallbacks log one line on stderr. See
  [Crash on launch with an older Linux GPU](/docs/reference/troubleshooting#crash-on-launch-with-an-older-linux-gpu).

---

## v2.5.15

**Released: 2026-09-07**

### New features

- **Trackpad pan events on macOS** (#654) — two-finger trackpad gestures arrived as ordinary
  Compose `Scroll` events, indistinguishable from wheel notches, so a map could not bind panning
  to the trackpad and zoom to the wheel. Phased AppKit scroll steps now become
  `PointerEventType.PanStart` / `PanMove` / `PanEnd` with `panOffset` in pixels (AWT
  `preciseWheelRotation` × 10.dp). Wheel notches and phase-less precise scrolls stay `Scroll`.
  The pan stays open across AppKit's momentum tail so Compose does not stack its own fling.
  `Modifier.scrollable` handles both; a custom `pointerInput` that only listens for `Scroll`
  must also handle Pan, or start the process with `-Dnucleus.tao.trackpadPanEvents=false` to
  get AWT-style `Scroll` for everything. Native views consume the pan and forward it so the
  embedded scroll view rubber-bands; popups share the same router. See
  [Read trackpad pans from Compose](/docs/tao/multi-touch#read-trackpad-pans-from-compose).

### Bug fixes

- **Horizontal trackpad scroll reversed on macOS** (#652) — tao negated `scrollingDeltaX` in
  the macOS `scroll_wheel` handler, then Nucleus negated both axes assuming raw AppKit deltas,
  so a two-finger swipe left panned the wrong way relative to AWT. AppKit already follows the
  `MouseScrollDelta` convention (as winit does); the extra X negation is gone, and popup
  conversion flips both axes without a second guess. See
  [Read trackpad pans from Compose](/docs/tao/multi-touch#read-trackpad-pans-from-compose).
- **Trackpad scroll magnitude included display scale** (#653) — Tao converted AppKit logical
  deltas to physical pixels before dividing by 10, so a 10-point swipe moved twice as far on a
  2× display as under AWT (which uses `scrollingDelta * 0.1` with no scale). Precise deltas are
  now handed over in logical points. See
  [How it works](/docs/tao/multi-touch#how-it-works).

---

## v2.5.14

**Released: 2026-09-04**

### Bug fixes

- **Window content reclassified by a non-UI composable** (#636) — the window and dialog
  openers had their composition target inferred, so a single unmarked factory called in the
  `nucleusApplication` block (the Compose compiler bakes `@ComposableTarget` onto any unmarked
  function that forwards a target-marked content lambda) reclassified the whole scope — nested
  windows included — and every `@UiComposable` call in it warned, which is fatal under
  `-Werror`. The reported case was MapLibre Compose's `rememberMapState`. Each opener is now
  `@ComposableOpenTarget(-1)` with a `@UiComposable` content lambda, matching Compose Desktop's
  `Window`/`Dialog`: callable from any applier, always composing UI in the new window's own
  composition. Covers `DecoratedWindow`/`DecoratedDialog`, `NucleusWindowHost` /
  `NucleusDialogHost`, `HostedWindow`/`HostedDialog`, and Tao's `DecoratedWindow`,
  `DecoratedDialog`, and `TaoStandalonePopup`. The Material/Jewel wrappers inherit the same
  scheme through inference. See [Notes](/docs/tao/decorated-window#notes).

---

## v2.5.13

**Released: 2026-09-04**

### Bug fixes

- **Windows freeze on IME commit and taskbar restart** (#644) — two more instances of the
  #640 lock class: the window-state lock was held across `ImeHandler::process_message`, which
  peeks the queue on `WM_IME_ENDCOMPOSITION` (the Korean IME sends the committed string after
  the end message, so the queue decides whether to defer), and across `set_skip_taskbar` on
  `TaskbarCreated`, where the `CoCreateInstance` + `ITaskbarList` STA call pumps the queue
  while it waits. Both re-entered the window procedure and re-locked a non-reentrant mutex,
  parking the event-loop thread in `WaitOnAddress` for good. The IME commit-pending flag is
  now computed before the lock is taken and passed in, and the skip-taskbar flag is read out
  before the COM call. Wider blast radius than #640: nearly every IME arm took that lock.
  Ported from tauri-apps/tao#1215 and #1264. See
  [Text input](/docs/tao/decorated-window#text-input).
- **Windows freeze on a keyboard-triggered nested message** (#640) — `PeekMessageW` delivers
  pending cross-thread *sent* messages inline, re-entering the window procedure before the
  peek returns. The keyboard callback held the global `KEY_EVENT_BUILDERS` map and the
  key-press/release arms held `LAYOUT_CACHE` across such a peek, so the nested dispatch
  deadlocked the event-loop thread against itself and the window stayed "Not Responding".
  Reported as a freeze when moving a window between Windows 11 virtual desktops. The builder
  is now taken out of the map for the duration and put back only if the slot still exists, and
  the layout-cache guard ends before the peek. Only injected or sent key messages can nest
  here, and they are now dropped instead of hanging the process.

---

## v2.5.12

**Released: 2026-09-01**

### Bug fixes

- **`alwaysOnTop` dropped on Windows** (#631) — three layers lost `WS_EX_TOPMOST`:
  `DecoratedWindowComposable` created every window with a hardcoded `alwaysOnTop = false` and
  applied the real value from a later `LaunchedEffect`, losing the race against creation-time
  style rewrites (acrylic, skip-taskbar); tao only issues its z-order `SetWindowPos` on a
  `WindowFlags` cache diff, and asynchronously, so an external rewrite that dropped the
  topmost band was never repaired. The initial value is now passed at window creation,
  `setAlwaysOnTop` also applies the z-order synchronously, and the band is re-asserted after
  the known clobber sites — every resize, and the backdrop apply, teardown, and
  survivor-restore paths. See
  [Platform behavior](/docs/tao/overlay-windows#platform-behavior).
- **Input starving with two windows open on Windows** (#632) — any snapshot write in the
  process wakes every scene's `Recomposer` through the global apply observer, and the Windows
  host rendered and presented those frames unconditionally. Each `eglSwapBuffers` at interval
  1 parks the shared event-loop thread until the next VBlank, so every visible window
  re-presented at the animating window's rate and the VBlank waits serialized (a dashboard
  lagging while a small always-on-top window was visible). The scene bundle now tracks a
  visual-dirty flag fed by its `invalidateLayout` / `invalidateDraw` callbacks and the host
  skips the present for a frame with no visual change. Presents that must swap regardless are
  kept: a size or scale apply, the OS modal resize/move loop, a resolved clear-colour change,
  and the first swap after `show()`. See
  [How it works](/docs/tao/decorated-window#how-it-works).

---

## v2.5.11

**Released: 2026-08-31**

### New features

- **`menuCategory` and `shortcutName` on the NSIS targets** (#630) — follow-up to #629. The
  NSIS targets exposed most installer settings but not these two, so a start-menu group could
  not be declared at all and the shortcut always landed in the start menu root — a blocker for
  projects moving their MSI packaging to the recommended NSIS format while keeping the folder
  they had under jpackage. Both are emitted for `nsis` and `nsis-web`, default to `null`
  (nothing emitted, so existing installers are unchanged), and `windows.menuGroup` acts as the
  default `menuCategory` exactly as it does for MSI. See
  [Customize the NSIS installer](/docs/packaging/windows#customize-the-nsis-installer).

---

## v2.5.10

**Released: 2026-08-31**

### Bug fixes

- **MSI installer options** (#629) — the MSI target only forwarded `upgradeCode` and
  `perMachine` to electron-builder, so every other Windows installer setting fell back to
  an electron-builder default: `windows.menuGroup` was ignored and the shortcut landed in
  the start menu root, `oneClick` defaulted to `true` so the installer ran with no UI, and
  `runAfterFinish` launched the app as soon as the install finished. `MsiSettings` now
  emits `oneClick`, `runAfterFinish`, `createDesktopShortcut`, `createStartMenuShortcut`,
  `menuCategory`, and `shortcutName`. Defaults match electron-builder unless a project
  opts in; `windows.menuGroup` is the default `menuCategory`. `windows.menu` /
  `windows.shortcut` stay unmapped (jpackage `false` vs electron-builder `true`). See
  [Build an MSI for enterprise deployment](/docs/packaging/windows#build-an-msi-for-enterprise-deployment).

---

## v2.5.9

**Released: 2026-08-31**

### Bug fixes

- **Fatal dialog stack trace** (#627) — the 2.5.8 native dialog stuffed the throwable into
  the message line. On Linux that doubled the title ("Fatal Error" twice on WMs that draw
  dialog titlebars) and the unbounded secondary label sized the dialog to the whole screen.
  The payload is now a short message plus `Throwable.stackTraceToString()`: all three
  platforms render the trace in a bounded scrollable monospace view with a Copy button
  (`NSAlert` via an out-of-process `osascript` child on macOS, an in-memory `DLGTEMPLATE`
  on a fresh thread on Windows, `GtkMessageDialog` on Linux). Compact fallbacks
  (`CFUserNotification` / `MessageBoxW`) keep the `toString()` summary, capped at 2000
  chars so a `VerifyError` bytecode dump cannot silently hide the box. See
  [Handle uncaught exceptions](/docs/tao/decorated-window#handle-uncaught-exceptions).

---

## v2.5.8

**Released: 2026-08-31**

### New features

- **Native fatal-error dialog** (#622 / #623) — an exception that escaped a Tao event
  dispatch used to be cleared at the JNI boundary, leaving a frozen, silent, unclosable
  window. The default path now logs the stack at `SEVERE`, shows a blocking native dialog
  (`CFUserNotification` on macOS, `MessageBoxW` on a dedicated thread on Windows,
  `GtkMessageDialog` on Linux), exits the Tao loop, and rethrows so `nucleusApplication` /
  `taoApplication` end with exit code 1. The dialog is shown after the loop has exited — a
  modal pump inside a tao callback deadlocks the main thread. Skip it with
  `-Dnucleus.tao.fatalErrorDialog=false` for unattended runs. See
  [Handle uncaught exceptions](/docs/tao/decorated-window#handle-uncaught-exceptions).
- **`WindowExceptionHandlerFactory`** (#621 / #625) — Tao mirror of Compose Desktop's AWT
  factory. Provide `LocalWindowExceptionHandlerFactory` to catch failures during layout,
  draw, input, IME, and accessibility; a handler that returns normally drops the frame and
  keeps the window alive. Composition failures still kill the recomposer (Compose's own
  design); swallowing one logs at `SEVERE` instead of leaving a window that never updates.
  The default factory rethrows into the fatal dialog. `@ExperimentalComposeUiApi`. See
  [Handle uncaught exceptions](/docs/tao/decorated-window#handle-uncaught-exceptions).

---

## v2.5.7

**Released: 2026-08-30**

### Bug fixes

- **Popup render re-entry on a scrollbar drag** (#620) — dragging a scrollbar inside a `TrayApp`
  popup scrolls synchronously inside the pointer event, and the `LaunchedEffect`s of the lazy
  items subcomposed by that scroll scheduled a frame the standalone pump rendered inline. Measure
  and layout re-entered while the first pass was still on the stack, throwing
  `performMeasureAndLayout called during measure layout` and leaving the drag with a non-zero
  pending scroll. Every scene entry point of the standalone hosts — pointer, scroll, key dispatch,
  and `setContent` — now runs under the pump's re-entrancy guard, so a frame scheduled mid-pass is
  posted to the Tao main queue instead. See [Notes](/docs/os/tray-app#notes).

---

## v2.5.6

**Released: 2026-08-30**

### Bug fixes

- **Linux IME preedit** (#558 / #613) — the Linux backend pinned `gtk::IMContextSimple`, GTK's
  built-in fallback, which never reaches the system input method: CJK input was not degraded but
  impossible, and typing `aiueo` then confirming left a stray `a`. The backend now uses
  `gtk::IMMulticontext` — ibus or fcitx5 through the GTK immodule on X11, the text-input-v3 client
  on Wayland — and routes its signals into the same `ImePreedit` / `ImeCommit` events as macOS and
  Windows. Keys the input method consumed no longer reach Compose, including the orphan key
  releases Wayland delivers for a filtered press, and the candidate window follows the caret. See
  [Text input](/docs/tao/decorated-window#text-input).
- **Linux candidate window covering the caret** (#613) — GTK places its windows around a cursor
  *area* in logical pixels relative to the toplevel `GdkWindow`, not a point in physical pixels
  relative to the client area, so the candidate list landed on the composition it described. The
  caret rect is scaled and translated by the content widget's allocation, matching the correction
  the Wayland subsurface already applies. See
  [Text input](/docs/tao/decorated-window#text-input).
- **Linux modifier state drift** (#613) — `ModifiersChanged` was emitted only when the key itself
  was a modifier, so Compose tracked Ctrl, Shift, Alt, and Super from press and release
  bookkeeping. Input methods on X11 re-inject the events they forward, and a dropped Control
  release left Compose believing Ctrl was held for the rest of the session: a plain Return read as
  Ctrl+Return. The state is now derived from the GDK modifier mask carried by every event, so it
  self-heals on the next keystroke.
- **macOS press-and-hold accents** (#611 / #612 / #617) — Nucleus forced `ApplePressAndHoldEnabled`
  in four preference domains and guessed from a state machine when the accent picker was active.
  A held letter then did nothing at all on keyboards where the picker cannot engage, and ordinary
  fast typing armed the picker flag and routed the next commit into the replace path, deleting the
  character just committed ("Xcode" landing as "Xcde"). Nucleus no longer reads or writes the user
  default — the OS decides whether a held letter repeats or opens the picker — and the pick is
  applied from the `replacementRange` AppKit sends with `insertText:`, select-then-insert. See
  [Text input](/docs/tao/decorated-window#text-input).
- **Sub-pixel pointer jitter eating clicks** (#615 / #619) — Tao reports cursor positions in
  1/1024 px and macOS emits a `CursorMoved` before every `mouseDown` and `mouseUp`, so a click
  drifting a fraction of a pixel produced a real move delta, started a parent drag gesture, and
  cancelled the tap: selections needed two clicks. Moves under 1 dp from the last dispatched
  position are now suppressed, and `viewConfiguration.touchSlop` is density-scaled to 18.dp
  instead of 18 raw pixels, which had halved every drag and scroll threshold on 2x displays. See
  [How it works](/docs/tao/multi-touch#how-it-works).
- **Linux tray popup scroll** (#610) — standalone, overlay, and owner-based popups now feed wheel
  events through the same AWT-shaped dispatch as `TaoWindow`, with the Windows lines-per-notch
  value from `LocalScrollConfig`. Standalone popup frames paint inline when the caller is already
  on the main thread, so a wheel flood cannot starve `MainEventsCleared`. See
  [Notes](/docs/os/tray-app#notes).
- **Auto-launch at half size on GNOME** (#614 / #616) — `graphical-session.target` is reached
  before `gsd-xsettings` writes `Xft.dpi` into the X resource database, so a HiDPI app started at
  login froze `sun.java2d.uiScale` at 1.0 while a manual launch was always correct. The generated
  systemd user unit is ordered after `gnome-session-x11-services-ready.target`. systemd ignores
  ordering on units that are not loaded, so this is a no-op on other desktops. See
  [Notes](/docs/lifecycle/auto-launch#notes).

---

## v2.5.5

**Released: 2026-08-28**

### Bug fixes

- **macOS tray popup and Show Desktop** (#609) — the standalone `NSPanel` had the default
  collection behavior, so "Click wallpaper to reveal desktop" on Sonoma and later Exposé-slid the
  popup away while Compose was already fading it. The panel is now stationary, joins all spaces,
  is fullscreen-auxiliary, and is ignored by window cycling, so `TrayApp` dismisses it itself. See
  [Notes](/docs/os/tray-app#notes).
- **macOS tray popup dismissed by its own icon** (#609) — the outside-click monitor counted a
  `mouseDown` on the `NSStatusItem` and on its native context menu as a click outside the panel,
  so a right-click hid the popup before the menu appeared. Those windows are skipped for
  standalone panels; the left-click toggle stays with the tray callback. See
  [Notes](/docs/os/tray-app#notes).

---

## v2.5.4

**Released: 2026-08-27**

### Bug fixes

- **Linux inbound drop on tray popups** (#605 / #607) — a `TrayApp` popup on Linux is an
  override-redirect X11 window, so GTK `gtk_drag_dest_set` cannot attach. Inbound XDND 5 is
  implemented on the panel event thread and dispatched through `TaoSceneDnD`, matching
  `DecoratedWindow`. See [How it works](/docs/tao/drag-and-drop#how-it-works).
- **macOS tray popup scroll** (#608) — popup `NSPanel`s forwarded raw AppKit
  `scrollingDelta`. `TaoWindow` already reshapes those to AWT `preciseWheelRotation` (negate Y,
  physical /10 for precise deltas). Tray and overlay popups now use the same mapping, so wheel
  sign and trackpad magnitude match the main window. See [Notes](/docs/os/tray-app#notes).

---

## v2.5.3

**Released: 2026-08-27**

### Bug fixes

- **Inbound drop on Windows and macOS tray popups** (#604) — `TrayApp` popups are ownerless
  native panels (`WS_POPUP` / `NSPanel`), not `TaoWindow`s, so they had no drop target. Inbound
  file drops now reach Compose `dragAndDropTarget` through `TaoSceneDnD`. Windows native-image
  builds include the JNI metadata for that path. See
  [How it works](/docs/tao/drag-and-drop#how-it-works).
- **Windows IME preedit** (#558 / #603) — composition was never forwarded, so the IME painted
  its own floating window near the top-left of the window, and keys the IME had consumed
  (`VK_PROCESSKEY`) still reached Compose: conversion Enter inserted a newline, candidate arrows
  moved the caret, Backspace deleted committed text. Preedit now renders inline, the candidate
  list follows the caret, and consumed keys are dropped. See
  [Text input](/docs/tao/decorated-window#text-input).

---

## v2.5.2

**Released: 2026-08-27**

### Bug fixes

- **Windows tray popup scroll** (#601) — popup and overlay `WndProc`s reported raw Win32 wheel
  units. `TaoWindow` already negates those to AWT `preciseWheelRotation`; standalone and owned
  popup layers now do the same, so `TrayApp` scrolling is no longer inverted. See
  [Notes](/docs/os/tray-app#notes).
- **Hidden Windows tray popup GPU frames** (#602) — a hidden standalone tray popup no longer
  submits GPU frames.
- **UTF-8 javac/javadoc encoding** (#600) — the compiler and javadoc tasks pin `-encoding UTF-8`,
  so non-ASCII KDoc no longer fails the Windows build.

---

## v2.5.1

**Released: 2026-08-27**

### New features

- **GraalVM innovation channel defaults to 25.3** (#598) — `GraalvmChannel.INNOVATION` resolves
  to `25i3`. See
  [Provision the toolchain](/docs/performance/graalvm/configuration#provision-the-toolchain).

### Bug fixes

- **Animated `WindowState.size` tremble** (#576 / #597) — programmatic height animation left the
  HWND/NSWindow a frame ahead of the Compose scene, and native resize echoes wrote
  `WindowState.size` backwards. Inner size is applied synchronously, `EVENT_RESIZED` is pushed
  in the same turn, and in-flight programmatic echoes are ignored. See
  [DecoratedWindow parameters](/docs/tao/decorated-window#decoratedwindow-parameters).
- **macOS IME preedit** (#595 / #596 / #599) — CJK composition was invisible and the committing
  Enter leaked as a newline. `setMarkedText` / `unmarkText` are forwarded as preedit, commit
  goes through `commitText`, and keys the IME consumed are dropped. The PressAndHold accent
  picker stays gated while a composition is live, so a segment commit cannot arm the picker and
  hijack the next commit (duplicated segments, U+F7xx tofu). See
  [Text input](/docs/tao/decorated-window#text-input).

---

## v2.5.0

**Released: 2026-08-26**

### New modules

- **Spell check** (`nucleus.spellcheck`) — checks spelling through the engine each OS already
  ships: Hunspell on Linux (loaded with `dlopen`, no compile-time dependency), `NSSpellChecker`
  on macOS, and the Windows Spell Checking API. Ships a `SpellcheckContextMenu` wrapper that adds
  suggestions and "Add to dictionary" to a Compose text field's context menu, plus an engine API
  (`SpellChecker`, `SpellcheckSession`) usable without Compose. `nucleus-application` exposes it
  as an `api` dependency, so no extra Gradle line is needed. Where no engine is available every
  operation is a no-op rather than an error. See
  [Spell check](/docs/os/spell-check#check-a-text-field).
    - Per-field and process-wide language override via `locale` / `SpellChecker.locale`. See
      [Choose the check language](/docs/os/spell-check#choose-the-check-language).
    - `SpellcheckMenuPlacement` puts suggestions above or below Cut/Copy/Paste. See
      [Place the menu items](/docs/os/spell-check#place-the-menu-items).
    - The "Add to dictionary" label is localized for 45+ locales; user words persist to
      `~/.config/nucleus/spellcheck/<tag>.dic`.

### New features

- **Native context menus** (#542, #544, #545, #547) — `nativeContextMenu = true` on
  `DecoratedWindow` / `HostedWindow` replaces the Compose-drawn context menu with the platform's:
  a real `NSMenu` on macOS, and a Compose flyout styled as Fluent on Windows, Adwaita on GTK
  desktops, and Breeze on Qt desktops. Covers `ContextMenuArea`, text-field Cut/Copy/Paste, and
  spellcheck items. Tao backend only; accepted and ignored on AWT. See
  [Context menus](/docs/window/context-menu#turn-on-the-native-menu).
    - `NucleusContextMenuItem`, `NucleusContextMenuDivider`, and `NucleusContextMenuSubmenu` build
      items with icons and lazy submenus. See
      [Add your own items](/docs/window/context-menu#add-your-own-items).
    - Stock icons carry their platform shortcut label (`⌘C` / `Ctrl+C`), overridable per item.
      Drawn on the Windows and Linux flyouts. See
      [Show keyboard shortcuts](/docs/window/context-menu#show-keyboard-shortcuts).
    - New `LinuxUiToolkit` in `core-runtime` reports whether the session is Gtk or Qt, which is
      also how the Linux menu style is chosen. See
      [Detect the Linux toolkit](/docs/window/context-menu#detect-the-linux-toolkit).
    - `menu-macos` gained the popup primitives behind it: `NativePopupMenuItem`,
      `popUpNativeMenu`, `isNativePopupMenuAvailable`.
- **Overlay windows** (#564, #568) — new window flags for watermarks, desktop widgets, and
  heads-up overlays: `clickThrough` (pointer events pass through), `alwaysOnBottom` (below normal
  windows, mutually exclusive with `alwaysOnTop`), and `visibleOnAllWorkspaces`. All three are
  reactive, with imperative `TaoWindow` setters alongside. See
  [Overlay windows](/docs/tao/overlay-windows#build-a-click-through-watermark).
    - `transparent` is now exposed on the backend-agnostic `DecoratedWindow` and the Material and
      Jewel window wrappers, not just the Tao composable. A fully transparent window drops the
      contour that traced the rectangular window instead of the content, and Compose scenes are
      told the window is transparent so dialog scrims blend against alpha (#559, #561).
    - `forceX11` gives one window an XWayland surface without moving the whole process off
      Wayland, and `TaoWindow.isNativeWaylandSurface` reports what it actually got. Flags that
      cannot work on a native Wayland surface log once per window with the reason. See
      [Take an X11 surface on Wayland](/docs/tao/overlay-windows#take-an-x11-surface-on-wayland).
- **Compose over native views** (#587) — the `NativeView` `content` slot now draws in the
  window's own Compose scene on all three platforms, so Compose siblings declared after the view
  and in-scene `Popup`s paint over it, and overlay content claims its own pointer events. Linux
  supports the `content` slot at all for the first time (Wayland only).
  `Modifier.consumeOverlayPointerEvents()` is deprecated and no longer needed. See
  [Overlay Compose content](/docs/tao/native-views#overlay-compose-content).
- **Linux clipboard through GTK** (#582, #583) — the Tao clipboard on Linux goes through GDK
  instead of AWT, so copy and paste work in a Wayland-native window and in a session with no
  XWayland. Images (as PNG) and file lists (`text/uri-list` plus the GNOME copied-files target)
  are carried in both directions alongside plain text. No API change: use Compose's
  `LocalClipboard`. See [Copy and paste](/docs/tao/wayland#copy-and-paste).
- **`EnergyManager.acquireAwake`** — returns an `AwakeHandle` that holds one awake request until
  it is closed, so independent features can each keep the machine awake without releasing each
  other. `keepAwake` keeps its single last-writer-wins slot. This also backs Compose's
  `Modifier.keepScreenOn`, which the Tao backend now implements. See
  [Hold several awake requests at once](/docs/lifecycle/energy-manager#hold-several-awake-requests-at-once).
- **Custom scheduler command** (#540) — `SchedulerConfig.executablePath` and
  `executableArguments` point the OS scheduler at a custom launcher instead of the current
  executable. Set them before the first `enqueue`; values are baked into the generated
  plist, unit, or task. See [SchedulerConfig](/docs/lifecycle/scheduler#schedulerconfig).
- **Compose 1.12** (#354, #550, #551, #555) — `decorated-window-tao` moves to Compose
  Multiplatform 1.12, with frames driven through `SingleComposeSceneRenderingScope` and the new
  `RectManager` delayed dispatch kept off the AWT event thread.
- **`jdk.unsupported` in the default runtime modules** — `sun.misc.Unsafe` is required by JNA,
  Jewel, and many common libraries, so the module is included by default rather than discovered
  through a runtime failure. See the
  [`nativeDistributions { }` reference](/docs/start/configuration#nativedistributions---reference).

### Breaking changes

- **`GenericProvider` requires `https`** — a non-`https` update origin now throws
  `IllegalArgumentException` at construction. The manifest, checksums, and artifact all come from
  that one origin, so plain `http` lets an on-path attacker rewrite the three together and the
  SHA-512 protects nothing. `http` is still accepted for loopback hosts so integration tests can
  serve fixtures without TLS. See [Providers](/docs/packaging/auto-update#providers).

### Bug fixes

- **Self-update scripts written to a private directory** — the detached update script and its log
  went to a fixed path in the shared temp directory (`/tmp/nucleus-update.sh` on Linux), which
  another local user can pre-create as a symlink or a file they own, turning the update into local
  code execution as the app's user. Each run now gets a fresh owner-only (`0700`) directory.
- **Windows update script escaping** — manifest-derived paths are escaped before they reach
  PowerShell.
- **Linux root update helper** — closed a time-of-check/time-of-use window and a downgrade path
  in the privileged helper.
- **Linux update helper leaked a gpg-agent** — the signature check no longer leaves a gpg-agent
  running inside the app's systemd scope.
- **MPRIS invalid D-Bus name** (#548) — an app id that is not a valid D-Bus name no longer hangs
  media-control startup on Linux.
- **Context menu dismissal and first right-click** — the flyout closes when the owning window
  loses focus, and the macOS menu opens on the first right-click in an app that is not yet
  active.
- **Tao fixes** — the dialog close button animates its hover like `DecoratedWindow`; a native
  session that swallows a mouse-up no longer leaves a stuck button; Adwaita separators follow
  libadwaita's `currentColor` rule.

---

## v2.4.7

**Released: 2026-08-17**

### Bug fixes

- **Windows SMTC local cover art** (#552) — a `file://` `coverUrl` (or a bare path) now
  appears in the Windows media flyout. `CreateFromUri` never opens local files, so SMTC
  kept a blank square. Local covers go through `CreateFromFile`; remote `http`/`https`
  URLs are unchanged. See
  [Publish now-playing metadata](/docs/os/media-control#publish-now-playing-metadata).

---

## v2.4.6

**Released: 2026-08-16**

### Bug fixes

- **macOS fullscreen minimize button** (#539 / #531) — replacement traffic lights in
  native fullscreen cannot miniaturize the window. The minimize button is disabled so
  it no longer looks clickable; close and zoom stay on the same hover path. At rest
  the copies paint the standard active colours instead of inactive gray. See
  [Window controls](/docs/tao/window-scaffold#window-controls).

---

## v2.4.5

**Released: 2026-08-16**

### Bug fixes

- **`Dp.Unspecified` wrap-content window size** (#535) — `DecoratedWindow` no longer
  passes NaN through to the native surface when a `WindowState` / `DialogState` axis is
  `Dp.Unspecified`. Wrap-content axes are measured after the first composition and
  applied, matching Compose Desktop. See
  [DecoratedWindow parameters](/docs/tao/decorated-window#decoratedwindow-parameters).
- **Linux discrete mouse-wheel scroll** (#533) — GDK only fills `delta_x` / `delta_y`
  for smooth (trackpad) events. A discrete wheel notch arrived with a zero delta, so
  Compose never scrolled. Direction is now mapped to a unit delta.
- **Win11 caption-button hover fade** (#537) — platform caption buttons use the system
  hover fade duration. See
  [Window controls](/docs/tao/window-scaffold#window-controls).

---

## v2.4.4

**Released: 2026-08-14**

### Bug fixes

- **Win11 CSD corners clipped** (#527) — windowed CSD draws the 8px rounded contour
  through DWM so the Compose frame is not clipped at the corners. See
  [DecoratedWindow notes](/docs/tao/decorated-window#notes).
- **macOS press-and-hold accent picker** (#529 / #530) — key-repeat now reaches
  `interpretKeyEvents:`, so AppKit's PressAndHold menu opens. Picking an accent
  replaces the already-committed base letter (`e` → `é`) instead of appending.
- **Windows multi-monitor popup DPI** (#528) — popups and `DecoratedDialog` pick up
  the target monitor's DPI and work-area constraints when they open on a different
  display from the owner. See [Per-monitor HiDPI notes](/docs/tao/hidpi#notes).

---

## v2.4.3

**Released: 2026-08-13**

### Bug fixes

- **Windows CSD frame hidden by DWM** (#523 / #522 / #520) — windowed CSD (no Mica/Acrylic)
  clears only the DWM border fill so the Compose frame stroke is visible, while the Win11
  8px rounded clip and drop shadow stay. See
  [DecoratedWindow notes](/docs/tao/decorated-window#notes).
- **`appResources` missing from GraalVM native packages** (#524) — `prepareAppResources` is
  copied next to the native binary and `compose.application.resources.dir` is set for
  `packageGraalvmNative` and `runWithNativeAgent`. Sidecars such as Dawn's `dxil.dll` load
  the same way as `run` / jpackage. See
  [GraalVM tasks — metadata, installers, and helpers](/docs/performance/graalvm/tasks-ci#metadata-installers-and-helpers).

---

## v2.4.2

**Released: 2026-08-12**

### Bug fixes

- **Windows sibling GPU cache purge** (#519 / #514) — resize-path Skia cache purges bind
  the host's own ANGLE context first, so a sibling window's `WM_PAINT` cannot leave another
  unshared context current and delete that window's glyph atlas and icons. See
  [GPU render context notes](/docs/tao/gpu-render-context#notes).
- **`nativeLinuxHandles` on Windows and macOS** (#518) — the Linux-only JNI entry is now
  platform-guarded. Detaching a tab into a popup with `WindowPosition.Absolute` no longer
  throws `UnsatisfiedLinkError`. See
  [DecoratedWindow parameters](/docs/tao/decorated-window#decoratedwindow-parameters).

---

## v2.4.1

**Released: 2026-08-12**

### Bug fixes

- **White region on Windows off-screen windows** (#516) — a window created partly off-screen
  no longer stays white in the previously clipped area after you drag it into view. Each
  `WM_MOVE` requests a full present so newly exposed pixels are filled.

---

## v2.4.0

**Released: 2026-08-11**

### Highlights

- **`TaoGpuRenderContext` — in-process GPU on the scene's device.** Map engines, 3D viewports,
  and charting can allocate render targets on the window's own Skia `DirectContext` and native
  device (Metal / ANGLE GLES / native EGL) with no second GPU, no shareable handle, and no
  per-frame cross-device copy. `TextureView` remains the contract for foreign producers. See
  [GPU render context](/docs/tao/gpu-render-context).
- **`AwakeMode` — keep the system awake without forcing the display.**
  `EnergyManager.keepAwake(AwakeMode.SYSTEM_ONLY)` lets the screen saver and display sleep behave
  normally during long background work. `keepScreenAwake()` remains as a deprecated forwarder.
  See [Keep the system awake](/docs/lifecycle/energy-manager#keep-the-system-awake).
- **Public ABI freeze.** Published runtime modules run under Kotlin `explicitApi()` with
  kotlinx binary-compatibility-validator baselines (`api/*.api`); `apiCheck` is part of
  `check` / `preMerge`. Exception: `decorated-window-jewel` until BCV can read JVM 25 class files.

### New features

- **`windows.msi { perMachine }`** (#480) — install-scope DSL aligned with `nsis { perMachine }`.
  `windows.perUserInstall` is deprecated (inverted meaning) but still works when `msi.perMachine`
  is unset. MSI remains per-machine by default. See
  [Build an MSI](/docs/packaging/windows#build-an-msi-for-enterprise-deployment).

### Improvements

- **Unified JUL logging and renamed tray log API** (#491) — runtime modules log through
  `java.util.logging`; `composeNativeTrayLoggingLevel` → `nucleusLoggingLevel` /
  `NucleusLoggingLevel` (deprecated aliases retained).
- **Safer updater construction** (#493) — provider validated at construction, config snapshotted,
  downloads staged privately instead of a predictable shared temp path. See
  [Auto-update](/docs/packaging/auto-update).
- **Windows outbound drag** (#482) — `DoDragDrop` deferred off Compose pointer dispatch so
  outbound drag frames paint without reentrancy. See
  [Drag and drop](/docs/tao/drag-and-drop).

### Bug fixes

- **macOS live-resize trembling** (#476) — content no longer trails AppKit bounds during corner
  resize.
- **Windows interactive resize lag** (#479) — VSync dropped through the modal resize loop so
  content tracks the border drag.
- **Frame-paced GPU through modal loops** (#489, #505) — keep VSync on Windows move/resize and
  Linux resize bursts when the scene hosts `TextureView` imports or `TaoGpuRenderContext`
  consumers. See [GPU render context](/docs/tao/gpu-render-context#frame-pacing).
- **macOS Metal render-thread leak** (#495) — autorelease pool around every render-thread task.
- **`LocalComposeSceneContext` under `DecoratedWindow`** (#499) — Popup / Dialog / DropdownMenu
  / Tooltip inside decorated window content no longer throw. See
  [DecoratedWindow](/docs/tao/decorated-window).
- **macOS overlay detach / focusable retain** (#496), **Wayland popup buffer_scale** (#508),
  **macOS scene density from the window's display** (#509), **zoom-button tiling hover menu**
  (#511), **RTL title-bar constraints while fullscreen** (#512).

---

## v2.3.2

**Released: 2026-08-07**

### New features

- **`HostedWindow` / `HostedDialog` composition hosts** (#473) — libraries and navigation
  open secondary windows without hard-coding Compose Desktop's AWT `Window`/`Dialog` or a
  specific design-system chrome. `nucleusApplication` provides
  `LocalNucleusWindowHost` / `LocalNucleusDialogHost` (defaults: `DecoratedWindow` /
  `DecoratedDialog`); override the host to inject Material, Jewel, or app chrome. See
  [Hosted windows](/docs/tao/decorated-window#hosted-windows).

### Bug fixes

- **Secondary window drag and system controls** (#472) — re-provide `LocalTaoWindow` and
  `LocalTitleBarInfo` after bridging parent locals into a secondary Tao scene so title-bar
  drag, double-click maximize, and min/max/close bind to the child window. `BasicTitleBar`
  uses `Modifier.windowDragArea(window)` so drag does not depend on a parent
  `LocalTaoWindow`. See
  [Open a window from composition](/docs/tao/decorated-window#open-a-window-from-composition)
  and [Drag areas](/docs/tao/window-scaffold#drag-areas).
- **Wayland `popupFor` CSD content origin** (#474) — `TaoWindow.setOuterPosition` adds the
  parent hidden-titlebar CSD content origin for native Wayland popup overlays, so
  content-space coordinates (tab ghosts, HUDs) no longer drift by the theme shadow margin.
  In-scene popup layers no longer double-apply that offset. See
  [DecoratedWindow parameters](/docs/tao/decorated-window#decoratedwindow-parameters).

---

## v2.3.1

**Released: 2026-08-06**

### New features

- **XDG Desktop Portal parent for Tao windows** (#466) — `TaoWindow.xdgPortalParent()`,
  `x11PortalParent` / `x11WindowId`, and `exportXdgForeignHandle()` / `XdgForeignExport`
  so FileKit and other portal clients can parent file choosers on X11 and Wayland
  (`x11:<hex>` / `wayland:<token>`). See [Native file dialogs](/docs/ecosystem/file-dialog#parent-a-dialog-to-the-tao-window).
- **`TaoWindow.nsWindowHandle` on macOS** (#469) — owning `NSWindow*` for sheet /
  dialog parenting (`beginSheetModalForWindow:`); distinct from `nativeHandle` which is
  the Compose host `NSView*`. See
  [Native file dialogs](/docs/ecosystem/file-dialog#parent-a-dialog-to-the-tao-window).
- **Per-format compression for AppImage and Windows portable** (#468) —
  `linux.appImage { compressionLevel }` and `windows.portable { compressionLevel }`
  override the root `nativeDistributions.compressionLevel`, so DEB/DMG can stay on
  `Ultra` while AppImage/portable use `Normal` or `Store`. See
  [Build an AppImage](/docs/packaging/linux#build-an-appimage) and
  [Portable mode](/docs/packaging/windows#enable-portable-mode).

### Improvements

- **L1 GraalVM metadata expansion** (#470) — richer ktor (client plugins, server,
  websockets), new `androidx-sqlite-bundled` pack, broader JDK FFM/VarHandle/Module
  coverage, `AtomicInt` / `AtomicRef` and `kotlin.kotlin_builtins`. See
  [Automatic metadata](/docs/performance/graalvm/automatic-metadata#level-1--per-library-metadata).
- **Kotlin agent phantoms always dropped on cleanup** (#470) — tracing-agent mapped
  types (`kotlin.Any`, `kotlin.Int`, `FunctionN`, collections) are removed during
  `cleanupGraalvmMetadata` without needing `removeUnresolvable`. See
  [Clean up manual entries](/docs/performance/graalvm/automatic-metadata#clean-up-manual-entries).

### Bug fixes

- **KMP named JVM targets and orphan detection** (#467) — project-class / orphan
  detection uses the application target's compilation outputs
  (`jvm("desktop")` → `desktopMainClasses`) instead of hardcoded `jvm`/`main` paths;
  nest-internal edges no longer hide real Room `*_Impl` classes. See
  [Detect orphan project classes](/docs/performance/graalvm/automatic-metadata#detect-orphan-project-classes).
- **Linux NativeView opaque region** (#471) — clear the full-surface opaque region while
  a `NativeView` is attached so GTK (e.g. WebKit) shows through the EGL subsurface again
  after #447. See [Native views](/docs/tao/native-views).
- **Linux NativeView overlay click offset** (#471) — `consumeOverlayPointerEvents` maps
  pointer events into content coordinates (window bin), matching CSD shadow-margin
  normalisation. See
  [Overlay Compose content](/docs/tao/native-views#overlay-compose-content).

---

## v2.3.0

**Released: 2026-08-06**

### Highlights

- **`TextureView` — external GPU textures in the Compose scene.** Composite decoder or engine
  frames with real z-order, clipping, and `graphicsLayer` transforms, and no CPU frame copy.
  Windows uses ANGLE/D3D11 shared handles, macOS Metal/`IOSurface`, Linux DMA-BUF/`EGLImage`
  (including planar YUV I420/YV12). Frame updates go through `TextureViewController.markFrameAvailable`
  (draw-only invalidation). See [TextureView](/docs/tao/texture-view),
  [platform sources](/docs/tao/texture-view#platform-sources), and
  [how it works](/docs/tao/texture-view#how-it-works).
- **Per-platform notification options on the common DSL.** `notification { }` accepts
  `linux { }`, `macos { }`, and `windows { }` blocks applied only on the matching OS
  (urgency, interruption level, toast scenario, …). See
  [Platform-specific options](/docs/os/notifications#platform-specific-options).
- **Differential auto-update downloads.** `updater-runtime` reassembles installers from the
  previous artifact plus HTTP range requests for changed blocks (electron-builder block maps).
  On by default via `differentialDownload`. See
  [Differential downloads](/docs/packaging/auto-update#differential-downloads).
- **`LocalNucleusApplicationScope` and receiver-less windows.** Open secondary
  `DecoratedWindow` / `DecoratedDialog` from deep in the composition without threading the
  application receiver. See
  [Open a window from composition](/docs/tao/decorated-window#open-a-window-from-composition).
- **Live `isSystemInDarkTheme()` under `nucleusApplication`.** Compose's `LocalSystemTheme` is
  fed from `darkmode-detector`, so official and library call sites track OS theme changes.
  See [Bridge to Compose `isSystemInDarkTheme`](/docs/os/dark-mode#bridge-to-compose-issystemindarktheme).

### New features

- **`TextureView` + platform source factories** (#429 / #338) — `TextureView`,
  `TextureViewController`, `rememberTextureViewController`,
  `nucleusD3D11SharedTextureSource`, `nucleusIOSurfaceTextureSource` /
  `nucleusMetalTextureSource`, `nucleusDmaBufTextureSource` /
  `nucleusEglImageTextureSource` / `nucleusYuvDmaBufTextureSource`, plus Linux acquire-fence
  signalling. Samples: mediafoundation-demo, avfoundation-demo, gstreamer-demo. See
  [TextureView](/docs/tao/texture-view#show-a-texture).
- **Platform blocks on `notification { }`** (#436 / #397) — `LinuxNotificationScope`
  (`urgency`, `category`, `transient`, `resident`, `expireTimeout`),
  `MacNotificationScope` (`interruptionLevel`, `relevanceScore`, `subtitle`),
  `WindowsNotificationScope` (`scenario`, `duration`). See
  [Platform-specific options](/docs/os/notifications#platform-specific-options).
- **Differential downloads in `NucleusUpdater`** (#428) — uses published `.blockmap` companions
  (NSIS, macOS ZIP/DMG) and AppImage-embedded maps; `DownloadProgress.isDifferential`;
  `UpdaterConfig.differentialDownload` (default `true`) and `cacheDir`. See
  [Differential downloads](/docs/packaging/auto-update#differential-downloads) and
  [Builder fields](/docs/packaging/auto-update#builder-fields).
- **`LocalNucleusApplicationScope`** (#449 / #438) — CompositionLocal provided by
  `nucleusApplication` on AWT and Tao; receiver-less `DecoratedWindow` / `DecoratedDialog`
  overloads. See
  [Open a window from composition](/docs/tao/decorated-window#open-a-window-from-composition).
- **System theme bridge** (#463) — `ProvideNucleusSystemTheme` wires `isSystemInDarkMode()` into
  `LocalSystemTheme`; `darkmode-detector` is an `api` dependency of `nucleus-application`. See
  [Bridge to Compose `isSystemInDarkTheme`](/docs/os/dark-mode#bridge-to-compose-issystemindarktheme).
- **Exact reachability metadata on the GraalVM dev loop** (#453 / #440) —
  `graalvm { exactReachabilityMetadata = ExactReachabilityMetadata.APP_PACKAGES }` (default)
  on `runGraalvmNative` only; `-Pnucleus.graalvm.missingRegistration=warn|exit|throw`. See
  [Exact reachability on the dev loop](/docs/performance/graalvm/configuration#exact-reachability-on-the-dev-loop).
- **Orphan project-class detection** (#460 / #441) —
  `detectOrphanProjectClasses` (default `true`) registers public no-arg constructors for
  reflectively-only types (Room `*_Impl`, …); opt-in `reflectionForProjectClasses`. See
  [Detect orphan project classes](/docs/performance/graalvm/automatic-metadata#detect-orphan-project-classes).
- **GraalVM innovation channel defaults to 25.2** (#432) — `GraalvmChannel.INNOVATION` resolves
  to `25i2`. See [Provision the toolchain](/docs/performance/graalvm/configuration#provision-the-toolchain).

### Improvements

- **Silent DEB/RPM self-update packaging** (#457) — `nucleus-update-helper` ships in the package
  payload so `dpkg -S` / `rpm -qf` attribute it; afterInstall only installs polkit; detached
  `*.asc` uploaded next to packages. See
  [Passwordless updates on Linux](/docs/packaging/auto-update#set-up-passwordless-updates-on-linux).
- **AppImage post-update relaunch** (#465 / #178) — replace-in-place while the old mount holds,
  clean environment on restart (`APPDIR` / `LD_LIBRARY_PATH` unset). See
  [Supported formats](/docs/packaging/auto-update#supported-formats).
- **Linux portal global hotkeys** (#455 / #264) — stable `shortcut_id` from modifiers+keyCode,
  debounced `BindShortcuts`, `GlobalHotKeyManager.commitRegistrations()` and `portalShortcutId`.
  See [Linux portal registrations](/docs/os/global-hotkey#linux-portal-registrations).
- **Unresolvable cleanup metadata reporting** (#461 / #439) — `cleanupGraalvmMetadata` reports
  types that resolve nowhere; optional
  `-Pnucleus.graalvm.cleanup.removeUnresolvable=true`. See
  [Clean up manual entries](/docs/performance/graalvm/automatic-metadata#clean-up-manual-entries).
- **Metadata dirs as `nativeImageCompile` inputs** (#459 / #431) — editing reachability metadata
  invalidates the native image task instead of serving a stale binary.
- **`mlProfileInference = false` gated on Oracle** (#458 / #452) — community toolchains skip
  `-H:-MLProfileInference` (unrecognized) with a warning. See
  [graalvm { } reference](/docs/performance/graalvm/configuration#graalvm---reference).

### Bug fixes

- **Outbound OS drag freezes the Tao host** (#434) — Windows, macOS, and Linux keep the render
  loop alive during `DoDragDrop` / AppKit / GTK drag via a shared `DragPump`. See
  [Drag and drop](/docs/tao/drag-and-drop).
- **Wayland resize flash / shift** (#462 / #444) — paint at last drawable size until
  `wl_egl_window_resize` applies on the next present. See [Wayland](/docs/tao/wayland).
- **Linux Compose subsurface opaque region** (#447 / #446) — `wl_surface.set_opaque_region`
  with transparent corners preserved for the CSD shadow.
- **Linux jpackage SIGSEGV on long classpaths** (#456 / #454) — after `jpackage`, multi-entry
  `app.classpath` is collapsed into a pathing jar (JDK-8380085 workaround).
- **FSEvents roots reached through a symlink** (#448 / #442) — macOS temp dirs under `/var` →
  `/private/var` deliver events again. See [Filesystem watcher](/docs/lifecycle/fs-watcher).
- **SLF4J no longer forced to build-time init** (#450 / #443) — avoids image-heap failures with
  run-time SLF4J 2.x backends; opt in via `buildArgs` if you want build-time init. See
  [Set build arguments](/docs/performance/graalvm/configuration#set-build-arguments).
- **`runWithNativeAgent` toolchain mismatch** (#451 / #437) — forks through `JavaLauncher`
  instead of a conflicting `executable` property.
- **Linux popup / tray panel EGL neutrality** (TextureView series / #350) — popup layers and
  tray panels no longer break the window EGL binding; Wayland popups offset by CSD content origin.

### Samples

- **mediafoundation-demo**, **avfoundation-demo**, **gstreamer-demo** — end-to-end video into
  `TextureView` on Windows, macOS, and Linux (native-image builds for the GStreamer sample).

---

## 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](/docs/tao/window-scaffold), [chrome primitives](/docs/tao/window-scaffold#chrome-primitives), and [platform materials](/docs/tao/window-scaffold#platform-materials-and-appearance).
- **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](/docs/performance/graalvm/tasks-ci#public-surface-aligned-with-the-jvm-pipeline) and [output locations](/docs/performance/graalvm/tasks-ci#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](/docs/performance/graalvm/configuration#choose-a-garbage-collector) and the [Gradle DSL](/docs/reference/gradle-dsl#application----jvmapplication).

### 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](/docs/tao/window-scaffold#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](/docs/tao/window-scaffold#chrome-primitives), [drag areas](/docs/tao/window-scaffold#drag-areas), and [window controls](/docs/tao/window-scaffold#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](/docs/tao/window-scaffold#platform-materials-and-appearance), [macOS glass](/docs/tao/window-scaffold#macos-glass-regions), and [Windows 11 backdrops](/docs/tao/window-scaffold#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](/docs/tao/window-scaffold#transparent-and-borderless-overlays) and [DecoratedWindow on Tao](/docs/tao/decorated-window#scaffold-and-chrome-22).
- **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](/docs/tao/decorated-window#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](/docs/tao/accessibility#how-it-works).
- **`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](/docs/performance/graalvm/configuration#choose-a-garbage-collector) and [Gradle DSL — GraalVM](/docs/reference/gradle-dsl#graalvm--graalvmsettings).
- **`NucleusApplicationScope` implements Compose `ApplicationScope`** (#372) — libraries scoped to plain `ApplicationScope` (for example ComposeNativeTray) resolve inside `nucleusApplication { }` without a separate overload set. See [DecoratedWindow notes](/docs/tao/decorated-window#notes).

### Ecosystem (separate repos)

Published around the 2.2 line; versioned independently of Nucleus:

- **[compose-macos-26-ui](https://github.com/NucleusFramework/compose-macos-26-ui)** — macOS 26 design system + `MacosDecoratedWindow`. Docs: [macOS toolkit](/docs/window/toolkit-macos).
- **[compose-fluent-ui](https://github.com/NucleusFramework/compose-fluent-ui)** — Fluent Design + `FluentDecoratedWindow`. Docs: [Fluent toolkit](/docs/window/toolkit-fluent).
- **[yaru-compose-ui](https://github.com/NucleusFramework/yaru-compose-ui)** — Yaru / GNOME design system + `YaruDecoratedWindow`. Docs: [Yaru toolkit](/docs/window/toolkit-yaru).

### 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](/docs/tao/hidpi).

### Bug fixes

- **NsView `setBounds` / resize on layout changes** (#421) — embedded macOS native views update their frames when Compose layout changes. See [Native views](/docs/tao/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](/docs/lifecycle/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.1-262.9437.29`, 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](/docs/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 &lt; 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.

```kotlin
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](/docs/lifecycle/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](/docs/lifecycle/app-metadata).

### 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](https://github.com/oracle/graalvm-reachability-metadata). 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](/docs/performance/graalvm/automatic-metadata#how-the-sources-merge).

- **`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](/docs/packaging/auto-update#result-and-level-types).

- **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](/docs/packaging/auto-update#post-update-detection).

- **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](/docs/performance/graalvm/automatic-metadata#clean-up-manual-entries).

- **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](/docs/performance/graalvm/configuration#no-release-variant).

---

## 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](/docs/performance/graalvm/configuration#graalvm---reference).

---

## 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](/docs/packaging/macos#enable-liquid-glass-on-sdk-26).
- **`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](/docs/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](https://github.com/NucleusFramework/Nucleus/issues/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](/docs/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](/docs/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](/docs/os/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](/docs/lifecycle/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](/docs/window).
- **macOS RTL traffic-light support** — Correct traffic light button positioning in right-to-left layouts. See [Decorated Window](/docs/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](/docs/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](https://github.com/NucleusFramework/Nucleus/issues/79))
- **Skip ZIP stapling to preserve blockmap** — Prevents breaking auto-update blockmap integrity during notarization. ([#70](https://github.com/NucleusFramework/Nucleus/issues/70))
- **Detect target arch from JDK release file for cross-building** — Fixes architecture detection when cross-compiling. ([#71](https://github.com/NucleusFramework/Nucleus/issues/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](https://github.com/NucleusFramework/Nucleus/issues/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](https://bell-sw.com/liberica-native-image-kit/). See [GraalVM Native Image](/docs/performance/graalvm).
- **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](#migration-guide-12x--13x) 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:

```kotlin
implementation("dev.nucleusframework:nucleus.decorated-window:<version>")
```

With one of:

```kotlin
// JBR-based (same behavior as before)
implementation("dev.nucleusframework:nucleus.decorated-window-jbr:<version>")

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

**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](/docs/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](/docs/packaging/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](/docs/performance/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](/docs/performance/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](/docs/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](/docs/os/dark-mode).
- **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](/docs/migrate/from-1.x) — the plugin id, namespace, and API changes for the 2.0 upgrade.
- [Quickstart](/docs/start/quickstart) — build and run your first Nucleus app.
- [GraalVM Native Image](/docs/performance/graalvm) — the native-image pipeline referenced throughout these notes.
- [Auto-update](/docs/packaging/auto-update) — the updater APIs mentioned across several releases.