metalsmith-optimize-images 0.10.2 → 0.12.0

package/lib/index.cjs

@@ -139,7 +139,14 @@ function buildConfig(options = {}) {
     // 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
+    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
@@ -226,9 +233,10 @@ function generateVariantPath(originalPath, width, format, hash, config) {
  * @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) {
+async function processImageToVariants(buffer, originalPath, debugFn, config, cacheDir) {
   const image = sharp__default["default"](buffer);
   const metadata = await image.metadata();
   const variants = [];
@@ -242,6 +250,16 @@ async function processImageToVariants(buffer, originalPath, debugFn, config) {
     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
@@ -310,6 +328,76 @@ async function processImageToVariants(buffer, originalPath, debugFn, config) {
   // 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;
 }
 
@@ -324,6 +412,8 @@ async function processImageToVariants(buffer, originalPath, debugFn, config) {
  * @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({
@@ -334,7 +424,9 @@ async function processImage({
   processedImages,
   debug,
   config,
-  replacePictureElement
+  replacePictureElement,
+  cacheDir,
+  sourcePrefix
 }) {
   const $img = $(img);
   const src = $img.attr('src');
@@ -353,30 +445,53 @@ async function processImage({
   // 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 to load it from the build directory
-  // This handles cases where images were copied by other plugins (like assets)
+  // Image not in Metalsmith files object — try alternative locations on disk
   if (!files[normalizedSrc]) {
-    try {
-      const destination = metalsmith.destination();
-      const imagePath = path__default["default"].join(destination, normalizedSrc);
-      if (fs__default["default"].existsSync(imagePath)) {
-        // Load the image contents from the build directory
-        const imageBuffer = fs__default["default"].readFileSync(imagePath);
-
-        // Get modification time for cache busting - this helps with incremental builds
-        const mtime = fs__default["default"].statSync(imagePath).mtimeMs;
-
-        // Add it to Metalsmith files so the plugin can process it
-        files[normalizedSrc] = {
-          contents: imageBuffer,
-          mtime
-        };
-      } else {
-        debug(`Image not found in build: ${normalizedSrc}`);
-        return;
+    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}`);
       }
-    } catch (err) {
-      debug(`Error processing image from build directory: ${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;
     }
   }
@@ -396,15 +511,18 @@ async function processImage({
   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);
+    const variants = await processImageToVariants(files[normalizedSrc].contents, normalizedSrc, debug, config, cacheDir);
 
-    // 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
-      };
-    });
+    // 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);
@@ -891,9 +1009,11 @@ function replacePictureElement($, $img, variants, config) {
  * @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) {
+async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedImages, debug, config, cacheDir, sourcePrefix) {
   debug(`Processing HTML file: ${htmlFile}`);
 
   // Validate file.contents before processing
@@ -930,7 +1050,9 @@ async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedI
       metalsmith,
       processedImages,
       debug,
-      config
+      config,
+      cacheDir,
+      sourcePrefix
     }) : processImage({
       $,
       img,
@@ -939,7 +1061,9 @@ async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedI
       processedImages,
       debug,
       config,
-      replacePictureElement
+      replacePictureElement,
+      cacheDir,
+      sourcePrefix
     })));
   }));
 
@@ -995,7 +1119,9 @@ async function processProgressiveImage({
   metalsmith,
   processedImages,
   debug,
-  config
+  config,
+  cacheDir,
+  sourcePrefix
 }) {
   const $img = $(img);
   const src = $img.attr('src');
@@ -1014,29 +1140,53 @@ async function processProgressiveImage({
   // 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)
+  // Image not in Metalsmith files object — try alternative locations on disk
   if (!files[normalizedSrc]) {
-    try {
-      const destination = metalsmith.destination();
-      const imagePath = path__default["default"].join(destination, normalizedSrc);
-      if (fs__default["default"].existsSync(imagePath)) {
-        // Load the image contents from the build directory
-        const imageBuffer = fs__default["default"].readFileSync(imagePath);
-
-        // Get modification time for cache busting
-        const mtime = fs__default["default"].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;
+    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}`);
       }
-    } catch (err) {
-      debug(`Error processing image from build directory: ${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;
     }
   }
@@ -1059,19 +1209,23 @@ async function processProgressiveImage({
   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);
+    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);
 
-    // Save all variants to Metalsmith files
-    variants.forEach(variant => {
-      files[variant.path] = {
-        contents: variant.buffer
-      };
-    });
+    // 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
+    // Save placeholder to files (always needed for progressive loading)
     files[placeholderData.path] = {
       contents: placeholderData.contents
     };
@@ -1090,12 +1244,14 @@ async function processProgressiveImage({
 
     // 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 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) {
@@ -1158,6 +1314,27 @@ function optimizeImagesPlugin(options = {}) {
       // 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);
 
@@ -1197,7 +1374,7 @@ function optimizeImagesPlugin(options = {}) {
         // 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);
+          await processHtmlFile(htmlFile, files[htmlFile], files, metalsmith, processedImages, debug, config, cacheDir, sourcePrefix);
         }));
       }));
 
@@ -1205,7 +1382,7 @@ function optimizeImagesPlugin(options = {}) {
       // 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);
+        await processUnusedImages(files, metalsmith, processedImages, debug, config, cacheDir);
       }
 
       // Optional: Generate a JSON metadata file with information about all processed images
@@ -1234,7 +1411,7 @@ function optimizeImagesPlugin(options = {}) {
  * @param {Object} config - Plugin configuration
  * @return {Promise<void>} - Promise that resolves when processing is complete
  */
-async function processUnusedImages(files, metalsmith, processedImages, debug, config) {
+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
@@ -1260,14 +1437,18 @@ async function processUnusedImages(files, metalsmith, processedImages, debug, co
       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
-        };
-      });
+      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()}`;
@@ -1450,12 +1631,24 @@ async function findUnprocessedImages(files, metalsmith, config, processedImagePa
  * @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) {
+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
@@ -1535,10 +1728,88 @@ async function processBackgroundImageVariants(buffer, originalPath, debugFn, con
   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