fix(sdl): stop re-rasterizing text at device size — popup/dialog text no longer steps size/weight

Regression from 120abbad's glyph device-scaling: drawNativeText scaled the font size by the layer affine (inFontSize * scaleY, int-quantized) and re-rasterized. Under an animated layer scale — every Material DropdownMenu/AlertDialog enter transition scale-animates (Menu.kt scaleX/scaleY) — text re-rasterized at each integer size every frame, so it visibly stepped through sizes and (via SDL3_ttf re-hinting) weights as the popup grew in. User-reported, seen across dropdowns and dialogs. Revert to rasterising at LOGICAL font size + 1:1 blit at the affine-mapped position (the pre-120abbad behaviour): the layer scale reaches text POSITION but not glyph size, so animated-scale popups are stable. Keeps 120abbad's separate clip-mask AA/overlap fixes. Trade-off: statically graphicsLayer-scaled text renders at logical size (a rare, minor parity gap) — smoothly scaling glyphs needs blit-scaling a logical rasterisation (noted for a future text-renderer pass). Verified: demo dropdown opens with clean uniform text; text no longer scales with the layer, so mid-animation == settled by construction.
cleanup: delete dead modifier scaffolding + fix demo's fake cacheKey claims
2026-10-05 18:57:26 +00:00 · 2026-07-14 20:19:40 +02:00 · 2026-07-14 20:02:30 +02:00 · 2026-07-14 19:54:04 +02:00 · 2026-07-14 19:53:12 +02:00 · 2026-07-14 19:52:24 +02:00
20 changed files with 1179 additions and 212 deletions
@@ -458,6 +458,96 @@ build tell you what broke.
  `Dialog` / `DropdownMenu` / `DropdownMenuItem` / `TooltipBox` (m3 doesn't
  ship drop-in equivalents for our anchor / scrim patterns).

+## Tooling — what's available and when to reach for it
+
+Index of the repo's tooling. Each entry says when to use it and points at its
+own README for detail; the parity/profiler/probe entries are expanded below
+since they're newer.
+
+| Tool | Reach for it when | Detail |
+|------|-------------------|--------|
+| `python scripts/build-sdl/build-all.py` | building/refreshing the static SDL3/TTF/image/FreeType libs under `libs/` (once per host, or after bumping `build-sdl.properties`) | "Building" above |
+| `scripts/compose-fork/sync.sh` | re-syncing vendored upstream `androidx.compose.*` after a fresh checkout or a `compose.properties` ref bump; `format-manifest.py` to re-align a `compose-fork.txt` | "Vendor sync workflow" above + `scripts/compose-fork/README.md` |
+| `./gradlew apiDump && python scripts/compose-coverage.py` | measuring how much upstream public API the port actually covers, per module (`--missing <module>` lists uncovered decls) | "Vendoring" above |
+| `scripts/generate-material-symbols.py` / `subset-material-symbols.py` | regenerating the Material Symbols codepoints, or hb-subsetting bundled icon fonts to used glyphs (the latter runs automatically in app Zip tasks under `-PsubsetIcons`) | — |
+| **`scripts/parity/parity.py`** | after ANY renderer/layout change: catch a screen that visually diverged native-vs-JVM (missing content, wrong shape/colour, broken clip) | `scripts/parity/README.md` + below |
+| **`scripts/probe/probe.py`** | reproducing a specific interaction bug (click/hover/hold at a point) or grabbing one screen's pixels deterministically | `scripts/probe/README.md` + below |
+| **`CDN_PROFILE=1 <app>`** | finding where a slow frame goes (per-phase main-loop timings) before optimizing | below |
+| bridge plugin (`com.bitsycore.compose-desktop-native.bridge`) | consuming the published klibs from a third-party app | `gradle-plugin/compose-desktop-native-bridge/README.md` |
+| `demo --screen=<Name>` / `--screenshot=` / `--nav3test` / `--backtest` / `--multiwintest` | driving one screen headless, or the regression probes for nav3 / predictive-back / multi-window | `demo/src/nativeMain/kotlin/MainNative.kt` |
+
+Whole-project renderer-touching change → run **parity** (broad net). Chasing
+one reported interaction → **probe** (targeted). Slow → **profiler** first,
+optimize second. See `ROADMAP.md` for the renderer work these support.
+
+### Frame profiler — `CDN_PROFILE=1`
+
+Set the env var (`CDN_PROFILE=1`, or `=<path>` for a specific file) and run any
+native app; every ~2 s of rendered frames it writes avg/max ms per main-loop
+phase (`events` / `app` pump / `pump` per-window / `render`) to a FILE
+(`cdn_profile.log` by default — works for GUI-subsystem apps like the demo that
+have no console). The line also carries render SUB-phases (`layout` / `draw` /
+`present`) and per-frame DRAW COUNTERS from `DrawStats` (`geo` =
+SDL_RenderGeometry submits, `verts`, `masks` = rounded-clip offscreen passes,
+`text`, `img` blits) — so you can see WHAT `draw` is doing, not just that it's
+slow. `CDN_FORCERENDER=1` renders every frame (bypasses idle-skip) so
+steady-state timings can be read on otherwise-idle static screens.
+
+**Caveat learned the hard way:** `present` is vsync-blocking, so every timing is
+capped by the DISPLAY refresh of the machine running the app. A 75 Hz dev
+display makes every app look "75 fps, present-bound" no matter what — so profile
+on the TARGET refresh rate before concluding anything about a frame-rate gap
+(the demo-70 / apidemo-144 report could not be reproduced on a 75 Hz box, where
+both pinned at 75 fps and the demo's `draw` was actually the lighter of the two).
+
+### Interaction probe — `scripts/probe/`
+
+Launches a native app, sends **window-client-relative** input (click / hover /
+hold, fractional coords addressed by process name so it ignores window
+position/focus) and captures the client area via `PrintWindow` (works even
+when occluded). The packaged form of the rigs that reproduced the
+square-on-click and TLS-chain bugs. Windows-only. See its README.
+
+### Parity harness — native-vs-JVM screenshot diff (`scripts/parity/`)
+
+`: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,
@@ -0,0 +1,114 @@
+# Next session — renderer caching / retained layers
+
+## RESOLVED: the 70-vs-144 "gap" was two monitors, not a bug
+
+The user has a **75 Hz main screen + a 144 Hz second screen**. Each app's FPS is
+just the refresh of whichever monitor its window opened on (SDL locks vsync to
+the window's current display). demo happened to open on the 75 Hz screen,
+apidemo on the 144 Hz one. Move the demo to the 144 Hz screen and it hits ~144.
+
+Instrumentation confirmed there is NO performance problem: both apps have only
+~3.7 ms `draw` per frame (demo geo=40 masks=0; apidemo geo=146 masks=74 —
+apidemo does MORE and is fine), which fits both the 13.3 ms (75 Hz) and 6.7 ms
+(144 Hz) budgets with large headroom. Everything is present/vsync-bound.
+
+**Implication:** the retained-layers / dirty-region / cacheKey work is a
+SPECULATIVE optimization with NO demonstrated need right now — no app misses its
+frame budget. Don't spend the big content-redirect-primitive effort chasing a
+phantom. Revisit only if a real, animated, heavy screen is measured (with
+CDN_PROFILE, ON the target monitor) to exceed its budget.
+
+Still worth doing regardless of perf (correctness / cleanup, small):
+- Delete the dead `cacheKey` scaffolding (`GraphicsLayerModifier` /
+  `GraphicsLayerNode`, unread) OR wire it — and fix the demo's misleading
+  "(cached)" label (it uses a plain `graphicsLayer()`).
+
+--- Original investigation notes below (kept for context) ---
+
+
+Starting point after v0.1.19. Context for the perf work the profiling pointed at.
+
+## The problem (measured)
+
+The demo caps at ~70 fps on every screen while apidemo hits 144. Cause is NOT
+vsync (both use `SDL_SetRenderVSync(renderer, 1)`) — the demo is **draw-bound**:
+`CDN_PROFILE=1` showed draw ~34 ms cold / ~14 ms steady, present only ~1.3 ms.
+The renderer is **immediate-mode**: every rendered frame walks the layout tree
+and re-tessellates everything (text → glyph quads, shapes → triangles). The
+always-present sidebar (30+ text rows + icons) is re-tessellated each frame.
+
+Two open threads:
+
+### FINDING (updated) — the 70-vs-144 is NOT reproducible on a 75 Hz dev box
+
+Instrumented the draw phase (`DrawStats`: geo/verts/masks/text/img) + added
+`CDN_FORCERENDER=1`. Measured both apps forced-continuous:
+- demo:    draw ~3.7ms, geo=40,  verts=6582,  masks=0,  text=51
+- apidemo: draw ~2.9ms, geo=146, verts=18576, masks=74, text=174
+BOTH pinned at exactly 150 frames/2s = 75 fps with present ~9ms — i.e. the DEV
+DISPLAY is 75 Hz, so everything is present/vsync-bound here and the demo's draw
+is actually LIGHTER than apidemo's. The "demo is draw-bound" theory is WRONG on
+this hardware; the 70-vs-144 split is specific to the user's 144 Hz monitor and
+can't be reproduced/diagnosed from a 75 Hz box.
+
+NEXT STEP FOR THE USER (144 Hz machine): run both apps with
+`CDN_FORCERENDER=1 CDN_PROFILE=1` and share the `cdn_profile.log` lines. If demo
+shows present ~13ms (75 fps) while apidemo shows present ~7ms (144 fps) at
+similar draw times, it's a present/vsync-path difference (driver / swap
+interval / DWM), NOT draw cost — a different investigation than caching.
+
+The demo idles correctly when static (verified: 2 frames headless, even while
+hovering the sidebar), so there's NO spurious-continuous-render bug — thread A
+below is resolved as a non-issue.
+
+### A. Why does the demo render CONTINUOUSLY? (investigate FIRST — likely cheaper)
+
+Headless the demo idled (2 frames); interactively you see a constant 70-71 fps,
+so something invalidates every frame. Prime suspect: a **hover self-loop** — the
+main loop dispatches a synthetic hover every rendered frame
+(`ComposeWindow.renderFrame`: `if (hasMousePos) host.onPointerRaw(...)`), and if
+that perpetually re-invalidates a hover-reactive sidebar row, the app never
+idles while the cursor is over it. If confirmed, the fix is to stop the spurious
+invalidation so static screens idle (→ sidebar stops re-tessellating because
+nothing renders) — small and targeted, no caching needed.
+- Quick test: does the demo's FPS-title stop updating when the mouse leaves the
+  window? If yes → hover loop confirmed.
+- Look at: `renderFrame` synthetic hover; how hover state feeds `needsFrame` /
+  `hasPendingWork` / `shouldRender()`.
+
+### B. cacheKey / retained-layer texture caching (bigger — the "renderer rewrite")
+
+`Modifier.graphicsLayer(cacheKey=…)` exists as API (`GraphicsLayerModifier` /
+`GraphicsLayerNode` in `element/ModifierElements.kt`) but is **dead
+scaffolding**: `cacheKey` is stored and never read by the renderer; the node is
+a bare `Modifier.Node` with no draw behaviour (comment: "stays dormant until the
+renderer rewrite drives it"). The demo's GraphicsLayer "(cached)" section uses a
+plain `graphicsLayer()` — the label is aspirational; nothing is cached.
+
+Blocker for real texture caching: it needs to render a subtree's `drawContent()`
+into an **offscreen canvas**, and the renderer has no way to redirect
+`drawContent()` off the frame canvas. `GraphicsLayer.native.draw()` replays its
+recorded block against a canvas via `drawScope.draw(…, canvas, …)`, but
+`drawContent()` is bound to the outer `ContentDrawScope`'s canvas, which nothing
+swaps. The vector/icon offscreen path works only because it draws an explicit
+object, not opaque `drawContent()`.
+
+So the real unit of work is a **content-redirect primitive**: make the
+`ContentDrawScope` canvas swappable (or add a coordinator-level "draw this
+subtree into canvas X"). That primitive is the foundation for BOTH cacheKey
+(retained layers) AND dirty-region rendering. Infrastructure that already
+exists to build on: `OffscreenRenderer` (`createImageBitmap` + `createCanvas`),
+`SdlImageBitmap` render-target textures + `drawImage` blit-back, and the
+`NativeReleaseQueue` for freeing cached textures.
+
+Cleanup to do regardless: either implement `cacheKey` or delete the dead
+`GraphicsLayerModifier`/`GraphicsLayerNode` scaffolding and fix the demo's
+misleading "(cached)" label.
+
+## Tooling ready for this work
+
+- `CDN_PROFILE=1 <app>` → per-phase timings (layout/draw/present) to a file.
+- `scripts/parity/parity.py` → native-vs-JVM screenshot diff (regression net).
+- `scripts/probe/probe.py` → drive a native window (click/hover/hold) + capture.
+- See ROADMAP.md item 2 (dirty regions + retained layers promoted, with the
+  demo evidence) and CLAUDE.md "Tooling".
@@ -261,6 +261,24 @@ RESUMED, unfocused → STARTED, minimized → CREATED), `ViewModelStoreOwner`
 ViewModels scope per nav entry, per window, or anywhere in between — same
 semantics as Android.

+## Tooling
+
+Helper scripts live under `scripts/`; each has its own README with detail.
+
+| Tool | Use it to | More |
+|------|-----------|------|
+| `scripts/build-sdl/build-all.py` | build the static SDL3 / TTF / image / FreeType libs | see **Building** above |
+| `scripts/compose-fork/sync.sh` | re-sync the vendored upstream Compose sources | [README](scripts/compose-fork/README.md) |
+| `scripts/parity/parity.py` | diff every demo screen native-vs-JVM to catch render regressions | [README](scripts/parity/README.md) |
+| `scripts/probe/probe.py` | drive a native window (click/hover/hold) + screenshot it | [README](scripts/probe/README.md) |
+| `CDN_PROFILE=1 <app>` | print per-phase frame timings to find slow frames | — |
+| `python scripts/compose-coverage.py` | measure API coverage vs upstream (after `./gradlew apiDump`) | — |
+
+Building on the port from another project? Use the bridge plugin —
+[gradle-plugin/compose-desktop-native-bridge](gradle-plugin/compose-desktop-native-bridge/README.md).
+Contributor-facing detail (including how to read the parity `%differ`) is in
+[CLAUDE.md](CLAUDE.md#tooling--whats-available-and-when-to-reach-for-it).
+
 ## License

 [MIT](LICENSE.md).
@@ -0,0 +1,105 @@
+# 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.
+- [ ] **Dirty-region rendering** — NEXT, promoted by profiling: the app
+  re-tessellates the whole window on any invalidation. Accumulate damage from
+  invalidated layers and scissor the redraw. Biggest lever for heavy scenes.
+  Evidence (CDN_PROFILE): the full demo is DRAW-bound — draw ~34ms cold /
+  ~14ms steady, present only ~1.3ms — because it re-tessellates the whole
+  always-present sidebar (30+ text rows + icons) every rendered frame. That
+  ~14ms caps it near 70 fps; apidemo's lighter chrome fits the 6.9ms budget
+  and reaches the 144 Hz vsync ceiling. The "70 ≈ 144/2" look is coincidence,
+  NOT a vsync-half artifact — both use vsync(1). Retained layers / dirty
+  regions would stop re-tessellating the static sidebar.
+- [ ] **Retained layer textures** — cache a layer's rendered output keyed by
+  its draw content (RenderNode-style); static subtrees stop re-tessellating.
+- [ ] **Right-size clip scratch targets** (LOW — profiling showed masks aren't
+  a hot path after lazy clips): size scratch textures to the clip bbox.
+  Memory, not frame time.
+- [ ] **Glyph atlas** — text draws currently break geometry batches (z-order
+  flush per run); an atlas texture lets glyphs ride the vertex batches.
+
+## 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. NOTE: this list predates several
+fixes — verify a claim against the parity heatmaps before acting (gradients and
+rotation both turned out already-working). In a parity `_diff.png`: a solid
+bright block = real gap; ghosted text = font drift.
+
+- [x] **Gradient brushes on SDL** — samplers were already implemented; the real
+  bug was UNDER-SAMPLING: fills sampled only corners, so radial/sweep on a
+  rect/round-rect rendered FLAT (a square's corners are equidistant from centre
+  → identical t). Gradient fills now grid-mesh the interior (emitRectMesh);
+  radial/sweep match upstream. (Solid fills unchanged — one quad.)
+- [x] **Layer rotation** — verified WORKING (demo GraphicsLayer "Rotation
+  (live)" + "Combined" rotate correctly); stale claim removed.
+- [ ] **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.
+- [x] Promote the press/hover automation rig into `scripts/probe/`:
+  window-CLIENT-relative input (click/hover/hold, fractional coords, process-
+  addressed) + PrintWindow capture (works occluded). See scripts/probe/README.md.
+
+## 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.
@@ -32,8 +32,11 @@ import com.compose.sdl.window.createPopupHostState
 import kotlinx.coroutines.*
 import kotlinx.coroutines.test.resetMain
 import kotlinx.coroutines.test.setMain
+import kotlinx.cinterop.toKString
 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
@@ -149,6 +152,7 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 		var vGcLastTicks = SDL_GetTicks()
 		var vRenderedSinceGc = false
 		while (!runtime.exitRequested) {
+			FrameProfiler.mark()
 			Snapshot.sendApplyNotifications()

 			// ============
@@ -176,6 +180,7 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 			}

 			mainDispatcher.drainPending()
+			FrameProfiler.phase("events")

 			// ============
 			//  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
+			FrameProfiler.phase("app")

 			// ============
 			//  Per-window pump + render.
@@ -208,13 +214,24 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 				Snapshot.sendApplyNotifications()
 				vW.frameClock.sendFrame()
 				yield()
+				FrameProfiler.phase("pump")
 				if (vW.shouldRender()) {
 					vW.renderFrame()
 					vAnyRendered = true
 					if (!vW.backend.vsyncEnabled) vAllVsync = false
 				}
+				FrameProfiler.phase("render")
 			}
 			runtime.reapDestroyed()
+			FrameProfiler.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,8 +280,78 @@ fun nativeComposeApp(content: @Composable ApplicationScope.() -> Unit) {
 	SDL_Quit()
 }

+/* CDN_PROFILE=1 — per-phase timings, printed every ~2s of rendered frames.
+   A named-phase SINGLETON so both the main loop (events / app / pump / render)
+   AND renderFrame's sub-steps (render.layout / render.draw / render.present)
+   report into one line. `mark()` resets the stopwatch; `phase(name)` charges
+   the elapsed since the last mark/phase to that name. Measure first, optimize
+   second — see ROADMAP.md. */
+@OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
+internal object FrameProfiler {
+	// null until first checked; then true/false for the run's lifetime.
+	private var fEnabled: Boolean? = null
+	// Output file — resolved once from CDN_PROFILE. Writing to a file (not
+	// stdout) lets GUI-subsystem apps (the demo links --subsystem,windows, so
+	// it has no console) be profiled too. CDN_PROFILE=1 → "cdn_profile.log" in
+	// the cwd; CDN_PROFILE=<path> → that path.
+	private var fPath: String = "cdn_profile.log"
+	val enabled: Boolean
+		get() = fEnabled ?: run {
+			val vEnv = platform.posix.getenv("CDN_PROFILE")?.toKString()
+			if (vEnv != null && vEnv != "1" && vEnv.isNotEmpty()) fPath = vEnv
+			(vEnv != null).also { fEnabled = it }
+		}
+
+	private val fFreq = SDL_GetPerformanceFrequency().toDouble()
+	// Insertion-ordered so the printed line follows the call order.
+	private val fSum = LinkedHashMap<String, Double>()
+	private val fMax = LinkedHashMap<String, Double>()
+	private var fFrames = 0
+	private var fLastPrintMs = SDL_GetTicks()
+	private var fMark = 0uL
+
+	fun mark() { if (enabled) fMark = SDL_GetPerformanceCounter() }
+
+	fun phase(inName: String) {
+		if (!enabled) return
+		val vNow = SDL_GetPerformanceCounter()
+		val vMs = (vNow - fMark).toDouble() * 1000.0 / fFreq
+		fSum[inName] = (fSum[inName] ?: 0.0) + vMs
+		if (vMs > (fMax[inName] ?: 0.0)) fMax[inName] = vMs
+		fMark = vNow
+	}
+
+	fun frameDone(inRendered: Boolean) {
+		if (!enabled) return
+		if (inRendered) fFrames++
+		val vNowMs = SDL_GetTicks()
+		if (vNowMs - fLastPrintMs >= 2000u && fFrames > 0) {
+			val vParts = fSum.keys.map { vName ->
+				val vAvg = (fSum[vName] ?: 0.0) / fFrames
+				"$vName=${(vAvg * 100).toInt() / 100.0}/${((fMax[vName] ?: 0.0) * 100).toInt() / 100.0}ms"
+			}
+			// Per-frame draw-work averages (see DrawStats): what's inside `draw`.
+			val vStats = com.compose.sdl.graphics.DrawStats
+			val vDraw = "geo=${vStats.geometrySubmits / fFrames} verts=${vStats.vertices / fFrames} " +
+				"masks=${vStats.maskRealizations / fFrames} text=${vStats.textDraws / fFrames} img=${vStats.imageBlits / fFrames}"
+			val vLine = "[profile] frames=$fFrames avg/max " + vParts.joinToString(" ") + " | per-frame " + vDraw + "\n"
+			val vFile = platform.posix.fopen(fPath, "a")
+			if (vFile != null) {
+				platform.posix.fputs(vLine, vFile)
+				platform.posix.fclose(vFile)
+			}
+			vStats.reset()
+			fSum.clear(); fMax.clear()
+			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). */
+private val kForceRender: Boolean = platform.posix.getenv("CDN_FORCERENDER") != null
+
@OptIn(kotlin.native.runtime.NativeRuntimeApi::class)
 private fun collectNativeGarbage() = kotlin.native.runtime.GC.collect()

@@ -664,7 +752,10 @@ internal class WindowInstance(
 	//  Frame pump

 	fun shouldRender(): Boolean =
-		needsFrame || (recomposer?.hasPendingWork == true) || onFrame != null
+		needsFrame || (recomposer?.hasPendingWork == true) || onFrame != null || kForceRender
+
+	// TEMP measurement: CDN_FORCERENDER=1 forces every frame to render so
+	// sustained steady-state timings can be measured on otherwise-idle screens.

 	fun renderFrame() {
 		val vRender = renderBackend ?: return
@@ -675,6 +766,7 @@ internal class WindowInstance(
 		vRender.ensureSize(backend.pixelWidth, backend.pixelHeight)
 		host.setConstraints(backend.pixelWidth, backend.pixelHeight)
 		host.measureAndLayout()
+		FrameProfiler.phase("  layout")

 		// Hover refresh after layout (upstream skiko: SyntheticEventSender).
 		if (hasMousePos) {
@@ -687,7 +779,9 @@ internal class WindowInstance(
 			// Probe consumers end the app when their scenario completes.
 			facade.close()
 		}
+		FrameProfiler.phase("  draw")
 		vRender.endFrame()
+		FrameProfiler.phase("  present")
 		frameIndex++

 		// FPS — refreshed ~once a second, per window.
@@ -1,97 +0,0 @@
-package com.compose.sdl.element
-
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.graphics.Shape
-import androidx.compose.ui.graphics.TransformOrigin
-import androidx.compose.ui.node.ModifierNodeElement
-
-// ==================
-// MARK: Project modifier elements
-// ==================
-// Small set of project-only modifier elements — each pairs a
-// `ModifierNodeElement<XxxNode>` with a `XxxNode : Modifier.Node`. Upstream
-// LayoutNode reads them through the chain (ModifierNodeElement IS-A
-// Modifier.Element). Everything gesture-related has been removed — pointer
-// input, text input, right/middle click, drag: all go through the standard
-// `Modifier.pointerInput` + `detectTapGestures` / `detectDragGestures` /
-// `awaitPointerEventScope` APIs upstream now supplies. What's left is the
-// two elements the renderer still owns directly:
-//   * ClipModifier — GraphicsLayer.kt lowers `clip = true` to it.
-//   * GraphicsLayerModifier — the transform / alpha / cache pipeline.
-
-class ClipModifier(val shape: Shape) : ModifierNodeElement<ClipNode>() {
-    override fun create() = ClipNode(shape)
-    override fun update(node: ClipNode) { node.shape = shape }
-    override fun hashCode(): Int = shape.hashCode()
-    override fun equals(other: Any?): Boolean = other is ClipModifier && other.shape == shape
-}
-class ClipNode(var shape: Shape) : Modifier.Node()
-
-// ==================
-// MARK: GraphicsLayerModifier
-// ==================
-
-/**
- * A "graphics layer" element: alpha + 2D transform (scale / rotation /
- * translation), with an optional cacheKey that opts the subtree into
- * render-to-texture caching across frames. See `Modifier.graphicsLayer`
- * (in `androidx.compose.ui.graphics`) for the caching semantics.
- *
- * The renderer reads this element directly via the `LayoutNode.graphicsLayer`
- * `foldIn` over the chain; the paired [GraphicsLayerNode] lifecycle stays
- * dormant until the renderer rewrite drives it.
- */
-class GraphicsLayerModifier(
-    val alpha: Float = 1f,
-    val scaleX: Float = 1f,
-    val scaleY: Float = 1f,
-    val rotationZ: Float = 0f,
-    val translationX: Float = 0f,
-    val translationY: Float = 0f,
-    val transformOrigin: TransformOrigin = TransformOrigin.Center,
-    val cacheKey: Any? = null,
-) : ModifierNodeElement<GraphicsLayerNode>() {
-
-    val needsLayer: Boolean
-        get() = alpha < 1f || cacheKey != null
-
-    val needsTransform: Boolean
-        get() = scaleX != 1f || scaleY != 1f || rotationZ != 0f ||
-            translationX != 0f || translationY != 0f
-
-    val isIdentity: Boolean
-        get() = !needsLayer && !needsTransform
-
-    override fun create() =
-        GraphicsLayerNode(alpha, scaleX, scaleY, rotationZ, translationX, translationY, transformOrigin, cacheKey)
-    override fun update(node: GraphicsLayerNode) {
-        node.alpha = alpha; node.scaleX = scaleX; node.scaleY = scaleY
-        node.rotationZ = rotationZ; node.translationX = translationX; node.translationY = translationY
-        node.transformOrigin = transformOrigin; node.cacheKey = cacheKey
-    }
-    override fun hashCode(): Int {
-        var v = alpha.hashCode()
-        v = 31 * v + scaleX.hashCode(); v = 31 * v + scaleY.hashCode()
-        v = 31 * v + rotationZ.hashCode()
-        v = 31 * v + translationX.hashCode(); v = 31 * v + translationY.hashCode()
-        v = 31 * v + transformOrigin.hashCode(); v = 31 * v + (cacheKey?.hashCode() ?: 0)
-        return v
-    }
-    override fun equals(other: Any?): Boolean =
-        other is GraphicsLayerModifier &&
-            other.alpha == alpha && other.scaleX == scaleX && other.scaleY == scaleY &&
-            other.rotationZ == rotationZ &&
-            other.translationX == translationX && other.translationY == translationY &&
-            other.transformOrigin == transformOrigin && other.cacheKey == cacheKey
-}
-
-class GraphicsLayerNode(
-    var alpha: Float,
-    var scaleX: Float,
-    var scaleY: Float,
-    var rotationZ: Float,
-    var translationX: Float,
-    var translationY: Float,
-    var transformOrigin: TransformOrigin,
-    var cacheKey: Any?,
-) : Modifier.Node()
@@ -0,0 +1,34 @@
+package com.compose.sdl.graphics
+
+// ==================
+// MARK: DrawStats — per-frame renderer work counters (diagnostic)
+// ==================
+
+/**
+ * Cheap per-frame counters the SDL draw path bumps and the frame profiler
+ * reads, to answer "what inside `draw` costs the time?" — geometry submissions
+ * (SDL_RenderGeometry calls), total vertices tessellated, rounded-clip mask
+ * realizations (offscreen render-target passes — the expensive ones), text
+ * blits and image blits. Reset each frame by the profiler after reading.
+ *
+ * Single-threaded (all draw is on the main thread), so plain vars are fine.
+ * Zero overhead when the profiler isn't reading — just integer increments.
+ */
+object DrawStats {
+	var geometrySubmits: Int = 0
+	var vertices: Int = 0
+	var maskRealizations: Int = 0
+	var textDraws: Int = 0
+	var imageBlits: Int = 0
+
+	fun reset() {
+		geometrySubmits = 0
+		vertices = 0
+		maskRealizations = 0
+		textDraws = 0
+		imageBlits = 0
+	}
+
+	fun summary(): String =
+		"geo=$geometrySubmits verts=$vertices masks=$maskRealizations text=$textDraws img=$imageBlits"
+}
@@ -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
+	}
+}
@@ -228,15 +228,27 @@ internal class Sdl3Canvas(
 		}
 	}

-	/* Convert pending clips into real offscreen mask layers (outermost first). */
+	/* 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()
-			// A clipRect after the push may have narrowed the visible area.
-			val vRegion = intersect(fClip, vPending.region)
+			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.
@@ -247,6 +259,7 @@ internal class Sdl3Canvas(
 			fClip = vRegion
 			applyClip()
 			clearRegion(vRegion)
+			com.compose.sdl.graphics.DrawStats.maskRealizations++
 			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
@@ -258,6 +271,10 @@ internal class Sdl3Canvas(
 				}
 			}
 		}
+		// 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
@@ -947,6 +964,7 @@ internal class Sdl3Canvas(
 		// 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)
+		com.compose.sdl.graphics.DrawStats.textDraws++
 		fScope.flush()
 		// Paragraph-level decoration bits forwarded to every wrapped line.
 		val vUnderline = inTextDecoration?.contains(androidx.compose.ui.text.style.TextDecoration.Underline) == true
@@ -962,26 +980,25 @@ 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)
-
+		// Text is rasterised at its LOGICAL font size (stable glyph-texture cache
+		// + stable hinting) and blit 1:1 at the affine-mapped pen position; the
+		// layer's scale reaches position but NOT glyph size. Re-rasterising at a
+		// per-frame device size (an earlier attempt) made text under an animated
+		// layer scale — every Material popup/dropdown enter transition
+		// (Menu.kt scaleX/scaleY) — step through integer sizes with visible
+		// size/weight jumps, since SDL3_ttf re-hints at each size. Smoothly
+		// scaling glyphs would need blit-scaling a logical-size rasterisation
+		// (JVM/Skia GPU-scales the layer) — a future text-renderer enhancement;
+		// until then logical-size + no glyph scale is the stable choice.
 		if (inFontFamily != null && IconFont.isIconFamily(inFontFamily)) {
 			vTr.drawText(
 				inText = inText,
 				inX = mapX(inX, inY).toInt(),
 				inY = mapY(inX, inY).toInt(),
-				inBoxWidth = (inBoxWidth * vTextScaleX).toInt(),
-				inBoxHeight = (inBoxHeight * vTextScaleY).toInt(),
+				inBoxWidth = inBoxWidth.toInt(),
+				inBoxHeight = inBoxHeight.toInt(),
 				inColor = vColor,
-				inFontSize = vDeviceFontPx,
+				inFontSize = inFontSizePx,
 				inAlign = inTextAlign,
 				inFontFamily = inFontFamily,
 				inFontVariations = inFontVariations,
@@ -1024,10 +1041,10 @@ internal class Sdl3Canvas(
 				// scale with the layer. Rotation still only repositions.
 				inX = mapX(inX, vLineY).toInt(),
 				inY = mapY(inX, vLineY).toInt(),
-				inBoxWidth = (inBoxWidth * vTextScaleX).toInt(),
-				inBoxHeight = (vLineH * vTextScaleY).toInt(),
+				inBoxWidth = inBoxWidth.toInt(),
+				inBoxHeight = vLineH.toInt(),
 				inColor = vColor,
-				inFontSize = vDeviceFontPx,
+				inFontSize = inFontSizePx,
 				inAlign = inTextAlign,
 				inFontFamily = inFontFamily,
 				inFontVariations = inFontVariations,
@@ -1099,6 +1116,7 @@ internal class Sdl3Canvas(
 	) {
 		realizePendingClips()
 		val vTex = (image as? SdlImageBitmap)?.texture ?: return
+		com.compose.sdl.graphics.DrawStats.imageBlits++
 		// Commit pending frame geometry and re-assert this canvas's target + clip
 		// (an offscreen render just borrowed the render target).
 		fScope.flush()
@@ -141,6 +141,8 @@ internal class Sdl3DrawScope(
 			)
 		}
 		SDL_RenderGeometry(fRenderer.reinterpret(), null, fBatch, fBatchCount, null, 0)
+		com.compose.sdl.graphics.DrawStats.geometrySubmits++
+		com.compose.sdl.graphics.DrawStats.vertices += fBatchCount
 		fBatchCount = 0
 	}

@@ -243,7 +245,10 @@ internal class Sdl3DrawScope(
 		val vB = vT + size.height
 		when (style) {
 			Fill -> {
-				emitQuad(vL, vT, vR, vT, vR, vB, vL, vB, vSampler)
+				// Gradient fills need interior samples (see emitRectMesh); solid
+				// fills are a single flat quad.
+				if (brush is SolidColor) emitQuad(vL, vT, vR, vT, vR, vB, vL, vB, vSampler)
+				else emitRectMesh(vL, vT, vR, vB, vSampler)
 				// Axis-aligned rects are pixel-crisp and need no AA. When the affine
 				// rotates/shears them, the edges become diagonal — feather each edge
 				// outward (normals in local space; the matrix orients them on screen).
@@ -524,20 +529,30 @@ internal class Sdl3DrawScope(
 		val vY = fOriginY + topLeft.y
 		val vW = size.width
 		val vH = size.height
+		// Gradient fills sample per-vertex, so the interior must be meshed
+		// (corner-only sampling renders radial/sweep flat — see emitRectMesh);
+		// solid fills stay single quads.
+		val vGrad = brush !is SolidColor
 		if (vR <= 0f) {
-			// Trivial: just two triangles.
-			emitQuad(vX, vY, vX + vW, vY, vX + vW, vY + vH, vX, vY + vH, vSampler)
+			if (vGrad) emitRectMesh(vX, vY, vX + vW, vY + vH, vSampler)
+			else emitQuad(vX, vY, vX + vW, vY, vX + vW, vY + vH, vX, vY + vH, vSampler)
 			return
 		}
 		// Body in 3 strips: middle (full width × inner height), top edge,
 		// bottom edge — plus the 4 corner arcs.
 		if (style == Fill) {
-			// Middle strip
-			emitQuad(vX, vY + vR, vX + vW, vY + vR, vX + vW, vY + vH - vR, vX, vY + vH - vR, vSampler)
-			// Top edge (between left+right corners)
-			emitQuad(vX + vR, vY, vX + vW - vR, vY, vX + vW - vR, vY + vR, vX + vR, vY + vR, vSampler)
-			// Bottom edge
-			emitQuad(vX + vR, vY + vH - vR, vX + vW - vR, vY + vH - vR, vX + vW - vR, vY + vH, vX + vR, vY + vH, vSampler)
+			if (vGrad) {
+				emitRectMesh(vX, vY + vR, vX + vW, vY + vH - vR, vSampler)          // middle
+				emitRectMesh(vX + vR, vY, vX + vW - vR, vY + vR, vSampler)          // top edge
+				emitRectMesh(vX + vR, vY + vH - vR, vX + vW - vR, vY + vH, vSampler) // bottom edge
+			} else {
+				// Middle strip
+				emitQuad(vX, vY + vR, vX + vW, vY + vR, vX + vW, vY + vH - vR, vX, vY + vH - vR, vSampler)
+				// Top edge (between left+right corners)
+				emitQuad(vX + vR, vY, vX + vW - vR, vY, vX + vW - vR, vY + vR, vX + vR, vY + vR, vSampler)
+				// Bottom edge
+				emitQuad(vX + vR, vY + vH - vR, vX + vW - vR, vY + vH - vR, vX + vW - vR, vY + vH, vX + vR, vY + vH, vSampler)
+			}
 			// 4 corner fills — segment count adapts to the corner radius.
 			val vSeg = arcSegments(90f, vR)
 			emitFilledArc(vX + vR,          vY + vR,         vR, vR, 180f,  90f, false, vSeg, vSampler)
@@ -854,6 +869,34 @@ internal class Sdl3DrawScope(
 		emitTri(ax, ay, cx, cy, dx, dy, inSampler)
 	}

+	// Axis-aligned rect subdivided into a grid, so a per-vertex sampler is
+	// evaluated across the INTERIOR, not just the 4 corners. Corner-only
+	// sampling renders radial/sweep gradients flat (a square's corners are all
+	// equidistant from its centre → identical t → solid fill) and clips
+	// non-uniform multi-stop linear ramps. SDL interpolates linearly within
+	// each cell, so ~16 cells/axis tracks the gradient curve closely. Solid
+	// fills never come here (they use emitQuad — one quad).
+	private fun emitRectMesh(
+		inL: Float, inT: Float, inR: Float, inB: Float, inSampler: Sampler,
+	) {
+		// ~one cell per 8 device px per axis (1..24), so thin edge strips stay
+		// cheap while large fills get enough interior samples for the gradient.
+		val vCols = (((inR - inL) / 8f).toInt()).coerceIn(1, 24)
+		val vRows = (((inB - inT) / 8f).toInt()).coerceIn(1, 24)
+		val vW = (inR - inL) / vCols
+		val vH = (inB - inT) / vRows
+		for (vRow in 0 until vRows) {
+			val vY0 = inT + vRow * vH
+			val vY1 = if (vRow == vRows - 1) inB else vY0 + vH
+			for (vCol in 0 until vCols) {
+				val vX0 = inL + vCol * vW
+				val vX1 = if (vCol == vCols - 1) inR else vX0 + vW
+				emitTri(vX0, vY0, vX1, vY0, vX1, vY1, inSampler)
+				emitTri(vX0, vY0, vX1, vY1, vX0, vY1, inSampler)
+			}
+		}
+	}
+
 	private fun emitTri(
 		ax: Float, ay: Float, bx: Float, by: Float, cx: Float, cy: Float,
 		inSampler: Sampler,
@@ -893,7 +936,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 +963,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.
@@ -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,
@@ -42,55 +42,9 @@ internal fun GraphicsLayerScreen() {
 	Column(verticalArrangement = Arrangement.spacedBy(16.dp)) {
 		ScreenTitle(
 			"Modifier.graphicsLayer",
-			"2D transform (scale / rotation / translation) + alpha + optional cacheKey opt-in. " +
-				"When cacheKey is set, the renderer renders the subtree into an offscreen target once " +
-				"and reuses it while the key compares equal — change the key to invalidate.",
+			"2D transform (scale / rotation / translation) + alpha, applied to a subtree.",
 		)

-		Section(
-			"Cached subtree (cacheKey)",
-			"Identical to a fresh-drawn row visually, but the subtree is rendered once and reused while " +
-				"cacheKey doesn't change. Useful for static screens — no per-frame redraw of the chrome.",
-		) {
-			Row(horizontalArrangement = Arrangement.spacedBy(16.dp)) {
-				for (vI in 0..3) {
-					Box(
-						modifier = Modifier
-							.size(64.dp)
-							.graphicsLayer(),
-					) {
-						Canvas(modifier = Modifier.size(64.dp)) {
-							drawCircle(color = vPrimary, radius = 22f, center = Offset(32f, 32f))
-							drawCircle(color = vSecondary, radius = 12f, center = Offset(32f, 32f))
-						}
-					}
-				}
-				Text("(cached)", color = vPrimary, fontSize = 12.sp)
-			}
-		}
-
-		Section("Combined (cache + rotation)", "Cached subtree blitted with live rotation around its centre.") {
-			Row(horizontalArrangement = Arrangement.spacedBy(16.dp)) {
-				for (vI in 0..4) {
-					Box(
-						modifier = Modifier
-							.size(64.dp)
-							.graphicsLayer(
-								rotationZ = vSpin + vI * 30f,
-							),
-					) {
-						Canvas(modifier = Modifier.size(64.dp)) {
-							drawRect(
-								color = if (vI % 2 == 0) vPrimary else vSecondary,
-								topLeft = Offset(10f, 10f),
-								size = Size(44f, 44f),
-							)
-						}
-					}
-				}
-			}
-		}
-
 		Section("Rotation (live)", "Each tile holds the same shape rotated at multiples of the current spin angle.") {
 			Row(horizontalArrangement = Arrangement.spacedBy(16.dp)) {
 				for (vI in 0..4) {
@@ -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() }
+    }
+}
@@ -54,17 +54,24 @@ private val desktopTargets = mapOf(
 )

 private fun registerDataKresTasks(project: Project) {
-	val taskNames = project.tasks.names
-	val resPackage = project.resolveResourcePackage()
+	// 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"
-			if (linkName !in taskNames) continue
 			val zipName = "package${variant}ComposeResources$target"
-			if (zipName in taskNames) continue
-			val prepareNames = sourceSets
-				.map { "prepareComposeResourcesTaskFor" + it.replaceFirstChar { c -> c.uppercase() } }
-				.filter { it in taskNames }
+			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")
@@ -77,6 +84,10 @@ private fun registerDataKresTasks(project: Project) {
 				// 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() }
@@ -87,7 +98,7 @@ private fun registerDataKresTasks(project: Project) {
 					task.dependsOn(project.tasks.named(prepareName))
 				}
 			}
-			project.tasks.named(linkName) { it.dependsOn(zipTask) }
+			project.tasks.matching { it.name == linkName }.configureEach { it.dependsOn(zipTask) }
 		}
 	}
 }
@@ -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.
@@ -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())
@@ -0,0 +1,35 @@
+# Probe driver
+
+Launches a native compose-desktop-native app window, sends **window-relative**
+synthetic input, and captures the client area — for reproducing visual bugs
+deterministically (this is the packaged form of the rigs that caught the
+square-on-click and TLS-chain regressions).
+
+Why window-relative + PrintWindow: input coordinates are FRACTIONS of the
+window client rect and addressed by process name, so a probe doesn't depend on
+where the window landed or on it being foreground; capture uses `PrintWindow`,
+which grabs the window even when occluded or unfocused (a plain screen grab
+would catch whatever's on top).
+
+```bash
+# screenshot a demo screen
+python scripts/probe/probe.py demo --screen=Images --shot images.png
+
+# press-and-hold a point (fraction of the window) and capture DURING the press
+python scripts/probe/probe.py demo --screen=Buttons --hold 0.1,0.32 --shot press.png
+
+# hover then capture
+python scripts/probe/probe.py demo --screen=Shapes --hover 0.3,0.45 --shot hov.png
+
+# an app built elsewhere (e.g. the bridge example)
+python scripts/probe/probe.py shared --exe /path/to/shared.exe --click 0.5,0.5 --shot x.png
+```
+
+- `proc` = the window's process name (`demo`, `apidemo`, `shared`).
+- Actions run in order; `--hold` captures mid-press (async), `--click` /
+  `--hover` complete first. `--shot` captures after `--settle` seconds.
+- Windows-only (uses Win32 input + PrintWindow). Pillow only needed if you
+  post-process the PNG.
+
+Pairs with `scripts/parity/` (whole-screen diffing); this is for targeted
+interaction repro.
@@ -0,0 +1,28 @@
+param([string]$proc, [string]$out)
+# Capture a window's CLIENT area by process name, via PrintWindow — works even
+# when the window is occluded or not focused (unlike a screen grab). Used by the
+# probe driver to screenshot native app windows deterministically.
+Add-Type -AssemblyName System.Drawing
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public class Cap {
+    [DllImport("user32.dll")] public static extern bool GetClientRect(IntPtr h, out RECT r);
+    [DllImport("user32.dll")] public static extern bool PrintWindow(IntPtr h, IntPtr dc, uint flags);
+    public struct RECT { public int L, T, R, B; }
+}
+"@
+$h = (Get-Process $proc -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowHandle -ne 0 } | Select-Object -First 1).MainWindowHandle
+if (-not $h -or $h -eq [IntPtr]::Zero) { Write-Output "NO WINDOW"; exit 1 }
+$r = New-Object Cap+RECT
+[Cap]::GetClientRect($h, [ref]$r) | Out-Null
+$w = $r.R - $r.L; $ht = $r.B - $r.T
+if ($w -le 0 -or $ht -le 0) { Write-Output "ZERO SIZE"; exit 1 }
+$bmp = New-Object System.Drawing.Bitmap $w, $ht
+$g = [System.Drawing.Graphics]::FromImage($bmp)
+$hdc = $g.GetHdc()
+# flags=3 : PW_CLIENTONLY | PW_RENDERFULLCONTENT (captures accelerated content)
+[Cap]::PrintWindow($h, $hdc, 3) | Out-Null
+$g.ReleaseHdc($hdc)
+$bmp.Save($out, [System.Drawing.Imaging.ImageFormat]::Png)
+Write-Output "captured ${w}x${ht}"
@@ -0,0 +1,42 @@
+param(
+    [string]$proc,          # process name of the target window
+    [string]$action,        # click | hold | hover | move
+    [double]$fx,            # fractional X within the window client area (0..1)
+    [double]$fy,            # fractional Y
+    [int]$holdMs = 80       # press duration for 'hold'
+)
+# Window-CLIENT-relative synthetic input against a native app window, addressed
+# by process name — so probes don't depend on where the window landed or on it
+# being the foreground window (it's raised to foreground first). Coordinates are
+# FRACTIONS of the client rect, so they're resolution/DPI independent.
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public class In {
+    [DllImport("user32.dll")] public static extern bool GetClientRect(IntPtr h, out RECT r);
+    [DllImport("user32.dll")] public static extern bool ClientToScreen(IntPtr h, ref POINT p);
+    [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+    [DllImport("user32.dll")] public static extern bool SetCursorPos(int x, int y);
+    [DllImport("user32.dll")] public static extern void mouse_event(uint f, uint x, uint y, uint d, UIntPtr e);
+    public struct RECT { public int L, T, R, B; }
+    public struct POINT { public int X, Y; }
+    public const uint DOWN = 2, UP = 4;
+}
+"@
+$h = (Get-Process $proc -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowHandle -ne 0 } | Select-Object -First 1).MainWindowHandle
+if (-not $h -or $h -eq [IntPtr]::Zero) { Write-Output "NO WINDOW"; exit 1 }
+$r = New-Object In+RECT
+[In]::GetClientRect($h, [ref]$r) | Out-Null
+$p = New-Object In+POINT
+$p.X = [int](($r.R - $r.L) * $fx); $p.Y = [int](($r.B - $r.T) * $fy)
+[In]::ClientToScreen($h, [ref]$p) | Out-Null
+[In]::SetForegroundWindow($h) | Out-Null
+Start-Sleep -Milliseconds 120
+[In]::SetCursorPos($p.X, $p.Y) | Out-Null
+switch ($action) {
+    "move"  { }
+    "hover" { Start-Sleep -Milliseconds 250 }
+    "click" { Start-Sleep -Milliseconds 120; [In]::mouse_event([In]::DOWN,0,0,0,[UIntPtr]::Zero); Start-Sleep -Milliseconds 60; [In]::mouse_event([In]::UP,0,0,0,[UIntPtr]::Zero) }
+    "hold"  { Start-Sleep -Milliseconds 120; [In]::mouse_event([In]::DOWN,0,0,0,[UIntPtr]::Zero); Start-Sleep -Milliseconds $holdMs; [In]::mouse_event([In]::UP,0,0,0,[UIntPtr]::Zero) }
+}
+Write-Output "$action at $($p.X),$($p.Y)"
@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Drive a native compose-desktop-native app window for manual/automated visual
+checks: launch it, send window-relative input (click / hover / hold / move),
+and capture the client area via PrintWindow (works even when occluded).
+
+Built from the ad-hoc rigs used to reproduce the square-on-click and TLS-chain
+bugs — window-CLIENT-relative and process-addressed, so it doesn't care where
+the window lands or whether it's focused.
+
+Examples:
+    # boot the demo's Images screen, screenshot after 4s
+    python scripts/probe/probe.py demo --screen=Images --shot=images.png
+
+    # boot bubble-wrap (example repo), press-and-hold a bubble mid-sheet, capture
+    python scripts/probe/probe.py shared --exe <path-to>/shared.exe \\
+        --hold 0.55,0.55 --shot press.png
+
+    # hover then capture
+    python scripts/probe/probe.py demo --screen=Shapes --hover 0.3,0.4 --shot hov.png
+
+`proc` is the window's process name (demo / apidemo / shared). Native apps
+built here use the mingwX64 debug exe by default; override with --exe. Actions
+run in order; --shot captures after them. Windows-only. Needs Pillow only if
+you pass --crop.
+"""
+import argparse, subprocess, sys, time, os, signal
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+HERE = Path(__file__).resolve().parent
+DEFAULT_EXE = {
+    "demo": REPO / "demo/build/bin/mingwX64/debugExecutable/demo.exe",
+    "apidemo": REPO / "apidemo/build/bin/mingwX64/debugExecutable/apidemo.exe",
+}
+
+
+def ps(script: str, *args: str):
+    return subprocess.run(
+        ["powershell", "-ExecutionPolicy", "Bypass", "-File", str(HERE / script), *args],
+        capture_output=True, text=True,
+    )
+
+
+def frac(s: str):
+    x, y = s.split(",")
+    return float(x), float(y)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("proc", help="window process name (demo / apidemo / shared)")
+    ap.add_argument("--exe", help="path to the executable (default: mingwX64 debug for demo/apidemo)")
+    ap.add_argument("--screen", help="pass --screen=<Name> to the app (demo)")
+    ap.add_argument("--args", default="", help="extra args passed verbatim to the exe")
+    ap.add_argument("--boot", type=float, default=4.0, help="seconds to wait after launch")
+    ap.add_argument("--click", help="fractional X,Y to click (e.g. 0.5,0.5)")
+    ap.add_argument("--hold", help="fractional X,Y to press-and-hold")
+    ap.add_argument("--hover", help="fractional X,Y to hover")
+    ap.add_argument("--hold-ms", type=int, default=900, help="hold duration")
+    ap.add_argument("--settle", type=float, default=0.3, help="seconds between action and capture")
+    ap.add_argument("--shot", help="capture the window to this PNG after the actions")
+    args = ap.parse_args()
+
+    exe = Path(args.exe) if args.exe else DEFAULT_EXE.get(args.proc)
+    if not exe or not exe.exists():
+        print(f"exe not found: {exe} (build it, or pass --exe)", file=sys.stderr)
+        return 1
+
+    cmd = [str(exe)]
+    if args.screen:
+        cmd.append(f"--screen={args.screen}")
+    if args.args:
+        cmd += args.args.split()
+
+    proc = subprocess.Popen(cmd)
+    try:
+        time.sleep(args.boot)
+        if args.hover:
+            fx, fy = frac(args.hover)
+            print(ps("_input.ps1", "-proc", args.proc, "-action", "hover", "-fx", str(fx), "-fy", str(fy)).stdout.strip())
+        if args.click:
+            fx, fy = frac(args.click)
+            print(ps("_input.ps1", "-proc", args.proc, "-action", "click", "-fx", str(fx), "-fy", str(fy)).stdout.strip())
+        if args.hold:
+            fx, fy = frac(args.hold)
+            # hold runs async so we can capture DURING the press
+            p = subprocess.Popen(["powershell", "-ExecutionPolicy", "Bypass", "-File", str(HERE / "_input.ps1"),
+                                   "-proc", args.proc, "-action", "hold", "-fx", str(fx), "-fy", str(fy), "-holdMs", str(args.hold_ms)])
+        time.sleep(args.settle)
+        if args.shot:
+            out = str(Path(args.shot).resolve())
+            r = ps("_capture.ps1", "-proc", args.proc, "-out", out)
+            print(f"{r.stdout.strip()} -> {out}")
+    finally:
+        subprocess.run(["taskkill", "/F", "/IM", exe.name], capture_output=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
Author	SHA1	Message	Date
Bitsy	aad70f342b	fix(sdl): stop re-rasterizing text at device size — popup/dialog text no longer steps size/weight Regression from 120abbad's glyph device-scaling: drawNativeText scaled the font size by the layer affine (inFontSize * scaleY, int-quantized) and re-rasterized. Under an animated layer scale — every Material DropdownMenu/AlertDialog enter transition scale-animates (Menu.kt scaleX/scaleY) — text re-rasterized at each integer size every frame, so it visibly stepped through sizes and (via SDL3_ttf re-hinting) weights as the popup grew in. User-reported, seen across dropdowns and dialogs. Revert to rasterising at LOGICAL font size + 1:1 blit at the affine-mapped position (the pre-120abbad behaviour): the layer scale reaches text POSITION but not glyph size, so animated-scale popups are stable. Keeps 120abbad's separate clip-mask AA/overlap fixes. Trade-off: statically graphicsLayer-scaled text renders at logical size (a rare, minor parity gap) — smoothly scaling glyphs needs blit-scaling a logical rasterisation (noted for a future text-renderer pass). Verified: demo dropdown opens with clean uniform text; text no longer scales with the layer, so mid-animation == settled by construction.	2026-07-14 20:19:40 +02:00
Bitsy	cf597c12e0	cleanup: delete dead modifier scaffolding + fix demo's fake cacheKey claims ModifierElements.kt (ClipModifier/ClipNode + GraphicsLayerModifier/ GraphicsLayerNode with the never-implemented cacheKey) was entirely unreferenced — apps use the upstream clip/graphicsLayer; nothing read these. Deleted the file (compiles clean across :ui and :demo). The demo GraphicsLayer screen advertised caching that never existed ('Cached subtree (cacheKey)', 'Combined (cache + rotation)', a '(cached)' label) over plain graphicsLayer() calls. Removed those two fabricated sections and the cacheKey wording; the honest Rotation (live) / Scale / Alpha sections already show what graphicsLayer does.	2026-07-14 20:02:30 +02:00
Bitsy	cbddf8ca0b	docs: RESOLVED — demo-70/apidemo-144 was mixed-refresh monitors, not a renderer bug User has a 75Hz main + 144Hz second screen; each app's fps is just the refresh of the monitor its window opened on (SDL vsync follows the display). Instrumentation already showed both apps at ~3.7ms draw — well under both the 13.3ms (75Hz) and 6.7ms (144Hz) budgets, so no perf problem exists. Records that retained-layers/dirty-region/cacheKey are speculative with no demonstrated need; only the dead-scaffolding cleanup is worth doing regardless.	2026-07-14 19:54:04 +02:00
Bitsy	ad738a643e	docs(CLAUDE): profiler now file-output + draw counters + CDN_FORCERENDER; vsync/display caveat Documents the DrawStats per-frame counters, file output, and CDN_FORCERENDER added this session, plus the load-bearing caveat: present is vsync-bound so all timings are capped by the dev display's refresh — profile on the target rate before diagnosing a frame-rate gap.	2026-07-14 19:53:12 +02:00
Bitsy	8f5c59bd64	feat(window): per-frame DrawStats in profiler + CDN_FORCERENDER; correct the 70fps theory Extends CDN_PROFILE with per-frame draw counters (DrawStats: geometry submits, vertices, mask realizations, text/image blits) and a CDN_FORCERENDER=1 flag to render every frame for steady-state timing on idle screens. Used them to test the demo-70fps theory and DISPROVE it: forced-render, both apps pin at 75 fps (this dev display's refresh), present ~9ms; the demo's draw (~3.7ms, geo=40, masks=0) is actually LIGHTER than apidemo's (~2.9ms, geo=146, masks=74). So the demo is NOT draw-bound — the 70-vs-144 split is specific to the user's 144Hz monitor and can't be reproduced on a 75Hz box. Recorded the correct next step (profile on the 144Hz machine) in NEXT-SESSION.md; noted the vsync/display confound in CLAUDE.md's profiler docs. Thread A (spurious continuous render) resolved as a non-issue — the demo idles when static.	2026-07-14 19:52:24 +02:00
Bitsy	914bab840d	docs: handoff notes for the renderer-caching session Captures the demo-70fps investigation for the next session: (A) the likely-cheaper continuous-render / hover-self-loop thread to chase first, and (B) the cacheKey/retained-layer work — dead scaffolding today, blocked on a content-draw-redirect primitive (the 'renderer rewrite') that also underpins dirty regions. Lists the tooling + existing infrastructure to build on.	2026-07-14 19:34:39 +02:00
Bitsy	8f96ba9478	docs(roadmap): record demo 70fps cause (draw-bound sidebar re-tessellation) Investigated the demo-70fps / apidemo-144fps question with CDN_PROFILE: both apps use vsync(1), so it's NOT a vsync-mode difference. The full demo is DRAW-bound (draw ~34ms cold / ~14ms steady, present ~1.3ms) — it re-tessellates the whole always-present sidebar (30+ rows of text + icons) every rendered frame, capping ~70 fps. apidemo's lighter chrome fits the 6.9ms/144Hz budget and hits the vsync ceiling. '70≈144/2' is coincidence. Concrete motivation for retained layers / dirty regions.	2026-07-14 18:43:23 +02:00
Bitsy	5a9e7b0f7f	docs(roadmap): mark layer rotation verified-working; warn item-4 list is stale Layer rotation renders correctly (demo GraphicsLayer Rotation-live + Combined rows) — like gradients, the claimed gap was already fixed. Added a note to verify item-4 claims against the parity heatmaps before acting, since the list predates several fixes.	2026-07-14 18:28:55 +02:00
Bitsy	5dfd9200f8	fix(sdl): grid-mesh gradient fills so radial/sweep aren't flat The brush samplers (linear/radial/sweep with stops) were fully implemented, but fills sampled the brush only at the shape's CORNERS and let SDL interpolate. A square's four corners are equidistant from its centre → identical radial/sweep t → the fill rendered as ONE flat colour (the demo Brushes radial was solid green: center==corner pixel). Linear survived because corners differ along the axis. Gradient fills (brush !is SolidColor) now tessellate rect and round-rect bodies into an ~8px-cell grid (emitRectMesh, adaptive 1..24 cells/axis), so the sampler is evaluated across the interior and SDL interpolates per-cell. Solid fills keep the single-quad fast path. Round-rect corner arcs already fan from their centre. Verified: demo Brushes radial now shows centre→edge falloff matching the JVM render (was flat); parity Brushes 22.75%→21.72% (swatches are a small pixel fraction; the rest is font drift).	2026-07-14 18:27:07 +02:00
Bitsy	8c7168a1a9	feat(window): profiler render sub-phases + file output; reprioritize roadmap from data FrameProfiler is now a named-phase singleton writing to a FILE (CDN_PROFILE=1 -> cdn_profile.log, or =<path>) not stdout — so GUI-subsystem apps (the demo links --subsystem,windows) profile too. renderFrame splits into layout / draw / present sub-phases. Measured: light screen = 75 Hz, present ~10ms (vsync wait), draw ~1.4ms (GPU-idle); heavy 84-bubble sheet ~32ms = DRAW, not masks. ROADMAP item 2 re-ordered: dirty-region rendering + retained layers promoted (the real lever); clip-target right-sizing demoted to memory-only/low.	2026-07-14 18:16:27 +02:00
Bitsy	377f3aa775	docs: consolidated tooling index in CLAUDE.md + simple redirecting table in README CLAUDE.md gains a '## Tooling — what to reach for' section: a when-to-use table covering build-sdl, compose-fork sync, compose-coverage, material-symbols, parity, probe, the CDN_PROFILE profiler, the bridge plugin and the demo CLI probes — each pointing at its own README. The parity/profiler/probe entries are expanded inline (parity keeps the 'what the %differ means' detail). README gets a simpler table redirecting to each tool's README + the bridge/CLAUDE detail.	2026-07-14 17:18:11 +02:00
Bitsy	662975c802	feat(probe): reusable native-window input+capture driver (ROADMAP item 5) scripts/probe/ — launch a native app, send WINDOW-CLIENT-relative input (click/hover/hold, fractional coords addressed by process name so it ignores window position/focus), capture via PrintWindow (works occluded). The packaged form of the ad-hoc rigs that reproduced the square-on-click and TLS-chain bugs. Verified: demo --screen=Shapes hover+capture yields real 1000x700 content.	2026-07-14 17:15:19 +02:00
Bitsy	3b420a7bad	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.	2026-07-14 17:09:52 +02:00
Bitsy	2dad6c9bcc	fix(parity): use Path.replace so re-runs overwrite prior native PNGs on Windows Path.rename raised FileExistsError mid-sweep when a screen's <Name>.native.png already existed from an earlier run (Windows rename won't overwrite). replace() is an atomic overwrite everywhere. Full 56-screen sweep now completes: smooth 2%%(Counter)..32%%(Tabs) distribution, no catastrophic outlier — confirms this session's renderer changes (lazy clips, batch flush, TLS fix) left no screen blank or structurally broken. Text density + known SDL parity gaps (solid gradients, effect differences) explain the top of the ranking.	2026-07-14 17:08:44 +02:00
Bitsy	723f80c8af	feat(parity): native-vs-jvm screenshot diff harness (ROADMAP item 5) A regression net built on the demo's dual-stack design: the same commonMain screens render on native (SDL/Skia) and on upstream Compose Desktop (jvm), and scripts/parity/parity.py pixel-diffs them per screen. - MainJvm gains a headless --screenshot-all=<dir> mode: renders every registered screen via ImageComposeScene (density 1, same verticalScroll+padding wrapper as MainNative's --screen path) to PNGs in ONE jvm process. - parity.py drives the native exe per screen (--screen/--screenshot), diffs against the jvm PNGs with a per-channel tolerance, and writes <pct>_<Name>_diff.png (amplified heatmap) + _compare.png (side by side) to build/parity/ (gitignored), ranked worst-first by the pct filename prefix + report.txt. The ranking is the signal, not the absolute %: fonts differ between stacks (text ghosts in the heatmap), so a screen jumping well above its neighbours/history is the regression. Verified on Buttons/Shapes/Colors (~16/14/4% — all font drift, structure aligned).	2026-07-14 17:06:08 +02:00
Bitsy	450247175f	feat(sdl): deterministic native-resource lifecycle — release queue + bitmap cleaner ROADMAP.md item 1. SdlImageBitmap textures were NEVER freed (manual SDL memory the GC nudge can't touch) — the lazy-texture rework made it worse since the render-target path also leaked. Now: - NativeReleaseQueue (:ui): thread-safe queue of release actions drained on the MAIN thread each frame by the window loop. SDL calls aren't thread-safe and both disposal triggers are off-main (a Cleaner runs on a GC worker; close() can be reached from other dispatchers), so both just ENQUEUE. - SdlImageBitmap: holds its texture/surface in a by-ref holder with a Cleaner that enqueues destruction (backstop) + an explicit close() (prompt path). Idempotent — first to run nulls the handles. - ComposeWindow drains the queue between frames and once at teardown. This makes the periodic GC.collect() nudge a safeguard rather than the disposal mechanism (issue #2). Verified end-to-end in the example: a direct enqueue and a real Cleaner->enqueue->drain cycle both fire. close()-on-eviction wiring is a documented follow-up (caches hold the ImageBitmap interface, not the concrete type).	2026-07-14 16:55:33 +02:00
Bitsy	5d6f772a1c	fix(sdl): lazily-realized clips use push-time region, not the narrowed current clip The TLS-chain regression (only the first card + nothing below it, until a scroll shifted things): realizePendingClips re-intersected each pending clip's region with the CURRENT fClip. A lazy clip can realize arbitrarily deep inside descendants whose own clips have since narrowed fClip — so an OUTER clip (the dialog's rounded Surface) realized with the innermost descendant's tiny rect as its region. Its offscreen then composited back only that sliver; every sibling card + the button drawn into the same offscreen fell outside the blit and vanished. Each pending clip now realizes with its OWN push-time region (enclosing-clip-at-push ∩ bbox, already captured in PendingRoundClip), and the real (already-narrowed) drawing clip is saved across the realize loop and restored after, so draws into the innermost target stay correctly clipped. Reproduced with an outer rounded Surface + height-bounded verticalScroll of rounded+bordered cards + a button (the TLS dialog's exact shape): first-card-only before, full list + button after. Demo scroll/card screens and bubble-wrap unaffected.	2026-07-14 16:37:45 +02:00
Bitsy	575c19f921	feat(window): CDN_PROFILE=1 per-phase frame profiler Prints avg/max ms per main-loop phase (events / app pump / window pump / render) every ~2s of rendered frames, via SDL performance counters. Bubble-wrap sheet under hover: render=32/41ms dominates a 39ms frame — confirms the renderer, not composition, is the 75Hz bottleneck (ROADMAP.md item 2).	2026-07-14 16:19:56 +02:00
Bitsy	328663b9e7	docs: renderer roadmap — lifecycle, performance, parity, tooling	2026-07-14 16:14:54 +02:00
Bitsy	c9ddd3488d	fix(sdl): auto-flush the vertex batch only on triangle boundaries SDL_RenderGeometry renders floor(count/3) triangles and silently drops the tail. writeVertex auto-flushed the batch whenever it was full — at ANY vertex boundary — so a triangle straddling the flush lost its tail vertices AND left orphan vertices at the head of the next batch, misaligning every triangle after it: ~350° pac-man circles and glitch shapes that shifted with every redraw once a frame's geometry outgrew one batch. Never seen before because clip layers flushed constantly; bubble-wrap's new unclipped drawBehind sheet (84 bubbles, one giant batch, ~4 overflows per frame) exposed it — most of the sheet simply vanished. Flush now only fires at multiples of 3, and kBatchCapacity drops 8192 → 8190 (a multiple of 3, so the cap lands on a triangle boundary and the buffer can never overrun).	2026-07-14 16:08:07 +02:00
Bitsy	9958386792	fix(bridge): data.kres zips must not race executable declaration The resources packaging pre-scanned link-task names in afterEvaluate — but executables can be declared AFTER that runs, notably by the bridge's own compose.desktop.native { entryPoint } DSL (also afterEvaluate, registered later). The scan found no link tasks and silently packaged nothing: 'data.kres not found' at startup. The old single-module example masked this with stale build output; a fresh multi-module layout exposed it. Zips are now pre-registered lazily for every desktop target/variant and wired via tasks.matching{}.configureEach — order-independent, and an unrealised task is free when the target has no executable. (Registering the zip reactively from inside the link task's configuration callback is forbidden by Gradle — 'cannot be executed in the current context'.) Content wiring moved into the zip's own configuration action, which runs at realisation when the Compose plugin's prepare tasks and the final compose.resources config exist. Verified on the restructured multi-module bubble-wrap (shared KMP library with the new com.android.kotlin.multiplatform.library DSL + androidApp): packageDebugComposeResourcesMingwX64 runs, data.kres lands next to shared.exe with the drawable + converted .cvr strings, app boots with resources loading.	2026-07-14 14:39:29 +02:00