react-native-icon-switcher 0.1.4 → 0.1.7

package/README.md

@@ -107,6 +107,10 @@ Icons with no art for a platform are omitted from that platform's generated outp
 
 **Android reserved names:** names may not be `round`, `foreground`, `background`, or `monochrome`, nor end in `_round`, `_foreground`, `_background`, or `_monochrome`.
 
+**Legacy Android icons (API 24–25):** besides the adaptive layers and `mipmap-anydpi-v26` XML, `sync` and the plugin write `ic_launcher*.png` the way Android Studio's Image Asset tool does: the visible centre of an adaptive icon (72 dp of the 108 dp layers; a plain path uses the whole image) in a 38 dp rounded square or a 44 dp circle, with a soft drop shadow, on a transparent 48 dp canvas.
+
+**Managed iOS icon sets:** when `sync` or the plugin rewrites an `.appiconset` it owns, it deletes files in that folder that the new `Contents.json` does not reference (`sync --check` reports them). Other icon sets are left alone.
+
 ## Usage
 
 ```ts
@@ -238,7 +242,7 @@ it('applies a pending switch', async () => {
 
 Deferred apply, task recreation when aliases toggle, the `applyPending()` foreground guard, cold-start behaviour, and launcher shortcuts are documented in [docs/guides/android.md](docs/guides/android.md).
 
-Summary: with default `applyOn: 'background'`, `set()` returns `pending` and the launcher updates after the user leaves the app; the process usually survives but the next open may look like a cold start. `applyPending()` in the foreground is refused with `foreground`.
+Summary: with default `applyOn: 'background'`, `set()` returns `pending` and the launcher updates when the last screen stops (including swipe-away from Recents) or after you background the app; listening starts at process start via AndroidX Startup. The process usually survives but the next open may look like a cold start. `applyPending()` in the foreground is refused with `foreground`.
 
 ## Requirements
 

package/android/build.gradle

@@ -43,6 +43,7 @@ android {
 dependencies {
   implementation "com.facebook.react:react-android"
   implementation "androidx.lifecycle:lifecycle-process:2.8.7"
+  implementation "androidx.startup:startup-runtime:1.2.0"
 
   testImplementation "androidx.test:core:1.7.0"
   testImplementation "junit:junit:4.13.2"

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,16 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  xmlns:tools="http://schemas.android.com/tools">
+
+  <application>
+    <provider
+      android:name="androidx.startup.InitializationProvider"
+      android:authorities="${applicationId}.androidx-startup"
+      android:exported="false"
+      tools:node="merge">
+      <meta-data
+        android:name="com.iconswitcher.IconSwitcherInitializer"
+        android:value="androidx.startup"
+        tools:node="merge" />
+    </provider>
+  </application>
 </manifest>

package/android/src/main/java/com/iconswitcher/IconSwitcher.kt

@@ -1,5 +1,7 @@
 package com.iconswitcher
 
+import android.app.Activity
+import android.app.Application
 import android.content.ComponentName
 import android.content.Context
 import android.content.pm.ApplicationInfo
@@ -7,6 +9,7 @@ import android.content.pm.PackageManager
 import android.os.Build
 import android.os.Handler
 import android.os.Looper
+import androidx.annotation.VisibleForTesting
 import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleOwner
@@ -25,9 +28,13 @@ class IconSwitcher internal constructor(
   private val packageName: String,
   private val prefs: android.content.SharedPreferences,
   private val lifecycleRegistrar: (DefaultLifecycleObserver) -> Unit,
+  private val activityLifecycleRegistrar: (Application.ActivityLifecycleCallbacks) -> Unit,
   private val isInForeground: () -> Boolean,
 ) {
   private val writeExecutor = Executors.newSingleThreadExecutor()
+  private val processStartLock = Any()
+  private var processStartInitialized = false
+  private var startedActivityCount = 0
 
   private val markedAliases: Map<String, ComponentName> by lazy { discoverMarkedAliases() }
   private val applyOn: String by lazy { readApplyOn() }
@@ -53,6 +60,9 @@ class IconSwitcher internal constructor(
         }
       }
     },
+    activityLifecycleRegistrar = { callbacks ->
+      (context.applicationContext as Application).registerActivityLifecycleCallbacks(callbacks)
+    },
     isInForeground = {
       ProcessLifecycleOwner.get().lifecycle.currentState.isAtLeast(Lifecycle.State.STARTED)
     },
@@ -67,21 +77,33 @@ class IconSwitcher internal constructor(
     packageName = context.applicationContext.packageName,
     prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE),
     lifecycleRegistrar = { },
+    activityLifecycleRegistrar = { },
     isInForeground = { false },
   )
 
   fun onModuleCreate() {
-    lifecycleRegistrar(
-      object : DefaultLifecycleObserver {
-        override fun onStop(owner: LifecycleOwner) {
-          val pending = prefs.getString(KEY_PENDING, null)
-          if (pending != null) {
-            runApply(pending, deferred = true)
+    onProcessStart()
+  }
+
+  fun onProcessStart() {
+    synchronized(processStartLock) {
+      if (processStartInitialized) {
+        return
+      }
+      activityLifecycleRegistrar(createActivityLifecycleCallbacks())
+      lifecycleRegistrar(
+        object : DefaultLifecycleObserver {
+          override fun onStop(owner: LifecycleOwner) {
+            val pending = prefs.getString(KEY_PENDING, null)
+            if (pending != null) {
+              runApply(pending, deferred = true)
+            }
           }
-        }
-      },
-    )
-    runColdStart()
+        },
+      )
+      runColdStart()
+      processStartInitialized = true
+    }
   }
 
   fun current(): String {
@@ -126,6 +148,41 @@ class IconSwitcher internal constructor(
     return SetResult(STATUS_APPLIED)
   }
 
+  private fun createActivityLifecycleCallbacks(): Application.ActivityLifecycleCallbacks {
+    return object : Application.ActivityLifecycleCallbacks {
+      override fun onActivityStarted(activity: Activity) {
+        startedActivityCount++
+      }
+
+      override fun onActivityStopped(activity: Activity) {
+        // Clamped: when registered late (no startup provider, so from the module),
+        // activities that started earlier were never counted.
+        startedActivityCount = maxOf(0, startedActivityCount - 1)
+        if (startedActivityCount == 0 && !activity.isChangingConfigurations) {
+          val pending = prefs.getString(KEY_PENDING, null)
+          if (pending != null) {
+            applyPendingOnLastActivityStop(pending)
+          }
+        }
+      }
+
+      override fun onActivityCreated(activity: Activity, savedInstanceState: android.os.Bundle?) {}
+      override fun onActivityResumed(activity: Activity) {}
+      override fun onActivityPaused(activity: Activity) {}
+      override fun onActivitySaveInstanceState(activity: Activity, outState: android.os.Bundle) {}
+      override fun onActivityDestroyed(activity: Activity) {}
+    }
+  }
+
+  private fun applyPendingOnLastActivityStop(name: String) {
+    val future = submitOnWriteExecutor { applyOnExecutor(name, deferred = true) }
+    try {
+      future.get()
+    } catch (_: Exception) {
+      // applyOnExecutor stores lastError for deferred failures; never propagate here.
+    }
+  }
+
   private fun runColdStart() {
     if (prefs.getString(KEY_PENDING, null) != null) {
       return
@@ -376,5 +433,23 @@ class IconSwitcher internal constructor(
     const val STATUS_APPLIED = "applied"
     const val STATUS_PENDING = "pending"
     const val STATUS_NONE = "none"
+
+    @Volatile
+    private var instance: IconSwitcher? = null
+
+    fun getInstance(context: Context): IconSwitcher {
+      val appContext = context.applicationContext
+      instance?.let { return it }
+      return synchronized(this) {
+        instance ?: IconSwitcher(appContext).also { instance = it }
+      }
+    }
+
+    @VisibleForTesting
+    internal fun clearInstanceForTests() {
+      synchronized(this) {
+        instance = null
+      }
+    }
   }
 }

package/android/src/main/java/com/iconswitcher/IconSwitcherInitializer.kt

@@ -0,0 +1,15 @@
+package com.iconswitcher
+
+import android.content.Context
+import androidx.lifecycle.ProcessLifecycleInitializer
+import androidx.startup.Initializer
+
+class IconSwitcherInitializer : Initializer<Unit> {
+  override fun create(context: Context) {
+    IconSwitcher.getInstance(context).onProcessStart()
+  }
+
+  override fun dependencies(): List<Class<out Initializer<*>>> {
+    return listOf(ProcessLifecycleInitializer::class.java)
+  }
+}

package/android/src/main/java/com/iconswitcher/IconSwitcherModule.kt

@@ -8,7 +8,7 @@ import com.facebook.react.bridge.WritableMap
 class IconSwitcherModule(reactContext: ReactApplicationContext) :
   NativeIconSwitcherSpec(reactContext) {
 
-  private val switcher = IconSwitcher(reactApplicationContext)
+  private val switcher = IconSwitcher.getInstance(reactApplicationContext)
 
   override fun initialize() {
     super.initialize()

package/android/src/test/java/com/iconswitcher/IconSwitcherTest.kt

@@ -1,5 +1,7 @@
 package com.iconswitcher
 
+import android.app.Activity
+import android.app.Application
 import android.content.ComponentName
 import android.content.Context
 import android.content.pm.ActivityInfo
@@ -34,6 +36,7 @@ class IconSwitcherTest {
 
   @Before
   fun setUp() {
+    IconSwitcher.clearInstanceForTests()
     context = ApplicationProvider.getApplicationContext()
     context.getSharedPreferences(IconSwitcher.PREFS_NAME, Context.MODE_PRIVATE)
       .edit()
@@ -205,6 +208,7 @@ class IconSwitcherTest {
       packageName = packageName,
       prefs = prefs,
       lifecycleRegistrar = { lifecycleObserver = it },
+      activityLifecycleRegistrar = { },
       isInForeground = { false },
     )
 
@@ -331,6 +335,231 @@ class IconSwitcherTest {
     ShadowLooper.idleMainLooper()
   }
 
+  @Test
+  fun initializer_starts_singleton_without_react_module() {
+    IconSwitcherInitializer().create(context)
+    val fromInitializer = IconSwitcher.getInstance(context)
+    assertTrue(fromInitializer.isSupported)
+  }
+
+  @Test
+  fun on_process_start_twice_registers_activity_callbacks_once() {
+    var registrationCount = 0
+    val pm = mockk<PackageManager>(relaxed = true)
+    every { pm.getPackageInfo(any<String>(), any<Int>()) } returns robolectricPackageInfo(context.packageName)
+    every { pm.getApplicationInfo(any<String>(), any<Int>()) } returns robolectricApplicationInfo()
+    val switcher = switcherWithActivityCallbacks(
+      pm = pm,
+      onRegister = { registrationCount++ },
+    )
+    switcher.onProcessStart()
+    switcher.onProcessStart()
+    assertEquals(1, registrationCount)
+  }
+
+  @Test
+  fun getInstance_is_shared_between_initializer_calls() {
+    IconSwitcherInitializer().create(context)
+    val first = IconSwitcher.getInstance(context)
+    val second = IconSwitcher.getInstance(context)
+    assertTrue(first === second)
+  }
+
+  @Test
+  fun last_activity_stop_applies_pending_before_on_activity_stopped_returns() {
+    val pm = mockk<PackageManager>(relaxed = true)
+    val packageName = context.packageName
+    every { pm.getPackageInfo(any<String>(), any<Int>()) } returns robolectricPackageInfo(packageName)
+    every { pm.getApplicationInfo(any<String>(), any<Int>()) } returns robolectricApplicationInfo()
+    val settingsSlot = slot<List<PackageManager.ComponentEnabledSetting>>()
+    every { pm.setComponentEnabledSettings(capture(settingsSlot)) } returns Unit
+    every { pm.getComponentEnabledSetting(any()) } answers {
+      val component = firstArg<ComponentName>()
+      if (component.className == ".IconSwitcher_halloween") {
+        PackageManager.COMPONENT_ENABLED_STATE_ENABLED
+      } else {
+        PackageManager.COMPONENT_ENABLED_STATE_DISABLED
+      }
+    }
+
+    val prefs = context.getSharedPreferences(IconSwitcher.PREFS_NAME, Context.MODE_PRIVATE)
+    prefs.edit().putString(IconSwitcher.KEY_PENDING, "halloween").apply()
+
+    var callbacks: Application.ActivityLifecycleCallbacks? = null
+    val switcher = switcherWithActivityCallbacks(pm) { callbacks = it }
+    switcher.onProcessStart()
+
+    val activity = mockk<Activity>(relaxed = true)
+    every { activity.isChangingConfigurations } returns false
+    callbacks!!.onActivityStarted(activity)
+    callbacks!!.onActivityStopped(activity)
+
+    assertTrue(
+      settingsSlot.captured.any {
+        it.componentName!!.className == ".IconSwitcher_halloween" &&
+          it.enabledFlags == PackageManager.DONT_KILL_APP
+      },
+    )
+    assertEquals(null, prefs.getString(IconSwitcher.KEY_PENDING, null))
+    assertEquals("halloween", prefs.getString(IconSwitcher.KEY_CURRENT, null))
+  }
+
+  @Test
+  fun last_activity_stop_applies_when_callbacks_were_registered_after_it_started() {
+    // No startup provider: listening starts from the module while a screen is
+    // already open, so its start was never counted.
+    val pm = mockk<PackageManager>(relaxed = true)
+    val packageName = context.packageName
+    every { pm.getPackageInfo(any<String>(), any<Int>()) } returns robolectricPackageInfo(packageName)
+    every { pm.getApplicationInfo(any<String>(), any<Int>()) } returns robolectricApplicationInfo()
+    val settingsSlot = slot<List<PackageManager.ComponentEnabledSetting>>()
+    every { pm.setComponentEnabledSettings(capture(settingsSlot)) } returns Unit
+    every { pm.getComponentEnabledSetting(any()) } answers {
+      val component = firstArg<ComponentName>()
+      if (component.className == ".IconSwitcher_halloween") {
+        PackageManager.COMPONENT_ENABLED_STATE_ENABLED
+      } else {
+        PackageManager.COMPONENT_ENABLED_STATE_DISABLED
+      }
+    }
+
+    val prefs = context.getSharedPreferences(IconSwitcher.PREFS_NAME, Context.MODE_PRIVATE)
+    prefs.edit().putString(IconSwitcher.KEY_PENDING, "halloween").apply()
+
+    var callbacks: Application.ActivityLifecycleCallbacks? = null
+    val switcher = switcherWithActivityCallbacks(pm) { callbacks = it }
+    switcher.onProcessStart()
+
+    val activity = mockk<Activity>(relaxed = true)
+    every { activity.isChangingConfigurations } returns false
+    callbacks!!.onActivityStopped(activity)
+
+    assertTrue(settingsSlot.isCaptured)
+    assertEquals(null, prefs.getString(IconSwitcher.KEY_PENDING, null))
+    assertEquals("halloween", prefs.getString(IconSwitcher.KEY_CURRENT, null))
+  }
+
+  @Test
+  fun last_activity_stop_with_two_activities_applies_only_after_both_stop() {
+    val pm = mockk<PackageManager>(relaxed = true)
+    val packageName = context.packageName
+    every { pm.getPackageInfo(any<String>(), any<Int>()) } returns robolectricPackageInfo(packageName)
+    every { pm.getApplicationInfo(any<String>(), any<Int>()) } returns robolectricApplicationInfo()
+
+    val prefs = context.getSharedPreferences(IconSwitcher.PREFS_NAME, Context.MODE_PRIVATE)
+    prefs.edit().putString(IconSwitcher.KEY_PENDING, "halloween").apply()
+
+    var callbacks: Application.ActivityLifecycleCallbacks? = null
+    val switcher = switcherWithActivityCallbacks(pm) { callbacks = it }
+    switcher.onProcessStart()
+
+    val first = mockk<Activity>(relaxed = true)
+    val second = mockk<Activity>(relaxed = true)
+    every { first.isChangingConfigurations } returns false
+    every { second.isChangingConfigurations } returns false
+
+    callbacks!!.onActivityStarted(first)
+    callbacks!!.onActivityStarted(second)
+    callbacks!!.onActivityStopped(second)
+    verify(exactly = 0) { pm.setComponentEnabledSettings(any()) }
+
+    every { pm.getComponentEnabledSetting(any()) } answers {
+      val component = firstArg<ComponentName>()
+      if (component.className == ".IconSwitcher_halloween") {
+        PackageManager.COMPONENT_ENABLED_STATE_ENABLED
+      } else {
+        PackageManager.COMPONENT_ENABLED_STATE_DISABLED
+      }
+    }
+    every { pm.setComponentEnabledSettings(any<List<PackageManager.ComponentEnabledSetting>>()) } returns Unit
+
+    callbacks!!.onActivityStopped(first)
+    verify(exactly = 1) { pm.setComponentEnabledSettings(any()) }
+  }
+
+  @Test
+  fun last_activity_stop_during_configuration_change_does_not_apply() {
+    val pm = mockk<PackageManager>(relaxed = true)
+    every { pm.getPackageInfo(any<String>(), any<Int>()) } returns robolectricPackageInfo(context.packageName)
+    every { pm.getApplicationInfo(any<String>(), any<Int>()) } returns robolectricApplicationInfo()
+
+    context.getSharedPreferences(IconSwitcher.PREFS_NAME, Context.MODE_PRIVATE)
+      .edit()
+      .putString(IconSwitcher.KEY_PENDING, "halloween")
+      .apply()
+
+    var callbacks: Application.ActivityLifecycleCallbacks? = null
+    val switcher = switcherWithActivityCallbacks(pm) { callbacks = it }
+    switcher.onProcessStart()
+
+    val activity = mockk<Activity>(relaxed = true)
+    every { activity.isChangingConfigurations } returns true
+    callbacks!!.onActivityStarted(activity)
+    callbacks!!.onActivityStopped(activity)
+
+    verify(exactly = 0) { pm.setComponentEnabledSettings(any()) }
+  }
+
+  @Test
+  fun last_activity_stop_without_pending_does_nothing() {
+    val pm = mockk<PackageManager>(relaxed = true)
+    every { pm.getPackageInfo(any<String>(), any<Int>()) } returns robolectricPackageInfo(context.packageName)
+    every { pm.getApplicationInfo(any<String>(), any<Int>()) } returns robolectricApplicationInfo()
+
+    var callbacks: Application.ActivityLifecycleCallbacks? = null
+    val switcher = switcherWithActivityCallbacks(pm) { callbacks = it }
+    switcher.onProcessStart()
+
+    val activity = mockk<Activity>(relaxed = true)
+    every { activity.isChangingConfigurations } returns false
+    callbacks!!.onActivityStarted(activity)
+    callbacks!!.onActivityStopped(activity)
+
+    verify(exactly = 0) { pm.setComponentEnabledSettings(any()) }
+  }
+
+  @Test
+  fun last_activity_stop_apply_failure_stores_last_error_without_throwing() {
+    val pm = mockk<PackageManager>(relaxed = true)
+    every { pm.getPackageInfo(any<String>(), any<Int>()) } returns robolectricPackageInfo(context.packageName)
+    every { pm.getApplicationInfo(any<String>(), any<Int>()) } returns robolectricApplicationInfo()
+    every { pm.setComponentEnabledSettings(any<List<PackageManager.ComponentEnabledSetting>>()) } throws
+      RuntimeException("pm failed")
+    every { pm.getComponentEnabledSetting(any()) } returns PackageManager.COMPONENT_ENABLED_STATE_DISABLED
+
+    val prefs = context.getSharedPreferences(IconSwitcher.PREFS_NAME, Context.MODE_PRIVATE)
+    prefs.edit().putString(IconSwitcher.KEY_PENDING, "halloween").apply()
+
+    var callbacks: Application.ActivityLifecycleCallbacks? = null
+    val switcher = switcherWithActivityCallbacks(pm) { callbacks = it }
+    switcher.onProcessStart()
+
+    val activity = mockk<Activity>(relaxed = true)
+    every { activity.isChangingConfigurations } returns false
+    callbacks!!.onActivityStarted(activity)
+    callbacks!!.onActivityStopped(activity)
+
+    assertEquals("halloween", prefs.getString(IconSwitcher.KEY_PENDING, null))
+    assertEquals("pm failed", prefs.getString(IconSwitcher.KEY_LAST_ERROR, null))
+  }
+
+  private fun switcherWithActivityCallbacks(
+    pm: PackageManager,
+    prefs: android.content.SharedPreferences =
+      context.getSharedPreferences(IconSwitcher.PREFS_NAME, Context.MODE_PRIVATE),
+    onRegister: (Application.ActivityLifecycleCallbacks) -> Unit = { },
+  ): IconSwitcher {
+    return IconSwitcher(
+      context = context,
+      packageManager = pm,
+      packageName = context.packageName,
+      prefs = prefs,
+      lifecycleRegistrar = { },
+      activityLifecycleRegistrar = onRegister,
+      isInForeground = { false },
+    )
+  }
+
   private fun switcherWithForeground(
     pm: PackageManager,
     inForeground: Boolean,
@@ -343,6 +572,7 @@ class IconSwitcherTest {
       packageName = context.packageName,
       prefs = prefs,
       lifecycleRegistrar = { },
+      activityLifecycleRegistrar = { },
       isInForeground = { inForeground },
     )
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-icon-switcher",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Switch the app icon at runtime on React Native and Expo from one config file, with the native wiring generated for you",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/plugin/build/core/assets.d.ts

@@ -1,4 +1,17 @@
 import type { HexColor, ResolvedConfig } from '../types';
+/** Drop shadow tuned to match Image Asset exports at xxxhdpi. */
+export declare const LEGACY_SHADOW_OFFSET_Y_DP = 0.75;
+export declare const LEGACY_SHADOW_BLUR_DP = 1;
+export declare const LEGACY_SHADOW_OPACITY = 0.25;
+/**
+ * Largest per-channel difference at which two PNGs still count as the same
+ * image. libvips resampling rounds slightly differently on arm64 and x86, so
+ * icons generated on a Mac and re-generated in Linux CI can differ by a level
+ * or two without any visible change.
+ */
+export declare const PNG_PIXEL_TOLERANCE = 3;
+/** True when both buffers are PNGs of the same size whose pixels differ by at most `PNG_PIXEL_TOLERANCE`. */
+export declare function pngsMatchWithinTolerance(a: Buffer, b: Buffer): Promise<boolean>;
 export type IosVariant = 'light' | 'dark' | 'tinted';
 export type AssetJob = {
     kind: 'ios-png';
@@ -72,6 +85,13 @@ export declare function writeAssets(plan: AssetPlan, opts: {
     iosAssetCatalog: string;
     androidResDir: string;
 }): Promise<WrittenFile[]>;
+/**
+ * Remove unreferenced files from managed `.appiconset` folders in `plan`.
+ * Returns absolute paths of stale files (removed or that would be removed in check mode).
+ */
+export declare function pruneStaleIosAppIconSets(iosAssetCatalog: string, plan: AssetPlan, opts: {
+    check: boolean;
+}): Promise<string[]>;
 /** Test helper: corner pixel RGB after iOS flatten (alpha removed). */
 export declare function _readCornerRgb(pngPath: string): Promise<{
     r: number;

package/plugin/build/core/assets.js

@@ -3,8 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PNG_PIXEL_TOLERANCE = exports.LEGACY_SHADOW_OPACITY = exports.LEGACY_SHADOW_BLUR_DP = exports.LEGACY_SHADOW_OFFSET_Y_DP = void 0;
+exports.pngsMatchWithinTolerance = pngsMatchWithinTolerance;
 exports.planAssets = planAssets;
 exports.writeAssets = writeAssets;
+exports.pruneStaleIosAppIconSets = pruneStaleIosAppIconSets;
 exports._readCornerRgb = _readCornerRgb;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const promises_1 = __importDefault(require("node:fs/promises"));
@@ -25,6 +28,47 @@ const ADAPTIVE_DENSITIES = [
     { folder: 'mipmap-xxxhdpi', size: 432 },
 ];
 const PNG_OPTIONS = { compressionLevel: 9, adaptiveFiltering: false };
+/** Legacy launcher canvas (API 24–25), matching Android Studio Image Asset at 48 dp. */
+const LEGACY_CANVAS_DP = 48;
+const LEGACY_SQUARE_INSET_DP = 5;
+const LEGACY_SQUARE_BODY_DP = 38;
+const LEGACY_SQUARE_RADIUS_DP = 3;
+const LEGACY_ROUND_INSET_DP = 2;
+const LEGACY_ROUND_DIAMETER_DP = 44;
+const ADAPTIVE_LAYER_DP = 108;
+const ADAPTIVE_VIEWPORT_DP = 72;
+/** Drop shadow tuned to match Image Asset exports at xxxhdpi. */
+exports.LEGACY_SHADOW_OFFSET_Y_DP = 0.75;
+exports.LEGACY_SHADOW_BLUR_DP = 1;
+exports.LEGACY_SHADOW_OPACITY = 0.25;
+/**
+ * Largest per-channel difference at which two PNGs still count as the same
+ * image. libvips resampling rounds slightly differently on arm64 and x86, so
+ * icons generated on a Mac and re-generated in Linux CI can differ by a level
+ * or two without any visible change.
+ */
+exports.PNG_PIXEL_TOLERANCE = 3;
+const PNG_SIGNATURE = Buffer.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+/** True when both buffers are PNGs of the same size whose pixels differ by at most `PNG_PIXEL_TOLERANCE`. */
+async function pngsMatchWithinTolerance(a, b) {
+    if (!a.subarray(0, 8).equals(PNG_SIGNATURE) ||
+        !b.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        return false;
+    }
+    const [left, right] = await Promise.all([a, b].map((buf) => (0, sharp_1.default)(buf).ensureAlpha().raw().toBuffer({ resolveWithObject: true })));
+    if (left.info.width !== right.info.width ||
+        left.info.height !== right.info.height) {
+        return false;
+    }
+    for (let i = 0; i < left.data.length; i += 1) {
+        if (Math.abs(left.data[i] - right.data[i]) > exports.PNG_PIXEL_TOLERANCE) {
+            return false;
+        }
+    }
+    return true;
+}
 function _iosSetFolder(icon) {
     return icon.isDefault
         ? 'AppIcon.appiconset'
@@ -274,31 +318,123 @@ async function _flattenPng(sourceAbs, flattenOn, width, height) {
         .png(PNG_OPTIONS)
         .toBuffer();
 }
-async function _applyRoundMask(image, size) {
-    const mask = Buffer.from(`<svg width="${size}" height="${size}"><circle cx="${size / 2}" cy="${size / 2}" r="${size / 2}" fill="white"/></svg>`);
-    return (0, sharp_1.default)(image)
+function _legacyDpToPx(dp, canvasPx) {
+    return Math.round((dp * canvasPx) / LEGACY_CANVAS_DP);
+}
+function _legacyShapeLayout(canvasPx, round) {
+    if (round) {
+        const inset = _legacyDpToPx(LEGACY_ROUND_INSET_DP, canvasPx);
+        const bodyPx = _legacyDpToPx(LEGACY_ROUND_DIAMETER_DP, canvasPx);
+        return { inset, bodyPx, radiusPx: bodyPx / 2 };
+    }
+    return {
+        inset: _legacyDpToPx(LEGACY_SQUARE_INSET_DP, canvasPx),
+        bodyPx: _legacyDpToPx(LEGACY_SQUARE_BODY_DP, canvasPx),
+        radiusPx: _legacyDpToPx(LEGACY_SQUARE_RADIUS_DP, canvasPx),
+    };
+}
+function _legacyShapeMaskSvg(bodyPx, round, radiusPx) {
+    if (round) {
+        const r = bodyPx / 2;
+        return Buffer.from(`<svg width="${bodyPx}" height="${bodyPx}"><circle cx="${r}" cy="${r}" r="${r}" fill="white"/></svg>`);
+    }
+    return Buffer.from(`<svg width="${bodyPx}" height="${bodyPx}"><rect width="${bodyPx}" height="${bodyPx}" rx="${radiusPx}" ry="${radiusPx}" fill="white"/></svg>`);
+}
+async function _legacyMaskedContent(content, bodyPx, round, radiusPx) {
+    const mask = _legacyShapeMaskSvg(bodyPx, round, radiusPx);
+    return (0, sharp_1.default)(content)
+        .resize(bodyPx, bodyPx, { fit: 'cover' })
+        .ensureAlpha()
         .composite([{ input: mask, blend: 'dest-in' }])
-        .png(PNG_OPTIONS)
+        .png()
         .toBuffer();
 }
-async function _legacyPng(sourceAbs, size, round) {
-    const resized = await (0, sharp_1.default)(sourceAbs)
-        .resize(size, size, { fit: 'cover' })
-        .png()
+function _boxBlurLine(src, size, radius, horizontal) {
+    const out = new Uint8Array(src.length);
+    const window = radius * 2 + 1;
+    for (let line = 0; line < size; line += 1) {
+        const at = (i) => (horizontal ? line * size + i : i * size + line);
+        let sum = 0;
+        for (let i = -radius; i <= radius; i += 1) {
+            if (i >= 0 && i < size) {
+                sum += src[at(i)];
+            }
+        }
+        for (let i = 0; i < size; i += 1) {
+            out[at(i)] = Math.floor(sum / window);
+            const leaving = i - radius;
+            const entering = i + radius + 1;
+            if (leaving >= 0) {
+                sum -= src[at(leaving)];
+            }
+            if (entering < size) {
+                sum += src[at(entering)];
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Black drop shadow of the shape on a transparent canvas. The blur is done in
+ * integer arithmetic here rather than with an SVG filter: librsvg's float blur
+ * produced different bytes on macOS and Linux, which broke `sync --check` in CI.
+ */
+async function _legacyShadowLayer(canvasPx, shapeMarkup, offsetY, blurPx) {
+    const shapeSvg = Buffer.from(`<svg width="${canvasPx}" height="${canvasPx}" xmlns="http://www.w3.org/2000/svg">${shapeMarkup}</svg>`);
+    const shape = await (0, sharp_1.default)(shapeSvg)
+        .ensureAlpha()
+        .extractChannel(3)
+        .raw()
         .toBuffer();
-    if (!round) {
-        return (0, sharp_1.default)(resized).png(PNG_OPTIONS).toBuffer();
+    // Three box-blur passes approximate a Gaussian.
+    const radius = Math.max(1, Math.round(blurPx / 2));
+    let alpha = Uint8Array.from(shape);
+    for (let pass = 0; pass < 3; pass += 1) {
+        alpha = _boxBlurLine(alpha, canvasPx, radius, true);
+        alpha = _boxBlurLine(alpha, canvasPx, radius, false);
+    }
+    const opacity256 = Math.round(exports.LEGACY_SHADOW_OPACITY * 256);
+    const rgba = Buffer.alloc(canvasPx * canvasPx * 4);
+    for (let y = 0; y < canvasPx; y += 1) {
+        const sourceY = y - offsetY;
+        if (sourceY < 0 || sourceY >= canvasPx) {
+            continue;
+        }
+        for (let x = 0; x < canvasPx; x += 1) {
+            const a = alpha[sourceY * canvasPx + x];
+            rgba[(y * canvasPx + x) * 4 + 3] = Math.floor((a * opacity256) / 256);
+        }
     }
-    return _applyRoundMask(resized, size);
+    return (0, sharp_1.default)(rgba, {
+        raw: { width: canvasPx, height: canvasPx, channels: 4 },
+    })
+        .png()
+        .toBuffer();
 }
-async function _legacyCompositePng(foregroundAbs, size, round, background) {
+async function _legacyStudioPng(content, canvasPx, round) {
+    const { inset, bodyPx, radiusPx } = _legacyShapeLayout(canvasPx, round);
+    const masked = await _legacyMaskedContent(content, bodyPx, round, radiusPx);
+    const shadowOffsetY = _legacyDpToPx(exports.LEGACY_SHADOW_OFFSET_Y_DP, canvasPx);
+    const blurPx = Math.max(1, _legacyDpToPx(exports.LEGACY_SHADOW_BLUR_DP, canvasPx));
+    const cx = inset + bodyPx / 2;
+    const cy = inset + bodyPx / 2;
+    const shapeMarkup = round
+        ? `<circle cx="${cx}" cy="${cy}" r="${bodyPx / 2}" fill="#000"/>`
+        : `<rect x="${inset}" y="${inset}" width="${bodyPx}" height="${bodyPx}" rx="${radiusPx}" ry="${radiusPx}" fill="#000"/>`;
+    const shadowLayer = await _legacyShadowLayer(canvasPx, shapeMarkup, shadowOffsetY, blurPx);
+    return (0, sharp_1.default)(shadowLayer)
+        .composite([{ input: masked, left: inset, top: inset, blend: 'over' }])
+        .png(PNG_OPTIONS)
+        .toBuffer();
+}
+async function _adaptiveLayerComposite(foregroundAbs, layerPx, background) {
     let base;
     if ('color' in background) {
         const { r, g, b } = _hexToRgb(background.color);
         base = await (0, sharp_1.default)({
             create: {
-                width: size,
-                height: size,
+                width: layerPx,
+                height: layerPx,
                 channels: 4,
                 background: { r, g, b, alpha: 255 },
             },
@@ -308,25 +444,41 @@ async function _legacyCompositePng(foregroundAbs, size, round, background) {
     }
     else {
         base = await (0, sharp_1.default)(background.imageAbs)
-            .resize(size, size, { fit: 'cover' })
+            .resize(layerPx, layerPx, { fit: 'cover' })
             .png()
             .toBuffer();
     }
     const foreground = await (0, sharp_1.default)(foregroundAbs)
-        .resize(size, size, {
+        .resize(layerPx, layerPx, {
         fit: 'contain',
         background: { r: 0, g: 0, b: 0, alpha: 0 },
     })
         .png()
         .toBuffer();
-    const flat = await (0, sharp_1.default)(base)
+    const cropPx = Math.round((layerPx * ADAPTIVE_VIEWPORT_DP) / ADAPTIVE_LAYER_DP);
+    const cropInset = Math.round((layerPx - cropPx) / 2);
+    const composed = await (0, sharp_1.default)(base)
         .composite([{ input: foreground, blend: 'over' }])
-        .png(PNG_OPTIONS)
+        .png()
+        .toBuffer();
+    return (0, sharp_1.default)(composed)
+        .extract({
+        left: cropInset,
+        top: cropInset,
+        width: cropPx,
+        height: cropPx,
+    })
+        .png()
         .toBuffer();
-    if (!round) {
-        return flat;
-    }
-    return _applyRoundMask(flat, size);
+}
+async function _legacyPng(sourceAbs, size, round) {
+    const content = await (0, sharp_1.default)(sourceAbs).ensureAlpha().png().toBuffer();
+    return _legacyStudioPng(content, size, round);
+}
+async function _legacyCompositePng(foregroundAbs, size, round, background) {
+    const layerPx = Math.round((size * ADAPTIVE_LAYER_DP) / LEGACY_CANVAS_DP);
+    const viewport = await _adaptiveLayerComposite(foregroundAbs, layerPx, background);
+    return _legacyStudioPng(viewport, size, round);
 }
 async function _resizePng(sourceAbs, size) {
     return (0, sharp_1.default)(sourceAbs)
@@ -452,6 +604,48 @@ async function writeAssets(plan, opts) {
     }
     return written;
 }
+function _iosFilenamesForContentsJob(job) {
+    const keep = new Set(['Contents.json']);
+    for (const variant of job.variants) {
+        keep.add(variant === 'light' ? 'AppIcon-1024.png' : `AppIcon-1024-${variant}.png`);
+    }
+    return keep;
+}
+/**
+ * Remove unreferenced files from managed `.appiconset` folders in `plan`.
+ * Returns absolute paths of stale files (removed or that would be removed in check mode).
+ */
+async function pruneStaleIosAppIconSets(iosAssetCatalog, plan, opts) {
+    const staleAbs = [];
+    for (const asset of plan.assets) {
+        if (asset.job.kind !== 'ios-contents') {
+            continue;
+        }
+        const setRel = node_path_1.default.dirname(asset.relativePath);
+        const setDir = node_path_1.default.join(iosAssetCatalog, setRel);
+        const keep = _iosFilenamesForContentsJob(asset.job);
+        let entries;
+        try {
+            entries = await promises_1.default.readdir(setDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const name = entry.name;
+            // Only plain files are ours to remove; leave folders and links alone.
+            if (!entry.isFile() || keep.has(name)) {
+                continue;
+            }
+            const abs = node_path_1.default.join(setDir, name);
+            staleAbs.push(abs);
+            if (!opts.check) {
+                await promises_1.default.unlink(abs);
+            }
+        }
+    }
+    return staleAbs;
+}
 /** Test helper: corner pixel RGB after iOS flatten (alpha removed). */
 async function _readCornerRgb(pngPath) {
     var _a, _b, _c;

package/plugin/build/index.js

@@ -125,6 +125,7 @@ const withIconSwitcher = (config, props) => {
                 iosAssetCatalog,
                 androidResDir: path_1.default.join(projectRoot, '.noop-android'),
             });
+            await (0, assets_1.pruneStaleIosAppIconSets)(iosAssetCatalog, plan, { check: false });
             await _writeTypesIfChanged(projectRoot, resolved);
             return config;
         },

package/plugin/build/sync.js

@@ -36,6 +36,12 @@ async function _applyFileChange(_projectRoot, abs, next, check) {
     if (existing !== null && existing.equals(nextBuf)) {
         return 'unchanged';
     }
+    // Keep a generated image that only differs by resampling rounding (for
+    // example made on another CPU), so --check passes and nothing is rewritten.
+    if (existing !== null &&
+        (await (0, assets_1.pngsMatchWithinTolerance)(existing, nextBuf))) {
+        return 'unchanged';
+    }
     if (check) {
         return 'updated';
     }
@@ -76,6 +82,13 @@ async function _syncAssets(resolved, projectRoot, iosAssetCatalog, androidResDir
                 unchanged += 1;
             }
         }
+        const staleIos = await (0, assets_1.pruneStaleIosAppIconSets)(iosAssetCatalog, plan, {
+            check,
+        });
+        for (const abs of staleIos) {
+            driftedPaths.push(_rel(projectRoot, abs));
+            updated += 1;
+        }
     }
     finally {
         await promises_1.default.rm(tmpRoot, { recursive: true, force: true });