safe_image 0.1.0 → 0.2.0

data/README.md

@@ -3,77 +3,36 @@
 Safe Image is a small Ruby image-processing boundary for untrusted uploads.
 
 It gives an application one narrow API for probing, thumbnailing, resizing,
-cropping, converting, optimising, SVG sanitising, animation checks, favicon
-conversion, and letter-avatar generation. The default fast path uses a tiny
-native extension that calls `libvips` directly. Compatibility paths use
-ImageMagick, but with shell-free command execution and a restrictive bundled
-policy.
+cropping, converting, optimising, SVG sanitising, animation checks, dominant
+colour extraction, favicon conversion, and letter-avatar generation.
+Everything that varies by host is decided once, at boot, with a single
+mandatory call:
 
-Safe Image started as a Discourse extraction: the public surface intentionally
-covers the image operations Discourse performs today. The useful part is more
-general: hostile image bytes are a lousy thing to spread across model callbacks,
-upload helpers, optimizer wrappers, and hand-built command strings.
-
-## Security model
+```ruby
+SafeImage.configure!(backend: :vips, landlock: true)
+```
 
-Safe Image is not magic pixie dust. It is a deliberately small choke point.
+The `:vips` backend uses a tiny Fiddle binding that drives `libvips` directly
+— pure Ruby, nothing compiles at install time. The `:imagemagick` backend
+runs ImageMagick with shell-free command execution and a restrictive bundled
+policy. There are no per-call backend choices and no silent fallback from one
+backend to the other: you pick the decoder for untrusted bytes in one place
+and every operation uses it.
 
-What it does:
-
-- uses explicit argv arrays for external commands, never shell strings
-- starts external commands with an allowlisted environment, private temp/home/cache
-  directories, bounded stdout/stderr, and process-group timeout cleanup
-- uses explicit libvips loaders selected from allowlisted extensions
-- enables libvips' untrusted-operation block in-process
-- blocks libvips ImageMagick loader classes in the native extension
-- disables libvips cache by default in-process
-- strips metadata on generated images where applicable
-- rejects symlinked local input/output paths and symlinked path components for
-  untrusted file-processing paths
-- caps decoded pixels before expensive work: the libvips path enforces a
-  default `SafeImage::DEFAULT_MAX_PIXELS` (128MP) ceiling even when no
-  `max_pixels` is given, and callers can raise or lower it per call
-- ships a restrictive ImageMagick `policy.xml`
-- denies Ghostscript-backed formats and dangerous ImageMagick features:
-  - `PS`, `PS2`, `PS3`, `EPS`, `EPSF`, `PDF`, `XPS`, `PCL`
-  - `MSL`, `MVG`
-  - `HTTP`, `HTTPS`, `URL`
-  - delegates, filters, and `@file` indirection
-- supports optional Landlock subprocess sandboxing on Linux
-
-The ImageMagick backend is explicit. Safe Image will not silently fall from the
-libvips path into generic ImageMagick decoding.
+The premise is that hostile image bytes are a lousy thing to spread across
+model callbacks, upload helpers, optimizer wrappers, and hand-built command
+strings. Safe Image puts the risky operations behind one small, hardened
+choke point instead.
 
 ## Install
 
-System dependency:
-
-- `libvips` headers and library, discoverable through `pkg-config vips`
-
-Optional command dependencies:
-
-- `magick` / `convert` and `identify` for ImageMagick compatibility operations
-- `jpegoptim` for JPEG optimisation
-- `oxipng` for PNG lossless optimisation
-- `pngquant` for optional lossy PNG optimisation
-- `cjpegli` for optional Jpegli JPEG encoding of generated JPEGs
-
-Ruby runtime dependency:
-
-- `rexml` for SVG sanitising
-
-Optional Ruby dependency:
-
-- `landlock` for Linux subprocess sandboxing
-
-`landlock` is intentionally **not** a gem dependency. Install it in the host
-application if you want sandboxing.
-
-`cjpegli` is also intentionally optional. On Arch it is provided by `libjxl`;
-on macOS it is commonly installed via `brew install jpeg-xl`; Debian/Ubuntu
-package names vary by release (`libjpegli-tools` where available). Safe Image
-detects it at runtime and falls back unless the caller explicitly requests
-`encoder: :cjpegli`.
+Nothing compiles at install time: libvips is bound at runtime through Fiddle
+(`libvips.so.42` is dlopened when `configure!(backend: :vips)` runs;
+`SAFE_IMAGE_LIBVIPS` overrides the library name authoritatively). libvips'
+GLib warnings about rejected input (e.g. "Not a PNG file") are silenced —
+failures surface as exceptions instead; set `SAFE_IMAGE_VIPS_WARNINGS=1` to
+restore them for debugging. Install the runtime
+[dependencies](#dependencies) below.
 
 ```bash
 gem build safe_image.gemspec
@@ -83,6 +42,8 @@ gem install ./safe_image-0.1.0.gem
 ```ruby
 require "safe_image"
 
+SafeImage.configure!(backend: :vips, landlock: false)
+
 result = SafeImage.thumbnail(
   input: "upload.jpg",
   output: "thumb.jpg",
@@ -102,7 +63,144 @@ SafeImage.convert(
 )
 ```
 
-## Return values
+## Configuration
+
+`SafeImage.configure!` must be called before any operation — typically from a
+boot-time initializer. Any operation before it (including the pure-Ruby SVG
+and remote helpers) raises `SafeImage::NotConfiguredError`.
+
+```ruby
+SafeImage.configure!(
+  backend: :vips,    # required: :vips or :imagemagick — decodes all untrusted bytes
+  landlock: true,    # required: route every operation through the Landlock sandbox
+  max_pixels: SafeImage::DEFAULT_MAX_PIXELS # optional: default decompression-bomb ceiling (128MP)
+)
+```
+
+Validation is eager, so a misconfigured host fails at boot rather than on the
+first request:
+
+- `backend: :vips` dlopens libvips and raises if it is unavailable
+- `backend: :imagemagick` raises if no `magick`/`convert` executable is found
+- `landlock: true` raises if the Landlock sandbox is unavailable
+  (`SafeImage.sandbox_available?` works before `configure!`, so a host can
+  probe first)
+- unknown values raise `ArgumentError`
+
+Calling `configure!` again replaces the configuration atomically (last call
+wins), so reloading initializers in development is safe. `SafeImage.config`
+returns the current frozen configuration and `SafeImage.configured?` reports
+whether one is set.
+
+Per-call `max_pixels:` still overrides the configured ceiling for an
+individual operation; everything else about backend selection and sandboxing
+is decided here and only here.
+
+Choosing a backend:
+
+- `:vips` — the recommended fast path: explicit native loaders, in-process
+  hardening, no subprocess per operation
+- `:imagemagick` — matches classic ImageMagick `convert` pipelines; also the
+  option for hosts without libvips. Formats are decoded by ImageMagick under
+  the bundled restrictive policy.
+
+A format the configured backend cannot decode fails closed — e.g. ICO
+transform inputs need `:imagemagick` (ICO *metadata* is parsed in pure Ruby on
+either backend), and HEIC needs a libvips build with libheif on `:vips`.
+
+## Dependencies
+
+### Quick install
+
+Debian / Ubuntu:
+
+```bash
+sudo apt-get install --no-install-recommends \
+  libvips42 imagemagick jpegoptim pngquant oxipng libjpeg-turbo-progs
+```
+
+`oxipng` is packaged from Debian 13 / Ubuntu 24.04; on older releases install
+it with `cargo install oxipng`. For `cjpegli`, Debian/Ubuntu package names
+vary by release (`libjpegli-tools` where available); it is optional and
+detected at runtime.
+
+Arch:
+
+```bash
+sudo pacman -S --needed libvips \
+  imagemagick jpegoptim pngquant oxipng libjpeg-turbo libjxl
+```
+
+(`libjpeg-turbo` provides `jpegtran`, `libjxl` provides `cjpegli`.)
+
+### What each dependency is for
+
+| Dependency | Kind | Needed for | Without it |
+| --- | --- | --- | --- |
+| `libvips` runtime library (`libvips.so.42`; Debian: `libvips42` ≥ 8.13) | required for `backend: :vips` | the fast path for every operation, bound via Fiddle | `configure!(backend: :vips)` raises at boot; configure `backend: :imagemagick` instead |
+| ImageMagick (`magick`/`convert`, `identify`) | required for `backend: :imagemagick` | every operation on the `:imagemagick` backend | `configure!(backend: :imagemagick)` raises at boot |
+| `jpegoptim` | required for JPEG `optimize` | lossless JPEG optimisation and metadata stripping | JPEG `optimize` raises in strict mode |
+| `oxipng` | required for PNG `optimize` | lossless PNG optimisation | PNG `optimize` raises in strict mode |
+| `pngquant` | optional | lossy PNG quantisation (`optimize_mode: :lossy`, files < 500KB) | lossy mode silently skips the quantisation pass |
+| `jpegtran` (libjpeg-turbo) | optional | lossless tier of `fix_orientation` for MCU-aligned JPEGs | falls back to the libvips re-encode tier |
+| `cjpegli` (libjxl) | optional | higher-quality encoding of generated JPEGs on the `:vips` backend — used automatically when installed | generated JPEGs use the backend's own encoder |
+| `landlock` gem (Linux kernel ≥ 5.13) | required for `landlock: true` | the atomic sandbox around every operation | `configure!(landlock: true)` raises at boot; `sandbox_available?` is false |
+| `rexml` gem | automatic | SVG sanitising and SVG metadata | installed as a gem dependency |
+
+The `landlock` gem is intentionally **not** a gem dependency; add it to the
+host application's Gemfile if you want sandboxing.
+
+### libvips build capabilities
+
+Some features depend on how the host's libvips was built (all present in
+stock Debian, Ubuntu and Arch packages):
+
+- **libheif** — HEIC/AVIF decode (`probe`, `convert`, thumbnails)
+- **Pango text** (`VipsText`) — `letter_avatar`; without it the operation
+  raises `UnsupportedFormatError` (configure `backend: :imagemagick` if you
+  need letter avatars on such a build)
+- **cgif** (`gifsave`) — GIF *output* from the vips backend; GIF *decode*
+  (libnsgif) is always built in
+- **libjxl** (`jxlload`/`jxlsave`) — JPEG XL decode and encode
+
+Check a host with:
+
+```bash
+vips -l | grep -cE "VipsForeignSaveCgif|VipsText|VipsForeignLoadHeif|VipsForeignLoadJxl" # expect 4+
+```
+
+### Fonts
+
+Letter avatars need **no font packages** with the default `DejaVu-Sans`
+token: the gem bundles DejaVu Sans and pins it via fontconfig's app-font API.
+The other allowlisted tokens (`NimbusSans-Regular`, `Liberation-Sans`,
+`Arial`, `Helvetica`, `Adwaita-Sans`) resolve through system fontconfig —
+install e.g. `fonts-liberation` (Debian/Ubuntu) or `ttf-liberation` (Arch) if
+you select them. Glyphs outside DejaVu's coverage (CJK, Hangul, ...) fall
+back per-glyph to whatever system fonts exist.
+
+### Checking a host
+
+These probes work before `configure!`, so an application can inspect the host
+and then make its configuration decision:
+
+```ruby
+require "safe_image"
+
+%w[magick identify jpegoptim oxipng pngquant jpegtran cjpegli].each do |tool|
+  puts format("%-10s %s", tool, SafeImage::Runner.available?(tool) ? "ok" : "missing")
+end
+puts format("%-10s %s", "libvips", SafeImage::VipsGlue.available? ? "ok" : "unavailable")
+puts format("%-10s %s", "sandbox", SafeImage.sandbox_available? ? "ok" : "unavailable")
+```
+
+## API
+
+All operations are module functions on `SafeImage` and run on the configured
+backend. Operations that decode an image accept `max_pixels:` to override the
+configured decompression-bomb ceiling for that one call.
+
+### Return values
 
 Image-producing operations return `SafeImage::Result`:
 
@@ -116,7 +214,7 @@ SafeImage::Result[
   height:,
   filesize:,
   backend:,        # e.g. "libvips-direct", "imagemagick", "cjpegli",
-                   #      "libvips-direct+cjpegli", or "sandboxed-..."
+                   #      "libvips-direct+cjpegli"
   duration_ms:,
   optimizer:       # optimizer tool list for thumbnail path, otherwise nil
 ]
@@ -134,19 +232,29 @@ Optimizer operations return a hash:
 }
 ```
 
-## Core API
+### Probing and metadata
+
+Metadata operations for local files. `type`, `size`/`dimensions`,
+`orientation`, and `info` are intended to cover the local-file parts of APIs
+like `FastImage.type`, `FastImage.size`, and `FastImage#orientation` without
+adding a Ruby dependency. None of these fetch remote URLs — see
+[Remote URLs](#remote-urls) for that.
 
-### `SafeImage.probe(path, max_pixels: nil)`
+#### `SafeImage.probe(path, max_pixels: nil)`
 
-Reads image metadata through the direct libvips backend.
+Reads image metadata through the configured backend.
 
-Supported inputs:
+Supported inputs on the `:vips` backend:
 
 - `jpg` / `jpeg`
 - `png`
+- `gif` (first frame, via libvips' bundled libnsgif loader)
 - `webp`
 - `heic` / `heif`
 - `avif`
+- `jxl` (requires a libvips build with libjxl support)
+- `ico` (pure-Ruby directory parse on either backend; reports the largest
+  entry's dimensions)
 
 ```ruby
 info = SafeImage.probe("upload.jpg", max_pixels: 40_000_000)
@@ -155,72 +263,7 @@ puts "#{info.width}x#{info.height} #{info.input_format}"
 
 Raises `SafeImage::LimitError` if `width * height > max_pixels`.
 
-### `SafeImage.thumbnail(...)`
-
-Creates a center-cropped thumbnail.
-
-```ruby
-result = SafeImage.thumbnail(
-  input: "upload.jpg",
-  output: "thumb.jpg",
-  width: 600,
-  height: 400,
-  format: nil,              # inferred from output extension when nil
-  quality: 85,
-  max_pixels: 40_000_000,
-  backend: :vips,           # :vips or :imagemagick
-  optimize: true,
-  optimize_mode: :lossless, # :lossless or :lossy for PNG optimisation
-  execution: :inline,       # :inline, :sandbox, :sandbox_if_available
-  encoder: :auto,           # :auto, :cjpegli, :vips, :imagemagick for JPEG output
-  chroma_subsampling: :auto # :auto, "420", "422", "444"
-)
-```
-
-Supported outputs for the direct libvips backend:
-
-- `jpg` / `jpeg`
-- `png`
-- `webp`
-- `avif`
-
-`execution: :sandbox` is fail-closed: it raises if Landlock is unavailable.
-`execution: :sandbox_if_available` uses the sandbox only when available.
-
-## JPEG encoder selection
-
-Safe Image separates **encoding generated JPEGs** from **optimising existing
-JPEGs**. This avoids hiding a lossy re-encode behind a method named `optimize`.
-
-| Operation | `encoder: :auto` behavior |
-| --- | --- |
-| `thumbnail` / `resize` / `crop` / `downsize` to JPEG with `backend: :vips` | use `cjpegli` when installed; otherwise use normal libvips JPEG output |
-| `convert("input.png", "output.jpg", format: "jpg")` | use `cjpegli` when installed; otherwise use ImageMagick compatibility path |
-| `convert` from HEIC/WebP/AVIF/GIF/JPEG to JPEG | fall back to ImageMagick compatibility path; `cjpegli` is not treated as a universal decoder |
-| `optimize("existing.jpg")` | use `jpegoptim`; never use `cjpegli` by default |
-
-Encoder controls:
-
-| Option | Meaning |
-| --- | --- |
-| `encoder: :auto` | best available default with safe fallback |
-| `encoder: :cjpegli` | require Jpegli and fail closed if unavailable/unsupported |
-| `encoder: :vips` | force normal libvips JPEG output where available |
-| `encoder: :imagemagick` | force ImageMagick compatibility output |
-
-`cjpegli` output is ordinary browser-compatible JPEG. It is optional because it
-is a system binary, not a Ruby dependency. Safe Image detects it at runtime.
-
-`chroma_subsampling: :auto` uses `4:4:4` for PNG-sourced JPEG conversion and
-`4:2:0` otherwise. Pass `"420"`, `"422"`, or `"444"` to force a value.
-
-## Local metadata helpers
-
-These helpers are intended to cover the local-file parts of APIs like
-`FastImage.type`, `FastImage.size`, and `FastImage#orientation` without adding a
-Ruby dependency. They do not fetch remote URLs.
-
-### `SafeImage.type(path, max_pixels: nil)`
+#### `SafeImage.type(path, max_pixels: nil)`
 
 Returns a FastImage-style symbol for a local file:
 
@@ -233,7 +276,7 @@ SafeImage.type("icon.svg")   # => :svg
 JPEG is returned as `:jpeg`, not `:jpg`, to match common Ruby image-probing
 conventions.
 
-### `SafeImage.size(path, max_pixels: nil)` / `SafeImage.dimensions(path, max_pixels: nil)`
+#### `SafeImage.size(path, max_pixels: nil)` / `SafeImage.dimensions(path, max_pixels: nil)`
 
 Returns `[width, height]` for a local file:
 
@@ -248,16 +291,24 @@ limited to local `.svg` files, caps input size/tree depth/element/attribute
 counts, rejects `DOCTYPE` and non-XML processing instructions, requires an `<svg>`
 root, and derives dimensions from numeric `width`/`height` or `viewBox`.
 
-### `SafeImage.orientation(path, max_pixels: nil)`
+#### `SafeImage.orientation(path, max_pixels: nil)`
+
+Returns the EXIF orientation integer (1-8) for a local file. On the `:vips`
+backend it is read from the orientation header field the native loaders
+populate during the header scan — no pixel data is decoded — and garbage tag
+values clamp to `1`. On the `:imagemagick` backend it comes from `identify`.
+SVG and ICO report `1` by definition.
 
-Returns the EXIF orientation integer for a local file, defaulting to `1` when no
-orientation is present or when ImageMagick cannot report it.
+Note one deliberate HEIC difference: libheif applies the container's
+`irot`/`imir` transforms during decode, so the native path reports the
+orientation of the pixels as actually decoded, rather than echoing a raw
+EXIF tag that may already be baked in.
 
 ```ruby
 SafeImage.orientation("upload.jpg") # => 1
 ```
 
-### `SafeImage.info(path, max_pixels: nil, animated: false, orientation: false)`
+#### `SafeImage.info(path, max_pixels: nil, animated: false, orientation: false)`
 
 Returns a `SafeImage::Info` object for a local file:
 
@@ -274,7 +325,45 @@ info.orientation # => 1
 `animated:` and `orientation:` default to `false` because they may require extra
 ImageMagick work. When disabled, those fields are `nil`.
 
-## Remote metadata helpers
+#### `SafeImage.frame_count(path, max_pixels: nil)`
+
+Returns the frame count. On the `:vips` backend it comes from the n-pages
+header field via the native loaders — no pixel data is decoded; on the
+`:imagemagick` backend from `identify`. ICO directories are counted by the
+pure-Ruby parser on either backend.
+
+```ruby
+frames = SafeImage.frame_count("animated.gif")
+```
+
+#### `SafeImage.animated?(path, max_pixels: nil)`
+
+Returns `true` when `frame_count(path) > 1`.
+
+```ruby
+SafeImage.animated?("animated.webp")
+```
+
+#### `SafeImage.dominant_color(path, max_pixels: nil)`
+
+Computes the image's alpha-weighted average colour (first frame for animated
+formats) and returns it as an uppercase `RRGGBB` hex string.
+
+The `:vips` backend computes the exact per-channel mean natively, with ICO
+decoded by the pure-Ruby parser. The `:imagemagick` backend uses a histogram
+command. The two backends agree to within a few least-significant bits per
+channel (ImageMagick averages through its resize filter rather than computing
+the exact mean).
+
+The pixel cap is enforced before the full decode on either backend,
+undecodable input raises `InvalidImageError`, and SVG input raises
+`UnsupportedFormatError`.
+
+```ruby
+SafeImage.dominant_color("upload.png") # => "6F745E"
+```
+
+### Remote URLs
 
 These helpers are intended to cover `FastImage.size(url)` / `FastImage.type(url)`
 style use cases without another Ruby dependency. They use only Ruby stdlib
@@ -316,7 +405,7 @@ or is intentionally probing a trusted internal URL. Passing `allow_private: true
 also permits non-standard ports; for public fetches, pass `allowed_ports:` if you
 really need to allow a different port.
 
-### `SafeImage.remote_size(url, ...)` / `SafeImage.remote_dimensions(url, ...)`
+#### `SafeImage.remote_size(url, ...)` / `SafeImage.remote_dimensions(url, ...)`
 
 ```ruby
 SafeImage.remote_size(
@@ -328,14 +417,14 @@ SafeImage.remote_size(
 # => [1600, 1200]
 ```
 
-### `SafeImage.remote_type(url, ...)`
+#### `SafeImage.remote_type(url, ...)`
 
 ```ruby
 SafeImage.remote_type("https://example.com/image.png", max_bytes: 10.megabytes)
 # => :png
 ```
 
-### `SafeImage.remote_info(url, ...)`
+#### `SafeImage.remote_info(url, ...)`
 
 ```ruby
 info = SafeImage.remote_info(
@@ -348,14 +437,21 @@ info.size     # => [640, 480]
 info.animated # => true
 ```
 
-### `SafeImage.remote_animated?(url, ...)`
+#### `SafeImage.remote_animated?(url, ...)`
 
 ```ruby
 SafeImage.remote_animated?("https://example.com/image.webp", max_bytes: 10.megabytes)
 # => true / false
 ```
 
-### `SafeImage.fetch_remote(url, ...) { |path| ... }`
+#### `SafeImage.remote_dominant_color(url, ...)`
+
+```ruby
+SafeImage.remote_dominant_color("https://example.com/image.png", max_bytes: 10.megabytes)
+# => "6F745E"
+```
+
+#### `SafeImage.fetch_remote(url, ...) { |path| ... }`
 
 Downloads a remote image to a tempfile and yields the local path:
 
@@ -365,121 +461,199 @@ SafeImage.fetch_remote("https://example.com/image.jpg", max_bytes: 10.megabytes)
 end
 ```
 
-When global Landlock is enabled, the network fetch itself is not put inside the
-Landlock worker because the worker denies network access. The downloaded tempfile
-is then passed through the normal Safe Image local image APIs, so decoding still
-uses the same sandboxed image-processing path.
+With `landlock: true` configured, the network fetch itself is not put inside
+the Landlock worker because the worker denies network access. The downloaded
+tempfile is then passed through the normal Safe Image local image APIs, so
+decoding still uses the same sandboxed image-processing path.
+
+### Generating images
+
+Operations that write a new image. All of them run on the configured backend
+and return [`SafeImage::Result`](#return-values).
+
+#### `SafeImage.thumbnail(...)`
+
+Creates a center-cropped thumbnail.
+
+```ruby
+result = SafeImage.thumbnail(
+  input: "upload.jpg",
+  output: "thumb.jpg",
+  width: 600,
+  height: 400,
+  format: nil,              # inferred from output extension when nil
+  quality: 85,
+  max_pixels: 40_000_000,   # overrides the configured ceiling for this call
+  optimize: true,
+  optimize_mode: :lossless, # :lossless or :lossy for PNG optimisation
+  chroma_subsampling: :auto # :auto, "420", "422", "444" for JPEG output
+)
+```
 
-## Compatibility API
+Supported outputs on the `:vips` backend:
 
-These methods are shaped around the image operations Discourse currently
-performs. They are useful outside Discourse too, but the names are deliberately
-boring because they map to common upload-pipeline tasks.
+- `jpg` / `jpeg`
+- `png`
+- `gif` (requires a libvips build with cgif support; raises `UnsupportedFormatError` otherwise)
+- `webp`
+- `avif`
+- `jxl` (requires a libvips build with libjxl support)
 
-### `SafeImage.resize(from, to, width, height, quality: nil, backend: :imagemagick, optimize: true, max_pixels: nil, encoder: :auto, chroma_subsampling: :auto)`
+#### `SafeImage.resize(from, to, width, height, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
 
 Creates a resized thumbnail-style output.
 
 ```ruby
 SafeImage.resize("upload.jpg", "thumb.jpg", 600, 400)
-SafeImage.resize("upload.jpg", "thumb.jpg", 600, 400, backend: :vips, quality: 85)
+SafeImage.resize("upload.jpg", "thumb.jpg", 600, 400, quality: 85)
 ```
 
-Backends:
+`resize`, `crop` and `downsize` run on the configured backend:
 
-- `:imagemagick` default compatibility path
-- `:vips` direct libvips path
+- `:vips` — the direct libvips path; formats outside the native loader
+  allowlist (ICO input) fail closed
+- `:imagemagick` — matches classic `convert` thumbnail pipelines
+  (`-thumbnail`, catrom interpolation, unsharp, sRGB profile); configure this
+  if byte-similar output with previously generated thumbnails matters
 
-### `SafeImage.crop(from, to, width, height, quality: nil, backend: :imagemagick, optimize: true, max_pixels: nil, encoder: :auto, chroma_subsampling: :auto)`
+#### `SafeImage.crop(from, to, width, height, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
 
-Creates a north-cropped image. This matches the avatar/optimized-image crop
-shape used by Discourse.
+Creates a north-cropped image — the shape typically used for square avatar
+crops.
 
 ```ruby
 SafeImage.crop("upload.jpg", "avatar.jpg", 240, 240)
-SafeImage.crop("upload.jpg", "avatar.jpg", 240, 240, backend: :vips)
 ```
 
-### `SafeImage.downsize(from, to, dimensions, backend: :imagemagick, optimize: true, max_pixels: nil, quality: 85, encoder: :auto, chroma_subsampling: :auto)`
+#### `SafeImage.downsize(from, to, dimensions, optimize: true, max_pixels: nil, quality: 85, chroma_subsampling: :auto)`
 
 Downsizes an image using ImageMagick-style geometry strings.
 
 ```ruby
 SafeImage.downsize("large.png", "small.png", "50%")
-SafeImage.downsize("large.png", "small.png", "100x100>", backend: :vips)
-SafeImage.downsize("large.png", "small.png", "400000@", backend: :vips)
+SafeImage.downsize("large.png", "small.png", "100x100>")
+SafeImage.downsize("large.png", "small.png", "400000@")
 ```
 
-The direct vips backend supports the geometry forms covered by the test suite:
+The vips backend supports the geometry forms covered by the test suite:
 percentage, bounding box with `>`, and pixel-area cap with `@`.
 
-### `SafeImage.convert(from, to, format:, quality: nil, optimize: true, max_pixels: nil, encoder: :auto, chroma_subsampling: :auto)`
+#### `SafeImage.convert(from, to, format:, quality: nil, optimize: true, max_pixels: nil, chroma_subsampling: :auto)`
 
 Converts an input image to an explicit output `format:`. Unsupported formats
 raise `SafeImage::UnsupportedFormatError`.
 
-For JPEG output, `encoder: :auto` uses `cjpegli` when it is installed and the
-input can be encoded directly by Jpegli. Today that direct path is intentionally
-limited to PNG input; other formats fall back to the hardened ImageMagick
-compatibility backend. Use `encoder: :cjpegli` to require Jpegli and fail closed,
-or `encoder: :imagemagick` to force the compatibility path.
+On the `:vips` backend this decodes through the native libvips loaders,
+auto-orients, flattens transparency onto white for JPEG targets (matching the
+ImageMagick path's `-background white -flatten`), and re-encodes. When no
+`quality:` is given, native JPEG output uses quality 92 — what ImageMagick
+uses for sources without quality tables — rather than libvips' default 75.
+ICO input/output is outside the native loaders and fails closed (use
+`convert_favicon_to_png` for favicons, or the `:imagemagick` backend).
+
+For PNG-to-JPEG on the `:vips` backend, `cjpegli` is used automatically when
+installed (see [JPEG encoding of generated images](#jpeg-encoding-of-generated-images)).
 
 ```ruby
 SafeImage.convert("upload.png", "upload.jpg", format: "jpg", quality: 85)
-SafeImage.convert("upload.png", "upload.jpg", format: "jpg", quality: 85, encoder: :cjpegli)
 SafeImage.convert("upload.heic", "upload.jpg", format: "jpg", quality: 85)
 SafeImage.convert("upload.jpg", "upload.webp", format: "webp", quality: 85)
 ```
 
-### `SafeImage.fix_orientation(from, to = from, max_pixels: nil)`
+#### `SafeImage.fix_orientation(from, to = from, max_pixels: nil, quality: nil)`
 
-Applies EXIF orientation through ImageMagick. If `to` is omitted, the file is
-rewritten in place.
+Bakes the EXIF orientation into the pixels and clears the tag. The `:vips`
+backend tries tiers in order:
 
-```ruby
-SafeImage.fix_orientation("upload.jpg")
-SafeImage.fix_orientation("upload.jpg", "oriented.jpg")
-```
+1. **jpegtran (lossless)** — for JPEGs with `jpegtran` installed, the
+   transform happens on the DCT coefficients with zero generation loss.
+   `-perfect` refuses non-MCU-aligned dimensions, in which case:
+2. **libvips re-encode** — autorotate and re-encode, stripping metadata.
+   JPEG output uses `quality:` (default 95).
 
-### `SafeImage.convert_favicon_to_png(from, to, optimize: true, max_pixels: nil)`
+The `:imagemagick` backend uses the previous `-auto-orient` behaviour and
+re-encodes at the input's estimated quality.
 
-Extracts the largest ICO frame and writes PNG.
+If `to` is omitted, the file is rewritten in place.
 
 ```ruby
-SafeImage.convert_favicon_to_png("favicon.ico", "favicon.png")
+SafeImage.fix_orientation("upload.jpg")
+SafeImage.fix_orientation("upload.jpg", "oriented.jpg")
 ```
 
-### `SafeImage.frame_count(path, max_pixels: nil)`
+#### `SafeImage.convert_favicon_to_png(from, to, optimize: true, max_pixels: nil)`
 
-Returns the frame count using the hardened ImageMagick identify path.
+Extracts the largest ICO entry and writes PNG. On the `:vips` backend no
+ImageMagick is involved: the container and legacy DIB payloads (1/4/8/24/32bpp
+BI_RGB plus the AND mask) are parsed in pure Ruby with explicit bounds checks,
+and pixels are encoded through the hardened native libvips path. Embedded PNG
+payloads are re-encoded — never copied through verbatim — and their pixel cap
+is enforced from the IHDR before any decoder runs. On the `:imagemagick`
+backend the conversion runs through ImageMagick's ico decoder under the
+bundled policy.
 
 ```ruby
-frames = SafeImage.frame_count("animated.gif")
+SafeImage.convert_favicon_to_png("favicon.ico", "favicon.png")
 ```
 
-### `SafeImage.animated?(path, max_pixels: nil)`
+#### `SafeImage.letter_avatar(output:, size:, background_rgb:, letter:, pointsize: 280, font: "DejaVu-Sans")`
 
-Returns `true` when `frame_count(path) > 1`.
+Generates a square letter avatar PNG: one grapheme blended in white at 80%
+opacity over a solid background.
 
-```ruby
-SafeImage.animated?("animated.webp")
-```
+The `:vips` backend renders natively through libvips' Pango text support (the
+glyph is markup-escaped before rendering) and fails closed on builds without
+a text renderer; the `:imagemagick` backend uses ImageMagick's annotation
+path.
 
-### `SafeImage.letter_avatar(output:, size:, background_rgb:, letter:, pointsize: 280, font: "NimbusSans-Regular")`
+The default `DejaVu-Sans` font uses the DejaVu Sans file bundled with the gem
+(see `lib/safe_image/fonts/DEJAVU-LICENSE`), so rendering does not depend on
+which fonts the host has installed. The other allowlisted tokens
+(`NimbusSans-Regular`, `Liberation-Sans`, `Arial`, `Helvetica`,
+`Adwaita-Sans`) resolve through fontconfig.
 
-Generates a square letter avatar PNG.
+The native path centres the glyph's ink box optically, which differs from the
+ImageMagick path's baseline placement (where descenders could clip at the
+canvas edge). Treat switching backends as a visual change: regenerate cached
+avatars.
 
 ```ruby
 SafeImage.letter_avatar(
   output: "avatar.png",
   size: 360,
   background_rgb: [1, 2, 3],
-  letter: "S",
-  font: "Adwaita-Sans"
+  letter: "S"
 )
 ```
 
-### `SafeImage.optimize(path, mode: :lossless, strip_metadata: true, quality: nil, strict: true)`
+#### JPEG encoding of generated images
+
+Safe Image separates **encoding generated JPEGs** from **optimising existing
+JPEGs**. This avoids hiding a lossy re-encode behind a method named `optimize`.
+
+Like the optimizer tools, the optional `cjpegli` encoder is availability
+driven: installed means used, absent means the configured backend encodes.
+There is no encoder knob — cjpegli only ever encodes pixels Safe Image has
+already decoded, so it is not part of the untrusted-input surface the backend
+choice controls.
+
+| Operation | Behavior |
+| --- | --- |
+| `thumbnail` / `resize` / `crop` / `downsize` to JPEG on the `:vips` backend | use `cjpegli` when installed; otherwise normal libvips JPEG output |
+| `convert("input.png", "output.jpg", format: "jpg")` on the `:vips` backend | use `cjpegli` when installed (PNG is the one input Jpegli encodes directly); otherwise libvips |
+| `convert` from HEIC/WebP/AVIF/GIF/JPEG to JPEG | decode through the native libvips loaders and encode with libvips; `cjpegli` is not treated as a universal decoder |
+| any operation on the `:imagemagick` backend | ImageMagick encodes; `cjpegli` is never used |
+| `optimize("existing.jpg")` | use `jpegoptim`; never `cjpegli` |
+
+`cjpegli` output is ordinary browser-compatible JPEG. It is optional because it
+is a system binary, not a Ruby dependency. Safe Image detects it at runtime.
+
+`chroma_subsampling: :auto` uses `4:4:4` for PNG-sourced JPEG conversion and
+`4:2:0` otherwise. Pass `"420"`, `"422"`, or `"444"` to force a value.
+
+### Optimising in place
+
+#### `SafeImage.optimize(path, mode: :lossless, strip_metadata: true, quality: nil, strict: true)`
 
 Optimises an existing JPEG or PNG in place.
 
@@ -504,16 +678,9 @@ PNG path:
 When `strict: true`, missing optimizer tools raise. When `strict: false`, missing
 optimizer tools are tolerated.
 
-### `SafeImage.optimize_image!(path, allow_lossy_png: false, strip_metadata: true, quality: nil, strict: true)`
-
-Compatibility wrapper around `SafeImage.optimize`.
+### SVG sanitising
 
-```ruby
-SafeImage.optimize_image!("image.jpg")
-SafeImage.optimize_image!("image.png", allow_lossy_png: true)
-```
-
-### `SafeImage.sanitize_svg!(path)`
+#### `SafeImage.sanitize_svg!(path)`
 
 Sanitises an SVG in place using a small REXML allowlist.
 
@@ -526,55 +693,90 @@ The sanitizer removes unsafe elements/attributes such as scripts and event
 handlers. It is intentionally conservative rather than a full browser-grade SVG
 implementation.
 
-## Security posture
+SVG sanitising is defense-in-depth for stored bytes. Applications that serve
+user-supplied SVGs directly should still use response-level controls such as a
+restrictive `Content-Security-Policy`, `X-Content-Type-Options: nosniff`, and/or
+attachment/sandbox handling for direct-open routes. Browsers restrict script
+execution when an SVG is embedded as `<img>`, but a top-level SVG document is a
+different sink.
+
+### Compatibility aliases
+
+Two thin wrappers kept for callers migrating from existing upload pipelines:
+
+```ruby
+SafeImage.optimize_image!("image.jpg")
+SafeImage.optimize_image!("image.png", allow_lossy_png: true)
+SafeImage.convert_to_jpeg("upload.heic", "upload.jpg", quality: 85)
+```
+
+`optimize_image!(path, allow_lossy_png: false, strip_metadata: true, quality: nil, strict: true)`
+forwards to `optimize`, with `allow_lossy_png:` mapping to `mode:`.
+`convert_to_jpeg(from, to, ...)` forwards to `convert` with `format: "jpg"`
+and accepts the same keywords.
 
-Safe Image is a hardened boundary for untrusted image processing, not a magic
-wand. The goal is to centralize risky operations, make the safe path boring, and
+## Security
+
+Safe Image is not magic pixie dust. It is a deliberately small choke point:
+the goal is to centralize risky operations, make the safe path boring, and
 remove common image-processing foot-guns.
 
-Baseline hardening:
-
-- external commands use argv arrays, never shell strings
-- command environment, temp/home/cache directories, stdout/stderr size, and
-  process-group timeout cleanup are controlled
-- libvips loaders are selected explicitly from an allowlist
-- libvips' untrusted-operation block is enabled in-process
-- libvips ImageMagick loader classes are blocked in the native extension
-- libvips cache is disabled by default in-process
-- local untrusted input/output paths reject symlinks and symlinked path components
-- generated images strip metadata where applicable
-- `max_pixels` checks fail before expensive work; the libvips path applies a
-  default 128MP ceiling (`SafeImage::DEFAULT_MAX_PIXELS`) when none is supplied
-- remote fetch uses SSRF hardening: scheme/port restrictions, special-use IP
+What it does:
+
+- forces one explicit, eagerly validated `configure!` decision — which backend
+  decodes untrusted bytes, whether the Landlock sandbox is on — before any
+  operation runs; everything else raises `NotConfiguredError`
+- uses explicit argv arrays for external commands, never shell strings
+- starts external commands with an allowlisted environment, private temp/home/cache
+  directories, bounded stdout/stderr, and process-group timeout cleanup
+- uses explicit libvips loaders selected from allowlisted extensions
+- enables libvips' untrusted-operation block in-process (deliberately
+  re-enabling only the libjxl loader/saver, which libvips tags untrusted,
+  because JPEG XL is part of the supported input surface)
+- blocks libvips ImageMagick loader classes in the libvips binding, which
+  itself exposes only the operations the gem invokes
+- disables libvips cache by default in-process
+- strips metadata on generated images where applicable
+- rejects symlinked local input/output paths and symlinked path components for
+  untrusted file-processing paths
+- caps decoded pixels before expensive work: the libvips path enforces a
+  default `SafeImage::DEFAULT_MAX_PIXELS` (128MP) ceiling even when no
+  `max_pixels` is given, and callers can raise or lower it per call
+- ships a restrictive ImageMagick `policy.xml`
+- denies Ghostscript-backed formats and dangerous ImageMagick features:
+  - `PS`, `PS2`, `PS3`, `EPS`, `EPSF`, `PDF`, `XPS`, `PCL`
+  - `MSL`, `MVG`
+  - `HTTP`, `HTTPS`, `URL`
+  - delegates, filters, and `@file` indirection
+- hardens remote fetch against SSRF: scheme/port restrictions, special-use IP
   blocking, DNS pinning, redirect limits, HTTPS-to-HTTP rejection, proxy-env
-  bypass prevention, request-header allowlists, content-type/extension agreement,
-  and probe-before-yield
-- SVG metadata uses a bounded parser; SVG is not handed to ImageMagick for probing
-- SVG sanitising is conservative and allowlist based; it rejects `DOCTYPE` and
-  XML processing instructions, removes comments and disallowed elements, converts
+  bypass prevention, request-header allowlists, content-type/extension
+  agreement, and probe-before-yield (details under [Remote URLs](#remote-urls))
+- parses SVG metadata with a bounded pure-Ruby parser; SVG is never handed to
+  ImageMagick for probing
+- sanitises SVG conservatively, allowlist based: rejects `DOCTYPE` and XML
+  processing instructions, removes comments and disallowed elements, converts
   CDATA to escaped text, and blocks event handlers, external URLs, and
   `javascript:` / `data:` URL values
+- supports optional Landlock subprocess sandboxing on Linux
 
-SVG sanitising is defense-in-depth for stored bytes. Applications that serve
-user-supplied SVGs directly should still use response-level controls such as a
-restrictive `Content-Security-Policy`, `X-Content-Type-Options: nosniff`, and/or
-attachment/sandbox handling for direct-open routes. Browsers restrict script
-execution when an SVG is embedded as `<img>`, but a top-level SVG document is a
-different sink.
+The backend is a configuration decision, not a per-call option. Safe Image
+will never silently fall from the libvips path into generic ImageMagick
+decoding — a format the configured backend cannot decode fails closed with
+`SafeImage::UnsupportedFormatError`.
 
 ### Security posture without Landlock
 
-Without Landlock, Safe Image still hardens the ImageMagick path substantially:
+Without Landlock, everything above still applies; in particular the
+ImageMagick path runs with:
 
-- delegates are disabled
-- filters are disabled
-- `@file` indirection is disabled
-- remote URL coders are disabled
-- Ghostscript/document/vector formats are denied
-- coders are deny-by-default with a small raster allowlist
-- commands are executed with argv arrays, not shell strings
-- command environment and ImageMagick policy path are controlled
-- ImageMagick resource limits are set in the bundled policy
+- delegates disabled
+- filters disabled
+- `@file` indirection disabled
+- remote URL coders disabled
+- Ghostscript/document/vector formats denied
+- coders deny-by-default with a small raster allowlist
+- ImageMagick resource limits set in the bundled policy
 
 That does **not** make hostile files benign. Raster decoders still parse attacker
 controlled bytes: libjpeg, libpng, libwebp, libheif/HEIC/AVIF, ImageMagick's
@@ -592,18 +794,18 @@ So the intended posture is:
 Do not describe non-sandboxed operation as making hostile images safe. The honest
 claim is defense-in-depth, not immunity.
 
-## Atomic Landlock sandboxing
+### Atomic Landlock sandboxing
 
-Landlock support is optional, but atomic once enabled.
+Landlock support is optional, but atomic once configured.
 
 ```ruby
-SafeImage.sandbox_available? # => true/false
-SafeImage.enable_sandbox!    # raises if unavailable
-SafeImage.sandbox_enabled?   # => true
+SafeImage.sandbox_available?                       # => true/false, works before configure!
+SafeImage.configure!(backend: :vips, landlock: true) # raises if unavailable
+SafeImage.config.landlock                          # => true
 ```
 
-After `SafeImage.enable_sandbox!`, every public operation routes through the
-sandbox worker:
+With `landlock: true`, every public operation routes through the sandbox
+worker:
 
 - `probe`
 - `type`
@@ -611,6 +813,7 @@ sandbox worker:
 - `dimensions`
 - `info`
 - `orientation`
+- `dominant_color`
 - `thumbnail`
 - `optimize`
 - `resize`
@@ -626,39 +829,22 @@ sandbox worker:
 - `optimize_image!`
 - `sanitize_svg!`
 
-There is no silent fallback after global sandbox enablement. If sandbox setup or
+There is no silent fallback once landlock is configured. If sandbox setup or
 a sandboxed command fails, the operation fails.
 
 The sandbox grants read/write access only to the paths inferred from the
 operation arguments, plus runtime/library paths and temporary directories needed
 by Ruby, libvips, ImageMagick, and optimizer tools. Network syscalls are denied
-through the Landlock helper's seccomp layer.
-
-## Discourse parity
-
-Safe Image currently covers the image-operation surface Discourse performs in:
-
-- optimized image generation
-- upload preprocessing
-- thumbnail generation
-- avatar cropping / letter avatars
-- favicon conversion
-- HEIC/PNG-to-JPEG conversion
-- orientation fixing
-- animated image detection
-- JPEG/PNG optimisation
-- SVG sanitising
-
-The claim is operation parity, not byte-for-byte output identity across all
-ImageMagick/libvips versions. The test suite includes golden compatibility
-checks, ImageMagick parity checks, policy-denial checks, and a real-image atomic
-sandbox sweep over the full public operation list.
+through the Landlock helper's seccomp layer. Worker processes inherit the
+parent's backend and pixel-ceiling configuration; landlock is forced off
+inside the worker so sandboxed operations never nest.
 
 ## Development
 
 ```bash
 bundle install
-bundle exec rake          # compile the native extension and run the tests
+bundle exec rake          # run the tests (nothing compiles)
+docker/run.sh             # run the suite on Debian bookworm's packaged libvips 8.14
 bundle exec rubocop       # lint
 ```
 
@@ -667,10 +853,14 @@ The minitest suite lives in `test/*_test.rb`; individual files run standalone
 host support — cjpegli, HEIC delegates, the Landlock sandbox — skip with an
 explanation when that support is missing.
 
+The suite includes golden-output checks, cross-backend parity checks (the
+claim is operation parity, not byte-for-byte output identity across
+ImageMagick/libvips versions), policy-denial checks, and a real-image atomic
+sandbox sweep over the full public operation list.
+
 Gem packaging uses the standard Bundler tasks (`rake build`, `rake install`).
-Releases follow the Discourse gem publication flow: bump
-`SafeImage::VERSION`, merge to `main`, and CI publishes the gem to
-RubyGems once the test matrix is green.
+Releases: bump `SafeImage::VERSION`, merge to `main`, and CI publishes the
+gem to RubyGems once the test matrix is green.
 
 ## Security reporting
 
@@ -686,13 +876,17 @@ Safe Image is MIT licensed.
 The gem dynamically links to system `libvips`; `libvips` is
 LGPL-2.1-or-later. Safe Image does not vendor `libvips`.
 
+The gem bundles the DejaVu Sans font for deterministic letter-avatar
+rendering; its license (Bitstream Vera derivative, freely redistributable)
+ships alongside the font at `lib/safe_image/fonts/DEJAVU-LICENSE`.
+
 Optional command-line tools are discovered at runtime and executed as external
 programs; they are not bundled into the gem. Typical licenses for those optional
 tools are:
 
 | Tool | Purpose | Typical license |
 | --- | --- | --- |
-| ImageMagick `magick` / `convert` / `identify` | compatibility operations | ImageMagick license |
+| ImageMagick `magick` / `convert` / `identify` | `:imagemagick` backend operations | ImageMagick license |
 | `jpegoptim` | JPEG lossless optimisation / metadata stripping | GPL-2.0-or-later |
 | `oxipng` | PNG lossless optimisation | MIT |
 | `pngquant` | optional lossy PNG quantisation | GPL-3.0-or-later / ISC / BSD-2-Clause components |
@@ -700,4 +894,4 @@ tools are:
 | `heif-enc` / libheif tools | optional HEIC/AVIF tooling when installed | LGPL-3.0-or-later |
 
 Deployment packages may vary; check your distribution's package metadata if
-license compliance depends on the exact binary build.
+license compliance depends on the exact binary build.