SuperAPI AI Directory

kotlin-multiplatform-api-mimicry

Coding & development

View repository

Updated 11-17 19:30

About this skill

When to Use This Skill

Use this skill when you need to:

  • Build a Kotlin Multiplatform library on a non-standard runtime (a custom native renderer, a custom transport, a custom storage engine) and want its Kotlin API to feel like a well-known reference API (Jetpack Compose, SwiftUI, Retrofit, Room, ...) without literally depending on or reimplementing that library's internals
  • Design a chainable configuration object (a Modifier-equivalent) for a custom rendering or layout engine
  • Design a slot-lambda DSL (content: Scope.() -> Unit) for a custom scene-graph builder
  • Decide how far to take the mimicry — plain-function DSL vs. writing an actual Kotlin compiler plugin — before committing engineering time to either
  • Document, for future maintainers and for legal clarity, exactly which parts of a reference API were mimicked and which were deliberately changed

Do NOT use this skill when:

  • The project already depends on the real reference library (Compose Multiplatform, Ktor, etc.) and just needs to use it — that is ordinary consumption, not mimicry; see kotlin-multiplatform-design-system for building a design system on top of real Compose Multiplatform
  • The goal is a real Kotlin compiler plugin providing true fine-grained recomposition — that is a distinct, much larger undertaking this skill deliberately does not cover; it only tells you when that investment is actually justified (see Decision Table below)
  • The goal is copying the reference library's actual source code under a new package — never do this; see Guidelines

Trigger keywords: mimic api, api mimicry, clone api shape, inspired by jetpack compose, custom dsl engine, from-scratch renderer, vulkan ui, metal ui, port api ergonomics, reimplement compose-like dsl, non-compose renderer, engine-agnostic dsl, own compiler-free dsl, api shape porting.

Freshness rule: the reference API you are mimicking changes between its own releases (Jetpack Compose's Modifier and CompositionLocal surface, SwiftUI's ViewBuilder, etc.) — re-read the reference API's current public docs before mimicking a new version's shape. Never mimic from memory or from an old cached understanding of the reference API; verify against its real current source or docs.


Recommendation First

Default to this approach:

  1. Catalog the reference API's real public surface first — read its actual current docs/source, don't guess. List the specific types/functions/annotations you intend to mimic.
  2. Mimic ergonomics, not internals. A chainable Modifier-style object and a slot-lambda DSL are cheap to mimic faithfully with plain Kotlin. Recomposition, snapshot state, and skipping are not — they depend on the reference's own compiler plugin. Default to a plain-function DSL with explicit invalidation, not a fake compiler plugin.
  3. Never reuse the reference library's package namespace or literal branding. Own group id, own package, own annotation name (@EngineUiDsl, not @Composable).
  4. Write a mirror map (MIRROR_MAP.md) documenting each mimicked primitive, its inspiration, and the deliberate deviation — before writing the second mimicked primitive, not after the tenth.

Why:

  • most of a reference API's ergonomics (chainable config, slot lambdas, scoped builders) come from ordinary Kotlin language features, not compiler magic — you get 90% of the developer-experience win for a fraction of the effort
  • a real compiler plugin is a permanent maintenance burden riding on your own fork of Kotlin compiler internals — only justified when fine-grained recomposition is a measured, not assumed, performance requirement
  • consumers who see @Composable-shaped code assume @Composable-shaped guarantees; an undocumented gap between mimicked ergonomics and real behavior is where the bug reports come from
// Own annotation, own package — not androidx.compose.runtime.Composable
@DslMarker
annotation class EngineUiDsl

@EngineUiDsl
sealed interface EngineModifier {
    fun then(other: EngineModifier): EngineModifier =
        if (other is EngineModifier.None) this else CombinedEngineModifier(this, other)
    object None : EngineModifier
}

Core Pattern: Mapping Reference Primitives to Plain Kotlin

This method applies to any reference API — the table below uses Jetpack Compose as the running example because it has the richest primitive set (DSL, chain object, scoped ambient values, state), not because this skill is Compose-specific. See "Other reference APIs, same method" below for non-UI examples.

Reference primitive (e.g. Jetpack Compose) What actually powers it Mimicable without a compiler plugin? Kotlin equivalent
@Composable function Compose compiler plugin (call-site tracking, skipping) No — mimicking the annotation without the plugin gives you a plain function call, not real skipping Own marker annotation (@EngineUiDsl) used as documentation only; be explicit it's not enforced
Modifier chain Plain immutable linked-list-style object with then() Yes, fully Sealed interface + then(), exactly Compose's own shape — no magic involved
Slot lambda (content: @Composable () -> Unit) Trailing lambda + receiver scope, a plain language feature Yes, fully fun Box(content: EngineScope.() -> Unit)
CompositionLocal Compose runtime's ambient value propagation through the composition tree No — depends on the runtime tracking a composition tree Explicit scope object threaded as a parameter, or a plain ThreadLocal/context object if the design tolerates it
remember { } / mutableStateOf Compose's snapshot state system + recomposition scheduler No — reimplementing snapshot state from scratch is a multi-month undertaking An explicit state holder bound to your own render loop's invalidation call (requestRedraw()); callers manage identity/keys themselves
LaunchedEffect / lifecycle-scoped coroutines Compose runtime lifecycle integration Partially Your own scene-graph node lifecycle + CoroutineScope bound to node attach/detach

Decision Table: plain-function DSL vs. real compiler plugin

Signal Choose
Ergonomics (chainable modifiers, slot DSL, readable call sites) is the goal Plain-function DSL — covers this fully
Fine-grained recomposition/skipping is a measured perf requirement, not assumed Real compiler plugin — but treat this as its own multi-month project, not an extension of this skill
Team size / maintenance budget for owning Kotlin compiler plugin internals long-term If small, plain-function DSL — a compiler plugin tracks Kotlin compiler versions forever
Consumers must be able to write literal @Composable functions and get real Compose semantics Neither — depend on real Compose Multiplatform instead; mimicry no longer applies

Other reference APIs, same method

Jetpack Compose is one example, not the scope of this skill. The same catalog → map → decide → mirror-map method applies to any reference API's ergonomics:

Reference API mimicked What's mimicked (ergonomics, not internals) What's explicitly not mimicked
Retrofit-style declarative service interfaces interface-with-annotated-methods DSL, generating a typed client at your call boundary Retrofit's actual annotation processor / CallAdapter machinery — write a plain factory function instead
Room-style DAO annotations @Dao-shaped method-per-query interface as the ergonomic surface Room's KSP-generated implementation — back it with your own hand-written or codegen'd implementation for your storage engine
SwiftUI's ViewBuilder/declarative tree Trailing-closure-equivalent slot lambdas, same as the Compose row above SwiftUI's own diffing/identity system
Jetpack Compose (worked example below) Modifier chain, slot lambdas, DSL marker annotations Snapshot state, recomposition, CompositionLocal propagation

Worked example: Vulkan-backed UI DSL inspired by Jetpack Compose

One concrete instance of the method above — not the only valid target for this skill. A KMM library wraps a custom Vulkan rendering backend (via expect/actual + JNI/cinterop — see kotlin-multiplatform-jni-pro and kotlin-multiplatform-expect-actual) and needs a Compose-shaped declarative UI layer on top of it.

Naming below uses a generic Engine placeholder — pick your own project's actual prefix instead. Do not literally fuse your backend's brand name with the reference API's own type name (e.g. do not name it VulkanModifier just because the backend is Vulkan and the mimicked type is Compose's Modifier) unless that fusion is genuinely your project's established naming convention — it usually isn't, and reads as if it were copied from a real, verified source when it's just this example's placeholder.

// :library/src/commonMain/kotlin/.../EngineModifier.kt
@EngineUiDsl
sealed interface EngineModifier {
    object None : EngineModifier
}

private data class CombinedEngineModifier(
    val outer: EngineModifier,
    val inner: EngineModifier,
) : EngineModifier

fun EngineModifier.padding(all: Dp): EngineModifier = this.then(PaddingModifier(all))
fun EngineModifier.size(width: Dp, height: Dp): EngineModifier = this.then(SizeModifier(width, height))

// :library/src/commonMain/kotlin/.../EngineScope.kt
class EngineScope internal constructor(private val node: SceneNode) {

    @EngineUiDsl
    fun Box(modifier: EngineModifier = EngineModifier.None, content: EngineScope.() -> Unit) {
        val child = node.addChild(SceneNode.Kind.Box, modifier)
        EngineScope(child).content()
    }

    @EngineUiDsl
    fun Text(text: String, modifier: EngineModifier = EngineModifier.None) {
        node.addChild(SceneNode.Kind.Text(text), modifier)
    }
}

// Entry point — mirrors setContent { } shape, explicit invalidation instead of
// Compose's snapshot-driven recomposition
fun EngineCanvas.setContent(content: EngineScope.() -> Unit) {
    val root = SceneNode.root()
    EngineScope(root).content()
    this.submit(root)   // hands the built scene graph to the Vulkan backend
}

This gives callers Compose-shaped call sites (Box(modifier = ...) { Text("Hi") }) without claiming or requiring real Compose compiler behavior. State changes are the caller's responsibility — call setContent again (or a narrower invalidate()) to rebuild the affected subtree.


Guidelines

  • Never copy the reference library's actual source code under a renamed package — copyright and drift risk; re-derive the shape from its public docs instead
  • Never use the reference library's real package prefix (androidx.compose.*, com.squareup.retrofit2.*) or trademarked product name in your own artifact — own group id, own package, own name
  • Never apply the reference library's real annotation (@Composable) to functions your own compiler doesn't process — undefined/misleading behavior for any tooling that expects the real Compose compiler plugin
  • State plainly in the library's README that it is "API-shape-inspired by X, not compiler-compatible with X, no interop with real X code" — this is the single highest-value sentence for avoiding wrong-expectation bug reports
  • Keep a MIRROR_MAP.md at the library root: one row per mimicked primitive, its reference inspiration, and the deliberate deviation
  • This is almost always a library project (see kotlin-multiplatform-library-publishing), not an app — scaffold accordingly

Testing

class EngineModifierTest {
    @Test
    fun `then chains in call order`() {
        val modifier = EngineModifier.None.padding(8.dp).size(100.dp, 100.dp)
        val flattened = modifier.flatten()   // test helper walking the CombinedEngineModifier chain
        assertEquals(listOf("padding", "size"), flattened.map { it.name })
    }
}

class EngineScopeTest {
    @Test
    fun `Box adds a child scene node with its modifier`() {
        val root = SceneNode.root()
        EngineScope(root).apply {
            Box(modifier = EngineModifier.None.padding(4.dp)) {
                Text("hello")
            }
        }
        assertEquals(1, root.children.size)
        assertEquals(SceneNode.Kind.Box, root.children.single().kind)
        assertEquals(1, root.children.single().children.size)
    }

    @Test
    fun `setContent rebuilds the scene graph on each call`() {
        val canvas = FakeEngineCanvas()
        var label = "first"
        canvas.setContent { Text(label) }
        val firstSubmit = canvas.lastSubmittedRoot
        label = "second"
        canvas.setContent { Text(label) }
        assertNotSame(firstSubmit, canvas.lastSubmittedRoot)   // explicit rebuild, not diffed
    }
}

Common Anti-Patterns

  • Copy-pasting real Compose (or any reference library) source under a new package — license and drift risk; the copied code silently diverges from real semantics as the original library evolves. Re-derive the shape from public docs instead.
  • Claiming @Composable-compatible without a real compiler plugin — misleads consumers about recomposition/skipping guarantees they do not actually get; document the gap explicitly instead of implying parity.
  • Reimplementing Compose's full snapshot-state system "just in case" — a multi-month undertaking almost never justified by the actual requirement; an explicit requestRedraw()/rebuild model covers most custom-renderer needs.
  • Using the reference library's real annotation on non-reference functions — applying @Composable to a function your own tooling processes is undefined behavior for any real Compose tooling that later touches the same codebase.
  • Skipping the MIRROR_MAP.md — without it, consumers and future maintainers assume full behavioral parity with the reference API and file bugs against the wrong mental model; write it before the second mimicked primitive.
  • Reusing the reference library's package namespace (androidx.compose.*) to "borrow" IDE tooling or autocomplete — breaks real Compose compiler expectations if the real library is ever added to the same classpath, and is a trademark/namespace collision risk on publish.

Related Skills

  • kotlin-multiplatform-library-publishing — this is almost always a library project; publish it the same way as any other KMP library
  • kotlin-multiplatform-jni-pro — if the custom runtime is native (Vulkan, Metal via cinterop, etc.), the JNI/cinterop bridge for it lives here
  • kotlin-multiplatform-expect-actual — platform-specific backend wiring for the custom renderer
  • kotlin-multiplatform-design-system — use this instead when the target runtime is real Compose Multiplatform; that skill builds a design system on top of the real thing rather than mimicking its shape
  • kotlin-multiplatform-compose-slot-api — slot-lambda patterns for real Compose Multiplatform projects; this skill's slot-lambda guidance is the non-Compose analog
  • kotlin-multiplatform-clean-architecture — layer boundaries still apply inside the library even though there's no :ui/:presenter split in the app sense

Output Style

When asked about mimicking a reference API's shape, respond in this order:

  1. recommendation (plain-function DSL, not a compiler plugin, unless justified)
  2. the specific reference primitives being mapped, and their Kotlin equivalents
  3. code snippet (one chainable-modifier example + one slot-lambda example)
  4. what real behavior is explicitly NOT being mimicked (recomposition, skipping, etc.)
  5. main alternative (a real compiler plugin, or just depending on the real reference library)

Keep the snippet to one modifier chain and one slot function. Always name the specific reference API being mimicked when the user names one — do not speak generically about "a reference API" once a real one (Jetpack Compose, SwiftUI, ...) is named.


Changelog

Date Change
2026-07-31 Initial release.