astro-lqip 1.7.2 → 1.8.1

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/dist/astro-lqip.css

@@ -0,0 +1 @@
+@layer astro-lqip{[data-astro-lqip]{--opacity:1;--z-index:0;isolation:isolate;width:fit-content;height:fit-content;line-height:0;display:inline-block;position:relative;overflow:clip;&:after{content:"";pointer-events:none;opacity:var(--opacity);z-index:var(--z-index);background:var(--lqip-background);background-position:50%;background-size:cover;transition:opacity 1s;position:absolute;inset:0}& img{z-index:1;position:relative}@media (scripting:none){--opacity:0;--z-index:1}}[data-astro-lqip-bg]{display:contents}}

package/dist/index.d.mts

@@ -0,0 +1,140 @@
+import { LocalImageProps, Picture as Picture$1, RemoteImageProps } from "astro:assets";
+import { GetPlaiceholderReturn } from "plaiceholder";
+import { ImageMetadata } from "astro";
+import { ComponentProps, HTMLAttributes } from "astro/types";
+
+//#region src/types/lqip.type.d.ts
+type LqipType = 'color' | 'css' | 'base64' | 'svg';
+//#endregion
+//#region src/types/style.type.d.ts
+type StylePrimitive = string | number | undefined;
+type StyleMap<TExtra = never> = Record<string, StylePrimitive | TExtra>;
+type StyleInput<TExtra = never> = StyleMap<TExtra> | string;
+//#endregion
+//#region src/types/components-options.type.d.ts
+type ComponentsOptions = {
+  src: string | object;
+  lqip: LqipType;
+  lqipSize: number;
+  styleProps: StyleMap;
+  forbiddenVars: string[];
+  isDevelopment: boolean | undefined;
+};
+//#endregion
+//#region src/types/image-path.type.d.ts
+type ImagePath = string | {
+  src: string;
+} | Promise<{
+  default: {
+    src: string;
+  };
+}>;
+type ResolvedImage = {
+  src: string;
+  width?: number;
+  height?: number;
+  [k: string]: unknown;
+};
+type ImportModule = Record<string, unknown> & {
+  default?: unknown;
+};
+type GlobMap = Record<string, () => Promise<ImportModule>>;
+//#endregion
+//#region src/types/image-transform.type.d.ts
+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 & {});
+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;
+}
+//#endregion
+//#region src/types/plaiceholder.type.d.ts
+type GetSVGReturn = GetPlaiceholderReturn['svg'];
+//#endregion
+//#region src/types/props.type.d.ts
+type Props = {
+  /**
+   * LQIP type.
+   * This can be 'color', 'css', 'svg' or 'base64'.
+   * The default value is 'base64'.
+   */
+  lqip?: LqipType;
+  /**
+   * Size of the LQIP image in pixels.
+   * This value should be between 4 and 64.
+   * The default value is 4.
+   */
+  lqipSize?: number;
+};
+//#endregion
+//#region src/types/svg-node.type.d.ts
+type StyleAttrs = StyleInput<GetSVGReturn>;
+type SVGNodeAttrs = {
+  style?: StyleAttrs;
+} & Record<string, string | number>;
+type SVGNode = [string, SVGNodeAttrs, SVGNode[]];
+//#endregion
+//#region src/components/Picture.d.ts
+type AstroPictureProps = ComponentProps<typeof Picture$1>;
+type Props$3 = AstroPictureProps & Props;
+//#endregion
+//#region src/components/Image.d.ts
+type Props$2 = (LocalImageProps | RemoteImageProps) & Props & {
+  parentAttributes?: HTMLAttributes<'div'>;
+};
+//#endregion
+//#region src/components/Background.d.ts
+type Props$1 = ImageTransform;
+//#endregion
+//#region src/index.d.ts
+type AstroTypedComponent<Props> = ((props: Props) => unknown) & {
+  isAstroComponentFactory?: boolean;
+  moduleId?: string;
+};
+declare const Image: AstroTypedComponent<Props$2>;
+declare const Picture: AstroTypedComponent<Props$3>;
+declare const Background: AstroTypedComponent<Props$1>;
+//#endregion
+export { Background, ComponentsOptions, GetSVGReturn, GlobMap, Image, ImagePath, ImageTransform, ImportModule, LqipType, Picture, Props, ResolvedImage, SVGNode, StyleAttrs, StyleInput, StyleMap };

package/dist/index.mjs

@@ -0,0 +1,18 @@
+import './astro-lqip.css';
+import{createComponent as e,renderComponent as t,renderSlotToString as n,renderTemplate as r,spreadAttributes as i}from"astro/runtime/server/index.js";import{Image as a,Picture as o,getImage as s,inferRemoteSize as c}from"astro:assets";import{existsSync as l,statSync as u}from"node:fs";import{mkdir as d,readFile as f,readdir as p,unlink as m,writeFile as h}from"node:fs/promises";import{basename as g,dirname as _,extname as v,join as y,relative as b,resolve as x,sep as S}from"node:path";import{fileURLToPath as C}from"node:url";import{getPlaiceholder as w}from"plaiceholder";const T=`[astro-lqip]`,E=process.cwd(),D=y(E,`src`),O=y(E,`public`),k=y(E,`dist`),ee=import.meta.env?.MODE===`development`,te=/(file:\/\/[^\s)]+|\/[^\s)]+|[A-Za-z]:[^\s)]+):\d+:\d+/,ne=[`${S}node_modules${S}`,`${S}dist${S}`,`${S}.astro${S}`,`${S}.prerender${S}`],re=new Set([`node_modules`,`dist`,`.astro`]),ie=new Set([`.astro`,`.vite`]),A=Object.assign({}),j=new Map,M=new Map;function N(e){if(!e)return;let t=e.toLowerCase();(t.includes(`/public/`)||e.startsWith(O))&&console.warn(`${T} Warning: image resolved from /public. Images should not be placed in /public - move them to /src so Astro can process them correctly.`),(t.endsWith(`.webp`)||t.endsWith(`.avif`))&&console.warn(`${T} Warning: image is in ${t.endsWith(`.webp`)?`webp`:`avif`} format. These formats are usually already optimized; using this component to re-process them may degrade quality.`)}function P(e){return typeof e==`object`&&!!e}function ae(e){return P(e)&&typeof e.then==`function`}function F(e){return P(e)&&typeof e.src==`string`}function oe(e){return/^https?:\/\//.test(e)}function se(e){let t=e.indexOf(`?`),n=e.indexOf(`#`),r=e.length;return t!==-1&&(r=Math.min(r,t)),n!==-1&&(r=Math.min(r,n)),e.slice(0,r)}function I(e){let t=se(e.trim()).replace(/\\/g,`/`);return t.startsWith(`@/`)?`src/${t.slice(2)}`:t.startsWith(`~@/`)?`src/${t.slice(3)}`:t}function L(e){return e.startsWith(`./`)||e.startsWith(`../`)}function R(e){let t=e;for(;t.startsWith(`./`)||t.startsWith(`../`);)t=t.startsWith(`./`)?t.slice(2):t.slice(3);return t}function ce(e){let t=e.match(te);if(!t?.[1])return null;let n=t[1];if(!n.startsWith(`file://`))return n;try{return C(n)}catch{return n.replace(/^file:\/\//,``)}}function le(e){return!e||!e.startsWith(`/`)&&!/^[A-Za-z]:/.test(e)||!e.startsWith(E)?!1:!ne.some(t=>e.includes(t))}function ue(){let e=Error().stack;if(!e)return null;for(let t of e.split(`
+`).slice(2)){let e=ce(t);if(e&&le(e))return _(e)}return null}function z(e){let t=b(E,e);return!e||t.startsWith(`..`)||t.includes(`..${S}`)||t.includes(`node_modules`)?null:e}function de(e){let t=b(E,e).replace(/\\/g,`/`);return!t||t.startsWith(`../`)?null:`/${t}`}function fe(e,t){let n=I(e),r=new Set;if(n.startsWith(`/src/`)?r.add(n):n.startsWith(`src/`)&&r.add(`/${n}`),t&&L(n)){let e=de(x(t,n));e?.startsWith(`/src/`)&&r.add(e)}if(L(n)){let e=R(n);e&&r.add(e.startsWith(`src/`)?`/${e}`:`/src/${e}`);let t=`/${e}`;for(let e of Object.keys(A))e.endsWith(t)&&r.add(e)}return!n.startsWith(`/`)&&!n.startsWith(`src/`)&&!L(n)&&r.add(`/src/${n}`),Array.from(r)}function pe(e,t){let n=I(e),r=new Set,i=n.startsWith(`/`)?n.slice(1):n;if(t&&L(n)){let e=z(x(t,n));e&&r.add(e)}if(L(n)){let e=R(n);if(e){let t=z(y(D,e));t&&r.add(t);let n=z(y(O,e));n&&r.add(n)}}if(n.startsWith(`/src/`)?r.add(y(E,n.slice(1))):n.startsWith(`src/`)&&r.add(y(E,n)),n.startsWith(`/public/`)?r.add(y(E,n.slice(1))):n.startsWith(`public/`)&&r.add(y(E,n)),!n.startsWith(`/`)){let e=z(y(D,n));e&&r.add(e);let t=z(y(E,n));t&&r.add(t)}else if(i){let e=z(y(E,i));e&&r.add(e)}return Array.from(r)}async function B(e){if(!e)return null;let t=`${D}::${e}`;if(j.has(t))return j.get(t)??null;async function n(t){let r;try{r=await p(t,{withFileTypes:!0})}catch{return}for(let i of r){let r=y(t,i.name);if(i.isDirectory()){if(re.has(i.name))continue;let e=await n(r);if(e)return e}else if(i.name===e)return r}}let r=await n(D);return j.set(t,r??null),r??null}function me(e,t){if(e!=null)return String(e).toLowerCase();let n=v(t).replace(`.`,``);return n?n.toLowerCase():void 0}function he(e,t,n,r){return`/@fs${e.replace(/\\/g,`/`)}?origWidth=${t}&origHeight=${n}&origFormat=${r}`}function ge(e,t){let n=g(e);if(t===n)return!0;let r=v(n),i=r?n.slice(0,-r.length):n;return t.startsWith(`${i}.`)&&t.endsWith(r)}function _e(e){let t=e.replace(/\\/g,`/`),n=t.lastIndexOf(`/_astro/`);if(n!==-1)return t.slice(n);let r=b(k,e).replace(/\\/g,`/`),i=r.indexOf(`.prerender/`);return i===-1?`/${r}`:`/${r.slice(i+11)}`}async function ve(e){if(M.has(e))return M.get(e)??null;if(!l(k))return M.set(e,null),null;async function t(n){let r;try{r=await p(n,{withFileTypes:!0})}catch{return}for(let i of r){let r=y(n,i.name);if(i.isDirectory()){if(ie.has(i.name))continue;let e=await t(r);if(e)return e}else if(ge(e,i.name))return r}}let n=await t(k);if(!n)return M.set(e,null),null;let r=_e(n);return M.set(e,r),r}async function V(e){try{let{metadata:t}=await w(await f(e),{size:4}),n=t?.width??0,r=t?.height??0,i=me(t?.format,e);if(!n||!r||!i)return console.warn(`${T} Missing metadata for "${e}".`),null;let a=ee?he(e,n,r,i):await ve(e);if(!a)return null;let o={src:a,width:n,height:r,format:i};return Object.defineProperty(o,`fsPath`,{value:e,enumerable:!1,configurable:!1,writable:!1}),o}catch(t){return console.warn(`${T} Failed to derive metadata for "${e}".`,t),null}}async function ye(e,t){let n=fe(e,t);for(let e of n){let t=A[e];if(!t)continue;let n=await t(),r=n.default??n;if(F(r))return N(r.src),r}return null}async function be(e,t){let n=pe(e,t);for(let e of n){if(!e||!l(e))continue;let t=await V(e);if(t)return N(e),t}let r=I(e).split(`/`).pop();if(!r)return null;let i=await B(r);if(!i||!l(i))return null;let a=await V(i);return a?(N(i),a):null}async function H(e){if(e==null)return null;if(ae(e)){let t=await e,n=t.default??t;return F(n)?(N(n.src),n):typeof n==`string`?(N(n),n):null}if(P(e)){let t=e;return N(typeof t.src==`string`?t.src:void 0),F(t)?t:null}if(typeof e==`string`){if(oe(e))return e;let t=I(e),n=L(t)?ue():null;return await ye(t,n)||await be(t,n)||null}return null}const xe=/[A-Z]/g;function Se(e){return e.replace(xe,e=>`-${e.toLowerCase()}`)}function U(e){if(e==null)return;if(typeof e==`string`)return e;let t=[];for(let[n,r]of Object.entries(e))r!=null&&t.push(`${Se(n)}:${r}`);return t.length>0?t.join(`;`):void 0}function W([e,t,n=[]]){let r=``;for(let[e,n]of Object.entries(t||{}))e===`style`&&n&&typeof n==`object`?r+=` style="${U(n)}"`:n!==void 0&&(r+=` ${e}="${n}"`);return n.length>0?`<${e}${r}>${n.map(W).join(``)}</${e}>`:`<${e}${r} />`}function Ce(e,t,n=``){if(!t)return{};switch(e){case`css`:return{"--lqip-background":t};case`svg`:return{"--lqip-background":`url('data:image/svg+xml;utf8,${encodeURIComponent(n)}')`};case`color`:return{"--lqip-background":t};default:return{"--lqip-background":`url('${t}')`}}}function we(e){return process.platform===`win32`&&/^\/[A-Za-z]:\//.test(e)?e.slice(1):e}function Te(){return typeof process<`u`&&!!process.versions?.node}async function Ee(e){if(Te())try{return await f(e)}catch{return}}function De(e,t=4){let n=Number(e);return Number.isFinite(n)?Math.min(64,Math.max(4,Math.round(n))):t}async function G(e,t,n,r){try{let i=we(e),a=De(n),o=await Ee(i);if(!o){console.warn(`${T} image not found for:`,e);return}let s=await w(o,{size:a}),c;switch(t){case`color`:c=s.color?.hex;break;case`css`:c=typeof s.css==`object`&&s.css.backgroundImage?s.css.backgroundImage:String(s.css);break;case`svg`:c=s.svg;break;default:c=s.base64;break}return r?console.log(`${T} LQIP (${t}) successfully generated!`):console.log(`${T} LQIP (${t}) successfully generated for:`,e),c}catch(n){console.error(`${T} Error generating LQIP (${t}) in:`,e,`
+`,n);return}}function Oe(e){return/^https?:\/\//.test(e)}const K=y(process.cwd(),`node_modules`,`.cache`,`astro-lqip`),ke=[`jpg`,`jpeg`,`png`,`webp`,`avif`],Ae=[`src`],je=/\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9]+$/,Me=/^(.+?)\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9]+$/,q=(()=>{try{let e=import.meta.env?.BASE_URL??`/`;return!e||e===`/`?`/`:e.endsWith(`/`)?e.slice(0,-1):e}catch{return`/`}})(),J=new Map;function Ne(e){if(typeof e!=`string`)return e;let t=e.indexOf(`?`),n=t>=0?e.slice(0,t):e;return q!==`/`&&n.startsWith(q)&&(n=n.slice(q.length)||`/`),n.startsWith(`/`)||(n=`/${n}`),n}async function Pe(){l(K)||await d(K,{recursive:!0})}function Fe(e){let t=e.split(`/`).pop()||``,n=t.match(Me);if(n)return n[1];let r=t.split(`.`);return r.length>=3?r.slice(0,r.length-2).join(`.`):r[0]}async function Ie(e){if(!e)return;if(J.has(e))return J.get(e)||void 0;let t=new Set([`node_modules`,`dist`,`.astro`]);async function n(r){let i;try{i=await p(r)}catch{return}for(let a of i){let i=y(r,a),o;try{o=u(i)}catch{continue}if(o.isDirectory()){if(t.has(a))continue;let e=await n(i);if(e)return e}else if(ke.some(t=>a===`${e}.${t}`))return i}}for(let t of Ae){let r=y(process.cwd(),t);if(l(r)){let t=await n(r);if(t)return J.set(e,t),t}}J.set(e,null)}async function Y(e,t,n,r){if(e?.src){if(Oe(e.src)){await Pe();let i=await fetch(e.src);if(!i.ok)return;let a=await i.arrayBuffer(),o=Buffer.from(a),s=y(K,`astro-lqip-${Math.random().toString(36).slice(2)}.jpg`);await h(s,o);try{return await G(s,t,n,r)}finally{await m(s)}}if(r&&e.src.startsWith(`/@fs/`)){let i=e.src.replace(/^\/@fs/,``).split(`?`)[0];return await G(i,t,n,r)}if(!r){let i=e.src,a=Ne(i),o=a.replace(/^\//,``);if(o){let e=[y(process.cwd(),`dist`,`client`,o),y(process.cwd(),`dist`,o)];for(let i of e)if(l(i))return await G(i,t,n,r)}let s=a.split(`/`).pop()??``;if(je.test(s)){let e=Fe(a),i=await Ie(e);if(i)return console.log(`${T} fallback recursive source found:`,i),await G(i,t,n,r);console.warn(`${T} original source not found recursively for basename:`,e)}}}}async function X({src:e,lqip:t=`base64`,lqipSize:n=4,styleProps:r={},forbiddenVars:i=[`--lqip-background`,`--z-index`,`--opacity`],isDevelopment:a}){let o=await H(e)??null,s;o&&(s=await Y(typeof o==`string`?{src:o}:o,t,n,a));let c=``;t===`svg`&&Array.isArray(s)&&(c=W(s));let l=Ce(t,s,c);for(let e of Object.keys(r))i.includes(e)&&console.warn(`${T} The CSS variable “${e}” should not be passed in style because it can override the functionality of LQIP.`);let u={...r,...l};return{lqipImage:s,svgHTML:c,lqipStyle:l,combinedStyle:u,resolvedSrc:o}}const Le=e({factory:async(e,n)=>{let{class:r,lqip:i=`base64`,lqipSize:a=4,pictureAttributes:s={},...c}=n,{combinedStyle:l,resolvedSrc:u}=await X({src:c.src,lqip:i,lqipSize:a,styleProps:s.style??{},forbiddenVars:[],isDevelopment:import.meta.env.MODE===`development`});return await t(e,`Picture`,o,{...c,class:r,src:u??c.src,pictureAttributes:{"data-astro-lqip":``,...s,style:l},onload:`
+          parentElement.style.setProperty("--z-index", 1);
+          parentElement.style.setProperty("--opacity", 0);
+        `})}}),Re=e({factory:async(e,n)=>{let{class:o,lqip:s=`base64`,lqipSize:c=4,parentAttributes:l={},...u}=n,{combinedStyle:d,resolvedSrc:f}=await X({src:u.src,lqip:s,lqipSize:c,styleProps:l.style??{},forbiddenVars:[],isDevelopment:import.meta.env.MODE===`development`});return r`
+      <div ${i({...l,class:[l.class,o].filter(Boolean).join(` `)||void 0,"data-astro-lqip":``,style:U(d)})}>
+        ${t(e,`Image`,a,{...u,class:o,src:f??u.src,onload:`
+              parentElement.style.setProperty("--z-index", 1);
+              parentElement.style.setProperty("--opacity", 0);
+            `})}
+      </div>
+    `}});async function ze({src:e,cssVariable:t=`--background`,format:n=`webp`,widths:r,width:i,height:a,quality:o,fit:l,lqip:u=`base64`,isDevelopment:d}){let f=i,p=a,m=await H(e);if(!m)throw Error(`${T} Could not resolve background image in "${e}"`);let h=typeof m==`string`&&Ue(m)?m:null;if(h&&(!f||!p)){try{let{width:e,height:t}=await c(h);f??=e,p??=t}catch(e){console.warn(`${T} Failed to infer remote background size for "${h}".`,e)}if(!f||!p)throw Error(`${T} Remote background images require width and height. Provide both props or ensure the URL is reachable in your Astro config 'image.domains'.`)}let g=m,_,v=typeof m==`string`?{src:m}:m;if(v){let e=await Y(v,u,12,d);_=qe(u,typeof e==`string`?e:void 0)}let y=He((Array.isArray(n)?n:[n]).filter(e=>typeof e==`string`&&e.trim().length>0)),b=y.length?y:[`webp`],x=Array.isArray(n),S={src:g,widths:r,width:f,height:p,quality:o,fit:l},C=await Promise.all(b.map(e=>s({...S,format:e}))),w=C.map((e,t)=>({format:b[t],mimeType:Z(b[t]),fallbackSrc:e.src,sources:We(e.srcSet?.attribute)})),E=Be(t),D=w[0]?.sources??[],O=Array.isArray(r)&&r.length>0,k=e=>Ke({formatSources:w,optimizedImages:C,isFormatArray:x,selector:e,layer:_});return{style:O?Ge({referenceSources:D,baseVariable:E,createValue:k}):`${E}: ${k()}`,resolvedSrc:m}}function Be(e){let t=e.trim();return t?t.startsWith(`--`)?t:`--${t}`:`--background`}function Ve(e){return e.trim().toLowerCase()}function He(e){let t=[`avif`,`webp`,`png`,`jpeg`,`jpg`,`svg`],n=new Set;return e.map(e=>Ve(e)).filter(e=>!e||n.has(e)?!1:(n.add(e),!0)).sort((e,n)=>{let r=t.indexOf(e),i=t.indexOf(n),a=r===-1?2**53-1:r,o=i===-1?2**53-1:i;return a===o?e.localeCompare(n):a-o})}function Ue(e){return typeof e==`string`&&/^https?:\/\//.test(e)}function Z(e){switch(e){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/${e}`}}function We(e){if(!e)return[];let t=e.split(`,`).map(e=>e.trim()).filter(Boolean).map(e=>{let t=e.lastIndexOf(` `);if(t===-1)return{url:e};let n=e.slice(0,t),r=e.slice(t+1).match(/(?<value>\d+(?:\.\d+)?)(?<unit>[wx])/i);return{url:n,width:r?.groups?.unit?.toLowerCase()===`w`?Number.parseFloat(r.groups.value):void 0}}),n=new Map(t.map(e=>[e.url,e]));return Array.from(n.values()).sort((e,t)=>(e.width??0)-(t.width??0))}function Ge({referenceSources:e,baseVariable:t,createValue:n}){if(!e.length)return`${t}: ${n()}`;let r=[`${t}: ${n(e=>e.sources[e.sources.length-1])}`],i=[{suffix:`-small`,match:e=>typeof e==`number`&&e<768},{suffix:`-medium`,match:e=>typeof e==`number`&&e>=768&&e<=1200},{suffix:`-large`,match:e=>typeof e==`number`&&e>1200&&e<=1920},{suffix:`-xlarge`,match:e=>typeof e==`number`&&e>1920}];for(let a of i){let i=[...e].reverse().find(e=>a.match(e.width));if(!i||typeof i.width!=`number`)continue;let o=n(e=>e.sources.find(e=>e.width===i.width));r.push(`${t}${a.suffix}: ${o}`)}return r.join(`; `)}function Q(e,t){return t?.(e)??e.sources[e.sources.length-1]??{url:e.fallbackSrc}}function $(e,t){return e&&t?`${e}, ${t}`:e||t||``}function Ke({formatSources:e,optimizedImages:t,isFormatArray:n,selector:r,layer:i}){if(!e.length){let e=t[0]?.src??``;return $(e?`url('${e}')`:``,i)}if(!n){let t=e[0];return $(`url('${Q(t,r).url??t.fallbackSrc}')`,i)}return $(`image-set(${e.map(e=>`url('${Q(e,r).url??e.fallbackSrc}') type('${e.mimeType}')`).join(`, `)})`,i)}function qe(e,t){if(!(!e||!t))return e===`color`?`linear-gradient(${t}, ${t})`:`url("${t}")`}const Je=e({factory:async(e,t,a)=>{let o=import.meta.env.MODE===`development`,{style:s}=await ze({...t,isDevelopment:o}),c=await n(e,a.default);return r`
+      <div data-astro-lqip-bg ${i({style:s})}>
+        ${c}
+      </div>
+    `}}),Ye=Re,Xe=Le,Ze=Je;export{Ze as Background,Ye as Image,Xe as Picture};

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "astro-lqip",
-  "version": "1.7.2",
-  "description": "Native extended Astro components for generating low quality image placeholders (LQIP).",
+  "version": "1.8.1",
+  "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",
@@ -21,12 +23,21 @@
   "license": "MIT",
   "author": "Felix Icaza",
   "type": "module",
+  "types": "./dist/index.d.mts",
   "exports": {
-    "./components": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./components": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
   },
   "files": [
-    "src"
+    "dist"
   ],
+  "sideEffects": false,
   "simple-git-hooks": {
     "pre-commit": "pnpm nano-staged"
   },
@@ -37,34 +48,53 @@
     "plaiceholder": "3.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.1",
-    "@typescript-eslint/parser": "8.48.0",
-    "astro": "5.16.1",
-    "bumpp": "10.3.2",
-    "eslint": "9.39.1",
-    "eslint-plugin-astro": "1.5.0",
-    "eslint-plugin-jsonc": "2.21.0",
+    "@eslint/js": "9.39.4",
+    "@tsdown/css": "0.21.7",
+    "@types/node": "25.5.0",
+    "@typescript-eslint/parser": "8.57.0",
+    "astro": "6.1.2",
+    "bumpp": "11.0.1",
+    "concurrently": "9.2.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.85.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",
+    "lightningcss": "1.32.0",
     "nano-staged": "0.9.0",
-    "neostandard": "0.12.2",
-    "simple-git-hooks": "2.13.1"
+    "neostandard": "0.13.0",
+    "simple-git-hooks": "2.13.1",
+    "tsdown": "0.21.7"
   },
   "peerDependencies": {
     "astro": ">=3.3.0"
   },
   "scripts": {
+    "build": "tsdown",
     "build:docs": "pnpm --filter ./docs -r build",
-    "dev": "pnpm --filter=!./docs -r dev",
+    "build:watch": "tsdown --watch",
+    "dev": "concurrently \"pnpm dev:lib\" \"pnpm dev:fixtures\"",
     "dev:docs": "pnpm --filter ./docs -r dev",
+    "dev:fixtures": "pnpm --filter \"./tests/fixtures/**\" -r --parallel dev",
+    "dev:lib": "tsdown --watch",
     "lint": "eslint --cache .",
     "lint:fix": "eslint --cache --fix .",
-    "preview": "pnpm -r preview",
     "release": "bumpp",
+    "sync:types": " pnpm --filter \"./tests/fixtures/**\" astro sync",
+    "test": "pnpm test:fixtures",
     "test:fixtures": "pnpm --filter \"./tests/fixtures/**\" -r build",
-    "test:fixtures:preview": "pnpm --filter \"./tests/fixtures/**\" -r preview"
+    "test:fixtures:custom-base": "pnpm --filter \"./tests/fixtures/custom-base\" build",
+    "test:fixtures:default": "pnpm --filter \"./tests/fixtures/default\" build",
+    "test:fixtures:preview": "pnpm --filter \"./tests/fixtures/**\" -r preview",
+    "test:fixtures:preview:custom-base": "pnpm --filter \"./tests/fixtures/custom-base\" preview",
+    "test:fixtures:preview:default": "pnpm --filter \"./tests/fixtures/default\" preview",
+    "test:fixtures:preview:ssr": "pnpm --filter \"./tests/fixtures/ssr-node\" preview",
+    "test:fixtures:preview:ssr:custom-base": "pnpm --filter \"./tests/fixtures/ssr-node-custom-base\" preview",
+    "test:fixtures:ssr": "pnpm --filter \"./tests/fixtures/ssr-node\" build",
+    "test:fixtures:ssr:custom-base": "pnpm --filter \"./tests/fixtures/ssr-node-custom-base\" build",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/components/Image.astro

@@ -1,45 +0,0 @@
----
-import type { LocalImageProps, RemoteImageProps } from 'astro:assets'
-import type { HTMLAttributes } from 'astro/types'
-import type { Props as LqipProps } from '../types'
-
-import { useLqipImage } from '../utils/useLqipImage'
-
-import { Image as ImageComponent } from 'astro:assets'
-
-import '../styles/lqip.css'
-
-type Props = (LocalImageProps | RemoteImageProps) & LqipProps & {
-  parentAttributes?: HTMLAttributes<'div'>
-}
-
-const { class: className, lqip = 'base64', lqipSize = 4, parentAttributes = {}, ...props } = Astro.props as Props
-
-const isDevelopment = import.meta.env.MODE === 'development'
-
-const { combinedStyle, resolvedSrc } = await useLqipImage({
-  src: props.src,
-  lqip,
-  lqipSize,
-  styleProps: (parentAttributes.style ?? {}) as Record<string, string | number | undefined>,
-  forbiddenVars: [],
-  isDevelopment
-})
-
-const componentProps = {
-  ...props,
-  src: resolvedSrc ?? props.src
-}
-const combinedParentAttributes = {
-  ...parentAttributes,
-  style: combinedStyle
-}
----
-
-<div class={className} data-astro-lqip {...combinedParentAttributes}>
-  <ImageComponent
-    {...componentProps as LocalImageProps | RemoteImageProps}
-    class={className}
-    onload="parentElement.style.setProperty('--z-index', 1), parentElement.style.setProperty('--opacity', 0)"
-  />
-</div>

package/src/components/Picture.astro

@@ -1,41 +0,0 @@
----
-import type { Props as AstroPictureProps } from 'astro/components/Picture.astro'
-import type { Props as LqipProps } from '../types'
-
-import { useLqipImage } from '../utils/useLqipImage'
-
-import { Picture as PictureComponent } from 'astro:assets'
-
-import '../styles/lqip.css'
-
-type Props = AstroPictureProps & LqipProps
-
-const { class: className, lqip = 'base64', lqipSize = 4, pictureAttributes = {}, ...props } = Astro.props as Props
-
-const isDevelopment = import.meta.env.MODE === 'development'
-
-const { combinedStyle, resolvedSrc } = await useLqipImage({
-  src: props.src,
-  lqip,
-  lqipSize,
-  styleProps: (pictureAttributes.style ?? {}) as Record<string, string | number | undefined>,
-  forbiddenVars: [],
-  isDevelopment
-})
-
-const componentProps = {
-  ...props,
-  src: resolvedSrc ?? props.src
-}
-const combinedPictureAttributes = {
-  ...pictureAttributes,
-  style: combinedStyle
-}
----
-
-<PictureComponent
-  {...(componentProps as AstroPictureProps)}
-  class={className}
-  pictureAttributes={{ 'data-astro-lqip': '', ...combinedPictureAttributes }}
-  onload="parentElement.style.setProperty('--z-index', 1), parentElement.style.setProperty('--opacity', 0)"
-/>

package/src/constants/index.ts

@@ -1 +0,0 @@
-export const PREFIX = '[astro-lqip]'

package/src/index.ts

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

package/src/styles/lqip.css

@@ -1,37 +0,0 @@
-[data-astro-lqip] {
-  --opacity: 1;
-  --z-index: 0;
-
-  position: relative;
-  display: inline-block;
-  width: fit-content;
-  height: fit-content;
-}
-
-[data-astro-lqip]::after {
-  content: "";
-  inset: 0;
-  width: 100%;
-  height: 100%;
-  position: absolute;
-  pointer-events: none;
-  transition: opacity 1s;
-  opacity: var(--opacity);
-  z-index: var(--z-index);
-  background: var(--lqip-background);
-  background-size: cover;
-  background-position: 50% 50%;
-}
-
-[data-astro-lqip] img {
-  z-index: 1;
-  position: relative;
-  overflow: hidden;
-}
-
-@media (scripting: none) {
-  [data-astro-lqip] {
-    --opacity: 0;
-    --z-index: 1;
-  }
-}

package/src/types/components-options.type.ts

@@ -1,10 +0,0 @@
-import type { LqipType } from './lqip.type'
-
-export type ComponentsOptions = {
-  src: string | object
-  lqip: LqipType
-  lqipSize: number
-  styleProps: Record<string, string | number | undefined>
-  forbiddenVars: string[]
-  isDevelopment: boolean | undefined
-}

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

@@ -1,4 +0,0 @@
-export type ImagePath = string | { src: string } | Promise<{ default: { src: string } }>
-export type ResolvedImage = { src: string, width?: number, height?: number, [k: string]: unknown }
-export type ImportModule = Record<string, unknown> & { default?: unknown }
-export type GlobMap = Record<string, () => Promise<ImportModule>>

package/src/types/index.ts

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

package/src/types/lqip.type.ts

@@ -1 +0,0 @@
-export type LqipType = 'color' | 'css' | 'base64' | 'svg'

package/src/types/plaiceholder.type.ts

@@ -1,3 +0,0 @@
-import type { GetPlaiceholderReturn } from 'plaiceholder'
-
-export type GetSVGReturn = GetPlaiceholderReturn['svg']

package/src/types/props.type.ts

@@ -1,16 +0,0 @@
-import type { LqipType } from './lqip.type'
-
-export type Props = {
-  /**
-   * LQIP type.
-   * This can be 'color', 'css', 'svg' or 'base64'.
-   * The default value is 'base64'.
-   */
-  lqip?: LqipType
-  /**
-   * Size of the LQIP image in pixels.
-   * This value should be between 4 and 64.
-   * The default value is 4.
-   */
-  lqipSize?: number
-}

package/src/types/svg-node.type.ts

@@ -1,7 +0,0 @@
-export type StyleAttrs = Record<string, string | number>
-
-type SVGNodeAttrs = {
-  style?: StyleAttrs
-} & Record<string, string | number>
-
-export type SVGNode = [string, SVGNodeAttrs, SVGNode[]]

package/src/utils/generateLqip.ts

@@ -1,77 +0,0 @@
-import { readFile } from 'node:fs/promises'
-
-import type { GetSVGReturn, LqipType } from '../types'
-
-import { PREFIX } from '../constants'
-
-import { getPlaiceholder } from 'plaiceholder'
-
-function normalizeFsPath(path: string) {
-  if (process.platform === 'win32' && /^\/[A-Za-z]:\//.test(path)) {
-    return path.slice(1)
-  }
-  return path
-}
-
-function isNode() {
-  return typeof process !== 'undefined' && !!process.versions?.node
-}
-
-async function readIfExists(path: string): Promise<Buffer | undefined> {
-  if (!isNode()) return undefined
-  try {
-    return await readFile(path)
-  } catch {
-    return undefined
-  }
-}
-
-export async function generateLqip(
-  imagePath: string,
-  lqipType: LqipType,
-  lqipSize: number,
-  isDevelopment: boolean | undefined
-) {
-  try {
-    const normalizedPath = normalizeFsPath(imagePath)
-
-    const buffer = await readIfExists(normalizedPath)
-
-    if (!buffer) {
-      console.warn(`${PREFIX} image not found for:`, imagePath)
-      return undefined
-    }
-
-    const plaiceholderResult = await getPlaiceholder(buffer, { size: lqipSize })
-    let lqipValue: string | GetSVGReturn | undefined
-
-    switch (lqipType) {
-      case 'color':
-        lqipValue = plaiceholderResult.color?.hex
-        break
-      case 'css':
-        lqipValue = typeof plaiceholderResult.css === 'object' && plaiceholderResult.css.backgroundImage
-          ? plaiceholderResult.css.backgroundImage
-          : String(plaiceholderResult.css)
-        break
-      case 'svg':
-        lqipValue = plaiceholderResult.svg
-        break
-      case 'base64':
-      default:
-        lqipValue = plaiceholderResult.base64
-        break
-    }
-
-    if (isDevelopment) {
-      console.log(`${PREFIX} LQIP (${lqipType}) successfully generated!`)
-    } else {
-      console.log(`${PREFIX} LQIP (${lqipType}) successfully generated for:`, imagePath)
-    }
-
-    return lqipValue
-  } catch (err) {
-    console.error(`${PREFIX} Error generating LQIP (${lqipType}) in:`, imagePath, '\n', err)
-    return undefined
-  }
-}

package/src/utils/getLqip.ts

@@ -1,189 +0,0 @@
-import { join } from 'node:path'
-import { mkdir, writeFile, unlink, readdir } from 'node:fs/promises'
-import { existsSync, statSync } from 'node:fs'
-
-import type { LqipType } from '../types'
-
-import { generateLqip } from './generateLqip'
-
-import { PREFIX } from '../constants'
-
-function isRemoteUrl(url: string) {
-  return /^https?:\/\//.test(url)
-}
-
-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 })
-  }
-}
-
-function extractOriginalFileName(filename: string) {
-  const file = filename.split('/').pop() || ''
-
-  const match = file.match(HASHED_FILENAME_CAPTURE_REGEX)
-  if (match) return match[1]
-
-  const parts = file.split('.')
-  if (parts.length >= 3) return parts.slice(0, parts.length - 2).join('.')
-
-  return parts[0]
-}
-
-async function recursiveFind(basename: string): Promise<string | undefined> {
-  if (!basename) return
-
-  if (searchCache.has(basename)) {
-    const cached = searchCache.get(basename)
-    return cached || undefined
-  }
-
-  const ignoreDirs = new Set(['node_modules', 'dist', '.astro'])
-
-  async function walk(dir: string): Promise<string | undefined> {
-    let entries: string[]
-
-    try {
-      entries = await readdir(dir)
-    } catch {
-      return
-    }
-
-    for (const entry of entries) {
-      const full = join(dir, entry)
-      let st: ReturnType<typeof statSync>
-
-      try {
-        st = statSync(full)
-      } catch {
-        continue
-      }
-
-      if (st.isDirectory()) {
-        if (ignoreDirs.has(entry)) continue
-        const found = await walk(full)
-        if (found) return found
-      } else {
-        // match by basename and extension
-        if (EXTENSIONS.some((ext) => entry === `${basename}.${ext}`)) {
-          return full
-        }
-      }
-    }
-  }
-
-  for (const rootRel of SEARCH_ROOT) {
-    const rootAbs = join(process.cwd(), rootRel)
-
-    if (existsSync(rootAbs)) {
-      const found = await walk(rootAbs)
-      if (found) {
-        searchCache.set(basename, found)
-        return found
-      }
-    }
-  }
-
-  searchCache.set(basename, null)
-}
-
-export async function getLqip(
-  imagePath: { src: string },
-  lqipType: LqipType,
-  lqipSize: number,
-  isDevelopment: boolean | undefined
-) {
-  if (!imagePath?.src) return undefined
-
-  if (isRemoteUrl(imagePath.src)) {
-    await ensureCacheDir()
-
-    const response = await fetch(imagePath.src)
-    if (!response.ok) return undefined
-
-    const arrayBuffer = await response.arrayBuffer()
-    const buffer = Buffer.from(arrayBuffer)
-    const tempPath = join(CACHE_DIR, `astro-lqip-${Math.random().toString(36).slice(2)}.jpg`)
-    await writeFile(tempPath, buffer)
-
-    try {
-      return await generateLqip(tempPath, lqipType, lqipSize, isDevelopment)
-    } finally {
-      await unlink(tempPath)
-    }
-  }
-
-  if (isDevelopment && imagePath.src.startsWith('/@fs/')) {
-    const filePath = imagePath.src.replace(/^\/@fs/, '').split('?')[0]
-    return await generateLqip(filePath, lqipType, lqipSize, isDevelopment)
-  }
-
-  if (!isDevelopment) {
-    const src = imagePath.src
-    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)
-        }
-      }
-    }
-
-    const fileName = normalizedSrc.split('/').pop() ?? ''
-    if (HASHED_FILENAME_REGEX.test(fileName)) {
-      const originalBase = extractOriginalFileName(normalizedSrc)
-      const originalSource = await recursiveFind(originalBase)
-
-      if (originalSource) {
-        console.log(`${PREFIX} fallback recursive source found:`, originalSource)
-        return await generateLqip(originalSource, lqipType, lqipSize, isDevelopment)
-      } else {
-        console.warn(`${PREFIX} original source not found recursively for basename:`, originalBase)
-      }
-    }
-  }
-
-  return undefined
-}

package/src/utils/getLqipStyle.ts

@@ -1,17 +0,0 @@
-import type { GetSVGReturn, LqipType } from '../types'
-
-export function getLqipStyle(lqipType: LqipType, lqipImage: string | GetSVGReturn | undefined, svgHTML: string = '') {
-  if (!lqipImage) return {}
-
-  switch (lqipType) {
-    case 'css':
-      return { '--lqip-background': lqipImage }
-    case 'svg':
-      return { '--lqip-background': `url('data:image/svg+xml;utf8,${encodeURIComponent(svgHTML)}')` }
-    case 'color':
-      return { '--lqip-background': lqipImage }
-    case 'base64':
-    default:
-      return { '--lqip-background': `url('${lqipImage}')` }
-  }
-}

package/src/utils/renderSVGNode.ts

@@ -1,25 +0,0 @@
-import type { StyleAttrs, SVGNode } from '../types'
-
-function styleToString(style: StyleAttrs) {
-  return Object.entries(style)
-    .map(([key, val]) => `${key.replace(/([A-Z])/g, '-$1').toLowerCase()}:${val}`)
-    .join(';')
-}
-
-export function renderSVGNode([tag, attrs, children = []]: SVGNode): string {
-  let attrString = ''
-
-  for (const [k, v] of Object.entries(attrs || {})) {
-    if (k === 'style' && v && typeof v === 'object') {
-      attrString += ` style="${styleToString(v)}"`
-    } else if (v !== undefined) {
-      attrString += ` ${k}="${v}"`
-    }
-  }
-
-  if (children.length > 0) {
-    return `<${tag}${attrString}>${children.map(renderSVGNode).join('')}</${tag}>`
-  } else {
-    return `<${tag}${attrString} />`
-  }
-}

package/src/utils/resolveImagePath.ts

@@ -1,128 +0,0 @@
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-
-import type { GlobMap, ImagePath, ImportModule, ResolvedImage } from '../types'
-
-import { PREFIX } from '../constants'
-
-const PUBLIC_DIR = join(process.cwd(), 'public')
-
-const globFilesInSrc: GlobMap = ({ ...import.meta.glob('/src/**/*.{png,jpg,jpeg,svg}') } as unknown) as GlobMap
-
-function warnFiles(filePath: string | undefined) {
-  if (!filePath) return
-
-  const lowerPath = filePath.toLowerCase()
-
-  if (lowerPath.includes(`${join('/', 'public')}`) || lowerPath.includes('/public/') || filePath.startsWith(PUBLIC_DIR)) {
-    console.warn(
-      `${PREFIX} Warning: image resolved from /public. Images should not be placed in /public — move them to /src so Astro can process them correctly.`
-    )
-  }
-
-  if (lowerPath.endsWith('.webp') || lowerPath.endsWith('.avif')) {
-    const extension = lowerPath.endsWith('.webp') ? 'webp' : 'avif'
-    console.warn(
-      `${PREFIX} Warning: image is in ${extension} format. These formats are usually already optimized; using this component to re-process them may degrade quality.`
-    )
-  }
-}
-
-function isObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null
-}
-
-function isPromise(v: unknown): v is Promise<unknown> {
-  if (!isObject(v)) return false
-  const promise = v as { then?: unknown }
-  return typeof promise.then === 'function'
-}
-
-function hasSrc(v: unknown): v is ResolvedImage {
-  return isObject(v) && typeof (v as Record<string, unknown>)['src'] === 'string'
-}
-
-function isRemoteUrl(v: string) {
-  return /^https?:\/\//.test(v)
-}
-
-function findGlobMatch(keys: string[], path: string) {
-  const candidates = [path.replace(/^\//, ''), `/${path.replace(/^\//, '')}`]
-  const match = keys.find((k) => candidates.includes(k) || k.endsWith(path) || k.endsWith(path.replace(/^\//, '')))
-  if (match) return match
-
-  const fileName = path.split('/').pop()
-  if (!fileName) return null
-
-  return keys.find((k) => k.endsWith(`/${fileName}`) || k.endsWith(fileName)) ?? null
-}
-
-export async function resolveImagePath(path: ImagePath) {
-  if (path == null) return null
-
-  // validate dynamic import (Promise-like)
-  if (isPromise(path)) {
-    const mod = (await (path as Promise<ImportModule>)) as ImportModule
-    const resolved = (mod.default ?? mod) as unknown
-    if (hasSrc(resolved)) {
-      warnFiles(resolved.src)
-      return resolved
-    }
-    if (typeof resolved === 'string') {
-      warnFiles(resolved)
-      return resolved
-    }
-    return null
-  }
-
-  // validate already-resolved object (import result or { src: ... })
-  if (isObject(path)) {
-    const obj = path as Record<string, unknown>
-    const objSrc = typeof obj['src'] === 'string' ? (obj['src'] as string) : undefined
-    warnFiles(objSrc)
-    return hasSrc(obj) ? (obj as ResolvedImage) : null
-  }
-
-  // validate string path
-  if (typeof path === 'string') {
-    if (isRemoteUrl(path)) return path
-
-    const keys = Object.keys(globFilesInSrc)
-    const matchKey = findGlobMatch(keys, path)
-
-    if (matchKey) {
-      try {
-        const mod = await globFilesInSrc[matchKey]()
-        const resolved = (mod.default ?? mod) as unknown
-
-        if (hasSrc(resolved)) {
-          warnFiles((resolved as ResolvedImage).src)
-          return resolved as ResolvedImage
-        }
-
-        if (typeof resolved === 'string') {
-          warnFiles(resolved)
-          return resolved
-        }
-      } catch (err) {
-        console.log(`${PREFIX} resolveImagePath: failed to import glob match "${matchKey}" — falling back to filesystem.`, err)
-      }
-    }
-
-    // If module doesn't expose a usable value, fall through to filesystem check
-    try {
-      const absCandidate = path.startsWith('/') ? join(process.cwd(), path) : join(process.cwd(), path)
-
-      if (existsSync(absCandidate)) {
-        warnFiles(absCandidate)
-        return { src: `/@fs${absCandidate}` }
-      }
-    } catch (err) {
-      console.debug(`${PREFIX} resolveImagePath: filesystem check failed for "${path}".`, err)
-    }
-
-    return null
-  }
-
-  return null
-}

package/src/utils/useLqipImage.ts

@@ -1,50 +0,0 @@
-import type { ComponentsOptions, ImagePath, SVGNode } from '../types'
-
-import { PREFIX } from '../constants'
-
-import { resolveImagePath } from './resolveImagePath'
-import { renderSVGNode } from './renderSVGNode'
-import { getLqipStyle } from './getLqipStyle'
-import { getLqip } from './getLqip'
-
-export async function useLqipImage({
-  src,
-  lqip = 'base64',
-  lqipSize = 4,
-  styleProps = {},
-  forbiddenVars = ['--lqip-background', '--z-index', '--opacity'],
-  isDevelopment
-}: ComponentsOptions) {
-  // resolve any kind of src (string, alias, import result, dynamic import)
-  const resolved = await resolveImagePath(src as unknown as ImagePath)
-  // resolved may be an object (module-like), { src: '...' } or null
-  const resolvedSrc = resolved ?? null
-
-  let lqipImage
-  if (resolvedSrc) {
-    const lqipInput = typeof resolvedSrc === 'string' ? { src: resolvedSrc } : resolvedSrc
-    lqipImage = await getLqip(lqipInput, lqip, lqipSize, isDevelopment)
-  }
-
-  let svgHTML = ''
-  if (lqip === 'svg' && Array.isArray(lqipImage)) {
-    svgHTML = renderSVGNode(lqipImage as unknown as SVGNode)
-  }
-
-  const lqipStyle = getLqipStyle(lqip, lqipImage, svgHTML)
-
-  for (const key of Object.keys(styleProps)) {
-    if (forbiddenVars.includes(key)) {
-      console.warn(
-        `${PREFIX} The CSS variable “${key}” should not be passed in style because it can override the functionality of LQIP.`
-      )
-    }
-  }
-
-  const combinedStyle = {
-    ...styleProps,
-    ...lqipStyle
-  }
-
-  return { lqipImage, svgHTML, lqipStyle, combinedStyle, resolvedSrc }
-}