capacitor-lottie-splash 0.1.2 → 0.1.4

package/README.md

@@ -101,9 +101,9 @@ The documented HeadCount defaults are light `#f0f0f0 → #f5f5f5` and dark `#1e1
 
 ## Recovery and accessibility
 
-When playback completes before readiness, its final frame holds. After one second, a subtle indeterminate progress rail appears beneath the mark. After 15 foreground seconds the rail stops and a native/browser recovery surface presents “Still starting…” and “Try again.” The native retry reloads the WebView, so it does not depend on JavaScript having already loaded. Reduced-motion and asset failures retain the theme-matched native cover instead of exposing a blank screen.
+Each presentation fades in over 500 milliseconds before Lottie playback begins, then fades out over 500 milliseconds when the application is ready. When playback completes before readiness, its final frame holds. After one second, a subtle indeterminate progress rail appears beneath the mark and remains visible until the application is ready. Reduced-motion and asset failures retain the theme-matched native cover instead of exposing a blank screen.
 
-For a staged native/over-the-air rollout, the consuming app must keep its web bundle and native host compatible. The native cover stays visible until the app-ready latch is set; a broken boot transitions to the visible recovery surface instead of exposing a blank page.
+For a staged native/over-the-air rollout, the consuming app must keep its web bundle and native host compatible. The native cover stays visible until the app-ready latch is set.
 
 ## Compatibility
 

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

@@ -12,10 +12,7 @@ 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
@@ -23,7 +20,7 @@ import java.util.UUID
 import kotlin.math.max
 import kotlin.math.roundToInt
 
-enum class AndroidSplashPhase { PREPARING, PLAYING, HOLDING, HIDING, HIDDEN, RECOVERY }
+enum class AndroidSplashPhase { PREPARING, PLAYING, HOLDING, HIDING, HIDDEN }
 enum class AndroidSplashPlayback { PLAY, HOLD_FINAL_FRAME }
 
 /** A small indeterminate rail that reads as loading without covering the finished logo. */
@@ -82,7 +79,7 @@ object LottieSplashCoordinator {
     // 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_IN_MS = 500L
     private const val COVER_FADE_OUT_MS = 500L
     private val main = Handler(Looper.getMainLooper())
 
@@ -92,10 +89,10 @@ object LottieSplashCoordinator {
     private var hostForeground = false
     private var systemHandoffComplete = true
     private var compositionReady = false
+    private var coverFadeInStarted = false
+    private var coverFadeInComplete = 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
@@ -106,16 +103,13 @@ object LottieSplashCoordinator {
     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.
@@ -144,6 +138,8 @@ object LottieSplashCoordinator {
         hostForeground = activity.hasWindowFocus()
         systemHandoffComplete = !dismissWhenUnadopted
         compositionReady = false
+        coverFadeInStarted = false
+        coverFadeInComplete = false
         requestedPlayback = playback
         presentationId = UUID.randomUUID().toString()
         phase = AndroidSplashPhase.PREPARING
@@ -153,8 +149,6 @@ object LottieSplashCoordinator {
         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)
@@ -165,7 +159,7 @@ object LottieSplashCoordinator {
             isClickable = true
             isFocusable = true
             contentDescription = "Loading application"
-            alpha = 1f
+            alpha = 0f
             background = GradientDrawable(
                 GradientDrawable.Orientation.LEFT_RIGHT,
                 if (darkTheme) intArrayOf(backgroundStart, Color.rgb(37, 37, 37))
@@ -182,6 +176,7 @@ object LottieSplashCoordinator {
         overlay.post { updateAnimationLayout(overlay, lottie) }
         cover = overlay
         animation = lottie
+        if (systemHandoffComplete) beginCoverFadeIn(presentationId!!, overlay, lottie)
         if (dismissWhenUnadopted) scheduleUnadoptedFallback(presentationId!!)
         emit()
 
@@ -228,6 +223,7 @@ object LottieSplashCoordinator {
         val id = presentationId ?: return
         val existingCover = cover ?: return
         val existingAnimation = animation ?: return
+        beginCoverFadeIn(id, existingCover, existingAnimation)
         startPlaybackWhenVisible(id, existingCover, existingAnimation)
     }
 
@@ -294,7 +290,7 @@ object LottieSplashCoordinator {
     }
 
     private fun startPlaybackWhenVisible(id: String, overlay: FrameLayout, lottie: LottieAnimationView) {
-        if (id != presentationId || cover !== overlay || animation !== lottie || !compositionReady || !hostForeground || !systemHandoffComplete || phase != AndroidSplashPhase.PREPARING) return
+        if (id != presentationId || cover !== overlay || animation !== lottie || !compositionReady || !coverFadeInComplete || !hostForeground || !systemHandoffComplete || phase != AndroidSplashPhase.PREPARING) return
         val composition = lottie.composition ?: return
         phase = AndroidSplashPhase.PLAYING
         emit()
@@ -323,6 +319,22 @@ object LottieSplashCoordinator {
         }
     }
 
+    private fun beginCoverFadeIn(id: String, overlay: FrameLayout, lottie: LottieAnimationView) {
+        if (id != presentationId || cover !== overlay || animation !== lottie || coverFadeInStarted || !systemHandoffComplete) return
+        coverFadeInStarted = true
+        overlay.animate()
+            .alpha(1f)
+            .setDuration(if (ValueAnimator.areAnimatorsEnabled()) COVER_FADE_IN_MS else 0)
+            .setInterpolator(AccelerateDecelerateInterpolator())
+            .withEndAction {
+                if (id == presentationId && cover === overlay && animation === lottie) {
+                    coverFadeInComplete = true
+                    startPlaybackWhenVisible(id, overlay, lottie)
+                }
+            }
+            .start()
+    }
+
     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)
@@ -354,7 +366,6 @@ object LottieSplashCoordinator {
     private fun resetWaitingUi(id: String) {
         cancelWaitingTasks()
         progressRemainingMs = PROGRESS_DELAY_MS
-        recoveryRemainingMs = RECOVERY_DELAY_MS
         scheduleWaitingUi(id)
     }
 
@@ -371,24 +382,19 @@ object LottieSplashCoordinator {
         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
     }
 
@@ -404,36 +410,10 @@ object LottieSplashCoordinator {
         }
     }
 
-    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) {
@@ -464,11 +444,11 @@ object LottieSplashCoordinator {
             animation = null
             hostActivity = null
             loadingRail = null
-            recoveryMessage = null
-            recoveryRetry = null
             presentationId = null
             phase = AndroidSplashPhase.HIDDEN
             compositionReady = false
+            coverFadeInStarted = false
+            coverFadeInComplete = false
             emit()
             callback(null)
         }.start()
@@ -489,6 +469,8 @@ object LottieSplashCoordinator {
         presentationId = null
         phase = AndroidSplashPhase.HIDDEN
         compositionReady = false
+        coverFadeInStarted = false
+        coverFadeInComplete = false
         pendingHide = null
         completion = null
         emit()

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

@@ -20,7 +20,6 @@ class LottieSplashPlugin : Plugin() {
     }
     override fun load() {
         LottieSplashCoordinator.onStateChange = { notifyListeners("stateChange", stateObject()) }
-        LottieSplashCoordinator.onRecoveryRequested = { bridge?.webView?.reload() }
     }
 
     @PluginMethod
@@ -89,7 +88,7 @@ class LottieSplashPlugin : Plugin() {
                 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.
+                // A stalled GPU/compositor must not leave an app-ready screen covered.
                 main.postDelayed(fallback, VISUAL_STATE_TIMEOUT_MS)
             } catch (_: Throwable) {
                 finishHandoff()

package/dist/esm/definitions.d.ts

@@ -1,6 +1,6 @@
 import type { PluginListenerHandle } from '@capacitor/core';
 export type SplashRenderer = 'ios' | 'android' | 'web';
-export type SplashPhase = 'preparing' | 'playing' | 'holding' | 'hiding' | 'hidden' | 'recovery';
+export type SplashPhase = 'preparing' | 'playing' | 'holding' | 'hiding' | 'hidden';
 export type PlaybackOutcome = 'completed' | 'reduced-motion' | 'static-fallback';
 export type SplashTheme = 'light' | 'dark';
 export interface SplashAssets {

package/dist/esm/state-machine.d.ts

@@ -10,7 +10,6 @@ export declare class SplashStateMachine {
     playing(presentationId: string): StateMachineSnapshot;
     settlePlayback(presentationId: string, outcome: PlaybackOutcome, reason?: string): StateMachineSnapshot;
     requestHide(presentationId: string): StateMachineSnapshot;
-    recovery(presentationId: string): StateMachineSnapshot;
     hidden(presentationId: string): StateMachineSnapshot;
     getPlaybackResult(presentationId: string): PlaybackResult | undefined;
     current(): StateMachineSnapshot;

package/dist/esm/state-machine.js

@@ -45,12 +45,6 @@ export class SplashStateMachine {
             this.snapshot.phase = 'hiding';
         return this.current();
     }
-    recovery(presentationId) {
-        this.requireCurrent(presentationId);
-        if (!this.snapshot.appReady)
-            this.snapshot.phase = 'recovery';
-        return this.current();
-    }
     hidden(presentationId) {
         this.requireCurrent(presentationId);
         this.snapshot = {

package/dist/esm/web.d.ts

@@ -6,7 +6,7 @@ export declare class LottieSplashWeb extends WebPlugin implements LottieSplashPl
     private resolvePlayback?;
     private overlay?;
     private progressTimer?;
-    private recoveryTimer?;
+    private playbackTimer?;
     show(options: SplashShowOptions): Promise<Presentation>;
     setLaunchTheme(_options: SplashLaunchThemeOptions): Promise<void>;
     waitForCompletion(options: {
@@ -21,7 +21,6 @@ export declare class LottieSplashWeb extends WebPlugin implements LottieSplashPl
     private playComposition;
     private settle;
     private showLoadingRail;
-    private showRecovery;
     private removeOverlay;
     private ensureCurrent;
     private emitState;

package/dist/esm/web.js

@@ -1,14 +1,14 @@
 import { WebPlugin } from '@capacitor/core';
 import { SplashStateMachine } from './state-machine';
-const RECOVERY_TIMEOUT_MS = 15_000;
 const PROGRESS_DELAY_MS = 1_000;
+const COVER_FADE_MS = 500;
 export class LottieSplashWeb extends WebPlugin {
     stateMachine = new SplashStateMachine();
     playbackPromise;
     resolvePlayback;
     overlay;
     progressTimer;
-    recoveryTimer;
+    playbackTimer;
     async show(options) {
         const state = this.stateMachine.current();
         if (state.visible && state.presentationId)
@@ -32,7 +32,7 @@ export class LottieSplashWeb extends WebPlugin {
         this.emitState();
         if (!state.playbackSettled)
             await this.waitForCompletion(options);
-        this.removeOverlay(options.presentationId);
+        await this.removeOverlay(options.presentationId);
     }
     async getState() {
         const { generation: _generation, ...state } = this.stateMachine.current();
@@ -49,10 +49,14 @@ export class LottieSplashWeb extends WebPlugin {
         overlay.dataset.presentationId = presentationId;
         Object.assign(overlay.style, {
             position: 'fixed', inset: '0', zIndex: '2147483647', display: 'grid', placeItems: 'center',
-            background: this.backgroundFor(this.stateMachine.current().theme), overflow: 'hidden'
+            background: this.backgroundFor(this.stateMachine.current().theme), overflow: 'hidden',
+            opacity: '0', transition: `opacity ${COVER_FADE_MS}ms ease-in-out`
         });
         document.body.append(overlay);
         this.overlay = overlay;
+        // Force the initial transparent style to paint before beginning the fade.
+        void overlay.offsetWidth;
+        overlay.style.opacity = '1';
         // A generic package cannot ship HeadCount assets. The host supplies an approved local
         // composition; absent or failed assets leave the opaque branded background in place.
         if (!options.assets?.animationData && !options.assets?.animationPath) {
@@ -63,9 +67,13 @@ export class LottieSplashWeb extends WebPlugin {
             this.settle(presentationId, 'reduced-motion', 'Reduced motion is enabled');
             return;
         }
-        this.stateMachine.playing(presentationId);
-        this.emitState();
-        void this.playComposition(options, presentationId);
+        this.playbackTimer = window.setTimeout(() => {
+            if (this.stateMachine.current().presentationId !== presentationId || this.overlay !== overlay)
+                return;
+            this.stateMachine.playing(presentationId);
+            this.emitState();
+            void this.playComposition(options, presentationId);
+        }, COVER_FADE_MS);
     }
     async playComposition(options, presentationId) {
         try {
@@ -104,7 +112,6 @@ export class LottieSplashWeb extends WebPlugin {
             this.emitState();
             if (!state.appReady) {
                 this.progressTimer = window.setTimeout(() => this.showLoadingRail(presentationId), PROGRESS_DELAY_MS);
-                this.recoveryTimer = window.setTimeout(() => this.showRecovery(presentationId), RECOVERY_TIMEOUT_MS);
             }
         }
         catch {
@@ -127,32 +134,15 @@ export class LottieSplashWeb extends WebPlugin {
         rail.append(segment);
         this.overlay?.append(style, rail);
     }
-    showRecovery(presentationId) {
-        let state;
-        try {
-            state = this.stateMachine.recovery(presentationId);
-        }
-        catch {
-            return;
-        }
-        if (state.presentationId !== presentationId || state.appReady)
-            return;
-        this.overlay?.querySelector('[data-splash-loading-rail]')?.remove();
-        const recovery = document.createElement('div');
-        recovery.style.cssText = 'position:absolute;bottom:12%;display:grid;gap:12px;place-items:center;color:inherit;font:500 16px system-ui;';
-        recovery.textContent = 'Still starting…';
-        const retry = document.createElement('button');
-        retry.type = 'button';
-        retry.textContent = 'Try again';
-        retry.onclick = () => window.location.reload();
-        recovery.append(retry);
-        this.overlay?.append(recovery);
-        this.emitState();
-    }
-    removeOverlay(presentationId) {
+    async removeOverlay(presentationId) {
         window.clearTimeout(this.progressTimer);
-        window.clearTimeout(this.recoveryTimer);
-        this.overlay?.remove();
+        window.clearTimeout(this.playbackTimer);
+        const overlay = this.overlay;
+        if (overlay) {
+            overlay.style.opacity = '0';
+            await new Promise(resolve => window.setTimeout(resolve, COVER_FADE_MS));
+            overlay.remove();
+        }
         this.overlay = undefined;
         this.stateMachine.hidden(presentationId);
         this.emitState();

package/dist/plugin.cjs.js

@@ -53,12 +53,6 @@ class SplashStateMachine {
             this.snapshot.phase = 'hiding';
         return this.current();
     }
-    recovery(presentationId) {
-        this.requireCurrent(presentationId);
-        if (!this.snapshot.appReady)
-            this.snapshot.phase = 'recovery';
-        return this.current();
-    }
     hidden(presentationId) {
         this.requireCurrent(presentationId);
         this.snapshot = {
@@ -85,15 +79,15 @@ class SplashStateMachine {
     }
 }
 
-const RECOVERY_TIMEOUT_MS = 15_000;
 const PROGRESS_DELAY_MS = 1_000;
+const COVER_FADE_MS = 500;
 class LottieSplashWeb extends core.WebPlugin {
     stateMachine = new SplashStateMachine();
     playbackPromise;
     resolvePlayback;
     overlay;
     progressTimer;
-    recoveryTimer;
+    playbackTimer;
     async show(options) {
         const state = this.stateMachine.current();
         if (state.visible && state.presentationId)
@@ -117,7 +111,7 @@ class LottieSplashWeb extends core.WebPlugin {
         this.emitState();
         if (!state.playbackSettled)
             await this.waitForCompletion(options);
-        this.removeOverlay(options.presentationId);
+        await this.removeOverlay(options.presentationId);
     }
     async getState() {
         const { generation: _generation, ...state } = this.stateMachine.current();
@@ -134,10 +128,14 @@ class LottieSplashWeb extends core.WebPlugin {
         overlay.dataset.presentationId = presentationId;
         Object.assign(overlay.style, {
             position: 'fixed', inset: '0', zIndex: '2147483647', display: 'grid', placeItems: 'center',
-            background: this.backgroundFor(this.stateMachine.current().theme), overflow: 'hidden'
+            background: this.backgroundFor(this.stateMachine.current().theme), overflow: 'hidden',
+            opacity: '0', transition: `opacity ${COVER_FADE_MS}ms ease-in-out`
         });
         document.body.append(overlay);
         this.overlay = overlay;
+        // Force the initial transparent style to paint before beginning the fade.
+        void overlay.offsetWidth;
+        overlay.style.opacity = '1';
         // A generic package cannot ship HeadCount assets. The host supplies an approved local
         // composition; absent or failed assets leave the opaque branded background in place.
         if (!options.assets?.animationData && !options.assets?.animationPath) {
@@ -148,9 +146,13 @@ class LottieSplashWeb extends core.WebPlugin {
             this.settle(presentationId, 'reduced-motion', 'Reduced motion is enabled');
             return;
         }
-        this.stateMachine.playing(presentationId);
-        this.emitState();
-        void this.playComposition(options, presentationId);
+        this.playbackTimer = window.setTimeout(() => {
+            if (this.stateMachine.current().presentationId !== presentationId || this.overlay !== overlay)
+                return;
+            this.stateMachine.playing(presentationId);
+            this.emitState();
+            void this.playComposition(options, presentationId);
+        }, COVER_FADE_MS);
     }
     async playComposition(options, presentationId) {
         try {
@@ -189,7 +191,6 @@ class LottieSplashWeb extends core.WebPlugin {
             this.emitState();
             if (!state.appReady) {
                 this.progressTimer = window.setTimeout(() => this.showLoadingRail(presentationId), PROGRESS_DELAY_MS);
-                this.recoveryTimer = window.setTimeout(() => this.showRecovery(presentationId), RECOVERY_TIMEOUT_MS);
             }
         }
         catch {
@@ -212,32 +213,15 @@ class LottieSplashWeb extends core.WebPlugin {
         rail.append(segment);
         this.overlay?.append(style, rail);
     }
-    showRecovery(presentationId) {
-        let state;
-        try {
-            state = this.stateMachine.recovery(presentationId);
-        }
-        catch {
-            return;
-        }
-        if (state.presentationId !== presentationId || state.appReady)
-            return;
-        this.overlay?.querySelector('[data-splash-loading-rail]')?.remove();
-        const recovery = document.createElement('div');
-        recovery.style.cssText = 'position:absolute;bottom:12%;display:grid;gap:12px;place-items:center;color:inherit;font:500 16px system-ui;';
-        recovery.textContent = 'Still starting…';
-        const retry = document.createElement('button');
-        retry.type = 'button';
-        retry.textContent = 'Try again';
-        retry.onclick = () => window.location.reload();
-        recovery.append(retry);
-        this.overlay?.append(recovery);
-        this.emitState();
-    }
-    removeOverlay(presentationId) {
+    async removeOverlay(presentationId) {
         window.clearTimeout(this.progressTimer);
-        window.clearTimeout(this.recoveryTimer);
-        this.overlay?.remove();
+        window.clearTimeout(this.playbackTimer);
+        const overlay = this.overlay;
+        if (overlay) {
+            overlay.style.opacity = '0';
+            await new Promise(resolve => window.setTimeout(resolve, COVER_FADE_MS));
+            overlay.remove();
+        }
         this.overlay = undefined;
         this.stateMachine.hidden(presentationId);
         this.emitState();

package/dist/plugin.js

@@ -67,12 +67,6 @@ var capacitorLottieSplash = (function (exports, core) {
                 this.snapshot.phase = 'hiding';
             return this.current();
         }
-        recovery(presentationId) {
-            this.requireCurrent(presentationId);
-            if (!this.snapshot.appReady)
-                this.snapshot.phase = 'recovery';
-            return this.current();
-        }
         hidden(presentationId) {
             this.requireCurrent(presentationId);
             this.snapshot = {
@@ -99,15 +93,15 @@ var capacitorLottieSplash = (function (exports, core) {
         }
     }
 
-    const RECOVERY_TIMEOUT_MS = 15_000;
     const PROGRESS_DELAY_MS = 1_000;
+    const COVER_FADE_MS = 500;
     class LottieSplashWeb extends core.WebPlugin {
         stateMachine = new SplashStateMachine();
         playbackPromise;
         resolvePlayback;
         overlay;
         progressTimer;
-        recoveryTimer;
+        playbackTimer;
         async show(options) {
             const state = this.stateMachine.current();
             if (state.visible && state.presentationId)
@@ -131,7 +125,7 @@ var capacitorLottieSplash = (function (exports, core) {
             this.emitState();
             if (!state.playbackSettled)
                 await this.waitForCompletion(options);
-            this.removeOverlay(options.presentationId);
+            await this.removeOverlay(options.presentationId);
         }
         async getState() {
             const { generation: _generation, ...state } = this.stateMachine.current();
@@ -148,10 +142,14 @@ var capacitorLottieSplash = (function (exports, core) {
             overlay.dataset.presentationId = presentationId;
             Object.assign(overlay.style, {
                 position: 'fixed', inset: '0', zIndex: '2147483647', display: 'grid', placeItems: 'center',
-                background: this.backgroundFor(this.stateMachine.current().theme), overflow: 'hidden'
+                background: this.backgroundFor(this.stateMachine.current().theme), overflow: 'hidden',
+                opacity: '0', transition: `opacity ${COVER_FADE_MS}ms ease-in-out`
             });
             document.body.append(overlay);
             this.overlay = overlay;
+            // Force the initial transparent style to paint before beginning the fade.
+            void overlay.offsetWidth;
+            overlay.style.opacity = '1';
             // A generic package cannot ship HeadCount assets. The host supplies an approved local
             // composition; absent or failed assets leave the opaque branded background in place.
             if (!options.assets?.animationData && !options.assets?.animationPath) {
@@ -162,9 +160,13 @@ var capacitorLottieSplash = (function (exports, core) {
                 this.settle(presentationId, 'reduced-motion', 'Reduced motion is enabled');
                 return;
             }
-            this.stateMachine.playing(presentationId);
-            this.emitState();
-            void this.playComposition(options, presentationId);
+            this.playbackTimer = window.setTimeout(() => {
+                if (this.stateMachine.current().presentationId !== presentationId || this.overlay !== overlay)
+                    return;
+                this.stateMachine.playing(presentationId);
+                this.emitState();
+                void this.playComposition(options, presentationId);
+            }, COVER_FADE_MS);
         }
         async playComposition(options, presentationId) {
             try {
@@ -203,7 +205,6 @@ var capacitorLottieSplash = (function (exports, core) {
                 this.emitState();
                 if (!state.appReady) {
                     this.progressTimer = window.setTimeout(() => this.showLoadingRail(presentationId), PROGRESS_DELAY_MS);
-                    this.recoveryTimer = window.setTimeout(() => this.showRecovery(presentationId), RECOVERY_TIMEOUT_MS);
                 }
             }
             catch {
@@ -226,32 +227,15 @@ var capacitorLottieSplash = (function (exports, core) {
             rail.append(segment);
             this.overlay?.append(style, rail);
         }
-        showRecovery(presentationId) {
-            let state;
-            try {
-                state = this.stateMachine.recovery(presentationId);
-            }
-            catch {
-                return;
-            }
-            if (state.presentationId !== presentationId || state.appReady)
-                return;
-            this.overlay?.querySelector('[data-splash-loading-rail]')?.remove();
-            const recovery = document.createElement('div');
-            recovery.style.cssText = 'position:absolute;bottom:12%;display:grid;gap:12px;place-items:center;color:inherit;font:500 16px system-ui;';
-            recovery.textContent = 'Still starting…';
-            const retry = document.createElement('button');
-            retry.type = 'button';
-            retry.textContent = 'Try again';
-            retry.onclick = () => window.location.reload();
-            recovery.append(retry);
-            this.overlay?.append(recovery);
-            this.emitState();
-        }
-        removeOverlay(presentationId) {
+        async removeOverlay(presentationId) {
             window.clearTimeout(this.progressTimer);
-            window.clearTimeout(this.recoveryTimer);
-            this.overlay?.remove();
+            window.clearTimeout(this.playbackTimer);
+            const overlay = this.overlay;
+            if (overlay) {
+                overlay.style.opacity = '0';
+                await new Promise(resolve => window.setTimeout(resolve, COVER_FADE_MS));
+                overlay.remove();
+            }
             this.overlay = undefined;
             this.stateMachine.hidden(presentationId);
             this.emitState();

package/ios/Sources/LottieSplashPlugin/LottieSplashCoordinator.swift

@@ -149,7 +149,7 @@ public struct LottieSplashConfiguration {
 }
 
 public enum LottieSplashPhase: String {
-    case preparing, playing, holding, hiding, hidden, recovery
+    case preparing, playing, holding, hiding, hidden
 }
 
 public final class LottieSplashCoordinator {
@@ -159,7 +159,7 @@ public final class LottieSplashCoordinator {
     /// permanently obscure that bundle during an over-the-air/native rollout mismatch.
     private let webAdoptionGracePeriod: TimeInterval = 10
     private let progressDelay: TimeInterval = 1
-    private let recoveryDelay: TimeInterval = 15
+    private let coverFadeDuration: TimeInterval = 0.5
 
     public private(set) var presentationId: String?
     public private(set) var phase: LottieSplashPhase = .hidden
@@ -167,20 +167,18 @@ public final class LottieSplashCoordinator {
     public private(set) var appReady = false
     public private(set) var theme: LottieSplashTheme = .dark
     public var onStateChange: ((LottieSplashCoordinator) -> Void)?
-    public var onRecoveryRequested: (() -> Void)?
 
     private weak var hostController: UIViewController?
     private var cover: LottieSplashCoverView?
     private var animationWebView: WKWebView?
     private var animationMessageBridge: LottieSplashMessageBridge?
     private var loadingRail: LottieSplashLoadingRail?
-    private var recoveryWorkItem: DispatchWorkItem?
     private var progressWorkItem: DispatchWorkItem?
     private var adoptionWorkItem: DispatchWorkItem?
     private var adoptedByWeb = false
     private var webRendererLoaded = false
+    private var coverFadeInComplete = false
     private var progressRemaining = TimeInterval(1)
-    private var recoveryRemaining = TimeInterval(15)
     private var waitingClockStartedAt: Date?
     private var playbackCompletion: ((String, String?) -> Void)?
     private let queue = DispatchQueue.main
@@ -243,7 +241,7 @@ public final class LottieSplashCoordinator {
     }
 
     public func startPlaybackIfVisible(configuration: LottieSplashConfiguration = .init()) {
-        guard phase == .preparing, animationWebView != nil else { return }
+        guard phase == .preparing, animationWebView != nil, coverFadeInComplete else { return }
         phase = .playing
         emitState()
         guard !UIAccessibility.isReduceMotionEnabled else {
@@ -296,6 +294,7 @@ public final class LottieSplashCoordinator {
 
     private func buildCover(in controller: UIViewController, configuration: LottieSplashConfiguration) {
         let cover = LottieSplashCoverView(theme: configuration.resolvedTheme)
+        cover.alpha = 0
         cover.translatesAutoresizingMaskIntoConstraints = false
         cover.isAccessibilityElement = true
         cover.accessibilityLabel = "Loading application"
@@ -334,6 +333,15 @@ public final class LottieSplashCoordinator {
         self.animationWebView = animation
         self.animationMessageBridge = messageBridge
         self.webRendererLoaded = false
+        self.coverFadeInComplete = false
+        controller.view.layoutIfNeeded()
+        UIView.animate(withDuration: UIAccessibility.isReduceMotionEnabled ? 0 : coverFadeDuration, delay: 0, options: [.curveEaseInOut]) {
+            cover.alpha = 1
+        } completion: { [weak self, weak cover] _ in
+            guard let self, let cover, self.cover === cover else { return }
+            self.coverFadeInComplete = true
+            self.startPlaybackIfVisible()
+        }
     }
 
     private func apply(theme: LottieSplashTheme) {
@@ -401,20 +409,13 @@ public final class LottieSplashCoordinator {
             ])
             self.loadingRail = rail
         }
-        let recovery = DispatchWorkItem { [weak self] in
-            self?.recoveryRemaining = 0
-            self?.showRecovery(for: id)
-        }
         progressWorkItem = progress
-        recoveryWorkItem = recovery
         if self.loadingRail == nil { queue.asyncAfter(deadline: .now() + progressRemaining, execute: progress) }
-        queue.asyncAfter(deadline: .now() + recoveryRemaining, execute: recovery)
     }
 
     private func resetWaitingIndicators(for id: String) {
         cancelWaitingTasks()
         progressRemaining = progressDelay
-        recoveryRemaining = recoveryDelay
         scheduleWaitingIndicators(for: id)
     }
 
@@ -422,15 +423,12 @@ public final class LottieSplashCoordinator {
         guard let waitingClockStartedAt else { return }
         let elapsed = Date().timeIntervalSince(waitingClockStartedAt)
         progressRemaining = max(0, progressRemaining - elapsed)
-        recoveryRemaining = max(0, recoveryRemaining - elapsed)
         cancelWaitingTasks()
     }
 
     private func cancelWaitingTasks() {
         progressWorkItem?.cancel()
-        recoveryWorkItem?.cancel()
         progressWorkItem = nil
-        recoveryWorkItem = nil
         waitingClockStartedAt = nil
     }
 
@@ -445,33 +443,6 @@ public final class LottieSplashCoordinator {
         queue.asyncAfter(deadline: .now() + webAdoptionGracePeriod, execute: fallback)
     }
 
-    private func showRecovery(for id: String) {
-        guard presentationId == id, !appReady else { return }
-        cancelWaitingTasks()
-        phase = .recovery
-        loadingRail?.removeFromSuperview()
-        loadingRail = nil
-        let stack = UIStackView()
-        stack.axis = .vertical
-        stack.spacing = 12
-        stack.alignment = .center
-        stack.translatesAutoresizingMaskIntoConstraints = false
-        let label = UILabel()
-        label.text = "Still starting…"
-        label.accessibilityTraits = .updatesFrequently
-        let retry = UIButton(type: .system)
-        retry.setTitle("Try again", for: .normal)
-        retry.addAction(UIAction { [weak self] _ in self?.onRecoveryRequested?() }, for: .primaryActionTriggered)
-        stack.addArrangedSubview(label)
-        stack.addArrangedSubview(retry)
-        cover?.addSubview(stack)
-        if let cover {
-            NSLayoutConstraint.activate([stack.centerXAnchor.constraint(equalTo: cover.centerXAnchor), stack.bottomAnchor.constraint(equalTo: cover.safeAreaLayoutGuide.bottomAnchor, constant: -48)])
-        }
-        UIAccessibility.post(notification: .announcement, argument: "Still starting")
-        emitState()
-    }
-
     private func dismiss(completion: @escaping (Error?) -> Void) {
         guard phase != .hidden, let cover, let id = presentationId else { completion(nil); return }
         phase = .hiding
@@ -480,7 +451,7 @@ public final class LottieSplashCoordinator {
         adoptionWorkItem = nil
         loadingRail?.removeFromSuperview()
         loadingRail = nil
-        UIView.animate(withDuration: UIAccessibility.isReduceMotionEnabled ? 0 : 0.5, animations: { cover.alpha = 0 }) { [weak self] _ in
+        UIView.animate(withDuration: UIAccessibility.isReduceMotionEnabled ? 0 : coverFadeDuration, animations: { cover.alpha = 0 }) { [weak self] _ in
             cover.removeFromSuperview()
             self?.cover = nil
             self?.phase = .hidden
@@ -488,6 +459,7 @@ public final class LottieSplashCoordinator {
             self?.animationWebView?.configuration.userContentController.removeScriptMessageHandler(forName: "lottieSplash")
             self?.animationWebView = nil
             self?.animationMessageBridge = nil
+            self?.coverFadeInComplete = false
             self?.emitState()
             _ = id
             completion(nil)

package/ios/Sources/LottieSplashPlugin/LottieSplashPlugin.swift

@@ -17,7 +17,6 @@ public class LottieSplashPlugin: CAPPlugin, CAPBridgedPlugin {
 
     override public func load() {
         coordinator.onStateChange = { [weak self] coordinator in self?.notifyListeners("stateChange", data: self?.stateData(coordinator) ?? [:]) }
-        coordinator.onRecoveryRequested = { [weak self] in self?.bridge?.webView?.reload() }
     }
 
     @objc public func show(_ call: CAPPluginCall) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capacitor-lottie-splash",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Native-first Lottie splash presentation for Capacitor 8",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",