release: fixes

- Added a static cache (Optml_Settings) to avoid repeated get_option calls within a single request, improving performance and consistency.
- Fixed a potential PHP 8.2+ fatal error in get_svg_for by ensuring $sizes is always an array before destructuring (e.g. when images are missing or offloaded). Props to [@fuleinist](https://github.com/fuleinist) for the contribution.
- Improved optmlSrcsetDetector logic to prevent generating 1x DPR images larger than the original size, fixing incorrect srcset capping. Props to [@fuleinist](https://github.com/fuleinist) for the contribution.
- Fixed incorrect notice display when disabling the scaling option.

Author: selul

.distignore

@@ -49,3 +49,4 @@ test-results
 wp-scripts.config.js
 README.md
 CHANGELOG.md
+AGENTS.md

AGENTS.md

@@ -0,0 +1,139 @@
+# Agent Workflow
+
+## What This Is
+
+Optimole WordPress plugin — cloud-based image optimization with CDN delivery, lazy loading, WebP/AVIF conversion, media offloading, and a Digital Asset Management (DAM) interface. Requires a supported PHP and WordPress version; see the plugin header or readme for the current version and system requirements.
+
+## Build & Dev Commands
+
+```bash
+# Install dependencies
+npm install && composer install
+
+# Build all assets (production)
+npm run build
+
+# Development with HMR (all targets in parallel)
+npm run dev
+
+# Build individual targets
+npm run build:dashboard    # Admin settings UI
+npm run build:widget       # Dashboard widget
+npm run build:media        # Media library integration
+npm run build:optimizer    # Frontend lazy loading script
+npm run build:video-player-editor
+npm run build:video-player-frontend
+```
+
+## Testing
+
+```bash
+# PHP unit tests (requires WP test suite)
+composer phpunit
+composer install-wp-tests          # First-time setup
+
+# Run a specific PHP test file
+composer phpunit -- tests/test-replacer.php
+
+# Run a specific test method
+composer phpunit -- --filter="test_method_name"
+
+# JavaScript tests
+npm test
+npm run test:watch
+npm run test:coverage
+
+# E2E tests (Playwright — configure use.baseURL in playwright.config.ts to your local WP URL; do not run against the shared http://testing.optimole.com by default)
+npm run e2e:run
+npm run e2e:open                   # Interactive UI mode
+```
+
+## Linting & Static Analysis
+
+```bash
+# JavaScript
+npm run lint                       # ESLint
+npm run format                     # ESLint --fix
+
+# PHP
+composer phpcs                     # PHP CodeSniffer (WordPress-Core standard)
+composer format                    # Auto-fix with phpcbf
+composer phpstan                   # PHPStan level 6
+```
+
+## Architecture
+
+### Two-era codebase: v1 (legacy) and v2 (modern)
+
+**Legacy code (`inc/*.php`)** — Class prefix `Optml_*`, loaded by custom autoloader in `optimole-wp.php`. This is the bulk of the plugin.
+
+**Modern code (`inc/v2/`)** — PSR-4 autoloaded under `OptimoleWP\` namespace via Composer. New features should go here.
+
+### Plugin initialization flow
+
+```
+optimole-wp.php → optml() → Optml_Main::instance() (singleton)
+  ├── Optml_Manager      — Orchestrates replacers and loads compatibilities
+  ├── Optml_Admin         — Admin dashboard UI, conflict detection
+  ├── Optml_Rest          — REST API endpoints for the dashboard
+  ├── Optml_Media_Offload — Cloud offloading/restoration of media
+  ├── Optml_Dam           — Digital Asset Management UI
+  ├── Optml_Video_Player  — Video player blocks
+  └── Optml_Cli           — WP-CLI commands (when available)
+```
+
+### Core subsystems
+
+- **URL/Tag replacement** (`tag_replacer.php`, `url_replacer.php`, `app_replacer.php`) — Parses HTML output, rewrites image URLs to Optimole CDN URLs with optimization parameters.
+- **Lazy loading** (`lazyload_replacer.php`, `inc/v2/BgOptimizer/`) — Viewport-based and background-image lazy loading. Frontend JS in `assets/js/optimizer.js`.
+- **Media offloading** (`media_offload.php`) — Moves media to/from Optimole cloud storage, handles bulk operations.
+- **Settings** (`settings.php`) — Central settings schema and management, stores in `wp_options`.
+- **Compatibility layer** (`inc/compatibilities/`) — 47+ integrations for page builders (Elementor, Divi, Beaver Builder), caching plugins (WP Rocket, LiteSpeed), WooCommerce, etc. Each extends `Optml_compatibility`.
+
+### Frontend assets (`assets/src/`)
+
+React-based, built with `@wordpress/scripts`:
+- `dashboard/` — Main admin settings page (React + @wordpress/components)
+- `widget/` — Admin dashboard widget
+- `media/` — Media library DAM integration
+- `video-player/` — Editor and frontend video player blocks
+
+Built output goes to `assets/build/`. The `assets/js/optimizer.js` is the frontend lazy-loading script.
+
+## Task Routing (Where to Start)
+
+- Bootstrap/hooks: `optimole-wp.php`, `inc/main.php`, `inc/manager.php`, `inc/filters.php`.
+- URL/CDN rewriting: `inc/tag_replacer.php`, `inc/url_replacer.php`, `inc/app_replacer.php` + `tests/test-replacer.php`.
+- Lazyload: `inc/lazyload_replacer.php`, `inc/v2/BgOptimizer/Lazyload.php`, `assets/js/optimizer.js` + `tests/test-lazyload.php`.
+- Admin/REST/settings: `inc/admin.php`, `inc/rest.php`, `inc/settings.php`, `assets/src/dashboard/`.
+- Media/DAM: `inc/media_offload.php`, `inc/dam.php`, `assets/src/media/`.
+- Compat/conflicts: `inc/compatibilities/`, `inc/conflicts/`, related `tests/e2e/*.spec.ts`.
+- Video player: `inc/video_player.php`, `assets/src/video-player/`, `tests/test-video.php`.
+
+## Security Checklist (WordPress-Specific)
+
+- State-changing actions: capability check + nonce verification.
+- Input/output: sanitize on input, escape on output.
+- REST: always set strict `permission_callback` for write routes.
+- SQL: use `$wpdb->prepare()` for dynamic queries.
+- Safety: do not leak secrets/tokens; validate remote and file/media operations before mutate/delete.
+
+## Agent Execution Policy
+
+- Keep changes surgical; avoid unrelated refactors/cleanups.
+- Prefer `inc/v2/` for new logic unless legacy coupling forces `inc/*.php`.
+- Trace hooks and callsites before editing behavior.
+- Add/update the smallest relevant test and run targeted checks first.
+- Build only touched frontend targets; call out intentional build artifacts.
+
+## Code Standards
+
+- **PHP**: WordPress-Core via PHPCS. Text domain: `optimole-wp`.
+- **JS**: WordPress ESLint config. Tabs, single quotes, semicolons.
+- **v2 PHP code** requires PHPStan-compatible PHPDoc annotations, full namespace paths, type hints, and constants for magic values (e.g., `Profile::DEVICE_TYPE_MOBILE` not `1`).
+- Error handling: return `WP_Error` for WordPress-compatible errors, `false` for simple failures.
+- Debug logging: `do_action( 'optml_log', $message )` when `OPTML_DEBUG` is true.
+
+## Key Constants
+
+Defined in `optimole-wp.php`: `OPTML_URL`, `OPTML_PATH`, `OPTML_VERSION`, `OPTML_NAMESPACE` (`'optml'`), `OPTML_BASEFILE`, `OPTML_DEBUG`, `OPTML_DEBUG_MEDIA`.

assets/js/modules/srcset-detector.js

@@ -437,9 +437,10 @@ export const optmlSrcsetDetector = {
         const targetWidth = Math.round(baseWidth * dprValue);
         const targetHeight = Math.round(targetWidth / aspectRatio);
 
-        // Don't generate 1x DPR variations larger than current size
+        // Don't generate 1x DPR variations larger than natural image size
         // But allow 2x DPR variations for retina displays
-        if (dprValue === 1 && targetWidth > currentWidth) {
+        // Fixes: srcset capped at profiling container width (issue #1030)
+        if (dprValue === 1 && targetWidth > naturalWidth) {
           return;
         }
 

assets/src/dashboard/parts/connected/settings/Lazyload.js

@@ -204,7 +204,7 @@ const Lazyload = ({ settings, setSettings, setCanSave }) => {
 					labels={{
 						title: options_strings.performance_impact_alert_title,
 						description:
-							'scale' === showModal ?
+							DISABLE_OPTION_MODAL_TYPE.scale === showModal ?
 								options_strings.performance_impact_alert_scale_desc :
 								options_strings.performance_impact_alert_lazy_desc,
 						action: options_strings.performance_impact_alert_action_label,

inc/lazyload_replacer.php

@@ -529,7 +529,11 @@ public function get_svg_for( $width, $height, $url = null ) {
 					wp_cache_add( $key, [ $sizes[0], $sizes[1] ], 'optml_sources', DAY_IN_SECONDS );
 				}
 			}
-			list( $width, $height ) = $sizes;
+			// Check if $sizes is an array before list() assignment to prevent fatal error on PHP 8.2+
+			// when the image file is missing (e.g., offloaded to CDN or deleted).
+			if ( is_array( $sizes ) ) {
+				list( $width, $height ) = $sizes;
+			}
 		}
 		// If the width is not found the url might be an offloaded attachment so we can get the width and height from the metadata.
 		if ( ! is_numeric( $width ) && ! empty( $url ) ) {

inc/manager.php

@@ -407,7 +407,7 @@ public function register_hooks() {
 		);
 		add_action( 'template_redirect', [ $this, 'register_after_setup' ] );
 		add_action( 'rest_api_init', [ $this, 'process_template_redirect_content' ], PHP_INT_MIN );
-		add_action( 'shutdown', [ $this, 'close_buffer' ] );
+		add_action( 'shutdown', [ $this, 'close_buffer' ], PHP_INT_MIN );
 		foreach ( self::$loaded_compatibilities as $registered_compatibility ) {
 			$registered_compatibility->register();
 		}

inc/settings.php

@@ -119,6 +119,13 @@ class Optml_Settings {
 	 */
 	private static $options;
 
+	/**
+	 * Cache for site settings to avoid multiple calls to get_option on the same request.
+	 *
+	 * @var array<string, mixed>|null Cached site settings.
+	 */
+	private static $site_settings_cache = null;
+
 	/**
 	 * Optml_Settings constructor.
 	 */
@@ -440,6 +447,7 @@ public function update_frontend_banner_from_remote( $value ) {
 
 		if ( $update ) {
 			self::$options = $opts;
+			$this->set_settings_cache( 'banner_frontend', $opts['banner_frontend'] );
 		}
 
 		return $update;
@@ -476,6 +484,7 @@ public function update( $key, $value ) {
 
 		if ( $update ) {
 			self::$options = $opt;
+			$this->set_settings_cache( $key, $value );
 		}
 		if ( apply_filters( 'optml_dont_trigger_settings_updated', false ) === false ) {
 			/**
@@ -527,13 +536,17 @@ private function is_main_mu_site() {
 	 * @return array Site settings.
 	 */
 	public function get_site_settings() {
+		if ( self::$site_settings_cache !== null ) {
+			return self::$site_settings_cache;
+		}
+
 		$service_data = $this->get( 'service_data' );
 		$whitelist    = [];
 		if ( isset( $service_data['whitelist'] ) ) {
 			$whitelist = $service_data['whitelist'];
 		}
 
-		return [
+		self::$site_settings_cache = [
 			'quality'                    => $this->get_quality(),
 			'admin_bar_item'             => $this->get( 'admin_bar_item' ),
 			'lazyload'                   => $this->get( 'lazyload' ),
@@ -578,6 +591,7 @@ public function get_site_settings() {
 			'show_badge_icon'            => $this->get( 'show_badge_icon' ),
 			'badge_position'             => $this->get( 'badge_position' ),
 		];
+		return self::$site_settings_cache;
 	}
 
 	/**
@@ -747,6 +761,7 @@ public function reset() {
 		$update = update_option( $this->namespace, $reset_schema );
 		if ( $update ) {
 			self::$options = $reset_schema;
+			$this->set_settings_cache( 'filters', $reset_schema['filters'] );
 		}
 		wp_unschedule_hook( Optml_Admin::SYNC_CRON );
 		wp_unschedule_hook( Optml_Admin::ENRICH_CRON );
@@ -872,4 +887,17 @@ public function get_cloud_sites_whitelist_default() {
 			$site_url => 'true',
 		];
 	}
+
+	/**
+	 * Set settings cache value.
+	 *
+	 * @param string $key Cache key.
+	 * @param mixed  $value Cache value.
+	 * @return void
+	 */
+	private function set_settings_cache( $key, $value ) {
+		if ( self::$site_settings_cache !== null && isset( self::$site_settings_cache[ $key ] ) ) {
+			self::$site_settings_cache[ $key ] = $value;
+		}
+	}
 }