metalsmith-optimize-images 0.12.0 → 1.0.0

package/lib/index.cjs

@@ -1,1843 +0,0 @@
-'use strict';
-
-var path = require('path');
-var fs = require('fs');
-var mkdirp = require('mkdirp');
-var sharp = require('sharp');
-var cheerio = require('cheerio');
-var crypto = require('crypto');
-
-function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
-
-function _interopNamespace(e) {
-  if (e && e.__esModule) return e;
-  var n = Object.create(null);
-  if (e) {
-    Object.keys(e).forEach(function (k) {
-      if (k !== 'default') {
-        var d = Object.getOwnPropertyDescriptor(e, k);
-        Object.defineProperty(n, k, d.get ? d : {
-          enumerable: true,
-          get: function () { return e[k]; }
-        });
-      }
-    });
-  }
-  n["default"] = e;
-  return n;
-}
-
-var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
-var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
-var mkdirp__namespace = /*#__PURE__*/_interopNamespace(mkdirp);
-var sharp__default = /*#__PURE__*/_interopDefaultLegacy(sharp);
-var cheerio__namespace = /*#__PURE__*/_interopNamespace(cheerio);
-var crypto__default = /*#__PURE__*/_interopDefaultLegacy(crypto);
-
-/**
- * Configuration utility for the plugin
- * Handles merging user options with sensible defaults
- */
-
-/**
- * Deep merge for objects
- * @param {Object} target - Target object
- * @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] );
-    } 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
- * @param {Object} options - User provided plugin options
- * @return {Object} - Complete config with defaults
- */
-function buildConfig(options = {}) {
-  // Default configuration with sensible defaults
-  const defaults = {
-    // Responsive breakpoints to generate
-    widths: [320, 640, 960, 1280, 1920],
-    // Formats to generate in order of preference (first is most preferred)
-    formats: ['avif', 'webp', 'original'],
-    // Format-specific compression settings
-    formatOptions: {
-      avif: {
-        quality: 65,
-        speed: 5
-      },
-      // Better compression but slower
-      webp: {
-        quality: 80,
-        lossless: false
-      },
-      jpeg: {
-        quality: 85,
-        progressive: true
-      },
-      png: {
-        compressionLevel: 8,
-        palette: true
-      }
-    },
-    // Which HTML files to process
-    htmlPattern: '**/*.html',
-    // CSS selector for images to process
-    imgSelector: 'img:not([data-no-responsive])',
-    // Output directory for processed images (relative to Metalsmith destination)
-    outputDir: 'assets/images/responsive',
-    // Output naming pattern
-    // Available tokens: [filename], [width], [format], [hash]
-    outputPattern: '[filename]-[width]w-[hash].[format]',
-    // Whether to skip generating sizes larger than original
-    skipLarger: true,
-    // Add loading="lazy" to images
-    lazy: true,
-    // Add width and height attributes to prevent layout shift
-    dimensionAttributes: true,
-    // Default sizes attribute value for responsive images
-    sizes: '(max-width: 768px) 100vw, 75vw',
-    // Maximum number of images to process in parallel
-    concurrency: 5,
-    // Whether to generate a metadata JSON file
-    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
-
-    // Persistent cache directory for generated variants (relative to metalsmith.directory())
-    // false = disabled, true = default path ('lib/<outputDir>'), string = custom path
-    // When set, variants are written to this directory and loaded from it on subsequent builds.
-    // Commit this directory to git so CI/Netlify never needs to run Sharp.
-    cache: false
-  };
-
-  // Special handling for formatOptions to ensure deep merging
-  // 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 || {})
-  };
-}
-
-/**
- * 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 (8 characters)
- */
-function generateHash(buffer) {
-  // SHA-256 for cache-busting - using secure algorithm to satisfy security scanners
-  // Only use first 8 characters to keep filenames manageable
-  return crypto__default["default"].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 ('original' means keep source format)
- * @param {string} hash - Content hash for cache busting
- * @param {object} config - Plugin config options
- * @return {string} - Generated path relative to Metalsmith destination
- */
-function generateVariantPath(originalPath, width, format, hash, config) {
-  const parsedPath = path__default["default"].parse(originalPath);
-  const originalFormat = parsedPath.ext.slice(1).toLowerCase();
-
-  // If format is 'original', use the source format (e.g., 'jpeg' for image.jpg)
-  const outputFormat = format === 'original' ? originalFormat : format;
-
-  // 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__default["default"].join(config.outputDir, outputName);
-}
-
-/**
- * Image processing utilities for creating responsive image variants
- * Handles the core Sharp.js operations for resizing and format conversion
- */
-
-/**
- * Process an image into multiple responsive variants and formats
- * @param {Buffer} buffer - Original image buffer
- * @param {string} originalPath - Original image path
- * @param {Function} debugFn - Debug function for logging
- * @param {Object} config - Plugin configuration
- * @param {string} [cacheDir] - Absolute path to the persistent cache directory (e.g., lib/assets/images/responsive)
- * @return {Promise<Array<Object>>} - Array of generated variants
- */
-async function processImageToVariants(buffer, originalPath, debugFn, config, cacheDir) {
-  const image = sharp__default["default"](buffer);
-  const metadata = await image.metadata();
-  const variants = [];
-  const hash = generateHash(buffer);
-
-  // 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 [];
-  }
-
-  // Check if all variants already exist in the persistent cache directory.
-  // The content hash in each filename ensures correctness — if the source image
-  // changes, the hash changes, filenames differ, and the cache misses naturally.
-  if (cacheDir) {
-    const cached = await loadCachedVariants(originalPath, hash, targetWidths, config, cacheDir, metadata, debugFn);
-    if (cached) {
-      return cached;
-    }
-  }
-
-  // Process all widths in parallel for better performance
-  const widthPromises = targetWidths.map(async width => {
-    // Create a Sharp instance for this width - clone to avoid conflicts
-    const resized = image.clone().resize({
-      width,
-      withoutEnlargement: config.skipLarger // Prevents upscaling small images
-    });
-
-    // 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 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 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] || {};
-          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 actual image buffer - this is where compression happens
-        const formatBuffer = await formatted.toBuffer();
-        return {
-          path: outputPath,
-          buffer: formatBuffer,
-          width,
-          format: format === 'original' ? metadata.format.toLowerCase() : format,
-          originalFormat: metadata.format.toLowerCase(),
-          size: formatBuffer.length,
-          height: resizedMeta.height
-        };
-      } catch (err) {
-        debugFn(`Error generating ${format} variant for ${originalPath} at width ${width}: ${err.message}`);
-        return null;
-      }
-    });
-
-    // Wait for all formats at this width to complete
-    const formatResults = await Promise.all(formatPromises);
-    return formatResults.filter(v => v !== null);
-  });
-
-  // Wait for all widths to complete and flatten the results
-  const widthResults = await Promise.all(widthPromises);
-  variants.push(...widthResults.flat());
-
-  // Persist newly generated variants to the cache directory so subsequent
-  // builds (local or CI) can skip Sharp entirely for this image.
-  if (cacheDir && variants.length > 0) {
-    for (const variant of variants) {
-      const cachePath = path__default["default"].join(cacheDir, path__default["default"].basename(variant.path));
-      fs__default["default"].writeFileSync(cachePath, variant.buffer);
-    }
-    debugFn(`Wrote ${variants.length} variants to cache for ${originalPath}`);
-  }
-  return variants;
-}
-
-/**
- * Loads previously generated variants from the persistent cache directory.
- * Variant files live directly in cacheDir (flat structure, no subdirectories).
- * Returns the loaded variants array, or null on any cache miss.
- * @param {string} originalPath - Original image path
- * @param {string} hash - Content hash of the source image
- * @param {number[]} targetWidths - Array of widths to check
- * @param {Object} config - Plugin configuration
- * @param {string} cacheDir - Absolute path to the cache directory (e.g., lib/assets/images/responsive)
- * @param {Object} sourceMetadata - Sharp metadata of the source image
- * @param {Function} debugFn - Debug function
- * @return {Promise<Array<Object>|null>} - Loaded variants or null on cache miss
- */
-async function loadCachedVariants(originalPath, hash, targetWidths, config, cacheDir, sourceMetadata, debugFn) {
-  const expected = [];
-  for (const width of targetWidths) {
-    for (const format of config.formats) {
-      if (format === 'original' && sourceMetadata.format.toLowerCase() === 'webp') {
-        continue;
-      }
-      const variantPath = generateVariantPath(originalPath, width, format, hash, config);
-      const fullPath = path__default["default"].join(cacheDir, path__default["default"].basename(variantPath));
-      expected.push({
-        variantPath,
-        fullPath,
-        width,
-        format
-      });
-    }
-  }
-
-  // Quick existence check — bail on first miss
-  for (const ev of expected) {
-    if (!fs__default["default"].existsSync(ev.fullPath)) {
-      return null;
-    }
-  }
-
-  // All variants found on disk, load them
-  debugFn(`Loading ${expected.length} cached variants for ${originalPath}`);
-
-  // Compute height from the source aspect ratio instead of calling sharp().metadata()
-  // on every cached file — avoids spinning up Sharp entirely on cache hits.
-  const aspectRatio = sourceMetadata.height / sourceMetadata.width;
-  const variants = expected.map(ev => {
-    const buffer = fs__default["default"].readFileSync(ev.fullPath);
-    const resolvedFormat = ev.format === 'original' ? sourceMetadata.format.toLowerCase() : ev.format;
-    return {
-      path: ev.variantPath,
-      buffer,
-      width: ev.width,
-      format: resolvedFormat,
-      originalFormat: sourceMetadata.format.toLowerCase(),
-      size: buffer.length,
-      height: Math.round(ev.width * aspectRatio)
-    };
-  });
-  return variants;
-}
-
-/**
- * Process a single image
- * @param {Object} context - Processing context
- * @param {Object} context.$ - Cheerio instance
- * @param {Object} context.img - Image DOM element
- * @param {Object} context.files - Metalsmith files object
- * @param {Object} context.metalsmith - Metalsmith instance
- * @param {Map} context.processedImages - Cache of processed images
- * @param {Function} context.debug - Debug function
- * @param {Object} context.config - Plugin configuration
- * @param {Function} context.replacePictureElement - Function to replace img with picture
- * @param {string|null} context.cacheDir - Resolved absolute path to persistent cache, or null
- * @param {string|null} context.sourcePrefix - Prefix to map build paths to source asset paths on disk, or null
- * @return {Promise<void>} - Promise that resolves when the image is processed
- */
-async function processImage({
-  $,
-  img,
-  files,
-  metalsmith,
-  processedImages,
-  debug,
-  config,
-  replacePictureElement,
-  cacheDir,
-  sourcePrefix
-}) {
-  const $img = $(img);
-  const src = $img.attr('src');
-  if (!src || src.startsWith('http') || src.startsWith('data:')) {
-    debug(`Skipping external or data URL: ${src}`);
-    return;
-  }
-
-  // Skip SVG files - they are vector graphics that don't need responsive raster variants
-  if (src.toLowerCase().endsWith('.svg')) {
-    debug(`Skipping SVG file (vector graphics don't need responsive variants): ${src}`);
-    return;
-  }
-
-  // Normalize src path to match Metalsmith files object keys
-  // Remove leading slash if present (HTML paths vs Metalsmith file keys)
-  const normalizedSrc = src.startsWith('/') ? src.slice(1) : src;
-
-  // Image not in Metalsmith files object — try alternative locations on disk
-  if (!files[normalizedSrc]) {
-    let loaded = false;
-
-    // When cache is configured and the plugin runs before the static-files copy,
-    // source images live on disk at sourcePrefix + normalizedSrc
-    if (sourcePrefix && !loaded) {
-      try {
-        const sourcePath = path__default["default"].resolve(metalsmith.directory(), sourcePrefix, normalizedSrc);
-        if (fs__default["default"].existsSync(sourcePath)) {
-          files[normalizedSrc] = {
-            contents: fs__default["default"].readFileSync(sourcePath),
-            mtime: fs__default["default"].statSync(sourcePath).mtimeMs
-          };
-          loaded = true;
-        }
-      } catch (err) {
-        debug(`Error loading source image from ${sourcePrefix}: ${err.message}`);
-      }
-    }
-
-    // Fallback: try the build directory (handles post-static-copy scenario)
-    if (!loaded) {
-      try {
-        const destination = metalsmith.destination();
-        const imagePath = path__default["default"].join(destination, normalizedSrc);
-
-        // Security: Ensure resolved path stays within destination directory
-        const resolvedPath = path__default["default"].resolve(imagePath);
-        const resolvedDestination = path__default["default"].resolve(destination);
-        if (!resolvedPath.startsWith(resolvedDestination + path__default["default"].sep)) {
-          debug(`Skipping path traversal attempt: ${normalizedSrc}`);
-          return;
-        }
-        if (fs__default["default"].existsSync(imagePath)) {
-          files[normalizedSrc] = {
-            contents: fs__default["default"].readFileSync(imagePath),
-            mtime: fs__default["default"].statSync(imagePath).mtimeMs
-          };
-          loaded = true;
-        }
-      } catch (err) {
-        debug(`Error loading image from build directory: ${err.message}`);
-      }
-    }
-    if (!loaded) {
-      debug(`Image not found: ${normalizedSrc}`);
-      return;
-    }
-  }
-
-  // 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 exact image (same file + mtime)
-  if (processedImages.has(cacheKey)) {
-    debug(`Using cached variants for ${normalizedSrc}`);
-    const variants = processedImages.get(cacheKey);
-    replacePictureElement($, $img, variants, config);
-    return;
-  }
-  debug(`Processing image: ${normalizedSrc}`);
-  try {
-    // Process image to generate all variants (different sizes and formats)
-    const variants = await processImageToVariants(files[normalizedSrc].contents, normalizedSrc, debug, config, cacheDir);
-
-    // When cache is configured, variant files are written to cacheDir by
-    // processImageToVariants and the static-files plugin copies them to the build.
-    // When cache is NOT configured, add variants to the files object directly.
-    if (!cacheDir) {
-      variants.forEach(variant => {
-        files[variant.path] = {
-          contents: variant.buffer
-        };
-      });
-    }
-
-    // Cache variants for this image to avoid reprocessing
-    processedImages.set(cacheKey, variants);
-
-    // 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__default["default"](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__default["default"].basename(imagePath, path__default["default"].extname(imagePath))}-placeholder.jpg`;
-    const outputPath = path__default["default"].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
- */
-
-/**
- * Replace an img element with a responsive picture element
- * @param {Object} $ - Cheerio instance
- * @param {Object} $img - Cheerio image element
- * @param {Array<Object>} variants - Generated image variants
- * @param {Object} config - Plugin configuration
- */
-function replacePictureElement($, $img, variants, config) {
-  if (variants.length === 0) {
-    return;
-  }
-
-  // Get original img 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 for creating <source> elements
-  const variantsByFormat = {};
-  variants.forEach(v => {
-    if (!variantsByFormat[v.format]) {
-      variantsByFormat[v.format] = [];
-    }
-    variantsByFormat[v.format].push(v);
-  });
-
-  // Create picture element that will contain all formats
-  const $picture = $('<picture>');
-
-  // 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 - it's handled separately
-    if (format === 'original') {
-      return;
-    }
-    const formatVariants = variantsByFormat[format];
-    if (!formatVariants || formatVariants.length === 0) {
-      return;
-    }
-
-    // Sort variants by width for proper srcset ordering
-    formatVariants.sort((a, b) => a.width - b.width);
-
-    // Create srcset string: "path 320w, path 640w, path 960w"
-    const srcset = formatVariants.map(v => `/${v.path} ${v.width}w`).join(', ');
-
-    // 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 (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];
-    formatVariants.sort((a, b) => a.width - b.width);
-    const srcset = formatVariants.map(v => `/${v.path} ${v.width}w`).join(', ');
-    $('<source>').attr('type', `image/${originalFormat}`).attr('srcset', srcset).attr('sizes', sizesAttr).appendTo($picture);
-  }
-
-  // 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);
-
-  // Preserve original class attribute if present
-  if (className) {
-    $newImg.attr('class', className);
-  }
-
-  // Add native lazy loading if configured (improves performance)
-  if (config.lazy) {
-    $newImg.attr('loading', 'lazy');
-  }
-
-  // Add width/height attributes to prevent layout shift (CLS)
-  if (config.dimensionAttributes && variants.length > 0) {
-    // 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 (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));
-    }
-  }
-
-  // Add img to picture element
-  $newImg.appendTo($picture);
-
-  // Replace original img with picture element
-  $img.replaceWith($picture);
-}
-
-/**
- * Process an HTML file to replace img tags with responsive picture elements
- * @param {string} htmlFile - Path to HTML file
- * @param {Object} fileData - File data object
- * @param {Object} files - Metalsmith files object
- * @param {Object} metalsmith - Metalsmith instance
- * @param {Map} processedImages - Cache of processed images
- * @param {Function} debug - Debug function
- * @param {Object} config - Plugin configuration
- * @param {string|null} cacheDir - Resolved absolute path to persistent cache, or null
- * @param {string|null} sourcePrefix - Prefix to map build paths to source asset paths on disk, or null
- * @return {Promise<void>} - Promise that resolves when the HTML file is processed
- */
-async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedImages, debug, config, cacheDir, sourcePrefix) {
-  debug(`Processing HTML file: ${htmlFile}`);
-
-  // Validate file.contents before processing
-  if (!fileData.contents || !Buffer.isBuffer(fileData.contents)) {
-    debug(`Skipping ${htmlFile}: invalid or missing file contents`);
-    return;
-  }
-  const content = fileData.contents.toString();
-
-  // Parse HTML
-  const $ = cheerio__namespace.load(content);
-
-  // 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}`);
-    return;
-  }
-  debug(`Found ${images.length} images in ${htmlFile}`);
-
-  // 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 - 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 => config.isProgressive ? processProgressiveImage({
-      $,
-      img,
-      files,
-      metalsmith,
-      processedImages,
-      debug,
-      config,
-      cacheDir,
-      sourcePrefix
-    }) : processImage({
-      $,
-      img,
-      files,
-      metalsmith,
-      processedImages,
-      debug,
-      config,
-      replacePictureElement,
-      cacheDir,
-      sourcePrefix
-    })));
-  }));
-
-  // 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((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,
-      height: v.height,
-      format: v.format,
-      size: v.size
-    }));
-  });
-  const metadataPath = path__default["default"].join(config.outputDir, 'responsive-images-manifest.json');
-  files[metadataPath] = {
-    contents: Buffer.from(JSON.stringify(metadataObj, null, 2))
-  };
-}
-
-/**
- * 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,
-  cacheDir,
-  sourcePrefix
-}) {
-  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;
-  }
-
-  // Skip SVG files - they are vector graphics that don't need responsive raster variants
-  if (src.toLowerCase().endsWith('.svg')) {
-    debug(`Skipping SVG file (vector graphics don't need responsive variants): ${src}`);
-    return;
-  }
-
-  // Normalize src path to match Metalsmith files object keys
-  const normalizedSrc = src.startsWith('/') ? src.slice(1) : src;
-
-  // Image not in Metalsmith files object — try alternative locations on disk
-  if (!files[normalizedSrc]) {
-    let loaded = false;
-
-    // When cache is configured and the plugin runs before the static-files copy,
-    // source images live on disk at sourcePrefix + normalizedSrc
-    if (sourcePrefix && !loaded) {
-      try {
-        const sourcePath = path__default["default"].resolve(metalsmith.directory(), sourcePrefix, normalizedSrc);
-        if (fs__default["default"].existsSync(sourcePath)) {
-          files[normalizedSrc] = {
-            contents: fs__default["default"].readFileSync(sourcePath),
-            mtime: fs__default["default"].statSync(sourcePath).mtimeMs
-          };
-          loaded = true;
-        }
-      } catch (err) {
-        debug(`Error loading source image from ${sourcePrefix}: ${err.message}`);
-      }
-    }
-
-    // Fallback: try the build directory (handles post-static-copy scenario)
-    if (!loaded) {
-      try {
-        const destination = metalsmith.destination();
-        const imagePath = path__default["default"].join(destination, normalizedSrc);
-
-        // Security: Ensure resolved path stays within destination directory
-        const resolvedPath = path__default["default"].resolve(imagePath);
-        const resolvedDestination = path__default["default"].resolve(destination);
-        if (!resolvedPath.startsWith(resolvedDestination + path__default["default"].sep)) {
-          debug(`Skipping path traversal attempt: ${normalizedSrc}`);
-          return;
-        }
-        if (fs__default["default"].existsSync(imagePath)) {
-          files[normalizedSrc] = {
-            contents: fs__default["default"].readFileSync(imagePath),
-            mtime: fs__default["default"].statSync(imagePath).mtimeMs
-          };
-          loaded = true;
-        }
-      } catch (err) {
-        debug(`Error loading image from build directory: ${err.message}`);
-      }
-    }
-    if (!loaded) {
-      debug(`Image not found: ${normalizedSrc}`);
-      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, cacheDir);
-
-    // Generate low-quality placeholder image for smooth loading transitions
-    const placeholderData = await generatePlaceholder(normalizedSrc, files[normalizedSrc].contents, config.placeholder, metalsmith);
-
-    // When cache is configured, variant files are written to cacheDir by
-    // processImageToVariants and the static-files plugin copies them to the build.
-    // When cache is NOT configured, add variants to the files object directly.
-    if (!cacheDir) {
-      variants.forEach(variant => {
-        files[variant.path] = {
-          contents: variant.buffer
-        };
-      });
-    }
-
-    // Save placeholder to files (always needed for progressive loading)
-    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, cacheDir);
-      if (!cacheDir) {
-        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-optimize-images
- */
-
-/**
- * Creates a responsive images plugin for Metalsmith
- * Generates multiple sizes and formats of images and replaces img tags with picture elements
- *
- * @param {Options} [options={}] - Configuration options for the plugin
- * @returns {import('metalsmith').Plugin} - Metalsmith plugin function
- */
-function optimizeImagesPlugin(options = {}) {
-  // Build configuration with defaults and user options
-  const config = buildConfig(options);
-
-  /**
-   * The Metalsmith plugin function
-   * @param {Object} files - Metalsmith files object
-   * @param {Object} metalsmith - Metalsmith instance
-   * @param {Function} done - Callback function
-   * @return {void}
-   */
-  return async function optimizeImages(files, metalsmith, done) {
-    try {
-      const destination = metalsmith.destination();
-      const outputPath = path__default["default"].join(destination, config.outputDir);
-
-      // Set up debug function for logging (uses 'DEBUG=metalsmith-optimize-images*' env var)
-      const debug = metalsmith.debug('metalsmith-optimize-images');
-
-      // Resolve persistent cache directory from config.
-      // When set (e.g., 'lib/assets/images/responsive'), variants are read/written there
-      // and the static-files plugin copies them to the build.
-      let cacheDir = null;
-      let sourcePrefix = null;
-      if (config.cache) {
-        // Normalise: cache: true → default path 'lib/<outputDir>'
-        const cachePath = typeof config.cache === 'string' ? config.cache : path__default["default"].join('lib', config.outputDir);
-        cacheDir = path__default["default"].resolve(metalsmith.directory(), cachePath);
-        mkdirp__namespace.mkdirpSync(cacheDir);
-
-        // Derive the source-asset prefix so the plugin can find images on disk
-        // when it runs before the static-files copy.
-        // e.g., cachePath='lib/assets/images/responsive', outputDir='assets/images/responsive'
-        //   → sourcePrefix = 'lib/' (the part of cachePath that precedes outputDir)
-        if (cachePath.endsWith(config.outputDir)) {
-          sourcePrefix = cachePath.slice(0, cachePath.length - config.outputDir.length);
-        }
-        debug(`Persistent cache: ${cacheDir}`);
-      }
-
-      // Ensure the output directory exists where processed images will be saved
-      mkdirp__namespace.mkdirpSync(outputPath);
-
-      // 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();
-      }
-
-      // Cache to avoid re-processing identical images across different HTML files
-      // Key: "filepath:mtime", Value: array of processed image variants
-      const processedImages = new Map();
-
-      // 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 - 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, cacheDir, sourcePrefix);
-        }));
-      }));
-
-      // 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, cacheDir);
-      }
-
-      // 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);
-      }
-      debug('Responsive images processing complete');
-      done();
-    } catch (err) {
-      // Use console.error for errors to ensure they're visible even if debug mode is not enabled
-      console.error(`Error in responsive images plugin: ${err.message}`);
-      done(err);
-    }
-  };
-}
-
-/**
- * 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, cacheDir) {
-  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, cacheDir);
-
-      // When cache is configured, variant files are written to cacheDir by
-      // processBackgroundImageVariants and the static-files plugin copies them.
-      // Otherwise, add them to the files object directly.
-      if (!cacheDir) {
-        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__default["default"].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__default["default"].existsSync(sourceImagesDir)}`);
-    debug(`Metalsmith source: ${metalsmith.source()}`);
-    debug(`Metalsmith destination: ${metalsmith.destination()}`);
-    if (fs__default["default"].existsSync(sourceImagesDir)) {
-      debug(`Scanning source directory: ${sourceImagesDir}`);
-      const scanDirectory = (dir, relativePath = '') => {
-        const items = fs__default["default"].readdirSync(dir);
-        debug(`Found ${items.length} items in ${dir}`);
-        for (const item of items) {
-          if (item === '.DS_Store') {
-            continue;
-          }
-          const fullPath = path__default["default"].join(dir, item);
-          const itemRelativePath = path__default["default"].join(relativePath, item);
-          if (fs__default["default"].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__default["default"].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__default["default"].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__default["default"].join(metalsmith.source(), 'assets/images'), path__default["default"].join(metalsmith.source(), 'images'), path__default["default"].join(metalsmith.destination(), 'assets/images'), path__default["default"].join(process.cwd(), 'lib/assets/images'), path__default["default"].join(process.cwd(), 'src/assets/images')];
-      for (const altPath of altPaths) {
-        debug(`Trying alternative path: ${altPath} - exists: ${fs__default["default"].existsSync(altPath)}`);
-        if (fs__default["default"].existsSync(altPath)) {
-          debug(`Found images at alternative path: ${altPath}`);
-
-          // Scan the found alternative path
-          const scanAlternativeDirectory = (dir, relativePath = '') => {
-            const items = fs__default["default"].readdirSync(dir);
-            debug(`Found ${items.length} items in alternative path ${dir}`);
-            for (const item of items) {
-              if (item === '.DS_Store') {
-                continue;
-              }
-              const fullPath = path__default["default"].join(dir, item);
-              const itemRelativePath = path__default["default"].join(relativePath, item);
-              if (fs__default["default"].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__default["default"].join('assets/images', itemRelativePath) : path__default["default"].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__default["default"].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
- * @param {string} [cacheDir] - Absolute path to the persistent cache directory, or null
- * @return {Promise<Array<Object>>} - Array of generated variants
- */
-async function processBackgroundImageVariants(buffer, originalPath, debugFn, config, cacheDir) {
-  const image = sharp__default["default"](buffer);
-  const metadata = await image.metadata();
-  const variants = [];
-
-  // Check if background variants already exist on disk from a previous build.
-  // Background filenames are deterministic (no content hash), so existence alone
-  // tells us the work was already done. If a source image changes content without
-  // changing filename, delete the responsive directory to force regeneration.
-  if (cacheDir) {
-    const cached = await loadCachedBgVariants(originalPath, metadata, config, cacheDir, debugFn);
-    if (cached) {
-      return cached;
-    }
-  }
-  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);
-  });
-
-  // Persist newly generated variants to the cache directory so subsequent
-  // builds can skip Sharp entirely for these background images.
-  if (cacheDir && variants.length > 0) {
-    for (const variant of variants) {
-      const cachePath = path__default["default"].join(cacheDir, path__default["default"].basename(variant.path));
-      fs__default["default"].writeFileSync(cachePath, variant.buffer);
-    }
-    debugFn(`Wrote ${variants.length} background variants to cache for ${originalPath}`);
-  }
-  debugFn(`Generated ${variants.length} background variants for ${originalPath}`);
-  return variants;
-}
-
-/**
- * Loads previously generated background variants from the persistent cache directory.
- * Checks that every expected variant file (size × format) exists on disk.
- * Returns the loaded variants array, or null on any cache miss.
- * @param {string} originalPath - Original image path
- * @param {Object} sourceMetadata - Sharp metadata of the source image
- * @param {Object} config - Plugin configuration
- * @param {string} cacheDir - Absolute path to the persistent cache directory
- * @param {Function} debugFn - Debug function
- * @return {Promise<Array<Object>|null>} - Loaded variants or null on cache miss
- */
-async function loadCachedBgVariants(originalPath, sourceMetadata, config, cacheDir, debugFn) {
-  const sizes = [{
-    width: sourceMetadata.width,
-    density: '1x'
-  }, {
-    width: Math.round(sourceMetadata.width / 2),
-    density: '2x'
-  }];
-  const expected = [];
-  for (const size of sizes) {
-    for (const format of config.formats) {
-      if (format === 'original' && sourceMetadata.format.toLowerCase() === 'webp') {
-        continue;
-      }
-      let outputFormat = format;
-      if (format === 'original') {
-        outputFormat = sourceMetadata.format.toLowerCase();
-      }
-      const variantPath = generateBackgroundVariantPath(originalPath, size.width, outputFormat, config);
-      const fullPath = path__default["default"].join(cacheDir, path__default["default"].basename(variantPath));
-      expected.push({
-        variantPath,
-        fullPath,
-        width: size.width,
-        format: outputFormat,
-        density: size.density
-      });
-    }
-  }
-
-  // Quick existence check — bail on first miss
-  for (const ev of expected) {
-    if (!fs__default["default"].existsSync(ev.fullPath)) {
-      return null;
-    }
-  }
-
-  // All variants found on disk, load them
-  debugFn(`Loading ${expected.length} cached background variants for ${originalPath}`);
-
-  // Compute height from the source aspect ratio instead of calling sharp().metadata()
-  // on every cached file — avoids spinning up Sharp entirely on cache hits.
-  const aspectRatio = sourceMetadata.height / sourceMetadata.width;
-  const variants = expected.map(ev => {
-    const buffer = fs__default["default"].readFileSync(ev.fullPath);
-    return {
-      path: ev.variantPath,
-      buffer,
-      width: ev.width,
-      height: Math.round(ev.width * aspectRatio),
-      format: ev.format,
-      density: ev.density
-    };
-  });
-  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__default["default"].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__default["default"].join(config.outputDir, outputName);
-}
-
-// Set function name for better debugging
-Object.defineProperty(optimizeImagesPlugin, 'name', {
-  value: 'metalsmith-optimize-images'
-});
-
-module.exports = optimizeImagesPlugin;
-//# sourceMappingURL=index.cjs.map