@revenuecat/purchases-ui-js 3.12.1 → 4.0.0

package/dist/components/layout/Main/Main.stories.svelte

@@ -0,0 +1,263 @@
+<script module lang="ts">
+  import { defineMeta } from "@storybook/addon-svelte-csf";
+  import type { ComponentProps } from "svelte";
+  import Main from "./Main.svelte";
+  import Screen from "../../workflows/Screen.svelte";
+  import type { Background } from "../../../types/background";
+  import type { Component } from "../../../types/component";
+  import type { HeaderProps } from "../../../types/components/header";
+  import type { FooterProps } from "../../../types/components/footer";
+  import type { TextNodeProps } from "../../../types/components/text";
+  import type { WorkflowScreen } from "../../../types/workflow";
+  import { uiConfigData } from "../../../stories/fixtures";
+
+  function textComponent(id: string, textLid: string): TextNodeProps {
+    return {
+      type: "text",
+      id,
+      name: "",
+      text_lid: textLid,
+      font_name: null,
+      font_size: "body_m",
+      font_weight: "bold",
+      horizontal_alignment: "center",
+      color: { light: { type: "hex", value: "#ffffffff" } },
+      background_color: null,
+      padding: { top: 0, bottom: 0, leading: 0, trailing: 0 },
+      margin: { top: 0, bottom: 0, leading: 0, trailing: 0 },
+      size: { width: { type: "fit" }, height: { type: "fit" } },
+    };
+  }
+
+  function visibleStack(components: Component[] = []) {
+    return {
+      type: "stack" as const,
+      id: "s",
+      name: "",
+      components,
+      size: {
+        width: { type: "fill" as const },
+        height: { type: "fit" as const },
+      },
+      dimension: {
+        type: "vertical" as const,
+        alignment: "center" as const,
+        distribution: "center" as const,
+      },
+      spacing: 0,
+      margin: { top: 0, bottom: 0, leading: 0, trailing: 0 },
+      padding: { top: 16, bottom: 16, leading: 0, trailing: 0 },
+      background_color: { light: { type: "hex" as const, value: "#00000033" } },
+      background: null,
+      border: null,
+      shape: null,
+      shadow: null,
+      badge: null,
+    };
+  }
+
+  const minimalHeader: HeaderProps = {
+    id: "header",
+    name: "Header",
+    type: "header",
+    stack: visibleStack([textComponent("header-label", "header_label")]),
+  };
+
+  const minimalFooter: FooterProps = {
+    id: "footer",
+    name: "Footer",
+    type: "footer",
+    stack: visibleStack([textComponent("footer-label", "footer_label")]),
+  };
+
+  function shellData(
+    background: Background,
+    hasHeader: boolean,
+    hasFooter: boolean,
+  ): WorkflowScreen {
+    return {
+      id: "main-story",
+      default_locale: "en_US",
+      components_localizations: {
+        en_US: { header_label: "Header", footer_label: "Footer" },
+      },
+      asset_base_url: "https://assets.pawwalls.com",
+      config: {},
+      localized_strings: {},
+      localized_strings_by_tier: {},
+      name: "Main story",
+      offering_id: null,
+      revision: 1,
+      template_name: "stack",
+      components_config: {
+        base: {
+          background,
+          header: hasHeader ? minimalHeader : null,
+          sticky_footer: hasFooter ? minimalFooter : null,
+          stack: {
+            type: "stack" as const,
+            id: "content",
+            name: "",
+            components: [],
+            size: {
+              width: { type: "fill" as const },
+              height: { type: "fill" as const },
+            },
+            dimension: {
+              type: "vertical" as const,
+              alignment: "center" as const,
+              distribution: "start" as const,
+            },
+            spacing: 0,
+            margin: { top: 0, bottom: 0, leading: 0, trailing: 0 },
+            padding: { top: 0, bottom: 0, leading: 0, trailing: 0 },
+            background_color: null,
+            background: null,
+            border: null,
+            shape: null,
+            shadow: null,
+            badge: null,
+          },
+        },
+      },
+    };
+  }
+
+  const solidColour: Background = {
+    type: "color",
+    value: { light: { type: "hex", value: "#6B4FBBFF" } },
+  };
+
+  const gradient: Background = {
+    type: "color",
+    value: {
+      light: {
+        type: "linear",
+        degrees: 180,
+        points: [
+          { percent: 0, color: "#3B82F6FF" },
+          { percent: 100, color: "#9333EAFF" },
+        ],
+      },
+    },
+  };
+
+  const image: Background = {
+    type: "image",
+    fit_mode: "fill",
+    color_overlay: null,
+    value: {
+      light: {
+        width: 1170,
+        height: 2532,
+        original: "https://placehold.co/1170x2532",
+        heic: "https://placehold.co/1170x2532",
+        heic_low_res: "https://placehold.co/1170x2532",
+        webp: "https://placehold.co/1170x2532",
+        webp_low_res: "https://placehold.co/1170x2532",
+      },
+    },
+  };
+
+  const { Story } = defineMeta({
+    title: "Components/Layout/Main",
+    component: Main,
+    render: template,
+    args: { paywallData: shellData(solidColour, false, false) },
+  });
+</script>
+
+{#snippet template({
+  paywallData,
+  preferredColorMode,
+}: ComponentProps<typeof Main>)}
+  <div class="viewport-frame">
+    <Main {paywallData} {preferredColorMode}>
+      <div class="content-wrapper">
+        <Screen paywallComponents={paywallData} uiConfig={uiConfigData} />
+      </div>
+    </Main>
+  </div>
+{/snippet}
+
+<Story
+  name="Solid colour"
+  args={{ paywallData: shellData(solidColour, false, false) }}
+/>
+<Story
+  name="Solid colour — header"
+  args={{ paywallData: shellData(solidColour, true, false) }}
+/>
+<Story
+  name="Solid colour — footer"
+  args={{ paywallData: shellData(solidColour, false, true) }}
+/>
+<Story
+  name="Solid colour — header and footer"
+  args={{ paywallData: shellData(solidColour, true, true) }}
+/>
+
+<Story
+  name="Gradient"
+  args={{ paywallData: shellData(gradient, false, false) }}
+/>
+<Story
+  name="Gradient — header"
+  args={{ paywallData: shellData(gradient, true, false) }}
+/>
+<Story
+  name="Gradient — footer"
+  args={{ paywallData: shellData(gradient, false, true) }}
+/>
+<Story
+  name="Gradient — header and footer"
+  args={{ paywallData: shellData(gradient, true, true) }}
+/>
+
+<Story name="Image" args={{ paywallData: shellData(image, false, false) }} />
+<Story
+  name="Image — header"
+  args={{ paywallData: shellData(image, true, false) }}
+/>
+<Story
+  name="Image — footer"
+  args={{ paywallData: shellData(image, false, true) }}
+/>
+<Story
+  name="Image — header and footer"
+  args={{ paywallData: shellData(image, true, true) }}
+/>
+
+<style>
+  /* A fixed-position frame that emulates rc-workflows' <body> (see app.css).
+     Using position:fixed escapes Storybook's DOM chain (.sb-show-main, #storybook-root, PaywallWrapper) */
+  .viewport-frame {
+    position: fixed;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    padding: env(safe-area-inset-top) env(safe-area-inset-right)
+      env(safe-area-inset-bottom) env(safe-area-inset-left);
+    background-color: var(--rc-purchases-ui-bg-color, Canvas);
+    color-scheme: light dark;
+    overflow: hidden;
+  }
+
+  .content-wrapper {
+    width: 100%;
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  /* Screen's containerId is "screen-container" by default */
+  :global(#screen-container) {
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow: hidden;
+  }
+</style>

package/dist/components/layout/Main/Main.stories.svelte.d.ts

@@ -0,0 +1,19 @@
+import Main from "./Main.svelte";
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const Main: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type Main = InstanceType<typeof Main>;
+export default Main;

package/dist/components/layout/Main/Main.svelte

@@ -0,0 +1,117 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { ColorMode } from "../../../types";
+  import type { PaywallData } from "../../../types/paywall";
+  import { paywallRootBackgroundModel } from "../../../utils/background-utils";
+  import { MediaQuery } from "svelte/reactivity";
+  import ViewportBackdrop from "./ViewportBackdrop.svelte";
+
+  // Tracks the last Main instance that wrote --rc-purchases-ui-bg-color.
+  // Cleanup only removes the variable if this instance is still the last writer,
+  // so an unmounting shell won't clear a value set by a shell that overlapped it
+  // during a page transition.
+  let lastBgWriter: symbol | null = null;
+
+  interface Props {
+    paywallData: PaywallData | null | undefined;
+    preferredColorMode?: ColorMode;
+    children: Snippet;
+  }
+
+  const { paywallData, preferredColorMode, children }: Props = $props();
+
+  const instanceId: symbol = Symbol();
+
+  const prefersDark = new MediaQuery("prefers-color-scheme: dark", false);
+  const colorMode: ColorMode = $derived(
+    preferredColorMode ?? (prefersDark.current ? "dark" : "light"),
+  );
+
+  const viewportBackdropModel = $derived(
+    paywallRootBackgroundModel(paywallData, colorMode),
+  );
+
+  // When a sticky header or footer is present, iOS promotes it to its own compositor
+  // layer which breaks the fixed backdrop's safe-area painting for the opposite strip.
+  // Returns the edge stop colour to paint on body to patch the uncovered strip, or null.
+  // Only works for exactly vertical gradients (0°/180°) — any other angle produces a
+  // horizontal colour range across the strip that no single solid colour can represent.
+  function gradientSafeAreaFallbackColour(
+    gradient: string,
+    hasHeader: boolean,
+    hasFooter: boolean,
+  ): string | null {
+    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;
+  }
+
+  // Solid colours use --rc-purchases-ui-bg-color on body — iOS reliably propagates
+  // background-color to the viewport canvas (safe-area strips). Gradients and images
+  // are handled by ViewportBackdrop (position:fixed) instead.
+  $effect(() => {
+    if (typeof document === "undefined") return;
+    const model = viewportBackdropModel;
+    const root = document.documentElement;
+
+    let value: string | null = null;
+    if (model.kind === "style" && model.style.background) {
+      const bg = model.style.background;
+      if (!bg.includes("gradient")) {
+        value = bg;
+      } else {
+        const base = paywallData?.components_config?.base;
+        value = gradientSafeAreaFallbackColour(
+          bg,
+          !!base?.header,
+          !!base?.sticky_footer,
+        );
+      }
+    }
+
+    if (value !== null) {
+      lastBgWriter = instanceId;
+      root.style.setProperty("--rc-purchases-ui-bg-color", value);
+    }
+
+    return () => {
+      if (lastBgWriter === instanceId) {
+        lastBgWriter = null;
+        root.style.removeProperty("--rc-purchases-ui-bg-color");
+      }
+    };
+  });
+</script>
+
+<div class="main">
+  <ViewportBackdrop model={viewportBackdropModel} />
+  <main class="main-content">
+    {@render children()}
+  </main>
+</div>
+
+<style>
+  .main {
+    flex: 1 1 auto;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+  }
+
+  .main-content {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+</style>

package/dist/components/layout/Main/Main.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+import type { ColorMode } from "../../../types";
+import type { PaywallData } from "../../../types/paywall";
+interface Props {
+    paywallData: PaywallData | null | undefined;
+    preferredColorMode?: ColorMode;
+    children: Snippet;
+}
+declare const Main: import("svelte").Component<Props, {}, "">;
+type Main = ReturnType<typeof Main>;
+export default Main;

package/dist/components/layout/Main/ViewportBackdrop.svelte

@@ -0,0 +1,65 @@
+<script lang="ts">
+  import type { PaywallRootBackgroundModel } from "../../../utils/background-utils";
+
+  // This component exists because iOS WebKit does not reliably extend body's
+  // background-image (gradients, bitmaps) into safe-area strips — only background-color
+  // propagates reliably via the viewport canvas. A dedicated position:fixed element that
+  // explicitly fills the full viewport (including safe areas) is the consistent paint
+  // surface for gradients and images on iOS Safari.
+  //
+  // Solid colours are NOT handled here — they use background-color on body instead,
+  // which avoids compositor surface churn on navigation.
+  const { model }: { model: PaywallRootBackgroundModel } = $props();
+
+  const backdropStyle = $derived.by((): string => {
+    if (
+      model.kind === "style" &&
+      model.style.background?.includes("gradient")
+    ) {
+      return Object.entries(model.style)
+        .map(([k, v]) => `${k}:${v}`)
+        .join(";");
+    }
+    if (model.kind === "image") {
+      return [
+        `background-image:url("${model.src}")`,
+        `background-size:${model.fit}`,
+        `background-position:${model.position}`,
+        `background-repeat:no-repeat`,
+      ].join(";");
+    }
+    return "";
+  });
+
+  const overlayStyle = $derived(
+    model.kind === "image" && model.overlay && model.overlay !== "none"
+      ? `background:${model.overlay}`
+      : null,
+  );
+
+  const shouldRender = $derived(backdropStyle !== "");
+</script>
+
+{#if shouldRender}
+  <div class="viewport-backdrop" style={backdropStyle}>
+    {#if overlayStyle}
+      <div class="viewport-backdrop-overlay" style={overlayStyle}></div>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  .viewport-backdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 0;
+    pointer-events: none;
+    overflow: hidden;
+  }
+
+  .viewport-backdrop-overlay {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+</style>

package/dist/components/layout/Main/ViewportBackdrop.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { PaywallRootBackgroundModel } from "../../../utils/background-utils";
+type $$ComponentProps = {
+    model: PaywallRootBackgroundModel;
+};
+declare const ViewportBackdrop: import("svelte").Component<$$ComponentProps, {}, "">;
+type ViewportBackdrop = ReturnType<typeof ViewportBackdrop>;
+export default ViewportBackdrop;

package/dist/components/paywall/Paywall.stories.svelte

@@ -1,7 +1,9 @@
 <script module lang="ts">
   import { defineMeta } from "@storybook/addon-svelte-csf";
+  import type { ComponentProps } from "svelte";
 
   import Paywall from "./Paywall.svelte";
+  import Main from "../layout/Main/Main.svelte";
   import {
     alignmentPaywallData,
     calmPaywallData,
@@ -31,12 +33,16 @@
   import { CUSTOM_VARIABLES_PAYWALL } from "./fixtures/custom-variables-paywall";
   import { COUNTDOWN_PAYWALL } from "../countdown/fixtures/countdown-paywall";
   import { mockDateDecorator } from "storybook-mock-date-decorator";
-  import { IndividualPackageVariables } from "./fixtures/express-purchase-button-paywall";
+  import {
+    IndividualPackageVariables,
+    DUELINGUE_PAYWALL,
+  } from "./fixtures/express-purchase-button-paywall";
   import { CustomVariableValue } from "../../types/variables";
 
   const { Story } = defineMeta({
     title: "Example/Paywall",
     component: Paywall,
+    render: template,
     args: {
       onPurchaseClicked: (selectedPackageId: string, actionId: string) =>
         alert(
@@ -55,9 +61,13 @@
   });
 </script>
 
-<script>
-  import { DUELINGUE_PAYWALL } from "./fixtures/express-purchase-button-paywall";
-</script>
+{#snippet template(props: ComponentProps<typeof Paywall>)}
+  <div class="paywall-story-frame">
+    <Main paywallData={props.paywallData}>
+      <Paywall {...props} />
+    </Main>
+  </div>
+{/snippet}
 
 <Story
   name="Stack paywall"
@@ -491,3 +501,19 @@
     },
   }}
 />
+
+<style>
+  .paywall-story-frame {
+    flex: 1 1 auto;
+    display: flex;
+    flex-direction: column;
+    background-color: var(--rc-purchases-ui-bg-color, Canvas);
+    color-scheme: light dark;
+  }
+
+  /* Allow chromatic to capture the full content snapshot */
+  .paywall-story-frame :global(.paywall-content-scroll) {
+    flex: 1 1 auto;
+    overflow-y: visible;
+  }
+</style>

package/dist/components/paywall/Paywall.svelte

@@ -32,8 +32,6 @@
     type PackageInfo,
     type VariableDictionary,
   } from "../../types/variables";
-  import { mapBackground } from "../../utils/background-utils";
-  import { css } from "../../utils/base-utils";
   import { STICKY_OVERLAY_Z_INDEX } from "../../utils/constants";
   import { registerFonts } from "../../utils/font-utils";
   import { findSelectedPackageId } from "../../utils/style-utils";
@@ -130,8 +128,7 @@
     customVariables = {},
   }: Props = $props();
 
-  const getColorMode = setColorModeContext(() => preferredColorMode);
-  const colorMode = $derived(getColorMode());
+  setColorModeContext(() => preferredColorMode);
 
   const { default_locale, components_config, components_localizations } =
     paywallData;
@@ -285,8 +282,6 @@
 
   setPackageInfoContext(packageInfo);
 
-  const style = $derived(css(mapBackground(colorMode, null, base.background)));
-
   onMount(() => {
     registerFonts(uiConfig);
   });
@@ -305,7 +300,7 @@
 </script>
 
 <svelte:boundary onerror={onError}>
-  <div class={paywallClass} {style}>
+  <div class={paywallClass}>
     {#if header}
       <div
         class="header-wrapper"
@@ -321,12 +316,20 @@
         maxContentWidth
           ? `max-width: ${maxContentWidth}; margin-inline: auto;`
           : "",
-        pullContentUnderHeader ? `margin-top: -${headerHeight}px;` : "",
       ]
         .filter(Boolean)
         .join(" ")}
     >
-      <Stack {...stack} class="paywall-content-scroll" />
+      <Stack
+        {...stack}
+        class="paywall-content-scroll"
+        style={{
+          height: "auto",
+          ...(pullContentUnderHeader
+            ? { "margin-top": `-${headerHeight}px` }
+            : {}),
+        }}
+      />
       {#if sticky_footer}
         <Footer {...sticky_footer} />
       {/if}
@@ -342,27 +345,16 @@
   .paywall {
     position: relative;
     display: flex;
+    flex: 1 1 auto;
     flex-direction: column;
     align-items: stretch;
-    height: 100%;
+    min-height: 0;
 
     transition-property: filter, transform;
     transition-duration: 0.1s;
     transition-timing-function: ease-in-out;
     transform-origin: center;
 
-    &::before {
-      content: "";
-      position: absolute;
-      top: 0;
-      left: 0;
-      width: 100%;
-      height: 100%;
-      background: var(--overlay);
-      pointer-events: none;
-      z-index: 1;
-    }
-
     &:global(.blur) {
       filter: blur(10px) brightness(0.8);
       transform: scale(1.045);
@@ -384,7 +376,7 @@
     min-height: 0;
 
     & > :global(.paywall-content-scroll) {
-      flex-grow: 1;
+      flex: 1 1 0;
       min-height: 0;
       overflow-y: auto;
     }

package/dist/components/workflows/Screen.stories.svelte

@@ -1,7 +1,9 @@
 <script module lang="ts">
   import { defineMeta } from "@storybook/addon-svelte-csf";
+  import type { ComponentProps } from "svelte";
 
   import Screen from "./Screen.svelte";
+  import Main from "../layout/Main/Main.svelte";
   import { paywallData, uiConfigData } from "../../stories/fixtures";
   import type { WorkflowScreen } from "../../types/workflow";
 
@@ -20,6 +22,7 @@
   const { Story } = defineMeta({
     title: "Components/Screen",
     component: Screen,
+    render: template,
     args: {
       paywallComponents: defaultScreen,
       selectedLocale: defaultScreen.default_locale,
@@ -28,4 +31,43 @@
   });
 </script>
 
+{#snippet template(props: ComponentProps<typeof Screen>)}
+  <div class="viewport-frame">
+    <Main paywallData={props.paywallComponents}>
+      <div class="content-wrapper">
+        <Screen {...props} />
+      </div>
+    </Main>
+  </div>
+{/snippet}
+
 <Story name="Default" />
+
+<style>
+  .viewport-frame {
+    position: fixed;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    background-color: var(--rc-purchases-ui-bg-color, Canvas);
+    color-scheme: light dark;
+    overflow: hidden;
+  }
+
+  .content-wrapper {
+    width: 100%;
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  :global(#screen-container) {
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow: hidden;
+  }
+</style>

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { default as Stack } from "./components/stack/Stack.svelte";
 export { default as Text } from "./components/text/Text.svelte";
 export { default as Timeline } from "./components/timeline/Timeline.svelte";
 export { default as Screen } from "./components/workflows/Screen.svelte";
+export { default as Main } from "./components/layout/Main/Main.svelte";
 export { default as Video } from "./components/video/Video.svelte";
 export * from "./types";
 export { type PaywallData } from "./types/paywall";

package/dist/index.js

@@ -14,6 +14,7 @@ export { default as Stack } from "./components/stack/Stack.svelte";
 export { default as Text } from "./components/text/Text.svelte";
 export { default as Timeline } from "./components/timeline/Timeline.svelte";
 export { default as Screen } from "./components/workflows/Screen.svelte";
+export { default as Main } from "./components/layout/Main/Main.svelte";
 export { default as Video } from "./components/video/Video.svelte";
 export * from "./types";
 export {} from "./types/paywall";

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

@@ -1,4 +1,19 @@
 import type { ColorMode } from "../types";
 import type { Background } from "../types/background";
 import type { ColorGradientScheme } from "../types/colors";
+import type { PaywallData } from "../types/paywall";
+export type PaywallRootBackgroundModel = {
+    kind: "none";
+} | {
+    kind: "style";
+    style: Record<string, string>;
+    overlay: string;
+} | {
+    kind: "image";
+    src: string;
+    fit: string;
+    position: string;
+    overlay: string;
+};
+export declare function paywallRootBackgroundModel(paywallData: PaywallData | null | undefined, colorMode: ColorMode): PaywallRootBackgroundModel;
 export declare function mapBackground(colorMode: ColorMode, background_color: ColorGradientScheme | null | undefined, background: Background | null | undefined): Record<string, string>;

package/dist/utils/background-utils.js

@@ -23,6 +23,27 @@ function mapBackgroundValue(colorMode, background_color, background) {
     }
     return mapBackgroundVideo(colorMode, background.value);
 }
+export function paywallRootBackgroundModel(paywallData, colorMode) {
+    const background = paywallData?.components_config?.base?.background;
+    if (background == null) {
+        return { kind: "none" };
+    }
+    if (background.type !== "image") {
+        const styles = mapBackground(colorMode, null, background);
+        const overlay = styles["--overlay"] ?? "none";
+        const style = { ...styles };
+        delete style["--overlay"];
+        return { kind: "style", style, overlay };
+    }
+    const files = mapColorMode(colorMode, background.value);
+    return {
+        kind: "image",
+        src: files.webp,
+        fit: mapFitMode(background.fit_mode),
+        position: background.fit_mode === "fill" ? "center" : "top center",
+        overlay: mapOverlay(colorMode, background.color_overlay),
+    };
+}
 export function mapBackground(colorMode, background_color, background) {
     const value = mapBackgroundValue(colorMode, background_color, background);
     if (background?.type !== "image") {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@revenuecat/purchases-ui-js",
   "description": "Web components for Paywalls. Powered by RevenueCat",
   "private": false,
-  "version": "3.12.1",
+  "version": "4.0.0",
   "author": {
     "name": "RevenueCat, Inc."
   },
@@ -93,6 +93,7 @@
     "@testing-library/svelte": "^5.3.1",
     "@types/node": "24.9.2",
     "@types/qrcode": "^1.5.6",
+    "@types/react": "^19.2.14",
     "@typescript-eslint/parser": "8.57.2",
     "chromatic": "13.3.2",
     "eslint": "9.38.0",
@@ -122,4 +123,4 @@
       "eslint --fix"
     ]
   }
-}
+}