image_pack 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 606688569aac1fa1515edefe270b18a04e5b0042de602b18663964726d8fbb34
-  data.tar.gz: 9092fcf9fa3c061edc87ce2a22544acfe52dfa6ce4fe39961c95a1d17220a6b0
+  metadata.gz: 12f5358f1b62d18b5f23c0022bf953ae6efab239645a94329774465b5ff4681a
+  data.tar.gz: b0fd8d35a15c5e6ef157c925e0ed967a485755b32f310b5c49bdc10688b58ebf
 SHA512:
-  metadata.gz: ad6b0db99c56d69c99d9216559e3c114a2079941a4f879e69508126bbf12b070844dc53e806b3da7637783a205528c10136c3cd3bac8f60b5fd6ee2ddcad01eb
-  data.tar.gz: f1acfa9f5a7154d1ea201ae66658da704a5ee5d207886b096d284b7b69eca175d668993dba127b0a609d6fb5b68492196edb8d3bb70d12575f129c095c6b7704
+  metadata.gz: a3cf71f03cedf98384331e74fdd47d3fa151b432d3af4e059032261a3f4a929d15b9329cbc57aace8f04fda9c73ac1cdad9d99a4b7e499fbda1f7242334c5c6e
+  data.tar.gz: 99898ec78f08fe924e5447a514dd37dcd4b141cf6b619fe5713f1050c0ca1ded2e112eda18b407e75b39d3a9c2fe802e1294d02d46ed63a24960944f398603d4

data/CHANGELOG.md

@@ -1,6 +1,41 @@
 # Changelog
 
+## 0.2.5
+
+**Output and API changes (upgrade notes)**
+
+- `algo: :mozjpeg` and `algo: :size` now default to **progressive JPEG** with full scan optimization. Previously the default was baseline JPEG. Pass `progressive: false` to restore the old behavior.
+- Added `mozjpeg_scan_opt:` keyword to `compress` and `compress_pixels` (default `true`). Passing `false` keeps trellis + progressive + Huffman optimization but skips the multi-pass scan search, trading ~0.7% larger files for ~30% faster encode on the MozJPEG path.
+- `algo: :jpeg_turbo` and `algo: :fast` are unchanged: baseline JPEG, same output as 0.2.4.
+
+**Performance improvements**
+
+- SSIM guard (`min_ssim:`) now uses an interpolation/secant probe instead of pure bisection. Once a failing and a passing sample are known, the crossing quality is predicted by linear interpolation and clamped inside the live bracket. The accept/reject invariant and the minimal passing quality are unchanged; typical inputs converge in fewer encode/decode/SSIM round trips.
+- In size mode, the SSIM guard scores candidates with a cheap "measurement" encode that skips `OPTIMIZE_SCANS` (which only affects entropy coding/scan layout, never the dequantized coefficients). The winning quality is re-encoded once with the full profile, and the true SSIM of the final output is re-checked, so `report[:ssim] >= min_ssim` continues to hold.
+- The `algo: :jpeg_turbo`/`:fast` JPEG→JPEG path now transcodes through YCbCr instead of RGB, skipping one color-space round trip. Grayscale and `compress_pixels` inputs are unaffected.
+
+**Other**
+
+- Added stricter smoke coverage for legacy aliases, default algorithm behavior, and parser-backed JPEG assertions.
+- Added `rake simd:check` and `rake release:check` so release builds cannot silently ship scalar x86_64 output unless `IMAGE_PACK_ALLOW_SCALAR=1` is set.
+
+## 0.2.4
+
+- libjpeg/MozJPEG diagnostics are no longer written to `stderr`; instead decode warnings (e.g. "Premature end of JPEG file") are counted and the first message is captured, so a damaged or truncated input is observable rather than silently degraded.
+- Added `strict:` to `compress`, `compress_pixels`, and `optimize_jpeg`. With `strict: true` the first libjpeg warning is promoted to `ImagePack::InvalidImageError` instead of producing a degraded JPEG; default is `false`.
+- Added `report:` to `compress` and `compress_pixels`. With `report: true` the call returns a Hash `{ output:, quality:, ssim:, algo:, bytesize:, input_bytesize:, warning_count:, warning: }`, exposing the SSIM-selected quality, achieved luma SSIM, and decode warning information; `report: false` (default) keeps the previous return value (binary `String` or `true`).
+- Made the no-GVL and offload execution paths interruptible regardless of `cancellable:`. Decode/encode/SSIM checkpoints now always observe the unblock signal, and a pending Ruby interrupt (signal, `Thread#raise`, `Thread#kill`, scheduler) is delivered via `rb_thread_check_ints` after the native section, so the raised exception propagates instead of being masked. Cancellation is expressed by raising on the worker thread; `ImagePack::CancelledError` is the idiomatic choice.
+- Added the `IMAGE_PACK_DISABLE_OFFLOAD=1` runtime opt-out. The vendored MozJPEG SIMD thread-local storage is only an idempotent CPU-feature cache, so offload remains safe with SIMD enabled, but the environment variable forces `offload_safe?` to `false` and prevents `:auto`/`:offload` from offloading.
+- `NATIVE_MOZJPEG_VERSION` is now derived from a dedicated `IMAGE_PACK_MOZJPEG_VERSION` compile define instead of relying on the libjpeg `VERSION` macro being in scope.
+- Removed the unused `IMAGE_PACK_RUBY34_ONLY` compile define.
+- Removed a stale `v0.2.2` reference from the `output:` argument error message.
+- Added tests covering `report:`, `strict:`, warning collection, the cancellation contract, offload availability, and version hygiene.
+- Documentation and message version references updated to 0.2.4.
+
+## 0.2.3
+
 - Lowered the runtime floor to Ruby >= 3.1.0 while keeping `execution: :offload` Ruby >= 3.4-only and explicitly unsupported on older Rubies.
+
 ## 0.2.2
 
 - Fixed native cleanup safety: native contexts are now released through `rb_ensure`, including Ruby exception paths from argument coercion, config reads, native status errors, output `String` allocation, and file-output failures.

data/README.md

@@ -1,199 +1,177 @@
 # image_pack
 
-`image_pack` is a Ruby-native JPEG compressor prototype for Ruby `>= 3.1.0`.
+Ruby-native JPEG compression and optimization backed by vendored pure-C MozJPEG/libjpeg.
 
-Current version: `0.2.2`.
-
-This pure-C variant intentionally removes Jpegli and any C++ toolchain requirement.
-The native layer is written in C and links against vendored MozJPEG, which is libjpeg-compatible and based on libjpeg-turbo.
-
-## Backends / modes
+No system `libjpeg`, `mozjpeg`, `git`, or `CMake` is required for gem users.
 
 ```ruby
-ImagePack.compress(input, algo: :jpeg_turbo)
-ImagePack.compress(input, algo: :mozjpeg)
+gem "image_pack"
 ```
 
-- `:jpeg_turbo` / `:fast` — fast libjpeg-compatible mode with MozJPEG-specific size optimizations disabled.
-- `:mozjpeg` / `:size` — size-oriented mode using optimized Huffman coding and optional progressive output through the MozJPEG/libjpeg API.
-
-Both modes produce ordinary `.jpg` files.
-
-Important implementation note: this prototype uses one pure-C vendored codec family to avoid static-link symbol conflicts between separate libjpeg-compatible libraries. If later we need exact latest `libjpeg-turbo` and exact MozJPEG in one gem, the correct next step is linker isolation / separate native extensions with hidden symbols.
-
-
-## Native extension layout
-
-For the first prototype the native layer intentionally lives in one file:
-
-```text
-ext/image_pack/
-├── extconf.rb
-└── image_pack.c
+```ruby
+require "image_pack"
 ```
 
-This mirrors the early `multi_compress` style: one translation unit is easier to expand, debug and refactor while the API and codec boundaries are still moving. The code can be split into modules later, after the first working version is stable.
-
-## API
+## Quick use
 
 ```ruby
-require "image_pack"
-
 jpeg = File.binread("photo.jpg")
 
-ImagePack.compress(jpeg, algo: :jpeg_turbo, quality: 82)
-ImagePack.compress(jpeg, algo: :mozjpeg, quality: 82)
+small = ImagePack.compress_bytes(jpeg, quality: 82)
+File.binwrite("photo.small.jpg", small)
 
-# SSIM-guarded compression: choose the smallest acceptable JPEG quality
-# while keeping decoded visual similarity >= 0.985.
-ImagePack.compress(jpeg, algo: :mozjpeg, min_ssim: 0.985)
-
-# Start at quality 75, but raise quality if needed to satisfy min_ssim.
-ImagePack.compress(jpeg, algo: :mozjpeg, quality: 75, min_ssim: 0.985)
+ImagePack.compress_file("photo.jpg", output: "photo.small.jpg")
+ImagePack.optimize_file("photo.jpg", output: "photo.optimized.jpg")
+```
 
-ImagePack.compress("photo.jpg", output: "photo.optimized.jpg", algo: :mozjpeg)
-ImagePack.compress_file("photo.jpg", output: "photo.optimized.jpg", algo: :mozjpeg)
-ImagePack.compress_bytes(jpeg, algo: :fast, quality: 82)
+Prefer explicit helpers:
 
-# Lossless coefficient-level JPEG optimization/transcode.
-# This rewrites JPEG coefficients without decoding/re-encoding pixels.
-ImagePack.optimize_jpeg(jpeg, progressive: true, strip_metadata: false)
-ImagePack.optimize_file("photo.jpg", output: "photo.lossless.jpg")
+```ruby
+ImagePack.compress_bytes(jpeg)
+ImagePack.compress_file("photo.jpg", output: "out.jpg")
 ImagePack.optimize_bytes(jpeg)
+ImagePack.optimize_file("photo.jpg", output: "out.jpg")
+```
 
-ImagePack.compress_pixels(rgb_buffer,
-  width: 1920,
-  height: 1080,
-  channels: 3,
-  algo: :mozjpeg
-)
+## Compression
 
-ImagePack.inspect_image(jpeg)
-# => { format: :jpeg, width: 1920, height: 1080, channels: 3, bit_depth: 8, decoded_bytes: 6220800 }
+```ruby
+ImagePack.compress_bytes(jpeg,
+  algo: :size,
+  quality: 82,
+  strip_metadata: true
+)
 ```
 
-## Input / output policy
+Algorithms:
 
-`compress(input, ...)` accepts JPEG input only:
+- `:size` / `:mozjpeg` — smaller files, default; uses optimized progressive MozJPEG output by default
+- `:fast` / `:jpeg_turbo` — faster baseline mode
 
-- binary `String` (`ASCII-8BIT`) — JPEG bytes;
-- non-binary `String` that points to an existing file — file path;
-- `Pathname` — file path;
-- `IO::Buffer` — JPEG bytes, copied before native no-GVL execution for safety.
+Common options:
 
-For non-ambiguous call sites prefer `compress_bytes(bytes, ...)` or `compress_file(path, ...)`.
-
-`compress_pixels(buffer, ...)` accepts raw pixels as binary `String` or `IO::Buffer`.
-`channels` must be `1`, `3`, or `4`. Alpha in RGBA input is dropped in v0.2.2; pass `drop_alpha: true` to make that explicit, or `drop_alpha: false` to reject it.
+```ruby
+ImagePack.compress_bytes(jpeg, min_ssim: 0.985)
+ImagePack.compress_bytes(jpeg, progressive: false) # force baseline output
+ImagePack.compress_bytes(jpeg, strict: true)
+ImagePack.compress_bytes(jpeg, report: true)
+```
 
-`output: nil` returns binary JPEG bytes. `output: String/Pathname` writes through a temporary file and renames it into place.
-Streaming output is intentionally not supported in v0.2.2.
 
-## Lossless JPEG optimize
+`algo: :size` / `:mozjpeg` now defaults to optimized progressive scans plus scan-aware MozJPEG trellis tuning because that is the strongest built-in size profile used by the gem. Pass `progressive: false` when you explicitly need baseline JPEG output.
 
-`optimize_jpeg`, `optimize_bytes`, and `optimize_file` are coefficient-level JPEG transcode helpers. They use `jpeg_read_coefficients` / `jpeg_write_coefficients`, so pixels are not decoded and re-encoded. This is the preferred path when you only want to rewrite an existing JPEG with optimized Huffman tables and optional progressive scans.
+`algo: :fast` / `:jpeg_turbo` keeps baseline output by default and remains the throughput path.
 
-Defaults are intentionally conservative:
+`min_ssim:` searches for the lowest acceptable quality using a fast native luma SSIM guard.
 
-- `progressive: true` creates a progressive optimized JPEG;
-- `strip_metadata: false` preserves APP/COM metadata by default because this path is meant to be visually/losslessly safe.
+`strict: true` raises `ImagePack::InvalidImageError` on damaged/truncated JPEG warnings.
 
-If `strip_metadata: true` is requested and the source JPEG has EXIF Orientation, `optimize_jpeg` raises `UnsupportedError` instead of silently removing the orientation tag and changing how viewers display the image. Use `strip_metadata: false` for coefficient-level optimization, or `compress(..., strip_metadata: true)` if you want pixel-level orientation normalization.
+`report: true` returns a Hash:
 
-## SSIM guard
+```ruby
+{
+  output: "\xFF\xD8...",
+  quality: 84,
+  ssim: 0.9861,
+  algo: :mozjpeg,
+  bytesize: 50122,
+  input_bytesize: 81344,
+  warning_count: 0,
+  warning: nil
+}
+```
 
-`compress` and `compress_pixels` accept `min_ssim:`. This enables a native guarded path:
+With `output: "file.jpg"`, `output` is `true`.
 
-1. decode the original JPEG to reference pixels;
-2. encode trial JPEG candidates with the existing MozJPEG/libjpeg backend;
-3. decode each candidate;
-4. compute a native luma SSIM score;
-5. return the smallest quality that satisfies `SSIM >= min_ssim`.
+## Lossless optimize
 
-If only `min_ssim:` is provided, the search starts at quality `1`. If both `quality:`
-and `min_ssim:` are provided, `quality:` is treated as the lower starting point and
-the encoder raises quality only if the candidate violates the SSIM floor.
+```ruby
+ImagePack.optimize_bytes(jpeg)
+ImagePack.optimize_file("photo.jpg", output: "photo.optimized.jpg")
+```
 
-If no quality can satisfy the requested floor, `ImagePack::QualityConstraintError`
-is raised. With `execution: :auto`, guarded compression uses the no-GVL/offload
-path instead of the small-image direct path because it may encode/decode several
-candidates. For `compress_pixels`, the reference is the raw pixel buffer itself, not a seed JPEG. RGBA + `min_ssim` is rejected because JPEG cannot represent alpha.
+This rewrites JPEG coefficients without decoding and re-encoding pixels. It is the right path for existing JPEGs when you only want optimized Huffman tables and optional progressive scans.
 
-The metric is a fast native luma SSIM-like guard based on 8x8 blocks, not a full Wang-style Gaussian-window reference implementation. It is intended as a compression guard, not as a general-purpose image quality benchmark.
+Defaults: `progressive: true`, `strip_metadata: false`.
 
-## Execution modes
+If `strip_metadata: true` would remove EXIF Orientation, `optimize_jpeg` raises `UnsupportedError` instead of silently changing visual orientation.
 
-### Ruby compatibility for offload
+## Raw pixels
 
-ImagePack supports Ruby `>= 3.1.0`. Ruby `>= 3.4.0` is required only for the scheduler-aware `execution: :offload` path.
+```ruby
+ImagePack.compress_pixels(rgb,
+  width: 1920,
+  height: 1080,
+  channels: 3,
+  output: "frame.jpg"
+)
+```
 
-On Ruby 3.1–3.3:
+`channels` must be `1`, `3`, or `4`. JPEG cannot store alpha, so RGBA input needs explicit opt-in:
 
-- `execution: :direct` works.
-- `execution: :nogvl` works.
-- `execution: :auto` works, but never selects `:offload`.
-- explicit `execution: :offload` raises `ImagePack::UnsupportedError`.
+```ruby
+ImagePack.compress_pixels(rgba, width: 100, height: 100, channels: 4, drop_alpha: true)
+```
 
-On Ruby 3.4+:
+## Inspect
 
-- `execution: :offload` is available.
-- `execution: :auto` may select `:offload` when a Fiber scheduler is active.
+```ruby
+ImagePack.inspect_image(jpeg)
+# => { format: :jpeg, width: 1920, height: 1080, channels: 3, bit_depth: 8, decoded_bytes: 6220800 }
+```
 
-Use `ImagePack.offload_safe?` or `ImagePack.build_info[:offload_safe]` to check the native capability at runtime.
+## Execution
 
+Default mode is `:auto`.
 
 ```ruby
-ImagePack.compress(jpeg, execution: :direct)
-ImagePack.compress(jpeg, execution: :nogvl)
-ImagePack.compress(jpeg, execution: :offload)
-ImagePack.compress(jpeg, execution: :auto)
+ImagePack.compress_bytes(jpeg, execution: :auto)
+ImagePack.compress_bytes(jpeg, execution: :direct)
+ImagePack.compress_bytes(jpeg, execution: :nogvl)
+ImagePack.compress_bytes(jpeg, execution: :offload) # Ruby >= 3.4 only
 ```
 
-- `:direct` — executes under GVL, intended for small images.
-- `:nogvl` — uses `rb_nogvl(..., flags: 0)`.
-- `:offload` — uses `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` on Ruby 3.4+; raises `ImagePack::UnsupportedError` on Ruby 3.1–3.3.
-- `:auto` — header-first policy chooses direct/nogvl/offload; on Ruby 3.1–3.3 it never selects offload.
-
-## Cancellation
+Use `ImagePack.offload_safe?` or `ImagePack.build_info` to inspect runtime support.
 
-`cancellable: true` is supported for `execution: :nogvl`, `:offload`, or `:auto`.
-Cancellation is cooperative at decode, encode, and SSIM-search checkpoints, not instant.
+Set `IMAGE_PACK_DISABLE_OFFLOAD=1` before loading the gem to disable offload.
 
-## Metadata / EXIF orientation
+Long no-GVL/offload calls can be interrupted by raising into the worker thread:
 
-`strip_metadata: true` removes metadata. If the source JPEG contains EXIF Orientation, `image_pack` applies that orientation to decoded pixels before stripping metadata, so the visual orientation is preserved. With `strip_metadata: false`, APP/COM markers are preserved across both fast and size-oriented paths.
+```ruby
+worker = Thread.new { ImagePack.compress_bytes(jpeg, execution: :nogvl, cancellable: true) }
+worker.raise(ImagePack::CancelledError, "cancelled")
+worker.join
+```
 
-## Build info
+## Configuration
 
 ```ruby
-ImagePack.build_info
-# => { version: "0.2.2", mozjpeg: "4.1.5", simd: true, offload_safe: true }
+ImagePack.configure do |config|
+  config.execution = :auto
+  config.max_input_size = 256 * 1024 * 1024
+  config.max_output_size = 256 * 1024 * 1024
+  config.max_pixels = 100_000_000
+end
 ```
 
-## Vendoring
-
-The gem is expected to ship vendored native sources/libs, so end users should not install system libjpeg/mozjpeg.
-For repository preparation:
+## Development
 
 ```bash
 bundle exec rake vendor
 bundle exec rake compile
+bundle exec rake test
+bundle exec rake release:check
 ```
 
 `rake vendor` pins MozJPEG `v4.1.5`.
 
-## Current limitations
-
-- Pixel-level `compress` rejects CMYK/YCCK JPEG input because it decodes to RGB/gray before re-encoding. Use `optimize_jpeg` for coefficient-level lossless optimization of existing CMYK/YCCK JPEGs.
-- Arithmetic-coded JPEG support is disabled in the vendored `jconfig.h` for v0.2.2.
-- The SSIM guard is a fast 8x8 luma block metric and still assumes quality/SSIM monotonicity during binary search.
-- `compress(input, ...)` still has a legacy path-vs-bytes heuristic for non-binary `String`; prefer `compress_bytes` / `compress_file` and `optimize_bytes` / `optimize_file` in new code.
+`rake release:check` compiles, verifies tests, and fails release builds when SIMD is unavailable. Set `IMAGE_PACK_ALLOW_SCALAR=1` only when intentionally shipping a scalar build.
 
-## What is intentionally not included
+## Limits
 
-- Jpegli / C++ code
-- AVIF/WebP/PNG
-- FFI
-- shell-out
-- external tempfiles for in-memory output
-- byte-size targets / max-bytes policy
+- JPEG only.
+- Ruby `>= 3.1`; `execution: :offload` requires Ruby `>= 3.4`.
+- Pixel-level `compress` rejects CMYK/YCCK JPEG input; use `optimize_jpeg` for existing CMYK/YCCK JPEGs.
+- Arithmetic-coded JPEG support is disabled in `0.2.5`.
+- Streaming output is not supported; file output uses atomic write-through-temp-file and rename.
+- `ImagePack.compress(input, ...)` keeps a legacy path-vs-bytes heuristic; prefer explicit `*_bytes` / `*_file` helpers.

data/ext/image_pack/extconf.rb

@@ -416,8 +416,8 @@ else
   $CFLAGS += " -O2"
 end
 
-$CFLAGS += " -DIMAGE_PACK_RUBY34_ONLY=1"
 $CFLAGS += build_info[:with_simd] ? " -DIMAGE_PACK_HAS_SIMD=1" : " -DIMAGE_PACK_PURE_C=1"
+$CPPFLAGS += " -DIMAGE_PACK_MOZJPEG_VERSION=\\\"#{MOZJPEG_VERSION}\\\""
 $LIBS += " -lm" unless msvc?
 
 have_header("ruby/thread.h") or abort "ruby/thread.h not found"

data/ext/image_pack/image_pack.c

@@ -40,6 +40,10 @@
 #define TRUE 1
 #endif
 
+#ifndef IMAGE_PACK_MOZJPEG_VERSION
+#define IMAGE_PACK_MOZJPEG_VERSION VERSION
+#endif
+
 #ifndef FALSE
 #define FALSE 0
 #endif
@@ -133,6 +137,7 @@ typedef struct {
     int progressive;
     int strip_metadata;
     int mozjpeg_trellis_enabled;
+    int mozjpeg_scan_opt_enabled;
     ip_algo_t algo;
     ip_execution_t requested_execution;
     ip_execution_t resolved_execution;
@@ -151,6 +156,9 @@ typedef struct {
 
     atomic_int cancelled;
     int cancellable_requested;
+    int strict;
+    int warning_count;
+    char first_warning[200];
 
     jmp_buf jmpbuf;
     int jmp_armed;
@@ -166,6 +174,7 @@ typedef struct {
     unsigned char *transient_jpeg_buf;
     unsigned char *transient_decode_buf;
     int source_orientation;
+    int decoded_as_ycbcr;
 } ip_context_t;
 
 typedef struct {
@@ -174,6 +183,7 @@ typedef struct {
 } ip_jpeg_error_mgr;
 
 static VALUE rb_mImagePack;
+static int ip_offload_runtime_enabled = 1;
 static VALUE rb_eImagePackError;
 static VALUE rb_eImagePackInvalidArgumentError;
 static VALUE rb_eImagePackInvalidImageError;
@@ -243,7 +253,8 @@ static int ip_run_context(ip_context_t *ctx);
 static void validate_limits_for_pixels(ip_context_t *ctx);
 
 static int ip_jpeg_decode_to_pixels(ip_context_t *ctx, unsigned char **pixels, int *width,
-                                    int *height, int *channels, int fast_decode_mode);
+                                    int *height, int *channels, int fast_decode_mode,
+                                    int allow_ycbcr_transcode);
 static int ip_decode_jpeg_to_luma_buffer(ip_context_t *ctx, const unsigned char *data, size_t size,
                                          unsigned char **luma, int *width, int *height);
 static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_size_mode);
@@ -255,18 +266,20 @@ static int ip_run_optimize_context(ip_context_t *ctx);
 typedef struct {
     VALUE self, input, input_kind, output, output_kind, algo, quality, min_ssim;
     VALUE mozjpeg_trellis, progressive, strip_metadata, execution, cancellable, has_scheduler;
+    VALUE report, strict, mozjpeg_scan_opt;
     ip_context_t *ctx;
 } ip_compress_jpeg_call_t;
 
 typedef struct {
     VALUE self, buffer, width, height, channels, output, output_kind, algo, quality, min_ssim;
     VALUE mozjpeg_trellis, progressive, exact_size, execution, cancellable, has_scheduler;
+    VALUE report, strict, mozjpeg_scan_opt;
     ip_context_t *ctx;
 } ip_compress_pixels_call_t;
 
 typedef struct {
     VALUE self, input, input_kind, output, output_kind, progressive, strip_metadata;
-    VALUE execution, cancellable, has_scheduler;
+    VALUE execution, cancellable, has_scheduler, strict;
     ip_context_t *ctx;
 } ip_optimize_jpeg_call_t;
 
@@ -284,18 +297,12 @@ static VALUE ip_call_cleanup(VALUE ptr) {
     return Qnil;
 }
 
-static VALUE ip_compress_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
-                                    VALUE output_kind, VALUE algo, VALUE quality, VALUE min_ssim,
-                                    VALUE mozjpeg_trellis, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler);
-static VALUE ip_compress_pixels_entry(VALUE self, VALUE buffer, VALUE width, VALUE height,
-                                      VALUE channels, VALUE output, VALUE output_kind, VALUE algo,
-                                      VALUE quality, VALUE min_ssim, VALUE mozjpeg_trellis,
-                                      VALUE progressive, VALUE exact_size, VALUE execution,
-                                      VALUE cancellable, VALUE has_scheduler);
+static VALUE ip_compress_jpeg_entry(int argc, VALUE *argv, VALUE self);
+static VALUE ip_compress_pixels_entry(int argc, VALUE *argv, VALUE self);
 static VALUE ip_optimize_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
                                     VALUE output_kind, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler);
+                                    VALUE execution, VALUE cancellable, VALUE has_scheduler,
+                                    VALUE strict);
 
 static VALUE ip_status_to_exception(ip_status_t status) {
     switch (status) {
@@ -440,6 +447,7 @@ static ip_context_t *ip_context_new(void) {
     ctx->status = IP_OK;
     ctx->quality = 82;
     ctx->mozjpeg_trellis_enabled = 1;
+    ctx->mozjpeg_scan_opt_enabled = 1;
     ctx->selected_quality = 82;
     ctx->requested_execution = IP_EXEC_AUTO;
     ctx->resolved_execution = IP_EXEC_AUTO;
@@ -543,10 +551,43 @@ static VALUE ip_sym(const char *name) {
     return ID2SYM(rb_intern(name));
 }
 
+static void ip_jpeg_emit_message_collect(j_common_ptr cinfo, int msg_level) {
+    if (msg_level >= 0)
+        return;
+
+    ip_jpeg_error_mgr *err = (ip_jpeg_error_mgr *)cinfo->err;
+    ip_context_t *ctx = err->ctx;
+    if (!ctx)
+        return;
+
+    ctx->warning_count++;
+    if (ctx->first_warning[0] == '\0') {
+        char buffer[JMSG_LENGTH_MAX];
+        (*cinfo->err->format_message)(cinfo, buffer);
+        snprintf(ctx->first_warning, sizeof(ctx->first_warning), "%s", buffer);
+    }
+
+    if (ctx->strict) {
+        if (ctx->status == IP_OK) {
+            char buffer[JMSG_LENGTH_MAX];
+            (*cinfo->err->format_message)(cinfo, buffer);
+            ip_context_set_error(ctx, IP_ERR_INVALID_IMAGE, buffer);
+        }
+        if (ctx->jmp_armed)
+            longjmp(ctx->jmpbuf, 1);
+    }
+}
+
+static void ip_jpeg_output_message_silent(j_common_ptr cinfo) {
+    (void)cinfo;
+}
+
 static struct jpeg_error_mgr *ip_use_error(ip_jpeg_error_mgr *jerr, ip_context_t *ctx,
                                            void (*handler)(j_common_ptr)) {
     struct jpeg_error_mgr *base = jpeg_std_error(&jerr->pub);
     jerr->pub.error_exit = handler;
+    jerr->pub.emit_message = ip_jpeg_emit_message_collect;
+    jerr->pub.output_message = ip_jpeg_output_message_silent;
     jerr->ctx = ctx;
     return base;
 }
@@ -876,6 +917,23 @@ static VALUE ip_finish_output(ip_context_t *ctx, ip_output_kind_t kind) {
     return Qtrue;
 }
 
+static VALUE ip_build_report(ip_context_t *ctx, VALUE output_value) {
+    VALUE hash = rb_hash_new();
+    rb_hash_aset(hash, ip_sym("output"), output_value);
+    rb_hash_aset(hash, ip_sym("quality"), INT2NUM(ctx->selected_quality));
+    rb_hash_aset(hash, ip_sym("ssim"),
+                 ctx->ssim_guard_enabled ? DBL2NUM(ctx->measured_ssim) : Qnil);
+    rb_hash_aset(hash, ip_sym("algo"),
+                 ctx->algo == IP_ALGO_MOZJPEG ? ip_sym("mozjpeg") : ip_sym("jpeg_turbo"));
+    rb_hash_aset(hash, ip_sym("bytesize"), SIZET2NUM(ctx->output_size));
+    rb_hash_aset(hash, ip_sym("input_bytesize"),
+                 SIZET2NUM(ctx->input_size > 0 ? ctx->input_size : ctx->pixel_size));
+    rb_hash_aset(hash, ip_sym("warning_count"), INT2NUM(ctx->warning_count));
+    rb_hash_aset(hash, ip_sym("warning"),
+                 ctx->first_warning[0] ? rb_str_new_cstr(ctx->first_warning) : Qnil);
+    return hash;
+}
+
 static int ip_save_marker(ip_context_t *ctx, int marker, const unsigned char *data,
                           unsigned int len) {
     if (ctx->preserved_marker_count == ctx->preserved_marker_capacity) {
@@ -1219,13 +1277,21 @@ static void configure_mozjpeg_profile_before_defaults(struct jpeg_compress_struc
 static void configure_mozjpeg_features_after_defaults(struct jpeg_compress_struct *cinfo,
                                                       int mozjpeg_size_mode,
                                                       int progressive_requested,
-                                                      int mozjpeg_trellis_enabled) {
+                                                      int mozjpeg_trellis_enabled,
+                                                      int scan_opt_enabled, int measurement) {
     if (mozjpeg_size_mode) {
         cinfo->optimize_coding = TRUE;
 
         if (progressive_requested) {
+            if (mozjpeg_trellis_enabled) {
+                jpeg_c_set_bool_param(cinfo, JBOOLEAN_USE_SCANS_IN_TRELLIS, TRUE);
+                jpeg_c_set_bool_param(cinfo, JBOOLEAN_TRELLIS_EOB_OPT, TRUE);
+            }
+            jpeg_c_set_int_param(cinfo, JINT_DC_SCAN_OPT_MODE, 2);
+            int run_scan_search = (measurement || !scan_opt_enabled) ? FALSE : TRUE;
+            jpeg_c_set_bool_param(cinfo, JBOOLEAN_OPTIMIZE_SCANS, run_scan_search);
             jpeg_simple_progression(cinfo);
-            jpeg_c_set_bool_param(cinfo, JBOOLEAN_OPTIMIZE_SCANS, TRUE);
+            jpeg_c_set_bool_param(cinfo, JBOOLEAN_OPTIMIZE_SCANS, run_scan_search);
         } else {
             cinfo->scan_info = NULL;
             cinfo->num_scans = 0;
@@ -1250,7 +1316,7 @@ static void configure_mozjpeg_features_after_defaults(struct jpeg_compress_struc
     }
 }
 
-static int encode_pixels_with_libjpeg(ip_context_t *ctx, int mozjpeg_size_mode) {
+static int encode_pixels_with_libjpeg(ip_context_t *ctx, int mozjpeg_size_mode, int measurement) {
     struct jpeg_compress_struct cinfo;
     ip_jpeg_error_mgr jerr;
     unsigned long jpeg_size = 0;
@@ -1272,14 +1338,19 @@ static int encode_pixels_with_libjpeg(ip_context_t *ctx, int mozjpeg_size_mode)
     cinfo.image_width = (JDIMENSION)ctx->width;
     cinfo.image_height = (JDIMENSION)ctx->height;
     cinfo.input_components = ctx->channels;
-    cinfo.in_color_space =
-        ctx->channels == 4 ? JCS_EXT_RGBA : color_space_for_channels(ctx->channels);
+    if (ctx->decoded_as_ycbcr && ctx->channels == 3) {
+        cinfo.in_color_space = JCS_YCbCr;
+    } else {
+        cinfo.in_color_space =
+            ctx->channels == 4 ? JCS_EXT_RGBA : color_space_for_channels(ctx->channels);
+    }
 
     configure_mozjpeg_profile_before_defaults(&cinfo, mozjpeg_size_mode);
     jpeg_set_defaults(&cinfo);
     jpeg_set_quality(&cinfo, ctx->quality, TRUE);
     configure_mozjpeg_features_after_defaults(&cinfo, mozjpeg_size_mode, ctx->progressive,
-                                              ctx->mozjpeg_trellis_enabled);
+                                              ctx->mozjpeg_trellis_enabled,
+                                              ctx->mozjpeg_scan_opt_enabled, measurement);
 
     jpeg_start_compress(&cinfo, TRUE);
 
@@ -1287,7 +1358,7 @@ static int encode_pixels_with_libjpeg(ip_context_t *ctx, int mozjpeg_size_mode)
         ip_write_preserved_markers(ctx, &cinfo);
 
     while (cinfo.next_scanline < cinfo.image_height) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+        if (atomic_load(&ctx->cancelled))
             IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "JPEG encode cancelled");
 
         JSAMPROW rows[16];
@@ -1305,7 +1376,7 @@ static int encode_pixels_with_libjpeg(ip_context_t *ctx, int mozjpeg_size_mode)
 
     jpeg_finish_compress(&cinfo);
 
-    if (ctx->max_output_size > 0 && (size_t)jpeg_size > ctx->max_output_size)
+    if (!measurement && ctx->max_output_size > 0 && (size_t)jpeg_size > ctx->max_output_size)
         IP_FAIL_GOTO(ctx, IP_ERR_LIMIT, "output exceeds max_output_size");
 
     jpeg_destroy_compress(&cinfo);
@@ -1326,7 +1397,8 @@ fail:
 }
 
 static int ip_jpeg_decode_to_pixels(ip_context_t *ctx, unsigned char **pixels, int *width,
-                                    int *height, int *channels, int fast_decode_mode) {
+                                    int *height, int *channels, int fast_decode_mode,
+                                    int allow_ycbcr_transcode) {
     struct jpeg_decompress_struct cinfo;
     ip_jpeg_error_mgr jerr;
     memset(&cinfo, 0, sizeof(cinfo));
@@ -1334,6 +1406,7 @@ static int ip_jpeg_decode_to_pixels(ip_context_t *ctx, unsigned char **pixels, i
     cinfo.err = ip_use_error(&jerr, ctx, ip_jpeg_invalid_error_exit);
     ctx->transient_decode_buf = NULL;
     ctx->source_orientation = 1;
+    ctx->decoded_as_ycbcr = 0;
 
     ctx->jmp_armed = 1;
     if (setjmp(ctx->jmpbuf)) {
@@ -1377,7 +1450,9 @@ static int ip_jpeg_decode_to_pixels(ip_context_t *ctx, unsigned char **pixels, i
     if (ctx->status != IP_OK)
         goto fail;
 
-    cinfo.out_color_space = ch == 1 ? JCS_GRAYSCALE : JCS_RGB;
+    int use_ycbcr = allow_ycbcr_transcode && ch == 3;
+    cinfo.out_color_space = ch == 1 ? JCS_GRAYSCALE : (use_ycbcr ? JCS_YCbCr : JCS_RGB);
+    ctx->decoded_as_ycbcr = use_ycbcr;
     if (fast_decode_mode)
         ip_apply_fast_decode(&cinfo);
 
@@ -1398,7 +1473,7 @@ static int ip_jpeg_decode_to_pixels(ip_context_t *ctx, unsigned char **pixels, i
         IP_FAIL_GOTO(ctx, IP_ERR_OOM, "failed to allocate decoded pixel buffer");
 
     while (cinfo.output_scanline < cinfo.output_height) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+        if (atomic_load(&ctx->cancelled))
             IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "JPEG decode cancelled");
 
         JSAMPROW rows[16];
@@ -1455,14 +1530,14 @@ fail:
 
 static int compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_size_mode) {
     if (ctx->pixel_data) {
-        return encode_pixels_with_libjpeg(ctx, mozjpeg_size_mode);
+        return encode_pixels_with_libjpeg(ctx, mozjpeg_size_mode, 0);
     }
 
     unsigned char *pixels = NULL;
     int width = 0;
     int height = 0;
     int channels = 0;
-    if (!ip_jpeg_decode_to_pixels(ctx, &pixels, &width, &height, &channels, !mozjpeg_size_mode))
+    if (!ip_jpeg_decode_to_pixels(ctx, &pixels, &width, &height, &channels, !mozjpeg_size_mode, 1))
         return 0;
 
     ctx->owned_pixel_data = pixels;
@@ -1473,7 +1548,7 @@ static int compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_size_mod
     ctx->channels = channels;
     ctx->decoded_bytes = ctx->pixel_size;
 
-    return encode_pixels_with_libjpeg(ctx, mozjpeg_size_mode);
+    return encode_pixels_with_libjpeg(ctx, mozjpeg_size_mode, 0);
 }
 
 static void ip_clear_output_buffer(ip_context_t *ctx) {
@@ -1558,7 +1633,7 @@ static int ip_decode_jpeg_to_luma_buffer(ip_context_t *ctx, const unsigned char
         IP_FAIL_GOTO(ctx, IP_ERR_OOM, "failed to allocate luma buffer");
 
     while (cinfo.output_scanline < cinfo.output_height) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+        if (atomic_load(&ctx->cancelled))
             IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "JPEG luma decode cancelled");
 
         JSAMPROW rows[16];
@@ -1763,6 +1838,49 @@ static double ip_compute_ssim_luma_buffer(const unsigned char *a, const unsigned
     return windows > 0 ? total_ssim / (double)windows : 0.0;
 }
 
+static int ip_guard_score_quality(ip_context_t *ctx, int mozjpeg_size_mode, int measurement,
+                                  const unsigned char *reference_luma, int reference_width,
+                                  int reference_height, unsigned char **out_jpeg,
+                                  size_t *out_jpeg_size, double *out_ssim) {
+    *out_jpeg = NULL;
+    *out_jpeg_size = 0;
+    *out_ssim = 0.0;
+
+    ip_clear_output_buffer(ctx);
+    if (!encode_pixels_with_libjpeg(ctx, mozjpeg_size_mode, measurement))
+        return 0;
+
+    unsigned char *candidate_jpeg = ctx->output_data;
+    size_t candidate_jpeg_size = ctx->output_size;
+    ctx->output_data = NULL;
+    ctx->output_size = 0;
+    ctx->output_owner = IP_OUTPUT_OWNER_NONE;
+
+    unsigned char *candidate_luma = NULL;
+    int candidate_width = 0;
+    int candidate_height = 0;
+    if (!ip_decode_jpeg_to_luma_buffer(ctx, candidate_jpeg, candidate_jpeg_size, &candidate_luma,
+                                       &candidate_width, &candidate_height)) {
+        free(candidate_jpeg);
+        return 0;
+    }
+
+    if (candidate_width != reference_width || candidate_height != reference_height) {
+        free(candidate_luma);
+        free(candidate_jpeg);
+        ip_context_set_error(ctx, IP_ERR_ENCODE,
+                             "candidate JPEG dimensions differ from reference image");
+        return 0;
+    }
+
+    *out_ssim = ip_compute_ssim_luma_buffer(reference_luma, candidate_luma, reference_width,
+                                            reference_height);
+    free(candidate_luma);
+    *out_jpeg = candidate_jpeg;
+    *out_jpeg_size = candidate_jpeg_size;
+    return 1;
+}
+
 static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_size_mode) {
     unsigned char *reference_pixels = NULL;
     int reference_width = 0;
@@ -1776,7 +1894,7 @@ static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_
         reference_channels = ctx->channels;
     } else {
         if (!ip_jpeg_decode_to_pixels(ctx, &reference_pixels, &reference_width, &reference_height,
-                                      &reference_channels, 1)) {
+                                      &reference_channels, 1, 0)) {
             return 0;
         }
 
@@ -1791,8 +1909,7 @@ static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_
     }
 
     if (reference_channels == 4) {
-        ip_context_set_error(ctx, IP_ERR_UNSUPPORTED,
-                             "min_ssim is not supported for RGBA input in v0.2.2");
+        ip_context_set_error(ctx, IP_ERR_UNSUPPORTED, "min_ssim is not supported for RGBA input");
         return 0;
     }
 
@@ -1809,59 +1926,45 @@ static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_
     size_t best_jpeg_size = 0;
     double best_seen_ssim = 0.0;
     int best_seen_quality = 0;
+    int probe_measurement = mozjpeg_size_mode ? 1 : 0;
+    int have_lo = 0, have_hi = 0;
+    int q_lo = 0, q_hi = 0;
+    double s_lo = 0.0, s_hi = 0.0;
 
     while (search_low <= search_high) {
-        if (ctx->cancellable_requested && atomic_load(&ctx->cancelled)) {
+        if (atomic_load(&ctx->cancelled)) {
             free(reference_luma);
             free(best_jpeg);
             ip_context_set_error(ctx, IP_ERR_CANCELLED, "SSIM-guarded JPEG encode cancelled");
             return 0;
         }
 
-        int trial_quality = search_low + ((search_high - search_low) / 2);
-        ctx->quality = trial_quality;
-        ip_clear_output_buffer(ctx);
-
-        if (!encode_pixels_with_libjpeg(ctx, mozjpeg_size_mode)) {
-            free(reference_luma);
-            free(best_jpeg);
-            return 0;
+        int trial_quality;
+        if (have_lo && have_hi && s_hi > s_lo) {
+            double t = (ctx->min_ssim - s_lo) / (s_hi - s_lo);
+            double q_est = (double)q_lo + t * (double)(q_hi - q_lo);
+            trial_quality = (int)(q_est + 0.5);
+            if (trial_quality < search_low)
+                trial_quality = search_low;
+            if (trial_quality > search_high)
+                trial_quality = search_high;
+        } else {
+            trial_quality = search_low + ((search_high - search_low) / 2);
         }
 
-        unsigned char *candidate_jpeg = ctx->output_data;
-        size_t candidate_jpeg_size = ctx->output_size;
-        ctx->output_data = NULL;
-        ctx->output_size = 0;
-        ctx->output_owner = IP_OUTPUT_OWNER_NONE;
-
-        unsigned char *candidate_luma = NULL;
-        int candidate_width = 0;
-        int candidate_height = 0;
-        int decoded_ok =
-            ip_decode_jpeg_to_luma_buffer(ctx, candidate_jpeg, candidate_jpeg_size, &candidate_luma,
-                                          &candidate_width, &candidate_height);
-
-        if (!decoded_ok) {
-            free(reference_luma);
-            free(candidate_jpeg);
-            free(best_jpeg);
-            return 0;
-        }
+        ctx->quality = trial_quality;
 
-        if (candidate_width != reference_width || candidate_height != reference_height) {
+        unsigned char *candidate_jpeg = NULL;
+        size_t candidate_jpeg_size = 0;
+        double ssim = 0.0;
+        if (!ip_guard_score_quality(ctx, mozjpeg_size_mode, probe_measurement, reference_luma,
+                                    reference_width, reference_height, &candidate_jpeg,
+                                    &candidate_jpeg_size, &ssim)) {
             free(reference_luma);
-            free(candidate_luma);
-            free(candidate_jpeg);
             free(best_jpeg);
-            ip_context_set_error(ctx, IP_ERR_ENCODE,
-                                 "candidate JPEG dimensions differ from reference image");
             return 0;
         }
 
-        double ssim = ip_compute_ssim_luma_buffer(reference_luma, candidate_luma, reference_width,
-                                                  reference_height);
-        free(candidate_luma);
-
         if (ssim > best_seen_ssim) {
             best_seen_ssim = ssim;
             best_seen_quality = trial_quality;
@@ -1873,9 +1976,15 @@ static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_
             best_jpeg_size = candidate_jpeg_size;
             best_quality = trial_quality;
             best_ssim = ssim;
+            q_hi = trial_quality;
+            s_hi = ssim;
+            have_hi = 1;
             search_high = trial_quality - 1;
         } else {
             free(candidate_jpeg);
+            q_lo = trial_quality;
+            s_lo = ssim;
+            have_lo = 1;
             search_low = trial_quality + 1;
         }
     }
@@ -1890,13 +1999,75 @@ static int guarded_compress_jpeg_input_with_mode(ip_context_t *ctx, int mozjpeg_
         return 0;
     }
 
-    ctx->quality = best_quality;
-    ctx->selected_quality = best_quality;
-    ctx->measured_ssim = best_ssim;
+    if (!mozjpeg_size_mode) {
+        ctx->quality = best_quality;
+        ctx->selected_quality = best_quality;
+        ctx->measured_ssim = best_ssim;
+        free(reference_luma);
+        ctx->output_data = best_jpeg;
+        ctx->output_size = best_jpeg_size;
+        ctx->output_owner = IP_OUTPUT_OWNER_MALLOC;
+        return 1;
+    }
+
+    free(best_jpeg);
+    best_jpeg = NULL;
+
+    int final_quality = best_quality;
+    unsigned char *final_jpeg = NULL;
+    size_t final_jpeg_size = 0;
+    double final_ssim = 0.0;
+    int satisfied = 0;
+
+    while (final_quality <= 100) {
+        if (atomic_load(&ctx->cancelled)) {
+            free(final_jpeg);
+            free(reference_luma);
+            ip_context_set_error(ctx, IP_ERR_CANCELLED, "SSIM-guarded JPEG encode cancelled");
+            return 0;
+        }
+
+        ctx->quality = final_quality;
+        unsigned char *jpeg = NULL;
+        size_t jpeg_size = 0;
+        double ssim = 0.0;
+        if (!ip_guard_score_quality(ctx, mozjpeg_size_mode, 0, reference_luma, reference_width,
+                                    reference_height, &jpeg, &jpeg_size, &ssim)) {
+            free(final_jpeg);
+            free(reference_luma);
+            return 0;
+        }
+
+        free(final_jpeg);
+        final_jpeg = jpeg;
+        final_jpeg_size = jpeg_size;
+        final_ssim = ssim;
+
+        if (ssim >= ctx->min_ssim) {
+            satisfied = 1;
+            break;
+        }
+        final_quality++;
+    }
+
+    if (!satisfied) {
+        char message[512];
+        snprintf(message, sizeof(message),
+                 "cannot satisfy min_ssim=%.6f; best full-profile SSIM %.6f at quality=100",
+                 ctx->min_ssim, final_ssim);
+        free(final_jpeg);
+        free(reference_luma);
+        ip_context_set_error(ctx, IP_ERR_QUALITY, message);
+        return 0;
+    }
+
     free(reference_luma);
 
-    ctx->output_data = best_jpeg;
-    ctx->output_size = best_jpeg_size;
+    ctx->quality = final_quality;
+    ctx->selected_quality = final_quality;
+    ctx->measured_ssim = final_ssim;
+    ctx->output_data = final_jpeg;
+    ctx->output_size = final_jpeg_size;
     ctx->output_owner = IP_OUTPUT_OWNER_MALLOC;
     return 1;
 }
@@ -1959,7 +2130,7 @@ static int ip_lossless_optimize_jpeg(ip_context_t *ctx) {
     jpeg_mem_src(&srcinfo, ctx->input_data, (unsigned long)ctx->input_size);
     ip_setup_marker_saving(&srcinfo, ctx->strip_metadata);
 
-    if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+    if (atomic_load(&ctx->cancelled))
         IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "lossless JPEG optimize cancelled");
 
     if (jpeg_read_header(&srcinfo, TRUE) != JPEG_HEADER_OK)
@@ -1989,7 +2160,7 @@ static int ip_lossless_optimize_jpeg(ip_context_t *ctx) {
 
     jpeg_mem_dest(&dstinfo, &ctx->transient_jpeg_buf, &jpeg_size);
 
-    if (ctx->cancellable_requested && atomic_load(&ctx->cancelled))
+    if (atomic_load(&ctx->cancelled))
         IP_FAIL_GOTO(ctx, IP_ERR_CANCELLED, "lossless JPEG optimize cancelled");
 
     jpeg_write_coefficients(&dstinfo, coef_arrays);
@@ -2035,7 +2206,7 @@ static int ip_mozjpeg_compress(ip_context_t *ctx) {
 
 static ip_execution_t ip_async_execution(const ip_context_t *ctx) {
 #if IMAGE_PACK_HAS_OFFLOAD_SAFE
-    return ctx->has_scheduler ? IP_EXEC_OFFLOAD : IP_EXEC_NOGVL;
+    return (ip_offload_runtime_enabled && ctx->has_scheduler) ? IP_EXEC_OFFLOAD : IP_EXEC_NOGVL;
 #else
     (void)ctx;
     return IP_EXEC_NOGVL;
@@ -2105,12 +2276,16 @@ static int ip_run_context(ip_context_t *ctx) {
         rb_nogvl(ip_run_encode_nogvl, ctx, ip_unblock_function, ctx, RB_NOGVL_OFFLOAD_SAFE);
 #else
         ip_context_set_error(ctx, IP_ERR_UNSUPPORTED,
-                             "offload execution requires Ruby >= 3.4; use :nogvl or :auto");
+                             "offload execution is unavailable in this runtime; it requires Ruby "
+                             ">= 3.4 and IMAGE_PACK_DISABLE_OFFLOAD must not be set");
 #endif
     } else {
         ip_context_set_error(ctx, IP_ERR_INVALID_ARGUMENT, "invalid resolved execution mode");
     }
 
+    if (ctx->resolved_execution != IP_EXEC_DIRECT)
+        rb_thread_check_ints();
+
     return ctx->status == IP_OK;
 }
 
@@ -2133,12 +2308,16 @@ static int ip_run_optimize_context(ip_context_t *ctx) {
         rb_nogvl(ip_run_optimize_nogvl, ctx, ip_unblock_function, ctx, RB_NOGVL_OFFLOAD_SAFE);
 #else
         ip_context_set_error(ctx, IP_ERR_UNSUPPORTED,
-                             "offload execution requires Ruby >= 3.4; use :nogvl or :auto");
+                             "offload execution is unavailable in this runtime; it requires Ruby "
+                             ">= 3.4 and IMAGE_PACK_DISABLE_OFFLOAD must not be set");
 #endif
     } else {
         ip_context_set_error(ctx, IP_ERR_INVALID_ARGUMENT, "invalid resolved execution mode");
     }
 
+    if (ctx->resolved_execution != IP_EXEC_DIRECT)
+        rb_thread_check_ints();
+
     return ctx->status == IP_OK;
 }
 
@@ -2215,11 +2394,13 @@ static VALUE ip_compress_jpeg_entry_body(VALUE ptr) {
     ctx->ssim_guard_enabled = ctx->min_ssim > 0.0;
     ip_validate_min_ssim_or_raise(ctx);
     ctx->mozjpeg_trellis_enabled = ip_bool_value(call->mozjpeg_trellis);
+    ctx->mozjpeg_scan_opt_enabled = ip_bool_value(call->mozjpeg_scan_opt);
     ctx->progressive = ip_bool_value(call->progressive);
     ctx->strip_metadata = ip_bool_value(call->strip_metadata);
     ctx->requested_execution = ip_parse_execution(call->execution);
     ctx->cancellable_requested = ip_bool_value(call->cancellable);
     ctx->has_scheduler = ip_bool_value(call->has_scheduler);
+    ctx->strict = ip_bool_value(call->strict);
     apply_configuration(call->self, ctx);
 
     ip_input_kind_t in_kind = ip_parse_input_kind(call->input_kind);
@@ -2242,17 +2423,18 @@ static VALUE ip_compress_jpeg_entry_body(VALUE ptr) {
     }
 
     ip_run_context(ctx);
+    if (ip_bool_value(call->report)) {
+        VALUE output_value = ip_finish_output(ctx, out_kind);
+        return ip_build_report(ctx, output_value);
+    }
     return ip_finish_output(ctx, out_kind);
 }
 
-static VALUE ip_compress_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
-                                    VALUE output_kind, VALUE algo, VALUE quality, VALUE min_ssim,
-                                    VALUE mozjpeg_trellis, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler) {
-    ip_compress_jpeg_call_t call = {
-        self,           input,     input_kind,  output,          output_kind,
-        algo,           quality,   min_ssim,    mozjpeg_trellis, progressive,
-        strip_metadata, execution, cancellable, has_scheduler,   NULL};
+static VALUE ip_compress_jpeg_entry(int argc, VALUE *argv, VALUE self) {
+    rb_check_arity(argc, 16, 16);
+    ip_compress_jpeg_call_t call = {self,     argv[0],  argv[1],  argv[2],  argv[3],  argv[4],
+                                    argv[5],  argv[6],  argv[7],  argv[8],  argv[9],  argv[10],
+                                    argv[11], argv[12], argv[13], argv[14], argv[15], NULL};
     return rb_ensure(ip_compress_jpeg_entry_body, (VALUE)&call, ip_call_cleanup, (VALUE)&call.ctx);
 }
 
@@ -2272,11 +2454,13 @@ static VALUE ip_compress_pixels_entry_body(VALUE ptr) {
     ctx->ssim_guard_enabled = ctx->min_ssim > 0.0;
     ip_validate_min_ssim_or_raise(ctx);
     ctx->mozjpeg_trellis_enabled = ip_bool_value(call->mozjpeg_trellis);
+    ctx->mozjpeg_scan_opt_enabled = ip_bool_value(call->mozjpeg_scan_opt);
     ctx->progressive = ip_bool_value(call->progressive);
     ctx->strip_metadata = 1;
     ctx->requested_execution = ip_parse_execution(call->execution);
     ctx->cancellable_requested = ip_bool_value(call->cancellable);
     ctx->has_scheduler = ip_bool_value(call->has_scheduler);
+    ctx->strict = ip_bool_value(call->strict);
     apply_configuration(call->self, ctx);
 
     if (!ip_prepare_output_path(ctx, call->output, out_kind) ||
@@ -2297,18 +2481,19 @@ static VALUE ip_compress_pixels_entry_body(VALUE ptr) {
     }
 
     ip_run_context(ctx);
+    if (ip_bool_value(call->report)) {
+        VALUE output_value = ip_finish_output(ctx, out_kind);
+        return ip_build_report(ctx, output_value);
+    }
     return ip_finish_output(ctx, out_kind);
 }
 
-static VALUE ip_compress_pixels_entry(VALUE self, VALUE buffer, VALUE width, VALUE height,
-                                      VALUE channels, VALUE output, VALUE output_kind, VALUE algo,
-                                      VALUE quality, VALUE min_ssim, VALUE mozjpeg_trellis,
-                                      VALUE progressive, VALUE exact_size, VALUE execution,
-                                      VALUE cancellable, VALUE has_scheduler) {
-    ip_compress_pixels_call_t call = {
-        self,        buffer,        width,    height,          channels,    output,     output_kind,
-        algo,        quality,       min_ssim, mozjpeg_trellis, progressive, exact_size, execution,
-        cancellable, has_scheduler, NULL};
+static VALUE ip_compress_pixels_entry(int argc, VALUE *argv, VALUE self) {
+    rb_check_arity(argc, 18, 18);
+    ip_compress_pixels_call_t call = {self,     argv[0],  argv[1],  argv[2],  argv[3],
+                                      argv[4],  argv[5],  argv[6],  argv[7],  argv[8],
+                                      argv[9],  argv[10], argv[11], argv[12], argv[13],
+                                      argv[14], argv[15], argv[16], argv[17], NULL};
     return rb_ensure(ip_compress_pixels_entry_body, (VALUE)&call, ip_call_cleanup,
                      (VALUE)&call.ctx);
 }
@@ -2326,6 +2511,7 @@ static VALUE ip_optimize_jpeg_entry_body(VALUE ptr) {
     ctx->requested_execution = ip_parse_execution(call->execution);
     ctx->cancellable_requested = ip_bool_value(call->cancellable);
     ctx->has_scheduler = ip_bool_value(call->has_scheduler);
+    ctx->strict = ip_bool_value(call->strict);
     ctx->ssim_guard_enabled = 0;
     apply_configuration(call->self, ctx);
 
@@ -2354,10 +2540,11 @@ static VALUE ip_optimize_jpeg_entry_body(VALUE ptr) {
 
 static VALUE ip_optimize_jpeg_entry(VALUE self, VALUE input, VALUE input_kind, VALUE output,
                                     VALUE output_kind, VALUE progressive, VALUE strip_metadata,
-                                    VALUE execution, VALUE cancellable, VALUE has_scheduler) {
-    ip_optimize_jpeg_call_t call = {
-        self,           input,     input_kind,  output,        output_kind, progressive,
-        strip_metadata, execution, cancellable, has_scheduler, NULL};
+                                    VALUE execution, VALUE cancellable, VALUE has_scheduler,
+                                    VALUE strict) {
+    ip_optimize_jpeg_call_t call = {self,        input,         input_kind,     output,
+                                    output_kind, progressive,   strip_metadata, execution,
+                                    cancellable, has_scheduler, strict,         NULL};
     return rb_ensure(ip_optimize_jpeg_entry_body, (VALUE)&call, ip_call_cleanup, (VALUE)&call.ctx);
 }
 
@@ -2403,14 +2590,17 @@ IMAGE_PACK_INIT_EXPORT void Init_image_pack(void) {
     for (size_t i = 0; i < IP_ARRAY_LEN(exceptions); i++)
         *exceptions[i].slot = rb_const_get(rb_mImagePack, rb_intern(exceptions[i].name));
 
-    rb_define_const(rb_mImagePack, "NATIVE_MOZJPEG_VERSION", rb_str_new_cstr(VERSION));
+    rb_define_const(rb_mImagePack, "NATIVE_MOZJPEG_VERSION",
+                    rb_str_new_cstr(IMAGE_PACK_MOZJPEG_VERSION));
 #if defined(IMAGE_PACK_HAS_SIMD)
     rb_define_const(rb_mImagePack, "NATIVE_SIMD", Qtrue);
 #else
     rb_define_const(rb_mImagePack, "NATIVE_SIMD", Qfalse);
 #endif
+    ip_offload_runtime_enabled = (getenv("IMAGE_PACK_DISABLE_OFFLOAD") == NULL) ? 1 : 0;
 #if IMAGE_PACK_HAS_OFFLOAD_SAFE
-    rb_define_const(rb_mImagePack, "NATIVE_OFFLOAD_SAFE", Qtrue);
+    rb_define_const(rb_mImagePack, "NATIVE_OFFLOAD_SAFE",
+                    ip_offload_runtime_enabled ? Qtrue : Qfalse);
 #else
     rb_define_const(rb_mImagePack, "NATIVE_OFFLOAD_SAFE", Qfalse);
 #endif
@@ -2419,9 +2609,9 @@ IMAGE_PACK_INIT_EXPORT void Init_image_pack(void) {
         const char *name;
         VALUE (*fn)(ANYARGS);
         int arity;
-    } methods[] = {{"__compress_jpeg", (VALUE (*)(ANYARGS))ip_compress_jpeg_entry, 13},
-                   {"__compress_pixels", (VALUE (*)(ANYARGS))ip_compress_pixels_entry, 15},
-                   {"__optimize_jpeg", (VALUE (*)(ANYARGS))ip_optimize_jpeg_entry, 9},
+    } methods[] = {{"__compress_jpeg", (VALUE (*)(ANYARGS))ip_compress_jpeg_entry, -1},
+                   {"__compress_pixels", (VALUE (*)(ANYARGS))ip_compress_pixels_entry, -1},
+                   {"__optimize_jpeg", (VALUE (*)(ANYARGS))ip_optimize_jpeg_entry, 10},
                    {"__inspect_image", (VALUE (*)(ANYARGS))ip_inspect_image_entry, 2}};
     for (size_t i = 0; i < IP_ARRAY_LEN(methods); i++) {
         rb_define_singleton_method(rb_mImagePack, methods[i].name, methods[i].fn, methods[i].arity);

data/lib/image_pack/configuration.rb

@@ -42,7 +42,7 @@ module ImagePack
 
       if value == :offload && ImagePack.respond_to?(:offload_safe?) && !ImagePack.offload_safe?
         raise UnsupportedError,
-              "execution: :offload requires Ruby >= 3.4.0; use execution: :nogvl or :auto"
+              "execution: :offload is unavailable in this runtime; it requires Ruby >= 3.4.0 and IMAGE_PACK_DISABLE_OFFLOAD must not be set"
       end
 
       @execution = value

data/lib/image_pack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ImagePack
-  VERSION = "0.2.3"
+  VERSION = "0.2.5"
 end

data/lib/image_pack.rb

@@ -90,10 +90,12 @@ module ImagePack
                       progressive: true,
                       strip_metadata: false,
                       execution: nil,
-                      cancellable: false)
+                      cancellable: false,
+                      strict: false)
       validate_boolean!(:progressive, progressive)
       validate_boolean!(:strip_metadata, strip_metadata)
       validate_boolean!(:cancellable, cancellable)
+      validate_boolean!(:strict, strict)
       execution ||= configuration.execution
       validate_execution!(execution)
       validate_execution_supported!(execution)
@@ -109,7 +111,8 @@ module ImagePack
                       strip_metadata ? 1 : 0,
                       execution,
                       cancellable ? 1 : 0,
-                      has_scheduler ? 1 : 0)
+                      has_scheduler ? 1 : 0,
+                      strict ? 1 : 0)
     end
 
     def compress(input,
@@ -118,16 +121,23 @@ module ImagePack
                  quality: nil,
                  min_ssim: nil,
                  mozjpeg_trellis: true,
-                 progressive: false,
+                 mozjpeg_scan_opt: true,
+                 progressive: nil,
                  strip_metadata: true,
                  execution: nil,
-                 cancellable: false)
+                 cancellable: false,
+                 report: false,
+                 strict: false)
       validate_algo!(algo)
       validate_min_ssim!(min_ssim)
       validate_boolean!(:mozjpeg_trellis, mozjpeg_trellis)
+      validate_boolean!(:mozjpeg_scan_opt, mozjpeg_scan_opt)
+      progressive = default_progressive_for(algo, progressive)
       validate_boolean!(:progressive, progressive)
       validate_boolean!(:strip_metadata, strip_metadata)
       validate_boolean!(:cancellable, cancellable)
+      validate_boolean!(:report, report)
+      validate_boolean!(:strict, strict)
       quality_was_given = !quality.nil?
       effective_quality = quality_was_given ? quality : DEFAULT_QUALITY
       effective_quality = 1 if min_ssim && !quality_was_given
@@ -150,7 +160,10 @@ module ImagePack
                       strip_metadata ? 1 : 0,
                       execution,
                       cancellable ? 1 : 0,
-                      has_scheduler ? 1 : 0)
+                      has_scheduler ? 1 : 0,
+                      report ? 1 : 0,
+                      strict ? 1 : 0,
+                      mozjpeg_scan_opt ? 1 : 0)
     end
 
     def compress_pixels(buffer,
@@ -162,19 +175,26 @@ module ImagePack
                         quality: nil,
                         min_ssim: nil,
                         mozjpeg_trellis: true,
-                        progressive: false,
+                        mozjpeg_scan_opt: true,
+                        progressive: nil,
                         drop_alpha: nil,
                         exact_size: false,
                         execution: nil,
-                        cancellable: false)
+                        cancellable: false,
+                        report: false,
+                        strict: false)
       validate_pixel_buffer!(buffer)
       validate_algo!(algo)
       validate_min_ssim!(min_ssim)
       validate_boolean!(:mozjpeg_trellis, mozjpeg_trellis)
+      validate_boolean!(:mozjpeg_scan_opt, mozjpeg_scan_opt)
+      progressive = default_progressive_for(algo, progressive)
       validate_boolean!(:progressive, progressive)
       validate_drop_alpha!(drop_alpha)
       validate_boolean!(:exact_size, exact_size)
       validate_boolean!(:cancellable, cancellable)
+      validate_boolean!(:report, report)
+      validate_boolean!(:strict, strict)
       quality_was_given = !quality.nil?
       effective_quality = quality_was_given ? quality : DEFAULT_QUALITY
       effective_quality = 1 if min_ssim && !quality_was_given
@@ -214,7 +234,10 @@ module ImagePack
                         exact_size ? 1 : 0,
                         execution,
                         cancellable ? 1 : 0,
-                        has_scheduler ? 1 : 0)
+                        has_scheduler ? 1 : 0,
+                        report ? 1 : 0,
+                        strict ? 1 : 0,
+                        mozjpeg_scan_opt ? 1 : 0)
     end
 
     def inspect_image(input)
@@ -251,7 +274,7 @@ module ImagePack
       return :return_string if output.nil?
       return :path if output.is_a?(String) || output.is_a?(Pathname)
 
-      raise InvalidArgumentError, "output must be nil, String path, or Pathname in v0.2.2"
+      raise InvalidArgumentError, "output must be nil, String path, or Pathname"
     end
 
     def validate_algo!(algo)
@@ -279,6 +302,13 @@ module ImagePack
       raise InvalidArgumentError, "#{name} must be true or false, got: #{value.inspect}"
     end
 
+
+    def default_progressive_for(algo, value)
+      return value unless value.nil?
+
+      ALGO_TO_NATIVE.fetch(algo) == :mozjpeg
+    end
+
     def validate_drop_alpha!(value)
       return if value.nil? || value == true || value == false
 
@@ -296,7 +326,7 @@ module ImagePack
       return if offload_safe?
 
       raise UnsupportedError,
-            "execution: :offload requires Ruby >= 3.4.0; use execution: :nogvl or :auto"
+            "execution: :offload is unavailable in this runtime; it requires Ruby >= 3.4.0 and IMAGE_PACK_DISABLE_OFFLOAD must not be set"
     end
 
     def validate_dimensions!(width, height, channels)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: image_pack
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Roman Haydarov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-17 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -80,9 +80,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.21'
-description: Single API, vendored pure-C MozJPEG/libjpeg codec, no tempfiles, Ruby
-  3.1+ native JPEG execution; Ruby 3.4+ enables Fiber::Scheduler-aware offload. Ships
-  vendored C sources — no system libjpeg, git, or CMake required.
+description: Single API, vendored pure-C MozJPEG/libjpeg codec, in-memory compression
+  and atomic file output, Ruby 3.1+ native JPEG execution; Ruby 3.4+ enables Fiber::Scheduler-aware
+  offload. Ships vendored C sources — no system libjpeg, git, or CMake required.
 email:
 - romnhajdarov@gmail.com
 executables: []