all publishers

maxrave-dev

@maxrave-dev source repo

241 published skills · page 1 of 3

  1. ▌
    Engineering Method Footguns · maxrave-dev bundle
    Debugging-method traps: run the discriminating experiment first, read build logs bottom-up, treat an empty actual as unwritten, audit shared handles before removing a feature, read commit history critically. Use when a fix is not converging.
    2.3k repo stars
  2. ▌
    State And Background Footguns · maxrave-dev bundle
    Reactive state and background-work traps: StateFlow conflation, flatMapLatest, job lifecycles, ViewModel bases, WorkManager, backups, crash reporting, logging, Glance widgets. Use when state lags or flips, or work runs twice or never.
    2.3k repo stars
  3. ▌
    Media Playback Footguns · maxrave-dev bundle
    Media player traps on Media3/ExoPlayer and desktop engines: crossfade, audio focus, fades, loudness, DSP, queues and shuffle, position restore, service lifecycle, group listening. Use when playback state, queue or audio levels go wrong.
    2.3k repo stars
  4. ▌
    Compose Screens Footguns · maxrave-dev bundle
    Compose screen and interaction traps: navigation, adaptive layout, window insets, pagers, toolbars, sheets, list drag and selection, sliders, text fields, settings UI, one-shot effects. Use when layout, gestures or navigation misbehave.
    2.3k repo stars
  5. ▌
    Compose Visuals Footguns · maxrave-dev bundle
    Compose look-and-feel traps: theme and colour tokens, artwork palettes, gradients and scrims, shimmer, glass and particle effects, animation, image loading, charts and stats displays (percent changes, shares, buckets). Use when a visual bands, pops, freezes or misleads.
    2.3k repo stars
  6. ▌
    Kmp Architecture Footguns · maxrave-dev bundle
    Kotlin Multiplatform structure and language traps: module splits, expect/actual, Koin and ViewModel scoping, layers, version catalogs, erased overloads, Char and string-resource formatting limits. Use when shaping modules or DI, when a format specifier renders verbatim, or code misbehaves on one platform.
    2.3k repo stars
  7. ▌
    Desktop And Build Footguns · maxrave-dev bundle
    Desktop JVM and build traps: JNA natives, bundling, memory, packaging, code signing, R8, deep links, Gradle and CI releases. Use when a desktop build fails packaged, signed, on another OS or arch, or in CI.
    2.3k repo stars
  8. ▌
    Footgun Scan · maxrave-dev bundle
    Scan a Kotlin or Compose Multiplatform diff for known footgun shapes and open the matching trap to confirm each hit. Use before committing, when reviewing a Kotlin change, or to audit a codebase.
    2.3k repo stars
  9. ▌
    Webview Footguns · maxrave-dev bundle
    WebView traps across device classes: startup that freezes low-RAM phones, a killed renderer that takes the app with it, devices with no usable provider, AndroidView lifecycle and cookies. Use when a web screen freezes, vanishes or crashes only on some devices.
    2.3k repo stars
  10. ▌
    Data Layer Footguns · maxrave-dev bundle
    Room/SQLite, DataStore and repository traps: migrations, NOT IN with NULLs, LIKE escaping, delete order, local-time bucketing, imports, caching, paging. Use before writing a query or migration, or when data comes back wrong.
    2.3k repo stars
  11. ▌
    Remote API Footguns · maxrave-dev bundle
    Remote API traps in Kotlin Multiplatform: Ktor clients, defensive parsing, Resource envelopes, OK responses that dropped your data, auth callbacks, retry backoff, downloads, websockets, clock sync. Use when calls succeed but data never lands.
    2.3k repo stars
  12. ▌
    Kotlin Multiplatform · maxrave-dev bundle
    Platform abstraction decision-making for Amethyst KMP project. Guides when to abstract vs keep platform-specific, source set placement (commonMain, jvmAndroid, platform-specific), expect/actual patterns. Covers primary targets (Android, JVM/Desktop, iOS) with web/wasm future considerations. Integrates with gradle-expert for dependency issues. Triggers on: abstraction decisions ("should I share this?"), source set placement questions, expect/actual creation, build.gradle.kts work, incorrect placement detection, KMP dependency suggestions.
    2.3k repo stars
  13. ▌
    UI UX Pro Max · maxrave-dev bundle
    UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient.
    2.3k repo stars
  14. ▌
    Simpmusic Icons · maxrave-dev
    Add or change an icon in SimpMusic. Every icon is a generated Material Symbols ImageVector under ui/icon, addressed as SimpIcons.<Name> — there is no material-icons dependency and no XML icon drawable. Use when adding a new icon, replacing one, or hitting ImageVector/Painter type errors.
    2.3k repo stars
  15. ▌
    Android Viewmodel · maxrave-dev
    Best practices for implementing Android ViewModels, specifically focused on StateFlow for UI state and SharedFlow for one-off events.
    2.3k repo stars
  16. ▌
    Compose Navigation · maxrave-dev
    Implement navigation in Jetpack Compose using Navigation Compose. Use when asked to set up navigation, pass arguments between screens, handle deep links, or structure multi-screen apps.
    2.3k repo stars
  17. ▌
    Android Emulator Skill · maxrave-dev bundle
    Production-ready scripts for Android app testing, building, and automation. Provides semantic UI navigation, build automation, log monitoring, and emulator lifecycle management. Optimized for AI agents with minimal token output.
    2.3k repo stars
  18. ▌
    Compose Capture To Share Image · maxrave-dev
    Render a composable off-screen into an ImageBitmap so a button can save or share it as a picture — a capture primitive ported into common code rather than pulled in as a platform-only dependency, a max-width ceiling standing in for a fixed output size, artwork that has to already be resolved before the button is even reachable, and an Android MediaStore save gated behind a permission that the same feature's Desktop save never needs. Use when a "share as image" feature exports a blank or half-drawn picture, when the exported picture comes out a different size on every device, or when saving works on some Android versions and fails silently on others.
    2.3k repo stars
  19. ▌
    Crossfade Exclusion Heuristics · maxrave-dev
    Decide when a crossfade must NOT run — the item plays as video, the item is too short for the fade, or two consecutive items belong to the same album — and encode each rule so it survives shuffle, an auto-length fade and a queue that keeps growing. Use when a fade cuts a song short, a video jumps to its first frame under the previous track, a 25-second interlude spends half its length fading, or an album sequenced to run continuously is interrupted between every track.
    2.3k repo stars
  20. ▌
    Derive Seek From Progress Flow · maxrave-dev
    Detect a scrub as a playhead that moved further than wall-clock time can account for, from the progress stream every platform already emits, because the platform's own discontinuity callback exists on one backend only and neither the item stream nor the transport stream fires when a scrubber is dragged. Use when a seek by one member of a shared session is never sent, or when a cross-platform layer needs an event only one platform provides.
    2.3k repo stars
  21. ▌
    First Ever Not First In Window · maxrave-dev
    Counting entities encountered for the first time means taking MIN over the entity's whole history and asking whether that minimum lands inside the window — the natural version, which filters to the window and then groups, calls every entity new. Covers why the wrong query passes its first test, why the window belongs in HAVING rather than WHERE, what an unbounded scan needs from the index, and how a retention prune quietly redefines "ever". Use when a "new this period" figure tracks the distinct count exactly, when discovery rate is implausibly close to 1, or before writing any first-seen query.
    2.3k repo stars
  22. ▌
    Follower Transport Stays Local · maxrave-dev
    A follower in a shared session owns its own stop button — pausing is local and silent, and pressing play asks where the session is now rather than restoring where this device stopped. Use when a follower cannot pause because the next state update immediately resumes it, when a follower's pause stops everyone, or when resuming lands minutes behind the rest of the group.
    2.3k repo stars
  23. ▌
    Intent Flag Not Observed State · maxrave-dev
    A component that is committed to running but not yet running reports "not running", so anything that means intent must read the intent flag, not the observed one — and at a transition the intent flag must be waited for with a timeout rather than sampled inline. Use when one client's buffering hiccup stops a whole synchronised group, when appending to a queue in the background silences the track that was about to start, when a resume command is issued on every tick, or when a state read is wrong on exactly the transitions it exists for.
    2.3k repo stars
  24. ▌
    Kmp Module Split For Packaging · maxrave-dev
    Split one Kotlin Multiplatform UI module into a shared app LIBRARY plus thin per-platform launcher modules — an Android application module that only packages, and a JVM/desktop module that owns main() and hands off to a public function in the library. Reach for it when the Android Gradle Plugin refuses to let your app module also be a multiplatform target, when packaging config and shared UI are tangled in one build script, or when a resource accessor class stopped generating after a module became a library.
    2.3k repo stars
  25. ▌
    Merge Split Av Streams Desktop · maxrave-dev
    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.
    2.3k repo stars
  26. ▌
    Named Job Lifecycle Discipline · maxrave-dev
    One `var xJob: Job?` field per concern, cancel-before-relaunch as an invariant at every launch site, and teardown writes wrapped so a cancellation cannot stop them halfway. Use when periodic updates arrive several times per tick, when stale results from a previous item overwrite the current one, or when a long-lived object keeps working after it was released.
    2.3k repo stars
  27. ▌
    Noop Actual Not Platform Limit · maxrave-dev
    An empty or pass-through platform implementation in a multiplatform project means nobody wrote it, not that the platform cannot do it — check the dependency's resolved variants and the source set that declares it before telling anyone a feature is impossible there. Use when a feature "doesn't work on desktop/iOS", when a platform file returns its input unchanged or has an empty body, or before writing off a feature as a platform limit.
    2.3k repo stars
  28. ▌
    OAUTH Callback Not Through Nav · maxrave-dev
    Deliver a returning auth callback's token straight to session state and let the login screen close itself by observing the stored session — routing the token through navigation pushes a second login screen and the post-login close peels the wrong one. Use when a browser-based login succeeds but the user is left staring at the login screen.
    2.3k repo stars
  29. ▌
    Palette State Parks On Loading · maxrave-dev
    A palette generator that flips its state to Loading before its own suspension point reports no colour for the entire duration of every generation, and a generation cancelled part-way leaves it Loading with nothing to restart it — so any surface reading the palette directly paints its null fallback. Covers why the effect must be keyed on the bitmap alone (or on nothing at all), why a "already done" flag assigned after a suspension is not a record of done, and why the last resolved colour has to be held separately. Use when a screen tinted from artwork is sometimes right and sometimes black, when the same item tints correctly on one visit and not the next, or when a derived colour scheme silently sits on its fallback.
    2.3k repo stars
  30. ▌
    Progress Indicator As Scrubber · maxrave-dev
    Build a seek control from a progress indicator plus a transparent pointer layer instead of from a slider — a hit box taller than the visual, drags consumed so an ancestor pager cannot steal a scrub, the drag's own fraction shown while interacting, a thumb drawn by you, and the separate decision of drawing an element closer without moving its layout slot. Use when the visual you need has no slider equivalent, when a scrub gets hijacked by a swipe or a sheet, when the bar jumps back mid-drag, or when a thin control is impossible to hit.
    2.3k repo stars
  31. ▌
    Readonly Stateflow Cold To Hot · maxrave-dev
    Expose state through `asStateFlow()` rather than an upcast of the mutable holder, and turn a cold source flow hot with `stateIn(scope, WhileSubscribed(timeout), initial)` so it survives collector churn without running forever. Use when a screen re-queries its source on every rotation or navigation, when work continues after the last collector leaves, or when something outside the owner is writing state it should only be reading.
    2.3k repo stars
  32. ▌
    Windows Msix Offline Installer · maxrave-dev
    Ship a self-signed MSIX (the modern Windows application package format) that end users can actually install without a hosted update site — bundle an install script plus the signing certificate beside the package, script the trust-then-sideload steps, and keep the signing key stable across releases; reach for it when double-clicking the packager's output fails, when its wrapper installer dies fetching a URL that returns 404, or when a new build refuses to install over the previous one.
    2.3k repo stars
  33. ▌
    Windows Vm Detection Post Wmic · maxrave-dev
    Detect that a desktop app is running inside a virtual machine on Windows after the classic command-line management query tool was removed in Windows 11 — query the management layer through PowerShell, probe both the manufacturer and the model field, and pick the fail direction deliberately; reach for it when a transparent or undecorated window renders nothing on a VM while the process keeps running, or when a detection probe that worked for years suddenly reports empty on every modern host.
    2.3k repo stars
  34. ▌
    Enum Normalize Over Legacy Data · maxrave-dev
    Reading a type marker the remote source declares for itself — normalizing before every comparison because locally stored rows from older app versions hold labels the app invented, treating null as "the source did not say" rather than as a default, exposing an is-known predicate so callers branch on knowledge, and correcting old rows by write-through instead of a migration. Use when a stored type column holds several spellings, when an item is treated as the wrong kind, or before adding a database migration to fix historical values.
    2.3k repo stars
  35. ▌
    Play Intent Decided Before Load · maxrave-dev
    Decide whether the freshly-loaded item should start, and where it should start, before you build it — then pass both into the load call, rather than loading with a hardcoded "start playing" and correcting it a moment later. Reach for it when a follower in a synchronised room bursts into sound in a session everyone else has paused, or when a newly loaded item audibly starts and then stops.
    2.3k repo stars
  36. ▌
    Writing Agent Skill House Style · maxrave-dev
    Write an agent skill that survives an adversarial review — a description carrying both the trigger and the error symptom the reader is staring at, a short orientation, a Traps section that dominates the file, and verification commands you have actually run. Use when authoring or reviewing a SKILL.md, when a skill reads like documentation instead of hard-won advice, or when review keeps finding claims the source repository does not support.
    2.3k repo stars
  37. ▌
    Desktop System Media Integration · maxrave-dev
    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.
    2.3k repo stars
  38. ▌
    Foss Vs Proprietary Module Pairs · maxrave-dev
    Ship one codebase in two forms — a full build carrying a proprietary or credentialed integration and an open build carrying a no-op stub — using twin modules with an identical public API selected by a Gradle property rather than product flavors, which do not exist for non-Android multiplatform targets. Reach for it when a tracking, casting, or paid-service dependency must be absent from an open-source build, when call sites are littered with build-flavor branches, or when the "clean" build still pulls the proprietary artifact through a transitive path.
    2.3k repo stars
  39. ▌
    Fullscreen Video Gesture Overlay · maxrave-dev
    The gesture and chrome layers of a fullscreen video screen — tap anywhere to toggle the controls, double-tap either half to seek, an auto-hide timer that every interaction postpones, and a picture-in-picture (PiP) guard that removes both layers. Use when single taps work on only half the screen, when the controls vanish while the user is dragging the seek bar, when the seek thumb snaps back under the finger, when a double-tap produces no ripple or a ripple that never fades, or when app chrome is still drawn over the video inside a small floating window.
    2.3k repo stars
  40. ▌
    Gradle Config Resolved Too Early · maxrave-dev
    Diagnosing Gradle failures of the form "cannot mutate a configuration after its child configuration was resolved" — why the message names the configuration you touched rather than the plugin that resolved it, how to bisect plugins against a minimal working template, and which fixes are documented dead ends. Reach for it when adding a perfectly ordinary dependency line makes the build refuse to configure, and rewriting that line every possible way changes nothing.
    2.3k repo stars
  41. ▌
    Hoist The Flag Not The Animation · maxrave-dev
    Share the boolean that drives a fade, never the tween that runs it — each look derives its own curve, so one can go asymmetric (fast in, slow out) without changing how the other feels; covers why a symmetric linear fade over a bright backdrop makes container-backed controls read as the wrong colour, and why the shared animated value must stay published anyway. Use when buttons look lighter or darker than their neighbours only while something is fading, when one visual style needs a different timing from another, or before pulling an `animateFloatAsState` up into a shared state holder.
    2.3k repo stars
  42. ▌
    Kmp Git Submodule Module Mapping · maxrave-dev
    Consume a git submodule as a set of Gradle modules in a multiplatform repo — mapping its nested directories onto flat project paths, making the recursive clone a hard prerequisite instead of tribal knowledge, and enabling submodules in every continuous-integration job that configures the build. Reach for it when a fresh clone fails with a project that "does not exist", when a build passes locally but fails on a runner, or when shared code changes vanish because the recorded submodule pointer was never moved.
    2.3k repo stars
  43. ▌
    Levenshtein Fuzzy Match Pure Kmp · maxrave-dev
    Match a string against a candidate list with a two-row edit-distance loop and no dependency, so the matcher lives in shared multiplatform code. Covers the two-row memory shape, normalizing before comparing, a similarity threshold that refuses rather than returning the least-bad candidate, picking a top-N without corrupting the indices, and the cases where fuzzy matching is the wrong tool. Use when a title-to-title lookup picks a confidently wrong candidate, when a "top 3" helper returns indices that point at the wrong rows or at -1, or when a matcher cannot move into shared code because the library it uses is platform-only.
    2.3k repo stars
  44. ▌
    Login State Fans Out To Settings · maxrave-dev
    Logging out must reset every setting that depended on being logged in, at the logout choke point itself — otherwise a gated switch stays on for a service you are no longer authenticated to and silently no-ops forever, or errors on every tick. Use when a feature toggle is stuck on, cannot be switched off, or keeps running against a credential that is gone.
    2.3k repo stars
  45. ▌
    Order Preserving Section Mapping · maxrave-dev
    Map a sectioned API response as a list of (title, items) in the order it arrived, never by reading result[0] and result[1] into named fields — a signed-in account is recorded here as getting an extra section pushed in front, and any such shift mislabels every section after it and drops the last one with no error. Assume the set and order may also vary by locale or region, and capture two responses to find out. Use when modelling a home feed or browse screen made of shelves, or when a screen shows the right content under the wrong headings for some users only.
    2.3k repo stars
  46. ▌
    Per Track Loudness Normalization · maxrave-dev
    Apply per-track loudness normalisation with the platform's loudness enhancer when each track gets its own player — re-creating the effect per track because it stays attached to one audio session, skipping it while a remote-playback session is active, and clamping the gain that comes from metadata. Use when normalisation works on the first track and silently stops afterwards, when enabling it throws while nothing is playing, or when every other track in a queue comes out louder.
    2.3k repo stars
  47. ▌
    Repository Resource Flow Pattern · maxrave-dev
    An envelope family for repository results — a remote wrapper, a local wrapper with a loading state, and a payload-free variant — plus the wrap-side and collect-side helpers that stop every view model from hand-writing the same branch, where the mapping from transport model to domain model belongs, and the one thing the envelope must never swallow. Use when designing repository return types, when error handling has drifted apart between screens, or when a cancelled screen reports a failure it never had.
    2.3k repo stars
  48. ▌
    Type Safe Nav Graph Organization · maxrave-dev
    Lay out a type-safe Navigation-Compose graph so it stays readable as the destination list grows — one serializable route object per file grouped by area, area graphs as extension functions on the graph builder, a single transition set on the host, and per-route theming applied by wrapping the screen inside its own entry. Use when a navigation file has grown to hundreds of lines, when route arguments start needing custom types, or when transitions or theming differ between destinations for no stated reason.
    2.3k repo stars
  49. ▌
    Borrowed Wire Protocol Discipline · maxrave-dev
    Rules for implementing a protocol someone else defined — no renaming, no reordering, constants the schema omits read off the counterpart implementation rather than guessed, unknown message types decoded to null instead of thrown, and negotiated capabilities narrowed but never widened. Use when your client must interoperate with an implementation you do not control, when a connection opens and then never gets anywhere, or when a peer on a newer version breaks your session.
    2.3k repo stars
  50. ▌
    Compose Desktop Runtime Hardening · maxrave-dev
    The ordered list of probes, system properties and platform gates a Compose desktop entry point must run before its first window exists. Covers warming the JDK's desktop-integration API ahead of any native load, renderer and interop properties that are read once at start-up, turning off vsync where the wait can park the UI thread, gating transparency and a custom titlebar on virtual-machine detection, and setting the Linux window-class name reflectively so the desktop entry binds. Use when the UI freezes while audio keeps playing after moving the window to another monitor, when the window never appears in a virtual machine, or when the Linux dock shows a class name instead of your app.
    2.3k repo stars
  51. ▌
    Config Fails Open Verify Artifact · maxrave-dev
    Verifying a config-driven feature against the generated artifact instead of against the config, for formats that fail open and ignore unknown keys — the two-build A/B diff, the artifact fingerprint to grep for, and the CI assertion that keeps it from regressing. Reach for it when a config key looks correct, the build is green, and the feature it configures has simply never been observed working.
    2.3k repo stars
  52. ▌
    Desktop Single Instance Before Di · maxrave-dev
    Order a desktop app's startup so the single-instance guard runs before the dependency container and before anything opens on-disk state. Covers forwarding a second launch's arguments to the running instance and exiting, bridging a restore request from outside the UI framework into the live window, and the platforms where a second launch never produces a second process at all. Use when launching the app a second time crashes or corrupts settings, when a link opened while the app is running does nothing, or when the second window steals a file the first one owns.
    2.3k repo stars
  53. ▌
    Glance Widget Over Existing State · maxrave-dev
    Build a home-screen widget that renders the app's existing state holder rather than a parallel copy of it, by injecting the same shared state object and the same long-lived scope the app already uses and re-issuing the widget update whenever that state changes. Covers dispatching the app's own UI events from widget buttons, why the injection target must be a singleton rather than a screen-scoped definition, making the whole widget a tap target, turning off hardware bitmaps for artwork the widget must read, and the leak to avoid when starting those collectors from the widget's provide-glance callback. Android only. Use when a widget shows stale playback or session state, when its artwork is blank, when a tap on it opens the launcher's menu or does nothing at all, or when its buttons need their own duplicate logic.
    2.3k repo stars
  54. ▌
    Nested Flag Settings Auto Disable · maxrave-dev
    A child toggle gated by a parent condition must key its auto-disable effect on the parent's current value, grey out rather than hide when the gate is closed, and be gated again at the consumer — otherwise the child sticks ON with no way for the user to clear it. Use when a settings switch is stuck on, is greyed out while reading enabled, or keeps acting after its precondition is gone.
    2.3k repo stars
  55. ▌
    Nowplaying Pager No Feedback Loop · maxrave-dev
    A now-playing artwork pager that both follows the player and drives it, without the two writing to each other in a loop — the in-progress-scroll flag covers programmatic animation as well as drags, the seek is dispatched from the settled page only, and the page-difference decision is a pure function outside the UI runtime. Use when a swipe bounces back to the page it came from, when one swipe skips two tracks, when the pager stops following the player after a fast swipe, when swiping backwards restarts the current track instead of going back one, or when a far swipe under shuffle lands on the wrong song.
    2.3k repo stars
  56. ▌
    Playback Position Persist Restore · maxrave-dev
    Persisting and restoring the playback position cheaply — a full queue save on lifecycle edges versus a light five-second position tick that rides an existing loop, skipping the save while the queue is being rebuilt, and snapshotting values before issuing player commands that change them. Use when background playback resumes from the start of a track after the process is killed, or when a restore lands on the wrong track or position.
    2.3k repo stars
  57. ▌
    Responsive Gate Size Not Platform · maxrave-dev
    Gate an adaptive layout on the window's own width-versus-height, never on the platform, and flip every geometry value the gate owns in the same breath — frame sizing, content scale and scrim height. Use when a layout is right on a phone and wrong in a narrow or resized desktop window, when forcing an adaptive flag to one value breaks a different platform's screen, or when artwork swallows the whole page on a wide window.
    2.3k repo stars
  58. ▌
    Touch Indication Bounds And Alpha · maxrave-dev
    Soften an app-wide touch ripple by alpha alone and give it the right bounds — the colour derives from the local content colour and stays correct inside a forced-scheme subtree, while pinning one paints darker than a near-black surface. Covers why the theme's configuration reaches a bare Modifier.clickable, why .clip(shape) must come before .clickable, why a card and its clip need one shape value, why two clickable modifiers must never stack, and the deprecated constructor that is the only way to set alpha. Use when a tap on a rounded item flashes a square, when the ripple reads as a sooty smudge on a dark theme, or when a long-pressable item ripples twice.
    2.3k repo stars
  59. ▌
    Filter Chain Two Owners One Writer · maxrave-dev
    Two independent features want entries in one engine property that holds the WHOLE chain, so writing it replaces everything — keep each feature's entries in its own field, compose them in a single writer, and let "clear" drop only its own tier. Use when a second effect is added beside an existing one, or when one of two effects works and then randomly stops working after a transition.
    2.3k repo stars
  60. ▌
    Identity Compare Immutable Setting · maxrave-dev
    Bundle a multi-field setting into one immutable value and hand it to a hot consumer as a supplier, so the consumer asks "has this changed?" with a single reference comparison instead of diffing N numbers per buffer — and can never observe the fields half-updated. Use when a per-buffer or per-frame consumer has to react to a user setting, or when a setting made of several fields is read inconsistently.
    2.3k repo stars
  61. ▌
    Polymorphic Load Media Entry Point · maxrave-dev
    One generic "load this item and start playing" function normalizes several item types into a single internal shape, routes the queue-seeding strategy off a discriminator, and gates every pre-enqueue policy at that one place. Use when playback can start from many screens and a rule (content filter, dedup, analytics, resume-without-autoplay) keeps getting forgotten on one of the paths.
    2.3k repo stars
  62. ▌
    Restricted Marker Is Not An Opt In · maxrave-dev
    Tell an opt-in marker from a restricted-to marker before adding suppressions — the first is enforced by the compiler and demands acknowledgement, the second demands nothing and means something different and worse; includes how to read which one an API carries straight out of the cached artifact, and why both conventions coexist in one library. Use when an `@OptIn` looks necessary but the same API compiles without it elsewhere, when the IDE offers a suppression for an annotation you have not read, or when deciding whether a library call is safe to depend on.
    2.3k repo stars
  63. ▌
    Script Aware Romanization Pipeline · maxrave-dev
    Adding a "show pronunciation" or transliteration feature across many non-Latin scripts in a Kotlin Multiplatform module — without pulling in ICU — needs a per-script dispatch built on Unicode block ranges rather than a locale, one line at a time rather than one song at a time, and a hard line between scripts that reduce to a table and the one or two that need a real dictionary. Use when a transliteration result is guessed for the wrong language, an unsupported platform fails outright instead of falling back, or a line that mixes two scripts (an original lyric plus an English aside) picks the wrong one.
    2.3k repo stars
  64. ▌
    Stateflow Conflation Inverts State · maxrave-dev
    A conflating state holder keeps one slot, so a callback that writes it several times per event makes write ORDER the correctness question — collectors see only the last write. Use when a spinner sits over content that is already loaded, when a loading flag clears at the wrong moment, or when a screen shows the state that was true one step ago.
    2.3k repo stars
  65. ▌
    Transparent Chip Selection Signals · maxrave-dev
    A see-through selection chip — a drop shadow under a transparent shape shows THROUGH it as a dark ring, and zeroing the resting elevation does NOT remove it, because each interaction state carries its own independent token default. Covers dropping the selection-only leading icon that widens the chip by 26dp and reflows a scrolling row under the finger that just tapped it, switching the outline off when the fill arrives, and pairing a role colour with its own "on" token. Use when a transparent chip has a dark halo that comes back on press or hover, when tapping a chip shifts its neighbours sideways, or when a selected chip's label is unreadable on one of the two themes.
    2.3k repo stars
  66. ▌
    Combining Chars Break Char Literals · maxrave-dev
    A Devanagari, Gurmukhi, or other diacritic-marked letter that looks like one glyph in the editor fails to compile as a `'x'` character literal with "Too many characters in a character literal," because it is a base letter plus a separate combining mark — two `Char`s, not one. Use when a lookup table keyed by `Char` needs an entry for a marked or accented letter outside plain Latin, or when per-character text processing garbles exactly the words that carry an accent.
    2.3k repo stars
  67. ▌
    Compose Desktop Video No Swingpanel · maxrave-dev
    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.
    2.3k repo stars
  68. ▌
    Dual Mode Persist Blocking Or Async · maxrave-dev
    One suspend persistence body driven two ways — blocking on the shutdown path, where the write must complete before the scope dies, and fire-and-forget on periodic ticks — instead of two copies that drift apart. Use when saved state is correct while the app runs but wrong after a hard quit, when a teardown save silently does nothing, or when two save functions have grown different guards.
    2.3k repo stars
  69. ▌
    Expect Actual Composable Capability · maxrave-dev
    Expose a device capability to shared Compose code as a @Composable expect function, with a full implementation on the platform that has it and a stub that returns the neutral value on the platform that does not. Covers the three shapes these take — a measurement, an effect with an undo, and a subscription read as state — and why a stub must still be correct. Use when shared UI needs a window measurement, a keep-awake flag or a windowing-mode state, when one platform stops the app the first time a screen paints, or when a shared screen behaves as if a capability is off on a platform that has it.
    2.3k repo stars
  70. ▌
    Pending State Makes Waiting Legible · maxrave-dev
    Model "asked, and not yet answered" as its own field, because without it a rejected request and a peer who simply has not looked at their screen are indistinguishable — both look like nothing happened. Covers the one set against many clears, clearing locally when no answer will ever come, and giving the user a way out. Use when an action appears to do nothing, when a screen can get stuck waiting forever, or when an error message has no place to appear.
    2.3k repo stars
  71. ▌
    Run Discriminating Experiment First · maxrave-dev
    When two nearly identical things behave differently, count the variables that still differ and run one swap-or-trade test that eliminates at least half of them, before writing any fix. Use when the same symptom has survived two or more attempted fixes, when one widget or screen or platform works and its near-twin sitting beside it does not, or when every attempt costs a slow build and somebody else's attention.
    2.3k repo stars
  72. ▌
    Ttl Keyed JSON Cache Lenient Decode · maxrave-dev
    A small keyed cache for values that drift — each entry carries the moment it was fetched and answers an isStale check against a time-to-live constant, the whole map is stored as one JSON string in key-value preferences, and decoding is lenient plus wrapped so a schema change degrades to a cache miss instead of destroying every entry. Use when caching resolved covers, lookups or per-key results without a database table, or when a cache stopped working entirely after a model field was added.
    2.3k repo stars
  73. ▌
    Ambient Tone Layer Behind Flat Pages · maxrave-dev
    A reusable top-glow layer that gives pages with no imagery of their own the same tinted ground the image-backed screens get — emitted as the first sibling of a navigation destination's content, with no wrapper, because destinations already stack. Covers why a null tone must collapse the gradient into the page colour instead of substituting a theme colour, why the scroll-away offset belongs in the draw phase, why the first list item must be taller than the layer, and which screens are right to keep their own copy. Use when a flat settings or list page looks unrelated to the rest of the app, when an idle app shows a glow for nothing, or when a glow snaps out of place as the list scrolls.
    2.3k repo stars
  74. ▌
    Bucket Local Time In Code Not In SQL · maxrave-dev
    Group events by local hour or local day in application code from one raw scan, not in SQL — the engine's local-time modifier answers from the process time zone rather than the user's, and four local-time aggregates mean four scans that can disagree with each other. Covers where the line sits between an aggregate that belongs in SQL and one that does not, and what the single scan has to return to stay correct. Use when an hour-of-day or weekday chart differs between platforms or between a device and a desktop build, when adding a fourth "group by day" query, or before writing a date function into a query string.
    2.3k repo stars
  75. ▌
    Chrome Drawn Outside The Theme Scope · maxrave-dev
    A custom window title bar, splash, or crash dialog composed as a sibling of the app theme rather than inside it reads MaterialTheme's framework DEFAULT scheme — light, always, no matter what the user picked — and nothing errors. Covers extracting the stored-mode-to-boolean decision as one shared composable function so the chrome and the theme cannot answer differently, passing colours in as parameters instead of re-theming, and the colours that must deliberately not follow the theme at all. Use when a title bar or dialog stays light in dark mode, when chrome colours lag one launch behind the setting, or before adding any composable above the theme call.
    2.3k repo stars
  76. ▌
    Compose Multiplatform Viewmodel Base · maxrave-dev
    A shared ViewModel base class for Compose Multiplatform — container-aware so subclasses can pull extra dependencies without constructor threading, with one loading/error surface for every screen — and the blocking resource-lookup hazard that such a base almost always grows. Use when every screen is re-implementing its own loading dialog, when a base class needs a dependency only some subclasses use, or when app start stutters on the main thread before anything is drawn.
    2.3k repo stars
  77. ▌
    Empty State Must Keep Its Navigation · maxrave-dev
    Replace a populated header with an empty-state message without deleting the controls that header owned — re-supply them only in the branch that owned them, order the loading branch above the empty one, and stop reserving the artwork's height for a line of text. Use when a user reaches an empty period, filter or search result and cannot get back out, when an empty message flashes on every reload, or when the same control renders twice.
    2.3k repo stars
  78. ▌
    Github Actions Multiplatform Release · maxrave-dev
    Structure a GitHub Actions release pipeline for a multiplatform desktop app so one Linux runner cross-builds every platform's artifacts and a second, tiny macOS job does only the one step that genuinely requires macOS — with artifact handoff between them and no compilation on the costly runner; reach for it when your release workflow runs three OS jobs that each rebuild the world, or when macOS users hit a hard block dialog on an app the pipeline signed correctly.
    2.3k repo stars
  79. ▌
    Model Entity Mapping Extension Layer · maxrave-dev
    Put every conversion between transport payloads, domain models and persistence rows in dedicated files of pure extension functions — one direction per function, no suspending work, no logging, nothing else in the file — and keep the layer honest with a grep. Use when conversion code is spreading into data classes, data-access objects or service clients, when a field turns out to be holding a value that belongs to a different field, or when re-reading a row wipes a flag the user set.
    2.3k repo stars
  80. ▌
    Preset Identity Read Back From Value · maxrave-dev
    Derive "which preset is this" by comparing the presets against the value in force instead of storing a label beside it, so editing drops to Custom by itself and returning re-selects — and derive any per-preset field that is a function of the preset's own numbers rather than writing it out per row. Use when a preset picker keeps showing a stale name, when a preset never re-selects itself, or when a per-row constant has drifted in one row out of twenty.
    2.3k repo stars
  81. ▌
    Readiness Barrier Needs Every Answer · maxrave-dev
    A barrier that holds a group until every member reports ready — answer it on bufferedness rather than on playing, answer only when you are actually named, name who is being waited for in the UI, and understand that one member that never answers freezes everyone. Use when a shared session stalls for all participants after one slow device joins, when playback silently never starts, or when a "loading" state has no explanation attached to it.
    2.3k repo stars
  82. ▌
    Swappable Crash Reporting And Dialog · maxrave-dev
    Ship a build with crash reporting and a build with none from one codebase, by swapping a module that exposes three top-level functions instead of an interface, so call sites are byte-identical and the no-tracking build provably contains no reporting code. Also covers a desktop crash dialog built on the older widget toolkit, because the modern UI may be exactly what just died, and how to marshal it onto that toolkit's event thread. Use when a privacy build must contain no reporting dependency at all, when a swapped implementation is drifting from its counterpart, or when the app dies with no visible error and no way for a user to send you the details.
    2.3k repo stars
  83. ▌
    Two Vendors One Package Kmp API Skew · maxrave-dev
    Two vendors ship the same package name at different versions into different source sets of one multiplatform build, so a member function that one vendor has already turned into a top-level extension resolves on exactly one target — a specific import compiles for Android and fails for desktop, or the reverse. Covers spotting the duplicate coordinate, why a wildcard import is the correct fix here rather than a smell, and the pinning discipline that keeps the pair readable. Use when shared UI code stops compiling on one target only after a routine dependency bump, when an unresolved-reference error names a symbol you can plainly see in the other target's sources, or when two catalog entries carry the same artifact name.
    2.3k repo stars
  84. ▌
    Upstream Lib Bug Workaround Template · maxrave-dev
    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.
    2.3k repo stars
  85. ▌
    Distinct By Key Reset Cancel Per Item · maxrave-dev
    Per-item pipelines that key on the item id with distinctUntilChangedBy, cancel the previous item's in-flight work before starting the next, and reset the visible state before filling it — so nothing from the previous item can appear under the new one. Use when a detail screen briefly shows the last item's artwork or text, when a slow response overwrites a newer one, or when a field stays populated after moving to an item that has no value for it.
    2.3k repo stars
  86. ▌
    Draw Outside Bounds Particle Modifier · maxrave-dev
    A celebration burst drawn by a plain draw modifier that paints past its host's own bounds — draw modifiers are unclipped by default, so the modifier must sit before every .clip(...) in the chain, and any clipping ancestor still trims whatever leaves its edge. Covers scaling origin and reach off the host's measured size so one effect reads the same at 28dp and at 48dp, keeping the per-frame lambda cheap, and why pure drawing beats an animation library here. Use when a burst renders cut to the button's outline, when it vanishes inside a rounded card or list row, or before adding a vector-animation dependency to draw one.
    2.3k repo stars
  87. ▌
    Jvmname Disambiguate Erased Overloads · maxrave-dev
    Resolve two extension functions that differ only in their generic receiver's type argument and so compile to a single JVM method, using @JvmName on one of them. Covers what the annotation changes, why it beats renaming the Kotlin function, and what non-Kotlin callers see afterwards. Use when the compiler reports a platform declaration clash between declarations you can plainly see are different, when adding a second converter over the same collection type breaks a file that compiled yesterday, or when a Java caller cannot find a function every Kotlin caller uses.
    2.3k repo stars
  88. ▌
    Mosaic Arrangements Must Be Hole Free · maxrave-dev
    Build a ranked mosaic (one big tile plus smaller ones) with an arm for every possible count, so no entry is silently dropped and no arrangement leaves an empty rectangle — plus one clip around the whole block rather than one per tile. Use when a "top five" shows four, when a grid renders a visible gap at some counts, or when an early return on an "unsupported" size looks harmless.
    2.3k repo stars
  89. ▌
    Publish A Snapshot On Taking The Role · maxrave-dev
    Every publisher in a shared session is edge-triggered off a change, so a participant who was already running when they took the publishing role emits nothing and the group sits in silence — publish a full snapshot on becoming the source, and again when a new member arrives. Use when a session starts empty until someone touches the transport, when a late joiner sees nothing, or when your state watchers all look correct and the group still knows nothing.
    2.3k repo stars
  90. ▌
    Runtime Override Not Preference Write · maxrave-dev
    Turn a user-facing feature off for the duration of a mode with a runtime override on the component, never by writing the stored preference — a process death mid-mode would leave the user's real setting permanently changed. Use when entering a mode has to disable an existing feature, when a setting mysteriously turned itself off and stayed off, or when a mode's cleanup is the only thing standing between a user and a lost preference.
    2.3k repo stars
  91. ▌
    Unbounded For Shares Capped For Lists · maxrave-dev
    A top-N query is right for a list and wrong for a share-of-the-whole — the cut tail shrinks the denominator and the entropy normaliser, inflating concentration and diversity alike — so the same grouped data needs two queries with different bounds. Covers why the truncation is invisible in the result, why the unbounded query's ORDER BY becomes load-bearing, and when unbounded is actually safe. Use when a "top 5 share" or diversity score reads implausibly high, when one grouped query is feeding both a leaderboard and a statistic, or before reusing a capped DAO method for anything that divides by a total.
    2.3k repo stars
  92. ▌
    Websocket Session Handshake Lifecycle · maxrave-dev
    The order a WebSocket session has to be brought up and torn down — reader started before the first message because the answer comes back through it, the handshake settled on a deferred with a timeout, the close frame sent under a non-cancellable context, and an event buffer that suspends rather than drops. Use when a socket connects but the session never becomes usable, when a deliberate disconnect leaves the peer thinking you are still there, or when clients drift out of sync after a burst of traffic.
    2.3k repo stars
  93. ▌
    Weight Fill False To Center A Cluster · maxrave-dev
    A weighted child occupies its whole slot even when its content measures narrower, which pins the sibling beside it to the far edge; `weight(1f, fill = false)` releases the unused width back to the row's arrangement so child, gap and sibling read as one cluster. Covers why the tell is the sibling rather than the weighted child, why the fix is two edits and not one, and why dropping the weight instead is a different layout. Use when a bar looks centred at one content size and lopsided at another, when a button clings to the screen edge with a hole beside it, or when a trailing label sits far from the text it belongs to.
    2.3k repo stars
  94. ▌
    Continuation Token Pagination Contract · maxrave-dev
    Model an endpoint that returns a page plus a next-token as Flow<Resource<Pair<items, token?>>> — a null token means the end, the caller stores only the token, and a bounded prefetch primes the first pages before anything is shown. Use when wiring an opaque-cursor API into a repository, or when a list stops loading after one failed request and never recovers, or when paging fires twice for one trigger.
    2.3k repo stars
  95. ▌
    Control Range Must Cover Stored Values · maxrave-dev
    Size a slider's range from the real distribution of values it will be handed — stored, imported, migrated — rather than from a neighbouring control's range, because a value outside the range parks the thumb at the end of the track while your readout shows a different number, and the first touch silently rewrites it. Use when adding a slider for a value that can arrive from anywhere but the slider itself.
    2.3k repo stars
  96. ▌
    Encoded Continuation Tokens Local Sort · maxrave-dev
    Carry locally sorted and shuffled paging through the same token slot a remote API uses, by prefixing the token with a mode tag and encoding a cursor after it — and reject an unrecognised prefix loudly, because a silently ignored token leaves the pager stuck in its in-flight state and the list never loads again. Use when one list must page from either a server cursor or a local ordering, or when local sorting made paging stop working with nothing in the log.
    2.3k repo stars
  97. ▌
    Flat Twin Shares Geometry Not Material · maxrave-dev
    When a user setting picks between two renderings of the same control — an expensive decorative one and a plain twin — every geometry decision has to be mirrored between them (item width, bar height, indicator size, inset, and the rule that computes the width budget) so toggling changes the material and never the layout; the compiler cannot pair two constants declared in two files. Also covers recolouring an icon that arrives as a slot lambda, which only CompositionLocalProvider(LocalContentColor) can reach. Use when switching a visual setting also moves things, when the plain variant's indicator sits off its item, or when a slot-lambda icon ignores every tint you pass.
    2.3k repo stars
  98. ▌
    Mirror Local State To A Remote Account · maxrave-dev
    An opt-in switch that mirrors a local flag onto a signed-in remote account — turning it on back-fills everything already flagged, turning it off stops mirroring and deliberately does not undo, and the per-item call is three-valued so "not attempted" is distinguishable from "failed". Covers writing locally first and unconditionally, which of the two paths is allowed to speak to the user, and why the back-fill is sequential. Use when a mirrored flag silently disagrees with the account, when the user cannot tell a failure from a no-op, or before wiring a settings switch to a remote write.
    2.3k repo stars
  99. ▌
    One Snapshot Per Period Not Many Flows · maxrave-dev
    Return a whole period's figures as one immutable snapshot from a single suspend call, rather than as a dozen independent flows the screen has to line up — a screen comparing two spans needs each span coherent, and separate emissions let a count from this period render beside a total from the last. Covers when a single-emission flow is a suspend function in costume, which derived figures belong on the snapshot, and why a rate needs the denominator a human means. Use when a comparison screen briefly shows mismatched numbers while reloading, when adding the tenth flow to one screen's repository, or when two places compute the same average differently.
    2.3k repo stars
  100. ▌
    Reproducible Native Bundling Two Tasks · maxrave-dev
    Ship prebuilt native libraries to a multiplatform desktop build by splitting bundling into two Gradle tasks with different homes — a dev-machine task that builds the slices, packs tarballs and prints their digests, and a CI task that only downloads and verifies against digests pinned in the build file; reach for it when CI needs a native toolchain it should not have, when a native bump quietly ships the previous binaries, or when the packaged installer launches with the native missing entirely.
    2.3k repo stars