capacitor-lottie-splash 0.1.0

package/ios/Sources/LottieSplashPlugin/LottieSplashCoordinator.swift

@@ -0,0 +1,501 @@
+import UIKit
+import WebKit
+
+public enum LottieSplashTheme: String {
+    case light
+    case dark
+
+    public var gradient: [CGColor] {
+        switch self {
+        case .light: return [UIColor(red: 240/255, green: 240/255, blue: 240/255, alpha: 1).cgColor, UIColor(red: 245/255, green: 245/255, blue: 245/255, alpha: 1).cgColor]
+        case .dark: return [UIColor(red: 30/255, green: 30/255, blue: 30/255, alpha: 1).cgColor, UIColor(red: 37/255, green: 37/255, blue: 37/255, alpha: 1).cgColor]
+        }
+    }
+
+    public var backgroundColor: UIColor {
+        switch self {
+        case .light: return UIColor(red: 240/255, green: 240/255, blue: 240/255, alpha: 1)
+        case .dark: return UIColor(red: 30/255, green: 30/255, blue: 30/255, alpha: 1)
+        }
+    }
+}
+
+/** A host-defined Capacitor Preferences value available before the WebView starts. */
+public struct LottieSplashThemePreference {
+    public let key: String
+    public let darkValue: String
+    public let lightValue: String
+    public let storagePrefix: String
+
+    public init(key: String, darkValue: String, lightValue: String, storagePrefix: String = "CapacitorStorage.") {
+        self.key = key
+        self.darkValue = darkValue
+        self.lightValue = lightValue
+        self.storagePrefix = storagePrefix
+    }
+
+    public func resolvedTheme() -> LottieSplashTheme? {
+        switch UserDefaults.standard.string(forKey: storagePrefix + key) {
+        case darkValue: return .dark
+        case lightValue: return .light
+        default: return nil
+        }
+    }
+}
+
+private final class LottieSplashCoverView: UIView {
+    private let gradient = CAGradientLayer()
+
+    init(theme: LottieSplashTheme) {
+        super.init(frame: .zero)
+        backgroundColor = theme.backgroundColor
+        gradient.colors = theme.gradient
+        gradient.startPoint = CGPoint(x: 0, y: 0.5)
+        gradient.endPoint = CGPoint(x: 1, y: 0.5)
+        layer.insertSublayer(gradient, at: 0)
+    }
+
+    required init?(coder: NSCoder) { nil }
+
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        gradient.frame = bounds
+    }
+
+    func apply(theme: LottieSplashTheme) {
+        backgroundColor = theme.backgroundColor
+        gradient.colors = theme.gradient
+    }
+}
+
+/** A quiet, indeterminate loading rail that does not obscure the completed mark. */
+private final class LottieSplashLoadingRail: UIView {
+    private let track = UIView()
+    private let segment = UIView()
+    private var animationStarted = false
+
+    init(theme: LottieSplashTheme) {
+        super.init(frame: .zero)
+        isAccessibilityElement = true
+        accessibilityLabel = "Application is still loading"
+        track.layer.cornerRadius = 1.5
+        track.clipsToBounds = true
+        segment.layer.cornerRadius = 1.5
+        addSubview(track)
+        track.addSubview(segment)
+        apply(theme: theme)
+    }
+
+    required init?(coder: NSCoder) { nil }
+
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        track.frame = bounds
+        let width = max(28, bounds.width * 0.36)
+        segment.frame = CGRect(x: -width, y: 0, width: width, height: bounds.height)
+        startAnimatingIfNeeded()
+    }
+
+    func apply(theme: LottieSplashTheme) {
+        track.backgroundColor = theme == .dark
+            ? UIColor.white.withAlphaComponent(0.18)
+            : UIColor.black.withAlphaComponent(0.14)
+        segment.backgroundColor = UIColor(red: 1, green: 0.30, blue: 0.30, alpha: 0.9)
+    }
+
+    private func startAnimatingIfNeeded() {
+        guard !animationStarted, bounds.width > 0 else { return }
+        animationStarted = true
+        let sweep = CABasicAnimation(keyPath: "transform.translation.x")
+        sweep.fromValue = -segment.bounds.width
+        sweep.toValue = bounds.width + segment.bounds.width
+        sweep.duration = 1.15
+        sweep.repeatCount = .infinity
+        sweep.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+        segment.layer.add(sweep, forKey: "lottieSplashLoadingRail")
+    }
+}
+
+private final class LottieSplashMessageBridge: NSObject, WKScriptMessageHandler, WKNavigationDelegate {
+    weak var coordinator: LottieSplashCoordinator?
+
+    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        guard message.name == "lottieSplash", let payload = message.body as? [String: Any] else { return }
+        coordinator?.receiveWebAnimationEvent(
+            outcome: payload["outcome"] as? String,
+            reason: payload["reason"] as? String
+        )
+    }
+
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        coordinator?.webRendererDidLoad()
+    }
+}
+
+public struct LottieSplashConfiguration {
+    public let animationName: String
+    public let theme: LottieSplashTheme
+    public let themePreference: LottieSplashThemePreference?
+
+    public var resolvedTheme: LottieSplashTheme {
+        themePreference?.resolvedTheme() ?? theme
+    }
+
+    public init(animationName: String = "animatedLogo", theme: LottieSplashTheme = .dark, themePreference: LottieSplashThemePreference? = nil) {
+        self.animationName = animationName
+        self.theme = theme
+        self.themePreference = themePreference
+    }
+}
+
+public enum LottieSplashPhase: String {
+    case preparing, playing, holding, hiding, hidden, recovery
+}
+
+public final class LottieSplashCoordinator {
+    public static let shared = LottieSplashCoordinator()
+
+    /// A web bundle from before this plugin existed cannot adopt the native cover. Do not
+    /// 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
+
+    public private(set) var presentationId: String?
+    public private(set) var phase: LottieSplashPhase = .hidden
+    public private(set) var playbackSettled = false
+    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 progressRemaining = TimeInterval(1)
+    private var recoveryRemaining = TimeInterval(15)
+    private var waitingClockStartedAt: Date?
+    private var playbackCompletion: ((String, String?) -> Void)?
+    private let queue = DispatchQueue.main
+
+    private init() {}
+
+    /// Call from a host CAPBridgeViewController subclass in capacitorDidLoad().
+    /// The view exists at this point but the WebView has not loaded yet.
+    public func installInitialCover(on controller: UIViewController, configuration: LottieSplashConfiguration = .init()) {
+        let install = { [weak self, weak controller] in
+            guard let self, let controller else { return }
+            guard self.cover == nil else { return }
+            self.hostController = controller
+            self.presentationId = UUID().uuidString
+            self.phase = .preparing
+            self.playbackSettled = false
+            self.appReady = false
+            self.theme = configuration.resolvedTheme
+            self.adoptedByWeb = false
+            self.buildCover(in: controller, configuration: configuration)
+            self.prepareWebRenderer(configuration: configuration)
+            self.scheduleUnadoptedFallback(for: self.presentationId)
+            self.emitState()
+        }
+        if Thread.isMainThread { install() } else { queue.async(execute: install) }
+    }
+
+    public func show(configuration: LottieSplashConfiguration = .init()) -> (id: String, adopted: Bool) {
+        if let presentationId, cover != nil {
+            adoptedByWeb = true
+            adoptionWorkItem?.cancel()
+            adoptionWorkItem = nil
+            return (presentationId, true)
+        }
+        guard let controller = hostController else {
+            let id = UUID().uuidString
+            presentationId = id
+            phase = .hidden
+            return (id, false)
+        }
+        installInitialCover(on: controller, configuration: configuration)
+        // Cold launch playback starts from the host controller's viewDidAppear. A later
+        // JavaScript show() has no second view-appearance callback, so it must start its
+        // own presentation here. If the renderer is still loading, webRendererDidLoad()
+        // completes this hand-off once it is ready.
+        startPlaybackIfVisible()
+        return (presentationId ?? UUID().uuidString, false)
+    }
+
+    public func waitForCompletion(id: String, completion: @escaping (String, String?) -> Void) {
+        guard id == presentationId else { completion("static-fallback", "Stale splash presentation"); return }
+        if playbackSettled { completion("completed", nil); return }
+        playbackCompletion = completion
+    }
+
+    public func hide(id: String, completion: @escaping (Error?) -> Void) {
+        guard id == presentationId else { completion(LottieSplashError.stalePresentation); return }
+        appReady = true
+        if playbackSettled { dismiss(completion: completion) } else { emitState() }
+    }
+
+    public func startPlaybackIfVisible(configuration: LottieSplashConfiguration = .init()) {
+        guard phase == .preparing, animationWebView != nil else { return }
+        phase = .playing
+        emitState()
+        guard !UIAccessibility.isReduceMotionEnabled else {
+            settle(outcome: "static-fallback", reason: "Reduced motion")
+            return
+        }
+        beginWebAnimationIfReady()
+    }
+
+    private func prepareWebRenderer(configuration: LottieSplashConfiguration) {
+        guard let animationWebView else { return }
+        guard let publicDirectory = Bundle.main.resourceURL?.appendingPathComponent("public", isDirectory: true),
+              let animationURL = Bundle.main.url(forResource: configuration.animationName, withExtension: "json"),
+              let animationData = try? String(contentsOf: animationURL, encoding: .utf8),
+              let lottieRuntimeURL = Bundle(for: LottieSplashCoordinator.self).url(forResource: "lottie.min", withExtension: "js"),
+              let lottieRuntime = try? String(contentsOf: lottieRuntimeURL, encoding: .utf8) else {
+            settle(outcome: "static-fallback", reason: "Bundled animation unavailable")
+            return
+        }
+        let document = Self.webAnimationDocument
+            .replacingOccurrences(of: "__LOTTIE_RUNTIME__", with: lottieRuntime)
+            .replacingOccurrences(of: "__ANIMATION_DATA__", with: animationData)
+        animationWebView.loadHTMLString(document, baseURL: publicDirectory)
+    }
+
+    func webRendererDidLoad() {
+        webRendererLoaded = true
+        beginWebAnimationIfReady()
+    }
+
+    private func beginWebAnimationIfReady() {
+        guard phase == .playing, webRendererLoaded else { return }
+        // The approved composition starts its scanner sequence at frame zero. Do not retain
+        // the former wordmark's fixed offset here, or the visible playback will skip the
+        // scanner and reveal stages even when the renderer was initialized at frame zero.
+        animationWebView?.evaluateJavaScript("window.__headcountSplashAnimation?.goToAndPlay(0, true)")
+    }
+
+    public func applicationDidEnterBackground() {
+        animationWebView?.evaluateJavaScript("window.__headcountSplashAnimation?.pause()")
+        if phase == .holding { pauseWaitingClock() }
+    }
+
+    public func applicationDidBecomeActive() {
+        if phase == .playing {
+            animationWebView?.evaluateJavaScript("window.__headcountSplashAnimation?.play()")
+        }
+        else if phase == .holding, let presentationId { scheduleWaitingIndicators(for: presentationId) }
+    }
+
+    private func buildCover(in controller: UIViewController, configuration: LottieSplashConfiguration) {
+        let cover = LottieSplashCoverView(theme: configuration.resolvedTheme)
+        cover.translatesAutoresizingMaskIntoConstraints = false
+        cover.isAccessibilityElement = true
+        cover.accessibilityLabel = "Loading application"
+        cover.accessibilityViewIsModal = true
+        let contentController = WKUserContentController()
+        let messageBridge = LottieSplashMessageBridge()
+        messageBridge.coordinator = self
+        contentController.add(messageBridge, name: "lottieSplash")
+        let webConfiguration = WKWebViewConfiguration()
+        webConfiguration.userContentController = contentController
+        let animation = WKWebView(frame: .zero, configuration: webConfiguration)
+        animation.navigationDelegate = messageBridge
+        animation.isOpaque = false
+        animation.backgroundColor = .clear
+        animation.scrollView.backgroundColor = .clear
+        animation.scrollView.isScrollEnabled = false
+        animation.translatesAutoresizingMaskIntoConstraints = false
+        animation.isAccessibilityElement = false
+        cover.addSubview(animation)
+        controller.view.addSubview(cover)
+        let preferredAnimationWidth = animation.widthAnchor.constraint(equalTo: cover.widthAnchor)
+        preferredAnimationWidth.priority = .defaultHigh
+        NSLayoutConstraint.activate([
+            cover.leadingAnchor.constraint(equalTo: controller.view.leadingAnchor), cover.trailingAnchor.constraint(equalTo: controller.view.trailingAnchor),
+            cover.topAnchor.constraint(equalTo: controller.view.topAnchor), cover.bottomAnchor.constraint(equalTo: controller.view.bottomAnchor),
+            animation.centerXAnchor.constraint(equalTo: cover.centerXAnchor), animation.centerYAnchor.constraint(equalTo: cover.centerYAnchor),
+            // The current composition is square. Give it the full portrait width so artwork
+            // designed near its 512 px edges is not cropped by the legacy wordmark-sized host.
+            // On a short landscape surface, the lower-priority width constraint yields to the
+            // height safety limit while the animation remains centered and fully visible.
+            preferredAnimationWidth,
+            animation.heightAnchor.constraint(equalTo: animation.widthAnchor),
+            animation.heightAnchor.constraint(lessThanOrEqualTo: cover.heightAnchor, multiplier: 0.75)
+        ])
+        self.cover = cover
+        self.animationWebView = animation
+        self.animationMessageBridge = messageBridge
+        self.webRendererLoaded = false
+    }
+
+    private func apply(theme: LottieSplashTheme) {
+        self.theme = theme
+        cover?.apply(theme: theme)
+    }
+
+    func receiveWebAnimationEvent(outcome: String?, reason: String?) {
+        guard phase == .playing else { return }
+        settle(outcome: outcome == "completed" ? "completed" : "static-fallback", reason: reason)
+    }
+
+    private static let webAnimationDocument = """
+    <!doctype html>
+    <html><head><meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
+    <style>html,body{width:100%;height:100%;margin:0;background:transparent;overflow:hidden}body{display:flex;align-items:center;justify-content:center}#animation{width:35%;height:35%;overflow:hidden}canvas{width:100%!important;height:100%!important;display:block}</style>
+    </head><body><div id="animation"></div><script>__LOTTIE_RUNTIME__</script><script>
+    (() => {
+      const report = (outcome, reason) => window.webkit.messageHandlers.lottieSplash.postMessage({ outcome, reason });
+      window.addEventListener('error', event => report('static-fallback', event.message));
+      try {
+          const animationData = __ANIMATION_DATA__;
+          const animation = window.lottie.loadAnimation({
+            container: document.getElementById('animation'), animationData, renderer: 'canvas', loop: false, autoplay: false,
+            rendererSettings: { clearCanvas: true, progressiveLoad: false }
+          });
+          window.__headcountSplashAnimation = animation;
+          // The approved host composition begins its scanner sequence at frame zero. The
+          // former HeadCount wordmark was blank until frame 70, but retaining that legacy
+          // offset skips the new animation's opening motion.
+          animation.goToAndStop(0, true);
+          animation.addEventListener('complete', () => report('completed'));
+          animation.addEventListener('data_failed', () => report('static-fallback', 'Unable to parse the bundled animation'));
+      } catch (error) { report('static-fallback', error.message); }
+    })();
+    </script></body></html>
+    """
+
+    private func settle(outcome: String, reason: String?) {
+        guard let id = presentationId, !playbackSettled else { return }
+        playbackSettled = true
+        phase = appReady ? .hiding : .holding
+        playbackCompletion?(outcome, reason)
+        playbackCompletion = nil
+        if appReady { dismiss(completion: { _ in }) } else { resetWaitingIndicators(for: id) }
+        emitState()
+    }
+
+    private func scheduleWaitingIndicators(for id: String) {
+        guard waitingClockStartedAt == nil, presentationId == id, !appReady, phase == .holding else { return }
+        waitingClockStartedAt = Date()
+        let progress = DispatchWorkItem { [weak self] in
+            guard let self, self.presentationId == id, !self.appReady, self.phase == .holding else { return }
+            self.progressRemaining = 0
+            let rail = LottieSplashLoadingRail(theme: self.theme)
+            rail.translatesAutoresizingMaskIntoConstraints = false
+            self.cover?.addSubview(rail)
+            NSLayoutConstraint.activate([
+                rail.centerXAnchor.constraint(equalTo: self.cover!.centerXAnchor),
+                // The Lottie composition occupies the center. Keep the loading cue just
+                // below its finished tally rather than placing it on top of the artwork.
+                rail.centerYAnchor.constraint(equalTo: self.cover!.centerYAnchor, constant: 100),
+                rail.widthAnchor.constraint(equalToConstant: 104),
+                rail.heightAnchor.constraint(equalToConstant: 3)
+            ])
+            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)
+    }
+
+    private func pauseWaitingClock() {
+        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
+    }
+
+    private func scheduleUnadoptedFallback(for id: String?) {
+        adoptionWorkItem?.cancel()
+        guard let id else { return }
+        let fallback = DispatchWorkItem { [weak self] in
+            guard let self, self.presentationId == id, !self.adoptedByWeb else { return }
+            self.dismiss(completion: { _ in })
+        }
+        adoptionWorkItem = fallback
+        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
+        cancelWaitingTasks()
+        adoptionWorkItem?.cancel()
+        adoptionWorkItem = nil
+        loadingRail?.removeFromSuperview()
+        loadingRail = nil
+        UIView.animate(withDuration: UIAccessibility.isReduceMotionEnabled ? 0 : 0.5, animations: { cover.alpha = 0 }) { [weak self] _ in
+            cover.removeFromSuperview()
+            self?.cover = nil
+            self?.phase = .hidden
+            self?.presentationId = nil
+            self?.animationWebView?.configuration.userContentController.removeScriptMessageHandler(forName: "lottieSplash")
+            self?.animationWebView = nil
+            self?.animationMessageBridge = nil
+            self?.emitState()
+            _ = id
+            completion(nil)
+        }
+        emitState()
+    }
+
+    private func emitState() { onStateChange?(self) }
+}
+
+public enum LottieSplashError: Error { case stalePresentation }

package/ios/Sources/LottieSplashPlugin/LottieSplashPlugin.swift

@@ -0,0 +1,71 @@
+import Capacitor
+
+@objc(LottieSplashPlugin)
+public class LottieSplashPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "LottieSplashPlugin"
+    public let jsName = "LottieSplash"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "show", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "setLaunchTheme", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "waitForCompletion", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "hide", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getState", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getCapabilities", returnType: CAPPluginReturnPromise)
+    ]
+
+    private let coordinator = LottieSplashCoordinator.shared
+
+    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) {
+        DispatchQueue.main.async {
+            let result = self.coordinator.show(configuration: self.configuration(from: call))
+            call.resolve(["presentationId": result.id, "renderer": "ios", "adopted": result.adopted])
+        }
+    }
+
+    @objc public func setLaunchTheme(_ call: CAPPluginCall) {
+        // iOS launch storyboard appearance is selected by UIKit; there is no persistent
+        // per-application night-mode override equivalent to Android's UiModeManager.
+        call.resolve()
+    }
+
+    @objc public func waitForCompletion(_ call: CAPPluginCall) {
+        guard let id = call.getString("presentationId") else { call.reject("presentationId is required"); return }
+        coordinator.waitForCompletion(id: id) { outcome, reason in
+            var result: PluginCallResultData = ["presentationId": id, "outcome": outcome]
+            if let reason { result["reason"] = reason }
+            call.resolve(result)
+        }
+    }
+
+    @objc public func hide(_ call: CAPPluginCall) {
+        guard let id = call.getString("presentationId") else { call.reject("presentationId is required"); return }
+        DispatchQueue.main.async { self.coordinator.hide(id: id) { error in error.map { call.reject($0.localizedDescription) } ?? call.resolve() } }
+    }
+
+    @objc public func getState(_ call: CAPPluginCall) { call.resolve(stateData(coordinator)) }
+
+    @objc public func getCapabilities(_ call: CAPPluginCall) {
+        call.resolve(["apiVersion": 1, "pluginVersion": "0.1.0", "coldStartInstalled": coordinator.presentationId != nil])
+    }
+
+    private func configuration(from call: CAPPluginCall) -> LottieSplashConfiguration {
+        let theme: LottieSplashTheme
+        if let darkMode = call.getBool("darkMode") {
+            theme = darkMode ? .dark : .light
+        } else {
+            // Accept already-delivered web bundles while the host upgrades to the explicit
+            // darkMode contract.
+            theme = call.getString("theme").flatMap(LottieSplashTheme.init(rawValue:)) ?? .dark
+        }
+        return LottieSplashConfiguration(theme: theme)
+    }
+
+    private func stateData(_ coordinator: LottieSplashCoordinator) -> PluginCallResultData {
+        ["presentationId": coordinator.presentationId ?? NSNull(), "phase": coordinator.phase.rawValue, "visible": coordinator.phase != .hidden, "playbackSettled": coordinator.playbackSettled, "appReady": coordinator.appReady, "theme": coordinator.theme.rawValue]
+    }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "capacitor-lottie-splash",
+  "version": "0.1.0",
+  "description": "Native-first Lottie splash presentation for Capacitor 8",
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "unpkg": "dist/plugin.js",
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "android/settings.gradle",
+    "dist/*.js",
+    "dist/esm/*.js",
+    "dist/esm/*.d.ts",
+    "ios/Sources/",
+    "Package.swift",
+    "CapacitorLottieSplash.podspec"
+  ],
+  "author": "HeadCount CMMS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Head-Count-CMMS/CapacitorLottieSplash.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Head-Count-CMMS/CapacitorLottieSplash/issues"
+  },
+  "keywords": [
+    "capacitor",
+    "plugin",
+    "lottie",
+    "splash-screen",
+    "native"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsc && rollup -c rollup.config.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "docgen": "docgen --api LottieSplashPlugin --output-readme README.md --output-json dist/docs.json",
+    "verify:web": "npm run build && npm test",
+    "verify:android": "gradle -p android compileDebugKotlin --no-daemon",
+    "verify:ios": "xcodebuild -scheme CapacitorLottieSplash -destination generic/platform=iOS build",
+    "verify": "npm run verify:web && npm run verify:android && npm run verify:ios",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.0.0"
+  },
+  "dependencies": {
+    "lottie-web": "5.13.0"
+  },
+  "devDependencies": {
+    "@capacitor/android": "8.2.0",
+    "@capacitor/core": "8.2.0",
+    "@capacitor/docgen": "0.3.1",
+    "@capacitor/ios": "8.2.0",
+    "@rollup/plugin-commonjs": "28.0.8",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-typescript": "12.1.4",
+    "rimraf": "6.1.2",
+    "rollup": "4.53.2",
+    "typescript": "5.8.3",
+    "vitest": "3.2.4"
+  },
+  "capacitor": {
+    "pluginId": "capacitor-lottie-splash",
+    "name": "LottieSplash",
+    "ios": {
+      "src": "ios",
+      "pluginClass": "LottieSplashPlugin"
+    },
+    "android": {
+      "src": "android",
+      "pluginClass": "LottieSplashPlugin"
+    }
+  }
+}