safe_image 0.1.0 → 0.3.0

data/lib/safe_image/native.rb

@@ -1,3 +1,382 @@
 # frozen_string_literal: true
 
-require "safe_image_native"
+require_relative "vips_glue"
+
+module SafeImage
+  # The libvips fast path, implemented in pure Ruby on top of the VipsGlue
+  # Fiddle binding (formerly a compiled C extension; the function surface and
+  # messages are unchanged). Loaders are explicit per extension, every decode
+  # enforces the pixel cap from the header before pixel data is touched, and
+  # all images are released deterministically.
+  module Native
+    LOADERS = {
+      "jpg" => "jpegload",
+      "png" => "pngload",
+      "webp" => "webpload",
+      "gif" => "gifload",
+      "heic" => "heifload",
+      "avif" => "heifload",
+      "jxl" => "jxlload"
+    }.freeze
+
+    class << self
+      def probe(path)
+        started = monotime
+        VipsGlue.with_images do |track|
+          image, format = load_image(track, String(path))
+          {
+            format: format,
+            width: VipsGlue.width(image),
+            height: VipsGlue.height(image),
+            duration_ms: monotime - started
+          }
+        end
+      end
+
+      def thumbnail(input, output, width, height, format, quality, max_pixels)
+        started = monotime
+        input = String(input)
+        output = String(output)
+        width = Integer(width)
+        height = Integer(height)
+        quality = Integer(quality)
+        raise ArgumentError, "width and height must be positive" if width <= 0 || height <= 0
+        validate_quality!(quality)
+        out_format = output_format!(format)
+
+        VipsGlue.with_images do |track|
+          # Route through the explicit loader for the path's extension and keep
+          # the resulting image object for the resize. Do not call the generic
+          # filename-based `thumbnail` operation here: it re-sniffs the path and
+          # can observe different bytes if a hostile local path is replaced
+          # between the header check and the decode.
+          image, input_format = load_image(track, input, autorotate: true)
+          check_pixels!(image, max_pixels)
+
+          thumb = track.call(
+            VipsGlue.operation(
+              "thumbnail_image",
+              { in: image, width: width, height: height,
+                size: "both", crop: "centre", fail_on: "error" }
+            )
+          )
+          save_image(thumb, output, out_format, quality)
+          info(input_format, out_format, thumb, started)
+        end
+      end
+
+      def resize(input, output, scale, format, quality, max_pixels)
+        started = monotime
+        scale = Float(scale)
+        quality = Integer(quality)
+        unless scale.finite? && scale.positive? && scale <= 100.0
+          raise ArgumentError, "scale must be finite and in 0..100"
+        end
+        validate_quality!(quality)
+        out_format = output_format!(format)
+
+        VipsGlue.with_images do |track|
+          image, input_format = load_image(track, String(input), autorotate: true)
+          check_pixels!(image, max_pixels)
+          rotated = track.call(VipsGlue.operation("autorot", { in: image }))
+          resized = track.call(VipsGlue.operation("resize", { in: rotated, scale: scale }))
+          save_image(resized, String(output), out_format, quality)
+          info(input_format, out_format, resized, started)
+        end
+      end
+
+      def crop_north(input, output, width, height, format, quality, max_pixels)
+        started = monotime
+        width = Integer(width)
+        height = Integer(height)
+        quality = Integer(quality)
+        raise ArgumentError, "width and height must be positive" if width <= 0 || height <= 0
+        validate_quality!(quality)
+        out_format = output_format!(format)
+
+        VipsGlue.with_images do |track|
+          image, input_format = load_image(track, String(input), autorotate: true)
+          check_pixels!(image, max_pixels)
+          rotated = track.call(VipsGlue.operation("autorot", { in: image }))
+
+          scale = [width.fdiv(VipsGlue.width(rotated)), height.fdiv(VipsGlue.height(rotated))].max * 1.0000001
+          resized = track.call(VipsGlue.operation("resize", { in: rotated, scale: scale }))
+          left = [(VipsGlue.width(resized) - width) / 2, 0].max
+          cropped = track.call(
+            VipsGlue.operation("extract_area", { input: resized, left: left, top: 0, width: width, height: height })
+          )
+          save_image(cropped, String(output), out_format, quality)
+          info(input_format, out_format, cropped, started)
+        end
+      end
+
+      def convert(input, output, format, quality, max_pixels)
+        started = monotime
+        quality = Integer(quality)
+        validate_quality!(quality)
+        out_format = output_format!(format)
+
+        VipsGlue.with_images do |track|
+          image, input_format = load_image(track, String(input), autorotate: true)
+          check_pixels!(image, max_pixels)
+          rotated = track.call(VipsGlue.operation("autorot", { in: image }))
+
+          # JPEG has no alpha; flatten onto white to match the ImageMagick
+          # convert path (libvips composites onto black otherwise).
+          final =
+            if out_format == "jpg" && VipsGlue.alpha?(rotated)
+              track.call(VipsGlue.operation("flatten", { in: rotated, background: [255.0, 255.0, 255.0] }))
+            else
+              rotated
+            end
+          save_image(final, String(output), out_format, quality)
+          info(input_format, out_format, final, started)
+        end
+      end
+
+      # Alpha-weighted average colour as [r, g, b] integers. Premultiplying
+      # keeps parity with ImageMagick's resize-based average; per-band means
+      # come from vips_stats (row b+1, column 4 of the stats matrix).
+      def dominant_color(path, max_pixels)
+        VipsGlue.with_images do |track|
+          image, = load_image(track, String(path))
+          check_pixels!(image, max_pixels)
+
+          srgb =
+            if VipsGlue.colourspace_supported?(image)
+              track.call(VipsGlue.operation("colourspace", { in: image, space: "srgb" }))
+            else
+              image
+            end
+          has_alpha = VipsGlue.alpha?(srgb)
+          work = has_alpha ? track.call(VipsGlue.operation("premultiply", { in: srgb })) : srgb
+
+          stats = track.call(VipsGlue.operation("stats", { in: work }))
+          columns = VipsGlue.width(stats)
+          matrix = VipsGlue.image_bytes(stats).unpack("d*")
+          mean = ->(band) { matrix[(band + 1) * columns + 4] || 0.0 }
+
+          bands = VipsGlue.bands(work)
+          colour_bands = has_alpha ? bands - 1 : bands
+          colour_bands = colour_bands.clamp(1, 3)
+          raise InvalidImageError, "image has no colour bands" if colour_bands < 1
+
+          alpha_mean = has_alpha ? mean.call(bands - 1) : 255.0
+          (0...3).map do |band|
+            value = mean.call([band, colour_bands - 1].min)
+            value = alpha_mean.positive? ? value * 255.0 / alpha_mean : 0.0 if has_alpha
+            value.round.clamp(0, 255)
+          end
+        end
+      end
+
+      def pages(path, max_pixels)
+        VipsGlue.with_images do |track|
+          image, = load_image(track, String(path))
+          check_pixels!(image, max_pixels)
+          VipsGlue.pages(image)
+        end
+      end
+
+      def orientation(path, max_pixels)
+        VipsGlue.with_images do |track|
+          image, = load_image(track, String(path))
+          check_pixels!(image, max_pixels)
+          value = VipsGlue.orientation(image)
+          (1..8).cover?(value) ? value : 1
+        end
+      end
+
+      # Encodes a raw RGBA buffer (top-down rows) as PNG. Used by the
+      # pure-Ruby ICO decoder.
+      def png_from_rgba(bytes, width, height, output)
+        bytes = String(bytes)
+        width = Integer(width)
+        height = Integer(height)
+        raise ArgumentError, "width and height must be positive" if width <= 0 || height <= 0
+        raise LimitError, "rgba buffer dimensions exceed 4096x4096" if width > 4096 || height > 4096
+        raise ArgumentError, "rgba buffer must be width*height*4 bytes" if bytes.bytesize != width * height * 4
+
+        VipsGlue.with_images do |track|
+          image = track.call(VipsGlue.image_from_memory(bytes, width, height, 4, 0)) # 0 = uchar
+          srgb = track.call(VipsGlue.operation("copy", { in: image, interpretation: "srgb" }))
+          save_image(srgb, String(output), "png", 100)
+        end
+        true
+      end
+
+      # Renders a letter avatar: a Pango glyph mask blended in white at 80%
+      # opacity over a solid background via a single linear transform. The
+      # markup string is escaped by the Ruby caller; font and fontfile come
+      # from an allowlist.
+      def letter_avatar(output, size, red, green, blue, markup, font, fontfile)
+        size = Integer(size)
+        markup = String(markup)
+        font = String(font)
+        fontfile = String(fontfile)
+        channels = [Integer(red), Integer(green), Integer(blue)]
+        raise ArgumentError, "size must be 1..4096" unless (1..4096).cover?(size)
+        unless channels.all? { |value| (0..255).cover?(value) }
+          raise ArgumentError, "background channels must be 0..255"
+        end
+        unless VipsGlue.type_find?("text")
+          raise UnsupportedFormatError, "this libvips build has no text renderer (Pango support missing)"
+        end
+
+        VipsGlue.with_images do |track|
+          mask =
+            if markup.empty?
+              # Blank letter: solid background only.
+              track.call(VipsGlue.operation("black", { width: size, height: size }))
+            else
+              text_inputs = { text: markup, font: font, dpi: 72 }
+              text_inputs[:fontfile] = fontfile unless fontfile.empty?
+              text = track.call(VipsGlue.operation("text", text_inputs))
+
+              # vips_text returns the tight ink box; crop to the canvas when
+              # the pointsize overflows it, then centre the ink optically.
+              text_w = VipsGlue.width(text)
+              text_h = VipsGlue.height(text)
+              if text_w > size || text_h > size
+                crop_w = [text_w, size].min
+                crop_h = [text_h, size].min
+                text = track.call(
+                  VipsGlue.operation(
+                    "extract_area",
+                    { input: text, left: (text_w - crop_w) / 2, top: (text_h - crop_h) / 2,
+                      width: crop_w, height: crop_h }
+                  )
+                )
+                text_w = crop_w
+                text_h = crop_h
+              end
+              track.call(
+                VipsGlue.operation(
+                  "embed",
+                  { in: text, x: (size - text_w) / 2, y: (size - text_h) / 2, width: size, height: size }
+                )
+              )
+            end
+
+          # blend = bg + (white - bg) * 0.8 * mask/255, one linear op.
+          opacity = 204.0 / 255.0 # FFFFFFCC
+          a = channels.map { |value| (255.0 - value) * opacity / 255.0 }
+          blended = track.call(VipsGlue.operation("linear", { in: mask, a: a, b: channels.map(&:to_f) }))
+          cast = track.call(VipsGlue.operation("cast", { in: blended, format: "uchar" }))
+          srgb = track.call(VipsGlue.operation("copy", { in: cast, interpretation: "srgb" }))
+          save_image(srgb, String(output), "png", 100)
+        end
+        true
+      end
+
+      private
+
+      def monotime
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
+      end
+
+      def info(input_format, output_format, image, started)
+        {
+          input_format: input_format,
+          output_format: output_format,
+          width: VipsGlue.width(image),
+          height: VipsGlue.height(image),
+          duration_ms: monotime - started
+        }
+      end
+
+      def normalized_format(ext)
+        case ext.to_s.downcase
+        when "jpg", "jpeg" then "jpg"
+        when "png" then "png"
+        when "webp" then "webp"
+        when "gif" then "gif"
+        when "heic", "heif" then "heic"
+        when "avif" then "avif"
+        when "jxl" then "jxl"
+        end
+      end
+
+      def output_format!(format)
+        normalized = normalized_format(String(format))
+        raise UnsupportedFormatError, "unsupported output format" if normalized.nil? || normalized == "heic"
+        normalized
+      end
+
+      def validate_quality!(quality)
+        raise ArgumentError, "quality must be 1..100" unless (1..100).cover?(quality)
+      end
+
+      def load_image(track, path, autorotate: false)
+        format = normalized_format(File.extname(path).delete_prefix("."))
+        raise UnsupportedFormatError, "unsupported input format" unless format
+
+        case format
+        when "gif"
+          # libnsgif loader: first frame only (the n=1 default), matching the
+          # [0] semantics of the ImageMagick compatibility backend.
+          raise UnsupportedFormatError, "this libvips build has no GIF loader" unless VipsGlue.type_find?("gifload")
+        when "jxl"
+          raise UnsupportedFormatError, "this libvips build has no JPEG XL loader" unless VipsGlue.type_find?("jxlload")
+        end
+
+        options = { filename: path, access: "sequential", fail_on: "error" }
+        image = track.call(VipsGlue.operation(LOADERS.fetch(format), options))
+
+        # autorot flips/rotates pull rows out of input order, which a
+        # sequential source can only serve while the image fits its readahead
+        # window (~512px); larger oriented images fail with "out of order
+        # read". Reload those with random access — the open itself is
+        # header-only, so the caller's pixel cap still runs before any decode.
+        if autorotate && VipsGlue.orientation(image) > 1
+          image = track.call(VipsGlue.operation(LOADERS.fetch(format), options.merge(access: "random")))
+        end
+        [image, format]
+      end
+
+      def check_pixels!(image, max_pixels)
+        if max_pixels.nil?
+          limit = DEFAULT_MAX_PIXELS
+        else
+          limit = Integer(max_pixels)
+          raise ArgumentError, "max_pixels must be positive" if limit <= 0
+        end
+        width = VipsGlue.width(image)
+        height = VipsGlue.height(image)
+        raise InvalidImageError, "image dimensions are invalid" if width <= 0 || height <= 0
+        pixels = width * height
+        raise LimitError, "image has #{pixels} pixels, exceeds #{limit}" if pixels > limit
+      end
+
+      # libvips renamed the strip-metadata save option from "strip" to "keep"
+      # (VIPS_FOREIGN_KEEP_NONE = 0) in 8.15; pick the spelling at runtime so
+      # one gem build serves distro packages from 8.13 up.
+      def strip_args
+        @strip_args ||= (VipsGlue.version <=> [8, 15]) >= 0 ? { keep: 0 } : { strip: true }
+      end
+
+      def save_image(image, path, format, quality)
+        case format
+        when "jpg"
+          VipsGlue.operation("jpegsave", { in: image, filename: path, Q: quality, interlace: false, **strip_args }, output: nil)
+        when "png"
+          VipsGlue.operation("pngsave", { in: image, filename: path, compression: 6, **strip_args }, output: nil)
+        when "webp"
+          VipsGlue.operation("webpsave", { in: image, filename: path, Q: quality, **strip_args }, output: nil)
+        when "avif"
+          VipsGlue.operation("heifsave", { in: image, filename: path, Q: quality, compression: "av1", **strip_args }, output: nil)
+        when "gif"
+          # cgif-backed saver; optional at libvips build time. GIF output is
+          # palette-quantised and has no quality parameter.
+          raise UnsupportedFormatError, "this libvips build cannot save GIF (cgif support missing)" unless VipsGlue.type_find?("gifsave")
+          VipsGlue.operation("gifsave", { in: image, filename: path, **strip_args }, output: nil)
+        when "jxl"
+          raise UnsupportedFormatError, "this libvips build cannot save JPEG XL" unless VipsGlue.type_find?("jxlsave")
+          VipsGlue.operation("jxlsave", { in: image, filename: path, Q: quality, **strip_args }, output: nil)
+        else
+          raise UnsupportedFormatError, "unsupported output format"
+        end
+      end
+    end
+  end
+end

data/lib/safe_image/optimizer.rb

@@ -8,7 +8,20 @@ module SafeImage
 
     MAX_PNGQUANT_SIZE = 500_000
 
-    def optimize(path, mode: :lossless, strip_metadata: true, quality: nil, timeout: Runner::DEFAULT_TIMEOUT, strict: true)
+    # EXIF orientation values mapped onto jpegtran's lossless transforms.
+    JPEGTRAN_OPERATIONS = {
+      2 => ["-flip", "horizontal"],
+      3 => ["-rotate", "180"],
+      4 => ["-flip", "vertical"],
+      5 => ["-transpose"],
+      6 => ["-rotate", "90"],
+      7 => ["-transverse"],
+      8 => ["-rotate", "270"]
+    }.freeze
+
+    # assume_upright: skips the JPEG orientation check; only for callers
+    # optimising output this gem just encoded (which is always upright).
+    def optimize(path, mode: :lossless, strip_metadata: true, quality: nil, timeout: Runner::DEFAULT_TIMEOUT, strict: true, assume_upright: false)
       path = PathSafety.ensure_regular_file!(path)
 
       ext = path.extname.delete_prefix(".").downcase
@@ -16,9 +29,26 @@ module SafeImage
 
       before = File.size(path)
       tools = []
+      rotated_from = nil
+      trimmed = false
 
       case ext
       when "jpg"
+        # Stripping metadata deletes the EXIF orientation tag, so an oriented
+        # image must have the rotation baked into its pixels first or it ships
+        # sideways. jpegtran does that losslessly; without it, leave the file
+        # untouched rather than strip-without-rotate.
+        orientation = strip_metadata && !assume_upright ? jpeg_orientation(path) : 1
+        if orientation > 1
+          unless Runner.available?("jpegtran")
+            raise Error, "jpegtran is required to optimize a JPEG with EXIF orientation" if strict
+            return { format: ext, before_bytes: before, after_bytes: before, saved_bytes: 0, tools: tools, rotated_from: nil, trimmed: false }
+          end
+          trimmed = upright!(path, orientation, timeout: timeout)
+          rotated_from = orientation
+          tools << "jpegtran"
+        end
+
         if Runner.available?("jpegoptim")
           argv = ["jpegoptim", "--quiet"]
           argv << (strip_metadata ? "--strip-all" : "--strip-none")
@@ -39,8 +69,18 @@ module SafeImage
               argv = ["pngquant", "--force", "--skip-if-larger", "--output", tmp_path.to_s]
               argv << "--quality=#{quality}" if quality # e.g. "65-90"
               argv << path.to_s
-              Runner.run!(argv, timeout: timeout)
-              if tmp_path.file? && File.size(tmp_path) < File.size(path)
+              skipped = false
+              begin
+                Runner.run!(argv, timeout: timeout)
+              rescue CommandError => e
+                # 98: --skip-if-larger declined the result; 99: --quality not
+                # met. Both mean "keep the original", not a failure — and the
+                # pre-created tempfile is still empty, so it must not win the
+                # size comparison below.
+                raise unless [98, 99].include?(e.status)
+                skipped = true
+              end
+              if !skipped && tmp_path.file? && File.size(tmp_path).positive? && File.size(tmp_path) < File.size(path)
                 FileUtils.mv(tmp_path, path)
                 tools << "pngquant"
               end
@@ -71,8 +111,43 @@ module SafeImage
         before_bytes: before,
         after_bytes: after,
         saved_bytes: before - after,
-        tools: tools
+        tools: tools,
+        rotated_from: rotated_from,
+        trimmed: trimmed
       }
     end
+
+    def jpeg_orientation(path)
+      case SafeImage.config.backend
+      when :vips then VipsBackend.orientation(path.to_s)
+      when :imagemagick then ImageMagickBackend.orientation(path.to_s)
+      end
+    end
+
+    # Applies the orientation's lossless jpegtran transform in place, dropping
+    # the metadata in the same pass (-copy none; this path only runs when
+    # strip_metadata is set). -perfect refuses dimensions that are not
+    # MCU-aligned; the -trim retry drops the partial edge blocks (under one
+    # MCU, at most 15px) instead of hiding a lossy re-encode here. Returns
+    # true when the fallback trimmed.
+    def upright!(path, orientation, timeout:)
+      transform = JPEGTRAN_OPERATIONS.fetch(orientation)
+      tmp = Tempfile.new([path.basename(".*").to_s, ".jpegtran.jpg"], path.dirname.to_s)
+      tmp_path = Pathname.new(tmp.path)
+      tmp.close
+      begin
+        trimmed = false
+        begin
+          Runner.run!(["jpegtran", "-copy", "none", "-perfect", *transform, "-outfile", tmp_path.to_s, path.to_s], timeout: timeout)
+        rescue CommandError
+          Runner.run!(["jpegtran", "-copy", "none", "-trim", *transform, "-outfile", tmp_path.to_s, path.to_s], timeout: timeout)
+          trimmed = true
+        end
+        FileUtils.mv(tmp_path, path)
+        trimmed
+      ensure
+        FileUtils.rm_f(tmp_path)
+      end
+    end
   end
 end

data/lib/safe_image/processor.rb

@@ -6,14 +6,14 @@ require "tempfile"
 
 module SafeImage
   class Processor
-    SUPPORTED_INPUTS = %w[jpg jpeg png webp heic heif avif].freeze
-    SUPPORTED_OUTPUTS = %w[jpg jpeg png webp avif].freeze
-
-    def initialize(max_pixels: nil, backend: :vips, execution: :inline, encoder: :auto, chroma_subsampling: :auto)
-      @max_pixels = max_pixels
-      @backend = backend.to_sym
-      @execution = execution.to_sym
-      @encoder = encoder.to_sym
+    SUPPORTED_INPUTS = %w[jpg jpeg png gif webp heic heif avif jxl].freeze
+    SUPPORTED_OUTPUTS = %w[jpg jpeg png gif webp avif jxl].freeze
+    # Formats the post-processing optimizer tools understand; other outputs
+    # skip the optimize pass instead of erroring.
+    OPTIMIZABLE_OUTPUTS = %w[jpg png].freeze
+
+    def initialize(max_pixels: nil, chroma_subsampling: :auto)
+      @max_pixels = max_pixels || SafeImage.config.max_pixels
       @chroma_subsampling = chroma_subsampling
     end
 
@@ -50,49 +50,17 @@ module SafeImage
         raise UnsupportedFormatError, "unsupported output format: #{out_format.inspect}"
       end
 
-      if @execution == :sandbox || @execution == :sandbox_if_available
-        if @execution == :sandbox && !Sandbox.available?
-          raise Error, "sandbox execution requested but Landlock::SafeExec is unavailable"
-        end
-
-        info = Sandbox.thumbnail(
-          input: input.to_s,
-          output: output.to_s,
-          width: width,
-          height: height,
-          format: out_format,
-          quality: quality,
-          max_pixels: @max_pixels,
-          backend: @backend,
-          optimize: optimize,
-          optimize_mode: optimize_mode
-        )
-        if info
-          return Result.new(
-            input: input.to_s,
-            output: output.to_s,
-            input_format: info.fetch(:input_format),
-            output_format: info.fetch(:output_format),
-            width: info.fetch(:width),
-            height: info.fetch(:height),
-            filesize: File.size(output),
-            backend: "sandboxed-#{info.fetch(:backend)}",
-            duration_ms: info.fetch(:duration_ms),
-            optimizer: info[:optimizer]
-          )
-        end
-      end
-
       output.dirname.mkpath
+      backend = SafeImage.config.backend
       info =
-        if out_format == "jpg" && use_jpegli_for_generated_jpeg?(input)
+        if out_format == "jpg" && use_jpegli_for_generated_jpeg?(backend)
           jpegli_thumbnail(input: input, output: output, width: width, height: height, quality: quality, source_format: input.extname.delete_prefix(".").downcase)
         else
-          case @backend
+          case backend
           when :vips
             Native.thumbnail(input.to_s, output.to_s, width, height, out_format, quality, @max_pixels)
-          when :imagemagick, :magick
-            probe_info = Native.probe(input.to_s)
+          when :imagemagick
+            probe_info = ImageMagickBackend.probe(input.to_s)
             validate_pixels!(probe_info.fetch(:width), probe_info.fetch(:height))
             ImageMagickBackend.thumbnail(
               input: input.to_s,
@@ -102,14 +70,12 @@ module SafeImage
               format: out_format,
               quality: quality
             )
-          else
-            raise ArgumentError, "unknown backend: #{@backend.inspect}"
           end
         end
 
       opt_info = nil
-      if optimize
-        opt_info = Optimizer.optimize(output, mode: optimize_mode, strip_metadata: true, quality: out_format == "jpg" ? quality : nil)
+      if optimize && OPTIMIZABLE_OUTPUTS.include?(out_format)
+        opt_info = Optimizer.optimize(output, mode: optimize_mode, strip_metadata: true, quality: out_format == "jpg" ? quality : nil, assume_upright: true)
       end
 
       Result.new(
@@ -120,7 +86,7 @@ module SafeImage
         width: info.fetch(:width),
         height: info.fetch(:height),
         filesize: File.size(output),
-        backend: result_backend(info),
+        backend: result_backend(info, backend),
         duration_ms: info.fetch(:duration_ms),
         optimizer: opt_info&.fetch(:tools, nil)
       )
@@ -128,23 +94,14 @@ module SafeImage
 
     private
 
-    def use_jpegli_for_generated_jpeg?(input)
-      case @encoder
-      when :auto
-        @backend == :vips && JpegliBackend.available?
-      when :cjpegli
-        true
-      when :vips, :imagemagick, :magick
-        false
-      else
-        raise ArgumentError, "unknown encoder: #{@encoder.inspect}"
-      end
+    # cjpegli is an output-quality tool, not a configuration choice: installed
+    # means used. It encodes only pixels this gem already decoded, so it is
+    # not part of the untrusted-input surface the backend choice controls.
+    def use_jpegli_for_generated_jpeg?(backend)
+      backend == :vips && JpegliBackend.available?
     end
 
     def jpegli_thumbnail(input:, output:, width:, height:, quality:, source_format:)
-      raise UnsupportedFormatError, "cjpegli is not installed" unless JpegliBackend.available?
-      raise ArgumentError, "encoder: :cjpegli currently requires backend: :vips" unless @backend == :vips
-
       output.dirname.mkpath
       Tempfile.create([output.basename(".*").to_s, ".safe-image.png"], output.dirname.to_s) do |tmp|
         tmp_path = Pathname.new(tmp.path)
@@ -167,12 +124,9 @@ module SafeImage
       format == "jpeg" ? "jpg" : format
     end
 
-    def result_backend(info)
-      if info[:encoder] == "cjpegli"
-        "#{@backend == :vips ? "libvips-direct" : "imagemagick"}+cjpegli"
-      else
-        @backend == :vips ? "libvips-direct" : "imagemagick"
-      end
+    def result_backend(info, backend)
+      base = backend == :vips ? "libvips-direct" : "imagemagick"
+      info[:encoder] == "cjpegli" ? "#{base}+cjpegli" : base
     end
 
     def safe_existing_file!(path)