Fix gradient overlay to cover full viewport instead of image bounds (#3017)

## Summary
Fixes gradient overlays on background images appearing more aggressive
on Android compared to the web builder.

## Problem
When a paywall has a background image with a color overlay (gradient),
the overlay was being applied via the `underlay()` modifier which draws
within the image's bounds. Since images are often aspect-fit and smaller
than the viewport, a gradient defined as "66% white from bottom" would
compress into that smaller area, making much more of the screen appear
white.

**Web builder:** Overlay covers 100% of viewport → gradient spread
across full screen
**Android (before):** Overlay only covered image bounds → gradient
compressed into smaller area

## Solution
### `Background.kt`
- Removed `colorOverlay` application from the image background modifier
- Added `alignment = TopCenter` to position the image at the top

### `ViewWithVideoBackground.kt`
- Extended `WithOptionalVideoBackground` to also handle
`BackgroundStyle.Image` with overlays
- Renders overlay as a separate `Box` layer using `.matchParentSize()`
to fill the full container
- Overlay renders between background image and content (correct Z-order)

| Android | Dashboard |
|--------|--------|
| <img width="426" height="808" alt="Screenshot 2026-01-15 at 10 37 51"
src="https://github.com/user-attachments/assets/49c4f4f6-d78f-4953-a95d-f9adeab9dc12"
/> | <img width="369" height="611" alt="Screenshot 2026-01-15 at 10 46
56"
src="https://github.com/user-attachments/assets/605af32d-91bf-49da-bc72-4f7dea9a3c43"
/> |

---------

Co-authored-by: Cesar de la Vega <664544+vegaro@users.noreply.github.com>

Author: facumenzella

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/LoadedPaywallComponents.kt

@@ -80,7 +80,7 @@ internal fun LoadedPaywallComponents(
         sheetState = state.sheet,
         modifier = modifier.background(background),
     ) {
-        WithOptionalVideoBackground(state, background = background) {
+        WithOptionalBackgroundOverlay(state, background = background) {
             Column {
                 ComponentView(
                     style = style,

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/ViewWithVideoBackground.kt

@@ -63,25 +63,3 @@ internal fun ViewWithVideoBackground(
         content()
     }
 }
-
-@Composable
-internal fun WithOptionalVideoBackground(
-    state: PaywallState.Loaded.Components,
-    background: BackgroundStyle?,
-    modifier: Modifier = Modifier,
-    shape: Shape = RectangleShape,
-    content: @Composable () -> Unit,
-) {
-    if (background is BackgroundStyle.Video) {
-        ViewWithVideoBackground(
-            state = state,
-            background = background,
-            shape = shape,
-            modifier = modifier,
-        ) {
-            content()
-        }
-    } else {
-        content()
-    }
-}

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/WithOptionalBackgroundOverlay.kt

@@ -0,0 +1,49 @@
+package com.revenuecat.purchases.ui.revenuecatui.components
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.RectangleShape
+import androidx.compose.ui.graphics.Shape
+import com.revenuecat.purchases.ui.revenuecatui.components.modifier.background
+import com.revenuecat.purchases.ui.revenuecatui.components.properties.BackgroundStyle
+import com.revenuecat.purchases.ui.revenuecatui.data.PaywallState
+
+@Composable
+internal fun WithOptionalBackgroundOverlay(
+    state: PaywallState.Loaded.Components,
+    background: BackgroundStyle?,
+    modifier: Modifier = Modifier,
+    shape: Shape = RectangleShape,
+    content: @Composable () -> Unit,
+) {
+    when {
+        background is BackgroundStyle.Video -> {
+            ViewWithVideoBackground(
+                state = state,
+                background = background,
+                shape = shape,
+                modifier = modifier,
+            ) {
+                content()
+            }
+        }
+        background is BackgroundStyle.Image && background.colorOverlay != null -> {
+            // Image backgrounds with color overlays need the overlay to cover the full container,
+            // not just the image bounds. This matches the web builder behavior where overlays
+            // cover 100% of the viewport.
+            Box(modifier = modifier) {
+                // Render overlay BEHIND content but in front of background image (applied via modifier)
+                Box(
+                    modifier = Modifier
+                        .matchParentSize()
+                        .background(background.colorOverlay, shape),
+                )
+                content()
+            }
+        }
+        else -> {
+            content()
+        }
+    }
+}

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/modifier/Background.kt

@@ -5,14 +5,14 @@ package com.revenuecat.purchases.ui.revenuecatui.components.modifier
 
 import androidx.compose.foundation.background
 import androidx.compose.runtime.Stable
+import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.draw.paint
 import androidx.compose.ui.graphics.RectangleShape
 import androidx.compose.ui.graphics.Shape
 import com.revenuecat.purchases.ui.revenuecatui.components.properties.BackgroundStyle
 import com.revenuecat.purchases.ui.revenuecatui.components.properties.ColorStyle
-import com.revenuecat.purchases.ui.revenuecatui.extensions.applyIfNotNull
 
 @JvmSynthetic
 @Stable
@@ -34,12 +34,15 @@ internal fun Modifier.background(
     when (background) {
         is BackgroundStyle.Color -> this.background(color = background.color, shape = shape)
         is BackgroundStyle.Image ->
+            // The image is applied here via paint(). Color overlays (if present) are rendered
+            // separately in WithOptionalBackgroundOverlay to ensure the overlay covers the full
+            // container, not just the image bounds. This matches the web builder behavior.
             this.clip(shape)
                 .paint(
                     painter = background.painter,
                     contentScale = background.contentScale,
+                    alignment = Alignment.TopCenter,
                 )
-                .applyIfNotNull(background.colorOverlay) { underlay(it, shape) }
         is BackgroundStyle.Video ->
             // Video backgrounds are handled specially - they need to be rendered
             // in a Box behind the content, so we do nothing here

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/stack/StackComponentView.kt

@@ -61,7 +61,7 @@ import com.revenuecat.purchases.paywalls.components.properties.TwoDimensionalAli
 import com.revenuecat.purchases.paywalls.components.properties.VerticalAlignment
 import com.revenuecat.purchases.ui.revenuecatui.components.ComponentView
 import com.revenuecat.purchases.ui.revenuecatui.components.PaywallAction
-import com.revenuecat.purchases.ui.revenuecatui.components.WithOptionalVideoBackground
+import com.revenuecat.purchases.ui.revenuecatui.components.WithOptionalBackgroundOverlay
 import com.revenuecat.purchases.ui.revenuecatui.components.ktx.toAlignment
 import com.revenuecat.purchases.ui.revenuecatui.components.ktx.toHorizontalAlignmentOrNull
 import com.revenuecat.purchases.ui.revenuecatui.components.ktx.toShape
@@ -621,7 +621,7 @@ private fun MainStackComponent(
     if (nestedBadge == null && overlay == null) {
         if (backgroundStyle is BackgroundStyle.Video) {
             // Video backgrounds require a Box wrapper with explicit sizing
-            WithOptionalVideoBackground(
+            WithOptionalBackgroundOverlay(
                 state = state,
                 background = backgroundStyle,
                 shape = composeShape,
@@ -656,7 +656,7 @@ private fun MainStackComponent(
                 .clip(composeShape)
                 .then(borderModifier),
         ) {
-            WithOptionalVideoBackground(state, background = backgroundStyle) {
+            WithOptionalBackgroundOverlay(state, background = backgroundStyle) {
                 stack(Modifier.then(innerShapeModifier))
             }
 
@@ -674,7 +674,7 @@ private fun MainStackComponent(
                 .then(outerShapeModifier)
                 .clip(composeShape),
         ) {
-            WithOptionalVideoBackground(state, background = backgroundStyle) {
+            WithOptionalBackgroundOverlay(state, background = backgroundStyle) {
                 stack(borderModifier.then(innerShapeModifier))
             }
             overlay()

ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/modifier/BackgroundTests.kt

@@ -172,18 +172,30 @@ class BackgroundTests {
             val sizeDp = with(LocalDensity.current) { imageSizePx.toDp() }
 
             // Act
-            Text(
-                text = "Hello",
+            // Image backgrounds with overlays are rendered in two layers:
+            // 1. The image is applied via the background modifier
+            // 2. The overlay is rendered as a separate Box layer (matching WithOptionalBackgroundOverlay)
+            val imageStyle = backgroundStyle as BackgroundStyle.Image
+            Box(
                 modifier = Modifier
                     .requiredSize(sizeDp)
                     .background(backgroundStyle)
-                    .semantics { testTag = "text" },
-                color = textColor,
-            )
+                    .semantics { testTag = "box" }
+            ) {
+                // Overlay layer - rendered behind content but in front of image
+                imageStyle.colorOverlay?.let { overlay ->
+                    Box(modifier = Modifier.matchParentSize().background(color = overlay))
+                }
+                // Content layer
+                Text(
+                    text = "Hello",
+                    color = textColor,
+                )
+            }
         }
 
         // Assert
-        onNodeWithTag("text")
+        onNodeWithTag("box")
             .assertIsDisplayed()
             // The overlay should cover the entire background, as it is fully opaque.
             .assertNoPixelColorEquals(unexpectedColor.color)