metalsmith-optimize-images 0.1.1 → 0.9.3

package/lib/index.js

@@ -1,12 +1,13 @@
 import path from 'path';
+import fs from 'fs';
 import * as mkdirp from 'mkdirp';
-import * as cheerio from 'cheerio';
 import sharp from 'sharp';
-import fs from 'fs';
+import * as cheerio from 'cheerio';
 import crypto from 'crypto';
 
 /**
  * Configuration utility for the plugin
+ * Handles merging user options with sensible defaults
  */
 
 /**
@@ -15,19 +16,33 @@ import crypto from 'crypto';
  * @param {Object} source - Source object
  * @return {Object} - Merged result
  */
-function deepMerge(target, source) {
-  const result = {
-    ...target
-  };
-  for (const key in source) {
-    if (source[key] instanceof Object && key in target && target[key] instanceof Object) {
-      result[key] = deepMerge(target[key], source[key]);
+/*
+function deepMerge( target, source ) {
+  const result = { ...target };
+
+  for ( const key in source ) {
+    if ( source[key] instanceof Object && key in target && target[key] instanceof Object ) {
+      result[key] = deepMerge( target[key], source[key] );
     } else {
       result[key] = source[key];
     }
   }
+
   return result;
 }
+*/
+
+// Modern functional approach to deep merge - handles nested objects properly
+// This is needed for formatOptions and placeholder options which are nested objects
+const deepMerge = (target, source) => Object.keys(source).reduce((acc, key) => {
+  var _source$key;
+  return {
+    ...acc,
+    [key]: ((_source$key = source[key]) == null ? void 0 : _source$key.constructor) === Object ? deepMerge(target[key] || {}, source[key]) : source[key]
+  };
+}, {
+  ...target
+});
 
 /**
  * Builds configuration with sensible defaults
@@ -81,64 +96,99 @@ function buildConfig(options = {}) {
     // Maximum number of images to process in parallel
     concurrency: 5,
     // Whether to generate a metadata JSON file
-    generateMetadata: false
+    generateMetadata: false,
+    // Progressive loading options
+    isProgressive: false,
+    // TODO: Debug timeout issue in tests
+
+    // Placeholder image settings for progressive loading
+    placeholder: {
+      width: 50,
+      quality: 30,
+      blur: 10
+    },
+    // Background image processing settings
+    processUnusedImages: true,
+    // Process images not found in HTML for background use
+    imagePattern: '**/*.{jpg,jpeg,png,gif,webp,avif}' // Pattern to find images for background processing
   };
 
   // Special handling for formatOptions to ensure deep merging
-  if (options.formatOptions) {
+  // This allows users to override specific format settings without losing defaults
+  // e.g., { formatOptions: { jpeg: { quality: 90 } } } only changes JPEG quality
+  if (options && options.formatOptions) {
     options = {
       ...options,
       formatOptions: deepMerge(defaults.formatOptions, options.formatOptions)
     };
   }
 
+  // Special handling for placeholder options to ensure deep merging
+  // Allows partial placeholder config like { placeholder: { width: 100 } }
+  if (options && options.placeholder) {
+    options = {
+      ...options,
+      placeholder: deepMerge(defaults.placeholder, options.placeholder)
+    };
+  }
+
   // Merge the defaults with user options
   return {
     ...defaults,
-    ...options
+    ...(options || {})
   };
 }
 
 /**
  * Utility for generating content hashes
+ * Used for cache-busting - ensures filenames change when image content changes
  */
 
 /**
  * Generates a short hash based on image content
+ * Creates an 8-character hash for cache-busting in filenames
  * @param {Buffer} buffer - The image buffer
- * @return {string} - A short hash string
+ * @return {string} - A short hash string (8 characters)
  */
 function generateHash(buffer) {
-  return crypto.createHash('md5').update(buffer).digest('hex').slice(0, 8);
+  // SHA-256 for cache-busting - using secure algorithm to satisfy security scanners
+  // Only use first 8 characters to keep filenames manageable
+  return crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 8);
 }
 
 /**
  * Path utilities for image variants
+ * Handles the filename pattern system with token replacement
  */
 
 /**
  * Generate variant filename using pattern
+ * Applies token replacement to create output filenames
+ * Tokens: [filename], [width], [format], [hash]
  * @param {string} originalPath - Original image path
  * @param {number} width - Target width
- * @param {string} format - Target format
+ * @param {string} format - Target format ('original' means keep source format)
  * @param {string} hash - Content hash for cache busting
  * @param {object} config - Plugin config options
- * @return {string} - Generated path
+ * @return {string} - Generated path relative to Metalsmith destination
  */
 function generateVariantPath(originalPath, width, format, hash, config) {
   const parsedPath = path.parse(originalPath);
   const originalFormat = parsedPath.ext.slice(1).toLowerCase();
 
-  // If format is 'original', use the source format
+  // If format is 'original', use the source format (e.g., 'jpeg' for image.jpg)
   const outputFormat = format === 'original' ? originalFormat : format;
 
-  // Apply pattern replacements
+  // Apply pattern replacements using the tokens system
+  // Default pattern: '[filename]-[width]w-[hash].[format]'
+  // Results in: 'image-320w-abc12345.webp'
   const outputName = config.outputPattern.replace('[filename]', parsedPath.name).replace('[width]', width).replace('[format]', outputFormat).replace('[hash]', hash || '');
   return path.join(config.outputDir, outputName);
 }
 
 /**
  * Image processing utilities for creating responsive image variants
+ * Handles the core Sharp.js operations for resizing and format conversion
  */
 
 /**
@@ -155,45 +205,58 @@ async function processImageToVariants(buffer, originalPath, debugFn, config) {
   const variants = [];
   const hash = generateHash(buffer);
 
-  // Determine which widths to generate
+  // Determine which widths to generate based on skipLarger setting
+  // If skipLarger is true (default), don't generate sizes larger than original
   const targetWidths = config.skipLarger ? config.widths.filter(w => w <= metadata.width) : config.widths;
   if (targetWidths.length === 0) {
     debugFn(`Skipping ${originalPath} - no valid target widths`);
     return [];
   }
 
-  // Process all widths in parallel
+  // Process all widths in parallel for better performance
   const widthPromises = targetWidths.map(async width => {
-    // Resize image (reused for all formats at this width)
+    // Create a Sharp instance for this width - clone to avoid conflicts
     const resized = image.clone().resize({
       width,
-      withoutEnlargement: config.skipLarger
+      withoutEnlargement: config.skipLarger // Prevents upscaling small images
     });
 
-    // Get dimensions for this width (for dimension attributes)
+    // Get actual dimensions after resize (may be smaller than requested width)
     const resizedMeta = await resized.metadata();
 
     // Process each format in parallel for this width
     const formatPromises = config.formats.map(async format => {
       try {
-        // Skip formats that make no sense (like webp -> original)
+        // Skip problematic format combinations (e.g., webp -> original doesn't make sense)
         if (format === 'original' && metadata.format.toLowerCase() === 'webp') {
           return null;
         }
         let formatted;
         const outputPath = generateVariantPath(originalPath, width, format, hash, config);
 
-        // Apply format-specific processing
+        // Apply format-specific processing with quality/compression settings
         if (format === 'original') {
+          // For 'original' format, use the source image format
           const originalFormat = metadata.format.toLowerCase();
           const formatOptions = config.formatOptions[originalFormat] || {};
           formatted = resized.clone().toFormat(originalFormat, formatOptions);
         } else {
+          // For specific formats (avif, webp, etc.), apply format-specific options
           const formatOptions = config.formatOptions[format] || {};
-          formatted = resized.clone()[format](formatOptions);
+          if (format === 'avif') {
+            formatted = resized.clone().avif(formatOptions);
+          } else if (format === 'webp') {
+            formatted = resized.clone().webp(formatOptions);
+          } else if (format === 'jpeg') {
+            formatted = resized.clone().jpeg(formatOptions);
+          } else if (format === 'png') {
+            formatted = resized.clone().png(formatOptions);
+          } else {
+            formatted = resized.clone()[format](formatOptions);
+          }
         }
 
-        // Generate the image buffer
+        // Generate the actual image buffer - this is where compression happens
         const formatBuffer = await formatted.toBuffer();
         return {
           path: outputPath,
@@ -252,10 +315,11 @@ async function processImage({
   }
 
   // Normalize src path to match Metalsmith files object keys
-  // Remove leading slash if present
+  // Remove leading slash if present (HTML paths vs Metalsmith file keys)
   const normalizedSrc = src.startsWith('/') ? src.slice(1) : src;
 
-  // Image not in files, try to load it from the build directory
+  // Image not in Metalsmith files object - try to load it from the build directory
+  // This handles cases where images were copied by other plugins (like assets)
   if (!files[normalizedSrc]) {
     try {
       const destination = metalsmith.destination();
@@ -264,10 +328,10 @@ async function processImage({
         // Load the image contents from the build directory
         const imageBuffer = fs.readFileSync(imagePath);
 
-        // Get modification time for cache busting
+        // Get modification time for cache busting - this helps with incremental builds
         const mtime = fs.statSync(imagePath).mtimeMs;
 
-        // Add it to files so the plugin can process it
+        // Add it to Metalsmith files so the plugin can process it
         files[normalizedSrc] = {
           contents: imageBuffer,
           mtime
@@ -283,10 +347,11 @@ async function processImage({
   }
 
   // Create a cache key that includes the file path and modification time
+  // This prevents reprocessing the same image multiple times in a single build
   const fileMtime = files[normalizedSrc].mtime || Date.now();
   const cacheKey = `${normalizedSrc}:${fileMtime}`;
 
-  // Check if we've already processed this image
+  // Check if we've already processed this exact image (same file + mtime)
   if (processedImages.has(cacheKey)) {
     debug(`Using cached variants for ${normalizedSrc}`);
     const variants = processedImages.get(cacheKey);
@@ -295,28 +360,394 @@ async function processImage({
   }
   debug(`Processing image: ${normalizedSrc}`);
   try {
-    // Process image to generate variants
+    // Process image to generate all variants (different sizes and formats)
     const variants = await processImageToVariants(files[normalizedSrc].contents, normalizedSrc, debug, config);
 
-    // Save variants to Metalsmith files
+    // Save all generated variants to Metalsmith files object
+    // This makes them available in the final build output
     variants.forEach(variant => {
       files[variant.path] = {
         contents: variant.buffer
       };
     });
 
-    // Cache variants for this image
+    // Cache variants for this image to avoid reprocessing
     processedImages.set(cacheKey, variants);
 
-    // Replace img with picture element
+    // Replace the original <img> tag with a responsive <picture> element
     replacePictureElement($, $img, variants, config);
   } catch (err) {
     debug(`Error processing image: ${err.message}`);
   }
 }
 
+/**
+ * Progressive image loading processor
+ * Handles placeholder generation and smooth loading transitions
+ */
+
+/**
+ * Generate placeholder image for progressive loading
+ * Creates a small, blurred, low-quality version for instant display
+ * @param {string} imagePath - Original image path
+ * @param {Buffer} imageBuffer - Original image buffer
+ * @param {Object} placeholderConfig - Placeholder configuration (width, quality, blur)
+ * @param {Object} metalsmith - Metalsmith instance
+ * @return {Promise<Object>} Placeholder data with path and contents
+ */
+async function generatePlaceholder(imagePath, imageBuffer, placeholderConfig, metalsmith) {
+  const {
+    width,
+    quality,
+    blur
+  } = placeholderConfig;
+  try {
+    // Get original image dimensions for aspect ratio calculation
+    const image = sharp(imageBuffer);
+    const metadata = await image.metadata();
+
+    // Process image: resize to small width, blur heavily, compress heavily
+    const processed = await image.resize(width) // Default: 50px wide
+    .blur(blur) // Default: 10px blur
+    .jpeg({
+      quality
+    }) // Default: 30% quality
+    .toBuffer();
+    const fileName = `${path.basename(imagePath, path.extname(imagePath))}-placeholder.jpg`;
+    const outputPath = path.join('assets/images/responsive', fileName);
+    return {
+      path: outputPath,
+      contents: processed,
+      fileName,
+      originalWidth: metadata.width,
+      originalHeight: metadata.height
+    };
+  } catch (error) {
+    metalsmith.debug('metalsmith-optimize-images')(`Error generating placeholder for ${imagePath}: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Create progressive wrapper HTML structure
+ * Creates a container with both placeholder and high-res images for smooth transitions
+ * @param {Object} $ - Cheerio instance
+ * @param {Object} $img - Original img element
+ * @param {Array} variants - Generated image variants
+ * @param {Object} placeholderData - Placeholder image data
+ * @param {Object} config - Plugin configuration
+ * @return {Object} Cheerio element for progressive wrapper
+ */
+function createProgressiveWrapper($, $img, variants, placeholderData, _config) {
+  // Get original attributes
+  const alt = $img.attr('alt') || '';
+  const className = $img.attr('class') || '';
+
+  // Group variants by format - use only original format for progressive mode
+  // Progressive mode focuses on smooth loading rather than format optimization
+  const variantsByFormat = {};
+  variants.forEach(v => {
+    if (!variantsByFormat[v.format]) {
+      variantsByFormat[v.format] = [];
+    }
+    variantsByFormat[v.format].push(v);
+  });
+
+  // Get original format variants (skip AVIF/WebP for progressive mode)
+  // JavaScript will handle format detection dynamically
+  const originalFormat = Object.keys(variantsByFormat).find(f => f !== 'avif' && f !== 'webp');
+  const originalVariants = originalFormat ? variantsByFormat[originalFormat] : [];
+  if (originalVariants.length === 0) {
+    return $img.clone(); // Fallback if no variants
+  }
+
+  // Calculate aspect ratio using original image dimensions to prevent layout shift
+  // Fallback to variant dimensions if placeholderData doesn't have original dimensions
+  let aspectRatio;
+  if (placeholderData.originalWidth && placeholderData.originalHeight) {
+    aspectRatio = `${placeholderData.originalWidth}/${placeholderData.originalHeight}`;
+  } else {
+    // Fallback: use the largest variant for most accurate aspect ratio
+    const largestVariant = [...originalVariants].sort((a, b) => b.width - a.width)[0];
+    aspectRatio = `${largestVariant.width}/${largestVariant.height}`;
+  }
+
+  // Find middle-sized variant for high-res image (good balance of quality/size)
+  const highResVariant = originalVariants[Math.floor(originalVariants.length / 2)];
+
+  // Create wrapper div with modern CSS aspect-ratio
+  const $wrapper = $('<div>').addClass('responsive-wrapper js-progressive-image-wrapper').attr('style', `aspect-ratio: ${aspectRatio}`);
+
+  // Add class from original image if present
+  if (className) {
+    $wrapper.addClass(className);
+  }
+
+  // Create low-res image (placeholder) - shown immediately
+  const $lowRes = $('<img>').addClass('low-res').attr('src', `/${placeholderData.path}`).attr('alt', alt);
+
+  // Create high-res image (empty with data source) - loaded by JavaScript
+  const $highRes = $('<img>').addClass('high-res').attr('src', '').attr('alt', alt).attr('data-source', `/${highResVariant.path}`);
+
+  // Assemble the progressive wrapper
+  $lowRes.appendTo($wrapper);
+  $highRes.appendTo($wrapper);
+  return $wrapper;
+}
+
+/**
+ * Create standard picture element HTML
+ * Fallback function for when progressive loading fails
+ * @param {Object} $ - Cheerio instance
+ * @param {Object} $img - Original img element
+ * @param {Array} variants - Generated image variants
+ * @param {Object} config - Plugin configuration
+ * @return {Object} Cheerio element for picture
+ */
+function createStandardPicture($, $img, variants, config) {
+  // Get original attributes
+  const src = $img.attr('src');
+  const alt = $img.attr('alt') || '';
+  const className = $img.attr('class') || '';
+  const sizesAttr = $img.attr('sizes') || config.sizes;
+
+  // Group variants by format
+  const variantsByFormat = {};
+  variants.forEach(v => {
+    if (!variantsByFormat[v.format]) {
+      variantsByFormat[v.format] = [];
+    }
+    variantsByFormat[v.format].push(v);
+  });
+
+  // Create picture element with all formats (standard mode)
+  const $picture = $('<picture>');
+
+  // Add format-specific source elements in preference order
+  ['avif', 'webp'].forEach(format => {
+    const formatVariants = variantsByFormat[format];
+    if (!formatVariants || formatVariants.length === 0) {
+      return;
+    }
+
+    // Sort variants by width
+    formatVariants.sort((a, b) => a.width - b.width);
+
+    // Create srcset string
+    const srcset = formatVariants.map(v => `/${v.path} ${v.width}w`).join(', ');
+
+    // Create source element
+    $('<source>').attr('type', `image/${format}`).attr('srcset', srcset).attr('sizes', sizesAttr).appendTo($picture);
+  });
+
+  // Add original format as img element
+  const originalFormat = Object.keys(variantsByFormat).find(f => f !== 'avif' && f !== 'webp');
+  if (originalFormat && variantsByFormat[originalFormat]) {
+    var _formatVariants$Math$;
+    const formatVariants = variantsByFormat[originalFormat];
+    formatVariants.sort((a, b) => a.width - b.width);
+    const srcset = formatVariants.map(v => `/${v.path} ${v.width}w`).join(', ');
+    const defaultSrc = (_formatVariants$Math$ = formatVariants[Math.floor(formatVariants.length / 2)]) == null ? void 0 : _formatVariants$Math$.path;
+
+    // Create new img element
+    const $newImg = $('<img>').attr('src', defaultSrc ? `/${defaultSrc}` : src).attr('srcset', srcset).attr('sizes', sizesAttr).attr('alt', alt).attr('loading', 'lazy');
+
+    // Add class if present
+    if (className) {
+      $newImg.attr('class', className);
+    }
+
+    // Add width/height attributes if configured and available
+    if (config.dimensionAttributes && variants.length > 0) {
+      const largestVariant = [...variants].sort((a, b) => b.width - a.width)[0];
+      $newImg.attr('width', largestVariant.width);
+      $newImg.attr('height', largestVariant.height);
+    }
+    $newImg.appendTo($picture);
+  }
+  return $picture;
+}
+
+/**
+ * Progressive image loader JavaScript
+ * Handles intersection observer, format detection, and smooth loading transitions
+ */
+const progressiveImageLoader = `
+(function() {
+  'use strict';
+  
+  // Cache for detected format support
+  let bestFormat = null;
+  
+  // Main function called when images enter the viewport
+  const loadImage = function(entries, observer) {
+    for (let entry of entries) {
+      if (entry.isIntersecting) {
+        const thisWrapper = entry.target;
+        
+        // Find the high res image in the wrapper
+        const thisImage = thisWrapper.querySelector('.high-res');
+        const thisImageSource = thisImage.dataset.source;
+        
+        if (!thisImageSource) {
+          console.warn('No data-source found for high-res image');
+          return;
+        }
+        
+        // Apply format based on detected support
+        let finalImageSource = thisImageSource;
+        
+        if (bestFormat === 'avif') {
+          finalImageSource = thisImageSource.replace(/\.(jpg|jpeg|png)$/i, '.avif');
+        } else if (bestFormat === 'webp') {
+          finalImageSource = thisImageSource.replace(/\.(jpg|jpeg|png)$/i, '.webp');
+        }
+        // If 'original' or null, use original (no change needed)
+        
+        thisImage.src = finalImageSource;
+        
+        // Take this image off the observe list to prevent duplicate loading
+        observer.unobserve(thisWrapper);
+        
+        // Once the hi-res image has been loaded, add done class to trigger CSS transition
+        thisImage.onload = function() {
+          thisWrapper.classList.add('done');
+        };
+        
+        // Handle loading errors gracefully
+        thisImage.onerror = function() {
+          thisWrapper.classList.add('error');
+        };
+      }
+    }
+  };
+
+  const init = async function() {
+    // Detect best supported format first
+    bestFormat = await detectBestFormat();
+    
+    // Check for Intersection Observer support (not available in older browsers)
+    if (!('IntersectionObserver' in window)) {
+      // Fallback: load all images immediately for older browsers
+      document.querySelectorAll('.js-progressive-image-wrapper').forEach(function(wrapper) {
+        const img = wrapper.querySelector('.high-res');
+        if (img && img.dataset.source) {
+          let finalImageSource = img.dataset.source;
+          
+          // Apply detected format for fallback
+          if (bestFormat === 'avif') {
+            finalImageSource = img.dataset.source.replace(/\.(jpg|jpeg|png)$/i, '.avif');
+          } else if (bestFormat === 'webp') {
+            finalImageSource = img.dataset.source.replace(/\.(jpg|jpeg|png)$/i, '.webp');
+          }
+          
+          img.src = finalImageSource;
+          wrapper.classList.add('done');
+        }
+      });
+      return;
+    }
+
+    // Create intersection observer with 50px margin (loads images slightly before they're visible)
+    const observer = new IntersectionObserver(loadImage, {
+      rootMargin: '50px'
+    });
+    
+    // Loop over all image wrappers and add to intersection observer
+    const allImageWrappers = document.querySelectorAll('.js-progressive-image-wrapper');
+    for (let imageWrapper of allImageWrappers) {
+      observer.observe(imageWrapper);
+    }
+  };
+  
+  // Format detection using createImageBitmap - more reliable than canvas encoding
+  async function detectBestFormat() {
+    const fallbackFormat = 'original';
+    
+    if (!window.createImageBitmap) return fallbackFormat;
+    
+    const avifData = 'data:image/avif;base64,AAAAIGZ0eXBhdmlmAAAAAGF2aWZtaWYxbWlhZk1BMUEAAADybWV0YQAAAAAAAAAoaGRscgAAAAAAAAAAcGljdAAAAAAAAAAAAAAAAGxpYmF2aWYAAAAADnBpdG0AAAAAAAEAAAAeaWxvYwAAAABEAAABAAEAAAABAAABGgAAABYAAAAoaWluZgAAAAAAAQAAABppbmZlAgAAAAABAABhdjAxQ29sb3IAAAAAamlwcnAAAABLaXBjbwAAABRpc3BlAAAAAAAAAAEAAAABAAAAEHBpeGkAAAAAAwgICAAAAAxhdjFDgSAAAAAAABNjb2xybmNseAACAAIABoAAAAAXaXBtYQAAAAAAAAABAAEEAQKDBAAAAB5tZGF0EgAKBzgADlAgIGkyCR/wAABAAACvcA==';
+    const webpData = 'data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoCAAEAAQAcJaQAA3AA/v3AgAA=';
+    
+    try {
+      const avifBlob = await fetch(avifData).then(r => r.blob());
+      await createImageBitmap(avifBlob);
+      return 'avif';
+    } catch {
+      try {
+        const webpBlob = await fetch(webpData).then(r => r.blob());
+        await createImageBitmap(webpBlob);
+        return 'webp';
+      } catch {
+        return fallbackFormat;
+      }
+    }
+  }
+
+  // Initialize when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+
+})();
+`;
+
+/**
+ * Progressive image CSS styles
+ * Handles aspect ratio, positioning, and smooth transitions between placeholder and high-res images
+ */
+const progressiveImageCSS = `
+.responsive-wrapper {
+  position: relative;
+  overflow: hidden;
+  background-color: #f0f0f0;
+}
+
+.responsive-wrapper .low-res {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: opacity 0.4s ease;
+}
+
+.responsive-wrapper .high-res {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  opacity: 0;
+  transition: opacity 0.4s ease;
+}
+
+.responsive-wrapper.done .high-res {
+  opacity: 1;
+}
+
+.responsive-wrapper.done .low-res {
+  opacity: 0;
+}
+
+.responsive-wrapper.error .low-res {
+  filter: none;
+}
+
+/* Ensure images are responsive */
+.responsive-wrapper img {
+  max-width: 100%;
+  height: auto;
+}
+`;
+
 /**
  * HTML processing utilities for replacing img tags with responsive picture elements
+ * Handles both standard and progressive loading modes
  */
 
 /**
@@ -337,7 +768,7 @@ function replacePictureElement($, $img, variants, config) {
   const className = $img.attr('class') || '';
   const sizesAttr = $img.attr('sizes') || config.sizes;
 
-  // Group variants by format
+  // Group variants by format for creating <source> elements
   const variantsByFormat = {};
   variants.forEach(v => {
     if (!variantsByFormat[v.format]) {
@@ -346,12 +777,13 @@ function replacePictureElement($, $img, variants, config) {
     variantsByFormat[v.format].push(v);
   });
 
-  // Create picture element
+  // Create picture element that will contain all formats
   const $picture = $('<picture>');
 
-  // Add format-specific source elements in preference order
+  // Add format-specific source elements in preference order (avif, webp, then original)
+  // Browser will use the first format it supports
   config.formats.forEach(format => {
-    // Skip 'original' placeholder
+    // Skip 'original' placeholder - it's handled separately
     if (format === 'original') {
       return;
     }
@@ -360,17 +792,17 @@ function replacePictureElement($, $img, variants, config) {
       return;
     }
 
-    // Sort variants by width
+    // Sort variants by width for proper srcset ordering
     formatVariants.sort((a, b) => a.width - b.width);
 
-    // Create srcset string
+    // Create srcset string: "path 320w, path 640w, path 960w"
     const srcset = formatVariants.map(v => `/${v.path} ${v.width}w`).join(', ');
 
-    // Create source element
+    // Create source element with format type and srcset
     $('<source>').attr('type', `image/${format}`).attr('srcset', srcset).attr('sizes', sizesAttr).appendTo($picture);
   });
 
-  // Add original format as last source
+  // Add original format as last source (fallback for browsers that don't support modern formats)
   const originalFormat = Object.keys(variantsByFormat).find(f => f !== 'avif' && f !== 'webp');
   if (originalFormat && variantsByFormat[originalFormat]) {
     const formatVariants = variantsByFormat[originalFormat];
@@ -379,29 +811,29 @@ function replacePictureElement($, $img, variants, config) {
     $('<source>').attr('type', `image/${originalFormat}`).attr('srcset', srcset).attr('sizes', sizesAttr).appendTo($picture);
   }
 
-  // Create new img element
-  const $newImg = $('<img>').attr('src', src) // Keep original as fallback
+  // Create new img element that serves as the final fallback
+  const $newImg = $('<img>').attr('src', src) // Keep original as fallback for very old browsers
   .attr('alt', alt);
 
-  // Add class if present
+  // Preserve original class attribute if present
   if (className) {
     $newImg.attr('class', className);
   }
 
-  // Add lazy loading if configured
+  // Add native lazy loading if configured (improves performance)
   if (config.lazy) {
     $newImg.attr('loading', 'lazy');
   }
 
-  // Add width/height attributes if configured and available
+  // Add width/height attributes to prevent layout shift (CLS)
   if (config.dimensionAttributes && variants.length > 0) {
-    // Use the largest variant as reference
+    // Use the largest variant as reference for dimensions
     const largestVariant = [...variants].sort((a, b) => b.width - a.width)[0];
     $newImg.attr('width', largestVariant.width);
     $newImg.attr('height', largestVariant.height);
   }
 
-  // Copy any other attributes from original img
+  // Copy any other attributes from original img (except ones we handle specially)
   for (const attrib in $img[0].attribs) {
     if (!['src', 'alt', 'class', 'width', 'height', 'sizes'].includes(attrib)) {
       $newImg.attr(attrib, $img.attr(attrib));
@@ -433,7 +865,7 @@ async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedI
   // Parse HTML
   const $ = cheerio.load(content);
 
-  // Find all images matching our selector
+  // Find all images matching our selector (default: img:not([data-no-responsive]))
   const images = $(config.imgSelector);
   if (images.length === 0) {
     debug(`No images found in ${htmlFile}`);
@@ -441,16 +873,24 @@ async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedI
   }
   debug(`Found ${images.length} images in ${htmlFile}`);
 
-  // Process images in parallel with a concurrency limit
+  // Process images in parallel with a concurrency limit to prevent overwhelming the system
   const imageChunks = [];
   for (let i = 0; i < images.length; i += config.concurrency) {
     imageChunks.push(Array.from(images).slice(i, i + config.concurrency));
   }
 
-  // Process all chunks in parallel
+  // Process all chunks in parallel - each chunk processes its images in parallel
   await Promise.all(imageChunks.map(async imageChunk => {
     // Process images within each chunk in parallel
-    await Promise.all(imageChunk.map(img => processImage({
+    await Promise.all(imageChunk.map(img => config.isProgressive ? processProgressiveImage({
+      $,
+      img,
+      files,
+      metalsmith,
+      processedImages,
+      debug,
+      config
+    }) : processImage({
       $,
       img,
       files,
@@ -462,20 +902,31 @@ async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedI
     })));
   }));
 
-  // Update file contents with modified HTML
+  // Inject progressive loading CSS and JavaScript if needed
+  if (config.isProgressive) {
+    injectProgressiveAssets($);
+  }
+
+  // Update file contents with modified HTML (converts back to Buffer)
   fileData.contents = Buffer.from($.html());
 }
 
 /**
  * Generate metadata file if configured
+ * Creates a JSON manifest with information about all processed images
+ * Useful for debugging or integration with other tools
  * @param {Map} processedImages - Cache of processed images
  * @param {Object} files - Metalsmith files object
  * @param {Object} config - Plugin configuration
  */
 function generateMetadata(processedImages, files, config) {
   const metadataObj = {};
-  processedImages.forEach((variants, key) => {
+  processedImages.forEach((value, key) => {
+    // Extract the original path from the cache key (path:mtime)
     const [path] = key.split(':');
+
+    // Handle both array format (from background processing) and object format (from HTML processing)
+    const variants = Array.isArray(value) ? value : value.variants;
     metadataObj[path] = variants.map(v => ({
       path: v.path,
       width: v.width,
@@ -490,9 +941,148 @@ function generateMetadata(processedImages, files, config) {
   };
 }
 
+/**
+ * Process a single image with progressive loading
+ * Creates low-quality placeholders and high-resolution images with smooth transitions
+ * @param {Object} context - Processing context
+ * @return {Promise<void>} - Promise that resolves when the image is processed
+ */
+async function processProgressiveImage({
+  $,
+  img,
+  files,
+  metalsmith,
+  processedImages,
+  debug,
+  config
+}) {
+  const $img = $(img);
+  const src = $img.attr('src');
+  debug(`Starting progressive processing for: ${src}`);
+  if (!src || src.startsWith('http') || src.startsWith('data:')) {
+    debug(`Skipping external or data URL: ${src}`);
+    return;
+  }
+
+  // Normalize src path to match Metalsmith files object keys
+  const normalizedSrc = src.startsWith('/') ? src.slice(1) : src;
+
+  // Image not in files, try to load it from the build directory (same logic as processImage)
+  if (!files[normalizedSrc]) {
+    try {
+      const destination = metalsmith.destination();
+      const imagePath = path.join(destination, normalizedSrc);
+      if (fs.existsSync(imagePath)) {
+        // Load the image contents from the build directory
+        const imageBuffer = fs.readFileSync(imagePath);
+
+        // Get modification time for cache busting
+        const mtime = fs.statSync(imagePath).mtimeMs;
+
+        // Add it to files so the plugin can process it
+        files[normalizedSrc] = {
+          contents: imageBuffer,
+          mtime
+        };
+      } else {
+        debug(`Image not found in build: ${normalizedSrc}`);
+        return;
+      }
+    } catch (err) {
+      debug(`Error processing image from build directory: ${err.message}`);
+      return;
+    }
+  }
+
+  // Create a cache key
+  const fileMtime = files[normalizedSrc].mtime || Date.now();
+  const cacheKey = `${normalizedSrc}:${fileMtime}`;
+
+  // Check if we've already processed this image
+  if (processedImages.has(cacheKey)) {
+    debug(`Using cached variants for ${normalizedSrc}`);
+    const {
+      variants,
+      placeholderData
+    } = processedImages.get(cacheKey);
+    const $wrapper = createProgressiveWrapper($, $img, variants, placeholderData);
+    $img.replaceWith($wrapper);
+    return;
+  }
+  debug(`Processing progressive image: ${normalizedSrc}`);
+  try {
+    // Process image to generate all variants (sizes and formats)
+    const variants = await processImageToVariants(files[normalizedSrc].contents, normalizedSrc, debug, config);
+
+    // Generate low-quality placeholder image for smooth loading transitions
+    const placeholderData = await generatePlaceholder(normalizedSrc, files[normalizedSrc].contents, config.placeholder, metalsmith);
+
+    // Save all variants to Metalsmith files
+    variants.forEach(variant => {
+      files[variant.path] = {
+        contents: variant.buffer
+      };
+    });
+
+    // Save placeholder to files
+    files[placeholderData.path] = {
+      contents: placeholderData.contents
+    };
+
+    // Cache variants and placeholder for this image
+    processedImages.set(cacheKey, {
+      variants,
+      placeholderData
+    });
+
+    // Create progressive wrapper with placeholder and high-res image
+    const $wrapper = createProgressiveWrapper($, $img, variants, placeholderData, config);
+    $img.replaceWith($wrapper);
+  } catch (err) {
+    debug(`Error processing progressive image: ${err.message}`);
+
+    // Fallback to standard processing if progressive loading fails
+    try {
+      const variants = await processImageToVariants(files[normalizedSrc].contents, normalizedSrc, debug, config);
+      variants.forEach(variant => {
+        files[variant.path] = {
+          contents: variant.buffer
+        };
+      });
+      const $picture = createStandardPicture($, $img, variants, config);
+      $img.replaceWith($picture);
+    } catch (fallbackErr) {
+      debug(`Fallback processing also failed: ${fallbackErr.message}`);
+    }
+  }
+}
+
+/**
+ * Inject progressive loading CSS and JavaScript assets
+ * Only injects if progressive images are actually present on the page
+ * @param {Object} $ - Cheerio instance
+ */
+function injectProgressiveAssets($) {
+  // Check if progressive images exist on this page
+  const hasProgressiveImages = $('.js-progressive-image-wrapper').length > 0;
+  if (!hasProgressiveImages) {
+    return;
+  }
+
+  // Inject CSS styles for progressive loading (only once per page)
+  if (!$('#progressive-image-styles').length) {
+    $('head').append(`<style id="progressive-image-styles">${progressiveImageCSS}</style>`);
+  }
+
+  // Inject JavaScript for intersection observer and loading logic (only once per page)
+  if (!$('#progressive-image-loader').length) {
+    $('body').append(`<script id="progressive-image-loader">${progressiveImageLoader}</script>`);
+  }
+}
+
 /**
  * Metalsmith plugin for generating responsive images with optimal formats
- * @module metalsmith-responsive-images
+ * @module metalsmith-optimize-images
  */
 
 /**
@@ -517,9 +1107,17 @@ function generateMetadata(processedImages, files, config) {
  * @param {string} [options.sizes] - Default sizes attribute
  * @param {number} [options.concurrency] - Maximum number of images to process in parallel
  * @param {boolean} [options.generateMetadata] - Whether to generate a metadata JSON file
+ * @param {boolean} [options.isProgressive] - Whether to use progressive image loading (default: true)
+ * @param {Object} [options.placeholder] - Placeholder image settings for progressive loading
+ * @param {number} [options.placeholder.width] - Placeholder image width (default: 50)
+ * @param {number} [options.placeholder.quality] - Placeholder image quality (default: 30)
+ * @param {number} [options.placeholder.blur] - Placeholder image blur amount (default: 10)
+ * @param {boolean} [options.processUnusedImages] - Whether to process unused images for background use (default: true)
+ * @param {string} [options.imagePattern] - Glob pattern to find images for background processing (default: `**\/*.{jpg,jpeg,png,gif,webp,avif}`)
+ * @param {string} [options.imageFolder] - Folder to scan for background images, relative to source (default: 'lib/assets/images')
  * @return {Function} - Metalsmith plugin function
  */
-function responsiveImagesPlugin(options = {}) {
+function optimizeImagesPlugin(options = {}) {
   // Build configuration with defaults and user options
   const config = buildConfig(options);
 
@@ -530,42 +1128,66 @@ function responsiveImagesPlugin(options = {}) {
    * @param {Function} done - Callback function
    * @return {void}
    */
-  return async function responsiveImages(files, metalsmith, done) {
+  return async function optimizeImages(files, metalsmith, done) {
     try {
       const destination = metalsmith.destination();
       const outputPath = path.join(destination, config.outputDir);
 
-      // Set up debug function
-      const debug = metalsmith.debug('metalsmith-responsive-images');
+      // Set up debug function for logging (uses 'DEBUG=metalsmith-optimize-images*' env var)
+      const debug = metalsmith.debug('metalsmith-optimize-images');
 
-      // Create output directory
+      // Ensure the output directory exists where processed images will be saved
       mkdirp.mkdirpSync(outputPath);
 
-      // Find all HTML files
-      const htmlFiles = Object.keys(files).filter(file => metalsmith.match(config.htmlPattern, file));
+      // Find all HTML files that match the pattern (default: **/*.html)
+      // Also ensure they actually end with .html to avoid processing CSS/JS files
+      const htmlFiles = Object.keys(files).filter(file => {
+        // Must match the HTML pattern
+        if (!metalsmith.match(config.htmlPattern, file)) {
+          return false;
+        }
+
+        // Must actually be an HTML file
+        if (!file.endsWith('.html')) {
+          return false;
+        }
+        return true;
+      });
       if (htmlFiles.length === 0) {
         debug('No HTML files found');
         return done();
       }
 
-      // Track all generated images to avoid duplicate processing
+      // Cache to avoid re-processing identical images across different HTML files
+      // Key: "filepath:mtime", Value: array of processed image variants
       const processedImages = new Map();
 
-      // Process HTML files in parallel with a concurrency limit
+      // Chunk HTML files to respect concurrency limit (default: 5)
+      // This prevents overwhelming the system with too many parallel operations
       const chunks = [];
       for (let i = 0; i < htmlFiles.length; i += config.concurrency) {
         chunks.push(htmlFiles.slice(i, i + config.concurrency));
       }
 
-      // Process all chunks in parallel
+      // Process all chunks in parallel - each chunk processes its files in parallel
+      // This creates a two-level parallelism: chunk-level and file-level within chunks
       await Promise.all(chunks.map(async chunk => {
         // Process files within each chunk in parallel
         await Promise.all(chunk.map(async htmlFile => {
+          // This function parses HTML, finds images, processes them, and updates the HTML
           await processHtmlFile(htmlFile, files[htmlFile], files, metalsmith, processedImages, debug, config);
         }));
       }));
 
-      // Generate metadata file if requested
+      // Process unused images for background image support
+      // This finds images that weren't processed during HTML scanning and creates variants
+      // for use in CSS background-image with image-set()
+      if (config.processUnusedImages) {
+        await processUnusedImages(files, metalsmith, processedImages, debug, config);
+      }
+
+      // Optional: Generate a JSON metadata file with information about all processed images
+      // Useful for debugging or integration with other tools
       if (config.generateMetadata) {
         generateMetadata(processedImages, files, config);
       }
@@ -579,5 +1201,345 @@ function responsiveImagesPlugin(options = {}) {
   };
 }
 
-export { responsiveImagesPlugin as default };
+/**
+ * Process unused images for background image support
+ * Finds images that weren't processed during HTML scanning and creates 1x/2x variants
+ * for use in CSS background-image with image-set()
+ * @param {Object} files - Metalsmith files object
+ * @param {Object} metalsmith - Metalsmith instance
+ * @param {Map} processedImages - Cache of already processed images
+ * @param {Function} debug - Debug function
+ * @param {Object} config - Plugin configuration
+ * @return {Promise<void>} - Promise that resolves when processing is complete
+ */
+async function processUnusedImages(files, metalsmith, processedImages, debug, config) {
+  debug('Processing unused images for background image support');
+
+  // Get all image paths that were already processed during HTML scanning
+  const processedImagePaths = new Set();
+  processedImages.forEach((_variants, cacheKey) => {
+    const [imagePath] = cacheKey.split(':');
+    processedImagePaths.add(imagePath);
+  });
+  debug(`Processed image paths from HTML: ${Array.from(processedImagePaths).join(', ')}`);
+
+  // Find images that weren't processed during HTML scanning using hybrid approach
+  const allBackgroundImages = await findUnprocessedImages(files, metalsmith, config, processedImagePaths, debug);
+  debug(`Background images found to process: ${allBackgroundImages.map(img => img.path).join(', ')}`);
+  if (allBackgroundImages.length === 0) {
+    debug('No unused images found to process');
+    return;
+  }
+  debug(`Found ${allBackgroundImages.length} unused images to process for background use`);
+
+  // Process background images in parallel for better performance
+  await Promise.all(allBackgroundImages.map(async imageObj => {
+    try {
+      debug(`Processing background image: ${imageObj.path} (source: ${imageObj.source})`);
+
+      // Generate background variants with original size and half size
+      const variants = await processBackgroundImageVariants(imageObj.buffer, imageObj.path, debug, config);
+
+      // Save all generated variants to Metalsmith files object
+      variants.forEach(variant => {
+        files[variant.path] = {
+          contents: variant.buffer
+        };
+      });
+
+      // Cache the variants (using current timestamp as mtime for unused images)
+      const cacheKey = `${imageObj.path}:${Date.now()}`;
+      processedImages.set(cacheKey, variants);
+      debug(`Generated ${variants.length} background variants for ${imageObj.path}`);
+    } catch (err) {
+      debug(`Error processing background image ${imageObj.path}: ${err.message}`);
+    }
+  }));
+  debug('Background image processing complete');
+}
+
+/**
+ * Find images that weren't processed during HTML scanning
+ * Uses a hybrid approach: scans filesystem first, then falls back to Metalsmith files object
+ * @param {Object} files - Metalsmith files object
+ * @param {Object} metalsmith - Metalsmith instance
+ * @param {Object} config - Plugin configuration
+ * @param {Set} processedImagePaths - Set of already processed image paths
+ * @param {Function} debug - Debug function
+ * @return {Promise<Array>} - Array of unprocessed image objects with {path, buffer}
+ */
+async function findUnprocessedImages(files, metalsmith, config, processedImagePaths, debug) {
+  const unprocessedImages = [];
+  const sourceImagesDir = path.join(metalsmith.source(), 'lib/assets/images');
+  debug(`Looking for unprocessed images using hybrid approach`);
+
+  // Method 1: Scan filesystem (for real testbed scenario)
+  try {
+    debug(`Attempting to scan source directory: ${sourceImagesDir}`);
+    debug(`Source directory exists: ${fs.existsSync(sourceImagesDir)}`);
+    debug(`Metalsmith source: ${metalsmith.source()}`);
+    debug(`Metalsmith destination: ${metalsmith.destination()}`);
+    if (fs.existsSync(sourceImagesDir)) {
+      debug(`Scanning source directory: ${sourceImagesDir}`);
+      const scanDirectory = (dir, relativePath = '') => {
+        const items = fs.readdirSync(dir);
+        debug(`Found ${items.length} items in ${dir}`);
+        for (const item of items) {
+          if (item === '.DS_Store') {
+            continue;
+          }
+          const fullPath = path.join(dir, item);
+          const itemRelativePath = path.join(relativePath, item);
+          if (fs.statSync(fullPath).isDirectory()) {
+            debug(`Scanning subdirectory: ${item}`);
+            scanDirectory(fullPath, itemRelativePath);
+          } else {
+            const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif'];
+            if (imageExtensions.some(ext => item.toLowerCase().endsWith(ext))) {
+              // Skip if this is in the responsive output directory
+              if (itemRelativePath.startsWith('responsive/') || itemRelativePath.includes('/responsive/') || fullPath.includes(config.outputDir)) {
+                debug(`Skipping responsive variant: ${itemRelativePath}`);
+                continue;
+              }
+              const buildPath = path.join('assets/images', itemRelativePath);
+              const normalizedBuildPath = buildPath.replace(/\\/g, '/');
+              debug(`Found filesystem image: ${item} -> ${normalizedBuildPath}`);
+              debug(`Already processed? ${processedImagePaths.has(normalizedBuildPath)}`);
+              if (!processedImagePaths.has(normalizedBuildPath)) {
+                debug(`Found unprocessed filesystem image: ${itemRelativePath}`);
+                const imageBuffer = fs.readFileSync(fullPath);
+                unprocessedImages.push({
+                  path: itemRelativePath,
+                  buffer: imageBuffer,
+                  source: 'filesystem'
+                });
+              }
+            }
+          }
+        }
+      };
+      scanDirectory(sourceImagesDir);
+    } else {
+      debug(`Source directory does not exist, trying alternative paths...`);
+
+      // Try alternative paths
+      const altPaths = [path.join(metalsmith.source(), 'assets/images'), path.join(metalsmith.source(), 'images'), path.join(metalsmith.destination(), 'assets/images'), path.join(process.cwd(), 'lib/assets/images'), path.join(process.cwd(), 'src/assets/images')];
+      for (const altPath of altPaths) {
+        debug(`Trying alternative path: ${altPath} - exists: ${fs.existsSync(altPath)}`);
+        if (fs.existsSync(altPath)) {
+          debug(`Found images at alternative path: ${altPath}`);
+
+          // Scan the found alternative path
+          const scanAlternativeDirectory = (dir, relativePath = '') => {
+            const items = fs.readdirSync(dir);
+            debug(`Found ${items.length} items in alternative path ${dir}`);
+            for (const item of items) {
+              if (item === '.DS_Store') {
+                continue;
+              }
+              const fullPath = path.join(dir, item);
+              const itemRelativePath = path.join(relativePath, item);
+              if (fs.statSync(fullPath).isDirectory()) {
+                debug(`Scanning alternative subdirectory: ${item}`);
+                scanAlternativeDirectory(fullPath, itemRelativePath);
+              } else {
+                const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif'];
+                if (imageExtensions.some(ext => item.toLowerCase().endsWith(ext))) {
+                  // Skip if this is in the responsive output directory
+                  if (itemRelativePath.startsWith('responsive/') || itemRelativePath.includes('/responsive/') || fullPath.includes(config.outputDir)) {
+                    debug(`Skipping responsive variant in alt scan: ${itemRelativePath}`);
+                    continue;
+                  }
+
+                  // For build directory, the path structure is already correct
+                  const buildPath = altPath.includes('build') ? path.join('assets/images', itemRelativePath) : path.join('assets/images', itemRelativePath);
+                  const normalizedBuildPath = buildPath.replace(/\\/g, '/');
+                  debug(`Found alternative filesystem image: ${item} -> ${normalizedBuildPath}`);
+                  debug(`Already processed? ${processedImagePaths.has(normalizedBuildPath)}`);
+                  if (!processedImagePaths.has(normalizedBuildPath)) {
+                    debug(`Found unprocessed alternative filesystem image: ${itemRelativePath}`);
+                    const imageBuffer = fs.readFileSync(fullPath);
+                    unprocessedImages.push({
+                      path: itemRelativePath,
+                      buffer: imageBuffer,
+                      source: 'filesystem-alt'
+                    });
+                  }
+                }
+              }
+            }
+          };
+          scanAlternativeDirectory(altPath);
+          break; // Stop after finding and scanning the first valid path
+        }
+      }
+    }
+  } catch (err) {
+    debug(`Error scanning filesystem: ${err.message}`);
+  }
+
+  // Method 2: Scan Metalsmith files object (for test scenarios and edge cases)
+  debug(`Scanning Metalsmith files object`);
+  const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif'];
+  Object.keys(files).forEach(filePath => {
+    // Skip if not an image
+    if (!imageExtensions.some(ext => filePath.toLowerCase().endsWith(ext))) {
+      return;
+    }
+
+    // Skip if it's already a responsive variant (comprehensive checks)
+    if (filePath.startsWith(`${config.outputDir}/`) || filePath.includes('/responsive/') || filePath.includes('responsive-images-manifest.json') || filePath.match(/-\d+w(-[a-f0-9]+)?\.(avif|webp|jpg|jpeg|png)$/i)) {
+      debug(`Skipping responsive variant in files object: ${filePath}`);
+      return;
+    }
+
+    // Skip if already processed during HTML scanning
+    if (processedImagePaths.has(filePath)) {
+      debug(`Skipping already processed files object image: ${filePath}`);
+      return;
+    }
+
+    // Check if we already found this image from filesystem scan
+    const isAlreadyFound = unprocessedImages.some(img => {
+      // For files object images starting with 'images/', check if filesystem found the same file
+      if (filePath.startsWith('images/')) {
+        const relativePath = filePath.replace('images/', '');
+        return img.path === relativePath;
+      }
+      return false;
+    });
+    if (!isAlreadyFound) {
+      debug(`Found unprocessed files object image: ${filePath}`);
+      unprocessedImages.push({
+        path: filePath,
+        buffer: files[filePath].contents,
+        source: 'files'
+      });
+    }
+  });
+  debug(`Found ${unprocessedImages.length} unprocessed images total`);
+  return unprocessedImages;
+}
+
+/**
+ * Process a background image to create 1x (original) and 2x (half-size) variants
+ * for use with CSS image-set() for retina displays
+ * @param {Buffer} buffer - Original image buffer
+ * @param {string} originalPath - Original image path
+ * @param {Function} debugFn - Debug function for logging
+ * @param {Object} config - Plugin configuration
+ * @return {Promise<Array<Object>>} - Array of generated variants
+ */
+async function processBackgroundImageVariants(buffer, originalPath, debugFn, config) {
+  const image = sharp(buffer);
+  const metadata = await image.metadata();
+  const variants = [];
+  debugFn(`Processing background image ${originalPath}: ${metadata.width}x${metadata.height}`);
+
+  // Create 1x (original size) and 2x (half size) variants
+  const sizes = [{
+    width: metadata.width,
+    density: '1x'
+  }, {
+    width: Math.round(metadata.width / 2),
+    density: '2x'
+  }];
+
+  // Process both sizes in parallel
+  const sizePromises = sizes.map(async size => {
+    // Create a Sharp instance for this size
+    const resized = image.clone().resize({
+      width: size.width,
+      withoutEnlargement: true // Don't upscale images
+    });
+
+    // Get actual dimensions after resize
+    const resizedMeta = await resized.metadata();
+
+    // Process each format in parallel for this size
+    const formatPromises = config.formats.map(async format => {
+      try {
+        // Skip problematic format combinations
+        if (format === 'original' && metadata.format.toLowerCase() === 'webp') {
+          return null;
+        }
+
+        // Determine output format and Sharp method
+        let outputFormat = format;
+        let sharpMethod = format;
+        if (format === 'original') {
+          outputFormat = metadata.format.toLowerCase();
+          sharpMethod = outputFormat === 'jpeg' ? 'jpeg' : outputFormat;
+        }
+
+        // Apply format-specific processing
+        let processedImage = resized.clone();
+        const formatOptions = config.formatOptions[format === 'original' ? outputFormat : format] || {};
+        if (sharpMethod === 'avif') {
+          processedImage = processedImage.avif(formatOptions);
+        } else if (sharpMethod === 'webp') {
+          processedImage = processedImage.webp(formatOptions);
+        } else if (sharpMethod === 'jpeg') {
+          processedImage = processedImage.jpeg(formatOptions);
+        } else if (sharpMethod === 'png') {
+          processedImage = processedImage.png(formatOptions);
+        }
+
+        // Generate output buffer
+        const outputBuffer = await processedImage.toBuffer();
+
+        // Generate variant path without hash for easier CSS usage
+        const variantPath = generateBackgroundVariantPath(originalPath, size.width, outputFormat, config);
+        debugFn(`Generated background variant: ${variantPath} (${size.density})`);
+        return {
+          path: variantPath,
+          buffer: outputBuffer,
+          width: resizedMeta.width,
+          height: resizedMeta.height,
+          format: outputFormat,
+          density: size.density
+        };
+      } catch (err) {
+        debugFn(`Error processing ${format} format for ${originalPath}: ${err.message}`);
+        return null;
+      }
+    });
+    const formatResults = await Promise.all(formatPromises);
+    return formatResults.filter(result => result !== null);
+  });
+  const sizeResults = await Promise.all(sizePromises);
+
+  // Flatten the results
+  sizeResults.forEach(formatVariants => {
+    variants.push(...formatVariants);
+  });
+  debugFn(`Generated ${variants.length} background variants for ${originalPath}`);
+  return variants;
+}
+
+/**
+ * Generate background image variant path without hash for easier CSS usage
+ * Creates predictable filenames that can be written in CSS without knowing the hash
+ * @param {string} originalPath - Original image path
+ * @param {number} width - Target width
+ * @param {string} format - Target format
+ * @param {Object} config - Plugin configuration
+ * @return {string} - Generated path without hash
+ */
+function generateBackgroundVariantPath(originalPath, width, format, config) {
+  const parsedPath = path.parse(originalPath);
+  const originalFormat = parsedPath.ext.slice(1).toLowerCase();
+
+  // If format is 'original', use the source format
+  const outputFormat = format === 'original' ? originalFormat : format;
+
+  // Create background pattern without hash: '[filename]-[width]w.[format]'
+  // Results in: 'header1-1000w.webp' instead of 'header1-1000w-abc12345.webp'
+  const outputName = config.outputPattern.replace('[filename]', parsedPath.name).replace('[width]', width).replace('[format]', outputFormat).replace('-[hash]', '') // Remove hash placeholder and preceding dash
+  .replace('[hash]', ''); // Remove any remaining hash placeholder
+
+  return path.join(config.outputDir, outputName);
+}
+
+export { optimizeImagesPlugin as default };
 //# sourceMappingURL=index.js.map