metalsmith-optimize-images 0.9.3 → 0.10.0

package/README.md

@@ -1,7 +1,5 @@
 # metalsmith-optimize-images
 
-> **🚀 Release Candidate**: This plugin has achieved comprehensive test coverage (95.27%) and is ready for production testing. Recent critical bug fixes have resolved recursive processing and AVIF format issues. Feedback welcome before 1.0.0 release!
-
 Metalsmith plugin for generating responsive images with optimal formats
 
 [![metalsmith:plugin][metalsmith-badge]][metalsmith-url]
@@ -11,16 +9,18 @@ Metalsmith plugin for generating responsive images with optimal formats
 [![ESM/CommonJS][modules-badge]][npm-url]
 [![Known Vulnerabilities](https://snyk.io/test/npm/metalsmith-optimize-images/badge.svg)](https://snyk.io/test/npm/metalsmith-optimize-images)
 
+> This Metalsmith plugin is under active development. The API is stable, but breaking changes may occur before reaching 1.0.0.
+
 ## Features
 
 - **Multiple image formats**: Generates AVIF and WebP variants with JPEG/PNG fallbacks
 - **Responsive sizes**: Creates different image sizes for various device widths
 - **Background image support**: Automatically processes unused images for CSS `image-set()` backgrounds
 - **Progressive loading**: Optional progressive image loading with low-quality placeholders
-- **Lazy loading**: Uses native browser lazy loading for better performance
+- **Lazy loading**: Uses native browser lazy loading
 - **Content-based hashing**: Adds hash to filenames for optimal caching
 - **Layout shift prevention**: Adds width/height attributes
-- **Parallel processing**: Processes images in parallel for faster builds
+- **Parallel processing**: Processes images in parallel
 - **Metadata generation**: Creates a JSON manifest with image information and variants
 - **Configurable compression**: Customize compression settings per format
 - **ESM and CommonJS support**:
@@ -33,20 +33,6 @@ Metalsmith plugin for generating responsive images with optimal formats
 npm install metalsmith-optimize-images
 ```
 
-## Requirements
-
-- Node.js >=18.0.0
-- Metalsmith >=2.5.0
-
-## Platform Testing Status
-
-- ✅ **macOS**: Fully tested and working
-- 🔄 **Windows**: Seeking community feedback on Sharp.js compatibility
-- 🔄 **Linux**: Seeking validation across different distributions
-- 🔄 **CI/CD**: Testing in various containerized environments
-
-**Help us reach 1.0.0**: If you test this plugin on Windows, Linux, or in production environments, please [share your experience](https://github.com/wernerglinka/metalsmith-optimize-images/issues)!
-
 ## Usage
 
 > This plugin **must** be run after assets are copied but before any final HTML processing.
@@ -228,7 +214,6 @@ After processing HTML-referenced images, the plugin:
    - **1x variant**: Half the original size for regular displays
    - **2x variant**: Original image size for retina displays (sharper on high-DPI screens)
 5. **Creates all formats** (AVIF, WebP, original) for optimal browser support
-6. **No HTML replacement** - you manually write CSS with `image-set()`
 
 ### Using Background Images with CSS
 
@@ -284,10 +269,8 @@ metalsmith.use(
 
 - **Automatic format optimization** - Browser selects best supported format
 - **Retina display support** - 2x variants provide crisp images on high-DPI screens
-- **Smart sizing** - Uses actual image dimensions instead of arbitrary widths
 - **No manual work** - Plugin automatically finds and processes unused images in Metalsmith files object
 - **Consistent workflow** - Same formats and quality settings as HTML images
-- **Efficient processing** - Parallel processing of sizes and formats
 
 ## Progressive Loading
 
@@ -439,39 +422,19 @@ metalsmith.env('DEBUG', 'metalsmith-optimize-images*');
 }
 ```
 
-## Recent Updates
-
-### Bug Fixes (January 2025)
-
-- **🚫 Fixed Recursive Processing**: Resolved critical issue where the background image processor was finding already-generated responsive images and reprocessing them recursively, creating malformed filenames like `image-320w-640w-960w.jpg`
-- **🚫 Fixed HEIF Extension Issue**: Fixed Sharp.js AVIF processing that was sometimes generating `.heif` extensions instead of `.avif`
-- **✅ Enhanced Background Image Filtering**: Added comprehensive filtering to prevent responsive variants from being treated as source images
-
-## Feedback & Testing
-
-This plugin is approaching 1.0.0 and we'd love your feedback! Please test and report:
-
-### Especially Needed
-
-- **Windows compatibility**: Sharp.js native compilation and image processing
-- **Large image batches**: Performance with 50+ images
-- **Memory usage**: Resource consumption in your environment
-- **Cross-platform consistency**: Image quality and file sizes across platforms
-- **Progressive loading**: Behavior across different browsers
-- **Background image processing**: Testing the new `image-set()` feature with CSS backgrounds
+## License
 
-### Current Status
+MIT
 
-- ✅ 95.27% test coverage with comprehensive edge case handling
-- ✅ Real Metalsmith integration tests (no mocks)
-- ✅ Tested on macOS with Node.js 18+
-- 🔄 Seeking broader platform validation
+## Development transparency
 
-**Report issues or success stories**: [GitHub Issues](https://github.com/wernerglinka/metalsmith-optimize-images/issues)
+Portions of this project were developed with the assistance of AI tools including Claude and Claude Code. These tools were used to:
 
-## License
+- Generate or refactor code
+- Assist with documentation
+- Troubleshoot bugs and explore alternative approaches
 
-MIT
+All AI-assisted code has been reviewed and tested to ensure it meets project standards. See the included [CLAUDE.md](CLAUDE.md) file for more details.
 
 [npm-badge]: https://img.shields.io/npm/v/metalsmith-optimize-images.svg
 [npm-url]: https://www.npmjs.com/package/metalsmith-optimize-images

package/lib/index.cjs

@@ -889,6 +889,12 @@ function replacePictureElement($, $img, variants, config) {
  */
 async function processHtmlFile(htmlFile, fileData, files, metalsmith, processedImages, debug, config) {
   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
@@ -1118,33 +1124,8 @@ function injectProgressiveAssets($) {
  * Creates a responsive images plugin for Metalsmith
  * Generates multiple sizes and formats of images and replaces img tags with picture elements
  *
- * @param {Object} options - Configuration options for the plugin
- * @param {number[]} [options.widths] - Array of image widths to generate
- * @param {string[]} [options.formats] - Array of image formats to generate (in order of preference)
- * @param {Object} [options.formatOptions] - Format-specific compression settings
- * @param {Object} [options.formatOptions.avif] - AVIF compression options
- * @param {Object} [options.formatOptions.webp] - WebP compression options
- * @param {Object} [options.formatOptions.jpeg] - JPEG compression options
- * @param {Object} [options.formatOptions.png] - PNG compression options
- * @param {string} [options.htmlPattern] - Glob pattern to match HTML files
- * @param {string} [options.imgSelector] - CSS selector for images to process
- * @param {string} [options.outputDir] - Output directory for processed images
- * @param {string} [options.outputPattern] - Output naming pattern
- * @param {boolean} [options.skipLarger] - Whether to skip generating sizes larger than original
- * @param {boolean} [options.lazy] - Whether to add loading="lazy" to images
- * @param {boolean} [options.dimensionAttributes] - Whether to add width/height attributes
- * @param {string} [options.sizes] - Default sizes attribute
- * @param {number} [options.concurrency] - Maximum number of images to process in parallel
- * @param {boolean} [options.generateMetadata] - Whether to generate a metadata JSON file
- * @param {boolean} [options.isProgressive] - Whether to use progressive image loading (default: true)
- * @param {Object} [options.placeholder] - Placeholder image settings for progressive loading
- * @param {number} [options.placeholder.width] - Placeholder image width (default: 50)
- * @param {number} [options.placeholder.quality] - Placeholder image quality (default: 30)
- * @param {number} [options.placeholder.blur] - Placeholder image blur amount (default: 10)
- * @param {boolean} [options.processUnusedImages] - Whether to process unused images for background use (default: true)
- * @param {string} [options.imagePattern] - Glob pattern to find images for background processing (default: `**\/*.{jpg,jpeg,png,gif,webp,avif}`)
- * @param {string} [options.imageFolder] - Folder to scan for background images, relative to source (default: 'lib/assets/images')
- * @return {Function} - Metalsmith plugin function
+ * @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
@@ -1570,5 +1551,10 @@ function generateBackgroundVariantPath(originalPath, width, format, config) {
   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