catalyst-core 1.0.0 → 1.0.1-canary.1

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/CustomWebview.kt

@@ -66,7 +66,7 @@ class CustomWebView(
     private var lastTargetUrl: String? = null
     private var activeOfflineRouteOrigin: String? = null
     private var visibleOfflineSnapshotUrl: String? = null
-    private var defaultRequestHeaders: Map<String, String> = emptyMap()
+    @Volatile private var defaultRequestHeaders: Map<String, String> = emptyMap()
     var onPageStarted: (() -> Unit)? = null
 
     // Counters for asset loading statistics

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/MainActivity.kt

@@ -9,7 +9,6 @@ import android.view.WindowManager
 import androidx.activity.OnBackPressedCallback
 import androidx.appcompat.app.AppCompatActivity
 import androidx.core.view.ViewCompat
-import androidx.core.view.WindowCompat
 
 import org.json.JSONObject
 import java.util.Properties
@@ -17,6 +16,7 @@ import io.yourname.androidproject.databinding.ActivityMainBinding
 import io.yourname.androidproject.NativeBridge
 import io.yourname.androidproject.plugins.PluginBridge
 import io.yourname.androidproject.utils.BridgeUtils
+import io.yourname.androidproject.utils.EdgeToEdgeUtils
 import io.yourname.androidproject.utils.KeyboardUtil
 import io.yourname.androidproject.utils.NetworkUtils
 import io.yourname.androidproject.utils.NotificationConstants
@@ -31,7 +31,9 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
 
     companion object {
         private const val TAG = "WebViewDebug"
-        private const val PREFS_NAME = "safe_area_prefs"
+        // v2: values are CSS px; the legacy "safe_area_prefs" file held physical px
+        private const val PREFS_NAME = "safe_area_prefs_v2"
+        private const val LEGACY_PREFS_NAME = "safe_area_prefs"
         private const val PREF_SAFE_AREA_TOP = "safe_area_top"
         private const val PREF_SAFE_AREA_RIGHT = "safe_area_right"
         private const val PREF_SAFE_AREA_BOTTOM = "safe_area_bottom"
@@ -75,25 +77,27 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
     }
 
     private fun configureEdgeToEdge() {
-        edgeToEdgeEnabled = properties
-            .getProperty("edgeToEdge.enabled", "false")
-            .equals("true", ignoreCase = true)
+        edgeToEdgeEnabled = EdgeToEdgeUtils.isEnabled(properties)
 
         if (edgeToEdgeEnabled) {
-            WindowCompat.setDecorFitsSystemWindows(window, false)
-        } else {
-            WindowCompat.setDecorFitsSystemWindows(window, true)
+            EdgeToEdgeUtils.apply(this, properties)
+            window.setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE)
         }
     }
 
     private fun setupSafeAreaHandling() {
         val rootView = binding.root
-        val cachedInsets = loadCachedSafeAreaInsets()
+        // Legacy cache held physical px; drop it once (no-op when absent)
+        deleteSharedPreferences(LEGACY_PREFS_NAME)
+
+        // Edge-to-edge disabled: insets are always ZERO, so skip the cache entirely
+        val cachedInsets = if (edgeToEdgeEnabled) loadCachedSafeAreaInsets() else null
 
         if (BuildConfig.DEBUG) {
             Log.d(TAG, "📋 Cache lookup result: $cachedInsets")
         }
 
+        // Synchronous initial read so the first loadUrl already carries safe area headers
         if (cachedInsets != null) {
             latestSafeAreaInsets = cachedInsets
             customWebView.setDefaultRequestHeaders(buildSafeAreaHeaders())
@@ -111,24 +115,34 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
             }
         }
 
-        rootView.post {
-            val postLayoutInsets = SafeAreaUtils.getSafeAreaInsets(window, rootView, edgeToEdgeEnabled)
+        // Track inset changes (first layout, rotation, cutout, bar visibility); insets stay unconsumed
+        var lastCachedInsets = cachedInsets
+        ViewCompat.setOnApplyWindowInsetsListener(rootView) { view, insets ->
+            val updatedInsets = SafeAreaUtils.fromWindowInsets(
+                insets,
+                edgeToEdgeEnabled,
+                view.resources.displayMetrics.density
+            )
 
-            if (postLayoutInsets != latestSafeAreaInsets) {
-                latestSafeAreaInsets = postLayoutInsets
+            if (updatedInsets != latestSafeAreaInsets) {
+                latestSafeAreaInsets = updatedInsets
                 customWebView.setDefaultRequestHeaders(buildSafeAreaHeaders())
-                notifySafeAreaUpdate(postLayoutInsets)
+                notifySafeAreaUpdate(updatedInsets)
 
                 if (BuildConfig.DEBUG) {
-                    Log.d(TAG, "🔄 Updated safe area insets: $postLayoutInsets")
+                    Log.d(TAG, "🔄 Updated safe area insets: $updatedInsets")
                 }
             }
 
             // Save to cache if not already cached or if values changed
-            if (cachedInsets == null || cachedInsets != postLayoutInsets) {
-                saveSafeAreaInsetsToCache(postLayoutInsets)
+            if (edgeToEdgeEnabled && updatedInsets != lastCachedInsets) {
+                saveSafeAreaInsetsToCache(updatedInsets)
+                lastCachedInsets = updatedInsets
             }
+
+            insets
         }
+        ViewCompat.requestApplyInsets(rootView)
     }
 
     private fun buildSafeAreaHeaders(): Map<String, String> = mapOf(
@@ -222,29 +236,25 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
             return
         }
 
-        val saved = getSharedPreferences(PREFS_NAME, android.content.Context.MODE_PRIVATE).edit().apply {
+        val prefs = getSharedPreferences(PREFS_NAME, android.content.Context.MODE_PRIVATE)
+        prefs.edit().apply {
             putInt(PREF_SAFE_AREA_TOP, insets.top)
             putInt(PREF_SAFE_AREA_RIGHT, insets.right)
             putInt(PREF_SAFE_AREA_BOTTOM, insets.bottom)
             putInt(PREF_SAFE_AREA_LEFT, insets.left)
             putBoolean(PREF_SAFE_AREA_CACHED, true)
-        }.commit()  // Use commit() instead of apply() to ensure immediate persistence
+        }.apply()  // Async disk write; the in-memory map is updated immediately
 
         if (BuildConfig.DEBUG) {
-            if (saved) {
-                // Verify by reading back immediately
-                val prefs = getSharedPreferences(PREFS_NAME, android.content.Context.MODE_PRIVATE)
-                val verified = SafeAreaInsets(
-                    top = prefs.getInt(PREF_SAFE_AREA_TOP, -1),
-                    right = prefs.getInt(PREF_SAFE_AREA_RIGHT, -1),
-                    bottom = prefs.getInt(PREF_SAFE_AREA_BOTTOM, -1),
-                    left = prefs.getInt(PREF_SAFE_AREA_LEFT, -1)
-                )
-                Log.d(TAG, "💾 Cached safe area insets: $insets")
-                Log.d(TAG, "✓ Verified cached values: $verified")
-            } else {
-                Log.e(TAG, "❌ Failed to cache safe area insets: $insets")
-            }
+            // Read back from the in-memory map (disk write may still be pending)
+            val verified = SafeAreaInsets(
+                top = prefs.getInt(PREF_SAFE_AREA_TOP, -1),
+                right = prefs.getInt(PREF_SAFE_AREA_RIGHT, -1),
+                bottom = prefs.getInt(PREF_SAFE_AREA_BOTTOM, -1),
+                left = prefs.getInt(PREF_SAFE_AREA_LEFT, -1)
+            )
+            Log.d(TAG, "💾 Cached safe area insets: $insets")
+            Log.d(TAG, "✓ Verified cached values: $verified")
         }
     }
 
@@ -311,7 +321,7 @@ class MainActivity : AppCompatActivity(), CoroutineScope by MainScope() {
         setContentView(binding.root)
         
         // Initialize keyboard utility (pass webView so keyboard events reach WebPerfCollector)
-        keyboardUtil = KeyboardUtil(this, binding.webviewContainer, binding.webview)
+        keyboardUtil = KeyboardUtil(this, binding.webviewContainer, binding.webview, edgeToEdgeEnabled)
         keyboardUtil.initialize()
         
         // Enable hardware acceleration for the window

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/SplashActivity.kt

@@ -13,6 +13,7 @@ import androidx.core.content.ContextCompat
 import androidx.core.graphics.drawable.RoundedBitmapDrawableFactory
 import androidx.core.graphics.drawable.toBitmap
 import io.yourname.androidproject.databinding.ActivitySplashBinding
+import io.yourname.androidproject.utils.EdgeToEdgeUtils
 import java.util.Properties
 
 class SplashActivity : AppCompatActivity() {
@@ -37,6 +38,10 @@ class SplashActivity : AppCompatActivity() {
             return
         }
 
+        if (EdgeToEdgeUtils.isEnabled(properties)) {
+            EdgeToEdgeUtils.apply(this, properties)
+        }
+
         binding = ActivitySplashBinding.inflate(layoutInflater)
         setContentView(binding.root)
         

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/EdgeToEdgeUtils.kt

@@ -0,0 +1,53 @@
+package io.yourname.androidproject.utils
+
+import android.graphics.Color
+import android.util.Log
+import androidx.activity.ComponentActivity
+import androidx.activity.SystemBarStyle
+import androidx.activity.enableEdgeToEdge
+import io.yourname.androidproject.BuildConfig
+import java.util.Properties
+
+/**
+ * Edge-to-edge window setup shared by SplashActivity and MainActivity.
+ *
+ * Reads `edgeToEdge.statusBarStyle` from webview_config.properties:
+ * - "auto" (default): androidx defaults, icons follow the system theme
+ * - "dark-content": dark icons, for light page backgrounds
+ * - "light-content": light icons, for dark page backgrounds
+ */
+object EdgeToEdgeUtils {
+
+    private const val TAG = "EdgeToEdgeUtils"
+
+    // Copies of androidx.activity's internal DefaultLightScrim / DefaultDarkScrim (activity 1.8.0)
+    private val DEFAULT_LIGHT_SCRIM = Color.argb(0xe6, 0xFF, 0xFF, 0xFF)
+    private val DEFAULT_DARK_SCRIM = Color.argb(0x80, 0x1b, 0x1b, 0x1b)
+
+    fun isEnabled(properties: Properties): Boolean =
+        properties.getProperty("edgeToEdge.enabled", "false").equals("true", ignoreCase = true)
+
+    /**
+     * Draws the activity behind the system bars and applies the configured bar style.
+     * Must be called before setContentView.
+     */
+    fun apply(activity: ComponentActivity, properties: Properties) {
+        when (val style = properties.getProperty("edgeToEdge.statusBarStyle", "auto")) {
+            "auto" -> activity.enableEdgeToEdge()
+            "dark-content" -> activity.enableEdgeToEdge(
+                statusBarStyle = SystemBarStyle.light(Color.TRANSPARENT, Color.TRANSPARENT),
+                navigationBarStyle = SystemBarStyle.light(DEFAULT_LIGHT_SCRIM, DEFAULT_DARK_SCRIM)
+            )
+            "light-content" -> activity.enableEdgeToEdge(
+                statusBarStyle = SystemBarStyle.dark(Color.TRANSPARENT),
+                navigationBarStyle = SystemBarStyle.dark(Color.TRANSPARENT)
+            )
+            else -> {
+                if (BuildConfig.DEBUG) {
+                    Log.d(TAG, "⚠️ Unknown edgeToEdge.statusBarStyle '$style', falling back to auto")
+                }
+                activity.enableEdgeToEdge()
+            }
+        }
+    }
+}

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/KeyboardUtil.kt

@@ -9,12 +9,16 @@ import android.view.ViewGroup
 import android.view.ViewTreeObserver
 import android.webkit.WebView
 import androidx.constraintlayout.widget.ConstraintLayout
+import androidx.core.graphics.Insets
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowInsetsCompat
 import org.json.JSONObject
 
 class KeyboardUtil(
     private val activity: Activity,
     private val webViewContainer: View,
     private val webView: WebView? = null,
+    private val edgeToEdgeEnabled: Boolean = false,
 ) {
     private var originalHeight: Int = 0
     private var listener: ViewTreeObserver.OnGlobalLayoutListener? = null
@@ -51,6 +55,22 @@ class KeyboardUtil(
     fun initialize() {
         val rootView = activity.findViewById<ViewGroup>(android.R.id.content)
 
+        if (edgeToEdgeEnabled) {
+            // Root stays full-screen in edge-to-edge, so pin the resized container to the top instead of centering it
+            (webViewContainer.layoutParams as ConstraintLayout.LayoutParams).verticalBias = 0f
+
+            // Strip IME insets from the WebView: we already shrink the container, and the WebView
+            // would otherwise subtract the keyboard a second time from its visual viewport
+            webView?.let { wv ->
+                ViewCompat.setOnApplyWindowInsetsListener(wv) { v, insets ->
+                    val withoutIme = WindowInsetsCompat.Builder(insets)
+                        .setInsets(WindowInsetsCompat.Type.ime(), Insets.NONE)
+                        .build()
+                    ViewCompat.onApplyWindowInsets(v, withoutIme)
+                }
+            }
+        }
+
         webViewContainer.post {
             originalHeight = webViewContainer.height
         }
@@ -58,8 +78,16 @@ class KeyboardUtil(
             val rect = Rect()
             rootView.getWindowVisibleDisplayFrame(rect)
             val screenHeight = activity.resources.displayMetrics.heightPixels
-            val visibleHeight = rect.height()
-            val keyboardHeight = screenHeight - visibleHeight
+            val keyboardHeight = if (edgeToEdgeEnabled) {
+                // Edge-to-edge: rootView spans behind the system bars, so measure how far the
+                // visible frame's bottom sits above rootView's bottom (screen coords; works in split-screen)
+                val location = IntArray(2)
+                rootView.getLocationOnScreen(location)
+                maxOf(0, (location[1] + rootView.height) - rect.bottom)
+            } else {
+                val visibleHeight = rect.height()
+                screenHeight - visibleHeight
+            }
 
             // Use density-independent threshold and consider screen size
             // Also add a minimum percentage of screen height as additional validation

package/dist/native/androidProject/app/src/main/java/io/yourname/androidproject/utils/SafeAreaUtils.kt

@@ -4,6 +4,7 @@ import android.view.View
 import android.view.Window
 import androidx.core.view.ViewCompat
 import androidx.core.view.WindowInsetsCompat
+import kotlin.math.ceil
 import kotlin.math.max
 
 data class SafeAreaInsets(
@@ -26,37 +27,31 @@ data class SafeAreaInsets(
 
 object SafeAreaUtils {
     /**
-     * Computes safe area insets from window insets.
-     * - Edge-to-edge disabled: Returns system bars only
-     * - Edge-to-edge enabled: Returns max(system bars, cutout) per edge
+     * Computes safe area insets from window insets, in CSS px.
+     * CSS px equal dp here: the WebView has no wide-viewport scaling, so
+     * devicePixelRatio == density and px / density gives CSS px.
+     * - Edge-to-edge disabled: Returns ZERO (the system already insets the WebView, iOS parity)
+     * - Edge-to-edge enabled: Returns ceil(max(system bars, cutout) / density) per edge
      */
-    fun fromWindowInsets(insets: WindowInsetsCompat?, edgeToEdgeEnabled: Boolean): SafeAreaInsets {
-        if (insets == null) return SafeAreaInsets.ZERO
+    fun fromWindowInsets(insets: WindowInsetsCompat?, edgeToEdgeEnabled: Boolean, density: Float): SafeAreaInsets {
+        if (insets == null || !edgeToEdgeEnabled) return SafeAreaInsets.ZERO
 
         val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
-
-        if (!edgeToEdgeEnabled) {
-            return SafeAreaInsets(
-                top = max(0, systemBars.top),
-                right = max(0, systemBars.right),
-                bottom = max(0, systemBars.bottom),
-                left = max(0, systemBars.left)
-            )
-        }
-
         val cutoutInsets = insets.getInsets(WindowInsetsCompat.Type.displayCutout())
 
         return SafeAreaInsets(
-            top = max(0, max(systemBars.top, cutoutInsets.top)),
-            right = max(0, max(systemBars.right, cutoutInsets.right)),
-            bottom = max(0, max(systemBars.bottom, cutoutInsets.bottom)),
-            left = max(0, max(systemBars.left, cutoutInsets.left))
+            top = toCssPx(max(systemBars.top, cutoutInsets.top), density),
+            right = toCssPx(max(systemBars.right, cutoutInsets.right), density),
+            bottom = toCssPx(max(systemBars.bottom, cutoutInsets.bottom), density),
+            left = toCssPx(max(systemBars.left, cutoutInsets.left), density)
         )
     }
 
     fun getSafeAreaInsets(window: Window, rootView: View, edgeToEdgeEnabled: Boolean): SafeAreaInsets {
         val windowInsets =
             ViewCompat.getRootWindowInsets(window.decorView) ?: ViewCompat.getRootWindowInsets(rootView)
-        return fromWindowInsets(windowInsets, edgeToEdgeEnabled)
+        return fromWindowInsets(windowInsets, edgeToEdgeEnabled, rootView.resources.displayMetrics.density)
     }
+
+    private fun toCssPx(px: Int, density: Float): Int = max(0, ceil(px / density).toInt())
 }

package/dist/native/androidProject/app/src/test/java/io/yourname/androidproject/WebCacheManagerTest.kt

@@ -209,4 +209,30 @@ class WebCacheManagerTest {
         val manager = WebCacheManager(context)
         manager.cleanup()
     }
+
+    /**
+     * cleanup() wraps its work in withContext(Dispatchers.IO). When the caller is
+     * already on Dispatchers.IO the call completes inline without suspending, which
+     * is a distinct code path (the final `return Unit`). The tests above call from a
+     * test dispatcher, which always suspends, so that path only ran in CI when some
+     * other test happened to call from an IO thread, moving the coverage number by
+     * one line between runs. Calling from IO explicitly makes it deterministic.
+     */
+    @Test
+    fun `cleanup called from an IO dispatcher completes without suspending`() = kotlinx.coroutines.runBlocking {
+        val manager = WebCacheManager(context)
+        val webviewCacheDir = File(cacheDir, "webview_cache")
+        val freshFile = File(webviewCacheDir, "fresh-entry")
+        freshFile.writeText("fresh")
+        val expiredFile = File(webviewCacheDir, "expired-entry")
+        expiredFile.writeText("expired")
+        expiredFile.setLastModified(System.currentTimeMillis() - java.util.concurrent.TimeUnit.HOURS.toMillis(26))
+
+        kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.IO) {
+            manager.cleanup()
+        }
+
+        assertTrue("Fresh file should survive cleanup", freshFile.exists())
+        assertFalse("Expired file should be deleted by cleanup", expiredFile.exists())
+    }
 }

package/dist/native/androidProject/app/src/test/java/io/yourname/androidproject/utils/EdgeToEdgeUtilsTest.kt

@@ -0,0 +1,87 @@
+package io.yourname.androidproject.utils
+
+import android.content.res.Configuration
+import android.content.res.Resources
+import android.view.View
+import android.view.Window
+import androidx.activity.ComponentActivity
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.mockito.kotlin.atLeastOnce
+import org.mockito.kotlin.doReturn
+import org.mockito.kotlin.mock
+import org.mockito.kotlin.verify
+import java.util.Properties
+
+/**
+ * Unit tests for EdgeToEdgeUtils, the edge-to-edge window setup shared by
+ * SplashActivity and MainActivity (previously 0/15 lines covered).
+ *
+ * `apply` hands off to androidx.activity's `enableEdgeToEdge`, which reads
+ * the window's decor view and its resources to decide the icon colors, so
+ * the activity mock is wired with just that chain. Under the mockable
+ * android.jar (isReturnDefaultValues = true) Build.VERSION.SDK_INT is 0, so
+ * androidx takes its base (no-op) implementation: these tests assert that
+ * every `edgeToEdge.statusBarStyle` value, including an unknown one, reaches
+ * the window without throwing.
+ */
+class EdgeToEdgeUtilsTest {
+
+    private fun properties(vararg pairs: Pair<String, String>) = Properties().apply {
+        pairs.forEach { (k, v) -> setProperty(k, v) }
+    }
+
+    private fun mockActivity(): ComponentActivity {
+        val configuration = Configuration()
+        val resources = mock<Resources> { on { getConfiguration() } doReturn configuration }
+        val decorView = mock<View> { on { getResources() } doReturn resources }
+        val window = mock<Window> { on { getDecorView() } doReturn decorView }
+        return mock { on { getWindow() } doReturn window }
+    }
+
+    @Test
+    fun isEnabled_defaultsToFalseWhenKeyMissing() {
+        assertFalse(EdgeToEdgeUtils.isEnabled(Properties()))
+    }
+
+    @Test
+    fun isEnabled_trueIsCaseInsensitive() {
+        assertTrue(EdgeToEdgeUtils.isEnabled(properties("edgeToEdge.enabled" to "true")))
+        assertTrue(EdgeToEdgeUtils.isEnabled(properties("edgeToEdge.enabled" to "TRUE")))
+    }
+
+    @Test
+    fun isEnabled_anyOtherValueIsFalse() {
+        assertFalse(EdgeToEdgeUtils.isEnabled(properties("edgeToEdge.enabled" to "false")))
+        assertFalse(EdgeToEdgeUtils.isEnabled(properties("edgeToEdge.enabled" to "yes")))
+    }
+
+    @Test
+    fun apply_autoIsTheDefaultStyle() {
+        val activity = mockActivity()
+        EdgeToEdgeUtils.apply(activity, Properties())
+        verify(activity, atLeastOnce()).window
+    }
+
+    @Test
+    fun apply_darkContentStyle() {
+        val activity = mockActivity()
+        EdgeToEdgeUtils.apply(activity, properties("edgeToEdge.statusBarStyle" to "dark-content"))
+        verify(activity, atLeastOnce()).window
+    }
+
+    @Test
+    fun apply_lightContentStyle() {
+        val activity = mockActivity()
+        EdgeToEdgeUtils.apply(activity, properties("edgeToEdge.statusBarStyle" to "light-content"))
+        verify(activity, atLeastOnce()).window
+    }
+
+    @Test
+    fun apply_unknownStyleFallsBackToAuto() {
+        val activity = mockActivity()
+        EdgeToEdgeUtils.apply(activity, properties("edgeToEdge.statusBarStyle" to "sparkly"))
+        verify(activity, atLeastOnce()).window
+    }
+}

package/dist/native/androidProject/app/src/test/java/io/yourname/androidproject/utils/SafeAreaUtilsTest.kt

@@ -1,5 +1,9 @@
 package io.yourname.androidproject.utils
 
+import android.content.res.Resources
+import android.util.DisplayMetrics
+import android.view.View
+import android.view.Window
 import androidx.core.graphics.Insets
 import androidx.core.view.WindowInsetsCompat
 import org.junit.Assert.assertEquals
@@ -41,22 +45,40 @@ class SafeAreaUtilsTest {
 
     @Test
     fun `fromWindowInsets returns ZERO when insets is null`() {
-        val result = SafeAreaUtils.fromWindowInsets(null, edgeToEdgeEnabled = true)
+        val result = SafeAreaUtils.fromWindowInsets(null, edgeToEdgeEnabled = true, density = 1f)
         assertEquals(SafeAreaInsets.ZERO, result)
     }
 
     // ============================================================
-    // edge-to-edge disabled -- system bars only
+    // getSafeAreaInsets passthrough
     // ============================================================
 
     @Test
-    fun `fromWindowInsets with edge-to-edge disabled returns system bar insets directly`() {
+    fun `getSafeAreaInsets returns ZERO when the window has no root insets yet`() {
+        // Under the mockable android.jar Build.VERSION.SDK_INT is 0, so
+        // ViewCompat.getRootWindowInsets returns null for both views (no
+        // static mocking needed) and the passthrough delegates a null.
+        val resources = mock<Resources> { on { getDisplayMetrics() } doReturn DisplayMetrics() }
+        val rootView = mock<View> { on { getResources() } doReturn resources }
+        val window = mock<Window> { on { getDecorView() } doReturn mock<View>() }
+
+        val result = SafeAreaUtils.getSafeAreaInsets(window, rootView, edgeToEdgeEnabled = true)
+
+        assertEquals(SafeAreaInsets.ZERO, result)
+    }
+
+    // ============================================================
+    // edge-to-edge disabled -- always ZERO (system already insets the WebView)
+    // ============================================================
+
+    @Test
+    fun `fromWindowInsets with edge-to-edge disabled returns ZERO`() {
         val systemBars = Insets.of(10, 20, 30, 40)
         val windowInsets = windowInsetsCompatWith(systemBars)
 
-        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = false)
+        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = false, density = 1f)
 
-        assertEquals(SafeAreaInsets(top = 20, right = 30, bottom = 40, left = 10), result)
+        assertEquals(SafeAreaInsets.ZERO, result)
     }
 
     @Test
@@ -65,9 +87,9 @@ class SafeAreaUtilsTest {
         val cutout = Insets.of(100, 100, 100, 100)
         val windowInsets = windowInsetsCompatWith(systemBars, cutout)
 
-        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = false)
+        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = false, density = 1f)
 
-        assertEquals(SafeAreaInsets(top = 20, right = 30, bottom = 40, left = 10), result)
+        assertEquals(SafeAreaInsets.ZERO, result)
     }
 
     // ============================================================
@@ -80,7 +102,7 @@ class SafeAreaUtilsTest {
         val cutout = Insets.of(0, 20, 60, 15)
         val windowInsets = windowInsetsCompatWith(systemBars, cutout)
 
-        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = true)
+        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = true, density = 1f)
 
         // left: max(10, 0)=10, top: max(50, 20)=50, right: max(30, 60)=60, bottom: max(5, 15)=15
         assertEquals(SafeAreaInsets(top = 50, right = 60, bottom = 15, left = 10), result)
@@ -91,11 +113,21 @@ class SafeAreaUtilsTest {
         val systemBars = Insets.of(10, 20, 30, 40)
         val windowInsets = windowInsetsCompatWith(systemBars, Insets.NONE)
 
-        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = true)
+        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = true, density = 1f)
 
         assertEquals(SafeAreaInsets(top = 20, right = 30, bottom = 40, left = 10), result)
     }
 
+    @Test
+    fun `fromWindowInsets with edge-to-edge enabled converts physical px to CSS px by density`() {
+        val systemBars = Insets.of(0, 66, 0, 0)
+        val windowInsets = windowInsetsCompatWith(systemBars)
+
+        val result = SafeAreaUtils.fromWindowInsets(windowInsets, edgeToEdgeEnabled = true, density = 2.75f)
+
+        assertEquals(SafeAreaInsets(top = 24, right = 0, bottom = 0, left = 0), result)
+    }
+
     // ============================================================
     // SafeAreaInsets.toMap()
     // ============================================================

package/dist/native/bridge/hooks/aiProviders.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveMode(provider: string | undefined): "local" | "native" | "cloud";
+/** Engine to pin for the native provider: an explicit option wins, then the provider alias, then config. */
+export declare function resolveNativeEngine(provider: string | undefined, explicitEngine: string | undefined, config: {
+    engine?: string;
+} | null | undefined): string | undefined;

package/dist/native/bridge/hooks/aiProviders.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveMode = resolveMode;
+exports.resolveNativeEngine = resolveNativeEngine;
+// On-device providers. "native" lets the platform pick (iOS: LiteRT-LM if its model is downloaded, else
+// Apple Foundation Models, else LiteRT-LM); "litert" and "foundation-models" pin an engine. They can be set
+// per call (useAI({ provider })) or app-wide in AI_CONFIG.browser.provider, optionally with
+// AI_CONFIG.browser.engine instead of an alias.
+const NATIVE_ENGINE_BY_PROVIDER = {
+  native: undefined,
+  litert: "litert",
+  "foundation-models": "foundation-models"
+};
+function resolveMode(provider) {
+  if (provider === "transformers") return "local";
+  if (provider !== undefined && Object.prototype.hasOwnProperty.call(NATIVE_ENGINE_BY_PROVIDER, provider)) return "native";
+  return "cloud";
+}
+
+/** Engine to pin for the native provider: an explicit option wins, then the provider alias, then config. */
+function resolveNativeEngine(provider, explicitEngine, config) {
+  const aliasEngine = provider !== undefined && Object.prototype.hasOwnProperty.call(NATIVE_ENGINE_BY_PROVIDER, provider) ? NATIVE_ENGINE_BY_PROVIDER[provider] : undefined;
+  return explicitEngine ?? aliasEngine ?? config?.engine;
+}

package/dist/native/bridge/hooks/useAI.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useAI = useAI;
+var _aiProviders = require("./aiProviders.js");
 /* global __CATALYST_PACKAGES__ */
 
 function getBrowserConfig() {
@@ -16,12 +17,10 @@ function getBrowserConfig() {
     return null;
   }
 }
-function resolveMode(provider) {
-  if (provider === "transformers") return "local";
-  if (provider === "native") return "native";
-  return "cloud";
-}
 function isNativeAIAvailable() {
+  // catalyst-ai knows both platforms (Android's NativeBridge, iOS's injected plugin manifest).
+  // Older catalyst-ai versions don't export it, so fall back to the Android-only check.
+  if (_pkg && typeof _pkg.isNativeAIAvailable === "function") return _pkg.isNativeAIAvailable();
   const nb = typeof window !== "undefined" && window.NativeBridge;
   return nb && typeof nb.isAIAvailable === "function" && nb.isAIAvailable();
 }
@@ -43,7 +42,8 @@ const _pkg = typeof window !== "undefined" && (typeof __CATALYST_PACKAGES__ ===
 })() : null;
 
 // provider: "transformers" → useWebAI   (catalyst-ai)
-//           "native"       → useNativeAI (catalyst-ai, falls back to useCloudAI if bridge unavailable)
+//           "native" | "litert" | "foundation-models"
+//                          → useNativeAI (catalyst-ai, falls back to useCloudAI if bridge unavailable)
 //           anything else  → useCloudAI  (catalyst-ai, default)
 // The shape of this hook is owned by the catalyst-ai package and sits outside
 // the native hook contract entirely, so its options and result stay loose here.
@@ -53,12 +53,13 @@ function useAI(options = {}) {
   } = options;
   const config = getBrowserConfig();
   const resolvedProvider = provider || config?.provider;
-  const mode = resolveMode(resolvedProvider);
+  const mode = (0, _aiProviders.resolveMode)(resolvedProvider);
   const cloudResult = _pkg ? _pkg.useCloudAI(options) : emptyHook();
   const webResult = _pkg ? _pkg.useWebAI(options) : emptyHook();
   const nativeResult = _pkg ? _pkg.useNativeAI({
     ...options,
-    enabled: mode === "native"
+    enabled: mode === "native",
+    engine: (0, _aiProviders.resolveNativeEngine)(resolvedProvider, options.engine, config)
   }) : emptyHook();
   if (typeof window === "undefined") return emptyHook();
   if (!_pkg) {