@revenuecat/purchases-ui-js 4.3.0 → 4.5.0

package/dist/components/input-text/InputText.svelte

@@ -41,6 +41,7 @@
     keyboard_type,
     capitalize,
     field_id,
+    reserved_attribute,
     required,
     size,
     padding,
@@ -74,7 +75,15 @@
     }
 
     const value = input.value.trim();
-    onInputChanged?.(field_id, value);
+    if (reserved_attribute) {
+      if (!onReservedAttributeChanged) {
+        console.error("onReservedAttributeChanged is not set");
+      } else {
+        onReservedAttributeChanged(reserved_attribute, value);
+      }
+    } else {
+      onInputChanged?.(field_id, value);
+    }
   }
 
   const oninput: FormEventHandler<HTMLInputElement> = (event) => {
@@ -90,7 +99,12 @@
 
   const getColorMode = getColorModeContext();
   const colorMode = $derived(getColorMode());
-  const { uiConfig, onInputChanged, selectedPackageId } = getPaywallContext();
+  const {
+    uiConfig,
+    onInputChanged,
+    onReservedAttributeChanged,
+    selectedPackageId,
+  } = getPaywallContext();
   const packageInfo = getOptionalPackageInfoContext();
 
   const wrapperStyle = $derived(

package/dist/components/paywall/Paywall.svelte

@@ -15,6 +15,7 @@
     type VariablesStore,
   } from "../../stores/variables";
   import type { ColorMode } from "../../types";
+  import type { ColorScheme } from "../../types/colors";
   import type {
     Action,
     CompleteWorkflowNavigateArgs,
@@ -48,6 +49,7 @@
     setPackageInfoContext,
   } from "../../stores/packageInfo";
   import type { WalletButtonRender } from "../../types/wallet";
+  import type { ReservedAttribute } from "../../types/components/input-text";
 
   /**
    * Props are captured once at mount and are not reactive to subsequent changes.
@@ -89,6 +91,10 @@
       value: string,
       actionId?: string,
     ) => void;
+    onReservedAttributeChanged?: (
+      reservedAttribute: ReservedAttribute,
+      value: string,
+    ) => void;
     maxContentWidth?: string;
     initialInputSelections?: InitialInputSelections;
     /**
@@ -105,6 +111,12 @@
      * ```
      */
     customVariables?: CustomVariables;
+    /**
+     * Optional baseline safe-area colour applied when the paywall background
+     * can't derive one and `background.safe_area_fallback_color` is unset.
+     * Hosts (e.g. workflow runtimes) pass their workflow-level fallback here.
+     */
+    safeAreaFallbackColor?: ColorScheme | null;
   }
 
   const {
@@ -126,10 +138,12 @@
     uiConfig,
     walletButtonRender,
     onInputChanged,
+    onReservedAttributeChanged,
     hideBackButtons = false,
     maxContentWidth,
     initialInputSelections = {},
     customVariables = {},
+    safeAreaFallbackColor,
   }: Props = $props();
 
   const getColorMode = setColorModeContext(() => preferredColorMode);
@@ -140,7 +154,11 @@
 
   const instanceId: symbol = Symbol();
   $effect(() =>
-    applyDocumentBackground(instanceId, viewportBackdropModel, paywallData),
+    applyDocumentBackground(instanceId, viewportBackdropModel, {
+      paywallData,
+      colorMode: getColorMode(),
+      hostFallbackColor: safeAreaFallbackColor,
+    }),
   );
 
   const { default_locale, components_config, components_localizations } =
@@ -285,6 +303,7 @@
     onNavigateToUrl: onNavigateToUrlClicked,
     onButtonAction,
     onInputChanged,
+    onReservedAttributeChanged,
     walletButtonRender,
     uiConfig,
     hideBackButtons,

package/dist/components/paywall/Paywall.svelte.d.ts

@@ -1,11 +1,13 @@
 import { type InitialInputSelections } from "../../stores/inputValidation";
 import type { ColorMode } from "../../types";
+import type { ColorScheme } from "../../types/colors";
 import type { CompleteWorkflowNavigateArgs } from "../../types/components/button";
 import type { OnComponentInteraction } from "../../types/paywall-component-interaction";
 import type { PaywallData } from "../../types/paywall";
 import type { UIConfig } from "../../types/ui-config";
 import { type CustomVariables, type PackageInfo, type VariableDictionary } from "../../types/variables";
 import type { WalletButtonRender } from "../../types/wallet";
+import type { ReservedAttribute } from "../../types/components/input-text";
 /**
  * Props are captured once at mount and are not reactive to subsequent changes.
  * The paywall should be remounted to reflect new prop values.
@@ -40,6 +42,7 @@ interface Props {
     hideBackButtons?: boolean;
     walletButtonRender?: WalletButtonRender;
     onInputChanged?: (fieldId: string, value: string, actionId?: string) => void;
+    onReservedAttributeChanged?: (reservedAttribute: ReservedAttribute, value: string) => void;
     maxContentWidth?: string;
     initialInputSelections?: InitialInputSelections;
     /**
@@ -56,6 +59,12 @@ interface Props {
      * ```
      */
     customVariables?: CustomVariables;
+    /**
+     * Optional baseline safe-area colour applied when the paywall background
+     * can't derive one and `background.safe_area_fallback_color` is unset.
+     * Hosts (e.g. workflow runtimes) pass their workflow-level fallback here.
+     */
+    safeAreaFallbackColor?: ColorScheme | null;
 }
 declare const Paywall: import("svelte").Component<Props, {}, "">;
 type Paywall = ReturnType<typeof Paywall>;

package/dist/components/workflows/Screen.svelte

@@ -1,12 +1,14 @@
 <script lang="ts">
   import Paywall from "../paywall/Paywall.svelte";
   import type { CompleteWorkflowNavigateArgs } from "../../types/components/button";
+  import type { ColorScheme } from "../../types/colors";
   import type { InitialInputSelections } from "../../stores/inputValidation";
   import type { OnComponentInteraction } from "../../types/paywall-component-interaction";
   import type { WorkflowScreen } from "../../types/workflow";
   import type { VariableDictionary } from "../../types/variables";
   import type { WalletButtonRender } from "../../types/wallet";
   import type { UIConfig } from "../../types/ui-config";
+  import type { ReservedAttribute } from "../../types/components/input-text";
   interface Props {
     paywallComponents: WorkflowScreen | null | undefined;
     selectedLocale?: string;
@@ -28,10 +30,15 @@
       value: string,
       actionId?: string,
     ) => void;
+    onReservedAttributeChanged?: (
+      reservedAttribute: ReservedAttribute,
+      value: string,
+    ) => void;
     onCompleteWorkflowNavigate?: (
       args: CompleteWorkflowNavigateArgs,
     ) => void | Promise<void>;
     walletButtonRender?: WalletButtonRender;
+    safeAreaFallbackColor?: ColorScheme | null;
   }
   const {
     paywallComponents,
@@ -47,8 +54,10 @@
     variablesPerPackage,
     initialInputSelections = {},
     onInputChanged,
+    onReservedAttributeChanged,
     onCompleteWorkflowNavigate,
     walletButtonRender,
+    safeAreaFallbackColor,
   }: Props = $props();
 </script>
 
@@ -75,7 +84,9 @@
       {onComponentInteraction}
       {onPurchaseClicked}
       {onInputChanged}
+      {onReservedAttributeChanged}
       {walletButtonRender}
+      {safeAreaFallbackColor}
       onError={(error) => {
         console.error("Paywall error:", error);
       }}

package/dist/components/workflows/Screen.svelte.d.ts

@@ -1,10 +1,12 @@
 import type { CompleteWorkflowNavigateArgs } from "../../types/components/button";
+import type { ColorScheme } from "../../types/colors";
 import type { InitialInputSelections } from "../../stores/inputValidation";
 import type { OnComponentInteraction } from "../../types/paywall-component-interaction";
 import type { WorkflowScreen } from "../../types/workflow";
 import type { VariableDictionary } from "../../types/variables";
 import type { WalletButtonRender } from "../../types/wallet";
 import type { UIConfig } from "../../types/ui-config";
+import type { ReservedAttribute } from "../../types/components/input-text";
 interface Props {
     paywallComponents: WorkflowScreen | null | undefined;
     selectedLocale?: string;
@@ -19,8 +21,10 @@ interface Props {
     variablesPerPackage?: Record<string, VariableDictionary>;
     initialInputSelections?: InitialInputSelections;
     onInputChanged?: (fieldId: string, value: string, actionId?: string) => void;
+    onReservedAttributeChanged?: (reservedAttribute: ReservedAttribute, value: string) => void;
     onCompleteWorkflowNavigate?: (args: CompleteWorkflowNavigateArgs) => void | Promise<void>;
     walletButtonRender?: WalletButtonRender;
+    safeAreaFallbackColor?: ColorScheme | null;
 }
 declare const Screen: import("svelte").Component<Props, {}, "">;
 type Screen = ReturnType<typeof Screen>;

package/dist/stores/paywall.d.ts

@@ -1,4 +1,5 @@
 import type { Action } from "../types/components/button";
+import type { ReservedAttribute } from "../types/components/input-text";
 import type { ComponentInteractionData } from "../types/paywall-component-interaction";
 import type { UIConfig } from "../types/ui-config";
 import type { PackageInfo, VariableDictionary } from "../types/variables";
@@ -21,6 +22,7 @@ type PaywallContext = Readonly<{
     emitComponentInteraction: (data: ComponentInteractionData) => void;
     onNavigateToUrl?: (url: string) => void;
     onInputChanged?: (fieldId: string, value: string, actionId?: string) => void;
+    onReservedAttributeChanged?: (reservedAttribute: ReservedAttribute, value: string) => void;
     walletButtonRender?: WalletButtonRender;
     onWalletButtonReady?: (walletButtonAvailable?: boolean) => void;
     onButtonAction: (action: Action, actionId?: string) => void;

package/dist/types/colors.d.ts

@@ -1,4 +1,4 @@
-type GradientPoint = {
+export type GradientPoint = {
     percent: number;
     color: string;
 };

package/dist/types/components/input-text.d.ts

@@ -4,6 +4,7 @@ import type { ColorGradientScheme } from "../colors";
 import type { Overrides } from "../overrides";
 export type InputTextCapitalizeType = "none" | "sentences" | "words" | "characters";
 export type InputTextKeyboardType = "decimal" | "email" | "numeric" | "tel" | "text" | "url";
+export type ReservedAttribute = "$email" | "$displayName" | "$phoneNumber";
 export interface InputTextProps extends BaseComponent {
     type: "input_text";
     visible?: boolean | null;
@@ -11,6 +12,7 @@ export interface InputTextProps extends BaseComponent {
     keyboard_type: InputTextKeyboardType;
     capitalize: InputTextCapitalizeType;
     field_id: string;
+    reserved_attribute?: ReservedAttribute | null;
     required: boolean;
     size: SizeType;
     padding: Spacing;

package/dist/types/paywall.d.ts

@@ -1,4 +1,5 @@
 import type { Background } from "./background";
+import type { ColorScheme } from "./colors";
 import type { FooterProps } from "./components/footer";
 import type { HeaderProps } from "./components/header";
 import type { StackProps } from "./components/stack";
@@ -8,6 +9,7 @@ export interface RootPaywall {
     stack: StackProps;
     sticky_footer?: FooterProps | null;
     header?: HeaderProps | null;
+    safe_area_fallback_color?: ColorScheme | null;
 }
 export interface ComponentConfig {
     colors?: Record<string, string>;

package/dist/types.d.ts

@@ -120,4 +120,6 @@ export declare enum StackDistribution {
     end = "flex-end"
 }
 export type { WorkflowScreen } from "./types/workflow";
+export type { ColorScheme } from "./types/colors";
 export type { ComponentInteractionData, ComponentInteractionType, OnComponentInteraction, } from "./types/paywall-component-interaction";
+export type { ReservedAttribute } from "./types/components/input-text";

package/dist/utils/document-background.d.ts

@@ -1,3 +1,9 @@
 import type { PaywallData } from "../types/paywall";
 import type { PaywallRootBackgroundModel } from "./background-utils";
-export declare function applyDocumentBackground(instanceId: symbol, model: PaywallRootBackgroundModel, paywallData: PaywallData | null | undefined): () => void;
+import type { ColorMode } from "../types";
+import type { ColorScheme } from "../types/colors";
+export declare function applyDocumentBackground(instanceId: symbol, model: PaywallRootBackgroundModel, options: {
+    paywallData: PaywallData | null | undefined;
+    colorMode: ColorMode;
+    hostFallbackColor?: ColorScheme | null;
+}): () => void;

package/dist/utils/document-background.js

@@ -1,40 +1,14 @@
+import { getBackgroundSafeAreaColors, resolveSafeAreaFallbackCss, SAFE_AREA_FALLBACK_COLOR_CSS_VAR, } from "./safe-area-background";
 // Last writer wins, but cleanup only fires for the last writer — otherwise an
-// unmounting paywall would clear a variable set by another paywall that overlapped
-// it during a transition.
+// unmounting paywall would clear a variable set by another paywall that
+// overlapped it during a transition.
 let lastBgWriter = null;
-// iOS promotes sticky header/footer to its own compositor layer, which breaks
-// safe-area painting for the opposite strip. A vertical gradient's edge stop
-// can stand in as a solid fallback for that strip; any other angle would smear
-// a horizontal colour range across the strip that no single colour represents.
-function gradientSafeAreaFallbackColour(gradient, hasHeader, hasFooter) {
-    if (!hasHeader && !hasFooter)
-        return null;
-    if (hasHeader && hasFooter)
-        return null;
-    const angleMatch = gradient.match(/linear-gradient\((\d+)deg/);
-    if (!angleMatch)
-        return null;
-    if (parseInt(angleMatch[1], 10) % 180 !== 0)
-        return null;
-    const stops = gradient.match(/#[0-9a-fA-F]{6,8}/g);
-    if (!stops || stops.length < 2)
-        return null;
-    const candidate = hasHeader ? stops[stops.length - 1] : stops[0];
-    if (candidate.length === 9 && candidate.slice(-2).toLowerCase() !== "ff") {
-        return null;
-    }
-    return candidate;
-}
-// Published as a CSS variable so consumer surfaces can opt in to safe-area
-// painting (`background: var(--rc-purchases-ui-bg-color, Canvas)` on any
-// element that extends into the safe-area canvas — typically html, body, or
-// a position:fixed root). Writing to documentElement.backgroundColor directly
-// would bleed the paywall colour onto host page chrome that shouldn't take
-// it on, so we expose the value rather than apply it.
-export function applyDocumentBackground(instanceId, model, paywallData) {
+export function applyDocumentBackground(instanceId, model, options) {
     if (typeof document === "undefined")
         return () => { };
+    const { paywallData, colorMode, hostFallbackColor } = options;
     const root = document.documentElement;
+    const base = paywallData?.components_config?.base;
     let value = null;
     if (model.kind === "style" && model.style.background) {
         const bg = model.style.background;
@@ -42,18 +16,26 @@ export function applyDocumentBackground(instanceId, model, paywallData) {
             value = bg;
         }
         else {
-            const base = paywallData?.components_config?.base;
-            value = gradientSafeAreaFallbackColour(bg, !!base?.header, !!base?.sticky_footer);
+            const edges = getBackgroundSafeAreaColors(base?.background, colorMode, { width: window.innerWidth, height: window.innerHeight }, {
+                stickyComponents: {
+                    hasHeader: base?.header != null,
+                    hasFooter: base?.sticky_footer != null,
+                },
+            });
+            value = edges.top ?? edges.bottom;
         }
     }
+    if (value === null) {
+        value = resolveSafeAreaFallbackCss(base?.safe_area_fallback_color, hostFallbackColor, colorMode);
+    }
     if (value !== null) {
         lastBgWriter = instanceId;
-        root.style.setProperty("--rc-purchases-ui-bg-color", value);
+        root.style.setProperty(SAFE_AREA_FALLBACK_COLOR_CSS_VAR, value);
     }
     return () => {
         if (lastBgWriter === instanceId) {
             lastBgWriter = null;
-            root.style.removeProperty("--rc-purchases-ui-bg-color");
+            root.style.removeProperty(SAFE_AREA_FALLBACK_COLOR_CSS_VAR);
         }
     };
 }

package/dist/utils/safe-area-background.d.ts

@@ -0,0 +1,21 @@
+import type { ColorMode } from "../types";
+import type { Background } from "../types/background";
+import type { ColorScheme } from "../types/colors";
+import type { PaywallData } from "../types/paywall";
+type Viewport = {
+    width: number;
+    height: number;
+};
+type SafeAreaEdge = "top" | "bottom";
+export declare const SAFE_AREA_FALLBACK_COLOR_CSS_VAR = "--rc-purchases-ui-bg-color";
+export declare function resolveSafeAreaFallbackCss(paywallOverride: ColorScheme | null | undefined, hostFallback: ColorScheme | null | undefined, colorMode: ColorMode): string | null;
+export declare function getSafeAreaFallbackColorHeadStyles(paywallData: PaywallData | null | undefined, hostFallbackColor?: ColorScheme | null): string;
+export declare function getBackgroundSafeAreaColors(background: Background | null | undefined, colorMode: ColorMode, viewport: Viewport, options?: {
+    stickyComponents?: {
+        hasHeader?: boolean;
+        hasFooter?: boolean;
+    };
+    paywallFallbackColor?: ColorScheme | null;
+    hostFallbackColor?: ColorScheme | null;
+}): Record<SafeAreaEdge, string | null>;
+export {};

package/dist/utils/safe-area-background.js

@@ -0,0 +1,211 @@
+import { mapColorInfo, mapColorMode } from "./base-utils";
+export const SAFE_AREA_FALLBACK_COLOR_CSS_VAR = "--rc-purchases-ui-bg-color";
+// Light-only schemes must not bleed into the dark media query — a dark rule
+// reading from `light` would override the light value.
+function getSafeAreaFallbackColorInfoForMode(paywallOverride, hostFallback, colorMode) {
+    const colorAtMode = (scheme) => colorMode === "dark" ? scheme?.dark : scheme?.light;
+    return colorAtMode(paywallOverride) ?? colorAtMode(hostFallback) ?? null;
+}
+const HEX_COLOR_REGEX = /^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/;
+function isHexColor(value) {
+    return HEX_COLOR_REGEX.test(value);
+}
+function isOpaqueHexColor(value) {
+    const match = HEX_COLOR_REGEX.exec(value);
+    return match != null && (match[1] == null || match[1].toLowerCase() === "ff");
+}
+function normalizeHexColor(color) {
+    return color.length === 7 ? `${color.toLowerCase()}ff` : color.toLowerCase();
+}
+function getCssHexColor(value) {
+    return value?.type === "hex" && isHexColor(value.value) ? value.value : null;
+}
+function isAxisAlignedVerticalGradient(degrees) {
+    return Math.abs(((degrees % 180) + 180) % 180) < 1e-10;
+}
+// Alias-aware counterpart for the SDK runtime; mapColorInfo resolves aliases
+// that the hex-only path can't.
+export function resolveSafeAreaFallbackCss(paywallOverride, hostFallback, colorMode) {
+    const info = getSafeAreaFallbackColorInfoForMode(paywallOverride, hostFallback, colorMode);
+    return info ? mapColorInfo(info) : null;
+}
+// SSR has no real viewport (no off-axis/radial sampling). Hex and alias
+// backgrounds short-circuit immediately; axis-aligned vertical gradients go
+// through the sticky-component disambiguation since edges may differ. Alias
+// values are emitted as var() references — valid CSS that resolves once the
+// SDK stylesheet is present. Invalid hex is skipped rather than emitted.
+function getSsrSafeAreaCssForMode(paywallData, hostFallback, colorMode) {
+    const base = paywallData?.components_config?.base;
+    const background = base?.background;
+    if (background?.type === "color") {
+        const color = mapColorMode(colorMode, background.value);
+        if (color.type === "hex") {
+            const hex = getCssHexColor(color);
+            if (hex)
+                return hex;
+        }
+        else if (color.type === "alias") {
+            return mapColorInfo(color);
+        }
+        else if (color.type === "linear" &&
+            isAxisAlignedVerticalGradient(color.degrees)) {
+            const edges = getBackgroundSafeAreaColors(background, colorMode, { width: 1, height: 1 }, {
+                stickyComponents: {
+                    hasHeader: base?.header != null,
+                    hasFooter: base?.sticky_footer != null,
+                },
+            });
+            const sampled = edges.top ?? edges.bottom;
+            if (sampled && isHexColor(sampled))
+                return sampled;
+        }
+    }
+    const fallbackInfo = getSafeAreaFallbackColorInfoForMode(base?.safe_area_fallback_color, hostFallback, colorMode);
+    if (fallbackInfo == null)
+        return null;
+    return fallbackInfo.type === "alias"
+        ? mapColorInfo(fallbackInfo)
+        : getCssHexColor(fallbackInfo);
+}
+export function getSafeAreaFallbackColorHeadStyles(paywallData, hostFallbackColor) {
+    return ["light", "dark"]
+        .map((mode) => {
+        const value = getSsrSafeAreaCssForMode(paywallData, hostFallbackColor, mode);
+        return value
+            ? `@media (prefers-color-scheme: ${mode}) { html, body { ${SAFE_AREA_FALLBACK_COLOR_CSS_VAR}: ${value}; } }`
+            : null;
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function colorAtPercent(sortedPoints, percent) {
+    const firstPoint = sortedPoints[0];
+    const lastPoint = sortedPoints.at(-1);
+    if (firstPoint == null || lastPoint == null) {
+        return null;
+    }
+    if (percent <= firstPoint.percent) {
+        return normalizeHexColor(firstPoint.color);
+    }
+    if (percent >= lastPoint.percent) {
+        return normalizeHexColor(lastPoint.color);
+    }
+    const nextPointIndex = sortedPoints.findIndex((point) => point.percent >= percent);
+    const previousPoint = sortedPoints[nextPointIndex - 1];
+    const nextPoint = sortedPoints[nextPointIndex];
+    if (previousPoint == null || nextPoint == null) {
+        return null;
+    }
+    if (previousPoint.color.toLowerCase() === nextPoint.color.toLowerCase()) {
+        return normalizeHexColor(previousPoint.color);
+    }
+    if (previousPoint.percent === nextPoint.percent) {
+        return normalizeHexColor(nextPoint.color);
+    }
+    return null;
+}
+function getSortedGradientPoints(points) {
+    return points
+        .filter((point) => Number.isFinite(point.percent) && isHexColor(point.color))
+        .slice()
+        .sort((a, b) => a.percent - b.percent);
+}
+function solidColorForRange(sortedPoints, [rangeStart, rangeEnd]) {
+    const expectedColor = colorAtPercent(sortedPoints, rangeStart);
+    if (expectedColor == null || !isOpaqueHexColor(expectedColor)) {
+        return null;
+    }
+    const breakpoints = [
+        rangeStart,
+        ...sortedPoints
+            .map((point) => point.percent)
+            .filter((percent) => percent > rangeStart && percent < rangeEnd),
+        rangeEnd,
+    ];
+    const isSolid = breakpoints.every((breakpoint, index) => {
+        if (colorAtPercent(sortedPoints, breakpoint) !== expectedColor) {
+            return false;
+        }
+        const nextBreakpoint = breakpoints[index + 1];
+        if (nextBreakpoint == null || nextBreakpoint === breakpoint) {
+            return true;
+        }
+        return (colorAtPercent(sortedPoints, (breakpoint + nextBreakpoint) / 2) ===
+            expectedColor);
+    });
+    return isSolid ? expectedColor : null;
+}
+function snapToZero(value) {
+    return Math.abs(value) < 1e-10 ? 0 : value;
+}
+function linearGradientPositionPercent(degrees, x, y, viewport) {
+    const radians = (degrees * Math.PI) / 180;
+    // Math.sin(Math.PI) is ~1.22e-16, not 0. Snap so a 180° gradient's edge
+    // sits exactly on a stop instead of just barely missing it.
+    const dx = snapToZero(Math.sin(radians));
+    const dy = snapToZero(-Math.cos(radians));
+    const gradientLength = Math.abs(dx) * viewport.width + Math.abs(dy) * viewport.height;
+    const offset = (x - viewport.width / 2) * dx + (y - viewport.height / 2) * dy;
+    return ((offset + gradientLength / 2) / gradientLength) * 100;
+}
+function linearEdgeRangePercent(degrees, edge, viewport) {
+    const y = edge === "top" ? 0 : viewport.height;
+    const start = linearGradientPositionPercent(degrees, 0, y, viewport);
+    const end = linearGradientPositionPercent(degrees, viewport.width, y, viewport);
+    return [Math.min(start, end), Math.max(start, end)];
+}
+function radialGradientPositionPercent(x, y, viewport) {
+    const radius = Math.hypot(viewport.width / 2, viewport.height / 2);
+    const distance = Math.hypot(x - viewport.width / 2, y - viewport.height / 2);
+    return (distance / radius) * 100;
+}
+function radialEdgeRangePercent(edge, viewport) {
+    const y = edge === "top" ? 0 : viewport.height;
+    const center = radialGradientPositionPercent(viewport.width / 2, y, viewport);
+    const corner = radialGradientPositionPercent(0, y, viewport);
+    return [Math.min(center, corner), Math.max(center, corner)];
+}
+function getSolidEdgeColor(color, edge, viewport, sortedPoints) {
+    switch (color.type) {
+        case "hex":
+        case "alias":
+            return mapColorInfo(color);
+        case "linear":
+            return solidColorForRange(sortedPoints ?? [], linearEdgeRangePercent(color.degrees, edge, viewport));
+        case "radial":
+            return solidColorForRange(sortedPoints ?? [], radialEdgeRangePercent(edge, viewport));
+    }
+}
+// `position: sticky` promotes a header/footer to its own compositor layer
+// regardless of fill, so even transparent sticky elements break the opposite
+// safe-area strip. Pass `stickyComponents` when painting into a single CSS
+// variable (SDK runtime + SSR head) so the covered edge is nulled and the
+// caller can fall through to the override/host chain; editor previews leave
+// it absent.
+export function getBackgroundSafeAreaColors(background, colorMode, viewport, options) {
+    let top = null;
+    let bottom = null;
+    if (background?.type === "color") {
+        const color = mapColorMode(colorMode, background.value);
+        const sortedPoints = color.type === "linear" || color.type === "radial"
+            ? getSortedGradientPoints(color.points)
+            : null;
+        top = getSolidEdgeColor(color, "top", viewport, sortedPoints);
+        bottom = getSolidEdgeColor(color, "bottom", viewport, sortedPoints);
+    }
+    if (options?.stickyComponents) {
+        const hasHeader = options.stickyComponents.hasHeader === true;
+        const hasFooter = options.stickyComponents.hasFooter === true;
+        // A single CSS variable can only paint one strip; emit only when exactly
+        // one edge is exposed (the opposite edge is occluded by a sticky element).
+        top = hasFooter && !hasHeader ? top : null;
+        bottom = hasHeader && !hasFooter ? bottom : null;
+    }
+    if (options?.paywallFallbackColor != null ||
+        options?.hostFallbackColor != null) {
+        const fallback = resolveSafeAreaFallbackCss(options.paywallFallbackColor, options.hostFallbackColor, colorMode);
+        top = top ?? fallback;
+        bottom = bottom ?? fallback;
+    }
+    return { top, bottom };
+}

package/dist/utils/safe-area.d.ts

@@ -0,0 +1 @@
+export { getBackgroundSafeAreaColors, getSafeAreaFallbackColorHeadStyles, } from "./safe-area-background";

package/dist/utils/safe-area.js

@@ -0,0 +1,4 @@
+// Public surface for `@revenuecat/purchases-ui-js/safe-area`. The CSS var
+// name and helpers used internally by `applyDocumentBackground` are
+// deliberately not re-exported.
+export { getBackgroundSafeAreaColors, getSafeAreaFallbackColorHeadStyles, } from "./safe-area-background";

package/package.json

@@ -2,7 +2,7 @@
   "name": "@revenuecat/purchases-ui-js",
   "description": "Web components for Paywalls. Powered by RevenueCat",
   "private": false,
-  "version": "4.3.0",
+  "version": "4.5.0",
   "author": {
     "name": "RevenueCat, Inc."
   },
@@ -65,6 +65,10 @@
     },
     "./web-components": {
       "default": "./dist/web-components/index.js"
+    },
+    "./safe-area": {
+      "types": "./dist/utils/safe-area.d.ts",
+      "default": "./dist/utils/safe-area.js"
     }
   },
   "engines": {