capacitor-lottie-splash 0.1.3 → 0.1.4

package/README.md

@@ -101,7 +101,7 @@ 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 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.
+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.
 

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

@@ -79,6 +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 COVER_FADE_IN_MS = 500L
     private const val COVER_FADE_OUT_MS = 500L
     private val main = Handler(Looper.getMainLooper())
 
@@ -88,6 +89,8 @@ 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 presentationId: String? = null
@@ -135,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
@@ -154,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))
@@ -171,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()
 
@@ -217,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)
     }
 
@@ -283,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()
@@ -312,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)
@@ -424,6 +447,8 @@ object LottieSplashCoordinator {
             presentationId = null
             phase = AndroidSplashPhase.HIDDEN
             compositionReady = false
+            coverFadeInStarted = false
+            coverFadeInComplete = false
             emit()
             callback(null)
         }.start()
@@ -444,6 +469,8 @@ object LottieSplashCoordinator {
         presentationId = null
         phase = AndroidSplashPhase.HIDDEN
         compositionReady = false
+        coverFadeInStarted = false
+        coverFadeInComplete = false
         pendingHide = null
         completion = null
         emit()

package/dist/esm/web.d.ts

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

package/dist/esm/web.js

@@ -1,12 +1,14 @@
 import { WebPlugin } from '@capacitor/core';
 import { SplashStateMachine } from './state-machine';
 const PROGRESS_DELAY_MS = 1_000;
+const COVER_FADE_MS = 500;
 export class LottieSplashWeb extends WebPlugin {
     stateMachine = new SplashStateMachine();
     playbackPromise;
     resolvePlayback;
     overlay;
     progressTimer;
+    playbackTimer;
     async show(options) {
         const state = this.stateMachine.current();
         if (state.visible && state.presentationId)
@@ -30,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();
@@ -47,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) {
@@ -61,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 {
@@ -124,9 +134,15 @@ export class LottieSplashWeb extends WebPlugin {
         rail.append(segment);
         this.overlay?.append(style, rail);
     }
-    removeOverlay(presentationId) {
+    async removeOverlay(presentationId) {
         window.clearTimeout(this.progressTimer);
-        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

@@ -80,12 +80,14 @@ class SplashStateMachine {
 }
 
 const PROGRESS_DELAY_MS = 1_000;
+const COVER_FADE_MS = 500;
 class LottieSplashWeb extends core.WebPlugin {
     stateMachine = new SplashStateMachine();
     playbackPromise;
     resolvePlayback;
     overlay;
     progressTimer;
+    playbackTimer;
     async show(options) {
         const state = this.stateMachine.current();
         if (state.visible && state.presentationId)
@@ -109,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();
@@ -126,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) {
@@ -140,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 {
@@ -203,9 +213,15 @@ class LottieSplashWeb extends core.WebPlugin {
         rail.append(segment);
         this.overlay?.append(style, rail);
     }
-    removeOverlay(presentationId) {
+    async removeOverlay(presentationId) {
         window.clearTimeout(this.progressTimer);
-        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

@@ -94,12 +94,14 @@ var capacitorLottieSplash = (function (exports, core) {
     }
 
     const PROGRESS_DELAY_MS = 1_000;
+    const COVER_FADE_MS = 500;
     class LottieSplashWeb extends core.WebPlugin {
         stateMachine = new SplashStateMachine();
         playbackPromise;
         resolvePlayback;
         overlay;
         progressTimer;
+        playbackTimer;
         async show(options) {
             const state = this.stateMachine.current();
             if (state.visible && state.presentationId)
@@ -123,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();
@@ -140,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) {
@@ -154,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 {
@@ -217,9 +227,15 @@ var capacitorLottieSplash = (function (exports, core) {
             rail.append(segment);
             this.overlay?.append(style, rail);
         }
-        removeOverlay(presentationId) {
+        async removeOverlay(presentationId) {
             window.clearTimeout(this.progressTimer);
-            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

@@ -159,6 +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 coverFadeDuration: TimeInterval = 0.5
 
     public private(set) var presentationId: String?
     public private(set) var phase: LottieSplashPhase = .hidden
@@ -176,6 +177,7 @@ public final class LottieSplashCoordinator {
     private var adoptionWorkItem: DispatchWorkItem?
     private var adoptedByWeb = false
     private var webRendererLoaded = false
+    private var coverFadeInComplete = false
     private var progressRemaining = TimeInterval(1)
     private var waitingClockStartedAt: Date?
     private var playbackCompletion: ((String, String?) -> Void)?
@@ -239,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 {
@@ -292,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"
@@ -330,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) {
@@ -439,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
@@ -447,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/package.json

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