Coder Legion - Recent posts tagged kmp

Why BasicTextField Fails at Scale — And How I Build Kortex

Mon, 19 Oct 2026 14:55:34 +0000

Reaching sub-millisecond input latency on 100K-line files using Kotlin Multiplatform, Skia, and Virtualized canvas layers

If you have ever tried building a serious text or code editor in Jetpack Compose or Compose Multiplatform using BasicTextField, you already know where the ceiling is.

Declarative UI frameworks excel at forms, chat inputs, and short documents. However, the moment you load a 50,000-line source file, attach real-time syntax highlighting, spawn multiple cursors, and scroll rapidly at 120Hz, the standard composable pipeline starts gasping for air. Recreating AnnotatedString instances on every keystroke, measuring thousands of nested layout nodes, and allocating objects on the hot rendering path inevitably leads to garbage collection pauses and dropped frames.

To solve this properly across Desktop (JVM), Android, iOS, and WebAssembly (Wasm-JS), I built Kortex — an open-source, hardware-accelerated code and text editor engine for Kotlin Multiplatform.

Here is a deep dive into the architecture behind Kortex, why it bypasses standard Compose text components entirely, and how it achieves locked 60+ FPS rendering on massive documents.

1. The Core Philosophy: Zero Composable-Per-Line Overhead

In a traditional declarative list (like a LazyColumn of text rows), every visible line is a separate composable node with its own layout pass, modifier chain, and composition state. When you scroll horizontally and vertically simultaneously, or render cross-line selections and diagnostic squiggles, coordinating state across individual row composables becomes an intractable bottleneck.

Kortex treats the entire editor viewport as a single hardware-accelerated surface.

Instead of delegating text rendering to Compose UI nodes, Kortex drops down directly to Skia (via Skiko) using a platform-specific SkiaCanvas abstraction:

// JVM, iOS, and WasmJS implementation
@Composable
actual fun SkiaCanvas(
    modifier: Modifier,
    onRender: (canvas: Canvas, width: Int, height: Int) -> Unit
) {
    Box(
        modifier = modifier.drawWithCache {
            val width = size.width.toInt()
            val height = size.height.toInt()

            onDrawBehind {
                if (width <= 0 || height <= 0) return@onDrawBehind

                drawIntoCanvas { canvas ->
                    onRender(canvas.nativeCanvas, width, height)
                }
            }
        }
    )
}

On Android, SkiaCanvas binds directly to an embedded SkikoSurfaceView and SkiaLayer. State changes that require repaints (such as cursor blinking or text input) trigger frame updates via SideEffect { surfaceView?.scheduleFrame() }, guaranteeing identical 60+ FPS Skia rendering semantics across all four targets without forcing recompositions across the entire Compose UI tree.

The Layered Rendering Pipeline

Every frame inside EditorCanvas is composed of lightweight, pre-calculated Layer primitives rendered in a strict Z-order pass:

Background Canvas (BackgroundLayer)
Gutter Background (gutterBackgroundLayer)
Unified Active Line Highlight (HighlightedLineLayer rendered across the full viewport width)
Isolated Gutter Elements (GutterLineLayer, FoldingMarkersLayer, GutterSeparatorLayer clipped to gutterWidth)
Code Viewport Matrix Shift & Clip (nativeCanvas.translate(gutterWidth, 0f) clipped to code width)
Underlay Guides & Markers (ColumnRulerLayer, OccurrencesHighlightLayer)
Multi-Selection Regions (SelectionLayer)
Syntax-Highlighted Text Paragraphs (TextContentLayer)
Diagnostic Sine-Wave Squiggles (DiagnosticsLayer)
Blinking Multi-Carets (CaretLayer)

Because the line-number gutter is isolated through its own clip bounds and the code area is shifted with matrix translations, horizontal code scrolling never bleeds into the gutter, and the entire viewport paints in a single unified GPU pass.

2. Backed by Krope: Logarithmic Text Mutations

A fast renderer is useless if typing a character copies a 10MB String in memory.

Under the hood, Kortex is powered by Krope, a thread-safe, persistent Red-Black Rope text buffer built specifically for high-throughput text processing.

Logarithmic Edits: Insertions, deletions, and range replacements execute in $O(\log N)$ time with structural sharing.
Immutable Snapshots: The UI and background analysis pipelines read from an immutable TextSnapshot tied to a monotonic TextRevision.
Delta Position Mapping: When a batch edit occurs (for example, typing simultaneously with 15 active cursors), Kortex sorts operations in descending document order so earlier edits never invalidate the offsets of later ones. Once the rope commits the transaction, it returns a TextEdit.Data delta, and EditorEngine maps every surviving selection and caret through that delta mathematically:

private fun mapSingleDelta(position: TextPosition, delta: TextEdit.Data.Single): TextPosition {
    val start = delta.startPosition
    val oldEnd = delta.oldEndPosition
    val newEnd = delta.newEndPosition

    return when {
        position < start -> position
        position in start..oldEnd -> newEnd
        else -> {
            val lineDelta = newEnd.line - oldEnd.line
            when (position.line) {
                oldEnd.line -> {
                    val colDelta = newEnd.column - oldEnd.column
                    TextPosition(line = position.line + lineDelta, column = position.column + colDelta)
                }
                else -> TextPosition(line = position.line + lineDelta, column = position.column)
            }
        }
    }
}

For structural line operations like MoveLineUp and MoveLineDown (Alt + Up/Down), calculating position via delta projection alone would snap the caret to the edge of the replaced range. Kortex resolves this by supporting explicit targetSelections inside EditorCommand.ApplyText, enabling line swaps to carry their carets and selections to adjacent lines without caret drift.

3. Killing GC Pauses with Bounded Native LRU Caches

Skia objects like Paragraph, TextLine, and Paint wrap native C++ resources. Allocating and destroying them on every 16ms frame (or 8ms on 120Hz ProMotion displays) quickly overwhelms the memory allocator.

Kortex solves this with a custom thread-safe LruCache extending CloseableResource. Whenever an item is evicted from the cache—or when the editor composable leaves the composition tree—its underlying native Skia pointer is deterministically closed:

internal class CodeParagraphCache(capacity: Int = 1000) : LruCache<CodeParagraphCache.Key, Paragraph>(capacity) {
    data class Key(
        val line: Int,
        val text: String,
        val tokens: List<Token>,
        val font: EditorFont,
        val syntaxTheme: SyntaxTheme,
    )

    override val factory: Key.() -> Paragraph = {
        // Builds and lays out the Skia Paragraph only on a cache miss
        ...
        builder.build().apply { layout(Float.MAX_VALUE) }
    }
}

Crucially, this zero-allocation philosophy extends to input gestures. Dragging the mouse to select text calls getOffsetAtCoordinate on every pixel change. Re-parsing a Skia paragraph on each pointer move would create unacceptable jank. In Kortex, EditorFont manages an internal measurementParagraphCache:

private val measurementParagraphCache = object : LruCache<String, Paragraph>(capacity = 128) {
    override val factory: String.() -> Paragraph = {
        val textToMeasure = this
        TextStyle().apply {
            this.fontFamilies = arrayOf(*Emails are not allowed*lyName)
            this.fontSize = *Emails are not allowed*
        }.use { baseTextStyle ->
            ParagraphStyle().apply {
                this.maxLinesCount = 1
                this.textStyle = baseTextStyle
            }.use { style ->
                buildParagraph(style) {
                    pushStyle(baseTextStyle)
                    addText(textToMeasure)
                    popStyle()
                }.use { builder ->
                    builder.build().apply { layout(Float.MAX_VALUE) }
                }
            }
        }
    }
}

During continuous 120 FPS scrolling, cursor blinking, or rapid mouse selection, Kortex hits its bounded caches with near-100% hit rates, resulting in zero native allocations on the render loop.

4. Viewport Virtualization & Logarithmic Code Folding (`FoldMap`)

How do you render a 200,000-line file when 50 different functions and classes are collapsed?

Iterating through lines to check which ones are hidden would turn rendering into an $O(N)$ operation. Instead, Kortex compiles collapsed regions into an immutable FoldMap—a sorted, merged interval table storing cumulative hidden line counts and visual thresholds:

internal data class Interval(
    val startLine: Int,
    val endLine: Int,
    val hiddenCount: Int,
    val cumulativeHiddenBefore: Int,
    val visualStartThreshold: Int,
)

Converting between a Visual Line (what the user sees on screen) and a Document Line (the actual index in the Rope buffer) is a binary search over active intervals running in $O(\log K)$ time, where $K$ is the number of folded blocks:

Viewport.of(...) calculates the exact visible visual line slice (startVisualLine..endVisualLine) from scrollY and lineHeight.
Each visible line is mapped to its true document line via foldMap.visualToDocumentLine(visualLineIndex).
Collapsed lines are completely culled before Skia ever touches them.

5. Pure Unidirectional MVI & Smart Undo/Redo Coalescing

UI components in Kortex never mutate state directly. The entire :kortex-core module is completely headless (zero Compose dependencies) and operates as a deterministic state machine:

(EditorState, EditorAction) -> EditorResult(newState, EditorCommand?)

Pure Reducers: CaretReducer, SelectionReducer, EditReducer, and ViewportReducer compute next states purely in memory.
Multi-Cursor Normalization: Every time cursors move or expand, Selection.normalize(...) sorts all active selections and automatically merges overlapping or touching ranges while preserving selection direction (FORWARD vs. BACKWARD), surrogate pairs (emoji), and stickyColumn offsets.
Sliding-Window Undo/Redo: HistoryManager records forward and inverse TextOperation.Data commands and automatically merges contiguous single-line insertions or deletions if they occur within a 700ms window—restoring exact multi-cursor positions when undone.

6. Full IDE Tooling: Async Analysis, Squiggles & Hierarchical Themes

On top of the plain-text :kortex-core engine sits :kortex-code and :kortex-code-compose, turning the editor into a complete IDE component.

Debounced Coroutine Pipelines

CodeEditorEngine binds to a pluggable LanguageAnalysisService using Kotlin Coroutine Flows on Dispatchers.Default:

Tokenization (TokenProvider): Debounced at 50ms, dropping stale snapshots via distinctUntilChangedBy(TextSnapshot::revision) and mapLatest. Existing folding regions and symbol occurrences are preserved during token updates.
Diagnostics (DiagnosticsProvider): Debounced at 300ms, feeding DiagnosticsLayer to draw procedural sine-wave/zigzag paths directly under erroneous tokens.
Hover Documentation (DocumentationProvider): Debounced at 250ms, resolving documentation for the symbol under the primary caret and updating CodeEditorState.documentation.
IntelliSense (CompletionProvider): Floating popup anchored to the active caret's visual coordinates with keyboard navigation (Up, Down, Tab/Enter, Escape).

Hierarchical Token Theming

Inspired by TextMate and VS Code scopes, SyntaxTheme resolves token colors hierarchically using dot-separated fallbacks. If your lexer emits keyword.control and the active theme only defines a color for keyword, Kortex walks up the scope tree automatically:

val syntaxTheme = SyntaxTheme.build(defaultText = Color(0xFFABB2BF)) {
    put(TokenType.KEYWORD.name, Color(0xFFC678DD))
    put(TokenType.KEYWORD_CONTROL.name, Color(0xFFE06C75)) // Overrides "keyword"
    put(TokenType.FUNCTION.name, Color(0xFF61AFEF))
    put(TokenType.STRING.name, Color(0xFF98C379))
}

Getting Started in 30 Seconds

Kortex is published on Maven Central and divided into four modular artifacts so you only pull what you need:

dependencies {
    implementation("io.github.numq.kortex:core:1.1.0")         // Headless engine
    implementation("io.github.numq.kortex:core-compose:1.1.0") // Plain text Skia editor
    implementation("io.github.numq.kortex:code:1.1.0")         // Code analysis engine
    implementation("io.github.numq.kortex:code-compose:1.1.0") // Full IDE Composable
    implementation("io.github.numq.krope:text:1.1.1")          // Rope text buffer
}

Embedding a full-featured code editor in your Compose Multiplatform app takes just a few lines:

@Composable
fun IdeEditorScreen() {
    val scope = rememberCoroutineScope()

    val buffer = remember {
        RopeTextBuffer(
            initialText = "fun main() {\n    println(\"Hello, Kortex!\")\n}",
            initialLineEnding = TextLineEnding.LF,
            initialEncoding = Encoding.UTF8,
            enablePooling = true
        )
    }

    val editorEngine = remember(buffer) { EditorEngine(scope = scope, buffer = buffer) }
    val codeEngine = remember(editorEngine) {
        CodeEditorEngine(
            scope = scope,
            engine = editorEngine,
            analysisService = myLanguageAnalysisService
        )
    }

    val font = remember {
        val typeface = FontMgr.default.matchFamilyStyle("JetBrains Mono", FontStyle.NORMAL)
            ?: Typeface.makeEmpty()
        EditorFont(typeface = typeface, size = 14f, lineSpacing = 1.25f)
    }

    DisposableEffect(font) {
        onDispose {
            font.close()
        }
    }

    val theme = rememberCodeEditorTheme()

    KortexCodeEditor(
        engine = codeEngine,
        font = font,
        theme = theme,
        columnRuler = 80,
        modifier = Modifier.fillMaxSize()
    )
}

Out of the box, you get Alt + Click multi-cursors, Ctrl/Cmd + D next-occurrence selection, code folding, smart indentation, line moving (Alt + Up/Down), comment toggling (Ctrl/Cmd + /), right-click context menus, and native desktop scrollbar adapters.

Explore the Source Code

Both Kortex and Krope are 100% open-source under the Apache 2.0 License. Whether you are building a developer tool, a Markdown note-taking app, a database query console, or a full multiplatform IDE, I would love for you to try it out and share your feedback!

Kortex: github.com/numq/kortex
Krope: github.com/numq/krope

Kempo: Real-Time Audio Time-Stretching, Pitch-Shifting, and Formant Control in Pure KMP

Wed, 14 Oct 2026 07:01:23 +0000

Zero-allocation streaming, phase-locked clarity, and multichannel spatial coherence across JVM, Android, iOS, and WebAssembly.

Whether you are building a podcast player with variable playback speed, a music practice app that slows down a complex guitar solo without dropping the tuning, a real-time voice modulator, or a spatial audio engine for a game, you eventually hit the same fundamental challenge: decoupling time from pitch.

In raw digital audio, playback speed and pitch are locked together. Play a buffer twice as fast, and the pitch jumps up a full octave. Slow it down, and everything drags into a muddy baritone.

Breaking that link—while keeping drums punchy, vocals natural, and the stereo image intact—requires a dedicated Digital Signal Processing (DSP) engine.

Meet Kempo (io.github.numq:kempo): an open-source, pure Kotlin Multiplatform audio time-stretching and pitch-shifting library built for studio-grade acoustic transparency and sub-millisecond real-time streaming across JVM, Android, iOS, and WebAssembly (Wasm/JS).

What Kempo Brings to Your Audio Stack

Kempo is designed to be drop-in simple for high-level application code while exposing full, granular control for low-level audio threads:

Independent Time, Pitch, and Formant Control: Speed up or slow down audio (0.25x to 3.0x and beyond), transpose musical pitch in semitones, and shift vocal timbre independently.
Zero-Allocation Real-Time Streaming: Once configured, the block-by-block processing loop allocates 0 bytes on the heap, eliminating Garbage Collection pauses on high-priority audio threads.
Vertical Harmonic Phase-Locking: Keeps transients crisp and eliminates the hollow, "underwater" phasing artifacts common in basic time-stretchers.
Multichannel & 5.1 Surround Coherence: Preserves exact inter-channel phase relationships across stereo and surround tracks so the soundstage never collapses.
Sample-Accurate Offline Rendering: Built-in pre-roll warm-up, algorithmic latency compensation, and automatic overlap-add tail flushing.
Built-In PCM-16 Serialization: Convert raw little-endian or big-endian WAV/PCM byte arrays directly into normalized floating-point tracks and back.

How Kempo Keeps Audio Crisp (Without the Artifacts)

If you have ever used a naive time-stretching algorithm, you probably recognize three classic audio defects: smeared drum hits, "chipmunk" vocals, and a collapsing stereo field. Kempo solves all three at the engine level.

1. Eliminating Transient Smearing with Vertical Phase-Locking

Standard phase vocoders split audio into hundreds of narrow frequency bins and advance the phase of each bin over time. Because each bin is updated in isolation, the natural harmonic alignment between a fundamental note and its overtones quickly drifts apart. Percussive attacks lose their snap, and instruments sound phasey and diffuse.

Kempo continuously analyzes the smoothed spectral energy contour of each frame to locate prominent spectral peaks. Instead of letting neighboring bins drift, Kempo performs vertical phase-locking—anchoring the phase trajectories of surrounding frequency bins to their dominant harmonic peaks. Harmonics move together as a unified acoustic event, keeping transients tight.

When stretching audio to extreme lengths (beyond 2.0x), Kempo automatically transitions into controlled stochastic phase dispersion, preventing the metallic ringing that usually plagues ultra-slow playback.

2. Fixing the "Chipmunk" Effect with Formant Decoupling

When you pitch a human voice up by +5 semitones, you aren't just raising the pitch of the vocal cords—you are also shrinking the perceived size of the singer's vocal tract. The result is the notorious "chipmunk" effect (or the "monster" effect when pitching down).

In Kempo, pitch and vocal timbre (formants) are decoupled. Kempo extracts the spectral envelope of the signal and allows you to shift or lock formants independently of the musical transposition:

Natural Pitch Shifting: Enable formant compensation (compensatePitch = true) to keep a singer's vocal tract resonance anchored while changing their melody.
Creative Voice Design: Shift formants up or down while keeping pitch at 0 st to transform the character and age of a voice without changing the note being sung.

3. Preserving Stereo Width and 5.1 Surround Imaging

Our ears localize sound in space by detecting tiny timing and phase differences between the left and right channels. If an audio processor stretches the Left and Right channels independently, their relative phases drift apart—causing the stereo image to wobble and center-panned vocals to hollow out when downmixed.

Kempo processes multichannel audio coherently. At every frequency band, it identifies the dominant channel and locks the Inter-channel Phase Differences (IPD) of all remaining channels to that reference. Whether you are processing a stereo master or a discrete 6-channel 5.1 surround mix, panning stays locked and center dialogue remains phase-aligned.

Getting Started

Kempo is published on Maven Central. Add the dependency to your build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.numq:kempo:1.0.0")
        }
    }
}

Or for a single-platform JVM/Android module:

dependencies {
    implementation("io.github.numq:kempo:1.0.0")
}

1. The One-Liner: Offline Track Processing

If you have raw 16-bit PCM bytes (from a WAV file, network stream, or microphone recording) and want to stretch or transpose them in a background coroutine, PcmConverter and AudioTrack handle the entire pipeline in a few lines:

import io.github.numq.kempo.PcmConverter

// 1. Decode interleaved 16-bit PCM bytes into a normalized [-1.0f, 1.0f] AudioTrack
val track = PcmConverter.fromPcm16(
    bytes = rawWavBytes,
    channels = 2,
    sampleRate = 44100f,
    isLittleEndian = true
)

// 2. Speed up by 25%, pitch up by 3 semitones, keep natural formants
val stretchedTrack = track.stretch(
    timeRatio = 1.25f,
    pitchSemitones = 3.0f,
    formantSemitones = 0.0f
)

// 3. Convert back to 16-bit PCM bytes for playback or file export
val outputBytes = PcmConverter.toPcm16(stretchedTrack, isLittleEndian = true)

2. Zero-Allocation Real-Time Streaming

Real-time audio callbacks operate under strict deadlines. Allocating arrays or objects inside the render loop will eventually trigger the garbage collector and cause audible clicks.

KempoStretch pre-allocates all ring buffers, FFT plans, twiddle factors, and spectral workspaces upfront during presetDefault() or configure(). Inside your audio callback, process() mutates pre-allocated buffers in place:

import io.github.numq.kempo.KempoStretch
import kotlin.math.max

class LiveAudioProcessor(
    channels: Int = 2,
    sampleRate: Float = 48000f
) {
    private val stretch = KempoStretch().apply {
        presetDefault(channels, sampleRate)
    }

    val outBlockSize: Int = stretch.defaultInterval
    private val outBuffer = Array(channels) { FloatArray(outBlockSize) }

    fun updateParameters(pitchSemitones: Float, formantSemitones: Float) {
        stretch.setTransposeSemitones(pitchSemitones)
        stretch.setFormantSemitones(formantSemitones, compensatePitch = true)
    }

    // Safe for high-priority audio threads: 0 B heap allocations
    fun processFrame(
        inputChannels: Array<FloatArray>,
        playbackSpeed: Float
    ): Array<FloatArray> {
        val inSamples = max(1, (outBlockSize * playbackSpeed).toInt())
        stretch.process(
            inputs = inputChannels,
            inputSamples = inSamples,
            outputs = outBuffer,
            outputSamples = outBlockSize
        )
        return outBuffer
    }
}

Need to support interactive scrubbing on a timeline without clicks or phase resets? Use stretch.seek() before resuming playback to pre-seed the internal phase accumulators with the audio frames right before the new cursor position:

val seekPreRoll = minOf(stretch.seekLength(), targetSampleIndex)
stretch.seek(
    inputs = track.channels,
    inputSamples = seekPreRoll,
    playbackRate = 1.0,
    inputOffset = (targetSampleIndex - seekPreRoll).coerceAtLeast(0)
)

3. Sample-Accurate Offline Rendering with `exact()`

When rendering an audio clip for a DAW timeline or a game asset pipeline, you often need the output buffer to match an exact target sample count—without leading silence from the STFT window latency or cut-off reverb tails at the end.

KempoStretch.exact() automates the entire offline lifecycle: it calculates the required pre-roll (outputSeekLength), warms up the vocoder state (outputSeek), processes the body of the track, and flushes the final synthesis tails (flush):

import io.github.numq.kempo.KempoStretch
import kotlin.math.roundToInt

fun renderExactClip(
    input: Array<FloatArray>,
    sampleRate: Float,
    timeRatio: Float,
    pitchSemitones: Float
): Array<FloatArray> {
    val channels = input.size
    val inSamples = input[0].size
    val outSamples = (inSamples / timeRatio).roundToInt().coerceAtLeast(1)
    val output = Array(channels) { FloatArray(outSamples) }

    val stretch = KempoStretch().apply {
        presetDefault(channels, sampleRate)
        setTransposeSemitones(pitchSemitones)
    }

    stretch.exact(
        inputs = input,
        inputSamples = inSamples,
        outputs = output,
        outputSamples = outSamples
    )
    return output
}

4. Custom Frequency Mapping & Tonality Limits

For experimental sound design, spectral effects, or specialized speech conditioning, Kempo lets you bypass standard semitone math entirely:

Tonality Limits: When transposing speech or vocals up, multiplying high-frequency sibilance ("s" and "sh" sounds) can make them sound lispy or artificial. Passing a tonalityLimit to setTransposeSemitones(semitones, tonalityLimit) transitions the upper spectrum from multiplicative harmonic scaling to a clean linear shift.
Custom Transfer Functions: Pass any lambda to setFreqMap to warp normalized frequencies [0.0f, 0.5f] non-linearly:

stretch.setFreqMap { normalizedFreq ->
    // Custom non-linear spectral warping
    (normalizedFreq * 1.15f).coerceIn(0f, 0.5f)
}

Engineered for Speed in Pure Kotlin

Writing high-throughput DSP in pure Kotlin without falling back to platform-specific C/C++ libraries requires careful attention to memory layout and CPU cache locality:

Flat Power-of-Two Ring Buffers (MultiChannelBuffer): Instead of nested object arrays or modulo arithmetic, Kempo backs all channels with a single flat FloatArray. Wrap-around indices are resolved via bitwise masks ((head + offset) and mask), and overlap-add accumulation uses 4x unrolled loops.
In-Place Mixed-Radix FFT (FastFft & ModifiedRealFFT): Supports radix-2, radix-3, radix-4, and composite window sizes with precomputed twiddle tables. Real signals are evaluated on a half-bin shifted grid (k + 0.5) / N, avoiding DC and Nyquist edge singularities and cutting transform overhead in half.
Split Computation Mode (split = true): In real-time audio, doing a full STFT analysis and synthesis every N samples can cause periodic CPU spikes. Enabling split = true in configure() or presetCheaper() slices the spectral workload into small incremental steps distributed evenly across every sample frame.
Automatic Silence Bypass: When input energy drops below the noise floor, Kempo automatically bypasses heavy spectral math while keeping ring buffers synchronized.

In JMH benchmarks on standard desktop JVM hardware (44.1 kHz audio), Kempo processes a real-time streaming block in ~220 μs (mono) and ~484 μs (stereo), and renders offline audio at over 128x real-time speed for mono and ~70x real-time for stereo.

Try It Live: The Compose Desktop Studio App

Want to hear how Kempo handles your own audio files before writing a line of code?

The repository includes an interactive Compose Multiplatform Desktop Studio application (:example). Drop any .wav file onto the window to inspect its waveform, scrub through the timeline in real time, and tweak live parameters on the fly:

Playback Speed (0.25x – 3.00x) with instant presets (0.50x, 0.75x, 1.25x, 1.50x, 2.00x)
Pitch Shift (-12 st to +12 st) in semitone steps
Formant Shift (-12 st to +12 st) for real-time vocal timbre shaping

Explore the Code

Check out the full source code, architecture docs, and the runnable CLI attack simulation on GitHub.

Why HTTPS Won’t Save Your Checkout Flow: Building Zero-Trust State Machines in Kotlin Multiplatform

Wed, 14 Oct 2026 06:29:28 +0000

How to protect multi-step workflows, fintech funnels, and Server-Driven UI from step-skipping, state tampering, and replay attacks — with zero runtime dependencies.

Imagine a standard e-commerce checkout flow: Shopping Cart → Shipping Address → Promo Code → Payment Authorization.

You use HTTPS. You validate JWT tokens on every request. Your backend endpoints are covered with unit tests. You feel safe.

Then someone opens your app on a rooted device, hooks into memory with Frida, or simply manipulates an internal deep link. Instead of going from Cart to Shipping (where a $50 express delivery fee is calculated), the client dispatches a transition straight from Cart to Payment. Or worse, in a Server-Driven UI (SDUI) flow, an attacker replays a cached JSON payload from five minutes ago where a KYC verification flag was temporarily set to true.

HTTPS only encrypts the pipe. JWTs only verify who is holding the token. Neither guarantees that your client-side state machine actually followed the legal sequence of steps to reach its current screen.

To fix this at the architectural level without littering business logic with endless if-else checks, I built TrustChain — a pure functional, cryptographically verifiable state machine ledger for Kotlin Multiplatform (KMP).

The Mental Model: Think "Git Commits" for Your App State

You don’t need a PhD in cryptography or heavy blockchain consensus algorithms to secure a user journey. You just need strict lineage.

Think about how Git works: every commit contains a hash of its own content plus the exact hash of the parent commit. If you try to alter history or insert a commit out of nowhere, the hashes don't match, and Git rejects the tree immediately.

TrustChain brings this exact mechanism to your application’s navigation and state stack:

Every screen or workflow step has a unique hash representing its current state, and a previousHash pointing to the exact step that preceded it.
When the user moves forward, the incoming step’s previousHash must match the hash of the currently active step on top of the stack.
Partial state updates (like applying a promo code or updating live order status over WebSockets) arrive as signed deltas (DeltaBlock). They verify the current hash, check the server’s asymmetric digital signature, mutate the state, and verify the new hash.

If an attacker tries to skip a screen, inject a fake discount, or replay an old state, the hash chain breaks. The state machine fails fast before a single pixel is rendered or a network call is fired.

Security Concern	Standard REST + HTTPS	JWT Tokens	TrustChain
Data In-Transit Encryption	Yes (TLS)	Yes (TLS)	Yes (TLS)
Prevent Step Skipping (Deep Links)	No (Complex backend checks)	No	Yes (Parent Hash Check)
Detect Tampered State Deltas	No	Partially	Yes (Asymmetric Signatures)
Replay Attack Prevention	Manual nonces required	No	Yes (Strict Hash Lineage)
Zero Runtime Dependencies	N/A	Often heavy	Yes (Pure KMP)

Designing for Zero Bloat: The Core Primitives

One of my main goals with TrustChain was keeping the core completely free of third-party runtime dependencies so it drops cleanly into Android, iOS, Desktop, Web, or backend KMP targets.

1. `VerifiableBlock`

Any screen, workflow step, or state snapshot in your domain simply implements a three-property interface:

interface VerifiableBlock {
    val id: String
    val hash: String
    val previousHash: String? // null only for the root (genesis) step
}

2. `DeltaBlock` (Signed Partial Updates)

Why re-fetch an entire screen when a user applies a 10% coupon or an order changes status? Instead of sending full state trees, the server sends a lightweight DeltaBlock:

@Serializable
data class DeltaBlock<P>(
    @SerialName("patches") val patches: P,
    @SerialName("previous_hash") val previousHash: String,
    @SerialName("new_hash") val newHash: String,
    @SerialName("signature") val signature: String = ""
)

Notice how DeltaBlock locks the mutation from both sides:

It can only be applied if the client is currently sitting on previousHash.
Its newHash is signed by the server's private key (RSA, Ed25519, or ECDSA).
Once the client applies patches via a BlockPatcher, the resulting block must produce newHash.

3. Pure Functional Reduction

TrustChain is completely immutable. There are no hidden side effects, mutable singletons, or uncaught exceptions flying across coroutines. You send a ChainEvent (Push, Pop, Replace, or ApplyDeltas), and reduce() returns a standard Kotlin Result:

sealed interface ChainEvent<out B : VerifiableBlock, out P> {
    data class Push<B : VerifiableBlock>(val block: B) : ChainEvent<B, Nothing>
    data object Pop : ChainEvent<Nothing, Nothing>
    data class Replace<B : VerifiableBlock>(val block: B) : ChainEvent<B, Nothing>
    data class ApplyDeltas<P>(val blocks: List<DeltaBlock<P>>) : ChainEvent<Nothing, P>
}

If a batch of 5 deltas is applied and the 4th delta has a broken hash link or invalid signature, atomicity is preserved — the entire reduction fails cleanly with a typed ChainError, leaving your original TrustChain untouched.

Real-World Walkthrough: The Unbreakable Checkout

Let’s look at how this works in practice using a multi-step checkout flow.

First, we define our domain step:

@Serializable
data class CheckoutStep(
    override val id: String,
    val title: String,
    val state: Map<String, String> = emptyMap(),
    override val hash: String,
    override val previousHash: String? = null
) : VerifiableBlock

Next, we initialize TrustChain on the client. Notice how cryptography and state patching are injected via simple functional interfaces (SignatureVerifier and BlockPatcher). You aren't locked into any specific crypto library:

var clientChain = TrustChain<CheckoutStep, Map<String, String>>(
    strictMode = true,
    verifier = SignatureVerifier { payload, signatureBase64 ->
        // Plug in your platform's Ed25519 / RSA / ECDSA verifier
        CryptoEngine.verify(serverPublicKey, payload, signatureBase64)
    },
    patcher = { step, patches, newHash ->
        step.copy(
            state = step.state + patches,
            hash = newHash
        )
    }
)

The Legitimate User Journey

As the user progresses through the checkout, every step returned by the server references the exact hash of the previous state:

// 1. User opens the Shopping Cart (Genesis block, previousHash = null)
val cartStep = server.startCheckout(sessionId)
clientChain = clientChain.reduce(ChainEvent.Push(cartStep)).getOrThrow()
// Active: Shopping Cart | Hash: h_c2c1a28598b8ad69

// 2. User confirms Shipping Address (Chained to Cart's hash)
val shippingStep = server.submitShipping(sessionId, "Baker St 221B")
clientChain = clientChain.reduce(ChainEvent.Push(shippingStep)).getOrThrow()
// Active: Shipping & Address | Hash: h_50bda3ba68cced0d | Prev: h_c2c1a28598b8ad69

// 3. User applies a 10% Promo Code (Signed DeltaBlock mutation)
val promoDelta = server.applyPromoCode(sessionId, "10%")
clientChain = clientChain.reduce(ChainEvent.ApplyDeltas(listOf(promoDelta))).getOrThrow()
// Active: Shipping & Address (Patched) | New Total: $1890 | New Hash: h_6471c5f0c53a644b

// 4. User proceeds to Payment (Chained to the patched Shipping hash)
val paymentStep = server.proceedToPayment(sessionId)
clientChain = clientChain.reduce(ChainEvent.Push(paymentStep)).getOrThrow()
// Active: Payment Authorization | Hash: h_6a6fd155e392f7ef

Simulating the Attack: Skipping Shipping

Now, let’s see what happens when an attacker loads the Cart (h_c2c1a28598b8ad69) and tries to jump straight to the paymentStep (bypassing shipping calculation):

var attackedChain = TrustChain<CheckoutStep, Map<String, String>>(strictMode = true)
attackedChain = attackedChain.reduce(ChainEvent.Push(cartStep)).getOrThrow()

// Attacker tries to force-push the Payment step directly onto the Cart
val attackResult = attackedChain.reduce(ChainEvent.Push(paymentStep))

attackResult.fold(
    onSuccess = {
        println("VULNERABILITY: Attack succeeded!")
    },
    onFailure = { error ->
        when (error) {
            is ChainError.HashMismatch -> {
                println("[!] BLOCKED BY TRUSTCHAIN: State machine integrity preserved.")
                println("    Expected parent: ${error.expected}, Actual: ${error.actual}")
            }
            is ChainError.SignatureVerificationFailed -> {
                println("[!] BLOCKED: Invalid server signature for block ${error.blockHash}")
            }
            else -> println("[!] Blocked: ${error.message}")
        }
    }
)

Console Output:

------------------------------------------------------
  Simulating Attack: Attacker tries to skip shipping  
------------------------------------------------------
Attacker has Cart loaded.
Attacker attempts to directly apply Payment step (bypassing Shipping)...
[!] BLOCKED BY TRUSTCHAIN: State machine integrity preserved.
Expected parent: h_c2c1a28598b8ad69, Actual: h_6471c5f0c53a644b

Because paymentStep expects its parent to be the patched shipping step (h_6471c5f0c53a644b), pushing it onto the cart (h_c2c1a28598b8ad69) triggers an immediate ChainError.HashMismatch. The state transition is rejected atomically.

Built for Developer Ergonomics

Security tools often fail because they make local development painful. Nobody wants to spin up a signing server just to preview a Compose Multiplatform screen or write a quick UI test.

That’s why TrustChain includes a strictMode flag:

strictMode = true (Default / Production): Enforces parent hash lineage on Push and Replace, verifies digital signatures via SignatureVerifier, and ensures BlockPatcher updates block hashes accurately.
strictMode = false (Previews / UI Prototyping): Bypasses cryptographic and lineage checks while keeping the exact same ChainEvent reducer API, allowing you to mock and jump between screens freely during development.

Where Does TrustChain Shine?

Server-Driven UI (SDUI): Guarantee that screens and dynamic patches pushed by the backend are rendered in the exact sequence intended by the server.
E-Commerce & Checkouts: Make it impossible to bypass delivery calculation, tax steps, or terms acceptance before payment.
Fintech & Banking: Enforce strict step ordering for wire transfers, credit limit increases, and multi-factor challenges.
KYC & Onboarding Funnels: Maintain a verifiable, tamper-proof progression through document capture and liveness checks.

Try It in Your Project

TrustChain is open-source under the Apache 2.0 License and published directly to Maven Central.

Check out the full source code, architecture docs, and the runnable CLI attack simulation on GitHub.

Telemetry: Shared Analytics and Crash Reporting in Kotlin Multiplatform

Fri, 09 Oct 2026 14:00:00 +0000

In a modern endurance car, every sensor talks to the same box. Tyre pressure, brake temperature, fuel flow, throttle trace. They all end up in one data stream that goes to the pit wall over a single radio link. The engineer on the wall doesn't care which supplier made the brake sensor. He cares that the channel is called BRAKE_TEMP_FL and that the number arrives every 100 milliseconds.

Swap a sensor, the channel name stays. That's the whole point of the standard.

Analytics and crash reporting in a KMP app should work the same way. The sensors are the SDKs, one per platform, made by different teams with different APIs. The channel names are yours.

What I had before

My first KMP app logged analytics twice. Once in Kotlin for Android, once in Swift for iOS. Same events, same names, in theory.

In practice, the Android side sent screen_view with a screen_name parameter. The iOS side sent screenView with screenName. Nobody noticed for six weeks, until I tried to build a funnel in the dashboard and half the users were missing from it. The numbers weren't wrong. They were split across two event names that meant the same thing.

That's the real cost of leaving telemetry in the platform layer. Not the duplicated code, which is small. The drift. Two implementations of the same contract, with no compiler checking that they agree.

If you read Change the Map, this is the same move applied to a different problem: the contract lives in commonMain, the SDKs sit underneath. It also pairs with flags directly, because the first event worth logging is which variant a user was actually shown.

Crash reporting has a quieter version of the same problem. A Kotlin exception that crashes the Android app shows up in Crashlytics with a readable stack trace. The same exception on iOS arrives as a native crash with frames that look like kfun:..., and the Kotlin type is buried in the message. I'll get to that.

The interface lives in commonMain

The fix is to stop treating analytics as a platform feature and start treating it as a domain contract.

// commonMain
interface Analytics {
    fun track(event: AnalyticsEvent)
    fun setUserId(id: String?)
}

sealed interface AnalyticsEvent {
    val name: String
    val params: Map<String, String>

    data class ScreenView(val screen: String) : AnalyticsEvent {
        override val name = "screen_view"
        override val params = mapOf("screen_name" to screen)
    }

    data class Purchase(val sku: String, val amountCents: Long) : AnalyticsEvent {
        override val name = "purchase"
        override val params = mapOf(
            "sku" to sku,
            "amount_cents" to amountCents.toString(),
        )
    }
}

A sealed interface for events is the part that pays for itself. The event name and the parameter keys exist in exactly one place. A new event is a new class, and the compiler tells every when that cares about it. A typo in "screen_name" is no longer possible in two files, because it's only written once.

I keep params as Map<String, String> on purpose. Firebase, Mixpanel, and Amplitude all accept richer types, but they disagree about which ones. Strings are the lowest common denominator, and the conversion cost is trivial.

The crash side is a second, separate interface.

// commonMain
interface CrashReporter {
    fun log(message: String)
    fun recordNonFatal(throwable: Throwable)
    fun setUserId(id: String?)
}

Two interfaces, not one. Analytics is about what users did. Crash reporting is about what broke. They often go to different vendors, and you'll want to swap one without touching the other.

Android: the easy side

On Android the implementation is a thin wrapper. Firebase is the obvious choice, though nothing here is Firebase-specific.

// androidMain
class FirebaseAnalyticsImpl(
    private val firebase: FirebaseAnalytics,
) : Analytics {

    override fun track(event: AnalyticsEvent) {
        val bundle = Bundle().apply {
            event.params.forEach { (k, v) -> putString(k, v) }
        }
        firebase.logEvent(event.name, bundle)
    }

    override fun setUserId(id: String?) {
        firebase.setUserId(id)
    }
}

class CrashlyticsReporter(
    private val crashlytics: FirebaseCrashlytics,
) : CrashReporter {

    override fun log(message: String) = crashlytics.log(message)

    override fun recordNonFatal(throwable: Throwable) =
        crashlytics.recordException(throwable)

    override fun setUserId(id: String?) {
        crashlytics.setUserId(id.orEmpty())
    }
}

Nothing clever. If the Android side is the only one you ever shipped, this is the code you already had.

iOS: the Swift bridge

The simplest iOS implementation doesn't call the Firebase iOS SDK from Kotlin at all. No expect/actual in this layer, no cinterop bindings, no CocoaPods dependency in the shared module.

The shared module defines the interface, and the iOS app passes in a Swift implementation at startup.

// iosApp
final class FirebaseAnalyticsBridge: Analytics {

    func track(event: AnalyticsEvent) {
        FirebaseAnalytics.Analytics.logEvent(event.name, parameters: event.params)
    }

    func setUserId(id: String?) {
        FirebaseAnalytics.Analytics.setUserID(id)
    }
}

Swift sees the Kotlin interface as a protocol, so conforming to it is ordinary Swift. The one snag is the name: Firebase's Swift class is also called Analytics, so inside this file the bare name is ambiguous. I qualify the Firebase one with its module. Renaming the Kotlin interface would also work, but I'd rather not let a vendor pick my names. The app registers it with the DI container before the first screen renders.

// commonMain/Telemetry.kt
fun setUpTelemetry(analytics: Analytics, crashReporter: CrashReporter) {
    // register both in your DI graph of choice
}

// iosApp
@main
struct IosApp: App {
    init() {
        TelemetryKt.setUpTelemetry(
            analytics: FirebaseAnalyticsBridge(),
            crashReporter: CrashlyticsBridge()
        )
    }
    // ...
}

I don't start that function name with init. The Objective-C export reserves init for initializers, so a Kotlin function called initTelemetry shows up in Swift as doInitTelemetry. It works, but it's the kind of thing that costs ten minutes the first time you see it.

The Firebase SDK stays where Xcode manages it. The shared module never learns it exists.

Two other ways to bring the SDK in

That Swift bridge is how I wrote this in my first KMP apps, and it's the version I'd explain to anyone starting out because every moving part is visible. It isn't what I use today.

GitLive's Firebase Kotlin SDK. firebase-kotlin-sdk from GitLive wraps Firebase so you can call it from commonMain. I haven't shipped it myself. If you use it, your Analytics interface still sits in front of it, otherwise you've just moved the vendor lock-in into shared code.

CocoaPods through Gradle, with the call in iosMain. This is what I use now. The Kotlin CocoaPods plugin lets the shared module declare the Firebase pod itself, and Kotlin generates the bindings so iosMain can call the iOS SDK directly.

// build.gradle.kts (shared module)
plugins {
    kotlin("multiplatform")
    kotlin("native.cocoapods")
}

kotlin {
    cocoapods {
        version = "1.0"
        ios.deploymentTarget = "16.0"
        pod("FirebaseAnalytics")
        pod("FirebaseCrashlytics")
    }
}

You can pin a version with pod("FirebaseAnalytics", "~> 12.0"), and linkOnly = true exists for pods you only need to link and not bind. The Kotlin docs cover both.

Then the iOS implementation is Kotlin, in the same module as the interface.

// iosMain
import cocoapods.FirebaseAnalytics.FIRAnalytics
import kotlinx.cinterop.ExperimentalForeignApi

@OptIn(ExperimentalForeignApi::class)
class IosAnalytics : Analytics {

    @Suppress("UNCHECKED_CAST")
    override fun track(event: AnalyticsEvent) {
        FIRAnalytics.logEventWithName(event.name, event.params as Map<Any?, *>)
    }

    override fun setUserId(id: String?) {
        FIRAnalytics.setUserID(id)
    }
}

The bindings come from the Objective-C headers, not the Swift API, so the class is FIRAnalytics and the method is logEventWithName. The parameters dictionary arrives as Map<Any?, *>?. A Map<String, String> doesn't fit that type as-is, because map keys are invariant in Kotlin, hence the cast.

I switched because the Swift bridge had a cost I only noticed over time: two files per interface, in two languages, in two repos' worth of mental context. With the pod declared in Gradle, the iOS implementation sits next to the Android one, in Kotlin, and a new method on Analytics fails the build in the same module.

It has its own cost. Pod dependencies and cinterop bindings are now part of your shared module's build, so Gradle sync and iOS builds feel it, and a Firebase SDK bump can break the generated bindings. It's also the option with an expiry date: the Kotlin docs now carry a CocoaPods-to-SwiftPM migration guide, and the new swiftPMDependencies { } block replaces cocoapods { }. The docs I read put the minimum Kotlin Gradle plugin at 2.4.20-RC3 for it, so check your version before planning the move. That's the trade I accept for keeping everything telemetry-related in one language.

I'm showing three options on purpose, and Firebase is only the example. A KMP project has more than one way to bring a native dependency in: a bridge the app injects, a KMP wrapper library, or a native dependency declared in Gradle. Which one fits depends on how much of the native SDK surface you need, and who maintains the glue.

Kotlin exceptions on iOS are not Kotlin exceptions

This is the part nobody mentions until you're staring at a dashboard.

When an uncaught Kotlin exception terminates the app on iOS, the crash is reported by the native crash handler. The stack trace is the native one. The Kotlin frames are there, but unsymbolicated Kotlin frames read as noise, and the exception type is flattened. Touchlab's CrashKiOS exists for exactly this: it sends symbolicated Kotlin crashes and handled exceptions to Crashlytics, with breadcrumbs and custom keys. Its docs page was last updated in January 2024, so check the repo for recent activity before you rely on it.

For non-fatal errors you have a better option. Catch the exception at a boundary you control, and hand it to recordNonFatal. On iOS that means converting it to an NSError, and that's where it gets fiddly.

Swift can't get much out of a KotlinThrowable by itself. The Kotlin stack trace accessor on Native, getStackTrace(), is a stdlib extension marked @ExperimentalNativeApi, so I don't count on it being reachable from Swift. I let Kotlin do the work instead, with two small extensions in iosMain.

// iosMain
fun Throwable.kotlinTypeName(): String =
    this::class.qualifiedName ?: "UnknownKotlinThrowable"

fun Throwable.kotlinStackTrace(): String = stackTraceToString()

They extend a Kotlin class, so the export turns them into methods on KotlinThrowable and Swift calls them like any other method.

// iosApp
final class CrashlyticsBridge: CrashReporter {

    func recordNonFatal(throwable: KotlinThrowable) {
        let error = NSError(
            domain: throwable.kotlinTypeName(),
            code: 0,
            userInfo: [
                NSLocalizedDescriptionKey: throwable.message ?? "unknown",
                "kotlin_stacktrace": throwable.kotlinStackTrace(),
            ]
        )
        Crashlytics.crashlytics().record(error: error)
    }

    func log(message: String) {
        Crashlytics.crashlytics().log(message)
    }

    func setUserId(id: String?) {
        Crashlytics.crashlytics().setUserID(id ?? "")
    }
}

Crashlytics turns userInfo into key-value pairs in the keys section of the issue, so the full Kotlin trace sits right there. I put it there on purpose rather than hoping the dashboard parses the message, because it won't.

The domain choice matters more than it looks. For fatal crashes Crashlytics groups by stack trace, but the Firebase docs say logged errors are grouped by domain and code. A fixed domain like "kotlin" with code 0 would collapse every non-fatal into one issue. With the Kotlin type there, an IllegalStateException and a network timeout stay separate. Keep unique values like user IDs or timestamps out of both fields, or you'll fragment the dashboard the other way. Crashlytics also only stores the most recent eight exceptions in a session, so recordNonFatal is not a log.

Where the calls go

The interface is only worth having if people use it in the same place. I let ViewModels own analytics events and nothing else.

// commonMain
class CheckoutViewModel(
    private val analytics: Analytics,
    private val crashReporter: CrashReporter,
    private val repository: CheckoutRepository,
) : ViewModel() {

    fun onPay(sku: String, amountCents: Long) {
        viewModelScope.launch {
            runCatching { repository.pay(sku, amountCents) }
                .onSuccess {
                    analytics.track(AnalyticsEvent.Purchase(sku, amountCents))
                }
                .onFailure {
                    if (it is CancellationException) throw it
                    crashReporter.recordNonFatal(it)
                }
        }
    }
}

The CancellationException check is there because runCatching catches it too. Without it, every user who leaves the screen mid-payment becomes a non-fatal in Crashlytics.

Composables and SwiftUI views don't call track. Screen views are the exception, and I fire them from a single navigation observer, so there's one line of code that produces every screen_view in the app.

The other benefit shows up in tests. A FakeAnalytics that stores events in a list takes ten lines, and asserting on it in commonTest is trivial. I used to skip testing analytics because it meant mocking an SDK. Now I assert that tapping Pay produces exactly one Purchase with the right amount, and it runs on every target.

Gotchas

Don't init the SDKs inside commonMain, whichever option you pick. Firebase on Android wants a Context. On iOS it wants FirebaseApp.configure() before anything else touches it. Those calls belong in Application.onCreate and the iOS App.init, not behind an abstraction that pretends the platforms are the same.

User IDs are a privacy decision, not a plumbing one. setUserId is easy to wire and easy to get wrong. I pass an internal opaque ID and never an email. Deciding that once, in the interface docs, beats hoping every caller remembers.

Consent has to be a gate, not a flag. If your users can opt out, wrap the implementation, not the call sites. A ConsentAwareAnalytics decorator that drops events when consent is off keeps the rule in one class. Crash reporting is different. setCrashlyticsCollectionEnabled can be called at runtime, but the Firebase docs say the override applies from the next launch, so a user who opts out mid-session is still reporting until the app restarts. Say that in your consent screen.

A debug build should not talk to production. I give the debug variant a LoggingAnalytics that prints to the console. It's another implementation of the same interface, which is the quiet argument for having the interface at all.

Wrapping up

Treat telemetry as a contract you own and a set of sensors you rent. The event names, the parameter keys, and the rule for what counts as a non-fatal live in commonMain, in code your compiler can check. The SDKs sit underneath, one per platform, and nobody outside the platform layer should know which ones.

I would still start with the interface even if the app only ships on one platform today. Adding iOS later then costs one Swift file instead of an audit of every event.

Same channel names, whatever the sensor. 🏁

The KMP Bits app is available on App Store and Google Play — built entirely with KMP.

Minimum Weight: Code Coverage Gates in Kotlin Multiplatform with Kover

Wed, 23 Sep 2026 09:00:00 +0000

After a GT race, every car rolls onto the weighbridge before parc fermé. It has to clear a minimum weight, set before the season and revised only upward as the series collects more data on what's fair. A car that comes in light gets disqualified, no matter how well it drove. Teams don't get to argue the number down when it's inconvenient. They add ballast, or they find grip somewhere else.

I think about that weighbridge every time I look at a coverage report.

A percentage on its own tells you almost nothing. Ninety percent coverage on a module full of generated code and empty getters is worse than sixty percent on a module where every line was actually exercised by a test that would fail if you broke something. I found this out the annoying way, wiring Kover into a project with close to twenty modules: the number moved, but it wasn't telling me the truth.

The number was lying before it was useful

The first pass was simple. Apply the Kover plugin, point it at every module, generate a report. The merged number came out somewhere in the low sixties. Respectable enough on paper, wrong in a way that mattered.

Domain modules with almost no real logic were sitting near the top of the report, and it wasn't because they were well tested. It was because a dependency injection library had generated a pile of factory classes and graph interfaces that every counted line inflated the denominator on, without a single one of them ever being able to fail a test. Compose @Preview functions did the same thing in the other direction: pure decoration, zero tests, dragging modules with real logic down next to modules that had none.

You can't set a meaningful floor on a number built like that. So before the floor came the exclude list, and before the exclude list came trusting the report at all.

Coverage across more than one module

A single-module Android app can get away with Kover's defaults: apply the plugin, run koverHtmlReport, done. A multi-module KMP project can't, for two reasons.

First, most modules don't need coverage measured at all. Pure API modules, thin platform-wrapper modules, anything with no meaningful branches, don't need a plugin dragging a bytecode instrumentation step into every build. Second, the number you actually care about is the merged one across every module that does carry logic, not twenty separate reports you have to average in your head.

The way I did was creating a convention plugin that applies Kover to a module and defines the excludes, plus a root-level aggregation that pulls the modules worth measuring into one merged report.

// build-logic/convention/src/main/kotlin/KoverConventionPlugin.kt
class KoverConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            val libs = the<LibrariesForLibs>()
            pluginManager.apply(libs.plugins.kover.get().pluginId)

            extensions.configure<KoverProjectExtension> {
                reports {
                    filters {
                        excludes {
                            classes(
                                // DI-generated factories and contribution classes.
                                "*\$Factory*",
                                "*\$ContributionToAppScope*",
                                // Compose-compiler-generated lambda holders, no logic of their own.
                                "*ComposableSingletons*",
                                "*Previews",
                                "*PreviewsKt",
                                // Generated resource accessors.
                                "*.generated.resources.*",
                                // Pure DI wiring: every class under a `.di.` package here
                                // is graph construction, nothing to unit test.
                                "*.di.*",
                            )
                        }
                    }
                }
            }
        }
    }
}

Any module with tests worth counting applies this plugin instead of wiring Kover from scratch:

// core/network/build.gradle.kts
plugins {
    id("template.kover")
    // ...other convention plugins
}

The root project then declares which modules feed the merged report, and repeats the same excludes so the merged view and each module's own view agree with each other:

// build.gradle.kts (root)
plugins {
    alias(libs.plugins.kover)
}

dependencies {
    // Only modules with real tests are listed here. A module with nothing
    // to measure doesn't need to show up in the merged number at all.
    kover(project(":core:common"))
    kover(project(":core:network"))
    kover(project(":core:database"))
    kover(project(":feature:auth:domain"))
    kover(project(":feature:auth:data"))
    kover(project(":feature:profile:presentation"))
}

kover {
    reports {
        filters {
            excludes {
                // Keep in sync with KoverConventionPlugin's excludes.
                classes(
                    "*\$Factory*",
                    "*\$ContributionToAppScope*",
                    "*ComposableSingletons*",
                    "*Previews",
                    "*PreviewsKt",
                    "*.generated.resources.*",
                    "*.di.*",
                )
            }
        }
    }
}

That "keep in sync" comment is doing real work. Kover reads excludes from wherever the report is generated. Exclude a class in the convention plugin but forget the same line in the root aggregation, and the merged report counts it again, quietly, and your floor starts failing for a reason that has nothing to do with a real regression.

Excluding the honest way

The instinct when a module reads 0% is to exclude your way to a better number. That's the wrong direction to pull. The right question for anything you're about to exclude is: could a test on this class ever fail for a real reason? If yes, it stays in the count, even if writing that test is annoying. If no, excluding it isn't gaming the number, it's correcting a measurement error.

Generated database entities and query classes are the clearest case. A SQLDelight-generated UserEntityQueries class has no branches a test could meaningfully assert on beyond "does the generated SQL run," which your actual repository tests already cover indirectly.

excludes {
    classes(
        "com.example.app.core.database.UserEntity",
        "com.example.app.core.database.UserEntityQueries",
        "com.example.app.core.database.UserEntityQueries\$*",
    )
}

The exclude list will grow every time you add a code generator. A new annotation processor, a new resource pipeline, a new DI library migration, each one leaves generated classes in its wake that need the same treatment. Treat additions to this list the same way you'd treat additions to .gitignore: expected maintenance, not a sign something's wrong.

The floor that only goes up

Once the report was honest, setting a floor was the easy part.

kover {
    reports {
        verify {
            rule {
                // Baseline was ~64% after excluding generated code.
                // Raised to 68% once core/network got real coverage.
                // Raised to 75% after the auth data layer got tests
                // for its *RepositoryImpl classes.
                // Never lower this to make a failing build pass.
                minBound(75)
            }
        }
    }
}

koverVerify fails the build if merged line coverage drops below that number. The number itself is a ratchet, not a target. Every time real tests push the baseline up, the floor moves up behind it, a couple of points below the current baseline so unrelated refactors don't fail the build on noise. It never moves down. If a change makes coverage drop, the fix is to write the missing tests, not to edit the floor.

That's the whole point of the weighbridge analogy holding up under pressure. A minimum weight limit that teams could talk their way under whenever it was inconvenient wouldn't be a rule, it would be a suggestion. Same with a coverage floor you lower the first time it's in your way.

Wiring it into CI

Locally, koverVerify runs alongside koverHtmlReport and koverXmlReport as part of the same pre-merge check that runs Detekt (covered in The White Lines). Coverage belongs in the same slot: a gate that runs before a PR is allowed to merge, not a report someone checks manually once a month.

If your KMP project already has a GitHub Actions workflow running unit tests on every pull request, adding a coverage gate is one more step, not a new pipeline:

# .github/workflows/tests.yml
name: Unit Tests
on:
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
          cache: 'gradle'

      - name: Run unit tests
        run: ./gradlew testDebugUnitTest --max-workers=2

      - name: Enforce coverage floor
        run: ./gradlew koverXmlReport koverVerify

      - name: Upload coverage report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: kover-report
          path: build/reports/kover/

koverVerify fails the job the same way a failing test does, so there's no extra branching logic to write. The XML report is worth generating even if nothing downstream reads it yet: it's the format most coverage-badge and PR-annotation tools expect, and generating it costs nothing extra once koverXmlReport is already in the command.

One gotcha if you're running this on Android modules with Robolectric tests: those tests are memory-hungry, and Kover's instrumentation adds overhead on top. If the job runs out of memory before it gets anywhere near reporting a real coverage number, raise the runner's heap before you start suspecting the plugin:

env:
  GRADLE_OPTS: -Dorg.gradle.jvmargs="-Xmx4g -XX:MaxMetaspaceSize=1g"

The line I hold

A coverage percentage nobody enforces is decoration. It sits at the top of a README, it looks fine in a badge, and it means nothing because there's no consequence when it drops. The moment koverVerify runs on every pull request and fails the build, the number stops being decoration and starts being a rule the team actually has to answer to.

I'd rather have a floor at seventy-five that only goes up than a badge that says ninety and hasn't been checked since the module was scaffolded.

Everyone crosses the weighbridge. Nobody gets to argue the number down. 🏁

Same Car, Every Time: Deterministic Feature Module Generation in KMP

Tue, 15 Sep 2026 14:00:00 +0000

Walk down the pit lane at a Porsche Cup weekend and every garage holds the same car. Same chassis from the same jig, same engine sealed by the same people, same tolerances checked against the same sheet. Nobody on that grid gets to be creative about the monocoque. It isn't a lack of ambition, it's the entire point: when thirty cars are identical, a tenth of a second means something. You learn from the difference because the baseline never moves.

A Formula 1 grid gives you brilliant engineering and twenty-two cars where no two problems have the same cause. Both are real forms of racing. They answer different questions.

Feature modules are a spec series. I want every one of mine built to the same jig, so that when a module behaves oddly I know it's the code I wrote and not the scaffold it arrived in. It took me a while, and one AI-generated codebase, to work out that I'd been running Formula 1.

A while back I wrote about custom Gemini commands in Android Studio, and the one I used most was the one that created KMP feature modules. The argument was simple: write down what your project looks like once, stop explaining it from scratch every time. I still believe that. The command file worked.

Then I went back and read three features I'd generated over about two months.

One had implementation(project(":feature:x:domain")) inside commonMain.dependencies. One had it at the top level of the kotlin block. One had it in both places, which somehow still compiled. The ViewModel in the oldest one extended a base class signature I'd changed since. The package for a hyphenated feature name had come out as user-profile in one file and user_profile in the rest, so that module simply didn't build until I fixed it by hand.

None of these were dramatic failures. Every single one was a five minute fix. But five minutes times four files times every feature is exactly the interruption I built the command to avoid, and now I was paying it at review time instead of at creation time, which is worse, because at review time I've already stopped thinking about this feature.

So I stopped asking and wrote a bash script.

The thing I actually wanted was not intelligence

Here's the part that took me embarrassingly long to accept: for this specific job, the AI's greatest strength is the problem.

An AI generator reads your instructions, reads your codebase, and produces something reasonable. "Reasonable" is a range. It has to be, because the model is inferring intent every time. Ask it twice and you get two points inside that range, both defensible, neither identical. That's exactly what you want when the task is genuinely novel and you can't specify it up front.

Scaffolding is not that task. Scaffolding is the opposite of that task. I know precisely what the output should be, down to the import order, because I wrote the module it's copying. There is nothing to infer. Every degree of freedom the model has is a degree of freedom I didn't ask for.

What I wanted was a fixed baseline. Not better output, identical output, so that any difference between two modules is information rather than noise.

Which raises the fair question of why bash, when a Gradle plugin or an IntelliJ file template would also be deterministic. Both were on the table. The template lost because it stops at files: it can't append to settings.gradle.kts or splice a route into an existing sealed interface, which is most of what makes a new module actually usable. The Gradle plugin lost on cost. It's the better answer if you're handing this to a team of fifteen, but it's a build-logic module to maintain and a Gradle build to re-run to test a change, whereas the script is one file I can read top to bottom and edit in place. If the thing ever outgrows bash I'll port it. It hasn't.

What the script generates

scripts/new-feature.sh takes a kebab-case feature name and produces up to three Gradle modules under feature/<name>/: domain, data, presentation. It mirrors the smallest real feature in the project, so the output isn't an idea of what my modules look like, it's a copy of one that already ships.

./scripts/new-feature.sh wishlist

That gives you:

feature/wishlist/domain with a WishlistRepository interface
feature/wishlist/data with WishlistRepositoryImpl, bound through Metro
feature/wishlist/presentation with WishlistState, WishlistEvent, WishlistAction, WishlistNavigator, WishlistViewModel, WishlistScreen, plus a WishlistGraph and WishlistGraphNavigator under navigation/
three include(...) lines appended to settings.gradle.kts
a NavigationRouter.Wishlist.Main route spliced into NavigationRouter.kt

It compiles and runs immediately. The screen is a PlaceholderScreen inside a ScaffoldScreen, the repository interface is empty, and the state holds a single Unit field so the data class is valid. Nothing pretends to be finished.

A note on the code you're about to read: this is my script, shaped around my project. The paths, the package com.example.template, Metro for DI, Navigation 3, StateViewModel and BaseState from my core/ui module, the template.* convention plugins. Dropped into your codebase as-is it won't generate anything that compiles, and that's expected rather than a problem. The value of a generator like this comes from it knowing your conventions, so the interesting part is the structure, not the contents. If you're on Koin instead of Metro, or MVI instead of this MVVM split, or one module per feature instead of three, the shape of the script stays and every heredoc inside it becomes yours. Treat what follows as a worked example to adapt.

The name handling is the first thing that stops being a per-feature annoyance:

# kebab-case -> snake_case (Kotlin package segment) and PascalCase (class name prefix)
SNAKE="${KEBAB//-/_}"
PASCAL=""
IFS='-' read -ra WORDS <<< "$KEBAB"
for word in "${WORDS[@]}"; do
  first_upper="$(printf '%s' "${word:0:1}" | tr '[:lower:]' '[:upper:]')"
  PASCAL="${PASCAL}${first_upper}${word:1}"
done

user-profile becomes the folder user-profile, the package segment user_profile, and the class prefix UserProfile. Three forms of the same name, derived once, used everywhere. This is the exact transformation an AI gets right most of the time. "Most of the time" is what shipped me a module that didn't build.

Guardrails come before generation

The script writes into feature/, appends to settings.gradle.kts, and rewrites NavigationRouter.kt in place. Something that edits tracked files without asking should be paranoid about it, so nothing gets written until three checks pass. Two are obvious: the name has to match ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, and feature/$KEBAB must not already exist. The third is the one I care about:

if [[ -n "$(git status --porcelain)" ]]; then
  echo "Warning: you have uncommitted changes. This script edits settings.gradle.kts and"
  echo "NavigationRouter.kt in place, and creates new files under feature/$KEBAB."
  read -r -p "Continue anyway? [y/N] " confirm
  [[ "$confirm" =~ ^[Yy]$ ]] || exit 1
fi

With a clean tree, git diff after the run is a complete, readable record of everything the script touched. With a dirty tree, the generated changes are tangled up with yours and you lose the cheapest verification you have. The script can't force a clean tree, but it can make you type y and think about it for a second.

set -euo pipefail sits at the top, so anything unexpected stops the run rather than leaving half a feature on disk.

Then I needed one module, not three

I wanted a domain and data pair with no UI. A feature that exposes a repository, consumed by an existing screen somewhere else. The script had exactly one mode: all three modules, every time.

The obvious move, if you're used to AI generation, is to go back and describe the exception. "Same as before, but skip presentation." And that works. It works right now, on the first try, which is precisely why it's a trap. Because next month I want domain alone, and the month after I want data and presentation with the domain contract living in a shared module, and each of those is a fresh description of an exception to a structure that nobody has actually written down. Every exception is a new chance for the output to drift from the last one.

Rigidity was the whole reason I wrote the script. The answer isn't to soften it, it's to make the flexibility part of the spec.

# Usage: ./scripts/new-feature.sh <feature-name> [--modules <module> [<module> ...]]
./scripts/new-feature.sh wishlist                    # domain + data + presentation
./scripts/new-feature.sh wishlist --modules domain data

Three booleans default to true, and --modules flips them all off and turns back on only what you named:

GEN_DOMAIN=false
GEN_DATA=false
GEN_PRES=false

for module in "${MODULES[@]}"; do
  case "$module" in
    domain) GEN_DOMAIN=true ;;
    data) GEN_DATA=true ;;
    presentation) GEN_PRES=true ;;
    *)
      echo "Error: unknown module '$module'. Must be one of: domain, data, presentation." >&2
      exit 1
      ;;
  esac
done

The flag accepts at most two names, deliberately. --modules domain data presentation is already the default, and offering two ways to say the same thing is how flags start rotting. If you want all three, don't pass the flag.

That cap has a hole you only find by running your own tool wrong: --modules domain domain has a length of two, passes the count check, and sets one boolean. Comparing how many booleans ended up true against how many names were typed catches it in three lines. Small thing, and the sort of edge case no amount of prompting reliably covers, because you'd have to think of it in advance to ask for it — and once you've thought of it you may as well encode it.

Notice what this is: a flag with a validated, closed set of values. The flexibility is real and it's bounded. Every combination that's allowed is a combination I decided was allowed, and the ones I didn't decide on fail loudly at argument parsing rather than quietly at compile time.

Conditionals are where the real work is

Adding the flag was twenty minutes. Making the generated code correct for each combination was the rest of the afternoon, and this is the part I think matters most.

If you generate data without domain, the data module's build.gradle.kts must not depend on a domain module that doesn't exist. Neither branch is clever, and that's the point:

if $GEN_DOMAIN; then
  cat > "feature/$KEBAB/data/build.gradle.kts" <<EOF
import com.android.build.api.dsl.LibraryExtension

plugins {
    alias(libs.plugins.template.data)
}

extensions.configure<LibraryExtension>("android") {
    namespace = "com.example.template.feature.$SNAKE.data"
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(project(":feature:$KEBAB:domain"))
        }
    }
}
EOF

and the else branch is the same file with the whole kotlin { } block gone.

Those alias(libs.plugins.template.data) lines are convention plugins from my build-logic module. Each layer gets one plugin ID, and everything else, targets, compiler options, common dependencies, lives centrally. It's the same setup I mentioned in the Gemini article. Worth noting here because it's part of why the generated Gradle files are short enough to template safely: there's very little per-module configuration left to get wrong.

The second consequence is more interesting. Without a domain module, there is no WishlistRepository, so WishlistRepositoryImpl has nothing to implement and nothing to bind. The script doesn't generate a degraded version of it. It doesn't generate it at all, and it tells you why:

echo "Note: domain not generated — feature/$KEBAB/data has no ${PASCAL}RepositoryImpl" \
  "(it would need ${PASCAL}Repository from the domain module)."

That line took a couple of iterations to get right and I'd argue it's the most valuable output the script produces. A generator that silently omits things trains you to distrust it. A generator that says "I left this out, here's the reason" is a tool you can stop checking. The absence is intentional and documented at the moment it happens, in the terminal, while you're still looking.

Same story for the route registration. NavigationRouter.Wishlist.Main only exists to be referenced by WishlistGraph, which lives in the presentation module. No presentation, no route:

if $GEN_PRES; then
  ROUTER_FILE="core/ui/src/commonMain/kotlin/com/example/template/core/ui/navigation/NavigationRouter.kt"
  # ... splice the route in
fi

Three modules, generated or not, gives eight combinations if you count naively, six that the argument parser actually allows. Every one produces code that compiles. That's the property I was buying, and it's a property you can verify by running the thing six times, which is not something you can meaningfully do with a prompt.

The one clever bit, and its escape hatch

NavigationRouter.kt is a sealed interface hierarchy, and new routes go in as nested data object declarations before the final closing brace. There's no marker comment, no anchor, just a } on its own line at the end of the file.

LAST_BRACE_LINE=$(grep -n '^}$' "$ROUTER_FILE" | tail -1 | cut -d: -f1)

Find every line that is exactly a closing brace, take the last one, extract the line number. Then rebuild the file in three pieces:

{
  head -n "$((LAST_BRACE_LINE - 1))" "$ROUTER_FILE"
  cat <<EOF

    @Serializable
    data object $PASCAL : NavigationRouter {
        @Serializable
        data object Main : NavigationRouter
    }
EOF
  tail -n "+$LAST_BRACE_LINE" "$ROUTER_FILE"
} > "$ROUTER_FILE.tmp"
mv "$ROUTER_FILE.tmp" "$ROUTER_FILE"

Everything before the brace, the new block, then the brace and anything after it. Written to a temp file and moved into place, so a failure halfway through leaves the original intact rather than truncated.

I'm aware this is line-based surgery on Kotlin source, and that it depends on a formatting convention holding. Which is why the fallback exists:

if [[ -z "$LAST_BRACE_LINE" ]]; then
  echo "Warning: couldn't find NavigationRouter.kt's closing brace — add the route manually:"
  echo "    @Serializable"
  echo "    data object $PASCAL : NavigationRouter {"
  echo "        @Serializable"
  echo "        data object Main : NavigationRouter"
  echo "    }"

If the assumption breaks, the script says so and prints exactly what you need to paste. It does not guess at an alternative insertion point. A generator that fails visibly and hands you the fix costs you thirty seconds. A generator that improvises when its assumptions break costs you a debugging session, and you won't know to start one, because it looked like it worked.

What it deliberately refuses to do

Two things the script will not touch, and both refusals are in the header comment so I can't quietly forget them.

It won't wire WishlistGraph into anything. A new feature can live in a bottom nav tab, behind a settings row, in a shared overlay, or somewhere I haven't invented yet, and that is an architecture decision with consequences. A generator making it for me is a generator making an architecture decision I didn't review.

It won't write domain logic. WishlistRepository is an empty interface with a comment telling you to define the contract. That's the actual work. The script's job was to clear a path to it.

So the run ends with a list rather than a claim of completion:

Still manual:
  - Wire WishlistGraph(onNavigation = ...) into wherever this feature actually lives
  - Fill in WishlistRepository / WishlistRepositoryImpl with real logic.
  - Run './gradlew :feature:wishlist:domain:detekt ...' (or just commit — the pre-commit hook covers it).

Building the detekt task list from the same booleans is a two-line addition, and it means the command you're told to run is always the right one for what was actually generated.

When I still reach for the AI

I want to be clear that I didn't replace one tool with a better one. I split one job into two jobs.

The script handles the part I've done forty times and will do forty more, where I know the answer and want it applied identically every time. The AI handles everything after that: the domain logic, the state modelling for a screen that doesn't resemble any other screen, the migration that touches nine files in ways I can't specify up front. That's genuinely novel work, and the ability to infer intent from a loose description is exactly what makes it useful there.

There's also a nice side effect. The AI is now working inside a codebase where every feature module has the same shape, because the shape came from a script rather than from six separate acts of interpretation. Consistent context produces better output. The rigid tool makes the flexible one work better.

A rough test I use now: if I'm about to write a prompt for the third time and it's substantially the same prompt, that's not a prompt, that's a script I haven't written yet. And if the script needs to handle a case it doesn't, the fix is a flag with a validated set of values, not a paragraph of natural language explaining the exception.

Wrapping up

The Gemini article's conclusion was that you should write down what your project looks like once. This one is the next step: for the things you do constantly, write down how as well, in something that executes rather than interprets. Not my how. Yours, with your package name and your base classes and your DI framework, which is an afternoon of work and the reason the thing is worth anything at all.

--modules is the whole argument in miniature. I needed the generator to do something it couldn't do. I could have described the exception to a model in about fifteen seconds, and I'd have described it again, slightly differently, every time since. Instead I spent an afternoon making the exception a first-class, validated, six-combinations-all-of-which-compile part of the tool. Now nobody describes anything. You pass --modules domain data and you get the same two modules I got, and the same two I'll get in November.

Boring is the feature. Six months from now the newest module and the oldest one will still be the same shape, and that is worth more to me than a generator clever enough to surprise me.

Same jig, same tolerances, same car off the truck every race weekend. The lap time is where the interesting differences belong. 🏁

Two Racing Lines: Annotations and the DSL in NetFlow 0.7.0

Mon, 14 Sep 2026 08:00:00 +0000

I have been building NetFlow, my Kotlin Multiplatform networking library, since it was an Android-only thing called Communication. I wrote about that migration and why I took it on in Why I Took the Leap from Android-Only to Kotlin Multiplatform, so I will not repeat it here. Version 0.6 I added a transform parameter. The compiler forces you to provide whenever your DTO and your domain model are different types. Forget it and the build fails. No runtime surprise, no half-mapped object reaching the UI.

Then I started a new data layer in a side project, opened an empty file, and typed @GET.

Into my own library. Which did not have annotations.

That is a small, stupid moment, and it told me something I had been avoiding. NetFlow has three stars on GitHub and, as far as I know, no users outside my own projects, so I cannot tell you what evaluators said about it. I can tell you what my own hands did when I was not paying attention.

The reflex

Years of Retrofit built a motor pattern into every Android developer I know, including me. You want an endpoint, you write an interface, you put @GET("users/{id}") on a method. It is not a decision. It is closer to reaching for the indicator stalk.

Here is what fetching a list looked like in NetFlow 0.6:

// commonMain
val todos = client.call {
    path = "todos"
    method = HttpMethod.Get
}.responseListFlow<TodoDto, Todo>(transform = { it.toModel() })

Read that with fresh eyes. It says exactly what it does, it is one expression, and the mapping is compiler-checked. It is also nothing like what muscle memory reaches for.

A developer evaluating a networking library gives it about ninety seconds of README. In that window, "does this look like the thing I already know" beats "is this better" almost every time. I don't think that is laziness. Familiarity is a real cost saving when you are picking one of five libraries that all do roughly the same job.

So the 0.7.0 question was not "annotations or DSL". It was: can I put a familiar entry on the front without weakening the thing behind it?

What came out is a ladder with three rungs. The bottom rung is an annotated interface and covers most of what you write in a day. The middle rung annotates the request and hands the response back to you. The top rung is the DSL, unchanged, for the calls that need everything. You climb only as far as the call in front of you requires.

Rung one: the return type picks the strategy

The annotation layer lives in two new modules, netflow-annotations and netflow-ksp. You annotate an interface, KSP generates the implementation, and a factory extension hands it to you.

// commonMain
@NetFlowApi
interface TodoApi {

    @GET("todos")
    suspend fun getTodos(@Query completed: Boolean?): AsyncState<List<TodoDto>>

    @GET("todos/{id}")
    fun observeTodo(@Path id: Int): Flow<ResultState<TodoDto>>

    @Headers("Accept: application/json", "X-Client: netflow")
    @POST("todos")
    suspend fun create(@Body request: CreateTodoRequest): AsyncState<TodoDto>

    @DELETE("todos/{id}")
    suspend fun delete(@Path id: Int): AsyncState<Unit>

    @GET("todos")
    fun pagedTodos(): Flow<PagingData<TodoDto>>
}

val api = client.createTodoApi()

The part I want to point at is that there is no @Strategy annotation anywhere. The return type does that job.

AsyncState<T> on a suspend function means a one-shot call. Flow<ResultState<T>> on a non-suspend function means an observable call with loading and error states. Flow<PagingData<T>> means a Paging 3 flow. List<T> inside any of those routes to the list variants. The processor reads the shape and picks responseAsync, responseListAsync, responseFlow, responseListFlow, or responsePaginated accordingly.

This is not a clever trick, it is consistency. Flow<ResultState<T>> already self-describes in the hand-written DSL. Making the annotation layer read the same signal means there is one fact to learn instead of two.

The processor is strict about mismatches, and the errors are compile-time:

Function 'getTodos' returns AsyncState and must be suspend.
Function 'observeTodo' path declares '{id}' but there is no @Path parameter named 'id'.
Function 'create' has more than one @Body; at most one @Body is allowed.

@Path and @Query and @Header take their wire name from the parameter name unless you override it, a nullable @Query or @Header is omitted from the request when it is null, and at most one @Body is allowed per function.

What the processor actually writes

This matters more than it sounds, so here is the generated file for two of those methods, copied out of build/generated:

// _TodoApiImpl.kt, generated
internal class _TodoApiImpl(
  private val client: NetFlowClient,
) : TodoApi {
  override suspend fun getTodos(completed: Boolean?): AsyncState<List<TodoDto>> = client.call {
    method = HttpMethod.Get
    path = "todos"
    if (completed != null) parameter("completed" to completed)
  }
  .responseListAsync<TodoDto>()

  override fun observeTodo(id: Int): Flow<ResultState<TodoDto>> = client.call {
    method = HttpMethod.Get
    path = "todos/" + id
  }
  .responseFlow<TodoDto>()
}

public fun NetFlowClient.createTodoApi(): TodoApi = _TodoApiImpl(this)

That is the 0.6 DSL. Byte for byte, it's the code you would have written by hand. The annotations are not a parallel implementation, they are a text expansion into the existing one. Nothing new runs at runtime, there is no reflection, and there is no second code path to keep in sync when the DSL changes.

It also means you can open the file and read it.

The decision that matters: no transform in annotations

Now the constraint that shaped everything else.

An annotation cannot hold a lambda. Kotlin annotation parameters are limited to compile-time constants, so transform = { it.toModel() } has nowhere to live. Neither does onNetworkSuccess { db.insert(it) }, or local { observe { db.todos() } }, or a paging RemoteMediator.

The mapping problem has known workarounds and I looked at all of them. @MappedBy(TodoMapper::class) pointing at an object with a map function. A converter registry you populate at client construction. An interface the DTO implements. Every one of them takes a relationship the 0.6 compiler verifies and moves it somewhere the compiler cannot see, resolved by KSP at best and by a map lookup at worst. Forgetting a mapper would stop being a build error and start being a runtime cast exception on a device.

I was not going to make the convenience layer less safe than the thing it is a convenience for. So annotated methods return the DTO. Full stop.

The mapping moves one layer out, into the repository, using the .map helpers NetFlow already ships. Their KDoc has said the same thing since 0.1: usually used in the repository to map the dto to the model.

// commonMain
class TodoApiRepositoryImpl(client: NetFlowClient) {

    private val api = client.createTodoApi()

    suspend fun getTodos(): AsyncState<List<Todo>> =
        api.getTodos(completed = null).map { dtos -> dtos.map { it.toModel() } }

    fun observeTodo(id: Int): Flow<ResultState<Todo>> =
        api.observeTodo(id).map { state -> state.map { it.toModel() } }

    fun pagedTodos(): Flow<PagingData<Todo>> =
        api.pagedTodos().map { page -> page.map { it.toModel() } }
}

The mapping is still explicit, still typed, still checked by the compiler. It moved. It did not weaken.

If there is one transferable idea in this whole article, it's that one. When you build a convenience layer over a stricter API, the layer is allowed to be less capable. It's not allowed to be less safe. The moment it is, every user of the convenience layer is quietly worse off than the users who ignored it, and you have built a trap with good ergonomics.

The paged endpoint is one line

If there is a single place where this layering pays for itself, it's paging.

An annotation library that only speaks HTTP gets you as far as the DTO. After that you write a PagingSource: a load that does the key arithmetic, a getRefreshKey that reads state.anchorPosition and reaches for the closest page, a LoadResult branch for success and one for failure, then a Pager and a PagingConfig to assemble it. That is fifty lines you have written before, and fifty more for the next paged endpoint, because none of this is about your data.

In NetFlow you only need a PagingData return type.

// commonMain
@GET("todos")
fun pagedTodos(): Flow<PagingData<TodoDto>>

@Paginated(pageSize = 15)
@GET("todos")
fun pagedTodosSmall(): Flow<PagingData<TodoDto>>

@Paginated is optional, and it carries only the two things: the query parameter name for the page number, and the page size. Leave it off and you get page and 20.

The DTO extends PagingModel, which is where the page number and the last-updated timestamp live:

@Serializable
data class TodoDto(
    val userId: Int,
    val id: Int,
    val title: String,
    val completed: Boolean
) : PagingModel()

Forget it and the build stops with Flow<PagingData<T>> requires T to extend PagingModel. Put @Paginated on a method that returns something else and the build stops there too. Neither is a runtime discovery.

The repository maps exactly like every other annotated call, and the ViewModel does what it always does:

// commonMain
fun pagedTodos(): Flow<PagingData<Todo>> =
    api.pagedTodos().map { page -> page.map { it.toModel() } }

val todos = repository.pagedTodos().cachedIn(viewModelScope)

That flow is declared in commonMain, and this is the part with no Ktorfit equivalent at all. On Android you collect it with collectAsLazyPagingItems(). On iOS, netflow-paging ships PagingCollectionViewController, a Kotlin class exposing loadStateFlow, onPagesUpdatedFlow, getItems() and loadNextPage() to Swift through SKIE, so a SwiftUI list drives the same pager. One annotated method, both platforms, no per-platform paging code.

Now the boundary. An annotated paged method is network-only. The generated call says so:

// generated
.responsePaginated<TodoDto, TodoDto> {
  onlyApiCall = true
  defaultPageSize = 15
}

Remote plus local paging needs a PagingSource factory, an insertAll block, and a timestamp lambda. Three lambdas. So it stays where lambdas live, and getting there is the next rung.

Rung two: NetFlowCall

That leaves an obvious hole. What about an endpoint whose request is pure boilerplate, path and method and three query params, but whose response needs a local cache?

Under a strict reading of rung one you drop back to the full DSL and hand-write the request too, which means the annotation layer is useless for exactly the calls that have the most typing in them.

0.7.0 splits the call in half. An annotated method can return NetFlowCall, which is the request with no response strategy attached:

// commonMain
@GET("todos")
fun todosCall(): NetFlowCall

The generated implementation stops at the request:

// generated
override fun todosCall(): NetFlowCall = client.prepareCall {
  method = HttpMethod.Get
  path = "todos"
}

And the caller composes the response side with the whole DSL available, transform requirement included:

// commonMain
fun getTodos(): Flow<ResultState<List<Todo>>> =
    api.todosCall().responseListFlow<TodoDto, Todo>(transform = { it.toModel() }) {

        onNetworkSuccess { dtos ->
            database.todoQueries.transaction {
                dtos.forEach { database.todoQueries.insertTodo(it.toEntity()) }
            }
        }

        local(
            { observe { database.todoQueries.selectTodos() } },
            transform = { entities -> entities.map { it.toModel() } }
        )
    }

The annotation owns what annotations are good at: path, method, query parameters, headers, body. The repository owns what only a lambda can express.

Because the response strategy now belongs to the caller, @Wrapped on a NetFlowCall method is a compile error, with a message that says why:

Function 'todosCall' returns NetFlowCall — @Wrapped is the caller's
response-strategy choice, not the interface's.

@Paginated fails the same way, since it requires a Flow<PagingData<T>> return type it will never see. I would rather refuse the annotation than silently pick a strategy on someone's behalf.

prepareCall { } is public, so hand-written DSL users get the same split without touching annotations.

Rung three: the call {} DSL

The top rung is unchanged. Remote plus local paging, localQuery with its count and items and invalidation lambdas, retry policies with a retryOn predicate, per-request headers computed at call time, onlyLocalCall for offline reads. The paged call from two sections ago, with a database under it, looks like this:

// commonMain
@OptIn(ExperimentalPagingApi::class)
override fun getTodos(): Flow<PagingData<Todo>> = client.call {
    path = "todos"
}.responsePaginated<TodoDto, Todo> {
    localSource(
        pagingSource = { TodoPagingSource(database) },
        transform = { it.toModel() }
    )

    deleteOnRefresh = false
    insertAll(transform = { it.toEntity() }) { todos ->
        database.todoQueries.transaction {
            database.todoQueries.deleteTodos()
            todos.forEach { database.todoQueries.insertTodo(it) }
        }
    }

    firstItemDatabase(
        itemDatabase = { database.todoQueries.getFirstTodo().executeAsOneOrNull() },
        timestamp = { it.lastUpdatedTimestamp }
    )
}

There is no annotation on earth that expresses that, and I did not try to invent one. The top of the ladder is supposed to look like this.

Three rungs, or three libraries

The alternative to layering is what most projects already do. Ktorfit for the HTTP calls, Store or something hand-rolled for the cache, Paging wired up separately with its own RemoteMediator. It works. I have shipped it.

What it costs is coherence. Three libraries mean three sets of state types that don't compose, three failure models, and three test setups. Your Ktorfit call throws, your cache layer returns a sealed class, your paging layer emits LoadState, and the repository is the place where you write the glue that reconciles all of it. Then you write a MockEngine for one, a fake for another, and an in-memory database for the third.

In NetFlow the three rungs return the same ResultState, AsyncState, and PagingData types. They run on the same NetFlowClient. And they are tested with the same MockNetFlowClient, which intercepts requests without any network at all:

@Test
fun `delete removes item from local database`() = runTest {
    val mockClient = MockNetFlowClient { _ -> NetFlowMockResponse.success() }
    val repository = TodoRepositoryImpl(mockClient, database)

    repository.deleteTodo(id = 1)

    mockClient.assertCalled("todos/1", HttpMethod.Delete)
}

That test doesn't care which rung the repository used. Swap getTodos from an annotated method to a call {} block and the test still passes, because the boundary is the client, not the call style.

Now the honest part. If you just want to use annotations, Ktorfit beats this comfortably. It has years of production use, multipart and form-data, streaming, response converters, a much larger vocabulary, and a community that has already hit the bugs you are about to hit. NetFlow 0.7.0 has a first pass and a roadmap item that still says multipart. If HTTP is genuinely all you need, use Ktorfit.

The exception is the one I spent a whole section on. No annotation layer hands you a Flow<PagingData<T>> from commonMain, because that requires the paging integration to already be part of the same library. That is not me out-annotating Ktorfit, it's the stack underneath the annotations showing through, which is the only bet I am actually making.

Generating into commonMain with KSP

This is the part I found least documented, so here it is in full.

The processor emits one file per annotated interface into the common metadata source set, and every target then compiles that file as ordinary common code. On the consumer side it is four pieces of wiring:

// build.gradle.kts
plugins {
    alias(libs.plugins.ksp)
}

kotlin {
    sourceSets {
        commonMain {
            kotlin.srcDir("build/generated/ksp/metadata/commonMain/kotlin")
        }
        commonMain.dependencies {
            implementation("io.github.kmpbits:netflow-annotations:<latest_version>")
        }
    }
}

dependencies {
    add("kspCommonMainMetadata", "io.github.kmpbits:netflow-ksp:<latest_version>")
}

tasks.withType<KotlinCompilationTask<*>>().configureEach {
    if (name != "kspCommonMainKotlinMetadata") {
        dependsOn("kspCommonMainKotlinMetadata")
    }
}

The srcDir line and the dependsOn block are the two that bite. Without srcDir, the generated file exists on disk and no source set can see it. Without the task dependency, your Android compilation happily starts before KSP has produced anything, and you get an unresolved reference to createTodoApi that disappears on the second build. That intermittent-failure flavour is the worst kind to debug, which is exactly why it is worth ten lines of Gradle.

One detail worth mention: netflow-ksp has no dependency on netflow-paging. The processor emits responsePaginated as a fully qualified name string and lets the consumer's own classpath resolve it. If you never return Flow<PagingData<T>>, you never pull in Paging 3, and the annotation module stays a pure Kotlin Multiplatform artifact with no Android-flavoured transitive weight.

I picked KSP over a compiler plugin for one reason: the output is a plain .kt file you can open. When a generated call sends the wrong query parameter, you go look at the generated line and see it. A compiler plugin gives you IR, a stack trace, and a bad afternoon. Ktorfit itself ran on KSP for years and only moved to a compiler-plugin-only model after it had the user base to absorb that opacity. For a library at 0.7.0 with three stars, readable output is worth more than whatever the plugin route buys.

The line I hold

Adding a familiar surface to an unfamiliar API is not a compromise, as long as the surface refuses to lie about what is underneath it. Annotations in NetFlow do not wrap the DSL, they generate it, they return the same types, they run on the same client, they break at compile time when you ask them for something they cannot do, and they stop at the exact line where a lambda becomes necessary. That stopping point is the design, not a gap in it.

A layer that quietly did less checking so it could cover more cases would be a worse library with a better README.

This is 0.7.0, and the honest framing is that I have no external users yet. The annotation surface may well shift in 0.8 or 0.9 once somebody who is not me tries to model an API with it. Read the code samples here as 0.7.0, not as a promise.

But the shape I would defend regardless of version: put the familiar entry on the front, keep the harder API reachable from it without changing cars, and be loud about where one ends and the other begins.

Pit lane or full circuit, it is the same car. 🏁

The library is available on GitHub.

Building High-Performance Text Editors in Kotlin Multiplatform with Krope

Fri, 24 Jul 2026 13:03:31 +0000

If you have ever tried building a text editor, an IDE, or a collaborative document tool, you quickly run into a fundamental wall: how do you store the text?

At first glance, a standard String seems fine. But Strings are immutable; changing a single character in a 1MB file requires allocating a brand new 1MB array. So, you move to StringBuilder. It’s mutable and fast for simple appends, but inserting or deleting text in the middle of a massive document still requires shifting hundreds of thousands of characters in memory — an O(N) operation that causes UI stuttering as your document grows.

This is where the Rope data structure comes in.

Today, I want to introduce Krope, a high-performance, memory-safe, and reactive Rope library built entirely in Kotlin Multiplatform. Whether you are targeting JVM, Android, iOS, or WASM, Krope provides the engine you need to build next-generation text editing tools.

What is a Rope?

Instead of storing text as a single massive, contiguous array of characters, a Rope stores text as a balanced binary tree (in Krope’s case, utilizing a Red-Black tree variant). The leaves of the tree contain short chunks of strings.

When you insert text in the middle of a document, a Rope doesn’t copy the whole string. Instead, it splits a leaf node and inserts a new branch. This gives operations like insertion, deletion, and replacement a time complexity of O(log N).

Furthermore, Krope implements structural sharing. When a modification occurs, Krope doesn’t mutate the existing tree; it returns a new tree that shares the untouched branches with the old one. This provides safe concurrent access, cheap undo/redo history.

Why I Built Krope

The idea for Krope was born while building haskcore — a full-featured IDE for Haskell written in Compose Desktop. It uses Skia for rendering, Tree-sitter for incremental syntax parsing, and the Language Server Protocol for code intelligence. It’s a real editor with 40+ modules, handling everything from syntax highlighting to code completion and project-wide diagnostics.

Very quickly, I hit a wall: Kotlin’s standard StringBuilder couldn't keep up. Editing large Haskell modules meant shifting massive text buffers on every keystroke, causing visible lag during syntax highlighting and LSP synchronization. I needed something better — and the rope data structure, battle-tested in editors like Emacs and Vim since the 90s, was the obvious answer.

But Kotlin Multiplatform lacked a modern, reactive, and fully-featured rope implementation. So I built Krope to solve the specific pain points I encountered:

Cross-Platform Consistency: haskcore targets the desktop, but the same text engine should work on Android, iOS, and WASM for future ports or companion apps.
Reactive by Design: Compose Multiplatform thrives on reactive state. Krope exposes every edit as a SharedFlow event and every document state as a StateFlow, making UI integration seamless.
Byte-Level Encoding Awareness: LSP servers speak in byte offsets, not character positions. Krope natively tracks UTF-8, UTF-16, and UTF-32, giving you efficient access to byte coordinates backed by an LRU cache.
Functional & Safe: Invalid operations shouldn’t crash your editor. Krope uses an Either<Throwable, Result> pattern, so out-of-bounds inserts return errors you can handle gracefully — critical when processing remote edits from LSP or collaborative peers.

Inside the Krope API

Krope separates the underlying data structure from the editor API. The primary interface you interact with is the TextBuffer.

Here is how simple it is to get started:

import io.github.numq.krope.core.Encoding
import io.github.numq.krope.text.*
import kotlinx.coroutines.launch

// 1. Initialize the buffer
val factory = RopeTextBufferFactory()
val buffer = factory.create(
    text = "Hello World",
    encoding = Encoding.UTF8,
    lineEnding = TextLineEnding.LF,
    enablePooling = true // Enables internal string interning to save memory
).fold(
    onLeft = { error -> throw error },
    onRight = { it }
)

The Reactive Paradigm

In a standard text editor, the UI needs to know exactly what changed to update the screen or send a diff over the network for collaborative editing. Krope exposes two flows:

snapshot: StateFlow<TextSnapshot>: Represents the immutable current state of the document.
data: SharedFlow<TextEdit.Data>: Emits granular events whenever the text changes.

// Observe all changes in real-time
launch {
    buffer.data.collect { editData ->
        when (editData) {
            is TextEdit.Data.Single.Insert -> 
                println("Inserted '${editData.insertedText}' at ${editData.startPosition}")
            is TextEdit.Data.Single.Delete -> 
                println("Deleted text ending at ${editData.oldEndPosition}")
            is TextEdit.Data.Single.Replace -> 
                println("Replaced '${editData.oldText}' with '${editData.newText}'")
            is TextEdit.Data.Batch -> 
                println("Batch processed ${editData.singles.size} operations atomically")
        }
    }
}

Line and Column Awareness

Most ropes just deal with raw character offsets. Krope natively understands Lines and Columns through TextPosition.

// "Hello Beautiful World"
buffer.insert(TextPosition(line = 0, column = 5), " Beautiful")

// Querying the snapshot is instantaneous thanks to cached tree node metadata
val snapshot = buffer.snapshot.value
println("Total Lines: ${snapshot.lines}")
println("Max Line Length: ${snapshot.maxLineLength}")

// Get byte offset for an LSP (Language Server Protocol)
val byteOffset = snapshot.getBytePosition(TextPosition(line = 0, column = 6))

Atomic Batch Operations

When you refactor code (like renaming a variable that appears 10 times in a file), you don’t want to trigger 10 separate UI redraws or clutter the undo stack. Krope supports withBatch:

buffer.withBatch { batch ->
    batch.replace(TextRange(TextPosition(0, 39), TextPosition(0, 42)), "vatAmount")
    batch.replace(TextRange(TextPosition(1, 19), TextPosition(1, 22)), "vatAmount")
}

This applies all edits internally, rebalances the tree once, and emits a single TextEdit.Data.Batch event to your listeners.

Performance: The 100 Megabyte Test

To answer the age-old question - "How does it perform with very large files?" - I ran JMH benchmarks on the JVM comparing Krope to StringBuilder.

We simulated the "Real Editor Scenario": 100 consecutive edits (insertions) occurring right in the middle of a document. We scaled the document size from 100,000 characters all the way to 100,000,000 characters (approximately 200 MB of text).

Here are the results (in milliseconds per 100 operations):

100,000 symbols

Krope: ~0.05 ms
StringBuilder: ~0.16 ms
Krope Advantage: ~3x faster

1,000,000 symbols

Krope: ~0.19 ms
StringBuilder: ~1.74 ms
Krope Advantage: ~9x faster

10,000,000 symbols

Krope: ~2.07 ms
StringBuilder: ~17.86 ms
Krope Advantage: ~8.5x faster

100,000,000 symbols

Krope: ~19.32 ms
StringBuilder: ~186.41 ms
Krope Advantage: ~9.6x faster

Why does StringBuilder choke?

Look at how the StringBuilder time multiplies by 10 every time the file size multiplies by 10. This is the curse of O(N) complexity. When you insert a single character in the middle of a 200MB StringBuilder, Java has to use System.arraycopy to physically shift 100MB of data in RAM to make room. Doing this 100 times forces the CPU to move 10 gigabytes of memory. This is exactly what causes UI thread stuttering and input lag in text editors.

Why does Krope win?

Because of structural sharing and its Red-Black tree foundation. When making 100 edits, Krope doesn't copy 100MB of arrays. It simply splits a small leaf node, updates a few pointers up to the root, and does a lightning-fast O(log N) tree rebalance.

(Note: In the benchmark above, the ~19.32 ms for Krope actually included the time to parse the 200MB string into a Rope tree from scratch on every iteration! The edits themselves are nearly instantaneous).

In a real-world typing or refactoring scenario, Krope maintains incredibly flat, predictable latency regardless of whether your file is 10 Kilobytes or 200 Megabytes, keeping your UI perfectly smooth while drastically reducing heap allocations.

Get Involved

If you are building text-heavy applications in Compose Multiplatform, writing a code editor, or experimenting with CRDTs for collaborative editing, give Krope a try.

The architecture is highly modular, separating the core data structures from the TextBuffer API, and includes built-in support for kotlinx.serialization.

Check out the source code, play with the examples, and star the repository on GitHub!

🔗 GitHub Repository: Krope

Kotlin 2.4.0 Released

Sat, 13 Jun 2026 19:31:15 +0000

JetBrains has released Kotlin 2.4.0. The update includes stable language features, standard library additions, Kotlin/Native changes for Swift interoperability, Kotlin/Wasm and Kotlin/JS improvements, and build tool updates for Gradle and Maven.

The release is included in the latest versions of IntelliJ IDEA and Android Studio. Projects can update by setting the Kotlin version to 2.4.0 in their build scripts.

Language and Standard Library

Several language features that were previously experimental are now stable, including context parameters, explicit backing fields, the @all meta-target for properties, and new defaulting rules for annotation use-site targets.

The common standard library now has a stable kotlin.uuid.Uuid API. Kotlin 2.4.0 also adds sorted-order checks such as .isSorted() and .isSortedBy(), plus JVM extensions for converting unsigned integers to BigInteger.

On Kotlin/JVM, the compiler can generate Java 26 bytecode, and annotations in Kotlin metadata are now enabled by default.

Kotlin/Native and KMP

For Kotlin Multiplatform projects, the main changes are in Kotlin/Native. Swift export is now Alpha and has improved concurrency support: Kotlin suspend functions are exported as Swift async counterparts, and kotlinx.coroutines flows can be exported to Swift as AsyncSequence.

KMP projects can also declare Swift packages as dependencies for iOS apps directly in Gradle configuration. JetBrains also provides migration support for projects that currently rely on CocoaPods dependencies.

Kotlin/Native now supports Xcode 26.4, updates LLVM to version 21, and enables the concurrent mark and sweep garbage collector by default. The default minimum supported Apple target versions have also been raised to iOS and tvOS 15.0, macOS 12.0, and watchOS 8.0.

Wasm, JS, and Build Tools

Kotlin/Wasm incremental compilation is now stable and enabled by default. Kotlin 2.4.0 also introduces experimental support for the WebAssembly Component Model.

Kotlin/JS improves JavaScript and TypeScript export with support for value class export and ES2015 features when inlining JavaScript code.

On the build side, Kotlin 2.4.0 is compatible with Gradle 9.5.0. Maven builds now support automatic alignment between Java and JVM target versions.

Official announcement:
https://blog.jetbrains.com/kotlin/2026/06/kotlin-2-4-0-released/

Detailed release notes:
https://kotlinlang.org/docs/whatsnew24.html

Drop the Clutch: Three Metro DI Patterns Every KMP Developer Should Know - Part 2

Fri, 05 Jun 2026 19:03:27 +0000

In Part 1, I covered Metro's fundamentals: how it differs from Koin Annotations and Dagger, the basic setup, and the @ContributesBinding pattern for everyday features. This part picks up where that left off, with two patterns that push past the basics — platform-specific graph splitting and scoped lifetimes with runtime values.

Feature 2: Notification permission

This is where Metro in a multiplatform project gets genuinely tricky, and where the constraint that makes it correct becomes obvious.

On Android, requesting notification permission requires Context, which goes to ActivityCompat.requestPermissions. On iOS, you use UNUserNotificationCenter. Neither type exists in commonMain. The interface for the provider lives there, but the implementations are entirely platform-specific. If you want a deep dive into cross-platform notifications with KMP, I covered the full setup in a previous article.

The instinct is to put @DependencyGraph on the common interface and let platform graphs extend it:

// WRONG: fails to compile on the iOS target
// commonMain/di/AppGraph.kt
@DependencyGraph(scope = AppScope::class)
interface AppGraph {
    @DependencyGraph.Factory
    fun interface Factory {
        fun create(@Provides context: Context): AppGraph // Context is an Android type
    }
}

The iOS compiler doesn't know what Context is. The build fails with an unresolved reference. After that error, we can try @GraphExtension. Metro provides it for extending an existing graph, but @GraphExtension.Factory is a different annotation from @DependencyGraph.Factory, and createGraphFactory only accepts the second one. You end up with a graph you can't instantiate.

I went through both of those dead ends before the correct pattern became clear: the common interface is just a plain Kotlin interface with no Metro annotations. The @DependencyGraph goes only on the platform-specific implementations.

// commonMain/di/RootGraph.kt
import dev.zacsweers.metrox.viewmodel.ViewModelGraph

// Plain Kotlin interface, no @DependencyGraph
interface RootGraph : ViewModelGraph {
    val platformNotificationProvider: PlatformNotificationProvider
}

// androidMain/di/AndroidRootGraph.kt
import dev.zacsweers.metro.DependencyGraph
import dev.zacsweers.metro.Provides

@DependencyGraph(scope = AppScope::class)
interface AndroidRootGraph : RootGraph {

    @DependencyGraph.Factory
    fun interface Factory {
        fun create(@Provides context: Context): AndroidRootGraph
    }
}

// iosMain/di/IosRootGraph.kt
import dev.zacsweers.metro.DependencyGraph

@DependencyGraph(scope = AppScope::class)
interface IosRootGraph : RootGraph

Creating the graph on each platform:

// androidMain/App.kt
class App : Application() {
    val graph: RootGraph by lazy {
        createGraphFactory<AndroidRootGraph.Factory>().create(applicationContext)
    }
}

// iosMain/MainViewController.kt
fun MainViewController() = ComposeUIViewController {
    val graph = remember { createGraph<IosRootGraph>() }
    App(graph)
}

createGraph<T>() expects T to be a @DependencyGraph with no required external parameters. createGraphFactory<F>() expects F to be a @DependencyGraph.Factory inside a graph that needs those parameters. Both return a RootGraph, which is what the shared App() composable receives. The composable never needs to know which platform it's running on.

Platform implementations

The notification provider expect class lives in common:

// commonMain/core/domain/PlatformNotificationProvider.kt
import kotlinx.coroutines.flow.StateFlow

expect class PlatformNotificationProvider {
    val permissionGranted: StateFlow<Boolean>
    fun requestPermission()
    fun observeNotificationServicePermission()
}

The Android implementation uses Context and an ActivityHolder, a wrapper that MainActivity updates on onCreate/onDestroy so DI-managed classes can reach the current Activity without holding a direct reference to it:

// androidMain/feature/notifications/data/PlatformNotificationProviderImpl.kt
@Inject
@SingleIn(AppScope::class)
actual class PlatformNotificationProvider(
    private val context: Context,
    private val activityHolder: ActivityHolder
) {
    companion object {
        const val REQUEST_CODE_NOTIFICATIONS = 1001
    }

    private val _permissionGranted = MutableStateFlow(false)
    actual val permissionGranted: StateFlow<Boolean> = _permissionGranted

    actual fun requestPermission() {
        val activity = activityHolder.get() ?: return
        ActivityCompat.requestPermissions(
            activity,
            arrayOf(Manifest.permission.POST_NOTIFICATIONS),
            REQUEST_CODE_NOTIFICATIONS
        )
    }

    actual fun observeNotificationServicePermission() {
        _permissionGranted.value = ContextCompat.checkSelfPermission(
            context, Manifest.permission.POST_NOTIFICATIONS
        ) == PackageManager.PERMISSION_GRANTED
    }
}

Android	iOS

Android doesn't deliver permission results to DI-managed classes. They come back to Activity.onRequestPermissionsResult. The pattern that works: MainActivity calls observeNotificationServicePermission() in the callback, the provider re-reads the system state, and the MutableStateFlow updates. Everything else observes the flow.

// androidMain/MainActivity.kt
override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String?>,
    grantResults: IntArray,
    deviceId: Int
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults, deviceId)
    if (requestCode == PlatformNotificationProviderImpl.REQUEST_CODE_NOTIFICATIONS) {
        graph.platformNotificationProvider.observeNotificationServicePermission()
    }
}

The iOS implementation uses UNUserNotificationCenter.

The error you get if you annotate the common graph isn't Metro being fussy. It's the compiler catching a design that would break the iOS build entirely. The plain interface isn't a workaround. It's the correct model.

Feature 3: Chat room

This is the pattern I wanted to understand before committing to Metro seriously. The first two features use AppScope for everything, which makes sense: repositories and providers live for the app's lifetime. But not everything does.

A WebSocket isn't a data object. It connects on creation and needs to be explicitly closed. Keeping it in AppScope means the socket stays open for the entire app lifetime, even when the user is on a completely different screen. That's almost never what you want for a real-time connection.

A scope is a lifetime, not a namespace. The ChatScope exists because the socket needs to be opened when the chat screen opens and closed when it leaves. And because every chat room is a different conversation, there's a second problem to solve: the conversation ID is only known at runtime, when the user taps a row. Metro needs to receive it and make it available to anything in the scope.

Here's how the two scopes relate in the demo:

AppScope  (AndroidRootGraph / IosRootGraph)
├── ConversationRepository       singleton, lives for the app's lifetime
├── PlatformNotificationProvider singleton, lives for the app's lifetime
├── AppViewModelFactory
│
└── ChatScope  (ChatGraph) ──── created via ChatGraph.Factory at navigation time
    ├── ConversationId           runtime value, injected through the factory parameter
    ├── ChatSocket               singleton within this scope
    └── ChatViewModelFactory

ChatScope is nested inside AppScope and inherits all of its bindings. ChatGraph uses @GraphExtension for exactly that reason. Anything in ChatScope can ask for ConversationRepository or PlatformNotificationProvider and Metro will resolve them from the parent graph. The reverse isn't true: AppScope knows nothing about ChatSocket or ConversationId.

The scope and the socket

// commonMain/di/ChatScope.kt
import dev.zacsweers.metro.Scope

@Scope
annotation class ChatScope

The conversation ID is a runtime value, so it gets a proper type:

// commonMain/feature/chat/domain/ConversationId.kt
@JvmInline
value class ConversationId(val value: String)

A value class, different from a raw String, keeps the binding unambiguous. Metro identifies bindings by type, so ConversationId and String are different things in the graph.

// commonMain/feature/chat/data/ChatSocket.kt
@Inject
@SingleIn(ChatScope::class)
class ChatSocket(val conversationId: ConversationId) {

    private val _messages = MutableStateFlow<List<ChatMessage>>(emptyList())
    val messages: StateFlow<List<ChatMessage>> = _messages

    private val _isTyping = MutableStateFlow(false)
    val isTyping: StateFlow<Boolean> = _isTyping

    private var job: Job? = null

    init {
        job = CoroutineScope(Dispatchers.Default).launch {
            var lap = 1
            while (true) {
                delay(2_000)
                _isTyping.value = true
                delay(1_000)
                _isTyping.value = false
                _messages.update {
                    it + ChatMessage(sender = "Engineer", text = "Lap $lap: pace looks good.")
                }
                lap++
            }
        }
    }

    fun close() {
        job?.cancel()
        job = null
    }
}

ChatSocket declares ConversationId as a constructor parameter. Metro will inject it — no special annotation needed on the parameter itself. The binding just has to exist somewhere in the scope, and the factory is where it comes from.

@SingleIn(ChatScope::class) means one ChatSocket per ChatGraph. Not one per app, one per chat session. Navigate away and come back, and you get a fresh socket with its own conversation ID.

The graph extension

The chat graph uses @GraphExtension rather than @DependencyGraph. The difference is that @GraphExtension extends an existing parent graph and inherits all of its bindings. @DependencyGraph creates a standalone graph that knows nothing about its caller.

// commonMain/di/ChatGraph.kt
import dev.zacsweers.metro.GraphExtension
import dev.zacsweers.metro.Provides
import dev.zacsweers.metrox.viewmodel.ViewModelGraph

@GraphExtension(scope = ChatScope::class)
interface ChatGraph : ViewModelGraph {
    val chatSocket: ChatSocket

    @ContributesTo(AppScope::class)
    @GraphExtension.Factory
    fun interface Factory {
        fun create(@Provides conversationId: ConversationId): ChatGraph
    }
}

@Provides on the factory parameter is Metro's answer to runtime injection. When create(conversationId) is called, Metro takes that value and makes it available as a binding for the entire ChatScope. ChatSocket asks for ConversationId in its constructor; Metro delivers the one passed into the factory. No extra wiring, no manual passing.

ConversationId isn't being threaded through a call chain. It's a graph-level binding. Any class in ChatScope can list it as a constructor parameter and get the right one automatically. The ChatGraph instance is this specific conversation. Add a read-receipt tracker or a typing service later and they get the ID for free, for as long as the socket is alive.

@ContributesTo(AppScope::class) on the factory tells Metro to aggregate it into the root graph automatically, so the root graph exposes chatGraphFactory without needing to declare it explicitly.

The entry composable

// commonMain/feature/chat/presentation/ChatEntry.kt
@Composable
fun ChatEntry(
    factory: ChatGraph.Factory,
    conversationId: ConversationId,
    onBackClick: () -> Unit
) {
    val graph = remember { factory.create(conversationId) }

    DisposableEffect(Unit) {
        onDispose { graph.chatSocket.close() }
    }

    CompositionLocalProvider(LocalMetroViewModelFactory provides graph.metroViewModelFactory) {
        ChatScreen(onBackClick = onBackClick)
    }
}

remember { factory.create(conversationId) } creates the graph once for the lifetime of this composable. The conversationId comes from the navigation back-stack entry and is fixed for the session, which is why remember with no key is correct here. DisposableEffect with onDispose calls close() when the composable leaves the composition. CompositionLocalProvider swaps the ViewModel factory to the one backed by ChatScope, so metroViewModel() calls inside ChatScreen resolve from ChatGraph, not the root AppScope factory.

The socket starts emitting as soon as ChatEntry enters the composition. While the screen is open, a new message arrives every three seconds, preceded by a one-second typing indicator. The moment you navigate away, onDispose fires, close() cancels the coroutine, and it stops. Navigate back to a different conversation and you get a fresh ChatGraph, a fresh ChatSocket, and a new ConversationId, all from a single factory.create(newId) call.

AppScope would mean the socket survives every screen transition for the app's entire lifetime. ChatScope means it lives exactly as long as the chat screen. The @Provides on factory parameter means runtime values flow into the scope cleanly, without leaking Android lifecycle details into the graph definition.

Gotchas

Most of these I hit personally while building the demo. Metro's error messages are generally good, but a few failure modes produce errors that point at the wrong place. You see the interface in the message, not the implementation that caused the problem. That's the pattern to watch for.

internal on @ContributesBinding classes.
If a contributed class is internal (usually in a multi-module project), Metro can't aggregate it across module boundaries. The reason: Metro's compiler plugin generates glue code that references your class by name. If that class is internal, the generated code sits outside the declaring module's visibility boundary and can't see it. The build succeeds, but you'll get a MissingBinding error naming the interface, not the implementation. This one is hard to trace the first time. Keep contributed classes public (the default) or at least within the same Gradle module as every class that needs them.

@DependencyGraph cannot extend @DependencyGraph.
Metro rejects this at compile time: "Graph class may not directly extend graph class." The plain-interface pattern from Feature 2 is the correct solution: annotate only the platform-specific leaf implementations.

createGraph vs createGraphFactory.
createGraph<T>() expects T to be a @DependencyGraph with no required external parameters. createGraphFactory<F>() expects F to be a @DependencyGraph.Factory. These are different annotations; mixing them produces a compiler error that points at the right place, but the fix isn't obvious until you understand the split.

@GraphExtension vs @DependencyGraph for child graphs.
Use @GraphExtension when the child graph should inherit parent bindings, which is the right choice for a scoped feature graph like ChatGraph. Use @DependencyGraph only for the root platform graphs. Mixing them up produces a graph that either can't see parent bindings or can't be instantiated correctly.

Scope mismatch.
A class scoped to ChatScope that gets injected into something in AppScope produces a MissingBinding error at compile time. The error names the interface, not the implementation. When you see it, check whether the implementation is scoped to a graph the requester can't reach.

Manifest permissions are a separate concern.
This is more an Android issue. Metro wires up a class that calls requestPermissions correctly. But if POST_NOTIFICATIONS isn't declared in AndroidManifest.xml, the dialog won't appear and there's no error anywhere. Always check the manifest first if a permission flow does nothing.

Wrapping up

Metro moves dependency graph validation from runtime to compile time, and that shift changes how you think about DI mistakes. The patterns here cover most of the ground: binding contributions for everyday features, the platform graph split for anything that needs Android or iOS types, and child scopes for dependencies with a real lifecycle, including runtime values like a conversation ID flowing in through a factory parameter. Get those three things in place and the rest of the wiring tends to solve itself.

The paddle shifters don't make you a faster driver. But they do free up your hands for the things that actually determine where you finish.

The full demo for this article is available on GitHub.

The KMP Bits app is available on App Store and Google Play, built entirely with KMP.

Drop the Clutch: Three Metro DI Patterns Every KMP Developer Should Know - Part 1

Fri, 05 Jun 2026 19:03:01 +0000

In a GT3 car, you have a choice. You can drive with a traditional manual gearbox: clutch pedal, H-pattern shifter, full control over every gear change. Or you can switch to the sequential paddle shifters that most modern GT3 cars run. The car is still yours to drive. The racing line, the braking points, the tyre management. All of that stays with you. The only thing that changes is that you stop managing something that was never really the point.

I've been running Koin in a multi-module Compose Multiplatform project for a while, and for a long time it felt like the manual gearbox. Not painful exactly, just present. Every new dependency meant another module { } block somewhere, another get() in the factory lambda, another place where the compiler had nothing to say if I forgot to wire something. The error came at runtime, and usually in a context that made it harder to trace than it should have been.

Metro is the paddle shifters. You annotate your classes, define a graph interface, and the Kotlin compiler plugin generates the wiring at build time. If something is missing from the graph, the build fails. Not the app launch. The build.

I already covered Koin Annotations in a previous article. What follows isn't a migration guide. It's a look at three specific patterns that come up in every real KMP project and where Metro's behaviour changed how I think about dependency injection. This is Part 1 — setup, the basics of Metro's model, and the binding pattern you'll use for most features. Part 2 covers platform-specific graphs and scoped lifetimes.

What Metro is

Metro is a compile-time dependency injection framework for Kotlin Multiplatform. It ships as a Kotlin compiler plugin, not an annotation processor or a KSP plugin. Code generation happens in the compiler's FIR/IR pipeline directly.

The mental model draws from three places: @Inject, @Provides, and the scope system come from Dagger; the interface-based graph definition comes from kotlin-inject; and the contribution aggregation system comes from Anvil. If you've worked with any of those three, the ideas transfer quickly.

Metro, Koin Annotations, and Dagger

Before getting into the patterns, it's worth placing Metro relative to the tools you've probably already used.

Koin Annotations

The comparison people reach for first is Koin Annotations, because both claim compile-time safety. I want to be clear about something: these are not competing answers to the same question. They solve the same problem, both do it well, and the choice comes down to what your project actually needs.

Koin Annotations uses KSP to generate source files during the build. It catches graph errors in the KSP phase, which is earlier than runtime, but the Koin service locator container still exists underneath. If something slips through, the app can still throw on startup. The generated .kt files land in build/generated/ksp/, and you need KSP configured and on the right classpath. For most projects, that's no trouble at all. Koin is mature, widely used, and well documented.

Metro works at a different level. It's a compiler plugin operating on the IR representation of your code, the same layer where kotlinx.serialization and the Compose compiler plugin live. There are no generated source files, no build/generated/ directory, no KSP classpath to manage. The output is direct constructor calls baked into bytecode. Metro has no runtime container. If the graph is invalid, the build doesn't produce a binary.

The trade-offs are real on both sides. Metro is strictly static, so dynamic or conditional bindings that Koin handles without friction are outside Metro's scope. And Metro is a newer library, primarily maintained by one person. Koin has years of production use behind it.

My take: if your team already knows Koin, or you need dynamic binding flexibility, stick with Koin Annotations. If you want the strictest compile-time guarantee with no runtime container underneath, Metro is the right call.

If you know Dagger

If you've used Dagger before, Metro will feel familiar in the right places. @Inject, @Provides, scope annotations, and compile-time graph validation are all there. The graph interface replaces Dagger's @Component, @DependencyGraph.Factory replaces @Component.Builder, and @ContributesBinding replaces the manual @Binds plus module wiring you'd write by hand in Dagger.

Metro is a compiler plugin rather than an annotation processor, so no KAPT, no KSP, no generated source files to track. The interface-based graph definition is cleaner than Dagger's abstract class components. And Metro supports Kotlin Multiplatform natively. Dagger never did. If you've used Hilt, the @ContributesBinding aggregation pattern will look familiar: Metro borrows it from Anvil, which is what Hilt builds on.

Where Dagger still has an edge: it's been used in large Android codebases for over a decade, the tooling is more mature, and the error messages are better when something goes wrong. If you're on a large Android-only project with an existing Dagger graph, there's rarely a reason to migrate.

The demo

The three patterns I want to show are easier to understand in context than in isolation. To make them concrete, I built a fake real-time chat app: a conversations list, a notification permission screen, and a chat room with a scoped WebSocket. No server, no real backend. Just hardcoded data and coroutine timers. Each screen demonstrates one Metro concept, and together they cover the situations you'll hit in almost any real KMP project.

The article focuses entirely on the DI wiring. The UI is minimal by design.

Setup

# gradle/libs.versions.toml
[versions]
metro = "1.0.0"

[plugins]
metro = { id = "dev.zacsweers.metro", version.ref = "metro" }

[libraries]
metro-viewmodel = { module = "dev.zacsweers.metro:metrox-viewmodel", version.ref = "metro" }
metro-viewmodel-compose = { module = "dev.zacsweers.metro:metrox-viewmodel-compose", version.ref = "metro" }

// build.gradle.kts (root)
plugins {
    alias(libs.plugins.metro) apply false
}

Apply the plugin to every module that contains Metro annotations and add the ViewModel extensions to the modules that need them:

// composeApp/build.gradle.kts
plugins {
    alias(libs.plugins.metro)
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.metro.viewmodel)
            implementation(libs.metro.viewmodel.compose)
        }
    }
}

metrox-viewmodel and metrox-viewmodel-compose are what give you ViewModelGraph, LocalMetroViewModelFactory, and @ContributesIntoMap for lifecycle-aware ViewModel injection. The demo uses all three.

One Gradle plugin, two extra libraries. No annotation processor configuration, no generated source directories to wire into your source sets.

The project organises code by package rather than separate Gradle modules. Metro's contribution system works at the annotation level, not the module boundary, so packages are enough. A scope marker is all you need to get started:

// commonMain/di/AppScope.kt
import dev.zacsweers.metro.Scope

@Scope
annotation class AppScope

Feature 1: Conversations list

This is the baseline. The pattern you'll use for most features in any KMP project.

The interface lives in the domain layer:

// commonMain/feature/conversations/domain/ConversationRepository.kt
interface ConversationRepository {
    suspend fun getConversations(): List<Conversation>
}

The implementation attaches itself to the graph:

// commonMain/feature/conversations/data/FakeConversationRepository.kt
import dev.zacsweers.metro.ContributesBinding
import dev.zacsweers.metro.Inject
import dev.zacsweers.metro.SingleIn
import kotlinx.coroutines.delay

@Inject
@ContributesBinding(AppScope::class)
@SingleIn(AppScope::class)
class FakeConversationRepository : ConversationRepository {

    override suspend fun getConversations(): List<Conversation> {
        delay(300) // fake network latency
        return listOf(
            Conversation(id = "1", name = "Garage channel", lastMessage = "Tyres are warm."),
            Conversation(id = "2", name = "Pit wall", lastMessage = "Box this lap.")
        )
    }
}

@ContributesBinding(AppScope::class) tells Metro: this class implements ConversationRepository and belongs to AppScope. The root graph never needs to declare it. Metro aggregates everything contributed to a scope automatically at compile time. @SingleIn(AppScope::class) keeps one instance alive for the app's lifetime. Remove it and Metro creates a new repository on every injection, which is almost never what you want for a repository.

This is the pattern that makes multi-feature wiring low-ceremony. Each feature declares its own contributions and the root graph stays small.

Lifecycle-aware ViewModel injection

The ViewModel follows the same constructor injection pattern, but contributing it uses a map:

// commonMain/feature/conversations/presentation/ConversationsViewModel.kt
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import dev.zacsweers.metro.ContributesIntoMap
import dev.zacsweers.metro.Inject
import dev.zacsweers.metro.ViewModelKey
import dev.zacsweers.metro.binding
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.launch

@Inject
@ContributesIntoMap(AppScope::class, binding = binding<ViewModel>())
@ViewModelKey(ConversationsViewModel::class)
class ConversationsViewModel(
    private val repository: ConversationRepository
) : ViewModel() {

    private val _conversations = MutableStateFlow<List<Conversation>>(emptyList())
    val conversations: StateFlow<List<Conversation>> = _conversations

    init {
        viewModelScope.launch {
            _conversations.value = repository.getConversations()
        }
    }
}

@ContributesIntoMap puts this ViewModel into a map that Metro generates for the scope. The @ViewModelKey annotation sets the key. That map feeds into MetroViewModelFactory, an abstract class from Metro's ViewModel extensions that you subclass once per scope.

Metro won't provide MetroViewModelFactory automatically. It's abstract and has no @Inject constructor. You bridge the gap with a small file that subclasses it for each scope:

// commonMain/di/ViewModelFactory.kt
@Inject
@ContributesBinding(AppScope::class)
@SingleIn(AppScope::class)
class AppViewModelFactory(
    override val viewModelProviders: Map<KClass<out ViewModel>, () -> ViewModel>,
    override val assistedFactoryProviders: Map<KClass<out ViewModel>, () -> ViewModelAssistedFactory>,
    override val manualAssistedFactoryProviders: Map<KClass<out ManualViewModelAssistedFactory>, () -> ManualViewModelAssistedFactory>,
) : MetroViewModelFactory()

The class is @Inject, so Metro can construct it. The three maps are populated from @ContributesIntoMap contributions in AppScope. @ContributesBinding wires AppViewModelFactory to the MetroViewModelFactory binding in the scope. (You'll see the ChatViewModelFactory equivalent in Part 2, when we introduce a second scope.)

ViewModelGraph then exposes metroViewModelFactory, which you provide through a CompositionLocal:

// commonMain/App.kt
@Composable
fun App(graph: RootGraph) {
    CompositionLocalProvider(LocalMetroViewModelFactory provides graph.metroViewModelFactory) {
        AppTheme { AppEntry() }
    }
}

Inside any screen below that provider, metroViewModel<ConversationsViewModel>() resolves from the map, scoped to the back stack entry, cleaned up when the screen pops. The Metro wiring doesn't touch any of that: it just provides the factory.

A quick note on metroViewModelFactory: Compose's viewModel() function uses reflection by default, which doesn't work with Metro since there's no runtime container. metroViewModel<T>() from metrox-viewmodel-compose reads LocalMetroViewModelFactory and constructs ViewModels from the contributed map instead. The MetroViewModelFactory subclass you write in ViewModelFactory.kt is the bridge: it takes the generated provider maps as constructor arguments and wires them into the factory. Everything else works exactly as you'd expect from the Jetpack ViewModel API.

The thing that clicked for me: @ContributesBinding contributes a single binding, @ContributesIntoMap contributes an entry to a map. Both are aggregated automatically. Neither requires touching the root graph.

What's next

Part 1 covers the foundation: how Metro differs from Koin and Dagger, how to wire up a simple feature with @ContributesBinding, and how ViewModel injection works through contributed maps.

[Part 2]([PART 2 LINK]) is where it gets more interesting. It covers two patterns that every multiplatform project eventually runs into: how to split platform-specific graph implementations correctly (spoiler: the common interface carries no Metro annotations at all), and how to create a scoped graph for dependencies with a real lifecycle — including how a runtime value like a conversation ID flows into a child scope through a factory parameter.

The full demo for this article is available on GitHub.

The KMP Bits app is available on App Store and Google Play, built entirely with KMP.

Kotlin Professional Certificate by JetBrains

Wed, 20 May 2026 10:00:04 +0000

JetBrains has launched the Kotlin Professional Certificate by JetBrains, a new LinkedIn Learning path designed to help developers build practical Kotlin and Kotlin Multiplatform skills.

The program is structured around four courses and takes developers from Kotlin fundamentals through object-oriented and asynchronous programming, Kotlin Multiplatform development, and full-stack app development with Ktor and Compose Multiplatform. JetBrains says the certificate is aimed at developers with basic programming knowledge who want to learn Kotlin and explore how it can be used across Android, iOS, web, desktop, and backend environments.

The course includes:

Kotlin Essential Training
Kotlin Multiplatform
Ktor
Compose

After completing the course and passing the final exam, developers can earn a certificate that can be downloaded, shared, and added to a LinkedIn profile.

Additional info at:
https://blog.jetbrains.com/kotlin/2026/04/kotlin-professional-certificate-by-jetbrains-now-on-linkedin-learning/

Link to the course:
https://www.linkedin.com/learning/paths/kotlin-professional-certificate-by-jetbrains

JetBrains Just Changed KMP Structure. Here's What They Didn't Tell You.

Mon, 18 May 2026 18:26:05 +0000

JetBrains announced a new default project structure for KMP. Two shared modules — sharedLogic and sharedUI — plus separate application modules for each platform. Clean. Simple. Obvious.

It's also a trap.

The problem with `sharedLogic` and `sharedUI`

A fresh sharedLogic module looks innocent. Business logic, models, repositories. sharedUI holds your Composables. What could go wrong?

Three months later sharedLogic contains:

Business logic
Network clients
Database models
Constants
Utility functions
Something called CommonUtils.kt that nobody understands but everyone is afraid to delete

sharedLogic has no internal boundaries. Everything depends on everything. You can import a database model from a use case and nobody stops you. The compiler certainly won't.

JetBrains tells you where to start. They don't tell you what happens when two modules become 50,000 lines.

What actually happens

You try to split sharedLogic into more modules. But there are no rules. So you end up with:

:sharedLogic:core — the new dumping ground
:sharedLogic:data — which also contains business logic somehow

The dependencies look like spaghetti. Changing one module breaks three others. You didn't enforce boundaries early, and now every refactoring is a gamble.

FLIP: the next step after `sharedLogic`

FLIP is an architectural pattern that gives you rules for splitting sharedLogic before it becomes a problem.

Five layers. One direction. Zero horizontal dependencies.

Layer	Purpose	Depends on
:common:core	Foundation	Nothing
:service	Domain logic without UI	`:common:core`
:feature	UI features	`:service`, `:common:core`
:entrypoint	DI assembly + slot composition	Everything above
:platform	Platform entry point	`:entrypoint`

The rule is simple: features don't know about other features. services don't know about other services. Dependencies only flow down.

Your IDE enforces this. You literally cannot import a feature from another feature — Gradle won't compile. The structure prevents the dumpster fire before it starts.

Start with JetBrains. Grow with FLIP.

The new KMP structure is a great starting point. Two modules is better than one. But when sharedLogic starts feeling like a junk drawer, you know what to do.

FLIP is at github.com/numq/flip. Template included. Konsist tests included. Rules over conventions.

FLIP: Modular Architecture for KMP

Sun, 17 May 2026 04:49:14 +0000

While building haskcore - an IDE for Haskell on Compose Desktop - I extracted rules that allowed me to create an architecture of 40 isolated modules, where each module knows only what it needs.

That's how FLIP - Feature-Layered Isolated Platform - was born.

The main problem I faced during development: horizontal dependencies make the system fragile. The solution - strict vertical hierarchy.

FLIP consists of the following isolated modules:

:common:core - common logic components.
:common:presentation - common UI components.
:service - UI-less domain module. Provides a service interface.

interface SeedService : AutoCloseable {
    val seed: Flow<Seed>
    suspend fun generateSeed(): Either<Throwable, Unit>
}

:feature:core — logic module of a UI-feature. Knows nothing about other features. Uses services from :service. Provides use cases.

class GenerateRemoteRandomSeed(private val seedService: SeedService) : UseCase.Action {
    override suspend fun Raise<Throwable>.action() = seedService.generateSeed().bind()
}

:feature:presentation — UI module of a UI-feature. Knows only about its :feature:core and uses its use cases. Provides the view. Knows only about its own :feature:core.
:entrypoint — module where dependency configuration and composition of views from :feature:presentation into a single Composable happens.
:platform — module that initializes the Composable provided by :entrypoint for each platform.

Arrows show the direction of dependencies.

How to structure your system?

Decide which features your app should have, then determine whether each feature has a UI:

If it does — it’s a feature.
If it doesn’t — it’s a service.
If one feature’s logic is needed by another — extract it into a separate service.

Important: both :service and :feature:core contain domain logic:

:service — core domain.
:feature:core — presentation domain (use cases).

Wrong:

:service:foo
:feature:foo:core
:feature:foo:presentation

Right:

:service:foo
:feature:bar:core
:feature:bar:presentation

Navigation in FLIP is just another feature. It aggregates and routes views passed as lambda slots, keeping it independent from other features.

NavigationView(
    splash = {
        SplashView(applicationScope = applicationScope)
    },
    profile = {
        ProfileView(applicationScope = applicationScope)
    }
)

This approach lets you add new screens without touching existing features.

A complete example is available in the official GitHub repository.

Essential Claude Code Skills for Mobile Developers

Thu, 02 Apr 2026 07:22:03 +0000

Claude Code skills are packaged folders of instructions, scripts and resources that teach the AI coding agent how to perform specialised tasks.

Each skill has a SKILL.md file containing YAML metadata and step by step instructions. Claude scans the names and descriptions of installed skills and loads the full content only when your request matches.

Because skills are part of an open standard adopted by multiple agent frameworks, a single skill can work across Claude Code, OpenAI Codex, Cursor and other tools.

Installing Claude Code skills

Skills can be installed globally or per project. Personal skills go into ~/.claude/skills/ and become available across all your projects, while project specific skills live in .claude/skills/ inside your repository so everyone who clones the repo can use them.

Most skills are plain Markdown folders: clone the repository and copy the skill directory into the appropriate folder. For example, the Swift Development skill’s README shows that you can install it by copying the Swift Development skill directory into ~/.claude/skills/ and then invoking it via /swift-development.

Recommended skills for mobile developers

Below is a curated list of Claude Code skills that are particularly valuable for mobile developers working with native iOS, Android or Kotlin Multiplatform (KMP). The list covers a range of design and development tasks. Each skill is linked to its repository or marketplace page along with a brief description.

Swift Development
https://github.com/hmohamed01/swift-development
This comprehensive skill turns Claude into a competent Swift engineer. It packages patterns for SwiftUI navigation, concurrency (async/await, actors) and testing frameworks, along with helper scripts for building, running tests, formatting code and managing simulators. Installation is simple: copy the Swift Development directory into your personal skills folder and invoke it with /swift-development.

iOS Mobile Design
https://mcpmarket.com/tools/skills/ios-mobile-design
For designers and developers building polished iOS apps, this skill provides expert guidance on Apple’s Human Interface Guidelines. It teaches Claude how to apply SwiftUI layout systems, dynamic type, SF Symbols and modern navigation patterns so interfaces feel native to iPhone, iPad and visionOS. Key features include accessible design with dynamic type, responsive layouts, Material You style theming and Dark Mode optimisation.

iOS App Builder
https://mcpmarket.com/tools/skills/ios-app-builder
This skill transforms Claude into a senior iOS developer who builds and ships native apps using a command line only workflow. It uses Xcode’s xcodebuild and simctl tools to scaffold projects, run tests and launch apps without opening Xcode. The skill emphasises a “prove, don’t promise” methodology: it verifies logic through tests and simulator screenshots, manages the full app life cycle from scaffolding to App Store readiness and includes features like performance profiling and memory leak detection

SwiftUI agent skill
https://github.com/twostraws/swiftui-agent-skill
A SwiftUI skill create by Paul Hudson (hacking with swift).
This skill helps identify and fix common mistakes AI agents make when writing SwiftUI – things like modern API usage, performance, accessibility, and more.

Android Development
https://github.com/dpconde/claude-android-skill
Designed for modern Android projects, this skill teaches Claude clean architecture with separate UI, domain and data layers. It covers Jetpack Compose patterns and best practices, multi module project structures, offline first architecture using Room and reactive streams, dependency injection with Hilt and comprehensive testing strategies. After cloning the repository into your skills folder, you can ask the agent to scaffold features, create Compose screens or set up repositories following Android best practices.

Android Kotlin Development
https://fastmcp.me/skills/details/241/android-kotlin-development
This skill focuses on building native Android apps with Kotlin. The description explains that it covers Model-View-ViewModel architecture with Jetpack, Compose for declarative user interfaces, Retrofit for API calls, Room for local storage and navigation patterns. It includes detailed instructions and code samples for models, API services and MVVM view models, making it a practical guide for Kotlin developers.

Mobile Android Design
https://fastmcp.me/skills/details/644/mobile-android-design
When you need to design Android interfaces that follow Google’s Material Design 3 guidelines, this skill is indispensable. It teaches Claude how to build adaptive layouts with Jetpack Compose, implement navigation patterns like bottom navigation and drawers, use dynamic colour and Material You theming, and create accessible UI for phones, tablets and foldables. It is especially helpful for modernising existing apps or ensuring new designs comply with Material Design principles.

Jetpack Compose Expert
https://github.com/aldefy/compose-skill
This skill provides Claude with real source code and extensive reference guides for Jetpack Compose. Without it, AI tools often misuse remember, generate inefficient recompositions or misorder modifiers; with the skill, Claude picks the right state primitive, applies stability annotations and orders modifiers correctly. The reference guides cover state management, view composition, performance, navigation, animation, lists, side effects, modifiers, theming, accessibility and deprecated patterns. Installation requires cloning the repository and copying the Jetpack Compose expert skill directory into your skills folder; Claude will automatically activate it when you mention Compose or related API names.

Kotlin Multiplatform (KMP) Abstraction Guide
https://fastmcp.me/skills/details/2190/kotlin-multiplatform
KMP projects often involve tough decisions about what to share between platforms and what to keep platform specific. This skill guides those decisions by providing a platform abstraction decision tree. It explains when to use commonMain, jvmAndroid or expect/actual patterns, covers targets like Android, JVM/Desktop and iOS, and offers triggers for questions such as "should I share this ViewModel?". It helps developers place code correctly and prepare for future web or WebAssembly targets.

Essential RSS Feeds for Mobile Developers

Tue, 06 Jan 2026 21:55:48 +0000

Keeping up with mobile development requires a steady flow of high quality information. RSS feeds are still one of the best ways to follow platform updates, deep technical articles, and long form insights without relying on social media algorithms.

What are RSS feeds

RSS stands for Really Simple Syndication.
An RSS feed is a constantly updated stream of content published by a website. Instead of visiting dozens of sites every day, you subscribe to their feeds and read all new articles in one place.

When a site publishes a new post, it automatically appears in your RSS reader. No algorithms, no distractions, no missing important updates.

RSS is especially useful for developers because it lets you follow official blogs, deep technical articles, and long form content in a clean chronological order.

How to read RSS feeds

To read RSS feeds you need an RSS reader. An RSS reader is an app or web service where you add feed links and read new posts as they appear.

You copy the feed URL and add it to the reader. From that moment on, new articles show up automatically.

A curated list of essential RSS feeds for mobile developers

Android Developers Blog
https://android-developers.googleblog.com/atom.xml
The official Android Developers Blog published by Google. It covers platform changes, new APIs, tooling updates, Jetpack libraries, performance improvements, and long term Android roadmap insights.

Google Android Medium Publication
https://medium.com/feed/androiddevelopers
Articles written by Android engineers at Google and the community. Often complements the official Android Developers Blog with practical examples and deep dives.

Android Weekly
https://androidweekly.net/rss.xml
A weekly curated newsletter with links to the best Android articles, libraries, tools, and open source projects. Very useful for discovering high quality content you might otherwise miss.

AppCoda
https://www.appcoda.com/rss/
A popular blog focused mainly on iOS development. It provides practical tutorials on Swift, SwiftUI, UIKit, and Apple platform APIs with clear explanations and code examples.

Apple Developer News
http://developer.apple.com/news/rss/news.rss
The official Apple developer feed. It includes announcements about SDK changes, App Store policies, WWDC updates, platform releases, and new Apple frameworks.

iOS Dev Weekly
https://iosdevweekly.com/issues.rss
A long running weekly newsletter curated by Dave Verwer. It aggregates the best iOS development articles, tools, libraries, and discussions from across the community.

Kotlin Blog by JetBrains
https://blog.jetbrains.com/kotlin/feed/
The official Kotlin blog by JetBrains. It covers Kotlin language evolution, Kotlin Multiplatform updates, compiler changes, and best practices relevant to Android and cross platform development.

ProMobile.Dev
https://promobile.dev/feed
A focused feed covering mobile development news, articles and tutorials across Android, iOS, and Kotlin Multiplatform.

Swift.org Blog
https://www.swift.org/atom.xml
The official Swift language blog. It publishes proposals, language evolution updates, compiler changes, and announcements relevant to Swift developers on all platforms.

Use Your Loaf
https://useyourloaf.com/blog/rss.xml
An iOS focused blog with deep dives into Apple frameworks, APIs, and platform behavior. Known for clear explanations and attention to technical detail.

Paul Hudson - Hacking with Swift
https://www.hackingwithswift.com/articles/rss
High quality Swift and iOS development content ranging from beginner to advanced topics, written clearly and consistently updated.

Type-safe Kotlin Multiplatform i18n: auto-convert Android strings to cross-platform translations.

Tue, 14 Oct 2025 23:22:55 +0000

i18nKonfig — Zero-Config Internationalization for Kotlin Multiplatform

Tired of juggling strings.xml, runtime crashes, and messy translation setups?
I built i18nKonfig, a Gradle plugin that turns your Android strings into type-safe, multiplatform translations — automatically

From this:
getString(R.string.welcome_message, userName)

To this:
Text(I18nKonfig.welcome_message)

Works across Android, iOS, Desktop & Web
Compile-time safety (no missing strings)
Auto-migrates your Android resources
Zero manual setup — just ./gradlew build

I haven’t released it yet — just testing community interest.
Would you use something like this in your KMP projects? Or even help shape the first release?

ImagePickerKMP 1.0.23: Controling Camera Launch on iOS with directCameraLaunch

Wed, 03 Sep 2025 05:56:05 +0000

ImagePickerKMP 1.0.23: Controling Camera Launch on iOS with `directCameraLaunch`

The latest release of ImagePickerKMP (v1.0.23) brings a small but
powerful addition for iOS developers: a new flag called
directCameraLaunch.

This feature gives you control over whether the image picker should
open directly into the camera or show the source selection
dialog first.

The New Flag: `directCameraLaunch`

By default, the picker shows a dialog on iOS asking the user to choose
between camera and gallery.\
With directCameraLaunch, you can now change that behavior:

directCameraLaunch = true → Skips the dialog and opens the
camera immediately.\
directCameraLaunch = false → Keeps the dialog so the user can
choose.

Usage Example

Here's how you can use it with ImagePickerLauncher in your Compose
Multiplatform project:

    ImagePickerLauncher(
        config = ImagePickerConfig(
            onPhotoCaptured = { result ->
                capturedPhoto = result
                showCamera = false
            },
            onError = {
                showCamera = false
            },
            onDismiss = {
                showImagePicker = false // Reset state when user doesn't select anything
            },
            directCameraLaunch = false // Set to true if you want to launch the camera directly Only IOS
        )
    )

Why This Matters

This new option provides better UX flexibility:

Apps that want a streamlined flow (e.g., scanning receipts, IDs, QR
codes) can go straight to the camera.\
Apps that want to offer both gallery and camera selection can keep
the dialog.

In short: you now have the best of both worlds, controlled with a simple
flag.

Dependency

To try it out, update your Gradle dependency to the latest version:

dependencies {
    implementation("io.github.ismoy:imagepickerkmp:1.0.23")
}

Final Thoughts

The directCameraLaunch flag makes ImagePickerKMP even more versatile
for real-world use cases. Whether your app prioritizes fast camera
access or user choice, you can now support both seamlessly with version
1.0.23.

Are you planning to use directCameraLaunch in your project? Would you
prefer the dialog or direct camera launch by default?

Github: https://github.com/ismoy/ImagePickerKMP

Coder Legion - Recent posts tagged kmp

Why BasicTextField Fails at Scale — And How I Build Kortex

Reaching sub-millisecond input latency on 100K-line files using Kotlin Multiplatform, Skia, and Virtualized canvas layers

1. The Core Philosophy: Zero Composable-Per-Line Overhead

The Layered Rendering Pipeline

2. Backed by Krope: Logarithmic Text Mutations

3. Killing GC Pauses with Bounded Native LRU Caches

4. Viewport Virtualization & Logarithmic Code Folding (FoldMap)

5. Pure Unidirectional MVI & Smart Undo/Redo Coalescing

6. Full IDE Tooling: Async Analysis, Squiggles & Hierarchical Themes

Debounced Coroutine Pipelines

Hierarchical Token Theming

Getting Started in 30 Seconds

Explore the Source Code

Kempo: Real-Time Audio Time-Stretching, Pitch-Shifting, and Formant Control in Pure KMP

Zero-allocation streaming, phase-locked clarity, and multichannel spatial coherence across JVM, Android, iOS, and WebAssembly.

What Kempo Brings to Your Audio Stack

How Kempo Keeps Audio Crisp (Without the Artifacts)

1. Eliminating Transient Smearing with Vertical Phase-Locking

2. Fixing the "Chipmunk" Effect with Formant Decoupling

3. Preserving Stereo Width and 5.1 Surround Imaging

Getting Started

1. The One-Liner: Offline Track Processing

2. Zero-Allocation Real-Time Streaming

3. Sample-Accurate Offline Rendering with exact()

4. Custom Frequency Mapping & Tonality Limits

Engineered for Speed in Pure Kotlin

Try It Live: The Compose Desktop Studio App

Explore the Code

Why HTTPS Won’t Save Your Checkout Flow: Building Zero-Trust State Machines in Kotlin Multiplatform

How to protect multi-step workflows, fintech funnels, and Server-Driven UI from step-skipping, state tampering, and replay attacks — with zero runtime dependencies.

The Mental Model: Think "Git Commits" for Your App State

Designing for Zero Bloat: The Core Primitives

1. VerifiableBlock

2. DeltaBlock (Signed Partial Updates)

3. Pure Functional Reduction

Real-World Walkthrough: The Unbreakable Checkout

The Legitimate User Journey

Simulating the Attack: Skipping Shipping

Built for Developer Ergonomics

Where Does TrustChain Shine?

Try It in Your Project

Telemetry: Shared Analytics and Crash Reporting in Kotlin Multiplatform

What I had before

The interface lives in commonMain

Android: the easy side

iOS: the Swift bridge

Two other ways to bring the SDK in

Kotlin exceptions on iOS are not Kotlin exceptions

Where the calls go

Gotchas

Wrapping up

Minimum Weight: Code Coverage Gates in Kotlin Multiplatform with Kover

The number was lying before it was useful

Coverage across more than one module

Excluding the honest way

The floor that only goes up

Wiring it into CI

The line I hold

Same Car, Every Time: Deterministic Feature Module Generation in KMP

The thing I actually wanted was not intelligence

What the script generates

Guardrails come before generation

Then I needed one module, not three

Conditionals are where the real work is

The one clever bit, and its escape hatch

What it deliberately refuses to do

When I still reach for the AI

Wrapping up

Two Racing Lines: Annotations and the DSL in NetFlow 0.7.0

The reflex

Rung one: the return type picks the strategy

What the processor actually writes

The decision that matters: no transform in annotations

The paged endpoint is one line

Rung two: NetFlowCall

Rung three: the call {} DSL

Three rungs, or three libraries

Generating into commonMain with KSP

The line I hold

4. Viewport Virtualization & Logarithmic Code Folding (`FoldMap`)

3. Sample-Accurate Offline Rendering with `exact()`

1. `VerifiableBlock`

2. `DeltaBlock` (Signed Partial Updates)

The problem with `sharedLogic` and `sharedUI`

FLIP: the next step after `sharedLogic`

ImagePickerKMP 1.0.23: Controling Camera Launch on iOS with `directCameraLaunch`

The New Flag: `directCameraLaunch`