capacitor-lottie-splash 0.1.0

package/CapacitorLottieSplash.podspec

@@ -0,0 +1,19 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapacitorLottieSplash'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.resources = 'node_modules/lottie-web/build/player/lottie.min.js'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.dependency 'lottie-ios', '4.6.1'
+  s.swift_version = '5.9'
+end

package/Package.swift

@@ -0,0 +1,30 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapacitorLottieSplash",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "CapacitorLottieSplash", targets: ["LottieSplashPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", exact: "8.2.0"),
+        .package(url: "https://github.com/airbnb/lottie-ios.git", from: "4.6.1")
+    ],
+    targets: [
+        .target(
+            name: "LottieSplashPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "Lottie", package: "lottie-ios")
+            ],
+            path: "ios/Sources/LottieSplashPlugin"
+        ),
+        .testTarget(
+            name: "LottieSplashPluginTests",
+            dependencies: ["LottieSplashPlugin"],
+            path: "ios/Tests/LottieSplashPluginTests"
+        )
+    ]
+)

package/README.md

@@ -0,0 +1,120 @@
+# Capacitor Lottie Splash
+
+`capacitor-lottie-splash` is a Capacitor 8 plugin for an app-owned splash presentation: a static OS launch surface hands off to Lottie on iOS and Android, while browser builds use an isolated DOM overlay.
+
+The package is public. It contains no HeadCount production art; the consuming app bundles its own Lottie JSON, posters, and native launch resources.
+
+## Contract
+
+`show()` attaches a presentation or adopts the native cold-start presentation. `waitForCompletion()` resolves only after Lottie has completed or a visible static fallback has been selected. `hide()` is the app-ready latch: it removes the cover only after both conditions are true.
+
+```ts
+// Resolve and persist the app's appearance before this call. Native cold-start
+// hosts read the same Capacitor Preferences value before JavaScript is running.
+const presentation = await LottieSplash.show({ darkMode: true });
+await LottieSplash.waitForCompletion({ presentationId: presentation.presentationId });
+await LottieSplash.hide({ presentationId: presentation.presentationId });
+```
+
+Repeated `show()` calls adopt an active presentation. Repeated `hide()` calls must use its presentation id. Stale presentation ids are rejected.
+
+## Host startup integration
+
+The native startup hook is intentionally small. A Capacitor bridge plugin cannot begin before the bridge exists, so the app supplies the earliest handoff and this package supplies the native cover.
+
+### iOS
+
+Create a `CAPBridgeViewController` subclass in the app target. Set it as the initial controller class/module in `Main.storyboard`.
+
+```swift
+import Capacitor
+import CapacitorLottieSplash
+
+final class HeadCountBridgeViewController: CAPBridgeViewController {
+    override func capacitorDidLoad() {
+        super.capacitorDidLoad()
+        LottieSplashCoordinator.shared.installInitialCover(on: self)
+    }
+
+    override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        LottieSplashCoordinator.shared.startPlaybackIfVisible()
+    }
+}
+```
+
+## Appearance contract
+
+The host app's appearance preference is the source of truth for a native cold
+start. Store it with Capacitor Preferences before the next launch, then provide
+the same preference mapping when installing the native cover. In HeadCount this
+is the existing `HEADCOUNT_DARK_MODE` key in Capacitor's default
+`CapacitorStorage`, with `DARK_MODE` and `LIGHT_MODE` values. iOS and Android
+both read that stored value before their WebView starts; the OS appearance is
+only the fallback when it has not yet been set.
+
+The JavaScript `show({ darkMode })` call adopts that native presentation. It
+must use the app's already-resolved value and must not recolor an active native
+cold-start cover, which prevents a light/dark flash during boot.
+
+The static launch storyboard remains mandatory. Keep it appearance-aware and visually quiet: it should supply the same base color as the native cover, without a second static logo. The Lottie cover takes over as soon as its initial frame is ready.
+
+### Android
+
+Call `installSystemSplashBeforeCreate()` before `super.onCreate()`, and attach the one native cover from `load()` before `super.load()`. Do not use a dedicated splash activity or a second process: both produce a visible reset during the handoff.
+
+```kotlin
+class MainActivity : BridgeActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        LottieSplashLaunch.installSystemSplashBeforeCreate(this)
+        super.onCreate(savedInstanceState)
+    }
+
+    override fun load() {
+        LottieSplashLaunch.attachNativeCover(this, darkTheme = true)
+        super.load()
+    }
+
+    override fun onPause() {
+        LottieSplashLaunch.onHostPaused()
+        super.onPause()
+    }
+
+    override fun onResume() {
+        super.onResume()
+        LottieSplashLaunch.onHostResumed()
+    }
+}
+```
+
+The system splash is a platform-controlled centered icon on a single color. It cannot render the full Lottie or gradient. Use a transparent system icon with an appearance-aware background when a second static mark would be distracting. The helper retains it only until the native cover has attached, then fades it out; it does not wait for application readiness.
+
+## Assets
+
+The host provides:
+
+- `android/app/src/main/assets/lottie-splash/animatedLogo.json`;
+- an iOS app-bundle `animatedLogo.json` resource;
+- system-launch colors and the Android adaptive splash icon.
+
+The documented HeadCount defaults are light `#f0f0f0 → #f5f5f5` and dark `#1e1e1e → #252525`, left to right.
+
+## 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.
+
+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.
+
+## Compatibility
+
+Native resources cannot be changed by a web-only Capgo update. Before adopting this plugin, the host must define its old/new native-binary and web-bundle compatibility policy. The 30-second compatibility escape hatch prevents a stuck screen while allowing a slow but healthy cold start to adopt the native cover; an old bundle cannot provide the new loading experience.
+
+## Verification
+
+```sh
+npm run verify:web
+npm run verify:android
+npm run verify:ios
+```
+
+Native launch continuity requires real-device evidence; unit/build verification alone cannot prove the OS-to-native handoff.

package/android/build.gradle

@@ -0,0 +1,36 @@
+buildscript {
+    repositories { google(); mavenCentral() }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+
+android {
+    namespace 'com.headcount.plugins.lottiesplash'
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 26
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        testInstrumentationRunner 'androidx.test.runner.AndroidJUnitRunner'
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+    kotlinOptions { jvmTarget = '21' }
+    testOptions { unitTests.returnDefaultValues = true }
+}
+
+repositories { google(); mavenCentral() }
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation 'androidx.core:core-splashscreen:1.2.0'
+    implementation 'com.airbnb.android:lottie:6.7.1'
+    testImplementation 'junit:junit:4.13.2'
+}

package/android/settings.gradle

@@ -0,0 +1,7 @@
+pluginManagement {
+    repositories { google(); mavenCentral(); gradlePluginPortal() }
+}
+
+rootProject.name = 'capacitor-lottie-splash-android'
+include ':capacitor-android'
+project(':capacitor-android').projectDir = new File('../node_modules/@capacitor/android/capacitor')

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application />
+</manifest>