New Release

.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,16 +33,19 @@ tests
 dist
 artifact
 assets/src
+assets/js/modules/__tests__
+coverage
 .wporg
 .nvmrc
 .github
 .eslintrc
 postcss.config.js
 tailwind.config.js
 phpstan.neon
+phpstan-baseline.neon
 development.php
 playwright.config.ts
 test-results
 wp-scripts.config.js
 README.md
-CHANGELOG.md
+CHANGELOG.md

.eslintrc

@@ -11,7 +11,7 @@
 		"ecmaVersion": 2021,
 		"sourceType": "module"
 	},
-	"ignorePatterns": [ "node_modules", "assets/js"  ],
+	"ignorePatterns": [ "node_modules", "assets/js", "**/*.d.ts"  ],
 	"rules": {
 		"camelcase" : "off",
 		"indent": [

.github/workflows/deploy.yml

@@ -25,3 +25,24 @@ jobs:
         env:
           SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }}
           SVN_USERNAME: ${{ secrets.SVN_USERNAME }}
+      - name: Make dist
+        run: npm run dist
+      - name: Upload Latest Version to S3
+        uses: jakejarvis/s3-sync-action@master
+        with:
+          args: --acl public-read --follow-symlinks --delete
+        env:
+          AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET_DOWNLOADS }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.S3_DOWNLOADS_AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.S3_DOWNLOADS_AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: "us-west-1" # optional: defaults to us-east-1
+          SOURCE_DIR: "artifact" # optional: defaults to entire repository
+          DEST_DIR: products/optimole-wp/latest
+      - name: Clear Cloudfront Cache
+        uses: chetan/invalidate-cloudfront-action@v2
+        env:
+          DISTRIBUTION: ${{ secrets.API_DIST_ID }}
+          PATHS: "/download/optimole/*"
+          AWS_REGION: "us-east-1"
+          AWS_ACCESS_KEY_ID: ${{ secrets.S3_DOWNLOADS_AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.S3_DOWNLOADS_AWS_SECRET_ACCESS_KEY }}

.github/workflows/test-eslint.yml → .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
+

.github/workflows/test-php.yml

@@ -56,14 +56,22 @@ jobs:
     name: PHPStan on PHP 8.0
     runs-on: ubuntu-latest
     steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
       - name: Setup PHP version
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.0'
           extensions: simplexml, mysql
-      - name: Checkout source code
-        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - name: Create the build file
+        run: |
+          npm ci
+          npm run build
       - name: Install Composer dependencies
         run: composer install --prefer-dist --no-progress --no-suggest
       - name: PHPStan Static Analysis
-        run: composer phpstan
+        run: composer phpstan

.gitignore

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

assets/js/modal-attachment.js

@@ -0,0 +1,69 @@
+jQuery(document).ready(function($) {
+    if (!$('body').hasClass('upload-php')) {
+        return;
+    }
+
+    /**
+     * Helper function to add Replace or Rename button to attachment actions
+     * @param {Object} view - The attachment view instance
+     */
+    function addReplaceRenameButton(view) {
+        var $el = view.$el;
+        var $actions = $el.find('.actions');
+
+        if (!$actions.length || $actions.find('.optml-replace-rename-link').length) {
+            return;
+        }
+
+        var attachmentId = view.model.get('id');
+
+        if (!attachmentId) {
+            return;
+        }
+
+        var editUrl = OptimoleModalAttachment.editPostURL + '?post=' + attachmentId + 
+                     '&action=edit&TB_iframe=true&width=90%&height=90%';
+
+        var $editLink = $actions.find('a[href*="post.php"]');
+
+        if ($editLink.length) {
+            $editLink.after(
+                ' <span class="links-separator">|</span>' +
+                '<a href="' + editUrl + '" class="optml-replace-rename-link thickbox" title="' + 
+                OptimoleModalAttachment.i18n.replaceOrRename + '"> ' +
+                OptimoleModalAttachment.i18n.replaceOrRename + '</a>'
+            );
+        }
+    }
+
+    /**
+     * Extend a WordPress media view with Replace/Rename functionality
+     * @param {Object} OriginalView - The original view to extend
+     * @returns {Object} Extended view
+     */
+    function extendMediaView(OriginalView) {
+        return OriginalView.extend({
+            initialize: function() {
+                OriginalView.prototype.initialize.apply(this, arguments);
+            },
+
+            render: function() {
+                OriginalView.prototype.render.apply(this, arguments);
+                addReplaceRenameButton(this);
+                return this;
+            }
+        });
+    }
+
+    var originalAttachmentDetails = wp.media.view.Attachment.Details;
+    wp.media.view.Attachment.Details = extendMediaView(originalAttachmentDetails);
+
+    if (wp.media.view.Attachment.Details.TwoColumn) {
+        var originalTwoColumn = wp.media.view.Attachment.Details.TwoColumn;
+        wp.media.view.Attachment.Details.TwoColumn = extendMediaView(originalTwoColumn);
+    }
+
+    $(document).on('click', '.optml-replace-rename-link.thickbox', function() {
+        tb_init('a.thickbox');
+    });
+});

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
+}
+```
+