astro-lqip 1.7.1 → 1.8.0

package/README.md

@@ -4,13 +4,13 @@
 
 # 🖼️ astro-lqip
 
-[![GitHub Release](https://img.shields.io/github/v/release/felixicaza/astro-lqip?logo=npm)](https://www.npmjs.com/package/astro-lqip)
+[![GitHub Release](https://img.shields.io/github/v/release/felixicaza/astro-lqip?logo=npm)](https://npmx.dev/package/astro-lqip)
 [![GitHub License](https://img.shields.io/github/license/felixicaza/astro-lqip)](https://github.com/felixicaza/astro-lqip/blob/main/LICENSE)
 
-Native extended Astro components for generating low quality image placeholders (LQIP).
+Native extended Astro components for generating low-quality image placeholders (LQIP), compatible with `<img>`, `<picture>` and CSS background images.
 
 ## ✨ Features
-- 🖼️ Supports both `<Image>` and `<Picture>` components.
+- 🖼️ Supports both `<Image>` and `<Picture>` components and CSS background images.
 - 🎨 Multiple LQIP techniques: base64, solid color, CSS via gradients and SVG.
 - 🚀 Easy to use, just replace the native Astro components with the ones from [astro-lqip](https://astro-lqip.web.app/).
 - ⚡️ Support images as static imports or using string paths.
@@ -40,7 +40,7 @@ yarn add astro-lqip
 
 ## 🚀 Usage
 
-In your current Astro project, just replace the import of the native Astro `<Image>` or `<Picture>` components with the ones provided by [astro-lqip](https://astro-lqip.web.app/).
+In your current Astro project, just replace the import of the native Astro `<Image>` or `<Picture>` components with the ones provided by [astro-lqip](https://astro-lqip.web.app/) or import the `<Background>` component for CSS background images.
 
 ### Image
 
@@ -56,18 +56,38 @@ In your current Astro project, just replace the import of the native Astro `<Ima
 + import { Picture } from 'astro-lqip/components';
 ```
 
+### Background
+
+```diff
++ import { Background } from 'astro-lqip/components';
+```
+
 Example:
 
 ```astro
 ---
-import { Image, Picture } from 'astro-lqip/components';
+import { Image, Picture, Background } from 'astro-lqip/components';
 
 import image from '/src/assets/images/image.png';
 import otherImage from '/src/assets/images/other-image.png';
+import backgroundImage from '/src/assets/images/background-image.png';
 ---
 
 <Image src={image} alt="Cover Image" width={220} height={220} />
 <Picture src={otherImage} alt="Other Image" width={220} height={220} />
+<Background src={backgroundImage}>
+  <section>
+    <p>Optimized background</p>
+  </section>
+</Background>
+
+<style>
+  section {
+    background-image: var(--background);
+    background-size: cover;
+    background-position: center;
+  }
+</style>
 ```
 
 > [!TIP]
@@ -77,40 +97,81 @@ Example with absolute path:
 
 ```astro
 ---
-import { Image, Picture } from 'astro-lqip/components';
+import { Image, Picture, Background } from 'astro-lqip/components';
 ---
 
 <Image src="/src/assets/images/image.png" alt="Cover Image" width={220} height={220} />
 <Picture src="/src/assets/images/other-image.png" alt="Other Image" width={220} height={220} />
+<Background src="/src/assets/images/background-image.png">
+  <section>
+    <p>Optimized background</p>
+  </section>
+</Background>
+
+<style>
+  section {
+    background-image: var(--background);
+    background-size: cover;
+    background-position: center;
+  }
+</style>
 ```
 
 Example with relative path:
 
 ```astro
 ---
-import { Image, Picture } from 'astro-lqip/components';
+import { Image, Picture, Background } from 'astro-lqip/components';
 ---
 
 <!-- assuming you are on the path `/src/pages/index.astro` -->
 <Image src="../assets/images/image.png" alt="Cover Image" width={220} height={220} />
 <Picture src="../assets/images/other-image.png" alt="Other Image" width={220} height={220} />
+<Background src="../assets/images/background-image.png">
+  <section>
+    <p>Optimized background</p>
+  </section>
+</Background>
+
+<style>
+  section {
+    background-image: var(--background);
+    background-size: cover;
+    background-position: center;
+  }
+</style>
 ```
 
 Example with alias:
 
 ```astro
 ---
-import { Image, Picture } from 'astro-lqip/components';
+import { Image, Picture, Background } from 'astro-lqip/components';
 ---
 
 <Image src="@/assets/images/image.png" alt="Cover Image" width={220} height={220} />
 <Picture src="@/assets/images/other-image.png" alt="Other Image" width={220} height={220} />
+<Background src="@/assets/images/background-image.png">
+  <section>
+    <p>Optimized background</p>
+  </section>
+</Background>
+
+<style>
+  section {
+    background-image: var(--background);
+    background-size: cover;
+    background-position: center;
+  }
+</style>
 ```
 
 Learn how to configure path aliasing in the [Astro documentation](https://docs.astro.build/en/guides/typescript/#import-aliases). If you want more examples of uses you can see the [Usage Tips](https://astro-lqip.web.app/usage-tips/) page.
 
 ## ⚙️ Props
 
+### Image and Picture
+
 Both `<Image>` and `<Picture>` components support all the props of the [native Astro components](https://docs.astro.build/en/reference/modules/astro-assets/), but adds a couple of props for LQIP management:
 
 - `lqip`: The LQIP type to use. It can be one of the following:
@@ -140,6 +201,102 @@ import otherImage from '/src/assets/images/other-image.png';
 > [!TIP]
 > For the `<Image>` component, a `parentAttributes` prop similar to `pictureAttributes` has been added.
 
+### Background
+
+The `<Background>` component supports the following props:
+
+- `src` (required): The source of the background image located in `src` folder. It can be a static import, absolute path, relative path, alias path or remote URL.
+- `lqip`: The LQIP type to use. It can be one of the following:
+  - `base64`: Generates a Base64-encoded LQIP image. (default option)
+  - `color`: Generates a solid color placeholder.
+- `cssVariable`: A string that represents the name of the CSS variable to store the background data.
+  - By default, the background data is stored in a CSS variable named `--background`.
+  - For responsive backgrounds, the CSS variable names are generated based on the provided widths, following the pattern `--background-small` (lower than 768px), `--background-medium` (768px to 1199px), `--background-large` (1200px to 1919px) and `--background-xlarge` (1920px and above). `--background` is also generated for the largest image for backward compatibility.
+  - If the `cssVariable` prop is provided, the generated CSS variable names will follow the pattern `--{cssVariable}-small`, `--{cssVariable}-medium`, `--{cssVariable}-large` and `--{cssVariable}-xlarge`.
+- `format`: The image format to use for the background. It can be one of the following in string or an array of strings. If an array is provided, this generates multiple background images with the native [`image-set()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/image/image-set) CSS function, which allows the browser to choose the best format to use based on its support:
+  - `avif`
+  - `webp` (default option)
+  - `jpeg`
+  - `png`
+- `widths`: An array of numbers that represents the widths to use for responsive background images.
+- `width`: The width to use for the background image. This prop is ignored if the `widths` prop is provided.
+- `height`: The height to use for the background image. This prop is ignored if the `widths` prop is provided.
+- `quality`: The quality to use for the background image. It can be a number from `1` to `100`.
+- `fit`: The fit to use for the background image. It can be one of the following:
+  - `cover`
+  - `contain`
+  - `fill`
+  - `inside`
+  - `outside`
+
+Example:
+
+```astro
+---
+import { Background } from 'astro-lqip/components';
+import backgroundImage from '/src/assets/images/background-image.png';
+---
+
+<Background src={backgroundImage} lqip="color" cssVariable="--bg-lqip" format={["avif", "webp"]} width={500} height={300} quality={80} fit="cover">
+  <section>
+    <p>Optimized background</p>
+  </section>
+</Background>
+
+<style>
+  section {
+    background-image: var(--bg-lqip);
+    background-size: cover;
+    background-position: center;
+  }
+</style>
+```
+
+Example with responsive background:
+
+```astro
+---
+import { Background } from 'astro-lqip/components';
+import backgroundImage from '/src/assets/images/background-image.png';
+---
+
+<Background src={backgroundImage} format="avif" widths={[475, 1000, 1536, 2100]}>
+  <section>
+    <p>Optimized background</p>
+  </section>
+</Background>
+
+<style>
+  section {
+    background-image: var(--background-small); /* 475px */
+    background-size: cover;
+    background-position: center;
+  }
+
+  @media (width >= 768px) {
+    section {
+      background-image: var(--background-medium); /* 1000px */
+    }
+  }
+
+  @media (width >= 1200px) {
+    section {
+      background-image: var(--background-large); /* 1536px */
+    }
+  }
+
+  @media (width >= 1920px) {
+    section {
+      /* or var(--background), since it's the default variable for the largest image */
+      background-image: var(--background-xlarge); /* 2100px */
+    }
+  }
+</style>
+```
+
+> [!NOTE]
+> The `lqipSize` prop is not compatible with this component, to avoid large CSS outputs.
+
 ## 💡 Knowledge
 
 Since this integration is built on top of Astro native `<Image>` and `<Picture>` components, you can refer to the [Astro documentation](https://docs.astro.build/en/guides/images/) for more information on how to use it.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "astro-lqip",
-  "version": "1.7.1",
-  "description": "Native extended Astro components for generating low quality image placeholders (LQIP).",
+  "version": "1.8.0",
+  "description": "🖼️ Native extended Astro components for generating low-quality image placeholders (LQIP), compatible with <img>, <picture> and CSS background images.",
   "keywords": [
     "astro",
     "astro-component",
     "astro-integration",
     "image",
     "picture",
+    "css",
+    "background",
     "lqip"
   ],
   "homepage": "https://astro-lqip.web.app",
@@ -27,6 +29,7 @@
   "files": [
     "src"
   ],
+  "sideEffects": false,
   "simple-git-hooks": {
     "pre-commit": "pnpm nano-staged"
   },
@@ -37,31 +40,34 @@
     "plaiceholder": "3.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.1",
-    "@typescript-eslint/parser": "8.46.4",
-    "astro": "5.15.5",
-    "bumpp": "10.3.1",
-    "eslint": "9.39.1",
-    "eslint-plugin-astro": "1.5.0",
-    "eslint-plugin-jsonc": "2.21.0",
+    "@eslint/js": "9.39.4",
+    "@typescript-eslint/parser": "8.57.0",
+    "astro": "6.0.4",
+    "bumpp": "10.4.1",
+    "eslint": "9.39.4",
+    "eslint-plugin-astro": "1.6.0",
+    "eslint-plugin-jsonc": "3.1.2",
     "eslint-plugin-jsx-a11y": "6.10.2",
-    "eslint-plugin-package-json": "0.71.0",
-    "eslint-plugin-yml": "1.19.0",
-    "globals": "16.5.0",
+    "eslint-plugin-package-json": "0.90.1",
+    "eslint-plugin-yml": "3.3.1",
+    "globals": "17.4.0",
     "jiti": "2.6.1",
-    "nano-staged": "0.8.0",
-    "neostandard": "0.12.2",
+    "nano-staged": "0.9.0",
+    "neostandard": "0.13.0",
     "simple-git-hooks": "2.13.1"
   },
   "peerDependencies": {
     "astro": ">=3.3.0"
   },
   "scripts": {
-    "build": "pnpm -r build",
-    "dev": "pnpm -r dev",
+    "build:docs": "pnpm --filter ./docs -r build",
+    "dev": "pnpm --filter=!./docs -r dev",
+    "dev:docs": "pnpm --filter ./docs -r dev",
     "lint": "eslint --cache .",
     "lint:fix": "eslint --cache --fix .",
     "preview": "pnpm -r preview",
-    "release": "bumpp -r"
+    "release": "bumpp",
+    "test:fixtures": "pnpm --filter \"./tests/fixtures/**\" -r build",
+    "test:fixtures:preview": "pnpm --filter \"./tests/fixtures/**\" -r preview"
   }
 }

package/src/components/Background.astro

@@ -0,0 +1,21 @@
+---
+import type { ImageTransform } from '../types'
+
+import { useLqipBackground } from '../utils/useLqipBackground'
+
+import '../styles/background.css'
+
+type Props = ImageTransform
+
+const props = Astro.props as Props
+const isDevelopment = import.meta.env.MODE === 'development'
+
+const { style: backgroundStyle } = await useLqipBackground({
+  ...props,
+  isDevelopment
+})
+---
+
+<div data-astro-lqip-bg style={backgroundStyle}>
+  <slot />
+</div>

package/src/index.ts

@@ -1,2 +1,3 @@
 export { default as Picture } from './components/Picture.astro'
 export { default as Image } from './components/Image.astro'
+export { default as Background } from './components/Background.astro'

package/src/styles/background.css

@@ -0,0 +1,3 @@
+[data-astro-lqip-bg] {
+  display: contents;
+}

package/src/types/image-transform.type.ts

@@ -0,0 +1,54 @@
+/**
+ * This file defines the types for the ImageTransform, which is used to optimize images for the Background component.
+ * Extracted from Astro's Types, reference: https://github.com/withastro/astro/blob/2dcd8d54c6fb00183228d757bf684e67c79029d8/packages/astro/src/assets/types.ts#L82
+ */
+
+type ValidOutputFormats = ['avif', 'png', 'webp', 'jpeg', 'jpg', 'svg']
+type ImageQualityPreset = 'low' | 'mid' | 'high' | 'max' | (string & {})
+type ImageQuality = ImageQualityPreset | number
+type ImageOutputFormat = ValidOutputFormats[number] | (string & {})
+type ImageFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | (string & {})
+
+export interface ImageTransform {
+  /**
+   * Path of the image that will be used as the background.
+   * It can be a relative path, an absolute path, an alias or ImageMetadata.
+   */
+  src: string | ImageMetadata
+  /**
+   * CSS custom property that will receive the generated background.
+   * (defaults to --background)
+   */
+  cssVariable?: string
+  /**
+   * LQIP placeholder strategy for Background (defaults to 'base64').
+   * Only 'base64' and 'color' are supported to keep CSS-friendly values.
+   */
+  lqip?: 'base64' | 'color'
+  /**
+   * Specifies one or more output formats (first entry is preferred fallback).
+   * Accepts a single `ImageOutputFormat` or an ordered array.
+   * (defaults to webp)
+   */
+  format?: ImageOutputFormat | ImageOutputFormat[] | undefined
+  /**
+   * Explicit widths used for responsive variants.
+   */
+  widths?: number[] | undefined
+  /**
+   * Single width fallback when `widths` is omitted.
+   */
+  width?: number | undefined
+  /**
+   * Target height for generated assets.
+   */
+  height?: number | undefined
+  /**
+   * Compression quality preset or numeric percentage.
+   */
+  quality?: ImageQuality | undefined
+  /**
+   * Object-fit behavior applied during resizing.
+   */
+  fit?: ImageFit | undefined
+}

package/src/types/index.ts

@@ -1,5 +1,6 @@
 export * from './components-options.type'
 export * from './image-path.type'
+export * from './image-transform.type'
 export * from './lqip.type'
 export * from './plaiceholder.type'
 export * from './props.type'

package/src/utils/getLqip.ts

@@ -15,9 +15,38 @@ function isRemoteUrl(url: string) {
 const CACHE_DIR = join(process.cwd(), 'node_modules', '.cache', 'astro-lqip')
 const EXTENSIONS = ['jpg', 'jpeg', 'png', 'webp', 'avif']
 const SEARCH_ROOT = ['src']
+const HASHED_FILENAME_REGEX = /\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9]+$/
+const HASHED_FILENAME_CAPTURE_REGEX = /^(.+?)\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9]+$/
+
+const BASE_URL = (() => {
+  try {
+    const base = (import.meta.env?.BASE_URL ?? '/') as string
+    if (!base || base === '/') return '/'
+    return base.endsWith('/') ? base.slice(0, -1) : base
+  } catch {
+    return '/'
+  }
+})()
 
 const searchCache = new Map<string, string | null>()
 
+function stripBasePath(src: string) {
+  if (typeof src !== 'string') return src
+
+  const queryIndex = src.indexOf('?')
+  let pathOnly = queryIndex >= 0 ? src.slice(0, queryIndex) : src
+
+  if (BASE_URL !== '/' && pathOnly.startsWith(BASE_URL)) {
+    pathOnly = pathOnly.slice(BASE_URL.length) || '/'
+  }
+
+  if (!pathOnly.startsWith('/')) {
+    pathOnly = `/${pathOnly}`
+  }
+
+  return pathOnly
+}
+
 async function ensureCacheDir() {
   if (!existsSync(CACHE_DIR)) {
     await mkdir(CACHE_DIR, { recursive: true })
@@ -27,7 +56,7 @@ async function ensureCacheDir() {
 function extractOriginalFileName(filename: string) {
   const file = filename.split('/').pop() || ''
 
-  const match = file.match(/^(.+?)\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9]+$/)
+  const match = file.match(HASHED_FILENAME_CAPTURE_REGEX)
   if (match) return match[1]
 
   const parts = file.split('.')
@@ -126,24 +155,25 @@ export async function getLqip(
 
   if (!isDevelopment) {
     const src = imagePath.src
-
-    const clean = src.replace(/^\//, '')
-
-    const candidatePaths = [
-      join(process.cwd(), 'dist', 'client', clean),
-      join(process.cwd(), 'dist', clean),
-      join(process.cwd(), 'dist', '_astro', clean.replace(/^_astro\//, ''))
-    ]
-
-    for (const path of candidatePaths) {
-      if (existsSync(path)) {
-        return await generateLqip(path, lqipType, lqipSize, isDevelopment)
+    const normalizedSrc = stripBasePath(src)
+    const clean = normalizedSrc.replace(/^\//, '')
+
+    if (clean) {
+      const candidatePaths = [
+        join(process.cwd(), 'dist', 'client', clean),
+        join(process.cwd(), 'dist', clean)
+      ]
+
+      for (const path of candidatePaths) {
+        if (existsSync(path)) {
+          return await generateLqip(path, lqipType, lqipSize, isDevelopment)
+        }
       }
     }
 
-    // if not found, try to recursively find the original source
-    if (src.startsWith('/_astro/')) {
-      const originalBase = extractOriginalFileName(src)
+    const fileName = normalizedSrc.split('/').pop() ?? ''
+    if (HASHED_FILENAME_REGEX.test(fileName)) {
+      const originalBase = extractOriginalFileName(normalizedSrc)
       const originalSource = await recursiveFind(originalBase)
 
       if (originalSource) {

package/src/utils/useLqipBackground.ts

@@ -0,0 +1,298 @@
+import type { ImageMetadata } from 'astro'
+import type { ImageTransform } from '../types'
+
+import { getImage, inferRemoteSize } from 'astro:assets'
+
+import { resolveImagePath } from './resolveImagePath'
+import { getLqip } from './getLqip'
+import { PREFIX } from '../constants'
+
+type SourceEntry = {
+  url: string
+  width?: number
+}
+
+type FormatSourceSet = {
+  format: string
+  mimeType: string
+  fallbackSrc: string
+  sources: SourceEntry[]
+}
+
+type FormatSelector = (formatSource: FormatSourceSet) => SourceEntry | undefined
+
+type BuildResponsiveBackgroundStyleOptions = {
+  referenceSources: SourceEntry[]
+  baseVariable: string
+  createValue: (selector?: FormatSelector) => string
+}
+
+type CreateBackgroundValueOptions = {
+  formatSources: FormatSourceSet[]
+  optimizedImages: Awaited<ReturnType<typeof getImage>>[]
+  isFormatArray: boolean
+  selector?: FormatSelector
+  layer?: string
+}
+
+export type UseLqipBackgroundOptions = ImageTransform & {
+  cssVariable?: string
+  lqip?: string
+  isDevelopment: boolean
+}
+
+export async function useLqipBackground({
+  src,
+  cssVariable = '--background',
+  format = 'webp',
+  widths,
+  width,
+  height,
+  quality,
+  fit,
+  lqip = 'base64',
+  isDevelopment
+}: UseLqipBackgroundOptions) {
+  let normalizedWidth = width
+  let normalizedHeight = height
+
+  const resolvedSrc = await resolveImagePath(src)
+  if (!resolvedSrc) {
+    throw new Error(`${PREFIX} Could not resolve background image in "${src}"`)
+  }
+
+  const remoteBackgroundUrl = typeof resolvedSrc === 'string' && isRemoteSource(resolvedSrc) ? resolvedSrc : null
+  if (remoteBackgroundUrl && (!normalizedWidth || !normalizedHeight)) {
+    try {
+      const { width: inferredWidth, height: inferredHeight } = await inferRemoteSize(remoteBackgroundUrl)
+      normalizedWidth ??= inferredWidth
+      normalizedHeight ??= inferredHeight
+    } catch (error) {
+      console.warn(`${PREFIX} Failed to infer remote background size for "${remoteBackgroundUrl}".`, error)
+    }
+
+    if (!normalizedWidth || !normalizedHeight) {
+      throw new Error(
+        `${PREFIX} Remote background images require width and height. Provide both props or ensure the URL is reachable in your Astro config 'image.domains'.`
+      )
+    }
+  }
+
+  const imageInput: string | ImageMetadata = typeof resolvedSrc === 'string' ? resolvedSrc : (resolvedSrc as ImageMetadata)
+
+  let lqipLayer: string | undefined
+  const lqipSize = 12
+  const lqipInput = typeof resolvedSrc === 'string' ? { src: resolvedSrc } : resolvedSrc
+  if (lqipInput) {
+    const rawLqipValue = await getLqip(lqipInput, lqip, lqipSize, isDevelopment)
+    lqipLayer = formatLqipLayer(lqip, typeof rawLqipValue === 'string' ? rawLqipValue : undefined)
+  }
+
+  const formatValues = Array.isArray(format) ? format : [format]
+  const normalizedFormats = sortFormats(
+    formatValues.filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
+  )
+  const targetFormats = normalizedFormats.length ? normalizedFormats : ['webp']
+  const isFormatArray = Array.isArray(format)
+
+  const sharedImageOptions = {
+    src: imageInput,
+    widths,
+    width: normalizedWidth,
+    height: normalizedHeight,
+    quality,
+    fit
+  }
+
+  const optimizedImages = await Promise.all(
+    targetFormats.map((currentFormat) => getImage({ ...sharedImageOptions, format: currentFormat }))
+  )
+
+  const formatSources: FormatSourceSet[] = optimizedImages.map((optimizedImage, index) => ({
+    format: targetFormats[index],
+    mimeType: mimeTypeFromFormat(targetFormats[index]),
+    fallbackSrc: optimizedImage.src,
+    sources: parseSrcSetAttribute(optimizedImage.srcSet?.attribute)
+  }))
+
+  const baseVariable = normalizeCssVariableName(cssVariable)
+  const referenceSources = formatSources[0]?.sources ?? []
+  const hasWidths = Array.isArray(widths) && widths.length > 0
+
+  const createValueWithLqip = (selector?: FormatSelector) =>
+    createBackgroundValue({
+      formatSources,
+      optimizedImages,
+      isFormatArray,
+      selector,
+      layer: lqipLayer
+    })
+
+  const backgroundStyle = hasWidths
+    ? buildResponsiveBackgroundStyle({
+      referenceSources,
+      baseVariable,
+      createValue: createValueWithLqip
+    })
+    : `${baseVariable}: ${createValueWithLqip()}`
+
+  return { style: backgroundStyle, resolvedSrc }
+}
+
+function normalizeCssVariableName(variable: string) {
+  const trimmed = variable.trim()
+  if (!trimmed) return '--background'
+  return trimmed.startsWith('--') ? trimmed : `--${trimmed}`
+}
+
+function normalizeFormatValue(value: string) {
+  return value.trim().toLowerCase()
+}
+
+function sortFormats(values: string[]) {
+  const formatPriority = ['avif', 'webp', 'png', 'jpeg', 'jpg', 'svg']
+  const seen = new Set<string>()
+  const unique = values
+    .map((value) => normalizeFormatValue(value))
+    .filter((value) => {
+      if (!value || seen.has(value)) return false
+      seen.add(value)
+      return true
+    })
+
+  return unique.sort((a, b) => {
+    const priorityA = formatPriority.indexOf(a)
+    const priorityB = formatPriority.indexOf(b)
+    const normalizedA = priorityA === -1 ? Number.MAX_SAFE_INTEGER : priorityA
+    const normalizedB = priorityB === -1 ? Number.MAX_SAFE_INTEGER : priorityB
+    if (normalizedA === normalizedB) {
+      return a.localeCompare(b)
+    }
+    return normalizedA - normalizedB
+  })
+}
+
+function isRemoteSource(value: unknown): value is string {
+  return typeof value === 'string' && /^https?:\/\//.test(value)
+}
+
+function mimeTypeFromFormat(value: string) {
+  switch (value) {
+    case 'avif':
+      return 'image/avif'
+    case 'webp':
+      return 'image/webp'
+    case 'png':
+      return 'image/png'
+    case 'jpeg':
+    case 'jpg':
+      return 'image/jpeg'
+    case 'svg':
+      return 'image/svg+xml'
+    default:
+      return `image/${value}`
+  }
+}
+
+function parseSrcSetAttribute(attribute?: string): SourceEntry[] {
+  if (!attribute) return []
+
+  const entries = attribute
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const lastSpaceIndex = entry.lastIndexOf(' ')
+      if (lastSpaceIndex === -1) {
+        return { url: entry } satisfies SourceEntry
+      }
+
+      const url = entry.slice(0, lastSpaceIndex)
+      const descriptor = entry.slice(lastSpaceIndex + 1)
+      const widthMatch = descriptor.match(/(?<value>\d+(?:\.\d+)?)(?<unit>[wx])/i)
+      const width
+        = widthMatch?.groups?.unit?.toLowerCase() === 'w' ? Number.parseFloat(widthMatch.groups.value) : undefined
+
+      return { url, width }
+    })
+
+  const unique = new Map(entries.map((entry) => [entry.url, entry]))
+  return Array.from(unique.values()).sort((a, b) => (a.width ?? 0) - (b.width ?? 0))
+}
+
+function buildResponsiveBackgroundStyle({ referenceSources, baseVariable, createValue }: BuildResponsiveBackgroundStyleOptions) {
+  if (!referenceSources.length) {
+    return `${baseVariable}: ${createValue()}`
+  }
+
+  const declarations = [
+    `${baseVariable}: ${createValue((formatSource) => formatSource.sources[formatSource.sources.length - 1])}`
+  ]
+
+  const buckets = [
+    { suffix: '-small', match: (width?: number) => typeof width === 'number' && width < 768 },
+    { suffix: '-medium', match: (width?: number) => typeof width === 'number' && width >= 768 && width <= 1200 },
+    { suffix: '-large', match: (width?: number) => typeof width === 'number' && width > 1200 && width <= 1920 },
+    { suffix: '-xlarge', match: (width?: number) => typeof width === 'number' && width > 1920 }
+  ] as const
+
+  for (const bucket of buckets) {
+    const referenceMatch = [...referenceSources].reverse().find((source) => bucket.match(source.width))
+    if (!referenceMatch || typeof referenceMatch.width !== 'number') continue
+
+    const value = createValue((formatSource) =>
+      formatSource.sources.find((source) => source.width === referenceMatch.width)
+    )
+    declarations.push(`${baseVariable}${bucket.suffix}: ${value}`)
+  }
+
+  return declarations.join('; ')
+}
+
+function selectSourceOrFallback(formatSource: FormatSourceSet, selector?: FormatSelector) {
+  return selector?.(formatSource) ?? formatSource.sources[formatSource.sources.length - 1] ?? { url: formatSource.fallbackSrc }
+}
+
+function appendLqipLayer(baseValue: string, layer?: string) {
+  if (baseValue && layer) {
+    return `${baseValue}, ${layer}`
+  }
+  return baseValue || layer || ''
+}
+
+function createBackgroundValue({
+  formatSources,
+  optimizedImages,
+  isFormatArray,
+  selector,
+  layer
+}: CreateBackgroundValueOptions) {
+  if (!formatSources.length) {
+    const fallbackSrc = optimizedImages[0]?.src ?? ''
+    const baseValue = fallbackSrc ? `url('${fallbackSrc}')` : ''
+    return appendLqipLayer(baseValue, layer)
+  }
+
+  if (!isFormatArray) {
+    const primary = formatSources[0]
+    const selected = selectSourceOrFallback(primary, selector)
+    const baseValue = `url('${selected.url ?? primary.fallbackSrc}')`
+    return appendLqipLayer(baseValue, layer)
+  }
+
+  const parts = formatSources.map((formatSource) => {
+    const selected = selectSourceOrFallback(formatSource, selector)
+    const url = selected.url ?? formatSource.fallbackSrc
+    return `url('${url}') type('${formatSource.mimeType}')`
+  })
+
+  return appendLqipLayer(`image-set(${parts.join(', ')})`, layer)
+}
+
+function formatLqipLayer(lqipType?: string, value?: string) {
+  if (!lqipType || !value) return undefined
+  if (lqipType === 'color') {
+    return `linear-gradient(${value}, ${value})`
+  }
+  return `url("${value}")`
+}