Merge pull request #960 from Codeinwp/feat/improved_scaling

Feat/improved scaling

Author: selul

.distignore

@@ -17,6 +17,8 @@ phpcs.xml
 phpunit.xml
 phpunit-cc.xml
 phpmd.xml
+jest.config.js
+jest.setup.js
 package.json
 package-lock.json
 composer.json
@@ -31,6 +33,8 @@ tests
 dist
 artifact
 assets/src
+assets/js/modules/__tests__
+coverage
 .wporg
 .nvmrc
 .github

.github/workflows/test-eslint.yml renamed to .github/workflows/test-js.yml

@@ -1,4 +1,4 @@
-name: ESLint
+name: JavaScript Tests
 
 on:
   pull_request:
@@ -9,21 +9,36 @@ on:
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
   cancel-in-progress: true
+
 jobs:
-  run:
-    if: github.event.pull_request.draft == false
+  test:
+    if: github.event_name == 'push' || github.event.pull_request.draft == false
     runs-on: ubuntu-latest
-    name: ESLint
+    name: ESLint & Jest Tests
     steps:
-      - uses: actions/checkout@master
+      - uses: actions/checkout@v3
         with:
           persist-credentials: false
+
       - name: Setup Node
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v3
         with:
           node-version: 18
-      - name: Lint js files
+          cache: 'npm'
+
+      - name: Install dependencies
         run: |
-          npm install -g npm
           npm ci
+
+      - name: Run ESLint
+        run: |
           npm run lint
+
+      - name: Run unit tests
+        run: |
+          npm test
+
+      - name: Run tests with coverage
+        run: |
+          npm run test:coverage
+

.gitignore

@@ -11,4 +11,5 @@ build
 cc-test-reporter
 assets/build
 test-results
-tests/assets/filestash
+tests/assets/filestash
+coverage

assets/js/modules/AGENTS.md

@@ -0,0 +1,14 @@
+# Optimole JavaScript Modules - Agent Instructions
+
+
+## Code standards
+- **CRITICAL**: All functions must have JSDoc comments with `@param` and `@return` annotations
+- Use ES6 modules with `import`/`export` syntax
+- Follow camelCase naming for functions and variables
+- Use `const`/`let` instead of `var`
+- Always handle errors gracefully with try/catch blocks
+- Use descriptive variable names and avoid abbreviations
+
+## Testing instructions
+- Use only unit tests
+ 

assets/js/modules/README.md

@@ -0,0 +1,162 @@
+# Optimole JavaScript Modules
+
+This directory contains the modular JavaScript components for the Optimole image optimizer. 
+
+## Module Structure
+
+### Core Modules
+
+#### `logger.js`
+- **Purpose**: Centralized logging functionality with debug mode support
+- **Exports**: `optmlLogger` object
+- **Key Features**:
+  - Debug mode detection via URL params or localStorage
+  - Structured logging with prefixes
+  - Table logging support
+  - Conditional logging based on debug state
+
+#### `storage.js`
+- **Purpose**: Session storage management for tracking processed pages
+- **Exports**: `optmlStorage` object
+- **Key Features**:
+  - Generate unique storage keys for URL/device combinations
+  - Check if page/device combinations have been processed
+  - Mark combinations as processed with timestamps
+  - Error handling for storage operations
+
+#### `device.js`
+- **Purpose**: Device type detection based on screen width
+- **Exports**: `optmlDevice` object
+- **Key Features**:
+  - Mobile/desktop detection using 600px breakpoint
+  - Device type constants (MOBILE: 1, DESKTOP: 2)
+  - Helper methods for device type checking
+  - PageSpeed Insights compatible detection logic
+
+#### `api.js`
+- **Purpose**: REST API communication with fallback mechanisms
+- **Exports**: `optmlApi` object
+- **Key Features**:
+  - Primary sendBeacon API for reliable data transmission
+  - Fetch API fallback for when sendBeacon fails
+  - Automatic storage marking on successful sends
+  - Error handling and logging
+
+#### `dom-utils.js`
+- **Purpose**: DOM manipulation and utility functions
+- **Exports**: `optmlDomUtils` object
+- **Key Features**:
+  - Debounce utility for performance optimization
+  - Unique CSS selector generation for elements
+  - Background image detection and URL extraction
+  - Page condition checking (viewport, visibility, load state)
+  - Promise-based waiting utilities
+
+### Specialized Modules
+
+#### `background.js`
+- **Purpose**: Background image handling and lazy loading observation
+- **Exports**: `optmlBackground` object
+- **Key Features**:
+  - Background image lazy loading detection
+  - Mutation observer setup for class changes
+  - URL extraction from background images
+  - Selector processing and element observation
+
+#### `lcp.js`
+- **Purpose**: Largest Contentful Paint (LCP) element detection
+- **Exports**: `optmlLcp` object
+- **Key Features**:
+  - Performance Observer integration
+  - LCP element identification and processing
+  - Support for both image and background image LCP elements
+  - Timeout handling for LCP detection
+
+#### `image-detector.js`
+- **Purpose**: Image detection and dimension analysis
+- **Exports**: `optmlImageDetector` object
+- **Key Features**:
+  - Missing dimension detection for images
+  - Intersection Observer setup for above-fold detection
+  - Optimole image observation (`data-opt-id` attributes)
+  - Cleanup utilities for temporary attributes
+
+#### `srcset-detector.js`
+- **Purpose**: Srcset analysis and missing variation detection for eligible images
+- **Exports**: `optmlSrcsetDetector` object
+- **Key Features**:
+  - Smart image detection with improved skip logic:
+    - 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
+    - Desktop range: 800w-1200w (200w steps) for desktop screens
+    - High-res range: 1200w-1600w (200w steps) with strategic 2x DPR
+  - Configurable generation settings:
+    - `widthStepSize`: Step size for width variations (default: 100px)
+    - `minSize`: Minimum image size to consider (default: 200px)
+    - `maxVariations`: Maximum srcset variations per image (default: 8)
+    - `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
+
+#### `main.js`
+- **Purpose**: Main orchestrator coordinating all functionality
+- **Exports**: `optmlMain` object
+- **Key Features**:
+  - Complete above-the-fold detection workflow
+  - Module coordination and data aggregation
+  - 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
+}
+```
+