feat: add LosslessMode enum (Lossy / NearLossless / Lossless)

[lilith]

Summary

• with_lossless(bool) can't express near-lossless modes that WebP, JXL, and PNG support
• WebP: with_near_lossless(0-100) pre-rounds pixels in VP8L lossless path
• JXL: distance 0.0-1.0 "perceptually lossless zone" (distinct from Modular lossless)
• PNG: with_near_lossless_bits(1-4) rounds LSBs before DEFLATE
• AVIF, JPEG, GIF have no near-lossless mode

Proposal

Add to EncoderConfig trait:

enum LosslessMode {
    Lossy,
    NearLossless,
    Lossless,
}

Codecs without near-lossless treat NearLossless as high-quality lossy. Replaces with_lossless(bool) (deprecate, keep working via true → Lossless, false → Lossy).

[lilith]

Cross-codec survey + a generic abstraction

Investigated how every zen codec actually treats lossless/near-lossless (from source), and the result is that the proposed LosslessMode { Lossy, NearLossless, Lossless } is on the right track but collapses two physically different contracts into one variant. Full write-up landed in docs/near-lossless-design.md (commit 0b45311). Summary:

What each codec actually does

Codec	True lossless	"Near-lossless" mechanism	Native param	Error semantics
WebP	yes (VP8L)	adaptive pre-quant on the lossless path	near_lossless 0–100 (100=off)	guaranteed max err ∈ {0,1,3,7,15,31}; non-smooth pixels only; borders preserved
PNG	yes	global LSB rounding before filter+DEFLATE	near_lossless_bits 0–4	round to 2^b → max err 2^(b−1), every pixel
JXL	yes (modular d=0)	(a) lossy_palette bool; (b) small distance = visually lossless lossy codestream	with_lossy_palette / -d	palette is error-diffused (no clean ceiling); distance is a perception bound, not a per-channel ceiling. No max_delta_error exposed.
AVIF	yes (qindex 0)	none (low-QP lossy only)	with_lossless	—
JPEG	no	none	quality only	q100 still lossy
GIF	yes (≤256 colors)	none for pixels (lossy_tolerance = animation frame-diff)	—	palette reduction is the lossy step

The key insight — three conflated axes

1. Coding mode: is the codestream a lossless or lossy coder? (the real fork)
2. Near-lossless = bounded pre-quantization on a lossless path. The only thing that's technically near-lossless. Universal currency = max per-channel error budget ε (LSBs). WebP + PNG = exactly this.
3. "Visually lossless" = the top of the lossy quality scale (JXL d∈0.1–1.0, AVIF/JPEG/WebP-lossy q95+). Already reachable via with_generic_quality(~98) — not a separate mode.

The proposal lists WebP/PNG (axis 2: an ε ceiling on pixels, lossless codestream) next to "JXL distance 0.0–1.0" (axis 3: a perception bound, lossy codestream) as one mode. They're different contracts ("≤ ε per channel" vs "no human can tell") with different parameters and different output codestreams. A parameterless NearLossless also throws away the one number that makes it a contract.

Proposed abstraction (additive, non-breaking)

#[non_exhaustive]
pub enum LosslessMode {
    Lossy,
    /// Lossless codestream of pixels pre-quantized within a bounded per-channel
    /// error (LSBs at the encoded bit depth, 0 == exact). Guaranteed ceiling:
    /// the codec rounds the budget DOWN, never exceeds it.
    NearLossless { max_channel_error: u16 },
    Lossless,
}

• EncoderConfig::with_lossless_mode(LosslessMode) + lossless_mode() -> Option<LosslessMode>; with_lossless/is_lossless stay and forward via defaults (a codec implements one side, gets the other free).
• EncodeCapabilities::near_lossless flag so a dyn pipeline can query support.
• ε (max per-channel error) is the portable currency — not "bits" or "0–100" (those are codec-private inverses of each other; WebP 100=off vs PNG 0=off is a trap).
• lossless_mode() reports what was actually resolved — honored / promoted / demoted.

Resolution policy (refines "treat NearLossless as high-quality lossy")

Codec	NearLossless{ε>0} resolves to	caps.near_lossless
WebP, PNG	honored (≤ ε)	true
JXL, AVIF, GIF	promote → exact Lossless (fidelity-first; lossy_palette stays a codec-specific knob, not wired to ε since it has no ceiling)	false
JPEG	demote → Lossy (no lossless path)	false

One line: honor if you can; else promote to exact lossless if you have a lossless path; demote to high-q lossy only if you don't — and always report the truth. Promoting AVIF/GIF/JXL to lossless (rather than the issue's "treat as high-q lossy for all") keeps the "near" in near-lossless instead of needlessly dropping fidelity.

Recommendation on with_lossless deprecation

Keep it, don't deprecate. bool ↔ 3-state is lossy in only one direction, and with_lossless_mode covers that gap additively. Deprecating a widely-used setter is churn for no expressive gain. Ship as a minor (additive). Full mapping tables + implementation checklist in the design doc.