jekyll-imgflow 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa56ff31b7cfe312dfe202726e049c99db5511dc35b2e82d721abde41c76488e
-  data.tar.gz: 88ff3c89e44a1dfe0fe022a016bbeba79185c137bca201c4e2c66c9d06cc5a92
+  metadata.gz: 8400a4bc3d213b557802452b3af0816098443aa5542f27e81bf690dd2ee3f7a8
+  data.tar.gz: 1f8562de9d69d7451603623ab2e63741f4889a4d04d35d9ae01a561878e8d539
 SHA512:
-  metadata.gz: c1f92e12c629652780356a972969ee435992b29dd62dea03ea263582084e8b512b35eb25e8bb1845c111834a5506cd1c3ffd5c9b4c5392ff6e17e20d3ea5c4ae
-  data.tar.gz: 92b73297116fd7dd7d38a5aeb349c81aeab97709f3a85886469dc0443e3fa9e5e35c2c971b1c01bd6682db2c59776c54112682a31e3610c64a6254b3d4067441
+  metadata.gz: cbd0f3c0d194bd7acfdc199c9c1eb78dcb69d09c4cc9f213ceb48d1c1c5cb4402518a87a14f44f234df1487ae6eba4495f92aae2b31bb602b199bcaaab4438ef
+  data.tar.gz: 7c07124101bf734ebedce868d1329900c79acde6d90463d5fbd680fe49f02517e743ba4d7d37ebf3e26454e3e9dd4df80ada8265874bb96b1659767a33a8306f

data/README.md

@@ -6,6 +6,8 @@ A [Jekyll](https://jekyllrb.com/) plugin for automatic image optimization with m
 
 [![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gundestrup/jekyll-imgflow)
 [![Status](https://img.shields.io/badge/status-active-success)](https://github.com/gundestrup/jekyll-imgflow)
+[![Semgrep](https://img.shields.io/badge/Semgrep-scanned-1B2B34?logo=semgrep&logoColor=white)](https://semgrep.dev/)
+[![CodeFactor](https://www.codefactor.io/repository/github/gundestrup/jekyll-imgflow/badge)](https://www.codefactor.io/repository/github/gundestrup/jekyll-imgflow)
 [![codecov](https://codecov.io/gh/gundestrup/jekyll-imgflow/branch/main/graph/badge.svg)](https://codecov.io/gh/gundestrup/jekyll-imgflow)
 [![VS Code Extension](https://img.shields.io/badge/VS%20Code%20Companion-jekyll--imgflow-blue?logo=visual-studio-code)](https://github.com/gundestrup/jekyll-imgflow-vscode)
 [![License](https://img.shields.io/github/license/gundestrup/jekyll-imgflow)](LICENSE)
@@ -96,6 +98,28 @@ ImgFlow has two processing flows: **Build-Time** (pre-generation) and **Runtime*
 
 **See:** [providers.md](docs/providers.md) for detailed provider comparison and setup
 
+### SVG File Handling
+
+SVG files are supported as input by all providers. Since SVGs are vector
+graphics, they are rasterized before format conversion (WebP, AVIF, JPG, PNG).
+
+- **Weserv** (via librsvg): When an SVG has no explicit pixel dimensions
+  (e.g. `width="100%"` with a large `viewBox`), ImgFlow automatically
+  caps the rasterization at 2000px wide to prevent memory exhaustion.
+  If a resize or crop operation is present, the target dimensions are used
+  directly.
+- **Sharp, LibVips, Imgproxy, Flyimg**: Handle SVGs via their respective
+  rasterization backends. SVGs with very large viewBox dimensions may be
+  slow or fail depending on the provider's memory limits.
+- **ImageMagick**: SVG processing is slower than other providers without
+  the `librsvg` delegate installed. Set `FULL_SVG_TEST=true` to include
+  SVGs in ImageMagick test runs.
+
+SVGs with explicit `width` and `height` attributes (in pixels, not
+percentages) are always processed at the specified size first, then resized
+to the target dimensions — this is the recommended way to author SVGs for
+image processing.
+
 ## 🚀 Quick Commands
 
 ```bash
@@ -202,8 +226,15 @@ bundle install
 # Download test images
 rake download_test_images
 
-# Run tests
-rake quick
+# Run the CI-equivalent checks locally
+rake ci
+
+# Run the local Semgrep Pro rules directly
+semgrep scan --pro --config .semgrep.yml --error lib/
+
+# Sync the repository scan and findings with the Semgrep dashboard
+# (requires semgrep login or SEMGREP_APP_TOKEN)
+semgrep ci
 ```
 
 ### Key Files

data/lib/jekyll-imgflow/build_time_processor.rb

@@ -78,8 +78,9 @@ module JekyllImgFlow
       results = @batch_manager.process_all
       register_skipped_tasks(@batch_manager.completed)
 
-      # Save manifest so it's available when ImgflowTag runs
-      @manifest.save
+      # Persist newly processed defaults; unchanged builds keep page-usage resets in memory
+      # until post_write saves the final stable manifest.
+      @manifest.save unless results[:completed].zero? && results[:failed].zero?
 
       Jekyll.logger.info "✅ BuildTimeProcessor complete: #{results[:completed]} completed, #{results[:failed]} failed"
 

data/lib/jekyll-imgflow/config.rb

@@ -28,33 +28,40 @@ module JekyllImgFlow
                 :optimize_qualities, :fallback_format, :image_modal
 
     def initialize(site)
-      shared = site.config["shared_images_configs"] || {}
-      overrides = site.config["imgflow"] || {}
-      cfg = shared.merge(overrides)
-
-      @site             = site
-      @originals        = cfg["originals"] || DEFAULT_ORIGINALS
-      @output           = cfg["output"] || DEFAULT_OUTPUT
-      @input_formats    = cfg["input_formats"] || DEFAULT_INPUT_FORMATS
-      @sizes            = cfg["sizes"] || DEFAULT_SIZES
-      @formats          = cfg["formats"] || DEFAULT_FORMATS
-      @quality          = cfg["quality"] || DEFAULT_QUALITY
+      @site = site
+      cfg = merged_config
+      assign_core_config(cfg)
+      assign_provider_config(cfg)
+      @optimize_qualities = cfg["optimize_qualities"] || default_optimize_qualities
+      validate_backend_priority!
+    end
+
+    def assign_core_config(cfg)
+      @originals = cfg["originals"] || DEFAULT_ORIGINALS
+      @output = cfg["output"] || DEFAULT_OUTPUT
+      @input_formats = cfg["input_formats"] || DEFAULT_INPUT_FORMATS
+      @sizes = cfg["sizes"] || DEFAULT_SIZES
+      @formats = cfg["formats"] || DEFAULT_FORMATS
+      @quality = cfg["quality"] || DEFAULT_QUALITY
       @backend_priority = cfg["backend_priority"] || DEFAULT_BACKEND_PRIORITY
-      @fallback_format  = cfg["fallback_format"] || DEFAULT_FALLBACK_FORMAT
-      @image_modal      = cfg.fetch("image_modal", DEFAULT_IMAGE_MODAL)
+      @fallback_format = cfg["fallback_format"] || DEFAULT_FALLBACK_FORMAT
+      @image_modal = cfg.fetch("image_modal", DEFAULT_IMAGE_MODAL)
+    end
 
+    def assign_provider_config(cfg)
       @imgproxy_url = cfg["imgproxy_url"]
-      @weserv_url       = cfg["weserv_url"]
-      @flyimg_url       = cfg["flyimg_url"]
-      @optimize_qualities = cfg["optimize_qualities"] || {
+      @weserv_url = cfg["weserv_url"]
+      @flyimg_url = cfg["flyimg_url"]
+    end
+
+    def default_optimize_qualities
+      {
         "low" => 30,
         "medium" => 50, # Uses default quality
         "high" => 85, # Uses default quality
         "maximum" => 95,
         "default" => 75
       }
-
-      validate_backend_priority!
     end
 
     def cache_dir

data/lib/jekyll-imgflow/filename_generator.rb

@@ -83,6 +83,7 @@ module JekyllImgFlow
     def generate_jpt_hash(original_path, operations)
       # Get filename digest (MD5 of filename) - exactly like JPT
       filename = File.basename(original_path)
+      # nosemgrep: ruby.lang.security.weak-hashes-md5.weak-hashes-md5 -- Jekyll Picture Tag filename compatibility, not security.
       file_digest = Digest::MD5.hexdigest(filename)
 
       # Build settings array (like Jekyll Picture Tag)
@@ -94,6 +95,7 @@ module JekyllImgFlow
       ]
 
       # Generate MD5 hash of settings (9 chars like JPT)
+      # nosemgrep: ruby.lang.security.weak-hashes-md5.weak-hashes-md5 -- Jekyll Picture Tag filename compatibility, not security.
       Digest::MD5.hexdigest(settings.join)[0..8]
     end
   end

data/lib/jekyll-imgflow/html_generator.rb

@@ -76,15 +76,15 @@ module JekyllImgFlow
       return default_attributes if attributes.nil? || attributes.empty?
 
       {
-        img: attributes[:img] || {},
-        picture: attributes[:picture] || {},
-        source: attributes[:source] || {},
-        a: attributes[:a] || {},
-        parent: attributes[:parent] || {},
+        img: attributes.fetch(:img, {}),
+        picture: attributes.fetch(:picture, {}),
+        source: attributes.fetch(:source, {}),
+        a: attributes.fetch(:a, {}),
+        parent: attributes.fetch(:parent, {}),
         alt: attributes[:alt],
         link: attributes[:link],
         modal: attributes[:modal],
-        modal_results: attributes[:modal_results] || []
+        modal_results: attributes.fetch(:modal_results, [])
       }
     end
 

data/lib/jekyll-imgflow/imgflow_tag.rb

@@ -73,46 +73,48 @@ module Jekyll
       return "" unless parsed[:image_path]
 
       site = context.registers[:site]
-      page = context.registers[:page]
+      input_path = resolve_input_path(parsed[:image_path], site, components[:config])
+      original_name = original_image_name(input_path, site, components[:config])
+      page_path = page_identifier(context.registers[:page])
+      results, modal_results = process_image_variants(components, parsed, original_name, input_path,
+                                                      page_path)
+      render_processed_results(results, modal_results, parsed, site, context)
+    end
 
-      # Resolve input path
-      input_path = resolve_image_path(parsed[:image_path], site, components[:config])
+    def resolve_input_path(image_path, site, config)
+      input_path = resolve_image_path(image_path, site, config)
       raise ArgumentError, "Input image file not found: #{input_path}" unless File.file?(input_path)
 
-      # Store original name relative to the configured originals directory
-      # so output can mirror the original directory structure
-      originals_dir = File.join(site.source, components[:config].originals)
-      original_name = input_path.sub("#{originals_dir}/", "")
+      input_path
+    end
 
-      # Get page path for manifest tracking
-      # Try multiple attributes to get the page identifier
-      page_path = if page
-                    page["path"] || page["url"] || page["name"] || "unknown"
-                  else
-                    "unknown"
-                  end
+    def original_image_name(input_path, site, config)
+      originals_dir = File.join(site.source, config.originals)
+      input_path.sub("#{originals_dir}/", "")
+    end
 
+    def page_identifier(page)
+      (page && (page["path"] || page["url"] || page["name"])) || "unknown"
+    end
+
+    def process_image_variants(components, parsed, original_name, input_path, page_path)
       operations = parsed[:operations]
-      results = if operations.empty?
-                  [input_path]
-                else
-                  process_variants(components, operations.first, original_name, input_path,
-                                   page_path)
-                end
-
-      modal_results = if operations.empty?
-                        []
-                      else
-                        process_modal_variants(components, operations.first, parsed, original_name,
-                                               input_path, page_path)
-                      end
+      return [[input_path], []] if operations.empty?
+
+      operation = operations.first
+      results = process_variants(components, operation, original_name, input_path, page_path)
+      modal_results = process_modal_variants(components, operation, parsed, original_name,
+                                             input_path, page_path)
+      [results, modal_results]
+    end
+
+    def render_processed_results(results, modal_results, parsed, site, context)
       relative_results = results.uniq.map { |result| relative_result_path(result, site) }
       relative_modal_results = modal_results.uniq.map do |result|
         relative_result_path(result, site)
       end
       parsed = parsed.merge(markup_format: "picture") if relative_results.length > 1
-      parsed = parsed.merge(modal_results: relative_modal_results)
-      generate_html(relative_results, parsed, context)
+      generate_html(relative_results, parsed.merge(modal_results: relative_modal_results), context)
     end
 
     def process_modal_variants(components, operation, parsed, original_name, input_path, page_path)
@@ -123,18 +125,22 @@ module Jekyll
       return [] unless original_width
 
       params = operation[:params].dup
-      formats = Array(params.delete(:formats) || params[:format])
-      formats = config.formats if formats.empty?
+      formats = modal_formats(params, config)
+      params.delete(:formats)
       modal_width = [original_width, config.sizes.values.max].min
-
       formats.map do |format|
-        modal_params = params.merge(width: modal_width, format: format)
-        process_variant(components, operation, modal_params, original_name, input_path, page_path)
+        process_variant(components, operation, params.merge(width: modal_width, format: format),
+                        original_name, input_path, page_path)
       end
     rescue FastImage::ImageFetchError, FastImage::UnknownImageType
       []
     end
 
+    def modal_formats(params, config)
+      formats = Array(params[:formats] || params[:format])
+      formats.empty? ? config.formats : formats
+    end
+
     def modal_requested?(parsed, config)
       return false if %w[direct_url naked_srcset].include?(parsed[:markup_format])
 
@@ -164,35 +170,63 @@ module Jekyll
 
     def process_variant(components, operation, params, original_name, input_path, page_path)
       config = components[:config]
-      if determine_version_type(params, config) == :default
-        params[:format] ||= config.formats.first
-        params[:quality] ||= config.quality
+      apply_default_params(params, config)
+      variant = variant_context(components, params, original_name, input_path, config)
+
+      if variant_cached?(components, original_name, params, variant[:version_type],
+                         variant[:digest], variant[:output_path])
+        return cached_variant(components, original_name, params, variant[:version_type],
+                              variant[:digest], variant[:output_path], page_path)
       end
 
+      process_variant_output(components, operation, params, variant, original_name, input_path,
+                             page_path)
+    end
+
+    def variant_context(components, params, original_name, input_path, config)
       digest = components[:filename_generator].file_digest(input_path)
-      variant = operation.merge(params: params, file_digest: digest)
-      subdir = File.dirname(original_name)
-      subdir = nil if subdir == "."
       filename = components[:filename_generator].generate_filename(input_path, params)
-      output_path = components[:path_resolver].resolve_source_output_path(filename, subdir)
-      version_type = determine_version_type(params, config)
-
-      if components[:manifest].version_exists?(original_name, params, version_type, digest) &&
-         File.file?(output_path)
-        components[:stats]&.record_cache_hit
-        components[:manifest].update_page_usage(original_name, params, version_type, page_path)
-        return output_path
-      end
+      subdir = output_subdir(original_name)
+      {
+        digest: digest,
+        output_path: components[:path_resolver].resolve_source_output_path(filename, subdir),
+        version_type: determine_version_type(params, config)
+      }
+    end
 
+    def process_variant_output(components, operation, params, variant, original_name, input_path,
+                               page_path)
       unless components[:operation_processor]
         Jekyll.logger.warn "ImgFlow:", "No image provider available — " \
                                        "rendering original without optimization."
         return input_path
       end
 
-      components[:operation_processor].process_operation(
-        original_name, variant.merge(force_processing: true), input_path, page_path
-      )
+      operation_params = operation.merge(params: params, file_digest: variant[:digest],
+                                         force_processing: true)
+      components[:operation_processor].process_operation(original_name, operation_params, input_path,
+                                                         page_path)
+    end
+
+    def apply_default_params(params, config)
+      return unless determine_version_type(params, config) == :default
+
+      params[:format] ||= config.formats.first
+      params[:quality] ||= config.quality
+    end
+
+    def output_subdir(original_name)
+      File.dirname(original_name).then { |dir| dir == "." ? nil : dir }
+    end
+
+    def variant_cached?(components, original_name, params, version_type, digest, output_path)
+      components[:manifest].version_exists?(original_name, params, version_type, digest) && File.file?(output_path)
+    end
+
+    def cached_variant(components, original_name, params, version_type, _digest, output_path, page_path)
+      components[:stats]&.record_cache_hit
+      components[:manifest].update_page_usage(original_name, params, version_type, page_path)
+      output_path
     end
 
     def relative_result_path(result, site)

data/lib/jekyll-imgflow/manifest_manager.rb

@@ -25,32 +25,35 @@ module JekyllImgFlow
 
     # Load existing manifest or create new one
     def load_manifest(path = @manifest_path)
-      if path && File.exist?(path)
-        begin
-          data = JSON.parse(File.read(path))
-
-          # Handle new format with provider at top level
-          if data.is_a?(Hash) && data.key?("images")
-            @cached_provider = data["provider"]
-            images = data["images"] || {}
-          else
-            # Old format - just image data
-            @cached_provider = nil
-            images = data
-          end
+      return empty_manifest unless path && File.exist?(path)
 
-          migrate_legacy_manifest(images)
-        rescue JSON::ParserError => e
-          Jekyll.logger.warn "ImgFlow: Corrupt manifest file, starting fresh: #{e.message}"
-          @cached_provider = nil
-          {}
-        end
+      load_manifest_file(path)
+    rescue JSON::ParserError => e
+      Jekyll.logger.warn "ImgFlow: Corrupt manifest file, starting fresh: #{e.message}"
+      empty_manifest
+    end
+
+    def load_manifest_file(path)
+      data = JSON.parse(File.read(path))
+      images = manifest_images(data)
+      migrate_legacy_manifest(images)
+    end
+
+    def manifest_images(data)
+      if data.is_a?(Hash) && data.key?("images")
+        @cached_provider = data["provider"]
+        data["images"] || {}
       else
         @cached_provider = nil
-        {}
+        data
       end
     end
 
+    def empty_manifest
+      @cached_provider = nil
+      {}
+    end
+
     # Detect and migrate legacy manifest entries (pre-0.1.11 format).
     # Old entries have operations like {"width": 400} without format/quality
     # and no file_digest. Clearing them lets the build re-register existing
@@ -232,51 +235,55 @@ module JekyllImgFlow
     # Register a new image version
     def register_version(original_name, output_path, operations, type, page_path,
                          file_digest = nil, provider = nil)
+      image = manifest_image(original_name, file_digest)
+      image["file_digest"] = file_digest if file_digest
+      versions = image["versions"][type.to_s] ||= []
+      normalized = normalize_operations(operations)
+      page_paths = normalize_page_paths(page_path)
+      version = versions.find { |entry| same_operations?(entry["operations"], normalized) }
+
+      if version
+        update_version(version, output_path, page_paths, file_digest, provider)
+      else
+        versions << new_version(output_path, normalized, type, page_paths, file_digest, provider)
+      end
+    end
+
+    def manifest_image(original_name, file_digest)
       @manifest[original_name] ||= {
         "versions" => { "default" => [], "specialized" => [] },
-        "file_digest" => file_digest # Store SHA256 digest of original file
+        "file_digest" => file_digest
       }
+    end
 
-      # Update file digest if provided
-      @manifest[original_name]["file_digest"] = file_digest if file_digest
-
-      versions = @manifest[original_name]["versions"][type.to_s] ||= []
-      normalized_operations = normalize_operations(operations)
-
-      # Find or create version entry
-      version = versions.find { |v| same_operations?(v["operations"], normalized_operations) }
-
-      # Normalize page_path to array
-      page_paths = if page_path.is_a?(Array)
-                     page_path
-                   else
-                     (page_path ? [page_path] : [])
-                   end
-
-      if version
-        # Add pages to used_on list if not already present
-        version["used_on"] ||= []
-        page_paths.each do |path|
-          version["used_on"] << path if path && !version["used_on"].include?(path)
-        end
-        version["output"] = output_path
-        version["file_digest"] = file_digest if file_digest
-        # Update provider if provided
-        version["provider"] = provider if provider
+    def normalize_page_paths(page_path)
+      if page_path.is_a?(Array)
+        page_path
       else
-        # Create new version entry
-        versions << {
-          "output" => output_path,
-          "operations" => normalized_operations,
-          "type" => type.to_s,
-          "used_on" => page_paths,
-          "created_at" => Time.now.to_i,
-          "file_digest" => file_digest,
-          "provider" => provider
-        }
+        (page_path ? [page_path] : [])
       end
     end
 
+    def update_version(version, output_path, page_paths, file_digest, provider)
+      version["used_on"] ||= []
+      page_paths.each { |path| version["used_on"] << path if path && !version["used_on"].include?(path) }
+      version["output"] = output_path
+      version["file_digest"] = file_digest if file_digest
+      version["provider"] = provider if provider
+    end
+
+    def new_version(output_path, operations, type, page_paths, file_digest, provider)
+      {
+        "output" => output_path,
+        "operations" => operations,
+        "type" => type.to_s,
+        "used_on" => page_paths,
+        "created_at" => Time.now.to_i,
+        "file_digest" => file_digest,
+        "provider" => provider
+      }
+    end
+
     # Check if image version is default type
     def default_version?(original_name, operations)
       return false unless @manifest[original_name]

data/lib/jekyll-imgflow/operation_processor.rb

@@ -43,84 +43,64 @@ module JekyllImgFlow
     # @param page_path [String] Optional page path for manifest tracking
     # @return [String] Path to processed image
     def process_operation(original_name, operation, input_path, page_path = nil)
-      type = operation[:type]
       params = operation[:params]
       file_digest = operation[:file_digest] || @filename_generator.file_digest(input_path)
-
-      # Determine version type
       version_type = determine_version_type(params)
-
-      # Preserve original directory structure under output
-      subdir = File.dirname(original_name)
-      subdir = nil if subdir == "."
-
-      # Generate filename using FilenameGenerator (JPT compatible)
       filename = @filename_generator.generate_filename(input_path, params)
+      subdir = output_subdir(original_name)
+      output_path = @path_resolver.resolve_source_output_path(filename, subdir)
+      FileUtils.mkdir_p(File.dirname(output_path))
 
-      # Write to source directory so Jekyll copies files to _site during the write phase
-      actual_output_path = @path_resolver.resolve_source_output_path(filename, subdir)
+      process_output(operation, original_name, input_path, output_path, params)
+      register_manifest(original_name, filename, params, version_type, page_path, file_digest, subdir)
+      register_jekyll_static_file(output_path)
+      output_path
+    end
 
-      # Ensure output directory exists before processing
-      FileUtils.mkdir_p(File.dirname(actual_output_path))
+    def output_subdir(original_name)
+      subdir = File.dirname(original_name)
+      subdir == "." ? nil : subdir
+    end
 
-      # Skip processing if the output file already exists and is up-to-date.
-      # This handles legacy manifests, corrupted manifests, and any case where
-      # optimized files exist on disk but the manifest is out of sync — the
-      # version is registered in the manifest without re-running the provider.
-      if !operation[:force_processing] && output_up_to_date?(input_path, actual_output_path)
-        Jekyll.logger.debug "⏭️  ImgFlow: Output exists and up-to-date, " \
-                            "skipping provider call for #{original_name}"
+    def process_output(operation, original_name, input_path, output_path, params)
+      if !operation[:force_processing] && output_up_to_date?(input_path, output_path)
+        Jekyll.logger.debug "⏭️  ImgFlow: Output exists and up-to-date, skipping provider call for #{original_name}"
         @stats.record_cache_hit
       elsif AnimatedGifDetector.animated?(input_path)
-        # Animated GIFs must not be resized or converted — the operation
-        # would destroy the animation. Copy the original file as-is so the
-        # manifest can track it and HTML references stay valid.
-        Jekyll.logger.warn "🖼️  ImgFlow: Skipping resize for animated GIF " \
-                           "'#{original_name}' — copying original as-is to " \
-                           "preserve animation."
-        FileUtils.cp(input_path, actual_output_path)
-        @stats.record_cache_miss
+        copy_animated_image(original_name, input_path, output_path)
       else
-        # Process the operation (create the image)
-        elapsed = Benchmark.measure do
-          process_single_operation(type, input_path, actual_output_path, params)
-        end
-        @stats.record_operation_time(type, elapsed.real)
-        @stats.record_cache_miss
-
-        # Record compression ratio if we have the original size
-        if File.file?(input_path) && File.file?(actual_output_path)
-          format = params[:format] || File.extname(input_path).delete(".")
-          @stats.record_compression_ratio(format.to_s, File.size(input_path),
-                                          File.size(actual_output_path))
-        end
+        process_image(operation[:type], input_path, output_path, params)
       end
+    end
 
-      # Register in manifest
-      if @manifest
-        # Store relative path (with leading /) for manifest storage
-        relative_path = "/#{@path_resolver.resolve_relative_output_path(filename, subdir)}"
-
-        provider_name = @provider&.class&.provider_name || "unknown"
-        @manifest.register_version(
-          original_name,
-          relative_path,
-          params,
-          version_type,
-          page_path,
-          file_digest,
-          provider_name
-        )
-      end
+    def copy_animated_image(original_name, input_path, output_path)
+      Jekyll.logger.warn "🖼️  ImgFlow: Skipping resize for animated GIF '#{original_name}' — " \
+                         "copying original as-is to preserve animation."
+      FileUtils.cp(input_path, output_path)
+      @stats.record_cache_miss
+    end
+
+    def process_image(type, input_path, output_path, params)
+      elapsed = Benchmark.measure { process_single_operation(type, input_path, output_path, params) }
+      @stats.record_operation_time(type, elapsed.real)
+      @stats.record_cache_miss
+      record_compression_ratio(input_path, output_path, params)
+    end
+
+    def record_compression_ratio(input_path, output_path, params)
+      return unless File.file?(input_path) && File.file?(output_path)
+
+      format = params[:format] || File.extname(input_path).delete(".")
+      @stats.record_compression_ratio(format.to_s, File.size(input_path), File.size(output_path))
+    end
 
-      # Register as Jekyll static file so Jekyll copies it to _site during
-      # the write phase. Without this, files created during pre_render (or
-      # during render via imgflow tags) are not picked up by Jekyll's static
-      # file reader, which runs before pre_render. This would leave _site
-      # without optimized images until a second build.
-      register_jekyll_static_file(actual_output_path)
+    def register_manifest(original_name, filename, params, version_type, page_path, file_digest, subdir)
+      return unless @manifest
 
-      actual_output_path
+      relative_path = "/#{@path_resolver.resolve_relative_output_path(filename, subdir)}"
+      provider_name = @provider&.class&.provider_name || "unknown"
+      @manifest.register_version(original_name, relative_path, params, version_type, page_path,
+                                 file_digest, provider_name)
     end
 
     # Register a generated file as a Jekyll::StaticFile so Jekyll copies it