feat: enhance srcset detection to include crop status and improve logging for image processing

Author: selul

assets/js/modules/README.md

@@ -89,6 +89,11 @@ This directory contains the modular JavaScript components for the Optimole image
     - Includes images without `data-opt-src` (non-lazyload images)
     - Includes images with `data-opt-src` AND `data-opt-lazy-loaded` (completed lazyload)
     - Skips images with only `data-opt-src` (pending lazyload)
+  - **Aspect ratio detection for cropping requirements**:
+    - Compares natural vs. displayed aspect ratios to determine if cropping is needed
+    - Uses intelligent thresholds: 5% tolerance, 15% significant difference, 10% ratio change
+    - Prevents unnecessary cropping when aspect ratios match
+    - Returns separate crop status data as `imageId: cropStatus` mapping
   - Calculates required srcset variations using comprehensive size ranges:
     - Mobile range: 200w-500w (50w steps) for dense mobile coverage
     - Tablet range: 500w-800w (100w steps) for tablet devices
@@ -101,6 +106,7 @@ This directory contains the modular JavaScript components for the Optimole image
     - `sizeTolerance`: Tolerance for existing sizes (default: 50px)
   - Analyzes existing srcset attributes to identify missing sizes
   - **Ultra-compact API payload**: Sends only essential fields with short names (w, h, d, s, b)
+  - **Separate crop status**: Returns crop requirements as `imageId: cropStatus` mapping instead of per-srcset flags
   - **Full logging**: Complete analysis data available in console logs for debugging
   - Smart selection from dense size grid for optimal responsive coverage
 
@@ -110,6 +116,47 @@ This directory contains the modular JavaScript components for the Optimole image
 - **Key Features**:
   - Complete above-the-fold detection workflow
   - Module coordination and data aggregation
-  - API data preparation and submission
+  - API data preparation and submission with separate crop status
   - Error handling and condition checking
+
+## Data Structure
+
+### API Payload Structure
+The main module sends data to the REST API with the following structure:
+
+```javascript
+{
+  d: deviceType,           // Device type (1=mobile, 2=desktop)
+  a: aboveTheFoldImages,   // Array of above-fold image IDs
+  b: backgroundSelectors,  // Background image selectors
+  u: url,                  // Page URL
+  t: timestamp,            // Request timestamp
+  h: hmac,                 // Security hash
+  l: lcpData,              // LCP (Largest Contentful Paint) data
+  m: missingDimensions,    // Missing dimension data
+  s: srcsetData,           // Srcset variations data
+  c: cropStatusData        // Crop status mapping (imageId -> boolean)
+}
+```
+
+### Srcset Data Structure
+Individual srcset entries contain:
+```javascript
+{
+  w: width,        // Image width
+  h: height,       // Image height  
+  d: dpr,          // Device pixel ratio
+  s: descriptor,   // Srcset descriptor (e.g., "300w")
+  b: breakpoint    // CSS breakpoint
+}
+```
+
+### Crop Status Data Structure
+Crop requirements are stored separately:
+```javascript
+{
+  882936320: true,   // Image ID -> requires cropping
+  123456789: false   // Image ID -> no cropping needed
+}
+```
 

assets/js/modules/main.js

@@ -112,9 +112,12 @@ export const optmlMain = {
     optmlLogger.info('Images with missing dimensions found:', Object.keys(imageDimensionsData).length);
 
     // Detect images requiring srcset variations (non-lazyload images)
-    const srcsetData = await optmlSrcsetDetector.detectMissingSrcsets();
+    const srcsetResult = await optmlSrcsetDetector.detectMissingSrcsets();
+    const srcsetData = srcsetResult.srcset;
+    const cropStatusData = srcsetResult.crop;
 
     optmlLogger.info('Images requiring srcset variations found:', Object.keys(srcsetData).length);
+    optmlLogger.info('Images with crop status found:', Object.keys(cropStatusData).length);
 
     // Process background image selectors if available
     let bgImageUrls = new Map();
@@ -177,7 +180,8 @@ export const optmlMain = {
           u: lcpData.bgUrls   
         },
         m: imageDimensionsData, // m for missing dimensions
-        s: srcsetData // s for srcset data
+        s: srcsetData, // s for srcset data
+        c: cropStatusData // c for crop status data
       };
 
       optmlLogger.info('Sending data with LCP information:', { 
@@ -188,6 +192,7 @@ export const optmlMain = {
       optmlLogger.info('Sending background selectors:', processedBgSelectors);
       optmlLogger.info('Sending dimension data for images:', imageDimensionsData);
       optmlLogger.info('Sending srcset data for images:', srcsetData);
+      optmlLogger.info('Sending crop status data for images:', cropStatusData);
 
       optmlApi.sendToRestApi(data);
       return data;

assets/js/modules/srcset-detector.js

@@ -118,17 +118,18 @@ export const optmlSrcsetDetector = {
   /**
    * Detect all Optimole images that are NOT using lazyload (no data-opt-src)
    * and calculate missing srcset variations
-   * @returns {Promise<Object>} Promise that resolves to object mapping image IDs to their required srcset data
+   * @returns {Promise<Object>} Promise that resolves to object with srcset data and crop status
    */
   detectMissingSrcsets: async function() {
     const missingSrcsetData = {};
+    const cropStatusData = {};
 
     // Find all Optimole images
     const optimoleImages = document.querySelectorAll('img[data-opt-id]');
 
     if (optimoleImages.length === 0) {
       optmlLogger.info('No Optimole images found for srcset analysis');
-      return missingSrcsetData;
+      return { srcset: missingSrcsetData, crop: cropStatusData };
     }
 
     optmlLogger.info(`Found ${optimoleImages.length} Optimole images, waiting for them to load...`);
@@ -159,10 +160,11 @@ export const optmlSrcsetDetector = {
           optmlLogger.info(`Image ${imageId} ${reason}, analyzing srcset requirements`);
 
           // Analyze the image and calculate required srcset variations
-          const missingSizes = this._analyzeSrcsetRequirements(img, imageId);
+          const analysisResult = this._analyzeSrcsetRequirements(img, imageId);
 
-          if (missingSizes && missingSizes.length > 0) {
-            missingSrcsetData[imageId] = missingSizes;
+          if (analysisResult && analysisResult.srcset && analysisResult.srcset.length > 0) {
+            missingSrcsetData[imageId] = analysisResult.srcset;
+            cropStatusData[imageId] = analysisResult.requiresCropping;
           }
         }
       } catch (error) {
@@ -171,7 +173,8 @@ export const optmlSrcsetDetector = {
     });
 
     optmlLogger.info('Images requiring srcset variations:', Object.keys(missingSrcsetData).length);
-    return missingSrcsetData;
+    optmlLogger.info('Images with crop status:', Object.keys(cropStatusData).length);
+    return { srcset: missingSrcsetData, crop: cropStatusData };
   },
 
   /**
@@ -199,17 +202,24 @@ export const optmlSrcsetDetector = {
       natural: `${naturalWidth}x${naturalHeight}`
     });
 
-    // Calculate aspect ratio
-    const aspectRatio = naturalWidth / naturalHeight;
+    // Calculate aspect ratios
+    const naturalAspectRatio = naturalWidth / naturalHeight;
+    const currentAspectRatio = currentWidth / currentHeight;
+    
+    // Determine if image requires cropping based on aspect ratio difference
+    const aspectRatioDifference = Math.abs(naturalAspectRatio - currentAspectRatio);
+    const requiresCropping = this._requiresCropping(aspectRatioDifference, naturalAspectRatio, currentAspectRatio);
 
     // Get current device type
     const currentDeviceType = optmlDevice.getDeviceType();
 
     // Calculate required sizes for different breakpoints
+    // Use current aspect ratio for srcset generation to match the rendered dimensions
+    const aspectRatioForSizing = requiresCropping ? currentAspectRatio : naturalAspectRatio;
     const requiredSizes = this._calculateRequiredSizes(
       currentWidth, 
       currentHeight, 
-      aspectRatio,
+      aspectRatioForSizing,
       currentDeviceType,
       naturalWidth,
       naturalHeight
@@ -231,20 +241,68 @@ export const optmlSrcsetDetector = {
     optmlLogger.info(`Image ${imageId} srcset analysis:`, {
       currentSize: { w: currentWidth, h: currentHeight },
       naturalSize: { w: naturalWidth, h: naturalHeight },
-      aspectRatio: Math.round(aspectRatio * 1000) / 1000,
+      naturalAspectRatio: Math.round(naturalAspectRatio * 1000) / 1000,
+      currentAspectRatio: Math.round(currentAspectRatio * 1000) / 1000,
+      aspectRatioDifference: Math.round(aspectRatioDifference * 1000) / 1000,
+      requiresCropping: requiresCropping,
+      aspectRatioForSizing: Math.round(aspectRatioForSizing * 1000) / 1000,
       deviceType: currentDeviceType,
       missingSizes: missingSizes,
       existingSrcset: existingSrcset || null
     });
+
+    // Additional debug logging for aspect ratio analysis
+    console.log(`[Optimole Debug] Image ${imageId} aspect ratio analysis:`, {
+      natural: `${naturalWidth}x${naturalHeight} (${Math.round(naturalAspectRatio * 1000) / 1000}:1)`,
+      current: `${currentWidth}x${currentHeight} (${Math.round(currentAspectRatio * 1000) / 1000}:1)`,
+      difference: Math.round(aspectRatioDifference * 1000) / 1000,
+      requiresCropping: requiresCropping,
+      aspectRatioForSizing: Math.round(aspectRatioForSizing * 1000) / 1000,
+      reason: requiresCropping ? 'Aspect ratio significantly different' : 'Aspect ratios match within tolerance'
+    });
+    
+    // Return both srcset data and crop status separately
+    return {
+      srcset: missingSizes.map(size => ({
+        w: size.w,
+        h: size.h,
+        d: size.dpr,        // dpr -> d
+        s: size.descriptor, // descriptor -> s (srcset)
+        b: size.breakpoint  // breakpoint -> b
+      })),
+      requiresCropping: requiresCropping
+    };
+  },
+
+  /**
+   * Determine if an image requires cropping based on aspect ratio differences
+   * @private
+   * @param {number} aspectRatioDifference - Absolute difference between natural and current aspect ratios
+   * @param {number} naturalAspectRatio - Natural image aspect ratio
+   * @param {number} currentAspectRatio - Current displayed aspect ratio
+   * @returns {boolean} True if the image requires cropping
+   */
+  _requiresCropping: function(aspectRatioDifference, naturalAspectRatio, currentAspectRatio) {
+    // Define thresholds for determining when cropping is needed
+    const ASPECT_RATIO_TOLERANCE = 0.05; // 5% tolerance for minor differences
+    const SIGNIFICANT_DIFFERENCE_THRESHOLD = 0.15; // 15% for significant differences
+    
+    // If the difference is very small, no cropping needed
+    if (aspectRatioDifference <= ASPECT_RATIO_TOLERANCE) {
+      return false;
+    }
+    
+    // If the difference is significant, definitely needs cropping
+    if (aspectRatioDifference >= SIGNIFICANT_DIFFERENCE_THRESHOLD) {
+      return true;
+    }
+    
+    // For moderate differences, check if the current aspect ratio is significantly different
+    // from the natural one (indicating intentional resizing that would require cropping)
+    const ratioChange = Math.abs(currentAspectRatio - naturalAspectRatio) / naturalAspectRatio;
 
-    // Return only essential fields for API (ultra-minimal payload with short names)
-    return missingSizes.map(size => ({
-      w: size.w,
-      h: size.h,
-      d: size.dpr,        // dpr -> d
-      s: size.descriptor, // descriptor -> s (srcset)
-      b: size.breakpoint  // breakpoint -> b
-    }));
+    // If the current aspect ratio is more than 10% different from natural, likely needs cropping
+    return ratioChange > 0.1;
   },
 
   /**
@@ -329,23 +387,45 @@ export const optmlSrcsetDetector = {
   _generateResponsiveSizes: function(currentWidth, currentHeight, aspectRatio, naturalWidth, naturalHeight) {
     const sizes = [];
 
-    // Generate comprehensive responsive sizes with better coverage
-    // Strategy: Create a dense grid of sizes for better responsive coverage
+    // Container-based size generation: Generate sizes relative to the actual container size
+    // This prevents oversized images from being selected for small containers
 
-    // Define size ranges for different device categories
-    const sizeRanges = [
-      // Mobile range: 200w - 500w (step 50w) - dense coverage for mobile
-      { min: 200, max: 500, step: 50, dpr: [1], category: 'mobile' },
-      
-      // Tablet range: 500w - 800w (step 100w) - good tablet coverage
-      { min: 500, max: 800, step: 100, dpr: [1], category: 'tablet' },
-      
-      // Desktop range: 800w - 1200w (step 200w) - desktop coverage
-      { min: 800, max: 1200, step: 200, dpr: [1], category: 'desktop' },
-      
-      // High-res range: 1200w - 1600w (step 200w) with selective 2x - practical high-res
-      { min: 1200, max: 1600, step: 200, dpr: [1, 2], category: 'high-res' }
-    ];
+    // Calculate maximum reasonable size for this container
+    // Use a multiplier to allow for some flexibility while staying close to container size
+    const maxSizeMultiplier = 1.5; // Allow up to 1.5x the container size
+    const maxReasonableWidth = Math.min(
+      Math.round(currentWidth * maxSizeMultiplier),
+      naturalWidth
+    );
+    
+    // Define size ranges based on container size
+    let sizeRanges = [];
+    
+    if (currentWidth <= 300) {
+      // Small containers (thumbnails, icons, etc.)
+      sizeRanges = [
+        { min: Math.max(200, Math.round(currentWidth * 0.8)), max: Math.round(currentWidth * 1.2), step: 25, dpr: [1], category: 'small' },
+        { min: Math.round(currentWidth * 1.2), max: maxReasonableWidth, step: 50, dpr: [1, 2], category: 'small-retina' }
+      ];
+    } else if (currentWidth <= 600) {
+      // Medium containers (cards, medium images)
+      sizeRanges = [
+        { min: Math.max(200, Math.round(currentWidth * 0.8)), max: Math.round(currentWidth * 1.2), step: 50, dpr: [1], category: 'medium' },
+        { min: Math.round(currentWidth * 1.2), max: maxReasonableWidth, step: 100, dpr: [1, 2], category: 'medium-retina' }
+      ];
+    } else if (currentWidth <= 1000) {
+      // Large containers (featured images, banners)
+      sizeRanges = [
+        { min: Math.max(200, Math.round(currentWidth * 0.8)), max: Math.round(currentWidth * 1.2), step: 100, dpr: [1], category: 'large' },
+        { min: Math.round(currentWidth * 1.2), max: maxReasonableWidth, step: 200, dpr: [1, 2], category: 'large-retina' }
+      ];
+    } else {
+      // Very large containers (full-width images)
+      sizeRanges = [
+        { min: Math.max(200, Math.round(currentWidth * 0.8)), max: Math.round(currentWidth * 1.2), step: 200, dpr: [1], category: 'xlarge' },
+        { min: Math.round(currentWidth * 1.2), max: maxReasonableWidth, step: 400, dpr: [1, 2], category: 'xlarge-retina' }
+      ];
+    }
 
     // Generate sizes for each range
     sizeRanges.forEach(range => {
@@ -358,13 +438,25 @@ export const optmlSrcsetDetector = {
           if (this._isValidSize(targetWidth, targetHeight, naturalWidth, naturalHeight) &&
               targetWidth >= this.CONFIG.MIN_SIZE) {
 
-            // Determine breakpoint based on width
+            // Determine breakpoint based on container size, not image size
+            // Use viewport-based breakpoints that make sense for the container
             let breakpoint = null;
-            if (targetWidth <= 400) breakpoint = 320;
-            else if (targetWidth <= 600) breakpoint = 768;
-            else if (targetWidth <= 900) breakpoint = 1024;
-            else if (targetWidth <= 1200) breakpoint = 1440;
-            else breakpoint = 1920;
+            if (currentWidth <= 300) {
+              // Small containers: use smaller breakpoints
+              if (targetWidth <= currentWidth * 1.1) breakpoint = 480;
+              else if (targetWidth <= currentWidth * 1.3) breakpoint = 768;
+              else breakpoint = 1024;
+            } else if (currentWidth <= 600) {
+              // Medium containers: use medium breakpoints
+              if (targetWidth <= currentWidth * 1.1) breakpoint = 768;
+              else if (targetWidth <= currentWidth * 1.3) breakpoint = 1024;
+              else breakpoint = 1440;
+            } else {
+              // Large containers: use larger breakpoints
+              if (targetWidth <= currentWidth * 1.1) breakpoint = 1024;
+              else if (targetWidth <= currentWidth * 1.3) breakpoint = 1440;
+              else breakpoint = 1920;
+            }
 
             sizes.push({
               w: targetWidth,

inc/rest.php

@@ -946,6 +946,7 @@ public function optimizations( WP_REST_Request $request ) {
 		}
 		$bg_selectors = $request->get_param( 'b' );
 		$lcp_data = $request->get_param( 'l' );
+		$crop_status = $request->get_param( 'c' );
 		$origin = $request->get_header( 'origin' );
 		if ( empty( $origin ) || ! is_allowed_http_origin( $origin ) ) {
 			return $this->response( 'Invalid origin', 'error' );
@@ -1007,6 +1008,12 @@ function ( $url ) {
 				$sanitized_missing_srcsets[ intval( $id ) ] = $srcset;
 			}
 		}
+		$sanitized_crop_status = [];
+		if ( ! empty( $crop_status ) ) {
+			foreach ( $crop_status as $id => $crop ) {
+				$sanitized_crop_status[ intval( $id ) ] = (bool) $crop;
+			}
+		}
 		$sanitized_lcp_data = [];
 		if ( ! empty( $lcp_data ) ) {
 			$sanitized_lcp_data['imageId'] = sanitize_text_field( $lcp_data['i'] ?? '' );
@@ -1025,10 +1032,10 @@ function ( $url ) {
 		}
 
 		if ( OPTML_DEBUG ) {
-			do_action( 'optml_log', 'Storing profile data: ' . $url . ' - ' . $device_type . ' - ' . print_r( $above_fold_images, true ) . print_r( $sanitized_selectors, true ) . print_r( $sanitized_lcp_data, true ) . print_r( $sanitized_missing_dimensions, true ) . print_r( $sanitized_missing_srcsets, true ) );
+			do_action( 'optml_log', 'Storing profile data: ' . $url . ' - ' . $device_type . ' - ' . print_r( $above_fold_images, true ) . print_r( $sanitized_selectors, true ) . print_r( $sanitized_lcp_data, true ) . print_r( $sanitized_missing_dimensions, true ) . print_r( $sanitized_missing_srcsets, true ) . print_r( $sanitized_crop_status, true ) );
 		}
 		$profile = new Profile();
-		$profile->store( $url, $device_type, $above_fold_images, $sanitized_selectors, $sanitized_lcp_data, $sanitized_missing_dimensions, $sanitized_missing_srcsets );
+		$profile->store( $url, $device_type, $above_fold_images, $sanitized_selectors, $sanitized_lcp_data, $sanitized_missing_dimensions, $sanitized_missing_srcsets, $sanitized_crop_status );
 		return $this->response( 'Above fold data stored successfully' );
 	}