feat(png): a composed effort dial for the encoder

AGENTS.md

@@ -70,7 +70,10 @@ Dependency edges (a crate depends on those to its right):
   hostile input, ancillary metadata surfaced as raw `MetadataBlock`-ready payloads
   (eXIf/iCCP/XMP/text) plus parsed gAMA/cHRM/sRGB/cICP. APNG out of scope (decodes as the
   default image). Differential oracle both directions: libpng, which also *generates* the
-  decoder's conformance fixtures. ← core, deflate (+ `miniz_oxide` for inflate).
+  decoder's conformance fixtures. ← core, deflate (+ `miniz_oxide` for inflate, and
+  **maintainer-approved `crc32fast`** for the chunk CRC that every encode pays on its critical
+  path — hardware CRC-32 on x86-64/aarch64, table fallback elsewhere including wasm32, and it
+  keeps its `unsafe` to itself, so gamut-png stays `#![deny(unsafe_code)]`).
 - **gamut-ifd** — TIFF/IFD container core (byte order, field types, IFD read/write); a
   low-level container primitive (sibling to bitstream), shared by `gamut-tiff` and EXIF
   metadata. ← core. Optional `bigtiff` feature adds 64-bit BigTIFF. Per-format metadata

README.md

@@ -214,6 +214,8 @@ cargo test --workspace
 | `mise run lint-fix`  | Lint and auto-fix                        |
 | `mise run check-commits` | Check commits are Conventional Commits |
 | `mise run coverage`  | Run tests with coverage (min 80%)        |
+| `mise run bench`     | Run performance benchmarks (Divan; see [docs/benchmarking.md](docs/benchmarking.md)) |
+| `mise run bench-test` | Run every bench once to prove it still executes (no timings) |
 | `mise run check-cross <triple>` | Cross-compile-check the libs for a target (extended CI; master/manual) |
 | `mise run check-msrv` | Check the libs compile on the documented MSRV (extended CI; master/manual) |
 | `mise run versions`  | List every crate's version               |

crates/gamut-cli/src/commands/convert.rs

@@ -1,6 +1,6 @@
 //! `gamut convert` — decode an image and re-encode it with a gamut codec.
 
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 
 use clap::{Args, ValueEnum};
 use gamut::avif::AvifEncoder;
@@ -10,7 +10,7 @@ use gamut::jxl::{
     Container as JxlContainer, Distance as JxlDistance, Effort as JxlEffort, JxlEncoder,
     ModularMode as JxlModularMode,
 };
-use gamut::png::{Level as PngLevel, PngEncoder};
+use gamut::png::{PngEncoder, Preset as PngCodecPreset};
 use gamut::tiff::{Compression as TiffCompression, TiffEncoder};
 use gamut::webp::{Effort as WebpEffort, NearLossless as WebpNearLossless, WebpEncoder};
 
@@ -63,9 +63,17 @@ pub(crate) struct ConvertArgs {
     /// Compress TIFF output with PackBits run-length encoding instead of storing it uncompressed.
     #[arg(long)]
     packbits: bool,
-    /// PNG DEFLATE effort: optimal-parse refinement passes at the always-used best compression
-    /// level (0 = lazy parse only; zopfli's default budget is 15). Omitting it keeps the encoder
-    /// default (6). Ignored for other output formats.
+    /// PNG effort preset: one setting for the five knobs that trade encoding time for output size
+    /// (compression level, DEFLATE effort, filter strategy, optimal-parse span, and lossless
+    /// colour-type reduction). `small` is the default and is what this command has always done;
+    /// `smallest` adds the whole-image filter search, which is much slower. Ignored for other
+    /// output formats.
+    #[arg(long = "png-preset", value_enum, default_value = "small")]
+    png_preset: PngPreset,
+    /// PNG DEFLATE effort: optimal-parse refinement passes, overriding whatever `--png-preset`
+    /// chose (0 = lazy parse only; zopfli's default budget is 15). Only the best compression level
+    /// consults it, so it does nothing under `--png-preset fast` or `balanced`. Omitting it keeps
+    /// the preset's own budget. Ignored for other output formats.
     #[arg(long)]
     png_effort: Option<u8>,
     /// JPEG XL Butteraugli distance for lossy encoding (~1.0 = visually lossless, up to 25.0).
@@ -86,6 +94,16 @@ pub(crate) struct ConvertArgs {
     /// for other output formats.
     #[arg(long)]
     jxl_container: bool,
+    /// Drop the input's metadata instead of carrying it into the output. By default a PNG input
+    /// re-encoded to PNG keeps its EXIF, ICC profile, XMP packet, text annotations and colour
+    /// chunks; a stripped file is smaller, an unstripped one is colour-accurate, so the default
+    /// is the one that loses nothing. Anything that cannot be carried — the C2PA manifest store,
+    /// signed over the bytes of the file it was made for — and anything carried in a shape the
+    /// PNG specification does not endorse is reported on stderr rather than passed over in
+    /// silence. Currently applies only to the PNG output path with a PNG input; every other pair
+    /// drops metadata regardless.
+    #[arg(long)]
+    strip_metadata: bool,
 }
 
 /// Output container/codec for `gamut convert`.
@@ -97,7 +115,8 @@ pub(crate) enum OutputFormat {
     Webp,
     /// TIFF (8-bit RGB; uncompressed, or PackBits with `--packbits`).
     Tiff,
-    /// PNG — lossless; transparency preserved, with automatic lossless colour-type reduction.
+    /// PNG — lossless; transparency preserved, with automatic lossless colour-type reduction at
+    /// the default `--png-preset`.
     Png,
     /// JPEG XL — lossless by default, or lossy at `--jxl-distance`; transparency preserved.
     Jxl,
@@ -130,6 +149,38 @@ pub(crate) enum JxlModular {
     Modular,
 }
 
+/// PNG effort preset for `--png-preset`, naming the rungs of `gamut_png::Preset`.
+///
+/// The discriminants **are** the codec's ladder levels, and `to_codec` resolves them through
+/// [`PngCodecPreset::from_level`] rather than re-deciding the mapping — the same route
+/// `--webp-effort` and `--jxl-effort` take through their own ladders. A named value enum rather
+/// than the siblings' bare integer only because clap prints a rung's doc comment in `--help`,
+/// which a number cannot.
+#[derive(Clone, Copy, ValueEnum)]
+#[repr(u8)]
+pub(crate) enum PngPreset {
+    /// Fastest: greedy matching and one fixed filter, accepting a larger file.
+    Fast = 0,
+    /// The `gamut-png` library default — the balanced speed/size point.
+    Balanced = 1,
+    /// The optimal parse and lossless reduction on one filter heuristic; this command's default.
+    Small = 2,
+    /// Adds the whole-image filter search, zopfli's own refinement budget and a wider
+    /// optimal-parse span. Six times slower than `small` and worth about 3.6% on gamut's corpus,
+    /// but nothing at all on three of its nine rows: measure your own material.
+    Smallest = 3,
+}
+
+impl PngPreset {
+    /// Maps the CLI choice onto the codec's [`PngCodecPreset`] rung.
+    fn to_codec(self) -> PngCodecPreset {
+        // `the_png_preset_flag_offers_exactly_the_codec_ladder` pins that every discriminant here
+        // is a level the codec admits, so the fallback is unreachable; it exists because this is
+        // a CLI and a panic is not an error report.
+        PngCodecPreset::from_level(self as u8).unwrap_or_default()
+    }
+}
+
 impl JpegSubsampling {
     /// Maps the CLI choice onto the codec's [`JpegChroma`] enum.
     fn to_codec(self) -> JpegChroma {
@@ -236,12 +287,40 @@ pub(crate) fn run(args: &ConvertArgs) -> Result<(), CliError> {
                 bytes = rgba.len(),
                 "decoded input"
             );
-            let mut encoder = PngEncoder::new()
-                .with_compression(PngLevel::Best)
-                .with_auto_reduce(true);
+            // The preset sets every size/time knob; `--png-effort` still overrides the one it
+            // names, so it must be applied after.
+            let mut encoder = PngEncoder::new().with_preset(args.png_preset.to_codec());
             if let Some(effort) = args.png_effort {
                 encoder = encoder.with_effort(effort);
             }
+            // Carry the input's metadata rather than dropping it (issue #483). `png_metadata`
+            // reads the file from disk a second time; the *walk* is cheap (it skips IDAT by
+            // length and never inflates a pixel), the second read is not, and it is what the
+            // convenience of taking a path rather than the already-loaded bytes costs. It yields
+            // nothing for an input that is not a PNG.
+            let metadata = (!args.strip_metadata)
+                .then(|| png_metadata(&args.input))
+                .flatten();
+            if let Some(metadata) = &metadata {
+                tracing::info!(
+                    texts = metadata.texts.len(),
+                    exif = metadata.exif.is_some(),
+                    icc = metadata.icc_profile.is_some(),
+                    xmp = metadata.xmp.is_some(),
+                    "carrying input metadata"
+                );
+                encoder = encoder.with_metadata(metadata);
+                // Say what could not come along, and what came along with a caveat. Silent loss
+                // is the defect this path exists to remove, and a payload the spec forbids
+                // carrying is still a payload the caller had.
+                for notice in encoder.metadata_notices() {
+                    if notice.carried() {
+                        tracing::warn!("input metadata carried with a caveat — {notice}");
+                    } else {
+                        tracing::warn!("input metadata not carried — {notice}");
+                    }
+                }
+            }
             encoder.encode_image(ImageRef::<Rgba8>::new(&rgba, dims)?, &mut out)?;
             (rgba.len(), dims)
         }
@@ -324,6 +403,16 @@ pub(crate) fn run(args: &ConvertArgs) -> Result<(), CliError> {
     Ok(())
 }
 
+/// The metadata `path` carries, or `None` when it is not a PNG or cannot be read.
+///
+/// Deliberately total: the input has already been decoded successfully by the time this is
+/// called, so an error here means the file is simply not a PNG — a JPEG or WebP input has
+/// metadata of its own, but mapping that into PNG chunks is a cross-format job this command does
+/// not do yet. Failing to *read* metadata must never fail a conversion whose pixels are fine.
+fn png_metadata(path: &Path) -> Option<gamut::png::PngMetadata> {
+    gamut::png::metadata(&std::fs::read(path).ok()?).ok()
+}
+
 /// Picks the output format from `--format`, falling back to the output file's extension.
 fn resolve_format(args: &ConvertArgs) -> Result<OutputFormat, CliError> {
     if let Some(format) = args.format {
@@ -346,3 +435,30 @@ fn resolve_format(args: &ConvertArgs) -> Result<OutputFormat, CliError> {
         None => Err(CliError::UnsupportedOutput("<none>".to_string())),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use clap::ValueEnum;
+
+    use super::{PngCodecPreset, PngPreset};
+
+    #[test]
+    fn the_png_preset_flag_offers_exactly_the_codec_ladder() {
+        // The flag's values and the codec's rungs are two lists that must stay the same list.
+        // Walking `from_level` from zero is the codec's own enumeration of its ladder, so a rung
+        // added to `gamut_png::Preset` fails here instead of being silently unreachable from the
+        // command line — which is what a hand-written arm-per-variant mapping could not catch.
+        let from_flag: Vec<u8> = PngPreset::value_variants()
+            .iter()
+            .map(|preset| preset.to_codec().level())
+            .collect();
+        let from_codec: Vec<u8> = (0..=u8::MAX)
+            .map_while(PngCodecPreset::from_level)
+            .map(PngCodecPreset::level)
+            .collect();
+        assert!(
+            from_flag == from_codec,
+            "--png-preset offers levels {from_flag:?} against the codec ladder {from_codec:?}"
+        );
+    }
+}