image_pack 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 301f10cb975250ef59e3bf1beae23208aeb3e40d6598721323b93e4ea8d2eee8
-  data.tar.gz: cc8b9139d2a16ebe94f2c32a047202ea9e9fdf04a608c1bc4608eb5d9e53d589
+  metadata.gz: 124f64ccca4910cee483d3c63a189f6de7d7ea72e8f4a8b88d538fe503cf0673
+  data.tar.gz: d51e698fdad475590f685ddd6097f9bf8486dcb154ce37716e60fac256949c6c
 SHA512:
-  metadata.gz: 2f9bbde96c6269da00a9514aa6eb7660024435ddcb05ae10e57e02338ce69b8a3465b6f7380c551986e0b0e067db041c34fc640074b86e3da189442486e2c111
-  data.tar.gz: 906df1d615b6ae0fb0fbb05636fcb8916ff671886b7319aad70801099974bc742da54444fcb858293c4777ffe89a87390c8d4de78d83c1a613314132dbf1661a
+  metadata.gz: 6ed979776d78d8e1d64e01ec46499d2453d13483495688cc79b71e0fc84b542d68e2a076015d480aaac812c90ef1dea49952f40b156d11d2b4dd95ace73a7688
+  data.tar.gz: 233229ccf2b0daa138dc6bd664ce14c8ddf770aaa232d42efc33d43419a3c7f0f5b673daf985e6745e49fcf8ceeac9503d84910319cb8a7d269178e08cd657eb

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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,180 +1,169 @@
 # image_pack
 
-`image_pack` is a Ruby-native JPEG compressor prototype for Ruby `>= 3.4.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
+- `:fast` / `:jpeg_turbo` — faster 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, ...)`.
+```ruby
+ImagePack.compress_bytes(jpeg, min_ssim: 0.985)
+ImagePack.compress_bytes(jpeg, progressive: true)
+ImagePack.compress_bytes(jpeg, strict: true)
+ImagePack.compress_bytes(jpeg, report: true)
+```
 
-`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.
+`min_ssim:` searches for the lowest acceptable quality using a fast native luma SSIM guard.
 
-`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.
+`strict: true` raises `ImagePack::InvalidImageError` on damaged/truncated JPEG warnings.
 
-## Lossless JPEG optimize
+`report: true` returns a Hash:
 
-`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.
+```ruby
+{
+  output: "\xFF\xD8...",
+  quality: 84,
+  ssim: 0.9861,
+  algo: :mozjpeg,
+  bytesize: 50122,
+  input_bytesize: 81344,
+  warning_count: 0,
+  warning: nil
+}
+```
 
-Defaults are intentionally conservative:
+With `output: "file.jpg"`, `output` is `true`.
 
-- `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.
+## Lossless optimize
 
-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.
+```ruby
+ImagePack.optimize_bytes(jpeg)
+ImagePack.optimize_file("photo.jpg", output: "photo.optimized.jpg")
+```
 
-## SSIM guard
+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.
 
-`compress` and `compress_pixels` accept `min_ssim:`. This enables a native guarded path:
+Defaults: `progressive: true`, `strip_metadata: false`.
 
-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`.
+If `strip_metadata: true` would remove EXIF Orientation, `optimize_jpeg` raises `UnsupportedError` instead of silently changing visual orientation.
 
-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.
+## Raw pixels
 
-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.
+```ruby
+ImagePack.compress_pixels(rgb,
+  width: 1920,
+  height: 1080,
+  channels: 3,
+  output: "frame.jpg"
+)
+```
 
-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.
+`channels` must be `1`, `3`, or `4`. JPEG cannot store alpha, so RGBA input needs explicit opt-in:
 
-## Execution modes
+```ruby
+ImagePack.compress_pixels(rgba, width: 100, height: 100, channels: 4, drop_alpha: true)
+```
+
+## Inspect
 
 ```ruby
-ImagePack.compress(jpeg, execution: :direct)
-ImagePack.compress(jpeg, execution: :nogvl)
-ImagePack.compress(jpeg, execution: :offload)
-ImagePack.compress(jpeg, execution: :auto)
+ImagePack.inspect_image(jpeg)
+# => { format: :jpeg, width: 1920, height: 1080, channels: 3, bit_depth: 8, decoded_bytes: 6220800 }
 ```
 
-- `: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+.
-- `:auto` — header-first policy chooses direct/nogvl/offload.
+## Execution
 
-## Cancellation
+Default mode is `:auto`.
 
-`cancellable: true` is supported for `execution: :nogvl`, `:offload`, or `:auto`.
-Cancellation is cooperative at decode, encode, and SSIM-search checkpoints, not instant.
+```ruby
+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
+```
 
-## Metadata / EXIF orientation
+Use `ImagePack.offload_safe?` or `ImagePack.build_info` to inspect runtime support.
 
-`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.
+Set `IMAGE_PACK_DISABLE_OFFLOAD=1` before loading the gem to disable offload.
 
-## Build info
+Long no-GVL/offload calls can be interrupted by raising into the worker thread:
 
 ```ruby
-ImagePack.build_info
-# => { version: "0.2.2", mozjpeg: "4.1.5", simd: true }
+worker = Thread.new { ImagePack.compress_bytes(jpeg, execution: :nogvl, cancellable: true) }
+worker.raise(ImagePack::CancelledError, "cancelled")
+worker.join
 ```
 
-## Vendoring
+## Configuration
+
+```ruby
+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
+```
 
-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
 ```
 
 `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.
-
-## 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.4`.
+- 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

@@ -4,127 +4,19 @@ require "mkmf"
 require "fileutils"
 require "rbconfig"
 
-if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.4.0")
-  abort "image_pack requires Ruby >= 3.4.0; got #{RUBY_VERSION}"
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.1.0")
+  abort "image_pack requires Ruby >= 3.1.0; got #{RUBY_VERSION}"
 end
 
-MOZJPEG_CORE_SOURCES = %w[
-  jcapimin.c
-  jcapistd.c
-  jccoefct.c
-  jccolor.c
-  jcdctmgr.c
-  jchuff.c
-  jcext.c
-  jcicc.c
-  jcinit.c
-  jcmainct.c
-  jcmarker.c
-  jcmaster.c
-  jcomapi.c
-  jcparam.c
-  jcphuff.c
-  jcprepct.c
-  jcsample.c
-  jctrans.c
-  jdapimin.c
-  jdapistd.c
-  jdatadst.c
-  jdatasrc.c
-  jdcoefct.c
-  jdcolor.c
-  jddctmgr.c
-  jdhuff.c
-  jdicc.c
-  jdinput.c
-  jdmainct.c
-  jdmarker.c
-  jdmaster.c
-  jdmerge.c
-  jdphuff.c
-  jdpostct.c
-  jdsample.c
-  jdtrans.c
-  jerror.c
-  jfdctflt.c
-  jfdctfst.c
-  jfdctint.c
-  jidctflt.c
-  jidctfst.c
-  jidctint.c
-  jidctred.c
-  jquant1.c
-  jquant2.c
-  jutils.c
-  jmemmgr.c
-  jmemnobs.c
-].freeze
-
-NEON_AARCH64_SOURCES = [
-  "simd/arm/aarch64/jsimd.c",
-  "simd/arm/aarch64/jchuff-neon.c",
-  "simd/arm/jccolor-neon.c",
-  "simd/arm/jcgray-neon.c",
-  "simd/arm/jcphuff-neon.c",
-  "simd/arm/jcsample-neon.c",
-  "simd/arm/jdcolor-neon.c",
-  "simd/arm/jdmerge-neon.c",
-  "simd/arm/jdsample-neon.c",
-  "simd/arm/jfdctfst-neon.c",
-  "simd/arm/jfdctint-neon.c",
-  "simd/arm/jidctfst-neon.c",
-  "simd/arm/jidctint-neon.c",
-  "simd/arm/jidctred-neon.c",
-  "simd/arm/jquanti-neon.c",
-].freeze
-
-X86_64_C_SOURCES = [
-  "simd/x86_64/jsimd.c",
-].freeze
-
-X86_64_ASM_SOURCES = %w[
-  simd/x86_64/jsimdcpu.asm
-  simd/x86_64/jfdctflt-sse.asm
-  simd/x86_64/jccolor-sse2.asm
-  simd/x86_64/jcgray-sse2.asm
-  simd/x86_64/jchuff-sse2.asm
-  simd/x86_64/jcphuff-sse2.asm
-  simd/x86_64/jcsample-sse2.asm
-  simd/x86_64/jdcolor-sse2.asm
-  simd/x86_64/jdmerge-sse2.asm
-  simd/x86_64/jdsample-sse2.asm
-  simd/x86_64/jfdctfst-sse2.asm
-  simd/x86_64/jfdctint-sse2.asm
-  simd/x86_64/jidctflt-sse2.asm
-  simd/x86_64/jidctfst-sse2.asm
-  simd/x86_64/jidctint-sse2.asm
-  simd/x86_64/jidctred-sse2.asm
-  simd/x86_64/jquantf-sse2.asm
-  simd/x86_64/jquanti-sse2.asm
-  simd/x86_64/jccolor-avx2.asm
-  simd/x86_64/jcgray-avx2.asm
-  simd/x86_64/jcsample-avx2.asm
-  simd/x86_64/jdcolor-avx2.asm
-  simd/x86_64/jdmerge-avx2.asm
-  simd/x86_64/jdsample-avx2.asm
-  simd/x86_64/jfdctint-avx2.asm
-  simd/x86_64/jidctint-avx2.asm
-  simd/x86_64/jquanti-avx2.asm
-].freeze
-
-X86_64_ASM_TEMPLATE_SOURCES = %w[
-  simd/x86_64/jccolext-sse2.asm
-  simd/x86_64/jcgryext-sse2.asm
-  simd/x86_64/jdcolext-sse2.asm
-  simd/x86_64/jdmrgext-sse2.asm
-  simd/x86_64/jccolext-avx2.asm
-  simd/x86_64/jcgryext-avx2.asm
-  simd/x86_64/jdcolext-avx2.asm
-  simd/x86_64/jdmrgext-avx2.asm
-].freeze
-
-MOZJPEG_VERSION = "4.1.5"
-MOZJPEG_VERSION_NUMBER = "4001005"
+require_relative "mozjpeg_sources"
+
+MOZJPEG_CORE_SOURCES = ImagePackMozjpegSources::TOPLEVEL_C_SOURCES
+MOZJPEG_INCLUDE_TEMPLATES = ImagePackMozjpegSources::TOPLEVEL_INCLUDE_TEMPLATES
+NEON_AARCH64_SOURCES = ImagePackMozjpegSources::NEON_AARCH64_C_SOURCES
+X86_64_C_SOURCES = ImagePackMozjpegSources::X86_64_C_SOURCES
+X86_64_ASM_SOURCES = ImagePackMozjpegSources::X86_64_ASM_SOURCES
+MOZJPEG_VERSION = ImagePackMozjpegSources::VERSION
+MOZJPEG_VERSION_NUMBER = ImagePackMozjpegSources::VERSION_NUMBER
 
 def find_vendor_dir
   candidates = [
@@ -285,8 +177,14 @@ def select_simd_backend(mozjpeg_dir, arch)
     else
       missing = NEON_AARCH64_SOURCES.reject { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
       missing << "simd/arm/neon-compat.h.in" unless template_present
-      warn "image_pack: ARM64 detected but NEON sources missing under #{mozjpeg_dir}:"
-      missing.each { |m| warn "  - #{m}" }
+      message = "image_pack: ARM64 detected but NEON sources are incomplete under #{mozjpeg_dir}:
+"                 "#{missing.map { |m| "  - #{m}" }.join("
+")}"
+      if ENV["IMAGE_PACK_REQUIRE_SIMD"] == "1"
+        abort "#{message}
+image_pack: refusing scalar fallback because IMAGE_PACK_REQUIRE_SIMD=1."
+      end
+      warn message
       warn "image_pack: re-run `bundle exec rake vendor` after updating script/vendor_libs.rb."
       warn "image_pack: falling back to scalar."
       { kind: :none }
@@ -301,13 +199,25 @@ def select_simd_backend(mozjpeg_dir, arch)
       warn "#{message} Falling back to scalar; install nasm for ~3-4x speedup. Set IMAGE_PACK_REQUIRE_SIMD=1 to fail instead."
       { kind: :none }
     elsif !X86_64_C_SOURCES.all? { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
-      warn "image_pack: x86_64 SIMD sources missing under #{mozjpeg_dir}/simd/x86_64/. Falling back to scalar."
+      missing = X86_64_C_SOURCES.reject { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
+      message = "image_pack: x86_64 SIMD C sources missing under #{mozjpeg_dir}: #{missing.join(', ')}"
+      ENV["IMAGE_PACK_REQUIRE_SIMD"] == "1" ? abort(message) : warn("#{message}. Falling back to scalar.")
       { kind: :none }
     else
+      missing_asm = X86_64_ASM_SOURCES.reject { |rel| File.exist?(File.join(mozjpeg_dir, rel)) }
+      unless missing_asm.empty?
+        message = "image_pack: x86_64 SIMD ASM sources missing under #{mozjpeg_dir}: #{missing_asm.join(', ')}"
+        if ENV["IMAGE_PACK_REQUIRE_SIMD"] == "1"
+          abort message
+        end
+        warn "#{message}. Falling back to scalar."
+        return { kind: :none }
+      end
+
       {
         kind:           :x86_64_simd,
         c_sources:      X86_64_C_SOURCES,
-        asm_sources:    X86_64_ASM_SOURCES.select { |rel| File.exist?(File.join(mozjpeg_dir, rel)) },
+        asm_sources:    X86_64_ASM_SOURCES,
         extra_includes: [
           File.join(mozjpeg_dir, "simd"),
           File.join(mozjpeg_dir, "simd", "nasm"),
@@ -367,7 +277,8 @@ def configure_vendored_mozjpeg(vendor_dir)
 
   abort "vendored MozJPEG sources not found in #{mozjpeg_dir}" unless Dir.exist?(mozjpeg_dir)
 
-  missing_sources = MOZJPEG_CORE_SOURCES.reject { |source| File.exist?(File.join(mozjpeg_dir, source)) }
+  required_sources = MOZJPEG_CORE_SOURCES + MOZJPEG_INCLUDE_TEMPLATES
+  missing_sources = required_sources.reject { |source| File.exist?(File.join(mozjpeg_dir, source)) }
   abort "vendored MozJPEG sources are incomplete: #{missing_sources.join(', ')}" unless missing_sources.empty?
 
   arch = detect_simd_arch
@@ -505,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"