docs(CLAUDE): document the parity harness + how to read the %differ

Explains running scripts/parity, the one-process JVM / per-screen native
mechanics, the build/parity outputs, and — the load-bearing part — what
the number means: it's a font-drift-inflated ranking signal, not a
pass/fail score. Ghosted text + dark shapes = normal; a solid bright
block or one-sided shape = regression. Baseline gradient ~2%..32%; known
SDL gaps (solid gradients, effects) inflate specific screens.

.github/workflows/publish.yml

@@ -18,9 +18,8 @@ jobs:
     strategy:
       fail-fast: false
       # Each host runs only the publish tasks Gradle actually generated for it.
-      # macOS also publishes the shared kotlinMultiplatform metadata module.
-      # No library module declares jvm() today — apps do their own JVM parity
-      # build against upstream Compose, so JVM isn't part of the publication.
+      # WINDOWS also publishes the shared kotlinMultiplatform metadata modules
+      # (see its matrix entry) + the jvm jar + the bridge plugin.
       # `target` is the Gradle K/N target token (Capitalised) — one per host,
       # used for :demo / :apidemo linkReleaseExecutable<Target>. linuxArm64 is
       # skipped for the app build because SDL3 static libs on the ubuntu runner
@@ -31,16 +30,8 @@ jobs:
             host: macos
             target: MacosArm64
             exe_ext: kexe
-            # jvm publication: only :material-symbols declares a jvm() target
-            # (its common API renders via upstream Compose on JVM) — publish
-            # its host-independent jar from the same host as the metadata.
-            # :compose-desktop-native-bridge (the consumer-side bridge Gradle plugin +
-            # its plugin marker) is host-independent too — same job.
             tasks: >-
-              publishKotlinMultiplatformPublicationToGitHubPackagesRepository
               publishMacosArm64PublicationToGitHubPackagesRepository
-              publishJvmPublicationToGitHubPackagesRepository
-              :compose-desktop-native-bridge:publishAllPublicationsToGitHubPackagesRepository
           - runner: ubuntu-22.04
             host: linux
             target: LinuxX64
@@ -52,8 +43,18 @@ jobs:
             host: windows
             target: MingwX64
             exe_ext: exe
+            # WINDOWS owns the root KotlinMultiplatform metadata modules: it is
+            # the ONLY host that declares every target (vHostSupportsMingw is
+            # host-gated), so only its generated .module files carry the full
+            # variant table — the macOS-published roots of v0.1.15 had NO
+            # mingwX64 variants and Windows consumers could not resolve them.
+            # The host-independent jvm jar (:material-symbols) and the bridge
+            # plugin ride along on the same job.
             tasks: >-
               publishMingwX64PublicationToGitHubPackagesRepository
+              publishKotlinMultiplatformPublicationToGitHubPackagesRepository
+              publishJvmPublicationToGitHubPackagesRepository
+              :compose-desktop-native-bridge:publishAllPublicationsToGitHubPackagesRepository
 
     runs-on: ${{ matrix.runner }}
 
@@ -148,8 +149,8 @@ jobs:
       # already completed; you can't tell from the 409 alone. The fix: between
       # attempts, DELETE this host's package versions for the current release
       # and re-upload from a clean slate. Each host owns DISJOINT package
-      # names (roots / -macosarm64 / -jvm / bridge on macOS, -mingwx64 on
-      # Windows, -linuxx64/-linuxarm64 on Linux), so parallel jobs never touch
+      # names (roots / -mingwx64 / -jvm / bridge on Windows, -macosarm64 on
+      # macOS, -linuxx64/-linuxarm64 on Linux), so parallel jobs never touch
       # each other's uploads. Uses the run's GITHUB_TOKEN (packages: write);
       # a 403 on delete just degrades to the old blind-retry behaviour.
       - name: Publish to GitHub Packages
@@ -161,9 +162,9 @@ jobs:
           # Keep in sync with the module list in settings.gradle.kts.
           MODULES="ui ui-util ui-geometry ui-unit ui-backhandler ui-tooling-preview animation animation-core animation-graphics foundation foundation-layout material3 material-ripple window material-symbols navigation3-ui components-resources"
           case "${{ matrix.host }}" in
-            macos)   SUFFIXES="_ROOT_ -macosarm64" ;;
+            macos)   SUFFIXES="-macosarm64" ;;
             linux)   SUFFIXES="-linuxx64 -linuxarm64" ;;
-            windows) SUFFIXES="-mingwx64" ;;
+            windows) SUFFIXES="_ROOT_ -mingwx64" ;;
           esac
           host_packages() {
             for m in $MODULES; do
@@ -171,7 +172,7 @@ jobs:
                 if [ "$s" = "_ROOT_" ]; then echo "com.bitsycore.compose.sdl.$m"; else echo "com.bitsycore.compose.sdl.$m$s"; fi
               done
             done
-            if [ "${{ matrix.host }}" = "macos" ]; then
+            if [ "${{ matrix.host }}" = "windows" ]; then
               echo "com.bitsycore.compose.sdl.material-symbols-jvm"
               echo "com.bitsycore.compose.sdl.compose-desktop-native-bridge"
               echo "com.bitsycore.compose-desktop-native.bridge.com.bitsycore.compose-desktop-native.bridge.gradle.plugin"

CLAUDE.md

@@ -275,11 +275,15 @@ commonMain
                    attached to: mingwX64Main always; macOS/Linux when -Prenderer=sdl3.
 ```
 
-`createRenderBackend(…)` + `rendererPreferredGpuMode()` are declared identically
-in both `skikoRendererMain` and `sdlRendererMain`. `:window` calls them straight
-from `:ui` — no `expect`/`actual`, no factory layer — and the right impl
-resolves because **only one of the two renderer source sets is attached to a
-given target**. Under `-Prenderer=sdl3`, the `skikoRenderer*` source sets are
+`createRenderBackend(…)` + `rendererPreferredGpuMode()` are `expect`s in
+`:ui`'s nativeMain with `actual`s in BOTH `skikoRendererMain` and
+`sdlRendererMain` — unambiguous because **only one of the two renderer source
+sets is attached to a given target**. (They used to be plain duplicate
+declarations with no expect; that compiled per-target but shared nativeMain
+METADATA couldn't see them on a host whose targets span both renderers, which
+blocked the WINDOWS host from producing :window's KotlinMultiplatform
+publication — and Windows must publish the root modules, see the publish
+workflow.) Under `-Prenderer=sdl3`, the `skikoRenderer*` source sets are
 **not even created**, so Gradle has nothing to warn about and Skiko is never
 pulled in.
 
@@ -454,6 +458,46 @@ build tell you what broke.
   `Dialog` / `DropdownMenu` / `DropdownMenuItem` / `TooltipBox` (m3 doesn't
   ship drop-in equivalents for our anchor / scrim patterns).
 
+## Parity harness — native-vs-JVM screenshot diff
+
+`:demo` renders the **same commonMain screens** on two stacks: native
+(SDL/Skia, Kotlin/Native) and a `jvm()` target on upstream Compose Desktop.
+`scripts/parity/parity.py` screenshots every screen on both and pixel-diffs
+them, so a screen that visually diverges is a **port regression** (missing
+content, wrong shape/colour, broken clip). Several past renderer regressions
+would have been caught here.
+
+```bash
+python scripts/parity/parity.py                 # all screens (builds first)
+python scripts/parity/parity.py Buttons Shapes  # a subset
+python scripts/parity/parity.py --no-build      # reuse the last renders
+```
+
+Mechanics: the JVM leg renders all screens headlessly via `ImageComposeScene`
+in ONE process (`:demo:run --args=--screenshot-all=<dir>`, wired in
+`MainJvm.kt`); the native leg launches the exe once per screen
+(`--screen=<Name> --screenshot=<x>.bmp`). Output lands in **`build/parity/`
+(gitignored)**: `<pct>_<Name>_diff.png` (amplified difference heatmap),
+`<pct>_<Name>_compare.png` (native ∣ jvm ∣ diff, side by side), and
+`report.txt` ranked worst-first. Windows-only for the native leg today; needs
+Pillow. See `scripts/parity/README.md`.
+
+**What the number means — read this before trusting it.** The `%differ` is the
+fraction of pixels whose per-channel difference exceeds a tolerance. It is NOT
+a pass/fail score and pixel-perfection is not the goal: the two stacks use
+different default fonts, so **every screen carries a steady baseline
+difference** — in the heatmap, text shows as a faint *doubled ghost* from
+slightly different line metrics/baselines. A healthy full sweep is a smooth
+gradient (~2% for a sparse screen like Counter, up to ~32% for a text-dense
+one like Tabs). Known SDL parity gaps also inflate specific screens
+predictably (Brushes ~23% — gradients render solid on SDL; Shadows / Canvas /
+GraphicsLayer — effect differences). **The signal is the RANKING and the
+delta from a screen's own history**, not the absolute value: a text-light
+screen suddenly reading 60%, or a screen jumping far above its neighbours, is
+the bug. In a `_diff.png`: ghosted/doubled text + dark shapes = normal font
+drift; a **solid bright block, or a shape present on only one side** = a real
+regression — open the `_compare.png` to see which stack is wrong.
+
 ## Conventions
 
 Kotlin standard style — plain `camelCase` for parameters, local variables,
@@ -512,7 +556,10 @@ that should surface in tooling.
   'Color'` / `Cannot access class ...` in `compileCommonMainKotlinMetadata`,
   while per-target compilation is fine). Declare EVERY artifact the common
   code touches DIRECTLY (ui-graphics, ui-text, ui-unit, …) and give each its
-  own bridge rule. Note only the macOS publish job compiles common metadata —
+  own bridge rule. Note only the WINDOWS publish job compiles common metadata
+  (it owns the root KotlinMultiplatform publications — the only host that
+  declares every target, so only its .module files carry the full variant
+  table; macOS-published roots left v0.1.15 without mingwX64 variants) —
   test with `gradlew :<module>:compileCommonMainKotlinMetadata` before tagging.
 - **`Path()` in commonMain returns different actuals per renderer** —
   the Skia renderer produces a `SkiaBackedPath` (wraps

ROADMAP.md

@@ -0,0 +1,91 @@
+# Renderer roadmap — fixes, performance, memory
+
+Grounded in the bubble-wrap findings (2026-07): lazy clips took the stress
+sheet from 23 → 39 FPS, but 75 Hz needs structural work; issue #2 showed that
+Cleaner-managed native memory starves when the Kotlin heap is quiet.
+
+## 1. Deterministic native-resource lifecycle
+
+Ownership closes resources the moment they're finished; GC stays as the
+safeguard, not the mechanism.
+
+- [x] **`NativeReleaseQueue`** — SDL calls are main-thread-only, so nothing may
+  destroy directly from a Cleaner or worker: release actions ENQUEUE, the main
+  loop DRAINS between frames. Cleaners become safe from any thread because
+  they only enqueue. Verified end-to-end (direct enqueue + a real
+  Cleaner→enqueue→drain cycle).
+- [x] **`SdlImageBitmap` textures** — previously never destroyed (manual SDL
+  memory, invisible to the GC nudge). A holder + Cleaner now enqueues
+  `SDL_DestroyTexture` / `SDL_DestroySurface` for the texture, render target
+  and never-realized decoded surface; explicit `close()` frees promptly.
+- [ ] **Wire `close()` into cache eviction** — the Cleaner is the current
+  release path for decoded/vector bitmaps (correct but GC-timed). Call
+  `SdlImageBitmap.close()` on image-cache eviction / `removeMemoryResource`
+  for prompt release (needs a cross-module hook — the caches hold the
+  `ImageBitmap` interface, not the concrete type).
+- [ ] **Cache-eviction closes (rest)** — every image/text cache closes what it
+  evicts (Sdl3ImageCache already does; sweep the rest, both renderers).
+- [ ] **Renderer `destroy()` chain** — window close synchronously frees every
+  pool (clip targets already do; text caches, image caches, shadow cache,
+  typefaces to follow).
+- [ ] **`SkiaImageBitmap.close()`** (surface + snapshot) + close-on-eviction in
+  the Skia caches. *Skia source sets build only on macOS/Linux — needs a mac
+  or CI leg to verify.*
+- [ ] **Demote the GC nudge** — once ownership does the work, stretch the 10s
+  interval / gate it on churn; it remains the backstop.
+
+Verification: `demo --leaktest`-style probe (cycle screens N times, print
+RSS; expect a plateau without GC sawtooth).
+
+## 2. SDL renderer performance (the 39 → 75 Hz path)
+
+- [x] **Frame profiler** — `CDN_PROFILE=1` env flag prints per-phase timings
+  (events / app pump / window pump / render / present) every ~2 s. Measure
+  first, optimize second.
+- [ ] **Right-size clip scratch targets** — the pool allocates window-sized
+  textures per mask depth; allocate at the clip bbox (size-bucketed pool) to
+  cut fill-rate for the masks that remain after lazy clips.
+- [ ] **Dirty-region rendering** — the big structural item: accumulate damage
+  from invalidated layers, scissor redraw to it. One bubble's spring should
+  not re-tessellate 84. Most likely single item to reach 75 Hz.
+- [ ] **Glyph atlas** — text draws currently break geometry batches (z-order
+  flush per run); an atlas texture lets glyphs ride the vertex batches.
+- [ ] **Retained layer textures** (later) — RenderNode-style caching of static
+  subtrees keyed by draw content.
+
+## 3. Skia renderer
+
+- [ ] Bounded `SkiaImageCache` (LRU + eviction close) — unbounded HashMap today.
+- [ ] Eager-close audit of the text pipeline (mirror of the SDL sweep).
+- [ ] `saveLayer` huge-bounds clamp (GPU offscreen memory spikes — see
+  CLAUDE.md pitfall).
+
+## 4. Correctness / parity gaps (future bug reports waiting)
+
+Ordered by likelihood of a user hitting them:
+
+- [ ] **Gradient brushes on SDL** — `Brush.linearGradient/radialGradient`
+  render solid; the per-vertex sampler infrastructure is half-present.
+- [ ] **Layer rotation** — rotationZ repositions but content doesn't rotate
+  (hit-testing too).
+- [ ] **Real `saveLayer` alpha on SDL** — overlapping content composites at
+  paint level; needs an offscreen (the clip-target pool can serve it).
+- [ ] **`clipPath` generic shapes** — bbox fallback clips square.
+
+## 5. Permanent tooling
+
+- [x] **Parity harness** — scripts/parity/: renders every :demo screen native +
+  JVM from the same commonMain composables, pixel-diffs, ranks by %differ,
+  emits per-screen diff heatmaps + side-by-side compares (pct in filename).
+  build/parity/ (gitignored). See scripts/parity/README.md.
+- [ ] Promote the press/hover automation rig (window-handle-relative input +
+  screenshot) into `scripts/`.
+
+## 6. Long-term
+
+- [ ] **SDL_GPU render backend** — real stencil clipping (no masks at all),
+  pipelined batching, shader gradients. Weeks of work across three
+  platforms; items 2–4 stay useful beneath it.
+
+Suggested order: profiler → lifecycle queue + leak closes → clip-target
+right-sizing → gradients → dirty regions → the rest by demand.

compose/sdl/window/src/nativeMain/kotlin/com/compose/sdl/ComposeWindow.kt

@@ -34,6 +34,8 @@ import kotlinx.coroutines.test.resetMain
 import kotlinx.coroutines.test.setMain
 import kotlinx.cinterop.reinterpret
 import sdl3.SDL_Delay
+import sdl3.SDL_GetPerformanceCounter
+import sdl3.SDL_GetPerformanceFrequency
 import sdl3.SDL_GetTicks
 import sdl3.SDL_Quit
 import sdl3.SDL_SetWindowTitle
@@ -148,7 +150,9 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 		//  Main loop
 		var vGcLastTicks = SDL_GetTicks()
 		var vRenderedSinceGc = false
+		val vProfiler = if (platform.posix.getenv("CDN_PROFILE") != null) FrameProfiler() else null
 		while (!runtime.exitRequested) {
+			vProfiler?.mark()
 			Snapshot.sendApplyNotifications()
 
 			// ============
@@ -176,6 +180,7 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 			}
 
 			mainDispatcher.drainPending()
+			vProfiler?.phase(0)
 
 			// ============
 			//  App composition pump — Window()s may appear / disappear here.
@@ -195,6 +200,7 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 			// Exit when the last window is gone (after at least one existed).
 			if (runtime.hadWindow && runtime.windows.isEmpty()) runtime.exitRequested = true
 			if (runtime.exitRequested) break
+			vProfiler?.phase(1)
 
 			// ============
 			//  Per-window pump + render.
@@ -208,13 +214,24 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 				Snapshot.sendApplyNotifications()
 				vW.frameClock.sendFrame()
 				yield()
+				vProfiler?.phase(2)
 				if (vW.shouldRender()) {
 					vW.renderFrame()
 					vAnyRendered = true
 					if (!vW.backend.vsyncEnabled) vAllVsync = false
 				}
+				vProfiler?.phase(3)
 			}
 			runtime.reapDestroyed()
+			vProfiler?.frameDone(vAnyRendered)
+
+			// ============
+			//  Drain deferred native-resource disposals on the MAIN thread —
+			//  textures/surfaces whose owner closed them or whose Cleaner fired
+			//  on a GC worker enqueue here (SDL calls aren't thread-safe). This
+			//  is the ownership path that makes the GC nudge below a mere
+			//  backstop (ROADMAP.md item 1).
+			com.compose.sdl.graphics.NativeReleaseQueue.drain()
 
 			// ============
 			//  Pace / idle-skip.
@@ -250,6 +267,7 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 		snapshotHandle.dispose()
 		for (vW in runtime.windows.toList()) runtime.scheduleDestroy(vW)
 		runtime.reapDestroyed()
+		com.compose.sdl.graphics.NativeReleaseQueue.drain()
 		appComposition.dispose()
 		appRecomposer.cancel()
 		appRecomposeJob.cancelAndJoin()
@@ -262,6 +280,47 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 	SDL_Quit()
 }
 
+/* CDN_PROFILE=1 — per-phase main-loop timings, printed every ~2s of rendered
+   frames. Phases: events (poll+dispatch), app (app-composition pump), pump
+   (per-window clocks/dispatch), render (layout+draw+present). Measure first,
+   optimize second — see ROADMAP.md. */
+@OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
+internal class FrameProfiler {
+	private val fFreq = SDL_GetPerformanceFrequency().toDouble()
+	private val fSum = DoubleArray(4)
+	private val fMax = DoubleArray(4)
+	private var fFrames = 0
+	private var fLastPrintMs = SDL_GetTicks()
+	private var fMark = 0uL
+
+	fun mark() { fMark = SDL_GetPerformanceCounter() }
+
+	fun phase(inIndex: Int) {
+		val vNow = SDL_GetPerformanceCounter()
+		val vMs = (vNow - fMark).toDouble() * 1000.0 / fFreq
+		fSum[inIndex] += vMs
+		if (vMs > fMax[inIndex]) fMax[inIndex] = vMs
+		fMark = vNow
+	}
+
+	fun frameDone(inRendered: Boolean) {
+		if (inRendered) fFrames++
+		val vNowMs = SDL_GetTicks()
+		if (vNowMs - fLastPrintMs >= 2000u && fFrames > 0) {
+			val vNames = listOf("events", "app", "pump", "render")
+			val vParts = vNames.mapIndexed { vI, vName ->
+				val vAvg = fSum[vI] / fFrames
+				"$vName=${(vAvg * 100).toInt() / 100.0}/${(fMax[vI] * 100).toInt() / 100.0}ms"
+			}
+			val vTotal = fSum.sum() / fFrames
+			println("[profile] frames=$fFrames avg/max " + vParts.joinToString(" ") + " total=${(vTotal * 100).toInt() / 100.0}ms")
+			for (vI in fSum.indices) { fSum[vI] = 0.0; fMax[vI] = 0.0 }
+			fFrames = 0
+			fLastPrintMs = vNowMs
+		}
+	}
+}
+
 /* Trigger a Kotlin/Native GC so Cleaner-managed renderer resources release
    their native memory (see the main loop's native-memory nudge). */
 @OptIn(kotlin.native.runtime.NativeRuntimeApi::class)

compose/ui/ui/src/nativeInterop/cinterop/sdl3.def

@@ -20,8 +20,13 @@ linkerOpts.osx = \
 	-framework QuartzCore -weak_framework CoreHaptics \
 	-lpthread -lm
 
-linkerOpts.linux_x64 = -lpthread -ldl -lm -lrt
-linkerOpts.linux_arm64 = -lpthread -ldl -lm -lrt
+# The -L multi-arch dirs + fontconfig/GL/X11 serve the SKIA renderer (font
+# matching, GL backend, windowing) — K/N's LLD sysroot doesn't include the
+# host's multi-arch dir, and carrying them here means apps (including bridge
+# consumers) need NO linker flags of their own. Unused under -Prenderer=sdl3;
+# the extra -l is harmless, and LLD skips missing -L dirs.
+linkerOpts.linux_x64 = -L/usr/lib/x86_64-linux-gnu -lpthread -ldl -lm -lrt -lfontconfig -lGL -lX11
+linkerOpts.linux_arm64 = -L/usr/lib/aarch64-linux-gnu -lpthread -ldl -lm -lrt -lfontconfig -lGL -lX11
 
 linkerOpts.mingw_x64 = \
 	-lm -lkernel32 -luser32 -lgdi32 -lwinmm -limm32 \

compose/ui/ui/src/nativeMain/kotlin/com/compose/sdl/RenderBackendFactory.kt

@@ -0,0 +1,24 @@
+package com.compose.sdl
+
+// ==================
+// MARK: Renderer entry points (expect)
+// ==================
+
+/* The renderer seam :window builds against. Each renderer source set
+   (skikoRendererMain / sdlRendererMain) supplies the actuals; exactly one of
+   the two is attached to any given target, so resolution stays unambiguous.
+
+   These were originally declared identically in both renderer source sets
+   with NO expect — fine per-target, but shared nativeMain METADATA (=: what
+   :window's KotlinMultiplatform publication compiles against) could not see
+   them on a host where the attached targets span BOTH renderers (Windows:
+   skikoRenderer for macos/linux + sdlRenderer for mingw). The expect makes
+   nativeMain metadata self-contained, which lets the WINDOWS publish job —
+   the only host that declares every target — produce the root modules. */
+
+/* Create the render backend for the selected [GpuMode]; null when the
+   backend can't initialise (caller falls back / reports). */
+expect fun createRenderBackend(inSdl: SDL3Backend, inGpu: GpuMode): RenderBackend?
+
+/* The renderer module's per-OS default GpuMode (used for GpuMode.Auto). */
+expect fun rendererPreferredGpuMode(): GpuMode

compose/ui/ui/src/nativeMain/kotlin/com/compose/sdl/graphics/NativeReleaseQueue.kt

@@ -0,0 +1,55 @@
+package com.compose.sdl.graphics
+
+import kotlinx.atomicfu.locks.SynchronizedObject
+import kotlinx.atomicfu.locks.synchronized
+
+// ==================
+// MARK: NativeReleaseQueue — main-thread-deferred native resource disposal
+// ==================
+
+/**
+ * A queue of native-resource release actions drained on the MAIN THREAD once
+ * per frame by the window loop (see ComposeWindow). It exists because the two
+ * ways a renderer resource dies are both off the main thread, while the calls
+ * that free them (SDL_DestroyTexture, and any renderer API) are main-thread-only:
+ *
+ *  - a Kotlin/Native `Cleaner` runs on a GC worker thread, and
+ *  - explicit `close()` can be reached from composition/effect code on other
+ *    dispatchers.
+ *
+ * Both simply ENQUEUE here; the main loop runs the actions between frames. This
+ * turns the GC (issue #2: Cleaner-managed native memory starving because the
+ * quiet Kotlin heap rarely triggers a collection) from the disposal MECHANISM
+ * into a mere safeguard — ownership closes resources promptly, the Cleaner is
+ * the backstop for whatever leaks a `close()`.
+ *
+ * Actions must be idempotent-safe at the source (guard against a resource being
+ * both explicitly closed and later GC-cleaned — see SdlImageBitmap's holder).
+ */
+object NativeReleaseQueue {
+
+	private val fLock = SynchronizedObject()
+	private var fPending = ArrayList<() -> Unit>()
+
+	/** Enqueue a release action. Safe to call from any thread. */
+	fun enqueue(action: () -> Unit) {
+		synchronized(fLock) { fPending.add(action) }
+	}
+
+	/**
+	 * Run and clear every queued action. MAIN THREAD ONLY — the actions call
+	 * renderer APIs that aren't thread-safe. Returns the number drained.
+	 */
+	fun drain(): Int {
+		val vBatch = synchronized(fLock) {
+			if (fPending.isEmpty()) return 0
+			val vTaken = fPending
+			fPending = ArrayList()
+			vTaken
+		}
+		for (vAction in vBatch) {
+			runCatching { vAction() }
+		}
+		return vBatch.size
+	}
+}

compose/ui/ui/src/sdlRendererMain/kotlin/com/compose/sdl/PlatformGpu.kt

@@ -6,7 +6,7 @@ import kotlin.experimental.ExperimentalNativeApi
 // MARK: SDL3 renderer per-OS default
 // ==================
 
-fun rendererPreferredGpuMode(): GpuMode {
+actual fun rendererPreferredGpuMode(): GpuMode {
     @OptIn(ExperimentalNativeApi::class)
     return when (Platform.osFamily) {
         OsFamily.MACOSX -> GpuMode.Sdl3.Metal

compose/ui/ui/src/sdlRendererMain/kotlin/com/compose/sdl/RenderBackendFactory.sdl.kt

@@ -11,7 +11,7 @@ import com.compose.sdl.renderer.sdl.Sdl3RenderBackend
    renderer modules expose createRenderBackend / rendererPreferredGpuMode
    with identical signatures in this package, and the build includes exactly
    one of them per target. Rejects Skia.* since this module has no Skiko. */
-fun createRenderBackend(inSdl: SDL3Backend, inGpu: GpuMode): RenderBackend? {
+actual fun createRenderBackend(inSdl: SDL3Backend, inGpu: GpuMode): RenderBackend? {
 	val vResolved = if (inGpu is GpuMode.Auto) rendererPreferredGpuMode() else inGpu
 	if (vResolved is GpuMode.Skia) {
 		error("$vResolved isn't available in this build — Skiko isn't linked. " +

compose/ui/ui/src/sdlRendererMain/kotlin/com/compose/sdl/renderer/sdl/Sdl3Canvas.kt

@@ -1,5 +1,6 @@
 package com.compose.sdl.renderer.sdl
 
+import androidx.compose.ui.geometry.CornerRadius
 import androidx.compose.ui.geometry.Offset
 import androidx.compose.ui.geometry.Rect
 import androidx.compose.ui.geometry.RoundRect
@@ -26,6 +27,7 @@ import com.compose.sdl.icons.IconFont
 import kotlinx.cinterop.*
 import sdl3.*
 import kotlin.math.PI
+import kotlin.math.sqrt
 import kotlin.math.cos
 import kotlin.math.max
 import kotlin.math.min
@@ -126,7 +128,7 @@ internal class Sdl3Canvas(
 	// offscreen clip opened inside this save frame (see fClipLayers below).
 	private data class State(
 		val a: Float, val b: Float, val c: Float, val d: Float, val e: Float, val f: Float,
-		val clip: IntArray?, val alpha: Float, val clipLayers: Int,
+		val clip: IntArray?, val alpha: Float, val clipLayers: Int, val pendingClips: Int,
 	)
 	private val fStack = ArrayDeque<State>()
 
@@ -146,9 +148,138 @@ internal class Sdl3Canvas(
 	)
 	private val fClipLayers = ArrayDeque<OffscreenClip>()
 
+	// ============
+	//  Lazy rounded clips. Opening an offscreen mask per clip is the SINGLE
+	//  most expensive thing this canvas does (two render-target switches +
+	//  clear + corner cut + feather + composite) - and the dominant Compose
+	//  idiom `Modifier.clip(CircleShape).background(...)` never needs one:
+	//  the background is a full-cover rect drawable AS the rounded shape, and
+	//  content wholly inside the rounded region needs no mask at all. So
+	//  clipRoundRect only RECORDS the clip; each draw either proves itself
+	//  safe (containment / cover) or realizes the offscreen on demand.
+
+	private class PendingRoundClip(
+		val deviceRound: RoundRect,   // device-space outline (clamped radii)
+		val localRound: RoundRect,    // as passed in (for cover -> shape-fill emission)
+		val region: IntArray,         // fClip intersect bbox at push time
+		val bbox: IntArray,           // device bbox of the outline
+		val prevClip: IntArray?,      // fClip before this clip was pushed
+		// Affine snapshot at push - cover -> fill re-emits in LOCAL space and
+		// must bail if the transform moved since.
+		val ma: Float, val mb: Float, val mc: Float, val md: Float, val me: Float, val mf: Float,
+		// fStack.size when the clip was pushed: a lazily-realized mask must be
+		// composited by the save-frame that OWNS the clip, not by whatever
+		// inner frame happened to trigger realization (a press draws the state
+		// layer and the ripple in separate inner clipRect{} frames - the first
+		// realize must not let the inner restore close the mask, or the second
+		// draw runs unmasked: the "square on click" artifact).
+		val saveDepth: Int,
+	)
+	private val fPendingClips = ArrayDeque<PendingRoundClip>()
+
+	/* Point-in-round-rect (device space) - inside the rect and, within a
+	   corner cut square, inside its ellipse. */
+	private fun roundRectContains(inRR: RoundRect, inX: Float, inY: Float): Boolean {
+		if (inX < inRR.left || inX > inRR.right || inY < inRR.top || inY > inRR.bottom) return false
+		fun corner(inRx: Float, inRy: Float, inDx: Float, inDy: Float): Boolean {
+			if (inRx <= 0f || inRy <= 0f) return true
+			val vNx = inDx / inRx; val vNy = inDy / inRy
+			return vNx * vNx + vNy * vNy <= 1f
+		}
+		val vTl = inRR.topLeftCornerRadius; val vTr = inRR.topRightCornerRadius
+		val vBr = inRR.bottomRightCornerRadius; val vBl = inRR.bottomLeftCornerRadius
+		if (inX < inRR.left + vTl.x && inY < inRR.top + vTl.y)
+			return corner(vTl.x, vTl.y, inX - (inRR.left + vTl.x), inY - (inRR.top + vTl.y))
+		if (inX > inRR.right - vTr.x && inY < inRR.top + vTr.y)
+			return corner(vTr.x, vTr.y, inX - (inRR.right - vTr.x), inY - (inRR.top + vTr.y))
+		if (inX > inRR.right - vBr.x && inY > inRR.bottom - vBr.y)
+			return corner(vBr.x, vBr.y, inX - (inRR.right - vBr.x), inY - (inRR.bottom - vBr.y))
+		if (inX < inRR.left + vBl.x && inY > inRR.bottom - vBl.y)
+			return corner(vBl.x, vBl.y, inX - (inRR.left + vBl.x), inY - (inRR.bottom - vBl.y))
+		return true
+	}
+
+	/* A device-space aabb is inside the round rect iff its four corners are. */
+	private fun roundRectContainsAabb(inRR: RoundRect, inL: Float, inT: Float, inR: Float, inB: Float): Boolean =
+		roundRectContains(inRR, inL, inT) && roundRectContains(inRR, inR, inT) &&
+			roundRectContains(inRR, inR, inB) && roundRectContains(inRR, inL, inB)
+
+	/* Device aabb of a LOCAL rect under the current affine. */
+	private fun deviceAabb(inL: Float, inT: Float, inR: Float, inB: Float): FloatArray {
+		val vX0 = mapX(inL, inT); val vX1 = mapX(inR, inT); val vX2 = mapX(inR, inB); val vX3 = mapX(inL, inB)
+		val vY0 = mapY(inL, inT); val vY1 = mapY(inR, inT); val vY2 = mapY(inR, inB); val vY3 = mapY(inL, inB)
+		return floatArrayOf(
+			minOf(vX0, vX1, vX2, vX3), minOf(vY0, vY1, vY2, vY3),
+			maxOf(vX0, vX1, vX2, vX3), maxOf(vY0, vY1, vY2, vY3),
+		)
+	}
+
+	/* If the LOCAL-space aabb stays inside every pending rounded clip, drawing
+	   it under the already-active rect clip is correct - no mask needed.
+	   Otherwise realize the pending masks before the draw proceeds. */
+	private fun admitDraw(inL: Float, inT: Float, inR: Float, inB: Float) {
+		if (fPendingClips.isEmpty()) return
+		val vBox = deviceAabb(inL, inT, inR, inB)
+		for (vPending in fPendingClips) {
+			if (!roundRectContainsAabb(vPending.deviceRound, vBox[0], vBox[1], vBox[2], vBox[3])) {
+				realizePendingClips()
+				return
+			}
+		}
+	}
+
+	/* Convert pending clips into real offscreen mask layers (outermost first).
+
+	   Each clip realizes with its OWN push-time region (pending.region =
+	   enclosing-clip-at-push ∩ bbox), NOT the current fClip: a lazily-realized
+	   clip may fire arbitrarily deep inside descendants whose own clips have
+	   since narrowed fClip. Re-intersecting with that narrow clip shrank an
+	   outer clip's offscreen to the innermost descendant's rect, so its
+	   composite blitted back only that sliver and every sibling drawn into the
+	   same offscreen was discarded (the TLS-chain regression: only the first
+	   card + nothing below it, until a scroll shifted which card triggered
+	   realization). The real (already-narrowed) drawing clip is preserved
+	   across the loop and restored at the end, so subsequent draws into the
+	   innermost target stay correctly clipped. */
+	private fun realizePendingClips() {
+		if (fPendingClips.isEmpty()) return
+		val vRenderer = fRenderer.reinterpret<cnames.structs.SDL_Renderer>()
+		val vDrawClip = fClip
+		while (fPendingClips.isNotEmpty()) {
+			val vPending = fPendingClips.removeFirst()
+			fScope.flush()
+			val vRegion = vPending.region
+			val vTarget = fClipTargets?.target(fClipLayers.size, fSize.width.toInt(), fSize.height.toInt())
+			if (vTarget == null || vRegion[2] <= vRegion[0] || vRegion[3] <= vRegion[1]) {
+				// Degrade to the rect clip that is already active.
+				continue
+			}
+			val vPrevTarget = SDL_GetRenderTarget(vRenderer)
+			SDL_SetRenderTarget(vRenderer, vTarget.reinterpret())
+			fClip = vRegion
+			applyClip()
+			clearRegion(vRegion)
+			fClipLayers.addLast(OffscreenClip(vTarget, vPrevTarget, vPending.prevClip, vRegion, vPending.bbox, vPending.deviceRound))
+			// Attribute the realized mask to the save-frame that pushed the
+			// clip: inner frames entered since must NOT composite it on their
+			// restore - bump their thresholds past the new layer.
+			for (vI in vPending.saveDepth until fStack.size) {
+				val vState = fStack[vI]
+				if (vState.clipLayers < fClipLayers.size) {
+					fStack[vI] = vState.copy(clipLayers = fClipLayers.size)
+				}
+			}
+		}
+		// Restore the real drawing clip (already narrowed by inner clipRects /
+		// scroll bounds) for draws into the now-active innermost target.
+		fClip = vDrawClip
+		applyClip()
+	}
+
 	// Flushes any pending batched geometry to SDL, then frees the scope's
 	// native buffer + clears the SDL clip. Call once per frame after the draw.
 	fun finish() {
+		fPendingClips.clear()
 		fScope.release()
 		// Safety: an unbalanced save/restore must never leave the renderer pointed
 		// at a scratch target when the frame is presented.
@@ -166,11 +297,14 @@ internal class Sdl3Canvas(
 		// Offscreen canvas: the outermost save (CanvasDrawScope brackets its draw with
 		// save/restore) switches the SDL render target to the ImageBitmap's texture.
 		if (fOffscreenTexture != null && fStack.isEmpty()) beginOffscreen()
-		fStack.addLast(State(fMa, fMb, fMc, fMd, fMe, fMf, fClip, fAlpha, fClipLayers.size))
+		fStack.addLast(State(fMa, fMb, fMc, fMd, fMe, fMf, fClip, fAlpha, fClipLayers.size, fPendingClips.size))
 	}
 
 	override fun restore() {
 		val vPrev = fStack.removeLastOrNull() ?: return
+		// Pending (never-realized) rounded clips opened inside this save frame:
+		// nothing was drawn through an offscreen for them - just drop them.
+		while (fPendingClips.size > vPrev.pendingClips) fPendingClips.removeLast()
 		// Composite + pop any offscreen rounded clips opened inside this save frame
 		// before restoring the plain state (each composite restores render target
 		// and SDL clip to what it was when the clip was opened).
@@ -267,6 +401,7 @@ internal class Sdl3Canvas(
 	// treating Difference as intersect clipped the border TO the notch instead
 	// (a floating line under the label, no outline anywhere else).
 	private fun clipRectDifference(inL: Float, inT: Float, inR: Float, inB: Float) {
+		realizePendingClips()
 		val vDiff = mapRectAABB(inL, inT, inR, inB)
 		val vRegion = fClip ?: intArrayOf(0, 0, fSize.width.toInt(), fSize.height.toInt())
 		if (fClipTargets == null || fSize.width < 1f || fSize.height < 1f ||
@@ -330,11 +465,19 @@ internal class Sdl3Canvas(
 	//  arbitrary paths keep the clipPath bbox fallback.
 
 	override fun clipRoundRect(inRoundRect: RoundRect) {
+		// The mask is cut in DEVICE space (the bbox below goes through the
+		// affine), but the corner radii arrive in LOCAL user space — scale
+		// them by the affine too, or a graphicsLayer-scaled circle clip cuts
+		// with oversized corners and degenerates toward a lozenge (seen as
+		// diamond-shaped "popped" bubbles under scale 0.55). Column norms
+		// approximate per-axis scale; rotation already degrades to AABBs here.
+		val vScaleX = sqrt(fMa * fMa + fMb * fMb)
+		val vScaleY = sqrt(fMc * fMc + fMd * fMd)
 		val vMaxRadius = maxOf(
-			inRoundRect.topLeftCornerRadius.x, inRoundRect.topLeftCornerRadius.y,
-			inRoundRect.topRightCornerRadius.x, inRoundRect.topRightCornerRadius.y,
-			inRoundRect.bottomRightCornerRadius.x, inRoundRect.bottomRightCornerRadius.y,
-			inRoundRect.bottomLeftCornerRadius.x, inRoundRect.bottomLeftCornerRadius.y,
+			inRoundRect.topLeftCornerRadius.x * vScaleX, inRoundRect.topLeftCornerRadius.y * vScaleY,
+			inRoundRect.topRightCornerRadius.x * vScaleX, inRoundRect.topRightCornerRadius.y * vScaleY,
+			inRoundRect.bottomRightCornerRadius.x * vScaleX, inRoundRect.bottomRightCornerRadius.y * vScaleY,
+			inRoundRect.bottomLeftCornerRadius.x * vScaleX, inRoundRect.bottomLeftCornerRadius.y * vScaleY,
 		)
 		// Effectively-square corners or no offscreen pool → plain rectangular clip.
 		if (vMaxRadius < 0.5f || fClipTargets == null || fSize.width < 1f || fSize.height < 1f) {
@@ -343,6 +486,20 @@ internal class Sdl3Canvas(
 		}
 		fScope.flush()
 		val vBbox = mapRectAABB(inRoundRect.left, inRoundRect.top, inRoundRect.right, inRoundRect.bottom)
+		// Clamp to the DEVICE half-box: the bbox is int-truncated, so a scaled
+		// radius can exceed it by a fraction — opposite corner cuts then overlap
+		// and leave flat spots at N/E/S/W (a circle read as an octagon).
+		val vHalfW = (vBbox[2] - vBbox[0]) / 2f
+		val vHalfH = (vBbox[3] - vBbox[1]) / 2f
+		fun deviceRadius(inR: CornerRadius) =
+			CornerRadius(minOf(inR.x * vScaleX, vHalfW), minOf(inR.y * vScaleY, vHalfH))
+		val vDeviceRound = RoundRect(
+			vBbox[0].toFloat(), vBbox[1].toFloat(), vBbox[2].toFloat(), vBbox[3].toFloat(),
+			topLeftCornerRadius = deviceRadius(inRoundRect.topLeftCornerRadius),
+			topRightCornerRadius = deviceRadius(inRoundRect.topRightCornerRadius),
+			bottomRightCornerRadius = deviceRadius(inRoundRect.bottomRightCornerRadius),
+			bottomLeftCornerRadius = deviceRadius(inRoundRect.bottomLeftCornerRadius),
+		)
 		val vRegion = intersect(fClip, vBbox)
 		// Nothing visible: keep behaviour of a normal clip (cull) without an
 		// offscreen pass. The enclosing save/restore restores the clip afterwards.
@@ -351,20 +508,18 @@ internal class Sdl3Canvas(
 			applyClip()
 			return
 		}
-		val vTarget = fClipTargets.target(fClipLayers.size, fSize.width.toInt(), fSize.height.toInt())
-		if (vTarget == null) {
-			// Couldn't allocate a scratch target — degrade to a rectangular clip.
-			clipRect(inRoundRect.left, inRoundRect.top, inRoundRect.right, inRoundRect.bottom)
-			return
-		}
-		val vRenderer = fRenderer.reinterpret<cnames.structs.SDL_Renderer>()
-		val vPrevTarget = SDL_GetRenderTarget(vRenderer)
+		// LAZY: record only — the rect part of the clip applies immediately,
+		// the offscreen mask is opened by the first draw that actually needs
+		// it (admitDraw / realizePendingClips). The common clip+background
+		// idiom never does.
 		val vPrevClip = fClip
-		SDL_SetRenderTarget(vRenderer, vTarget.reinterpret())
 		fClip = vRegion
 		applyClip()
-		clearRegion(vRegion)
-		fClipLayers.addLast(OffscreenClip(vTarget, vPrevTarget, vPrevClip, vRegion, vBbox, inRoundRect))
+		fPendingClips.addLast(PendingRoundClip(
+			vDeviceRound, inRoundRect, vRegion, vBbox, vPrevClip,
+			fMa, fMb, fMc, fMd, fMe, fMf,
+			fStack.size,
+		))
 	}
 
 	// Pops the top offscreen clip: flush its subtree, cut the rounded corners out
@@ -427,22 +582,24 @@ internal class Sdl3Canvas(
 	private fun zeroRoundRectCorners(inBbox: IntArray, inRoundRect: RoundRect) {
 		val vLeft = inBbox[0].toFloat(); val vTop = inBbox[1].toFloat()
 		val vRight = inBbox[2].toFloat(); val vBottom = inBbox[3].toFloat()
-		val vSeg = 12
 		val vTl = inRoundRect.topLeftCornerRadius
 		val vTr = inRoundRect.topRightCornerRadius
 		val vBr = inRoundRect.bottomRightCornerRadius
 		val vBl = inRoundRect.bottomLeftCornerRadius
-		// Upper bound: 4 corners × vSeg triangles × 3 vertices. Written straight
-		// into the native SDL_Vertex buffer — the old ArrayList<Float> staging
-		// boxed ~300 floats per clip layer per frame.
-		fun cornerCount(inR: androidx.compose.ui.geometry.CornerRadius): Int =
-			if (inR.x <= 0f || inR.y <= 0f) 0 else vSeg * 3
-		val vMax = cornerCount(vTl) + cornerCount(vTr) + cornerCount(vBr) + cornerCount(vBl)
-		if (vMax == 0) return
+		// Segments per quarter arc ~ every 4 device px along the arc, matching
+		// Sdl3DrawScope's density (~64/full circle at typical radii).
+		val vMaxR = maxOf(vTl.x, vTl.y, vTr.x, vTr.y, vBr.x, vBr.y, vBl.x, vBl.y)
+		val vSeg = ((vMaxR * 1.5708f) / 4f).toInt().coerceIn(8, 32)
+		fun cornerCount(inR: CornerRadius): Int = if (inR.x <= 0f || inR.y <= 0f) 0 else vSeg * 3
+		val vFanMax = cornerCount(vTl) + cornerCount(vTr) + cornerCount(vBr) + cornerCount(vBl)
+		if (vFanMax == 0) return
 		val vRenderer = fRenderer.reinterpret<cnames.structs.SDL_Renderer>()
-		SDL_SetRenderDrawBlendMode(vRenderer, SDL_BLENDMODE_NONE)
 		memScoped {
-			val vBuf = allocArray<SDL_Vertex>(vMax)
+			// ============
+			//  Pass 1 — hard cut: zero everything outside each corner arc
+			//  (triangle fan from the corner apex, blend NONE writes RGBA 0).
+			SDL_SetRenderDrawBlendMode(vRenderer, SDL_BLENDMODE_NONE)
+			val vBuf = allocArray<SDL_Vertex>(vFanMax)
 			var vIdx = 0
 			fun put(inX: Float, inY: Float) {
 				vBuf[vIdx].position.x = inX; vBuf[vIdx].position.y = inY
@@ -470,6 +627,51 @@ internal class Sdl3Canvas(
 			cutout(vRight, vBottom, vRight - vBr.x, vBottom - vBr.y, vBr.x, vBr.y, 0f)
 			cutout(vLeft, vBottom, vLeft + vBl.x, vBottom - vBl.y, vBl.x, vBl.y, 90f)
 			if (vIdx > 0) SDL_RenderGeometry(vRenderer, null, vBuf, vIdx, null, 0)
+
+			// ============
+			//  Pass 2 — feathered edge: a ~1.2px ring band straddling each arc
+			//  whose vertex alpha ramps 1 → 0 outward, drawn with a custom
+			//  "dst *= srcAlpha" blend. SDL_RenderGeometry has no antialiasing;
+			//  without this the mask boundary is a hard polygon edge while the
+			//  drawn shapes get Sdl3DrawScope's fringe AA (visibly rougher —
+			//  scaled-down circle clips read as low-poly).
+			val vMul = SDL_ComposeCustomBlendMode(
+				SDL_BLENDFACTOR_ZERO, SDL_BLENDFACTOR_SRC_ALPHA, SDL_BLENDOPERATION_ADD,
+				SDL_BLENDFACTOR_ZERO, SDL_BLENDFACTOR_SRC_ALPHA, SDL_BLENDOPERATION_ADD,
+			)
+			SDL_SetRenderDrawBlendMode(vRenderer, vMul)
+			val vFeather = 1.2f
+			val vBandMax = 4 * vSeg * 6
+			val vBand = allocArray<SDL_Vertex>(vBandMax)
+			var vBIdx = 0
+			fun putBand(inX: Float, inY: Float, inKeep: Float) {
+				vBand[vBIdx].position.x = inX; vBand[vBIdx].position.y = inY
+				vBand[vBIdx].color.r = 1f; vBand[vBIdx].color.g = 1f; vBand[vBIdx].color.b = 1f; vBand[vBIdx].color.a = inKeep
+				vBand[vBIdx].tex_coord.x = 0f; vBand[vBIdx].tex_coord.y = 0f
+				vBIdx++
+			}
+			fun feather(inCx: Float, inCy: Float, inRx: Float, inRy: Float, inStartDeg: Float) {
+				if (inRx <= 1f || inRy <= 1f) return
+				var vPrevInX = 0f; var vPrevInY = 0f; var vPrevOutX = 0f; var vPrevOutY = 0f
+				for (vI in 0..vSeg) {
+					val vAngle = ((inStartDeg + 90f * vI / vSeg) * (PI / 180.0)).toFloat()
+					val vCos = cos(vAngle); val vSin = sin(vAngle)
+					val vInX = inCx + (inRx - vFeather) * vCos
+					val vInY = inCy + (inRy - vFeather) * vSin
+					val vOutX = inCx + inRx * vCos
+					val vOutY = inCy + inRy * vSin
+					if (vI > 0) {
+						putBand(vPrevInX, vPrevInY, 1f); putBand(vPrevOutX, vPrevOutY, 0f); putBand(vInX, vInY, 1f)
+						putBand(vInX, vInY, 1f); putBand(vPrevOutX, vPrevOutY, 0f); putBand(vOutX, vOutY, 0f)
+					}
+					vPrevInX = vInX; vPrevInY = vInY; vPrevOutX = vOutX; vPrevOutY = vOutY
+				}
+			}
+			feather(vLeft + vTl.x, vTop + vTl.y, vTl.x, vTl.y, 180f)
+			feather(vRight - vTr.x, vTop + vTr.y, vTr.x, vTr.y, 270f)
+			feather(vRight - vBr.x, vBottom - vBr.y, vBr.x, vBr.y, 0f)
+			feather(vLeft + vBl.x, vBottom - vBl.y, vBl.x, vBl.y, 90f)
+			if (vBIdx > 0) SDL_RenderGeometry(vRenderer, null, vBand, vBIdx, null, 0)
 		}
 		SDL_SetRenderDrawBlendMode(vRenderer, SDL_BLENDMODE_BLEND)
 	}
@@ -502,6 +704,7 @@ internal class Sdl3Canvas(
 		inAmbientColor: androidx.compose.ui.graphics.Color,
 		inSpotColor: androidx.compose.ui.graphics.Color,
 	) {
+		realizePendingClips()
 		if (inElevationPx <= 0f) return
 
 		// Generic paths (CutCornerShape, GenericShape) don't 9-slice — blur the
@@ -636,6 +839,7 @@ internal class Sdl3Canvas(
 		// before re-rasterising a vector). Write transparent directly instead of the
 		// paint colour.
 		if (paint.blendMode == BlendMode.Clear) {
+			realizePendingClips()
 			fScope.flush()
 			clearRegion(intArrayOf(
 				mapX(left, top).toInt(), mapY(left, top).toInt(),
@@ -643,21 +847,75 @@ internal class Sdl3Canvas(
 			))
 			return
 		}
+		if (fPendingClips.isNotEmpty() && tryDrawRectUnderPendingClips(left, top, right, bottom, paint)) return
 		prep().rectCore(brushFor(paint), Offset(left, top), Size(right - left, bottom - top), (paint.alpha * fAlpha), styleFor(paint))
 	}
 
+	/* The `clip(shape).background(color)` idiom: a FILL rect that fully covers
+	   the innermost pending clip becomes a direct rounded-shape fill (with the
+	   scope's fringe AA — no offscreen mask at all). A rect fully INSIDE every
+	   pending clip draws as-is. Returns true when the draw has been emitted. */
+	private fun tryDrawRectUnderPendingClips(inL: Float, inT: Float, inR: Float, inB: Float, inPaint: Paint): Boolean {
+		val vBox = deviceAabb(inL, inT, inR, inB)
+		val vInner = fPendingClips.last()
+		// Cover case: fill paint, no stroke, rect covers the whole clip outline,
+		// affine unchanged since the clip was pushed (local-space re-emission),
+		// uniform corner radii (the scope's roundRectCore takes one radius), and
+		// the clip outline itself contained in every OUTER pending clip.
+		val vLr = vInner.localRound
+		val vUniform = vLr.topLeftCornerRadius.x == vLr.topLeftCornerRadius.y &&
+			vLr.topLeftCornerRadius == vLr.topRightCornerRadius &&
+			vLr.topLeftCornerRadius == vLr.bottomRightCornerRadius &&
+			vLr.topLeftCornerRadius == vLr.bottomLeftCornerRadius
+		val vAffineUnchanged = vInner.ma == fMa && vInner.mb == fMb && vInner.mc == fMc &&
+			vInner.md == fMd && vInner.me == fMe && vInner.mf == fMf
+		if (inPaint.style == PaintingStyle.Fill && inPaint.blendMode == BlendMode.SrcOver &&
+			vUniform && vAffineUnchanged &&
+			vBox[0] <= vInner.bbox[0] && vBox[1] <= vInner.bbox[1] &&
+			vBox[2] >= vInner.bbox[2] && vBox[3] >= vInner.bbox[3]
+		) {
+			var vOutersContain = true
+			for (vPending in fPendingClips) {
+				if (vPending === vInner) continue
+				if (!roundRectContainsAabb(vPending.deviceRound, vInner.deviceRound.left, vInner.deviceRound.top, vInner.deviceRound.right, vInner.deviceRound.bottom)) {
+					vOutersContain = false; break
+				}
+			}
+			if (vOutersContain) {
+				prep().roundRectCore(
+					brushFor(inPaint),
+					Offset(vLr.left, vLr.top), Size(vLr.width, vLr.height),
+					vLr.topLeftCornerRadius.x,
+					(inPaint.alpha * fAlpha), Fill,
+				)
+				return true
+			}
+		}
+		// Containment: inside every pending outline → the active rect clip is enough.
+		for (vPending in fPendingClips) {
+			if (!roundRectContainsAabb(vPending.deviceRound, vBox[0], vBox[1], vBox[2], vBox[3])) {
+				realizePendingClips()
+				return false
+			}
+		}
+		return false
+	}
+
 	override fun drawRoundRect(
 		left: Float, top: Float, right: Float, bottom: Float,
 		radiusX: Float, radiusY: Float, paint: Paint,
 	) {
+		admitDraw(left, top, right, bottom)
 		prep().roundRectCore(brushFor(paint), Offset(left, top), Size(right - left, bottom - top), radiusX, (paint.alpha * fAlpha), styleFor(paint))
 	}
 
 	override fun drawOval(left: Float, top: Float, right: Float, bottom: Float, paint: Paint) {
+		admitDraw(left, top, right, bottom)
 		prep().ovalCore(brushFor(paint), Offset(left, top), Size(right - left, bottom - top), (paint.alpha * fAlpha), styleFor(paint))
 	}
 
 	override fun drawCircle(center: Offset, radius: Float, paint: Paint) {
+		admitDraw(center.x - radius, center.y - radius, center.x + radius, center.y + radius)
 		prep().circleCore(brushFor(paint), radius, center, (paint.alpha * fAlpha), styleFor(paint))
 	}
 
@@ -665,14 +923,17 @@ internal class Sdl3Canvas(
 		left: Float, top: Float, right: Float, bottom: Float,
 		startAngle: Float, sweepAngle: Float, useCenter: Boolean, paint: Paint,
 	) {
+		realizePendingClips()
 		prep().arcCore(brushFor(paint), startAngle, sweepAngle, useCenter, Offset(left, top), Size(right - left, bottom - top), (paint.alpha * fAlpha), styleFor(paint))
 	}
 
 	override fun drawLine(p1: Offset, p2: Offset, paint: Paint) {
+		realizePendingClips()
 		prep().lineCore(brushFor(paint), p1, p2, paint.strokeWidth, paint.strokeCap, (paint.alpha * fAlpha))
 	}
 
 	override fun drawPath(path: ComposePath, paint: Paint) {
+		realizePendingClips()
 		prep().pathCore(path, brushFor(paint), (paint.alpha * fAlpha), styleFor(paint))
 	}
 
@@ -697,6 +958,11 @@ internal class Sdl3Canvas(
 		inBaseItalic: Boolean,
 		inTextDecoration: androidx.compose.ui.text.style.TextDecoration?,
 	) {
+		// Small centred labels (a popped bubble's "pop") usually sit fully
+		// inside a rounded clip — gate on containment like other draws, with
+		// a 2px margin for glyph overhang / AA bleed, instead of paying a
+		// mask pass per text run.
+		admitDraw(inX - 2f, inY - 2f, inX + inBoxWidth + 2f, inY + inBoxHeight + 2f)
 		fScope.flush()
 		// Paragraph-level decoration bits forwarded to every wrapped line.
 		val vUnderline = inTextDecoration?.contains(androidx.compose.ui.text.style.TextDecoration.Underline) == true
@@ -712,15 +978,26 @@ internal class Sdl3Canvas(
 		// node's real box. The per-line path below centres within a lineHeight band
 		// (1.2 em for Material Symbols), taller than the size-clamped icon node,
 		// which pushed every icon ~0.1 em below centre.
+		// Device-space scale for GLYPHS: the pen position already maps through
+		// the affine, but font size and centering boxes must scale with it too
+		// or text inside a graphicsLayer(scale) renders at full size, off
+		// centre (JVM/Skia scales glyphs with the canvas). Wrap stays in LOCAL
+		// units below so line breaks match what layout measured.
+		val vTextScaleX = sqrt(fMa * fMa + fMb * fMb)
+		val vTextScaleY = sqrt(fMc * fMc + fMd * fMd)
+		val vDeviceFontPx =
+			if (vTextScaleY == 1f) inFontSizePx
+			else (inFontSizePx * vTextScaleY).toInt().coerceAtLeast(1)
+
 		if (inFontFamily != null && IconFont.isIconFamily(inFontFamily)) {
 			vTr.drawText(
 				inText = inText,
 				inX = mapX(inX, inY).toInt(),
 				inY = mapY(inX, inY).toInt(),
-				inBoxWidth = inBoxWidth.toInt(),
-				inBoxHeight = inBoxHeight.toInt(),
+				inBoxWidth = (inBoxWidth * vTextScaleX).toInt(),
+				inBoxHeight = (inBoxHeight * vTextScaleY).toInt(),
 				inColor = vColor,
-				inFontSize = inFontSizePx,
+				inFontSize = vDeviceFontPx,
 				inAlign = inTextAlign,
 				inFontFamily = inFontFamily,
 				inFontVariations = inFontVariations,
@@ -758,15 +1035,15 @@ internal class Sdl3Canvas(
 			if (vLineY >= inY + inBoxHeight) break
 			vTr.drawText(
 				inText = vLine,
-				// Position maps through the affine (translate/scale reach the origin);
-				// glyph scaling/rotation isn't wired, so text in a rotated/scaled layer
-				// repositions but doesn't itself scale or rotate.
+				// Position maps through the affine; size/boxes switch to DEVICE
+				// units here (scaled by the affine's column norms) so glyphs
+				// scale with the layer. Rotation still only repositions.
 				inX = mapX(inX, vLineY).toInt(),
 				inY = mapY(inX, vLineY).toInt(),
-				inBoxWidth = inBoxWidth.toInt(),
-				inBoxHeight = vLineH.toInt(),
+				inBoxWidth = (inBoxWidth * vTextScaleX).toInt(),
+				inBoxHeight = (vLineH * vTextScaleY).toInt(),
 				inColor = vColor,
-				inFontSize = inFontSizePx,
+				inFontSize = vDeviceFontPx,
 				inAlign = inTextAlign,
 				inFontFamily = inFontFamily,
 				inFontVariations = inFontVariations,
@@ -794,6 +1071,7 @@ internal class Sdl3Canvas(
 		inContentScale: androidx.compose.ui.layout.ContentScale,
 		inAlpha: Float,
 	) {
+		admitDraw(inX, inY, inX + inWidth, inY + inHeight)
 		fScope.flush()
 		// Map the origin through the affine and scale the size by the matrix's axis
 		// magnitudes (rotation contributes 1, so it only repositions the blit — the
@@ -812,6 +1090,7 @@ internal class Sdl3Canvas(
 
 	override fun drawImage(image: ImageBitmap, topLeftOffset: Offset, paint: Paint) {
 		val vBmp = image as? SdlImageBitmap ?: return
+		admitDraw(topLeftOffset.x, topLeftOffset.y, topLeftOffset.x + vBmp.width, topLeftOffset.y + vBmp.height)
 		drawImageRect(
 			image,
 			androidx.compose.ui.unit.IntOffset.Zero,
@@ -834,6 +1113,7 @@ internal class Sdl3Canvas(
 		dstSize: androidx.compose.ui.unit.IntSize,
 		paint: Paint,
 	) {
+		realizePendingClips()
 		val vTex = (image as? SdlImageBitmap)?.texture ?: return
 		// Commit pending frame geometry and re-assert this canvas's target + clip
 		// (an offscreen render just borrowed the render target).

compose/ui/ui/src/sdlRendererMain/kotlin/com/compose/sdl/renderer/sdl/Sdl3DrawScope.kt

@@ -893,7 +893,13 @@ internal class Sdl3DrawScope(
 	// through the current affine so scale/rotate reach the GPU; the colour is
 	// sampled at the pre-transform point so a gradient rides its shape.
 	private fun writeVertex(inX: Float, inY: Float, inColor: ComposeColor, inAlphaScale: Float = 1f) {
-		if (fBatchCount >= kBatchCapacity) flush()
+		// Auto-flush ONLY at a triangle boundary: SDL_RenderGeometry renders
+		// floor(count/3) triangles and silently drops the tail, so flushing
+		// mid-triangle tears it AND misaligns every following triangle in the
+		// new batch (seen as ~350-degree pac-man circles and glitch shapes
+		// once a frame's geometry outgrew one batch - e.g. 84 unclipped
+		// drawBehind bubbles). kBatchCapacity is a multiple of 3.
+		if (fBatchCount >= kBatchCapacity && fBatchCount % 3 == 0) flush()
 		val vBase = fBatchCount * kFloatsPerVertex
 		fVertexData[vBase + 0] = fMa * inX + fMc * inY + fMe
 		fVertexData[vBase + 1] = fMb * inX + fMd * inY + fMf
@@ -914,11 +920,13 @@ private const val kAaFeather: Float = 1.0f
 private const val kAaHalf: Float = kAaFeather * 0.5f
 
 // ============
-//  Batch capacity — 8192 vertices = ~2730 triangles per submission. At
-//  64 segments per full circle that's room for ~21 full-circle filled
-//  shapes per Canvas{} before any flush. Bigger gives fewer GPU
-//  submissions; smaller saves RAM. ~128 KB at 16 bytes per SDL_Vertex.
-private const val kBatchCapacity: Int = 8192
+//  Batch capacity — 8190 vertices = 2730 triangles per submission (kept a
+//  MULTIPLE OF 3: the auto-flush in writeVertex only fires on triangle
+//  boundaries, so the cap must land on one). At 64 segments per full circle
+//  that's room for ~21 full-circle filled shapes per Canvas{} before any
+//  flush. Bigger gives fewer GPU submissions; smaller saves RAM. ~128 KB at
+//  16 bytes per SDL_Vertex.
+private const val kBatchCapacity: Int = 8190
 
 // Floats per SDL_Vertex: position(x,y) + color(r,g,b,a) + tex_coord(x,y), tightly
 // packed. Used to stage vertices in a Kotlin FloatArray and memcpy them across.

compose/ui/ui/src/sdlRendererMain/kotlin/com/compose/sdl/renderer/sdl/Sdl3Offscreen.kt

@@ -29,6 +29,34 @@ internal var currentMainCanvas: Sdl3Canvas? = null
 // An ImageBitmap backed by an SDL render-target texture. The vector rasterises
 // into the texture (via a Canvas returned by the factory) and Sdl3Canvas.drawImageRect
 // blits it back — with the Icon tint applied through SDL_SetTextureColorMod.
+// Mutable native handles held BY REFERENCE so a Cleaner can free them without
+// capturing the (collectable) SdlImageBitmap. Both the explicit close() and the
+// GC Cleaner enqueue release of whatever is still here — the first to run nulls
+// the fields, so the other is a no-op (they can't overlap: close() only runs
+// while the bitmap is reachable, the Cleaner only after it isn't).
+@OptIn(ExperimentalForeignApi::class)
+private class SdlBitmapHandles(
+	var texture: COpaquePointer?,
+	var surface: CPointer<SDL_Surface>?,
+)
+
+/* Enqueue destruction of the handles' current contents on the main thread
+   (SDL calls aren't thread-safe; the Cleaner runs on a GC worker). Idempotent:
+   clears the fields so a second call frees nothing. Top-level so the Cleaner
+   block never captures the bitmap. */
+@OptIn(ExperimentalForeignApi::class)
+private fun enqueueRelease(inHandles: SdlBitmapHandles) {
+	val vTex = inHandles.texture
+	val vSurf = inHandles.surface
+	if (vTex == null && vSurf == null) return
+	inHandles.texture = null
+	inHandles.surface = null
+	com.compose.sdl.graphics.NativeReleaseQueue.enqueue {
+		if (vSurf != null) SDL_DestroySurface(vSurf)
+		if (vTex != null) SDL_DestroyTexture(vTex.reinterpret())
+	}
+}
+
 @OptIn(ExperimentalForeignApi::class)
 internal class SdlImageBitmap(
 	private val fRenderer: COpaquePointer,
@@ -41,19 +69,28 @@ internal class SdlImageBitmap(
 	// Sdl3EncodedImageDecoder); converted to a texture on the first draw.
 	// null → create a render TARGET for the vector-rasterisation path below
 	// (that path always constructs on the main thread).
-	private var fDecodedSurface: CPointer<SDL_Surface>? = null,
+	fDecodedSurface: CPointer<SDL_Surface>? = null,
 ) : ImageBitmap {
 
 	// RGBA render-target texture, premultiplied blend for compositing back (content
 	// is drawn over a transparent clear with ordinary BLEND, leaving premultiplied
 	// colours — see Sdl3ClipTargets for the same reasoning).
-	private var fTexture: COpaquePointer? = if (fDecodedSurface != null) null else SDL_CreateTexture(
-		fRenderer.reinterpret(),
-		SDL_PIXELFORMAT_RGBA32,
-		SDL_TextureAccess.SDL_TEXTUREACCESS_TARGET,
-		maxOf(1, width),
-		maxOf(1, height),
-	)?.also { SDL_SetTextureBlendMode(it.reinterpret(), SDL_BLENDMODE_BLEND_PREMULTIPLIED) }
+	private val fHandles = SdlBitmapHandles(
+		texture = if (fDecodedSurface != null) null else SDL_CreateTexture(
+			fRenderer.reinterpret(),
+			SDL_PIXELFORMAT_RGBA32,
+			SDL_TextureAccess.SDL_TEXTUREACCESS_TARGET,
+			maxOf(1, width),
+			maxOf(1, height),
+		)?.also { SDL_SetTextureBlendMode(it.reinterpret(), SDL_BLENDMODE_BLEND_PREMULTIPLIED) },
+		surface = fDecodedSurface,
+	)
+
+	// GC backstop: if nothing calls close(), free the native handles when the
+	// bitmap is collected (deferred to the main thread via the queue). Ownership
+	// via close() is the primary path; this catches leaks.
+	@OptIn(kotlin.experimental.ExperimentalNativeApi::class)
+	private val fCleaner = kotlin.native.ref.createCleaner(fHandles) { enqueueRelease(it) }
 
 	// SDL renderer calls are NOT thread-safe, and the resources pipeline
 	// decodes on Dispatchers.Default workers — so the decode path hands over a
@@ -63,15 +100,20 @@ internal class SdlImageBitmap(
 	// render-target path above.
 	val texture: COpaquePointer?
 		get() {
-			fDecodedSurface?.let { vSurface ->
-				fTexture = SDL_CreateTextureFromSurface(fRenderer.reinterpret(), vSurface)
+			fHandles.surface?.let { vSurface ->
+				fHandles.texture = SDL_CreateTextureFromSurface(fRenderer.reinterpret(), vSurface)
 					?.also { SDL_SetTextureBlendMode(it.reinterpret(), SDL_BLENDMODE_BLEND) }
 				SDL_DestroySurface(vSurface)
-				fDecodedSurface = null
+				fHandles.surface = null
 			}
-			return fTexture
+			return fHandles.texture
 		}
 
+	/* Free the texture/surface now (deferred to the main thread). Call on
+	   cache eviction / removeMemoryResource so native memory releases promptly
+	   instead of waiting for a GC. The Cleaner remains as a backstop. */
+	fun close() = enqueueRelease(fHandles)
+
 	override fun readPixels(
 		buffer: IntArray,
 		startX: Int,

compose/ui/ui/src/skikoRendererMain/kotlin/com/compose/sdl/PlatformGpu.kt

@@ -9,7 +9,7 @@ import kotlin.experimental.ExperimentalNativeApi
 
 internal expect fun makeMetalBridge(backend: SDL3Backend): SkiaBridge?
 
-fun rendererPreferredGpuMode(): GpuMode {
+actual fun rendererPreferredGpuMode(): GpuMode {
     @OptIn(ExperimentalNativeApi::class)
     return when (Platform.osFamily) {
         OsFamily.MACOSX -> GpuMode.Skia.Metal

compose/ui/ui/src/skikoRendererMain/kotlin/com/compose/sdl/RenderBackendFactory.skia.kt

@@ -11,7 +11,7 @@ import com.compose.sdl.renderer.skia.SkiaRenderBackend
    SDL3 module's createRenderBackend / rendererPreferredGpuMode in the same
    package; exactly one renderer module is included per target. Rejects
    Sdl3.* since this module has no SDL3_ttf / SDL3_image. */
-fun createRenderBackend(inSdl: SDL3Backend, inGpu: GpuMode): RenderBackend? {
+actual fun createRenderBackend(inSdl: SDL3Backend, inGpu: GpuMode): RenderBackend? {
 	val vResolved = if (inGpu is GpuMode.Auto) rendererPreferredGpuMode() else inGpu
 	if (vResolved is GpuMode.Sdl3) {
 		error("Sdl3.* modes aren't available in a Skia build — rerun with -Prenderer=sdl3")

demo/src/jvmMain/kotlin/MainJvm.kt

@@ -1,23 +1,92 @@
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.darkColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.ExperimentalComposeUiApi
+import androidx.compose.ui.ImageComposeScene
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.Density
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.window.Window
 import androidx.compose.ui.window.application
 import androidx.compose.ui.window.rememberWindowState
+import demo.registry.allCategories
 import demo.shell.App
+import org.jetbrains.skia.EncodedImageFormat
+import java.io.File
 
-// The JVM comparison app's entry point. Runs the SAME shared App() shell + Core /
-// Material 3 screens (expressive included) as :demo, but on Compose Desktop (JVM)
-// against upstream org.jetbrains.compose. Compare side-by-side with
-// `:demo:runDebugExecutable<host>`.
-fun main() = application {
-    Window(
-        onCloseRequest = ::exitApplication,
-        title = "ComposeDesktopNative — JVM (upstream Compose)",
-        state = rememberWindowState(width = 1000.dp, height = 700.dp),
-    ) {
-        MaterialTheme(colorScheme = darkColorScheme()) {
-            App(isJvm = true)
+// The JVM comparison app: the SAME shared App() + screens as :demo, on upstream
+// Compose Desktop. Interactive by default; a headless screenshot mode drives
+// the parity harness (scripts/parity — compares each screen native vs jvm).
+//
+//   --screenshot-all=<dir>   render every registered screen to <dir>/<Name>.png
+//   --width / --height       viewport size (default 1000 / 700)
+//
+// The single-screen wrapper MIRRORS MainNative's --screen path (dark theme,
+// verticalScroll + 24dp padding) so layout constraints match the native
+// screenshots pixel-for-pixel.
+fun main(args: Array<String>) {
+    val screenshotDir = args.firstOrNull { it.startsWith("--screenshot-all=") }?.substringAfter('=')
+    if (screenshotDir != null) {
+        screenshotAllScreens(
+            outDir = File(screenshotDir),
+            width = args.intArg("--width", 1000),
+            height = args.intArg("--height", 700),
+        )
+        return
+    }
+    application {
+        Window(
+            onCloseRequest = ::exitApplication,
+            title = "ComposeDesktopNative — JVM (upstream Compose)",
+            state = rememberWindowState(width = 1000.dp, height = 700.dp),
+        ) {
+            MaterialTheme(colorScheme = darkColorScheme()) {
+                App(isJvm = true)
+            }
         }
     }
 }
+
+private fun Array<String>.intArg(name: String, default: Int): Int =
+    firstOrNull { it.startsWith("$name=") }?.substringAfter('=')?.toIntOrNull() ?: default
+
+/* Render each registered screen headlessly (density 1 to match the native
+   physical-pixel screenshots) and write a PNG per screen. */
+@OptIn(ExperimentalComposeUiApi::class)
+private fun screenshotAllScreens(outDir: File, width: Int, height: Int) {
+    outDir.mkdirs()
+    val screens = allCategories().flatMap { it.screens }.distinctBy { it.name }
+    for (screen in screens) {
+        val scene = ImageComposeScene(width, height, density = Density(1f)) {
+            ScreenHost { screen.content() }
+        }
+        try {
+            val image = scene.render()
+            val png = image.encodeToData(EncodedImageFormat.PNG) ?: continue
+            File(outDir, "${screen.name}.png").writeBytes(png.bytes)
+        } finally {
+            scene.close()
+        }
+        println("jvm screenshot: ${screen.name}")
+    }
+}
+
+/* Same wrapper as MainNative's --screen path. */
+@Composable
+private fun ScreenHost(content: @Composable () -> Unit) {
+    MaterialTheme(colorScheme = darkColorScheme()) {
+        Box(
+            modifier = Modifier
+                .fillMaxSize()
+                .background(MaterialTheme.colorScheme.background)
+                .verticalScroll(rememberScrollState())
+                .padding(24.dp),
+        ) { content() }
+    }
+}

gradle-plugin/compose-desktop-native-bridge/README.md

@@ -59,8 +59,63 @@ kotlin {
 }
 ```
 
-The plugin can also be applied to a single module's `build.gradle.kts` instead
-of settings (it then bridges only that module's configurations).
+### Settings-wide or per-module
+
+The plugin applies at either level:
+
+```kotlin
+// settings.gradle.kts — every module of the build
+plugins { id("com.bitsycore.compose-desktop-native.bridge") version "<v>" }
+```
+
+```kotlin
+// build.gradle.kts — this module only (compose-plugin style)
+plugins { id("com.bitsycore.compose-desktop-native.bridge") }
+```
+
+Note the difference between the two settings blocks: a
+`pluginManagement { plugins { id(...) version ... } }` entry only PINS the
+version (so module-level applications can omit it); the top-level
+`plugins { }` block in settings is what actually applies it build-wide.
+Rule of thumb: single app module → apply in the module; multi-module builds →
+apply once in settings.
+
+## compose.desktop.native — the application block for native
+
+The native counterpart of `compose.desktop { application { mainClass } }`:
+
+```kotlin
+compose.desktop {
+    application { mainClass = "app.MainJvmKt" }   // upstream jvm
+    native { entryPoint = "app.main" }            // compose-desktop-native
+}
+```
+
+Declares an executable with that entry point on every Kotlin/Native desktop
+target — no `targets.withType<KotlinNativeTarget> { binaries.executable { … } }`
+boilerplate. Targets that already declare an executable are left untouched,
+so manual configuration (extra linker flags, custom build types) still wins.
+
+## composeResources — zero setup
+
+If the module also applies the official `org.jetbrains.compose` plugin, the
+bridge completes the resources story on the native desktop targets: it
+registers a `package<Variant>ComposeResources<Target>` task per native
+executable that bundles the Compose plugin's prepared resources into
+`data.kres` next to the binary (a STORED zip the port's runtime reads via
+SDL_GetBasePath). Files under `src/commonMain/composeResources/` + the
+generated `Res.*` accessors then work exactly like on every other platform —
+drawables, strings (`values/*.xml`), fonts, raw files:
+
+```kotlin
+commonMain.dependencies {
+    implementation("org.jetbrains.compose.components:components-resources:<cmp-version>")
+}
+```
+
+`compose.resources { packageOfResClass = … }` is honoured; source-set
+overrides follow the default hierarchy (a `mingwX64Main` resource beats a
+`commonMain` one).
 
 ## Notes
 

gradle-plugin/compose-desktop-native-bridge/build.gradle.kts

@@ -16,6 +16,7 @@ plugins {
     `java-gradle-plugin`
 }
 
+
 gradlePlugin {
     plugins {
         create("composeDesktopNativeBridge") {

gradle-plugin/compose-desktop-native-bridge/src/main/kotlin/com/bitsycore/compose/sdl/gradle/ComposeDesktopNativeBridgePlugin.kt

@@ -79,6 +79,8 @@ class ComposeDesktopNativeBridgePlugin : Plugin<Any> {
 // ==================
 
 private fun installBridge(project: Project) {
+	installResourcePackaging(project)
+	installNativeApplicationDsl(project)
 	val version = project.providers.gradleProperty(versionProperty).orNull ?: pluginVersion
 	project.configurations.configureEach { configuration ->
 		if (nativeTargetTokens.any { configuration.name.contains(it, ignoreCase = true) }) {

gradle-plugin/compose-desktop-native-bridge/src/main/kotlin/com/bitsycore/compose/sdl/gradle/NativeApplication.kt

@@ -0,0 +1,76 @@
+package com.bitsycore.compose.sdl.gradle
+
+import org.gradle.api.Action
+import org.gradle.api.NamedDomainObjectCollection
+import org.gradle.api.Project
+import org.gradle.api.plugins.ExtensionAware
+
+// ==================
+// MARK: compose.desktop.native { } — the native counterpart of application { }
+// ==================
+
+/**
+ * The native desktop analog of `compose.desktop { application { mainClass } }`:
+ *
+ * ```kotlin
+ * compose.desktop {
+ *     application { mainClass = "bubblewrap.MainJvmKt" }   // jvm (upstream)
+ *     native { entryPoint = "bubblewrap.main" }            // this port
+ * }
+ * ```
+ *
+ * Declares an executable with the given entry point on every Kotlin/Native
+ * DESKTOP target (mingwX64 / linuxX64 / linuxArm64 / macosArm64) — replacing
+ * the hand-written `targets.withType<KotlinNativeTarget> { binaries.executable
+ * { entryPoint = … } }` block. Targets that already declare an executable are
+ * left untouched, so manual configuration (extra linker flags, custom build
+ * types) still wins.
+ */
+abstract class ComposeDesktopNativeExtension {
+	/** Entry point (`package.functionName`) for the native executables. */
+	var entryPoint: String? = null
+}
+
+/* Grafts the `native` extension onto the Compose plugin's `desktop` extension
+   (extensions are ExtensionAware, so this needs no compile-time dependency)
+   and materialises the executables in afterEvaluate. All KGP access is
+   reflective: applied from settings, this plugin's classloader is a PARENT of
+   the project's buildscript loader and cannot see KGP types. */
+internal fun installNativeApplicationDsl(project: Project) {
+	project.pluginManager.withPlugin("org.jetbrains.compose") {
+		project.pluginManager.withPlugin("org.jetbrains.kotlin.multiplatform") {
+			val composeExt = project.extensions.findByName("compose") as? ExtensionAware ?: return@withPlugin
+			val desktopExt = composeExt.extensions.findByName("desktop") as? ExtensionAware ?: return@withPlugin
+			if (desktopExt.extensions.findByName("native") != null) return@withPlugin
+			val nativeExt = desktopExt.extensions.create("native", ComposeDesktopNativeExtension::class.java)
+			project.afterEvaluate { configureNativeExecutables(it, nativeExt) }
+		}
+	}
+}
+
+private val desktopKonanFamilies = setOf("MINGW", "LINUX", "OSX")
+
+private fun configureNativeExecutables(project: Project, ext: ComposeDesktopNativeExtension) {
+	val entryPoint = ext.entryPoint ?: return
+	val kotlinExt = project.extensions.findByName("kotlin") ?: return
+	@Suppress("UNCHECKED_CAST")
+	val targets = kotlinExt.javaClass.getMethod("getTargets").invoke(kotlinExt) as NamedDomainObjectCollection<Any>
+	for (target in targets) {
+		val platformType = target.javaClass.getMethod("getPlatformType").invoke(target)
+		if (platformType.toString() != "native") continue
+		val konanTarget = target.javaClass.getMethod("getKonanTarget").invoke(target)
+		val family = konanTarget.javaClass.getMethod("getFamily").invoke(konanTarget)
+		if ((family as Enum<*>).name !in desktopKonanFamilies) continue
+		val binaries = target.javaClass.getMethod("getBinaries").invoke(target)
+		// Respect manual configuration: skip targets that already have an
+		// executable (matching by the binary class, not the name suffix).
+		val existing = (binaries as Iterable<*>).any { it != null && it.javaClass.simpleName == "Executable" }
+		if (existing) continue
+		val executableMethod = binaries.javaClass.methods.first {
+			it.name == "executable" && it.parameterCount == 1 && Action::class.java.isAssignableFrom(it.parameterTypes[0])
+		}
+		executableMethod.invoke(binaries, Action<Any> { binary ->
+			binary.javaClass.getMethod("setEntryPoint", String::class.java).invoke(binary, entryPoint)
+		})
+	}
+}

gradle-plugin/compose-desktop-native-bridge/src/main/kotlin/com/bitsycore/compose/sdl/gradle/ResourcePackaging.kt

@@ -0,0 +1,125 @@
+package com.bitsycore.compose.sdl.gradle
+
+import org.gradle.api.Project
+import org.gradle.api.file.DuplicatesStrategy
+import org.gradle.api.plugins.ExtensionAware
+import org.gradle.api.tasks.bundling.Zip
+import org.gradle.api.tasks.bundling.ZipEntryCompression
+
+// ==================
+// MARK: composeResources → data.kres packaging
+// ==================
+
+/**
+ * Gives consumer apps the OFFICIAL composeResources experience on the port's
+ * native desktop targets: files under `src/<sourceSet>/composeResources/` +
+ * the generated `Res.*` accessors, with nothing hand-rolled.
+ *
+ * The official Compose plugin already handles accessor generation and every
+ * other platform's packaging (jvm classpath, Android assets, …). What the
+ * native desktop targets need is the port's runtime bundle: `data.kres`, a
+ * STORED zip next to the executable that the runtime opens via
+ * SDL_GetBasePath() and reads entry-by-entry (fseek+fread — hence no
+ * compression). This registers one Zip task per native executable link task,
+ * zipping the Compose plugin's PREPARED resources (values*.xml are converted
+ * to .cvr there — zipping the raw source dir would break stringResource)
+ * under the same `composeResources/<res-package>/` prefix the generated
+ * accessors carry.
+ *
+ * IMPLEMENTATION NOTE — conventions, not KGP types: applied from settings,
+ * this plugin lives in a classloader that is a PARENT of the project's
+ * buildscript loader, so KGP / Compose plugin classes are structurally
+ * invisible to it. Link tasks (`link<Variant>Executable<Target>`), binary
+ * output dirs (`build/bin/<target>/<variant>Executable`), prepare tasks
+ * (`prepareComposeResourcesTaskFor<SourceSet>`) and the prepared-resources
+ * dir are all stable KGP / Compose-plugin naming conventions.
+ */
+internal fun installResourcePackaging(project: Project) {
+	project.pluginManager.withPlugin("org.jetbrains.compose") {
+		project.pluginManager.withPlugin("org.jetbrains.kotlin.multiplatform") {
+			// afterEvaluate: link tasks, prepare tasks and compose.resources {}
+			// all materialise during project evaluation.
+			project.afterEvaluate { registerDataKresTasks(it) }
+		}
+	}
+}
+
+/* The port's desktop targets and each one's default-hierarchy source sets,
+   most specific first — a target-level resource overrides a commonMain one. */
+private val desktopTargets = mapOf(
+	"MingwX64" to listOf("mingwX64Main", "mingwMain", "nativeMain", "commonMain"),
+	"LinuxX64" to listOf("linuxX64Main", "linuxMain", "nativeMain", "commonMain"),
+	"LinuxArm64" to listOf("linuxArm64Main", "linuxMain", "nativeMain", "commonMain"),
+	"MacosArm64" to listOf("macosArm64Main", "macosMain", "appleMain", "nativeMain", "commonMain"),
+)
+
+private fun registerDataKresTasks(project: Project) {
+	// The zips are PRE-REGISTERED lazily for every desktop target/variant and
+	// wired to their link task via matching{}.configureEach: executables may
+	// be declared after this afterEvaluate runs — notably by the bridge's OWN
+	// compose.desktop.native { entryPoint } DSL, which also materialises in
+	// afterEvaluate. (A name pre-scan raced that and silently packaged
+	// nothing — the "data.kres not found" crash; and Gradle forbids
+	// registering tasks from inside another task's configuration callback,
+	// so the zip cannot be created reactively either.) An unrealised
+	// registered task costs nothing: if the target has no executable, the
+	// link task never appears and the zip never runs. All content wiring
+	// happens in the zip's own configuration action, which only executes on
+	// realisation — by then the Compose plugin's prepare tasks and the final
+	// compose.resources config exist.
+	for ((target, sourceSets) in desktopTargets) {
+		for (variant in listOf("Debug", "Release")) {
+			val linkName = "link${variant}Executable$target"
+			val zipName = "package${variant}ComposeResources$target"
+			if (zipName in project.tasks.names) continue
+			val zipTask = project.tasks.register(zipName, Zip::class.java) { task ->
+				task.description = "Bundles composeResources into data.kres next to the $target ${variant.lowercase()} executable."
+				task.archiveFileName.set("data.kres")
+				task.destinationDirectory.set(
+					project.layout.buildDirectory.dir(
+						"bin/${target.replaceFirstChar { it.lowercase() }}/${variant.replaceFirstChar { it.lowercase() }}Executable"
+					)
+				)
+				// STORED: the runtime's reader hands raw bytes straight to the
+				// decoders — an entry is one fseek+fread, never inflated.
+				task.entryCompression = ZipEntryCompression.STORED
+				task.duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+				val resPackage = project.resolveResourcePackage()
+				val prepareNames = sourceSets
+					.map { "prepareComposeResourcesTaskFor" + it.replaceFirstChar { c -> c.uppercase() } }
+					.filter { it in project.tasks.names }
+				for (prepareName in prepareNames) {
+					val sourceSet = prepareName.removePrefix("prepareComposeResourcesTaskFor")
+						.replaceFirstChar { it.lowercase() }
+					val prepared = project.layout.buildDirectory.dir(
+						"generated/compose/resourceGenerator/preparedResources/$sourceSet/composeResources"
+					)
+					task.from(prepared) { spec -> spec.into("composeResources/$resPackage") }
+					task.dependsOn(project.tasks.named(prepareName))
+				}
+			}
+			project.tasks.matching { it.name == linkName }.configureEach { it.dependsOn(zipTask) }
+		}
+	}
+}
+
+/* The package the generated accessors carry in their resource paths —
+   compose.resources.packageOfResClass (read REFLECTIVELY: the ResourcesExtension
+   class lives in the project's buildscript loader, invisible from here), or
+   the Compose plugin's documented default `{group}.{module}.generated.resources`
+   (lowercased, '-' → '_', digit-leading segments prefixed with '_'). */
+private fun Project.resolveResourcePackage(): String {
+	val explicit = runCatching {
+		val composeExt = extensions.findByName("compose") as? ExtensionAware
+		val resourcesExt = composeExt?.extensions?.findByName("resources")
+		resourcesExt?.javaClass?.getMethod("getPackageOfResClass")?.invoke(resourcesExt) as? String
+	}.getOrNull().orEmpty()
+	if (explicit.isNotEmpty()) return explicit
+	val groupName = group.toString().lowercase().asUnderscoredIdentifier()
+	val moduleName = name.lowercase().asUnderscoredIdentifier()
+	val id = if (groupName.isNotEmpty()) "$groupName.$moduleName" else moduleName
+	return "$id.generated.resources"
+}
+
+private fun String.asUnderscoredIdentifier(): String =
+	replace('-', '_').let { if (it.isNotEmpty() && it.first().isDigit()) "_$it" else it }

scripts/parity/README.md

@@ -0,0 +1,47 @@
+# Parity harness
+
+Renders every `:demo` screen on the **native** (SDL/Skia, Kotlin/Native) stack
+and on the **JVM** upstream-Compose stack from the *same* commonMain
+composables, then pixel-diffs them per screen. It's a regression net: a screen
+whose difference jumps far above its usual level is a port bug (missing
+content, wrong shape/colour, broken clip). Several of this project's renderer
+regressions would have surfaced here.
+
+```bash
+python scripts/parity/parity.py                 # all screens (builds first)
+python scripts/parity/parity.py Buttons Shapes  # a subset
+python scripts/parity/parity.py --no-build      # reuse the last renders
+python scripts/parity/parity.py --gpu=sdl3      # native renderer (default sdl3)
+```
+
+Output → `build/parity/` (gitignored):
+
+- `<pct>_<Name>_compare.png` — native ∣ jvm ∣ amplified-diff, side by side
+- `<pct>_<Name>_diff.png` — the amplified difference heatmap alone
+- `report.txt` — screens ranked by % differing
+
+The `<pct>` prefix is zero-padded, so a plain file listing (or the report)
+sorts worst-first.
+
+## Reading the result
+
+**Absolute % is not the metric — the ranking is.** The two stacks use
+different default fonts, so text carries a steady baseline difference (in the
+heatmap, every text line shows a faint *doubled* ghost from slightly different
+line metrics). Buttons, cards, shapes, images should align (dark). So:
+
+- **doubled/ghosted text, dark shapes** → normal font drift.
+- **a solid bright block, or a shape present on one side only** → a real
+  regression. Open the `_compare.png` to see which stack is wrong.
+
+Compare a screen's % against its neighbours and its own history: Buttons ~16%,
+Shapes ~14%, Colors ~4% are the healthy baseline (mostly text). A screen that
+reads 60% when text-light is the bug.
+
+## Requirements
+
+- Windows for the native leg today (mingwX64 exe); the JVM leg is host-neutral.
+- Pillow (`pip install pillow`).
+- The JVM leg renders all screens headlessly via `ImageComposeScene` in one
+  process (`:demo:run --args=--screenshot-all=…`); native takes one exe launch
+  per screen.

scripts/parity/parity.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+Parity harness — render every demo screen on the NATIVE (SDL/Skia) stack and on
+the JVM upstream-Compose stack, then pixel-diff them per screen.
+
+The two stacks share the exact same commonMain screen composables, so a screen
+that suddenly diverges from its usual difference level is a PORT REGRESSION
+(missing content, wrong shape/colour, broken clip). Absolute pixel-perfection
+is NOT the goal — fonts differ between stacks, so text-heavy screens carry a
+steady baseline difference. The signal is the RANKING: a screen that jumps from
+~8% to ~60% different is the bug. Four of the renderer regressions this project
+hit would have surfaced here.
+
+Usage (from repo root):
+    python scripts/parity/parity.py                 # all screens
+    python scripts/parity/parity.py Buttons Shapes  # a subset
+    python scripts/parity/parity.py --no-build      # reuse existing screenshots
+
+Outputs to build/parity/ (gitignored):
+    <pct>_<Name>_compare.png   native | jvm | amplified-diff, side by side
+    <pct>_<Name>_diff.png      the amplified pixel-difference heatmap alone
+    report.txt                 ranked table
+The <pct> prefix is zero-padded so a plain file listing sorts worst-first.
+
+Windows-only for the native leg today (mingwX64 exe). Needs Pillow.
+Native uses the SDL renderer; pass --gpu to change.
+"""
+import subprocess, sys, os, shutil
+from pathlib import Path
+from PIL import Image, ImageChops, ImageDraw
+
+REPO = Path(__file__).resolve().parents[2]
+OUT = REPO / "build" / "parity"
+NATIVE_EXE = REPO / "demo" / "build" / "bin" / "mingwX64" / "debugExecutable" / "demo.exe"
+WIDTH, HEIGHT = 1000, 700
+# Per-channel tolerance: below this a pixel counts as "same" (JPEG-ish noise,
+# sub-pixel AA, font hinting). Tuned so unrelated screens sit well under it.
+TOL = 32
+
+GRADLEW = str(REPO / ("gradlew.bat" if os.name == "nt" else "gradlew"))
+
+
+def run(cmd, **kw):
+    print("+ " + " ".join(str(c) for c in cmd))
+    return subprocess.run(cmd, cwd=REPO, **kw)
+
+
+def build():
+    run([GRADLEW, ":demo:linkDebugExecutableMingwX64", "--console=plain"], check=True)
+
+
+def jvm_shots(dst: Path):
+    run([GRADLEW, ":demo:run", f"--args=--screenshot-all={dst}", "--console=plain"], check=True)
+
+
+def native_shot(name: str, dst: Path, gpu: str):
+    bmp = dst / f"{name}.bmp"
+    run([str(NATIVE_EXE), f"--screen={name}", f"--screenshot={bmp}",
+         f"--gpu={gpu}", f"--width={WIDTH}", f"--height={HEIGHT}"],
+        check=False, timeout=60)
+    if bmp.exists():
+        Image.open(bmp).convert("RGB").save(dst / f"{name}.png")
+        bmp.unlink()
+
+
+def diff_pair(native: Image.Image, jvm: Image.Image):
+    """Return (percent_differing, amplified_diff_image)."""
+    w = min(native.width, jvm.width)
+    h = min(native.height, jvm.height)
+    a = native.crop((0, 0, w, h)).convert("RGB")
+    b = jvm.crop((0, 0, w, h)).convert("RGB")
+    diff = ImageChops.difference(a, b)
+    # A pixel "differs" if any channel exceeds TOL.
+    gray = diff.convert("L")
+    mask = gray.point(lambda p: 255 if p > TOL else 0)
+    differing = sum(mask.point(lambda p: 1 if p else 0).getdata())
+    pct = 100.0 * differing / (w * h)
+    amplified = diff.point(lambda p: min(255, p * 4))
+    return pct, amplified
+
+
+def side_by_side(native, jvm, diff, path):
+    w = min(native.width, jvm.width)
+    h = min(native.height, jvm.height)
+    canvas = Image.new("RGB", (w * 3 + 20, h + 20), (16, 16, 16))
+    canvas.paste(native.crop((0, 0, w, h)), (0, 10))
+    canvas.paste(jvm.crop((0, 0, w, h)), (w + 10, 10))
+    canvas.paste(diff, (w * 2 + 20, 10))
+    canvas.save(path)
+
+
+def main():
+    argv = [a for a in sys.argv[1:] if not a.startswith("--")]
+    flags = [a for a in sys.argv[1:] if a.startswith("--")]
+    no_build = "--no-build" in flags
+    gpu = next((f.split("=", 1)[1] for f in flags if f.startswith("--gpu=")), "sdl3")
+
+    OUT.mkdir(parents=True, exist_ok=True)
+    jvm_dir = OUT / "_jvm"
+    # Clear last run's pct-prefixed visualizations so stale percentages don't
+    # linger alongside the fresh ones.
+    for old in list(OUT.glob("*_compare.png")) + list(OUT.glob("*_diff.png")):
+        old.unlink()
+
+    if not no_build:
+        build()
+        if jvm_dir.exists():
+            shutil.rmtree(jvm_dir)
+        jvm_dir.mkdir(parents=True)
+        jvm_shots(jvm_dir)
+
+    # Screen set: the JVM run enumerates the full registry → use its PNGs as the
+    # source of truth for names (native takes one exe launch each).
+    names = sorted(p.stem for p in jvm_dir.glob("*.png"))
+    if argv:
+        wanted = {n.lower() for n in argv}
+        names = [n for n in names if n.lower() in wanted]
+    if not names:
+        print("No screens matched.", file=sys.stderr)
+        return 1
+
+    results = []
+    for name in names:
+        jvm_png = jvm_dir / f"{name}.png"
+        if not no_build or not (OUT / f"{name}.native.png").exists():
+            native_shot(name, OUT, gpu)
+            src = OUT / f"{name}.png"
+            if src.exists():
+                src.replace(OUT / f"{name}.native.png")
+        native_png = OUT / f"{name}.native.png"
+        if not native_png.exists():
+            results.append((name, None))
+            continue
+        native = Image.open(native_png).convert("RGB")
+        jvm = Image.open(jvm_png).convert("RGB")
+        pct, amp = diff_pair(native, jvm)
+        # Zero-padded pct prefix → worst-first in any file listing.
+        prefix = f"{pct:06.2f}"
+        amp.save(OUT / f"{prefix}_{name}_diff.png")
+        side_by_side(native, jvm, amp, OUT / f"{prefix}_{name}_compare.png")
+        results.append((name, pct))
+        print(f"  {name:28s} {pct:6.2f}% differing")
+
+    results.sort(key=lambda r: (-1 if r[1] is None else r[1]), reverse=True)
+    lines = ["screen                        %differ", "-" * 40]
+    for name, pct in results:
+        lines.append(f"{name:28s}  {'NATIVE FAILED' if pct is None else f'{pct:6.2f}%'}")
+    report = "\n".join(lines)
+    (OUT / "report.txt").write_text(report + "\n", encoding="utf-8")
+    print("\n" + report)
+    print(f"\nDiff images + report in {OUT}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())