Desktop And Build Footguns

Desktop JVM and build footguns

24 traps mined from a production Kotlin and Compose Multiplatform app, one short file each under references/. Every file gives the working pattern, the Traps (the specific ways it fails in practice, and why), and a Verifying it section with commands to run against the user's own tree.

How to use this index. Match the code about to be written, or the symptom being chased, against the entries below: each names its topic and the symptom that should send you to it. Read every file that plausibly applies with the Read tool before proposing code or a fix; each is under 150 lines. Where a Verifying command names the source project's paths, substitute the equivalent paths in the user's tree.

Cross-references. A backticked trap name inside a file that is not listed here lives in a sibling area skill: glob ../*/references/<name>.md to open it.

Native code on the desktop JVM

• jna-native-binding-traps — Hand-writing a JVM binding for a C library with JNA (Java Native Access) — the open-flags option that means something else on Windows, structs read by raw offset, callbacks the binding holds weakly, search paths registered too late, and proving which file was actually opened. Reach for it when a binding works on every developer machine and fails on a clean one, or when the very first symbol lookup fails with "the specified module could not be found" while the library is sitting right there.
• native-artifact-for-embedding — Producing a native shared library a JVM app can actually load and ship — why a prebuilt portable bundle usually is not a loadable library at all, building on the oldest base system you support, run-path choice, which libraries to deliberately leave out of the bundle, and gating the build on a load-and-initialize smoke test. Reach for it when the bundled native works on every developer machine and fails on a clean one, or when you discover the app has been quietly using a system-wide copy instead of yours.
• bundled-native-soname-conflict — A native library you bundle with a desktop app drags its own copy of a general-purpose base library along, that copy claims the shared-object name for the whole process the moment your native loads, and an unrelated platform API then fails with a missing-symbol message naming a third library. Use when a feature that opens links or system dialogs works on your machine but silently does nothing on users' machines, when a platform API reports itself unsupported at runtime, when deciding what a native bundle may contain, or when a merged fix for exactly this bug does not seem to have changed anything for users.
• macos-codesign-sidecar-strip — Strip the ._* companion files that macOS archiving writes beside files carrying extended attributes, after unpacking anything into a macOS app bundle and before the bundle is signed, because the signer seals those companions as ordinary bundle members and the OS deletes them the first time the file manager touches the app. Use when a signed macOS app launches fine on the build machine but users are told it is damaged and can't be opened, or when signature verification reports a sealed resource missing.
• jvm-desktop-memory-footprint — Judge and reduce a desktop JVM application's memory honestly — read the heap-to-footprint ratio rather than the resident figure, run the one experiment that separates a leak from an allocator holding idle pages, and understand why per-thread allocator arenas make the footprint depend on the user's core count. Use when a desktop app settles near a gigabyte or keeps climbing over a long session, when users on big machines report far worse memory than you can reproduce, or before tuning any allocator or garbage-collector flag.
• embed-media-engine-desktop — Embedding a native C media engine in a JVM desktop app — one handle per media item, a dedicated event-pump thread, pinning the output driver and creating the render context in the right order, confining every property write to the thread that also releases handles, feature-detecting optional engine options, and formatting numbers the way the engine parses them. Reach for it when the app stops while setting a property, when the engine opens a window of its own, or when a value the app clearly sets is silently ignored.
• merge-split-av-streams-desktop — Playing a separate audio-only stream and video-only stream as ONE source on JVM desktop through the media engine's edit-list URL form — the desktop counterpart of a merging media source — including length-prefixed quoting of stream URLs and why a merged two-URL item must not be prepared in the middle of a crossfade. Reach for it when desktop video plays back completely silent with nothing in the log, when a stream URL is truncated at the first semicolon, or when fading into a video track cuts the outgoing song short.
• compose-desktop-video-no-swingpanel — Rendering video frames from a native media engine in Compose Desktop without embedding a heavyweight AWT panel — publish finished frames as immutable snapshots on a StateFlow and draw them with a plain Image, convert off the UI thread, match the engine's pixel byte order, and let the engine decide the fit. Reach for it when embedded video sits on top of everything regardless of z-order, lags a frame behind while scrolling, goes black on one screen the moment a second screen shows the player, comes out with red and blue swapped, or shows black bars that no content-scale can remove.
• desktop-system-media-integration — Wire a desktop app into each OS's system now-playing and transport surface behind one facade, so a failed native initialisation disables the integration and never takes playback down. Covers initialising on the platform's main thread inside a packaged app, reaching an OS media framework through the JVM's native-access layer, holding strong references to callbacks handed to the OS, and confining the integration to its own thread. Use when media keys or the system now-playing panel work under a plain Gradle run but not in the packaged app, when only the app name renders instead of the track title, or when transport callbacks stop arriving after a while.
• upstream-lib-bug-workaround-template — The shape a workaround should take when the bug is in a library you cannot patch — trace the mechanism as far as you actually got, name the tradeoffs you accepted, leave an escape hatch so a failure degrades instead of going silent, write the explicit condition for removing it, and record why your usage pattern exposes a bug the library's own users never hit. Use when you are about to pin a setting, avoid a code path or add a defensive branch because of someone else's bug, or when reviewing a workaround whose comment does not say when it may be deleted.
• macos-lsenvironment-path-pin — Declaring a Launch Services environment dictionary (LSEnvironment) in a packaged macOS app's property list pins the process PATH to the four bare system directories, so every external process the app spawns loses everything installed elsewhere. Use before adding any environment variable to a macOS app bundle, when a helper the app shells out to reports "command not found" only for installed users, or when a feature that works from a terminal launch silently does nothing from the Dock.