capacitor-lottie-splash 0.1.0

package/android/src/main/java/com/headcount/plugins/lottiesplash/LottieSplashCoordinator.kt

@@ -0,0 +1,498 @@
+package com.headcount.plugins.lottiesplash
+
+import android.animation.ValueAnimator
+import android.content.Context
+import android.graphics.Color
+import android.graphics.drawable.GradientDrawable
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import android.view.Gravity
+import android.view.View
+import android.view.ViewGroup
+import android.view.animation.AccelerateDecelerateInterpolator
+import android.view.animation.LinearInterpolator
+import android.widget.Button
+import android.widget.FrameLayout
+import android.widget.LinearLayout
+import android.widget.TextView
+import com.airbnb.lottie.LottieAnimationView
+import com.airbnb.lottie.LottieCompositionFactory
+import androidx.activity.ComponentActivity
+import java.util.UUID
+import kotlin.math.max
+import kotlin.math.roundToInt
+
+enum class AndroidSplashPhase { PREPARING, PLAYING, HOLDING, HIDING, HIDDEN, RECOVERY }
+enum class AndroidSplashPlayback { PLAY, HOLD_FINAL_FRAME }
+
+/** A small indeterminate rail that reads as loading without covering the finished logo. */
+private class LottieSplashLoadingRail(context: Context, darkTheme: Boolean) : FrameLayout(context) {
+    private val segment = View(context)
+    private var sweep: ValueAnimator? = null
+
+    init {
+        contentDescription = "Application is still loading"
+        importantForAccessibility = View.IMPORTANT_FOR_ACCESSIBILITY_YES
+        background = GradientDrawable().apply {
+            cornerRadius = dp(2).toFloat()
+            setColor(if (darkTheme) Color.argb(46, 255, 255, 255) else Color.argb(36, 0, 0, 0))
+        }
+        segment.background = GradientDrawable().apply {
+            cornerRadius = dp(2).toFloat()
+            setColor(Color.argb(230, 255, 77, 77))
+        }
+        clipToOutline = true
+        addView(segment, LayoutParams(dp(37), LayoutParams.MATCH_PARENT))
+    }
+
+    override fun onSizeChanged(width: Int, height: Int, oldWidth: Int, oldHeight: Int) {
+        super.onSizeChanged(width, height, oldWidth, oldHeight)
+        // The parent is sized before its segment completes layout. Deferring one frame makes
+        // the sweep start from the segment's real width rather than silently staying static.
+        post { startSweepIfReady() }
+    }
+
+    override fun onDetachedFromWindow() {
+        sweep?.cancel()
+        sweep = null
+        super.onDetachedFromWindow()
+    }
+
+    private fun startSweepIfReady() {
+        if (width <= 0 || segment.width <= 0 || sweep != null) return
+        sweep = ValueAnimator.ofFloat(-segment.width.toFloat(), width.toFloat()).apply {
+            duration = 1_150L
+            repeatCount = ValueAnimator.INFINITE
+            interpolator = LinearInterpolator()
+            addUpdateListener { segment.translationX = it.animatedValue as Float }
+            start()
+        }
+    }
+
+    private fun dp(value: Int): Int = (value * resources.displayMetrics.density).roundToInt()
+}
+
+/** One process-wide coordinator owns the native cover and its presentation generation. */
+object LottieSplashCoordinator {
+    // A Capgo bundle from before this plugin existed cannot call show() to adopt this cover.
+    // Release it after a short grace period rather than trapping the app during a staged rollout.
+    // HeadCount's real cold start can take longer than ten seconds before Angular reaches its
+    // first bridge call. Keep a bounded escape hatch for an old over-the-air bundle without
+    // incorrectly dismissing a healthy native cover during that startup work.
+    private const val WEB_ADOPTION_GRACE_MS = 30_000L
+    private const val PROGRESS_DELAY_MS = 1_000L
+    private const val RECOVERY_DELAY_MS = 15_000L
+    private const val COVER_FADE_OUT_MS = 500L
+    private val main = Handler(Looper.getMainLooper())
+
+    private var cover: FrameLayout? = null
+    private var animation: LottieAnimationView? = null
+    private var hostActivity: ComponentActivity? = null
+    private var hostForeground = false
+    private var systemHandoffComplete = true
+    private var compositionReady = false
+    private var requestedPlayback = AndroidSplashPlayback.PLAY
+    private var loadingRail: LottieSplashLoadingRail? = null
+    private var recoveryMessage: TextView? = null
+    private var recoveryRetry: Button? = null
+    private var presentationId: String? = null
+    private var phase = AndroidSplashPhase.HIDDEN
+    private var playbackSettled = false
+    private var appReady = false
+    private var darkTheme = true
+    private var playbackOutcome = "static-fallback"
+    private var playbackReason: String? = null
+    private var completion: ((String, String?) -> Unit)? = null
+    private var pendingHide: ((Throwable?) -> Unit)? = null
+    private var progressTask: Runnable? = null
+    private var recoveryTask: Runnable? = null
+    private var adoptionTask: Runnable? = null
+    private var adoptedByWeb = false
+    private var progressRemainingMs = PROGRESS_DELAY_MS
+    private var recoveryRemainingMs = RECOVERY_DELAY_MS
+    private var waitingClockStartedAtMs = 0L
+    private var waitingClockRunning = false
+
+    var onStateChange: (() -> Unit)? = null
+    var onRecoveryRequested: (() -> Unit)? = null
+
+    /**
+     * Called by AndroidX while deciding whether its system-owned launch surface may leave.
+     *
+     * Ownership is enough here: waiting for `isAttachedToWindow` can deadlock this handoff,
+     * because the keep condition runs before the first layout pass that would report that
+     * attachment. The activity identity still prevents a cover left by an older host from
+     * releasing a new activity's system splash.
+     */
+    @JvmStatic fun isCoverAttached(activity: ComponentActivity): Boolean =
+        hostActivity === activity && cover != null
+
+    /** Attach an opaque presentation to any host activity. */
+    @JvmStatic
+    fun attachCover(
+        activity: ComponentActivity,
+        darkTheme: Boolean = true,
+        playback: AndroidSplashPlayback = AndroidSplashPlayback.PLAY,
+        dismissWhenUnadopted: Boolean = false
+    ) {
+        if (cover != null && hostActivity === activity) return
+        if (cover != null) discardHost(hostActivity)
+        val root = activity.findViewById<ViewGroup>(android.R.id.content) ?: return
+        this.darkTheme = darkTheme
+        hostActivity = activity
+        hostForeground = activity.hasWindowFocus()
+        systemHandoffComplete = !dismissWhenUnadopted
+        compositionReady = false
+        requestedPlayback = playback
+        presentationId = UUID.randomUUID().toString()
+        phase = AndroidSplashPhase.PREPARING
+        playbackSettled = false
+        appReady = false
+        adoptedByWeb = false
+        playbackOutcome = "static-fallback"
+        playbackReason = null
+        loadingRail = null
+        recoveryMessage = null
+        recoveryRetry = null
+
+        val backgroundStart = if (darkTheme) Color.rgb(30, 30, 30) else Color.rgb(240, 240, 240)
+        root.setBackgroundColor(backgroundStart)
+        activity.window.decorView.setBackgroundColor(backgroundStart)
+
+        val overlay = FrameLayout(activity).apply {
+            layoutParams = ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
+            isClickable = true
+            isFocusable = true
+            contentDescription = "Loading application"
+            alpha = 1f
+            background = GradientDrawable(
+                GradientDrawable.Orientation.LEFT_RIGHT,
+                if (darkTheme) intArrayOf(backgroundStart, Color.rgb(37, 37, 37))
+                else intArrayOf(Color.rgb(240, 240, 240), Color.rgb(245, 245, 245))
+            )
+        }
+        val lottie = LottieAnimationView(activity).apply {
+            layoutParams = FrameLayout.LayoutParams(0, 0, Gravity.CENTER)
+            repeatCount = 0
+        }
+        overlay.addView(lottie)
+        root.addView(overlay)
+        overlay.addOnLayoutChangeListener { _, _, _, _, _, _, _, _, _ -> updateAnimationLayout(overlay, lottie) }
+        overlay.post { updateAnimationLayout(overlay, lottie) }
+        cover = overlay
+        animation = lottie
+        if (dismissWhenUnadopted) scheduleUnadoptedFallback(presentationId!!)
+        emit()
+
+        // Keep the cover unbranded while the composition is prepared. A completed-frame bitmap
+        // here made the launch look like a separate, static logo screen before the animation.
+        // Lottie parses asynchronously; the first artwork the user sees is therefore the
+        // animation's own first visible frame.
+        val id = presentationId ?: return
+        LottieCompositionFactory.fromAsset(activity, "lottie-splash/animatedLogo.json")
+            .addListener { composition ->
+                if (presentationId != id || cover !== overlay || hostActivity !== activity) return@addListener
+                lottie.setComposition(composition)
+                compositionReady = true
+                overlay.post {
+                    startPlaybackWhenVisible(id, overlay, lottie)
+                }
+            }
+            .addFailureListener {
+                if (presentationId == id && cover === overlay && hostActivity === activity) {
+                    settle("static-fallback", "Bundled animation unavailable")
+                }
+            }
+    }
+
+    fun show(activity: ComponentActivity, darkTheme: Boolean): Pair<String, Boolean>? {
+        val id = presentationId
+        if (id != null && cover != null) {
+            adoptedByWeb = true
+            adoptionTask?.let(main::removeCallbacks)
+            adoptionTask = null
+            return id to true
+        }
+
+        // A splash is also used around long-running in-app transitions. Once the cold-start
+        // cover has gone away, create a new presentation instead of rejecting the JS call.
+        attachCover(activity, darkTheme, AndroidSplashPlayback.PLAY, dismissWhenUnadopted = false)
+        return presentationId?.let { it to false }
+    }
+
+    /** The system-owned launch view has yielded; animation may start if the host is foreground. */
+    fun systemSplashDidExit(activity: ComponentActivity) {
+        if (hostActivity !== activity) return
+        systemHandoffComplete = true
+        val id = presentationId ?: return
+        val existingCover = cover ?: return
+        val existingAnimation = animation ?: return
+        startPlaybackWhenVisible(id, existingCover, existingAnimation)
+    }
+
+    fun waitForCompletion(id: String, callback: (String, String?) -> Unit) {
+        if (id != presentationId) return callback("static-fallback", "Stale splash presentation")
+        if (playbackSettled) callback(playbackOutcome, playbackReason) else completion = callback
+    }
+
+    fun hide(id: String, callback: (Throwable?) -> Unit) {
+        if (id != presentationId) return callback(IllegalStateException("Stale splash presentation"))
+        appReady = true
+        clearWaitingUi()
+        if (playbackSettled) dismiss(callback) else {
+            pendingHide = callback
+            emit()
+        }
+    }
+
+    /**
+     * The web layer has requested the handoff but its compositor has not acknowledged a frame
+     * yet. Stop recovery UI now, while preserving the opaque cover until hide() is called.
+     */
+    fun prepareForHide(id: String): Throwable? {
+        if (id != presentationId) return IllegalStateException("Stale splash presentation")
+        appReady = true
+        clearWaitingUi()
+        emit()
+        return null
+    }
+
+    fun state(): Map<String, Any?> = mapOf(
+        "presentationId" to presentationId,
+        "phase" to phase.name.lowercase(),
+        "visible" to (phase != AndroidSplashPhase.HIDDEN),
+        "playbackSettled" to playbackSettled,
+        "appReady" to appReady,
+        "theme" to if (darkTheme) "dark" else "light"
+    )
+
+    /** The host forwards onPause so playback and recovery timing count foreground time only. */
+    fun pause(activity: ComponentActivity) {
+        if (hostActivity !== activity) return
+        hostForeground = false
+        if (phase == AndroidSplashPhase.PLAYING) animation?.pauseAnimation()
+        if (phase == AndroidSplashPhase.HOLDING) pauseWaitingClock()
+    }
+
+    /** The host forwards onResume so foreground playback and timing can continue. */
+    fun resume(activity: ComponentActivity) {
+        if (hostActivity !== activity) return
+        hostForeground = true
+        val id = presentationId
+        val existingCover = cover
+        val existingAnimation = animation
+        if (phase == AndroidSplashPhase.PREPARING && id != null && existingCover != null && existingAnimation != null) {
+            startPlaybackWhenVisible(id, existingCover, existingAnimation)
+        } else if (phase == AndroidSplashPhase.PLAYING) animation?.resumeAnimation()
+        if (phase == AndroidSplashPhase.HOLDING) scheduleWaitingUi(presentationId ?: return)
+    }
+
+    /** Never retain views or callbacks from an activity that is being recreated or destroyed. */
+    fun destroy(activity: ComponentActivity) {
+        if (hostActivity === activity) discardHost(activity)
+    }
+
+    private fun startPlaybackWhenVisible(id: String, overlay: FrameLayout, lottie: LottieAnimationView) {
+        if (id != presentationId || cover !== overlay || animation !== lottie || !compositionReady || !hostForeground || !systemHandoffComplete || phase != AndroidSplashPhase.PREPARING) return
+        val composition = lottie.composition ?: return
+        phase = AndroidSplashPhase.PLAYING
+        emit()
+        val startFrame = composition.startFrame
+        val endFrame = composition.endFrame
+        if (requestedPlayback == AndroidSplashPlayback.HOLD_FINAL_FRAME) {
+            lottie.frame = endFrame.toInt()
+            settle("completed", null)
+        } else if (!ValueAnimator.areAnimatorsEnabled()) {
+            lottie.frame = endFrame.toInt()
+            settle("reduced-motion", "Android animations disabled")
+        } else {
+            lottie.setMinAndMaxFrame(startFrame.toInt(), endFrame.toInt())
+            lottie.frame = startFrame.toInt()
+            lottie.addAnimatorListener(object : android.animation.Animator.AnimatorListener {
+                override fun onAnimationStart(animation: android.animation.Animator) = Unit
+                override fun onAnimationCancel(animation: android.animation.Animator) {
+                    if (id == presentationId && phase == AndroidSplashPhase.PLAYING) settle("static-fallback", "Animation cancelled")
+                }
+                override fun onAnimationRepeat(animation: android.animation.Animator) = Unit
+                override fun onAnimationEnd(animation: android.animation.Animator) {
+                    if (id == presentationId) settle("completed", null)
+                }
+            })
+            lottie.playAnimation()
+        }
+    }
+
+    private fun updateAnimationLayout(overlay: FrameLayout, lottie: LottieAnimationView) {
+        if (cover !== overlay || animation !== lottie || overlay.width <= 0 || overlay.height <= 0) return
+        val availableWidth = minOf(overlay.width.toFloat(), overlay.height * 0.75f)
+        val side = (availableWidth * 0.35f).roundToInt().coerceAtLeast(1)
+        val params = lottie.layoutParams as FrameLayout.LayoutParams
+        if (params.width != side || params.height != side) {
+            params.width = side
+            params.height = side
+            params.gravity = Gravity.CENTER
+            lottie.layoutParams = params
+        }
+    }
+
+    private fun dp(view: View, value: Int): Int = (value * view.resources.displayMetrics.density).roundToInt()
+
+    private fun settle(outcome: String, reason: String?) {
+        if (playbackSettled || presentationId == null) return
+        playbackSettled = true
+        playbackOutcome = outcome
+        playbackReason = reason
+        phase = if (pendingHide != null) AndroidSplashPhase.HIDING else AndroidSplashPhase.HOLDING
+        completion?.invoke(outcome, reason)
+        completion = null
+        if (pendingHide != null) dismiss(pendingHide!!) else if (!appReady) resetWaitingUi(presentationId!!)
+        pendingHide = null
+        emit()
+    }
+
+    private fun resetWaitingUi(id: String) {
+        cancelWaitingTasks()
+        progressRemainingMs = PROGRESS_DELAY_MS
+        recoveryRemainingMs = RECOVERY_DELAY_MS
+        scheduleWaitingUi(id)
+    }
+
+    private fun scheduleUnadoptedFallback(id: String) {
+        adoptionTask?.let(main::removeCallbacks)
+        adoptionTask = Runnable {
+            if (presentationId == id && !adoptedByWeb) dismiss { }
+        }
+        main.postDelayed(adoptionTask!!, WEB_ADOPTION_GRACE_MS)
+    }
+
+    private fun scheduleWaitingUi(id: String) {
+        if (waitingClockRunning || presentationId != id || appReady || phase != AndroidSplashPhase.HOLDING) return
+        waitingClockRunning = true
+        waitingClockStartedAtMs = SystemClock.elapsedRealtime()
+        progressTask = Runnable { showLoadingRail(id) }
+        recoveryTask = Runnable { showRecovery(id) }
+        if (loadingRail == null) main.postDelayed(progressTask!!, progressRemainingMs)
+        main.postDelayed(recoveryTask!!, recoveryRemainingMs)
+    }
+
+    private fun pauseWaitingClock() {
+        if (!waitingClockRunning) return
+        val elapsed = SystemClock.elapsedRealtime() - waitingClockStartedAtMs
+        progressRemainingMs = max(0, progressRemainingMs - elapsed)
+        recoveryRemainingMs = max(0, recoveryRemainingMs - elapsed)
+        cancelWaitingTasks()
+    }
+
+    private fun cancelWaitingTasks() {
+        progressTask?.let(main::removeCallbacks)
+        recoveryTask?.let(main::removeCallbacks)
+        progressTask = null
+        recoveryTask = null
+        waitingClockRunning = false
+    }
+
+    private fun showLoadingRail(id: String) {
+        progressRemainingMs = 0
+        if (presentationId != id || appReady || phase != AndroidSplashPhase.HOLDING || loadingRail != null) return
+        val context = cover?.context ?: return
+        loadingRail = LottieSplashLoadingRail(context, darkTheme).also { rail ->
+            // Keep it below the composition's centered artwork, never layered over the tally.
+            cover?.addView(rail, FrameLayout.LayoutParams(dp(rail, 104), dp(rail, 3), Gravity.CENTER).apply {
+                topMargin = dp(rail, 100)
+            })
+        }
+    }
+
+    private fun showRecovery(id: String) {
+        recoveryRemainingMs = 0
+        if (presentationId != id || appReady || phase != AndroidSplashPhase.HOLDING) return
+        cancelWaitingTasks()
+        phase = AndroidSplashPhase.RECOVERY
+        loadingRail?.visibility = View.GONE
+        val context = cover?.context ?: return
+        val textColor = if (darkTheme) Color.WHITE else Color.rgb(30, 30, 30)
+        val message = TextView(context).apply { text = "Still starting…"; textSize = 16f; setTextColor(textColor); gravity = Gravity.CENTER }
+        val retry = Button(context).apply { text = "Try again"; setOnClickListener { onRecoveryRequested?.invoke() } }
+        val recoveryGroup = LinearLayout(context).apply {
+            orientation = LinearLayout.VERTICAL
+            gravity = Gravity.CENTER_HORIZONTAL
+            addView(message)
+            addView(retry)
+        }
+        recoveryMessage = message
+        recoveryRetry = retry
+        cover?.addView(recoveryGroup, FrameLayout.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT, Gravity.CENTER_HORIZONTAL or Gravity.BOTTOM).apply { bottomMargin = dp(recoveryGroup, 48) })
+        recoveryGroup.announceForAccessibility("Still starting. Try again is available.")
+        emit()
+    }
+
+    private fun clearWaitingUi() {
+        cancelWaitingTasks()
+        loadingRail?.let { cover?.removeView(it) }
+        recoveryMessage?.parent?.let { parent -> (parent as? ViewGroup)?.let { cover?.removeView(it) } }
+        loadingRail = null
+        recoveryMessage = null
+        recoveryRetry = null
+    }
+
+    private fun dismiss(callback: (Throwable?) -> Unit) {
+        val existingCover = cover ?: return callback(null)
+        phase = AndroidSplashPhase.HIDING
+        clearWaitingUi()
+        adoptionTask?.let(main::removeCallbacks)
+        adoptionTask = null
+        // Stop the renderer before animating the parent away. In particular, do not allow the
+        // Lottie canvas to keep a hardware buffer alive above the WebView after removal.
+        animation?.cancelAnimation()
+        animation?.clearAnimation()
+        existingCover.animate()
+            .alpha(0f)
+            .setDuration(if (ValueAnimator.areAnimatorsEnabled()) COVER_FADE_OUT_MS else 0)
+            .setInterpolator(AccelerateDecelerateInterpolator())
+            .withEndAction {
+            existingCover.clearAnimation()
+            existingCover.setLayerType(View.LAYER_TYPE_NONE, null)
+            val parent = existingCover.parent as? ViewGroup
+            parent?.removeView(existingCover)
+            // Removing a translucent native view does not always invalidate an underlying
+            // WebView immediately on Android. Request a fresh root frame before resolving hide.
+            parent?.requestLayout()
+            parent?.invalidate()
+            parent?.post { parent.invalidate() }
+            cover = null
+            animation = null
+            hostActivity = null
+            loadingRail = null
+            recoveryMessage = null
+            recoveryRetry = null
+            presentationId = null
+            phase = AndroidSplashPhase.HIDDEN
+            compositionReady = false
+            emit()
+            callback(null)
+        }.start()
+        emit()
+    }
+
+    private fun discardHost(activity: ComponentActivity?) {
+        if (activity == null) return
+        adoptionTask?.let(main::removeCallbacks)
+        adoptionTask = null
+        clearWaitingUi()
+        animation?.cancelAnimation()
+        animation?.clearAnimation()
+        cover?.let { existing -> (existing.parent as? ViewGroup)?.removeView(existing) }
+        cover = null
+        animation = null
+        hostActivity = null
+        presentationId = null
+        phase = AndroidSplashPhase.HIDDEN
+        compositionReady = false
+        pendingHide = null
+        completion = null
+        emit()
+    }
+
+    private fun emit() { onStateChange?.invoke() }
+}

package/android/src/main/java/com/headcount/plugins/lottiesplash/LottieSplashLaunch.kt

@@ -0,0 +1,72 @@
+package com.headcount.plugins.lottiesplash
+
+import android.content.Context
+import android.content.res.Configuration
+import androidx.activity.ComponentActivity
+import androidx.core.splashscreen.SplashScreen
+import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
+
+/** A host-defined Capacitor Preferences value available before the WebView starts. */
+class LottieSplashThemePreference @JvmOverloads constructor(
+    val key: String,
+    val darkValue: String,
+    val lightValue: String,
+    val storageName: String = "CapacitorStorage"
+)
+
+/** Host-only integration for one native splash presentation in the Capacitor activity. */
+object LottieSplashLaunch {
+    /**
+     * Call before super.onCreate() in the host activity. Android owns this first surface;
+     * it is retained only until the plugin's native cover has been added to the activity.
+     */
+    @JvmStatic fun installSystemSplashBeforeCreate(activity: ComponentActivity): SplashScreen =
+        activity.installSplashScreen().also { systemSplash ->
+            systemSplash.setKeepOnScreenCondition { !LottieSplashCoordinator.isCoverAttached(activity) }
+            systemSplash.setOnExitAnimationListener { provider ->
+                // The native cover is already fully opaque. Removing this system-owned surface
+                // immediately prevents a translucent crossfade from exposing a mismatched root.
+                provider.remove()
+                LottieSplashCoordinator.systemSplashDidExit(activity)
+            }
+        }
+
+    /**
+     * Attach the app-owned native cover before Capacitor constructs its bridge. The cover stays
+     * in this activity until the web layer has confirmed that its first route is ready to reveal.
+     */
+    @JvmStatic
+    fun attachNativeCover(activity: ComponentActivity, darkTheme: Boolean) {
+        LottieSplashCoordinator.attachCover(
+            activity = activity,
+            darkTheme = darkTheme,
+            playback = AndroidSplashPlayback.PLAY,
+            // An older over-the-air bundle cannot adopt a newly-installed native cover. Keep
+            // the bounded release path enabled so a staged rollout cannot trap the app here.
+            dismissWhenUnadopted = true
+        )
+    }
+
+    @JvmStatic
+    fun isSystemDark(activity: Context): Boolean =
+        (activity.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) == Configuration.UI_MODE_NIGHT_YES
+
+    @JvmStatic
+    fun resolveTheme(context: Context, preference: LottieSplashThemePreference): Boolean? {
+        val preferences = context.getSharedPreferences(preference.storageName, Context.MODE_PRIVATE)
+        return when (preferences.getString(preference.key, null)) {
+            preference.darkValue -> true
+            preference.lightValue -> false
+            else -> null
+        }
+    }
+
+    /** Forward the host activity lifecycle so recovery timing counts foreground time only. */
+    @JvmStatic fun onHostPaused(activity: ComponentActivity) = LottieSplashCoordinator.pause(activity)
+
+    /** Forward the host activity lifecycle so a paused animation can resume. */
+    @JvmStatic fun onHostResumed(activity: ComponentActivity) = LottieSplashCoordinator.resume(activity)
+
+    /** Release views and asynchronous work tied to an activity that is being destroyed. */
+    @JvmStatic fun onHostDestroyed(activity: ComponentActivity) = LottieSplashCoordinator.destroy(activity)
+}

package/android/src/main/java/com/headcount/plugins/lottiesplash/LottieSplashPlugin.kt

@@ -0,0 +1,121 @@
+package com.headcount.plugins.lottiesplash
+
+import android.app.UiModeManager
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import android.webkit.WebView
+import java.util.concurrent.atomic.AtomicBoolean
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+
+@CapacitorPlugin(name = "LottieSplash")
+class LottieSplashPlugin : Plugin() {
+    private companion object {
+        const val VISUAL_STATE_TIMEOUT_MS = 1_500L
+    }
+    override fun load() {
+        LottieSplashCoordinator.onStateChange = { notifyListeners("stateChange", stateObject()) }
+        LottieSplashCoordinator.onRecoveryRequested = { bridge?.webView?.reload() }
+    }
+
+    @PluginMethod
+    fun show(call: PluginCall) {
+        activity.runOnUiThread {
+            val darkTheme = call.getBoolean("darkMode") ?: LottieSplashLaunch.isSystemDark(activity)
+            val presentation = LottieSplashCoordinator.show(activity, darkTheme)
+                ?: return@runOnUiThread call.reject("Native splash has not been installed by the host activity")
+            val (id, adopted) = presentation
+            call.resolve(JSObject().put("presentationId", id).put("renderer", "android").put("adopted", adopted))
+        }
+    }
+
+    @PluginMethod
+    fun setLaunchTheme(call: PluginCall) {
+        val darkTheme = call.getBoolean("darkMode") ?: return call.reject("darkMode is required")
+        activity.runOnUiThread {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                val manager = activity.getSystemService(UiModeManager::class.java)
+                manager.setApplicationNightMode(
+                    if (darkTheme) UiModeManager.MODE_NIGHT_YES else UiModeManager.MODE_NIGHT_NO
+                )
+            }
+            call.resolve()
+        }
+    }
+
+    @PluginMethod
+    fun waitForCompletion(call: PluginCall) {
+        val id = call.getString("presentationId") ?: return call.reject("presentationId is required")
+        LottieSplashCoordinator.waitForCompletion(id) { outcome, reason ->
+            call.resolve(JSObject().put("presentationId", id).put("outcome", outcome).put("reason", reason))
+        }
+    }
+
+    @PluginMethod
+    fun hide(call: PluginCall) {
+        val id = call.getString("presentationId") ?: return call.reject("presentationId is required")
+        activity.runOnUiThread {
+            LottieSplashCoordinator.prepareForHide(id)?.let { error ->
+                call.reject(error.message)
+                return@runOnUiThread
+            }
+            val webView = bridge?.webView
+            if (webView == null) {
+                LottieSplashCoordinator.hide(id) { error -> resolveHide(call, error) }
+                return@runOnUiThread
+            }
+
+            // JavaScript's requestAnimationFrame only proves that a DOM frame was scheduled.
+            // Keep the native cover until WebView confirms that the sign-in DOM state has been
+            // composited; otherwise a busy cold start can reveal an empty white WebView.
+            val finished = AtomicBoolean(false)
+            val main = Handler(Looper.getMainLooper())
+            lateinit var fallback: Runnable
+            val finishHandoff = {
+                if (finished.compareAndSet(false, true)) {
+                    main.removeCallbacks(fallback)
+                    activity.runOnUiThread {
+                        LottieSplashCoordinator.hide(id) { error -> resolveHide(call, error) }
+                    }
+                }
+            }
+            fallback = Runnable { finishHandoff() }
+            try {
+                webView.postVisualStateCallback(SystemClock.uptimeMillis(), object : WebView.VisualStateCallback() {
+                    override fun onComplete(requestId: Long) = finishHandoff()
+                })
+                // A stalled GPU/compositor must not leave an app-ready screen in recovery.
+                main.postDelayed(fallback, VISUAL_STATE_TIMEOUT_MS)
+            } catch (_: Throwable) {
+                finishHandoff()
+            }
+        }
+    }
+
+    private fun resolveHide(call: PluginCall, error: Throwable?) {
+        if (error != null) {
+            call.reject(error.message)
+            return
+        }
+        // Ensure the WebView presents a fresh buffer after the native cover has been removed.
+        // This prevents a stale native composition region from obscuring sign-in controls.
+        bridge?.webView?.post {
+            val webView = bridge?.webView ?: return@post
+            webView.requestLayout()
+            webView.invalidate()
+            call.resolve()
+        } ?: call.resolve()
+    }
+
+    @PluginMethod fun getState(call: PluginCall) = call.resolve(stateObject())
+    @PluginMethod fun getCapabilities(call: PluginCall) = call.resolve(JSObject().put("apiVersion", 1).put("pluginVersion", "0.1.0").put("coldStartInstalled", LottieSplashCoordinator.state()["presentationId"] != null))
+
+    private fun stateObject(): JSObject = JSObject().apply {
+        LottieSplashCoordinator.state().forEach { (key, value) -> put(key, value) }
+    }
+}