react-native-ensys-camera-x 1.0.7

package/android/src/main/java/com/customcamera/ImageExporter.kt

@@ -0,0 +1,1394 @@
+package com.customcamera
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.ImageDecoder
+import android.graphics.Matrix
+import android.media.ExifInterface
+import android.media.Image
+import android.media.MediaCodec
+import android.media.MediaCodecInfo
+import android.media.MediaFormat
+import android.media.MediaMuxer
+import android.os.Build
+import android.os.SystemClock
+import android.util.Log
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.io.IOException
+import java.io.InputStream
+import java.io.OutputStream
+
+/**
+ * Re-encodes a still image for the preview editor's two header menus: [export] converts it into
+ * another container ("Export By") and [compress] rewrites it smaller ("Compress Image").
+ *
+ * The pairing mirrors the video side, where [VideoRotationTranscoder] holds `convertContainer` and
+ * `compress` for exactly the same two menus, and both of this object's entry points share the one
+ * contract:
+ *
+ *  - **The source file is never touched.** Every export writes a brand-new file; the original
+ *    bytes are only ever read.
+ *  - **Geometry survives.** The image is decoded at full resolution and encoded at exactly those
+ *    pixel dimensions, so width, height and aspect ratio come out unchanged. The one exception is
+ *    HEIF/AVIF, whose 4:2:0 encoders need even dimensions — see [encodeStillViaCodec].
+ *  - **Orientation survives.** EXIF rotation is baked into the pixels and the output is written
+ *    with an upright orientation tag, because PNG/WebP/HEIF do not carry an EXIF orientation that
+ *    consumers reliably honour. Reading the exported file therefore shows exactly what the
+ *    preview showed — no double rotation, no sideways export.
+ *  - **Metadata survives where the container can hold it.** Capture time, camera make/model, GPS
+ *    and exposure data are copied across for the containers this platform can write EXIF into.
+ *
+ * JPEG, PNG and WebP go through `Bitmap.compress`. HEIF and AVIF have no `Bitmap.CompressFormat`
+ * on ANY API level (verified against the API 36 platform: the enum holds JPEG, PNG, WEBP,
+ * WEBP_LOSSY and WEBP_LOSSLESS and nothing else), so they are encoded through the platform's
+ * dedicated still-image encoders and written with the HEIF muxer. [MediaExportFormats] decides
+ * whether that path exists on this device, so this class is only ever asked for a format the
+ * device can actually produce.
+ */
+object ImageExporter {
+  private const val TAG = "ImageExporter"
+
+  /**
+   * Encoder quality for lossy targets. Matches the quality the editor already uses when it bakes
+   * edits into a JPEG (MediaPreviewEditor.saveEditedImageComposited), so a format conversion
+   * never comes out visibly softer than an ordinary edited send.
+   */
+  const val DEFAULT_QUALITY = 95
+
+  private const val DEQUEUE_TIMEOUT_US = 10_000L
+  private const val ENCODE_TIMEOUT_NS = 30_000_000_000L
+  private const val MAX_IDLE_POLLS_AFTER_OUTPUT = 50
+
+  // ── Compression search bounds ───────────────────────────────────────────────────────────
+  /**
+   * Quality floor for a compressed still. Below roughly this the encoder starts producing
+   * blocking that is obvious at a glance, so the search stops asking for quality it cannot
+   * deliver and reaches for a downscale instead — fewer, cleaner pixels beat more, mushy ones.
+   */
+  private const val MIN_COMPRESSION_QUALITY = 20
+  /** Ceiling: re-encoding above this buys file size back without buying visible detail. */
+  private const val MAX_COMPRESSION_QUALITY = 95
+  /**
+   * Downscale factors tried in order when no quality in the band above reaches the target size.
+   * The first entry is "don't scale at all", which is the only step most images ever need.
+   */
+  private val COMPRESSION_SCALE_STEPS = floatArrayOf(1f, 0.75f, 0.5f, 0.35f)
+  /** Encodes per scale step. Six halvings resolve the 20..95 quality band to within one point. */
+  private const val MAX_QUALITY_PROBES = 6
+
+  // ── Size prediction (what a menu can quote before anything is encoded) ────────────────────
+  /**
+   * The low end of a predicted range, as a fraction of the target ceiling.
+   *
+   * [compress] aims at an exact byte CEILING (`source × (1 - percent/100)`) and keeps the highest
+   * quality that lands at or under it, so the produced file is never bigger than the target but is
+   * routinely a little smaller: the quality search resolves the band only to within about one
+   * step, a profile pre-cap on the longest edge removes pixels outright, and a target the encoder
+   * cannot reach falls back to the smallest candidate it found. All three land the output BELOW the
+   * ceiling, so the quoted band runs from `ceiling × this` up to the ceiling. This is the still's
+   * counterpart to the video side's [VideoRotationTranscoder.ESTIMATE_RATE_UNDERSHOOT] — a modelled
+   * tolerance, not a padded guess — and it is tighter because a byte target is a hard ceiling
+   * whereas a bit rate is only a target the VBR encoder spends around.
+   *
+   * The compression menu's VIDEO rows — now quoted PROPORTIONALLY rather than from the bit-rate
+   * model — reuse THIS fraction (not the bit-rate one) to open their band, so a video row and an
+   * image row shave their low end by the same amount. This constant is the one place it is defined.
+   */
+  internal const val ESTIMATE_SIZE_UNDERSHOOT = 0.85
+
+  // ── Progress reporting ──────────────────────────────────────────────────────────────────
+  // Both entry points report how far through the work they are so the caller's overlay can show a
+  // REAL remaining time rather than counting a prediction down.
+  //
+  // The fractions are CONTINUOUS, not milestones. A still's two expensive phases are single
+  // blocking platform calls with no callback of their own — `BitmapFactory.decodeStream` and
+  // `Bitmap.compress` — so each is measured through the bytes it moves: the decoder is fed a
+  // counting InputStream and the encoder writes through a counting OutputStream (see
+  // [CountingInputStream] / [CountingOutputStream]). Reporting only at the phase boundaries, as
+  // this used to, left the caller's countdown with seconds of silence to guess through, which is
+  // exactly how it ran out mid-export or froze one second short of the end.
+  //
+  // Every value is emitted through [ProgressEmitter], which keeps the sequence monotonic and
+  // throttles it to the same interval/delta pair the video transcode uses.
+  /** Smallest gap between two progress callbacks. Enough to animate; far too coarse to cost. */
+  private const val PROGRESS_MIN_INTERVAL_MS = 150L
+  /** …unless the fraction has moved this much, which forces a callback however recent the last. */
+  private const val PROGRESS_MIN_DELTA = 0.01f
+
+  // [compress]'s 0..1 range. Unlike the video transcode, whose fraction is a measured position on a
+  // known timeline, a still's compression cost is a decode plus an unknown number of encodes — the
+  // search stops as soon as it converges. So beyond the decode the fraction is the search's
+  // PROGRESS THROUGH ITS BUDGET: the boundaries below carve the range into one span per scale step,
+  // and each probe advances within its step's span. It is monotonic and it never claims to be
+  // finished early; when the search converges before spending its budget the fraction jumps
+  // forward, which is the truth (the work really did end sooner).
+  /** Fraction complete once the source is decoded and flattened — the one fixed, unavoidable cost. */
+  private const val PROGRESS_AFTER_DECODE = 0.15f
+  /**
+   * Upper bound of each scale step's span, indexed alongside [COMPRESSION_SCALE_STEPS]. The
+   * full-size step gets the largest share because it is both the most expensive (full-resolution
+   * encodes) and the only step the overwhelming majority of images ever need; the downscaled
+   * steps, reached only when the target is out of reach, are cheaper and get progressively less.
+   */
+  private val PROGRESS_SCALE_STEP_BOUNDS = floatArrayOf(0.70f, 0.85f, 0.93f, 0.97f)
+  /** Everything after the search — writing the winner, reading it back, copying metadata. */
+  private const val PROGRESS_BEFORE_WRITE = 0.97f
+
+  // [export] reports against the same contract, for the same reason — its caller shows the same
+  // countdown — but its 0..1 range is carved up differently, because a conversion is not a search:
+  // it is one decode, one encode and one read-back, in that order, every time. Both of the two
+  // expensive phases are measured as they run (bytes read by the decoder, bytes written by the
+  // encoder), so the fraction moves continuously rather than standing still between milestones.
+  /**
+   * Fraction complete once the source is decoded and flattened, for the targets encoded through
+   * `Bitmap.compress`.
+   *
+   * The decode is a fixed cost — full-resolution pixels out of a compressed container — while the
+   * encode's cost depends on the target, so the split is stated per encoder rather than shared.
+   * For JPEG/PNG/WebP/PDF the two phases are broadly comparable, which is what this near-even
+   * split says.
+   */
+  private const val PROGRESS_EXPORT_DECODE_END = 0.42f
+  /**
+   * The same boundary for HEIF/AVIF. Their encode is the MediaCodec + HEIF muxer path
+   * ([encodeStillViaCodec]), which pays a codec configure/start, a full RGB→YUV 4:2:0 conversion of
+   * every pixel in process and a muxer write on top of the encode itself — so it dwarfs the decode
+   * and gets a correspondingly larger share of the range.
+   */
+  private const val PROGRESS_EXPORT_CODEC_DECODE_END = 0.25f
+  /** Fraction complete once the single encode has produced the output file. */
+  private const val PROGRESS_EXPORT_AFTER_ENCODE = 0.90f
+  /**
+   * Reported once the encode is over and the pass is in its tail — decoding the output back to
+   * verify it and copying the metadata across. That work is real but has no measurable length, so
+   * it is deliberately reported ABOVE the caller's "finalizing" threshold: the countdown hands over
+   * to a static line for it instead of quoting a second count it cannot justify.
+   */
+  private const val PROGRESS_EXPORT_TAIL = 0.99f
+  /**
+   * Ceiling for the fraction derived from bytes written during an encode. The expected output size
+   * is an estimate ([estimatedEncodedBytes]), so a small file could otherwise reach — and appear to
+   * pass — its phase boundary while the encoder was still running. The boundary itself is only ever
+   * reported once the encode has actually returned.
+   */
+  private const val PROGRESS_ENCODE_MEASURED_CEILING = 0.97f
+
+  // Sub-phases of the HEIF/AVIF encode ([encodeStillViaCodec]), expressed as fractions of THAT
+  // encode rather than of the whole export — the caller maps them into the encode's span.
+  /** The codec is configured and started; nothing has been fed to it yet. */
+  private const val PROGRESS_CODEC_STARTED = 0.06f
+  /** The whole frame has been converted to YUV and handed over. */
+  private const val PROGRESS_CODEC_FRAME_QUEUED = 0.62f
+  /** How far one muxed tile advances the drain. */
+  private const val PROGRESS_CODEC_PER_SAMPLE = 0.12f
+  /** …and how far the drain may get on tiles alone, since their number is unknown up front. */
+  private const val PROGRESS_CODEC_MEASURED_CEILING = 0.97f
+
+  /** Dimensions of a successfully exported file, read back from the file itself. */
+  data class ExportResult(val width: Int, val height: Int)
+
+  /**
+   * What [compress] managed to do.
+   *
+   * The three cases are kept apart because the caller says something different about each: a
+   * [Success] reports the saving achieved, an [AlreadyMinimal] tells the user there is nothing
+   * left to squeeze (which is NOT an error), and a [Failed] is a genuine encode failure.
+   */
+  sealed interface CompressOutcome {
+    /** A smaller file was produced. [bytes] is its real length, [format] the container written. */
+    data class Success(
+      val width: Int,
+      val height: Int,
+      val bytes: Long,
+      val format: ImageFormatSupport.Format
+    ) : CompressOutcome
+
+    /**
+     * Every candidate came out at least as large as the source, so nothing was written.
+     *
+     * The ordinary cause is an image that has already been through a lossy encoder at a low
+     * quality (a re-shared chat photo, a heavily optimised thumbnail): there is no redundancy
+     * left for a second pass to remove, and re-encoding only adds overhead. Handing back a
+     * "compressed" copy that is BIGGER than the original would make the menu lie, so the
+     * original is kept instead.
+     */
+    object AlreadyMinimal : CompressOutcome
+
+    /** The source could not be decoded, or no encoder would produce a readable file. */
+    object Failed : CompressOutcome
+  }
+
+  /**
+   * Export [source] into [output] as [format].
+   *
+   * @param onProgress called on the CALLING (worker) thread with how much of the work is done,
+   *   0.0..1.0, CONTINUOUSLY as the decode and the encode run — see the export progress constants
+   *   above. Measured, not predicted: the decode's fraction is the source bytes the decoder has
+   *   consumed and the encode's is the output bytes it has written, so the number advances at
+   *   exactly the rate the conversion does and a caller can show a remaining time that tracks the
+   *   real work instead of a clock. Monotonic, starts at 0.0, and reaches exactly 1.0 on every
+   *   terminal outcome INCLUDING a failure — the work really is over in both cases, and a caller
+   *   waiting on a 1.0 that never came would sit on a stale overlay.
+   * @return the exported file's real dimensions, or null if the image could not be decoded, the
+   *   encoder refused the frame, or the result cannot be decoded again. [output] is deleted on
+   *   every failure, so a partial file is never left behind for a caller to mistake for a
+   *   finished export.
+   */
+  fun export(
+    source: File,
+    output: File,
+    format: ImageFormatSupport.Format,
+    quality: Int = DEFAULT_QUALITY,
+    onProgress: ((Float) -> Unit)? = null
+  ): ExportResult? {
+    val progress = ProgressEmitter(onProgress)
+    progress.report(0f)
+    if (!source.exists() || source.length() <= 0L) {
+      Log.w(TAG, "Export source is missing or empty: ${source.absolutePath}")
+      progress.report(1f)
+      return null
+    }
+    // Where the decode ends and the encode begins, for THIS target's encoder.
+    val decodeEnd = if (MediaExportFormats.stillEncoderMimeType(format) != null) {
+      PROGRESS_EXPORT_CODEC_DECODE_END
+    } else {
+      PROGRESS_EXPORT_DECODE_END
+    }
+    val encodeSpan = PROGRESS_EXPORT_AFTER_ENCODE - decodeEnd
+    var working: Bitmap? = null
+    return try {
+      // The decode reports as it consumes the file, so a multi-second full-resolution decode is
+      // visible to the caller's countdown while it happens instead of only once it is over.
+      val decoded = decodeUpright(source) { read -> progress.advance(decodeEnd * read) }
+      if (decoded == null) {
+        Log.w(TAG, "Could not decode ${source.absolutePath} for export")
+        return null
+      }
+      working = decoded
+      // Targets with no alpha channel get the image flattened onto white FIRST, rather than
+      // letting the encoder drop the channel — which composites onto black and turns a
+      // transparent PNG's background into a solid black slab.
+      if (needsOpaqueSource(format) && decoded.hasAlpha()) {
+        val flattened = flattenOntoWhite(decoded)
+        if (flattened !== decoded) {
+          runCatching { decoded.recycle() }
+          working = flattened
+        }
+      }
+      val bitmap = working ?: return null
+      // The decode (and any flatten) is done: the one cost every conversion pays before the
+      // encoder is even configured.
+      progress.report(decodeEnd)
+
+      // How the encode's own progress is measured: the output bytes it has written against a
+      // generous estimate of what it will write in total. Deliberately generous — see
+      // [estimatedEncodedBytes] — so the fraction lags the encoder rather than reaching its phase
+      // boundary early, and the boundary itself is only ever reported once the encode returns.
+      val expectedBytes = estimatedEncodedBytes(bitmap, format)
+      val onEncodedBytes: (Long) -> Unit = { written ->
+        progress.advance(decodeEnd + encodeSpan * writtenFraction(written, expectedBytes))
+      }
+      val encoded = when (format) {
+        ImageFormatSupport.Format.JPEG ->
+          compressBitmap(bitmap, Bitmap.CompressFormat.JPEG, quality, output, onEncodedBytes)
+        ImageFormatSupport.Format.PNG ->
+          // PNG is lossless; its quality argument is ignored by the encoder.
+          compressBitmap(bitmap, Bitmap.CompressFormat.PNG, 100, output, onEncodedBytes)
+        ImageFormatSupport.Format.WEBP ->
+          compressBitmap(bitmap, webpFormat(), quality, output, onEncodedBytes)
+        ImageFormatSupport.Format.HEIF,
+        ImageFormatSupport.Format.AVIF -> {
+          val mime = MediaExportFormats.stillEncoderMimeType(format)
+          mime != null && encodeStillViaCodec(bitmap, mime, quality, output) { phase ->
+            progress.advance(decodeEnd + encodeSpan * phase)
+          }
+        }
+        ImageFormatSupport.Format.PDF ->
+          exportPdf(bitmap, output, onEncodedBytes)
+        else -> {
+          Log.w(TAG, "No encoder for export format $format")
+          false
+        }
+      }
+      if (!encoded || !output.exists() || output.length() <= 0L) {
+        runCatching { output.delete() }
+        return null
+      }
+      // The encode is what the wait was mostly spent on, and it is over. Everything past here —
+      // reading the output back and copying metadata onto it — is real work of unmeasurable
+      // length, so the pass reports straight through [PROGRESS_EXPORT_AFTER_ENCODE] into its tail
+      // rather than quoting a share of a countdown for it.
+      progress.report(PROGRESS_EXPORT_TAIL)
+      // Report the dimensions of the FILE, not of the bitmap that was handed to the encoder. The
+      // two differ by a pixel when a HEIF/AVIF encode rounds an odd edge down (see
+      // [encodeStillViaCodec]), and this doubles as the "can it be read back?" check: an encoder
+      // can report success and still leave a container no decoder will open, which the preview
+      // would render as a blank frame.
+      val dimensions = if (format == ImageFormatSupport.Format.PDF) {
+        Pair(bitmap.width, bitmap.height)
+      } else {
+        readImageBounds(output)
+      }
+      if (dimensions == null) {
+        Log.w(TAG, "Exported ${output.name} cannot be decoded back; discarding")
+        runCatching { output.delete() }
+        return null
+      }
+      copyMetadata(source, output, format)
+      ExportResult(dimensions.first, dimensions.second)
+    } catch (e: OutOfMemoryError) {
+      // A full-resolution ARGB_8888 decode is the largest allocation this library makes; on a
+      // low-RAM device it can exhaust the heap. Treat it as a failed export (the caller keeps
+      // showing the original) rather than tearing the process down.
+      Log.e(TAG, "Out of memory exporting ${source.name} as $format", e)
+      runCatching { output.delete() }
+      null
+    } catch (e: Exception) {
+      Log.e(TAG, "Failed to export ${source.name} as $format", e)
+      runCatching { output.delete() }
+      null
+    } finally {
+      runCatching { working?.recycle() }
+      // Every way out of this function is the end of the work — a finished conversion, a source
+      // that could not be decoded, an encoder that refused the frame, an OOM. Reporting the
+      // terminal 1.0 from here rather than from the success path is what guarantees a caller's
+      // overlay is never left waiting on a completion that a failure quietly swallowed.
+      progress.report(1f)
+    }
+  }
+
+  /**
+   * How far through an encode [written] bytes is, given [expected] as the total it will write.
+   *
+   * Capped below 1.0 ([PROGRESS_ENCODE_MEASURED_CEILING]) because [expected] is an estimate: an
+   * output that beats it must not be able to walk the fraction over its phase boundary while the
+   * encoder is still writing. Only the encoder actually returning reports the boundary.
+   */
+  private fun writtenFraction(written: Long, expected: Long): Float {
+    if (expected <= 0L) return 0f
+    return (written.toDouble() / expected.toDouble())
+      .toFloat()
+      .coerceIn(0f, PROGRESS_ENCODE_MEASURED_CEILING)
+  }
+
+  /**
+   * Roughly how many bytes encoding [bitmap] into [format] will write — the denominator the
+   * encode's measured progress is expressed against, never a promise about the output.
+   *
+   * Bytes per pixel, because that is what every one of these encoders scales with, and biased
+   * HIGH on purpose. The two ways to be wrong are not symmetric: an estimate that is too small
+   * pins the fraction at its ceiling with the encoder still running (the caller's countdown then
+   * believes the work is nearly done and freezes a second short of the end), while one that is too
+   * large simply makes the fraction climb more slowly than the truth and snap forward when the
+   * encode returns — which is the same shape as any job that finishes ahead of its prediction.
+   */
+  private fun estimatedEncodedBytes(bitmap: Bitmap, format: ImageFormatSupport.Format): Long {
+    val pixels = bitmap.width.toLong() * bitmap.height.toLong()
+    val bytesPerPixel = when (format) {
+      // Lossy, and at [DEFAULT_QUALITY] a photo lands well under one byte per pixel.
+      ImageFormatSupport.Format.JPEG -> 1.2
+      ImageFormatSupport.Format.WEBP -> 1.0
+      // The 4:2:0 codec path is the densest of the lot.
+      ImageFormatSupport.Format.HEIF,
+      ImageFormatSupport.Format.AVIF -> 0.8
+      // Lossless deflate over (mostly) 24-bit pixels.
+      ImageFormatSupport.Format.PNG -> 3.0
+      // A PDF page here is one embedded, deflated image plus a little structure.
+      ImageFormatSupport.Format.PDF -> 3.0
+      else -> 2.0
+    }
+    return (pixels * bytesPerPixel).toLong().coerceAtLeast(1L)
+  }
+
+  // ---------------------------------------------------------------------------------------
+  // Compress — the still-image counterpart of VideoRotationTranscoder.compress
+  // ---------------------------------------------------------------------------------------
+
+  /**
+   * The container a compressed copy of [source] is written in.
+   *
+   * Compression normalises the container, exactly as the video side does (every compressed clip
+   * comes out an MP4 whatever went in): a lossless or exotic still has no quality knob to turn, so
+   * "make this 30% smaller" is only answerable by re-encoding into something lossy. The choice is
+   * between the two lossy encoders every device has:
+   *
+   *  - **JPEG** for anything opaque. Smallest output, universally readable.
+   *  - **Lossy WebP** when the source's container can carry transparency. JPEG has no alpha
+   *    channel, so a transparent PNG compressed to JPEG would come back with its background
+   *    flattened onto white — a visible, irreversible change the user did not ask for.
+   *
+   * Decided from the container alone (no decode), so the caller can name the output file before
+   * any work starts. A PNG that happens to be fully opaque therefore still goes to WebP, which
+   * costs nothing: lossy WebP is at least as small as JPEG at equal quality.
+   */
+  fun compressionFormatFor(source: File): ImageFormatSupport.Format =
+    if (ImageFormatSupport.fromFileName(source.name)?.mayHaveAlpha == true) {
+      ImageFormatSupport.Format.WEBP
+    } else {
+      ImageFormatSupport.Format.JPEG
+    }
+
+  /**
+   * Write a copy of [source] into [output] that is [percent] smaller.
+   *
+   * The contract matches [export] — the source is only ever READ, orientation is baked into the
+   * pixels, metadata is carried where the container can hold it, and [output] is deleted on every
+   * failure — with one addition: the output is measured against the request.
+   *
+   * **Why a search rather than a fixed quality.** The video encoder takes a target bit rate, so
+   * "shave 30%" maps straight onto a number the codec understands. A still encoder takes a quality
+   * index, and the size it yields depends entirely on the image's content: quality 70 on a flat
+   * screenshot is a 95% saving, on fine foliage it is barely 20%, and on an already-compressed chat
+   * photo it can be *larger* than the input. Handing the encoder `100 - percent` and hoping would
+   * make the menu's numbers meaningless and would sometimes grow the file. So the target size is
+   * computed first and the encoder is asked repeatedly:
+   *
+   *  1. Binary-search the quality band for the HIGHEST quality that lands at or under the target,
+   *     seeded at `100 - percent` (the mapping the video side uses, and the right answer for a
+   *     typical photo, so the common case converges in one or two probes).
+   *  2. If even [MIN_COMPRESSION_QUALITY] overshoots, downscale and search again — past that floor
+   *     the only honest way to remove bytes is to remove pixels.
+   *  3. If nothing anywhere beat the ORIGINAL's size, write nothing and report
+   *     [CompressOutcome.AlreadyMinimal].
+   *
+   * Only the winning byte array is written, so the search costs encodes, not disk churn.
+   *
+   * @param percent how much of the file's size to remove, 1..95. Clamped, not validated.
+   * @param onProgress called on the CALLING (worker) thread with how much of the work is done,
+   *   0.0..1.0, as the decode and each encode probe complete — see the progress constants above.
+   *   It is measured, not predicted: it advances when work finishes, so a caller can derive a
+   *   remaining time that tracks the real encode instead of a clock. Monotonic, starts at 0.0, and
+   *   reaches exactly 1.0 on every terminal outcome INCLUDING [CompressOutcome.AlreadyMinimal] and
+   *   [CompressOutcome.Failed] — the work really is over in all three cases, and a caller that
+   *   waited for a 1.0 that never came would sit on a stale overlay.
+   */
+  fun compress(
+    source: File,
+    output: File,
+    percent: Int,
+    onProgress: ((Float) -> Unit)? = null,
+    // The active image profile resolved to concrete knobs (quality band, downscale ladder, a
+    // pre-cap on the longest edge, and the low-RAM decode subsample). The default reproduces the
+    // pre-profile search exactly, so a caller that passes nothing is unaffected. Placed after
+    // [onProgress] so existing positional callers keep compiling.
+    plan: ImageCompressionPlan = ImageCompressionPlan()
+  ): CompressOutcome {
+    val progress = ProgressEmitter(onProgress)
+    progress.report(0f)
+    if (!source.exists() || source.length() <= 0L) {
+      Log.w(TAG, "Compression source is missing or empty: ${source.absolutePath}")
+      progress.report(1f)
+      return CompressOutcome.Failed
+    }
+    val sourceBytes = source.length()
+    val shave = percent.coerceIn(1, 95)
+    val targetBytes = (sourceBytes * (100L - shave) / 100L).coerceAtLeast(1L)
+    val format = compressionFormatFor(source)
+    val compressFormat = if (format == ImageFormatSupport.Format.WEBP) {
+      webpFormat()
+    } else {
+      Bitmap.CompressFormat.JPEG
+    }
+
+    var working: Bitmap? = null
+    return try {
+      // Measured as it consumes the file, exactly as [export]'s decode is: the search that follows
+      // reports often, but the decode ahead of it is one long blocking call and the caller's
+      // countdown has nothing else to go on until it ends.
+      val decoded = decodeUpright(source, plan.minDecodeSampleSize) { read ->
+        progress.advance(PROGRESS_AFTER_DECODE * read)
+      }
+      if (decoded == null) {
+        Log.w(TAG, "Could not decode ${source.absolutePath} for compression")
+        return CompressOutcome.Failed
+      }
+      working = decoded
+      // Same rule as [export]: flatten onto white OURSELVES rather than letting a JPEG encoder
+      // drop the alpha channel, which composites onto black.
+      if (needsOpaqueSource(format) && decoded.hasAlpha()) {
+        val flattened = flattenOntoWhite(decoded)
+        if (flattened !== decoded) {
+          runCatching { decoded.recycle() }
+          working = flattened
+        }
+      }
+      // Profile pre-cap on the longest edge, applied ONCE before the search so no probe ever
+      // encodes more pixels than the profile allows. Scaling both axes by the same factor keeps the
+      // aspect ratio exact; 0 = no cap (RECOMMENDED/MAXIMUM_QUALITY on a capable device), which
+      // leaves the picture at its decoded size and reproduces the pre-profile behaviour.
+      working?.let { current ->
+        val longest = maxOf(current.width, current.height)
+        if (plan.maxDimension > 0 && longest > plan.maxDimension) {
+          val capped = scaleBitmap(current, plan.maxDimension.toFloat() / longest)
+          if (capped != null && capped !== current) {
+            runCatching { current.recycle() }
+            working = capped
+          }
+        }
+      }
+      val bitmap = working ?: return CompressOutcome.Failed
+      // The decode (and any flatten) is done: the one cost every compression pays, whatever the
+      // search goes on to do.
+      progress.report(PROGRESS_AFTER_DECODE)
+
+      // The best candidate at or under the target (highest quality that fits) and, separately, the
+      // smallest candidate seen anywhere — the latter is the fallback when the target is simply
+      // out of reach, and the yardstick for "is this even worth writing".
+      var underTarget: ByteArray? = null
+      var smallest: ByteArray? = null
+
+      for ((stepIndex, scale) in plan.scaleSteps.withIndex()) {
+        // This step's slice of the progress range: it starts where the previous step ended and
+        // runs to its own bound, so a search that walks into a downscaled step keeps moving
+        // forward instead of restarting its count.
+        // getOrElse, not indexing: the bounds array is a fixed length and the profile's scale
+        // ladder can be shorter OR longer, so a profile must not be able to crash a compression
+        // over its progress bar.
+        val stepStart = PROGRESS_SCALE_STEP_BOUNDS.getOrElse(stepIndex - 1) { PROGRESS_AFTER_DECODE }
+        val stepEnd = PROGRESS_SCALE_STEP_BOUNDS.getOrElse(stepIndex) { PROGRESS_BEFORE_WRITE }
+        val frame = scaleBitmap(bitmap, scale) ?: continue
+        try {
+          // The quality search band comes from the profile: MAXIMUM_QUALITY holds a near-lossless
+          // floor, HIGH_COMPRESSION opens the band right down. Coerced so a floor above the ceiling
+          // (or out of 1..100) can never make the loop spin.
+          var low = plan.qualityFloor.coerceIn(1, 100)
+          var high = plan.qualityCeiling.coerceIn(low, 100)
+          // Full-size step: seed at the video side's mapping, which is the right answer for a
+          // typical photo. A downscaled step is only ever reached because no quality at full size
+          // was small enough, so it seeds at the FLOOR instead — if even that overshoots the probe
+          // loop exits after one encode and moves on, and if it fits the search spends its
+          // remaining probes climbing back toward quality, which is the same work either way.
+          var quality = if (scale >= 1f) (100 - shave).coerceIn(low, high) else low
+          var probes = 0
+          while (probes < MAX_QUALITY_PROBES && low <= high) {
+            probes++
+            val encoded = encodeToBytes(frame, compressFormat, quality) ?: break
+            // One probe of this step's budget is spent — reported AFTER the encode, so the
+            // fraction only ever describes work that has actually been done.
+            progress.report(
+              stepStart + (stepEnd - stepStart) * (probes.toFloat() / MAX_QUALITY_PROBES)
+            )
+            if (smallest == null || encoded.size < smallest!!.size) smallest = encoded
+            if (encoded.size <= targetBytes) {
+              // It fits — keep it and spend the remaining probes buying quality back.
+              if (underTarget == null || encoded.size > underTarget!!.size) underTarget = encoded
+              low = quality + 1
+            } else {
+              high = quality - 1
+            }
+            if (low > high) break
+            quality = (low + high) / 2
+          }
+        } finally {
+          if (frame !== bitmap) runCatching { frame.recycle() }
+        }
+        if (underTarget != null) break
+      }
+
+      // Accept the closest thing to the request that is still a real saving. Falling back to
+      // `smallest` mirrors the video side, which also only approximates its target and reports the
+      // saving it actually achieved — but never at the cost of handing back a bigger file.
+      val chosen = underTarget ?: smallest?.takeIf { it.size < sourceBytes }
+      if (chosen == null) {
+        Log.i(TAG, "No encode of ${source.name} came out smaller than its $sourceBytes bytes")
+        return CompressOutcome.AlreadyMinimal
+      }
+
+      // The search is over and a winner is in hand; all that is left is disk work.
+      progress.report(PROGRESS_BEFORE_WRITE)
+      output.parentFile?.mkdirs()
+      FileOutputStream(output).use { it.write(chosen) }
+      // Same read-back check [export] performs: an encoder can report success and still leave a
+      // container no decoder will open, which the preview would render as a blank frame.
+      val dimensions = readImageBounds(output)
+      if (dimensions == null) {
+        Log.w(TAG, "Compressed ${output.name} cannot be decoded back; discarding")
+        runCatching { output.delete() }
+        return CompressOutcome.Failed
+      }
+      copyMetadata(source, output, format)
+      CompressOutcome.Success(
+        width = dimensions.first,
+        height = dimensions.second,
+        // Read after copyMetadata: writing EXIF changes the length, and the caller quotes this
+        // figure to the user as the size of the file it is about to send.
+        bytes = output.length(),
+        format = format
+      )
+    } catch (e: OutOfMemoryError) {
+      Log.e(TAG, "Out of memory compressing ${source.name}", e)
+      runCatching { output.delete() }
+      CompressOutcome.Failed
+    } catch (e: Exception) {
+      Log.e(TAG, "Failed to compress ${source.name}", e)
+      runCatching { output.delete() }
+      CompressOutcome.Failed
+    } finally {
+      runCatching { working?.recycle() }
+      // Every way out of this function is the end of the work — success, "already minimal", a
+      // decode that never got started, an OOM. Reporting the terminal 1.0 from here rather than
+      // from the success path is what guarantees a caller's overlay is never left waiting on a
+      // completion that a failure quietly swallowed.
+      progress.report(1f)
+    }
+  }
+
+  /**
+   * The band of output sizes a compression at [percent] is expected to land in — what a "Compress
+   * Image" row quotes ("1.8 – 2.1 MB") — or null when [sourceBytes] is unknown (0), which drops
+   * the size from the row rather than inventing one.
+   *
+   * The still counterpart of [VideoRotationTranscoder.estimateCompressedByteRange], and it follows
+   * the encoder for the same reason: the number a row quotes has to be the number the search is
+   * aiming at, not a second calculation that can drift from it. [compress] computes exactly
+   * `sourceBytes × (1 - percent/100)` as its target and keeps the highest quality at or under it, so
+   *
+   *  - [high] and [expected] are that target CEILING, reproduced with the identical clamp and
+   *    integer arithmetic [compress] uses ([percent] pinned to 1..95). The search cannot exceed it,
+   *    so it is the honest top of the band.
+   *  - [low] is the ceiling scaled by [ESTIMATE_SIZE_UNDERSHOOT] — how far under the ceiling the
+   *    output routinely lands (quality quantisation, a profile pre-cap, or a fallback to the
+   *    smallest candidate when the target is out of reach).
+   *
+   * Every field is derived from the ACTUAL measured [sourceBytes] and the requested level; nothing
+   * here is a fixed or arbitrary size.
+   */
+  fun estimateCompressedByteRange(sourceBytes: Long, percent: Int): CompressedSizeEstimate? {
+    if (sourceBytes <= 0L) return null
+    // The exact clamp and arithmetic of [compress]'s own target, so the quoted ceiling is the
+    // number the search is aiming at.
+    val shave = percent.coerceIn(1, 95)
+    val ceiling = (sourceBytes * (100L - shave) / 100L).coerceAtLeast(1L)
+    val low = Math.round(ceiling * ESTIMATE_SIZE_UNDERSHOOT).coerceIn(1L, ceiling)
+    return CompressedSizeEstimate(low = low, expected = ceiling, high = ceiling)
+  }
+
+  /**
+   * A predicted output-size band: [low]..[high] around the most likely [expected], mirroring
+   * [VideoRotationTranscoder.CompressedSizeEstimate] so both menus quote the same shape.
+   */
+  data class CompressedSizeEstimate(val low: Long, val expected: Long, val high: Long)
+
+  /**
+   * [bitmap] scaled by [scale], or the input itself when no scaling is called for. Returns null
+   * only if the allocation failed, which the caller treats as "skip this step".
+   */
+  private fun scaleBitmap(bitmap: Bitmap, scale: Float): Bitmap? {
+    if (scale >= 1f) return bitmap
+    val width = (bitmap.width * scale).toInt().coerceAtLeast(1)
+    val height = (bitmap.height * scale).toInt().coerceAtLeast(1)
+    if (width >= bitmap.width && height >= bitmap.height) return bitmap
+    return runCatching { Bitmap.createScaledBitmap(bitmap, width, height, true) }.getOrNull()
+  }
+
+  /**
+   * Encode [bitmap] to memory so the size can be measured without touching the disk. Only the
+   * winning candidate is ever written to a file.
+   */
+  private fun encodeToBytes(
+    bitmap: Bitmap,
+    format: Bitmap.CompressFormat,
+    quality: Int
+  ): ByteArray? = runCatching {
+    val stream = ByteArrayOutputStream()
+    if (bitmap.compress(format, quality.coerceIn(1, 100), stream)) stream.toByteArray() else null
+  }.getOrElse {
+    Log.w(TAG, "Bitmap.compress to $format at quality $quality failed", it)
+    null
+  }
+
+  /**
+   * The pixel dimensions of [file], or null when nothing on this device can decode it.
+   *
+   * The still-image counterpart of MediaPreviewEditor.hasReadableVideoSamples. Only the bounds
+   * are read (no pixel allocation), which is both the cheapest way to tell a real image from a
+   * shell and the authoritative source for an export's dimensions.
+   */
+  private fun readImageBounds(file: File): Pair<Int, Int>? {
+    if (!file.exists() || file.length() <= 0L) return null
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    runCatching { BitmapFactory.decodeFile(file.absolutePath, bounds) }
+    if (bounds.outWidth > 0 && bounds.outHeight > 0) {
+      return Pair(bounds.outWidth, bounds.outHeight)
+    }
+    // BitmapFactory declines some HEIF/AVIF variants that ImageDecoder handles, so its "no" is
+    // not yet a verdict.
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) return null
+    var size: Pair<Int, Int>? = null
+    runCatching {
+      ImageDecoder.decodeDrawable(ImageDecoder.createSource(file)) { decoder, info, _ ->
+        if (info.size.width > 0 && info.size.height > 0) {
+          size = Pair(info.size.width, info.size.height)
+        }
+        // Nothing is displayed, so keep the probe from allocating the full image.
+        decoder.setTargetSize(1, 1)
+      }
+    }
+    // Deliberately read outside the runCatching result: the header having decoded is the answer,
+    // even if the 1x1 downscale that follows it is refused by a particular decoder.
+    return size
+  }
+
+  // ---------------------------------------------------------------------------------------
+  // Decode
+  // ---------------------------------------------------------------------------------------
+
+  /**
+   * Decode [source] at full resolution with its EXIF rotation applied to the PIXELS.
+   *
+   * Baking the rotation is what makes the export orientation-correct in every target container:
+   * only JPEG carries an EXIF orientation tag consumers reliably honour, so an exported PNG or
+   * HEIF of a rotated capture would otherwise display sideways. With the rotation in the pixels,
+   * the output's stored dimensions ARE its display dimensions and nothing can double-rotate it.
+   *
+   * On [OutOfMemoryError] the decode is retried at successively coarser subsamples rather than
+   * failing outright — a halved image is a far better export than none.
+   *
+   * @param minSample the inSampleSize the decode STARTS at (a power-of-two floor). 1 is the
+   *   historical full-resolution decode; a low-RAM profile passes 2 so a very large photo is halved
+   *   on each edge before it ever lands on the heap, which is the difference between a re-encode and
+   *   an OOM on a small device. The OOM retry ladder still doubles from here.
+   * @param onBytesRead how much of the source the decoder has consumed, 0.0..1.0, called on THIS
+   *   thread as it reads. `BitmapFactory` exposes no progress of its own, so the file is handed to
+   *   it through a [CountingInputStream] — which is all `BitmapFactory.decodeFile` does anyway,
+   *   minus the counting. A subsample retry rewinds to the start of the file, so the fraction can
+   *   repeat; callers pass it into a monotonic emitter, which absorbs that.
+   */
+  private fun decodeUpright(
+    source: File,
+    minSample: Int = 1,
+    onBytesRead: ((Float) -> Unit)? = null
+  ): Bitmap? {
+    var sample = minSample.coerceAtLeast(1)
+    val totalBytes = source.length()
+    while (sample <= 8) {
+      try {
+        val options = BitmapFactory.Options().apply {
+          inSampleSize = sample
+          inPreferredConfig = Bitmap.Config.ARGB_8888
+        }
+        val decoded = FileInputStream(source).use { stream ->
+          val input: InputStream =
+            if (onBytesRead != null && totalBytes > 0L) {
+              CountingInputStream(stream, totalBytes, onBytesRead)
+            } else {
+              stream
+            }
+          BitmapFactory.decodeStream(input, null, options)
+        }
+        // BitmapFactory returning nothing means the container is one it declines (some HEIF and
+        // AVIF variants); ImageDecoder handles those AND applies their orientation itself, which
+        // is why applyExifOrientation must not be run on its output.
+        return if (decoded != null) applyExifOrientation(source, decoded) else decodeViaImageDecoder(source)
+      } catch (e: OutOfMemoryError) {
+        Log.w(TAG, "Out of memory decoding ${source.name} at sample $sample; retrying coarser", e)
+        sample *= 2
+      } catch (e: IOException) {
+        // Same verdict BitmapFactory.decodeFile reaches for an unreadable file: no bitmap.
+        Log.w(TAG, "Could not read ${source.name} for decoding", e)
+        return null
+      }
+    }
+    return null
+  }
+
+  private fun decodeViaImageDecoder(source: File): Bitmap? {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) return null
+    return runCatching {
+      ImageDecoder.decodeBitmap(ImageDecoder.createSource(source)) { decoder, _, _ ->
+        // Software config: the pixels are read back below, which a hardware bitmap forbids.
+        decoder.allocator = ImageDecoder.ALLOCATOR_SOFTWARE
+        decoder.isMutableRequired = false
+      }
+    }.getOrNull()
+  }
+
+  /**
+   * Rotate/flip [bitmap] according to [source]'s EXIF orientation tag, returning the upright
+   * image. Returns the input unchanged when the tag is absent or already normal.
+   */
+  private fun applyExifOrientation(source: File, bitmap: Bitmap): Bitmap {
+    val orientation = runCatching {
+      ExifInterface(source.absolutePath)
+        .getAttributeInt(ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL)
+    }.getOrDefault(ExifInterface.ORIENTATION_NORMAL)
+
+    val matrix = Matrix()
+    when (orientation) {
+      ExifInterface.ORIENTATION_ROTATE_90 -> matrix.postRotate(90f)
+      ExifInterface.ORIENTATION_ROTATE_180 -> matrix.postRotate(180f)
+      ExifInterface.ORIENTATION_ROTATE_270 -> matrix.postRotate(270f)
+      ExifInterface.ORIENTATION_FLIP_HORIZONTAL -> matrix.postScale(-1f, 1f)
+      ExifInterface.ORIENTATION_FLIP_VERTICAL -> matrix.postScale(1f, -1f)
+      ExifInterface.ORIENTATION_TRANSPOSE -> {
+        matrix.postRotate(90f)
+        matrix.postScale(-1f, 1f)
+      }
+      ExifInterface.ORIENTATION_TRANSVERSE -> {
+        matrix.postRotate(270f)
+        matrix.postScale(-1f, 1f)
+      }
+      else -> return bitmap
+    }
+    return runCatching {
+      val rotated = Bitmap.createBitmap(bitmap, 0, 0, bitmap.width, bitmap.height, matrix, true)
+      if (rotated !== bitmap) bitmap.recycle()
+      rotated
+    }.getOrDefault(bitmap)
+  }
+
+  // ---------------------------------------------------------------------------------------
+  // Encode
+  // ---------------------------------------------------------------------------------------
+
+  /** Containers with no alpha channel, whose sources must be flattened before encoding. */
+  private fun needsOpaqueSource(format: ImageFormatSupport.Format): Boolean = when (format) {
+    ImageFormatSupport.Format.JPEG,
+    // The still-image encoder path below is 4:2:0 YUV, which has nowhere to put an alpha channel.
+    ImageFormatSupport.Format.HEIF,
+    ImageFormatSupport.Format.AVIF -> true
+    else -> false
+  }
+
+  private fun flattenOntoWhite(bitmap: Bitmap): Bitmap = runCatching {
+    val flat = Bitmap.createBitmap(bitmap.width, bitmap.height, Bitmap.Config.ARGB_8888)
+    Canvas(flat).apply {
+      drawColor(Color.WHITE)
+      drawBitmap(bitmap, 0f, 0f, null)
+    }
+    flat
+  }.getOrDefault(bitmap)
+
+  /** `WEBP_LOSSY` from API 30, the (deprecated, behaviourally identical) `WEBP` below it. */
+  @Suppress("DEPRECATION")
+  private fun webpFormat(): Bitmap.CompressFormat =
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+      Bitmap.CompressFormat.WEBP_LOSSY
+    } else {
+      Bitmap.CompressFormat.WEBP
+    }
+
+  /**
+   * @param onBytesWritten running total of bytes the encoder has written, called on THIS thread as
+   *   it writes. `Bitmap.compress` reports nothing about its own progress, but it writes its output
+   *   as it produces it, so the stream underneath is where a multi-second encode becomes visible.
+   */
+  private fun compressBitmap(
+    bitmap: Bitmap,
+    format: Bitmap.CompressFormat,
+    quality: Int,
+    output: File,
+    onBytesWritten: ((Long) -> Unit)? = null
+  ): Boolean = runCatching {
+    output.parentFile?.mkdirs()
+    FileOutputStream(output).use { file ->
+      val stream: OutputStream =
+        if (onBytesWritten != null) CountingOutputStream(file, onBytesWritten) else file
+      bitmap.compress(format, quality.coerceIn(1, 100), stream)
+    }
+  }.getOrElse {
+    Log.e(TAG, "Bitmap.compress to $format failed", it)
+    false
+  }
+
+  /** @param onBytesWritten as [compressBitmap]'s — `PdfDocument.writeTo` streams its output too. */
+  private fun exportPdf(
+    bitmap: Bitmap,
+    output: File,
+    onBytesWritten: ((Long) -> Unit)? = null
+  ): Boolean = runCatching {
+    output.parentFile?.mkdirs()
+    val document = android.graphics.pdf.PdfDocument()
+    val pageInfo = android.graphics.pdf.PdfDocument.PageInfo.Builder(bitmap.width, bitmap.height, 1).create()
+    val page = document.startPage(pageInfo)
+    page.canvas.drawBitmap(bitmap, 0f, 0f, null)
+    document.finishPage(page)
+    FileOutputStream(output).use { file ->
+      val stream: OutputStream =
+        if (onBytesWritten != null) CountingOutputStream(file, onBytesWritten) else file
+      document.writeTo(stream)
+      stream.flush()
+    }
+    document.close()
+    true
+  }.getOrElse {
+    Log.e(TAG, "Export to PDF failed", it)
+    false
+  }
+
+  /**
+   * Encode [bitmap] as a single still through the platform's dedicated image encoder for
+   * [mimeType] and write it with the HEIF muxer.
+   *
+   * This is the only way to produce HEIF/AVIF on Android — `Bitmap.CompressFormat` has no entry
+   * for either. The encoder is fed one frame in a flexible YUV 4:2:0 input buffer obtained via
+   * [MediaCodec.getInputImage], so the plane strides come from the codec rather than being
+   * guessed, and every output buffer it produces is written to the muxer: HEIC encoders may emit
+   * an image as several tiles and the muxer assembles them from the grid information carried in
+   * the output format.
+   *
+   * Dimensions are rounded DOWN to even numbers because 4:2:0 chroma subsampling cannot
+   * represent a trailing odd row or column. That costs at most one pixel on each axis and keeps
+   * the aspect ratio within a pixel; padding instead would add a visible border.
+   *
+   * @param onProgress how far through THIS encode the pass is, 0.0..1.0, called on this thread.
+   *   The RGB→YUV conversion of every pixel happens in process ([writeYuv420]) and is the bulk of
+   *   the wait on a large still, so it is reported row by row rather than as a single step; the
+   *   codec's own draining is reported per muxed sample, since a HEIC encoder may emit an image as
+   *   several tiles and there is no way to know in advance how many.
+   * @return true only when at least one sample reached the muxer, so a codec that starts and
+   *   produces nothing is reported as a failure rather than leaving an empty container behind.
+   */
+  private fun encodeStillViaCodec(
+    bitmap: Bitmap,
+    mimeType: String,
+    quality: Int,
+    output: File,
+    onProgress: ((Float) -> Unit)? = null
+  ): Boolean {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) return false
+    val width = bitmap.width - (bitmap.width % 2)
+    val height = bitmap.height - (bitmap.height % 2)
+    if (width < 2 || height < 2) {
+      Log.w(TAG, "Image too small to encode as $mimeType (${bitmap.width}x${bitmap.height})")
+      return false
+    }
+
+    var codec: MediaCodec? = null
+    var muxer: MediaMuxer? = null
+    var muxerStarted = false
+    var wroteSample = false
+    var muxedSamples = 0
+    try {
+      val format = MediaFormat.createVideoFormat(mimeType, width, height).apply {
+        setInteger(
+          MediaFormat.KEY_COLOR_FORMAT,
+          MediaCodecInfo.CodecCapabilities.COLOR_FormatYUV420Flexible
+        )
+        // Still-image encoders are driven by quality, not bit rate. A frame rate and a zero
+        // key-frame interval are set anyway because some encoders reject a video-shaped format
+        // that omits them.
+        setInteger(MediaFormat.KEY_QUALITY, quality.coerceIn(1, 100))
+        setInteger(MediaFormat.KEY_FRAME_RATE, 1)
+        setInteger(MediaFormat.KEY_I_FRAME_INTERVAL, 0)
+      }
+
+      output.parentFile?.mkdirs()
+      codec = MediaCodec.createEncoderByType(mimeType)
+      codec.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+      codec.start()
+      onProgress?.invoke(PROGRESS_CODEC_STARTED)
+
+      muxer = MediaMuxer(output.absolutePath, MediaMuxer.OutputFormat.MUXER_OUTPUT_HEIF)
+      // The pixels are already upright (see decodeUpright), so the container must advertise no
+      // rotation or every viewer would rotate the image a second time. Best-effort: not every
+      // writer accepts the hint, and refusing it is not a reason to fail an otherwise good file.
+      runCatching { muxer.setOrientationHint(0) }
+
+      val yuvSpan = PROGRESS_CODEC_FRAME_QUEUED - PROGRESS_CODEC_STARTED
+      val queued = queueSingleFrame(codec, bitmap, width, height) { rows ->
+        onProgress?.invoke(PROGRESS_CODEC_STARTED + yuvSpan * rows)
+      }
+      if (!queued) return false
+      onProgress?.invoke(PROGRESS_CODEC_FRAME_QUEUED)
+
+      val info = MediaCodec.BufferInfo()
+      var trackIndex = -1
+      val deadline = System.nanoTime() + ENCODE_TIMEOUT_NS
+      var idlePolls = 0
+      var draining = true
+      while (draining) {
+        if (System.nanoTime() > deadline) {
+          Log.w(TAG, "Timed out encoding $mimeType still")
+          return false
+        }
+        val outIndex = codec.dequeueOutputBuffer(info, DEQUEUE_TIMEOUT_US)
+        if (outIndex == MediaCodec.INFO_TRY_AGAIN_LATER) {
+          // Image encoders do not always raise END_OF_STREAM after their last tile, so a run of
+          // idle polls AFTER real output has been written is treated as "finished". Without it
+          // every successful export would spin until the deadline.
+          idlePolls++
+          if (wroteSample && idlePolls > MAX_IDLE_POLLS_AFTER_OUTPUT) draining = false
+        } else if (outIndex == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED) {
+          if (muxerStarted) throw IllegalStateException("Encoder format changed twice")
+          trackIndex = muxer.addTrack(codec.outputFormat)
+          muxer.start()
+          muxerStarted = true
+        } else if (outIndex >= 0) {
+          idlePolls = 0
+          val encoded = codec.getOutputBuffer(outIndex)
+          if (info.flags and MediaCodec.BUFFER_FLAG_CODEC_CONFIG != 0) {
+            // Codec config is folded into the track format by the muxer; drop the buffer.
+            info.size = 0
+          }
+          if (info.size > 0 && encoded != null) {
+            if (!muxerStarted) throw IllegalStateException("Muxer not started before data")
+            encoded.position(info.offset)
+            encoded.limit(info.offset + info.size)
+            muxer.writeSampleData(trackIndex, encoded, info)
+            wroteSample = true
+            muxedSamples++
+            // How many tiles this encoder will emit is not knowable in advance, so each one moves
+            // the fraction a fixed step toward — never past — the end of this phase.
+            onProgress?.invoke(
+              minOf(
+                PROGRESS_CODEC_MEASURED_CEILING,
+                PROGRESS_CODEC_FRAME_QUEUED + PROGRESS_CODEC_PER_SAMPLE * muxedSamples
+              )
+            )
+          }
+          codec.releaseOutputBuffer(outIndex, false)
+          if (info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM != 0) draining = false
+        }
+      }
+      return wroteSample
+    } catch (e: Exception) {
+      Log.e(TAG, "Still encode to $mimeType failed", e)
+      return false
+    } finally {
+      try { codec?.stop() } catch (_: Exception) {}
+      try { codec?.release() } catch (_: Exception) {}
+      // stop() on a muxer that was never started throws; release() alone is the correct teardown.
+      if (muxerStarted) {
+        try { muxer?.stop() } catch (_: Exception) {}
+      }
+      try { muxer?.release() } catch (_: Exception) {}
+    }
+  }
+
+  /**
+   * Hand the encoder its one and only frame, flagged as the end of the stream.
+   *
+   * @param onRowsWritten how much of the frame has been converted into the codec's buffer,
+   *   0.0..1.0, called on this thread as the rows are written.
+   */
+  private fun queueSingleFrame(
+    codec: MediaCodec,
+    bitmap: Bitmap,
+    width: Int,
+    height: Int,
+    onRowsWritten: ((Float) -> Unit)? = null
+  ): Boolean {
+    val deadline = System.nanoTime() + ENCODE_TIMEOUT_NS
+    while (System.nanoTime() < deadline) {
+      val index = codec.dequeueInputBuffer(DEQUEUE_TIMEOUT_US)
+      if (index < 0) continue
+      val image = codec.getInputImage(index)
+      if (image == null) {
+        Log.w(TAG, "Encoder did not expose a flexible YUV input image")
+        return false
+      }
+      writeYuv420(image, bitmap, width, height, onRowsWritten)
+      codec.queueInputBuffer(
+        index,
+        0,
+        width * height * 3 / 2,
+        0L,
+        MediaCodec.BUFFER_FLAG_END_OF_STREAM
+      )
+      return true
+    }
+    Log.w(TAG, "Timed out waiting for an encoder input buffer")
+    return false
+  }
+
+  /**
+   * Convert [bitmap] to YUV 4:2:0 straight into the codec's [image] planes.
+   *
+   * The plane layout is READ from the codec (`rowStride` / `pixelStride`) rather than assumed, so
+   * this writes correctly into both planar (I420) and semi-planar (NV12/NV21) buffers — the two
+   * layouts hide behind `COLOR_FormatYUV420Flexible` and differ per device.
+   *
+   * Rows are converted two at a time so one 2x2 chroma block completes per iteration, which keeps
+   * peak memory at two rows of pixels rather than a second copy of the whole image. The
+   * coefficients are the standard limited-range BT.601 set (luma 16..235, chroma centred on 128),
+   * which is what video and image encoders expect by default; full-range values here would come
+   * back visibly washed out.
+   *
+   * @param onRowsWritten how much of the frame has been converted, 0.0..1.0, called once per row
+   *   pair. This loop touches every pixel in process and is the single most expensive step of a
+   *   HEIF/AVIF export, so it is where that wait has to become visible; the callback is throttled
+   *   by the emitter behind it, not here.
+   */
+  private fun writeYuv420(
+    image: Image,
+    bitmap: Bitmap,
+    width: Int,
+    height: Int,
+    onRowsWritten: ((Float) -> Unit)? = null
+  ) {
+    val w = minOf(width, image.width)
+    val h = minOf(height, image.height)
+
+    val yPlane = image.planes[0]
+    val uPlane = image.planes[1]
+    val vPlane = image.planes[2]
+    val yBuffer = yPlane.buffer
+    val uBuffer = uPlane.buffer
+    val vBuffer = vPlane.buffer
+    // Absolute puts ignore the buffer position, so a plane that starts partway into a shared
+    // allocation needs its origin added explicitly.
+    val yBase = yBuffer.position()
+    val uBase = uBuffer.position()
+    val vBase = vBuffer.position()
+    val yRowStride = yPlane.rowStride
+    val yPixelStride = yPlane.pixelStride
+    val uRowStride = uPlane.rowStride
+    val uPixelStride = uPlane.pixelStride
+    val vRowStride = vPlane.rowStride
+    val vPixelStride = vPlane.pixelStride
+
+    val top = IntArray(w)
+    val bottom = IntArray(w)
+
+    var y = 0
+    while (y + 1 < h) {
+      bitmap.getPixels(top, 0, w, 0, y, w, 1)
+      bitmap.getPixels(bottom, 0, w, 0, y + 1, w, 1)
+
+      var x = 0
+      while (x + 1 < w) {
+        var sumR = 0
+        var sumG = 0
+        var sumB = 0
+        for (dy in 0..1) {
+          val row = if (dy == 0) top else bottom
+          for (dx in 0..1) {
+            val pixel = row[x + dx]
+            val r = (pixel shr 16) and 0xFF
+            val g = (pixel shr 8) and 0xFF
+            val b = pixel and 0xFF
+            sumR += r
+            sumG += g
+            sumB += b
+            val luma = ((66 * r + 129 * g + 25 * b + 128) shr 8) + 16
+            yBuffer.put(
+              yBase + (y + dy) * yRowStride + (x + dx) * yPixelStride,
+              luma.coerceIn(16, 235).toByte()
+            )
+          }
+        }
+        val avgR = sumR / 4
+        val avgG = sumG / 4
+        val avgB = sumB / 4
+        val cb = ((-38 * avgR - 74 * avgG + 112 * avgB + 128) shr 8) + 128
+        val cr = ((112 * avgR - 94 * avgG - 18 * avgB + 128) shr 8) + 128
+        val chromaRow = y / 2
+        val chromaCol = x / 2
+        uBuffer.put(
+          uBase + chromaRow * uRowStride + chromaCol * uPixelStride,
+          cb.coerceIn(16, 240).toByte()
+        )
+        vBuffer.put(
+          vBase + chromaRow * vRowStride + chromaCol * vPixelStride,
+          cr.coerceIn(16, 240).toByte()
+        )
+        x += 2
+      }
+      y += 2
+      if (onRowsWritten != null && h > 0) onRowsWritten((y.toFloat() / h).coerceIn(0f, 1f))
+    }
+  }
+
+  // ---------------------------------------------------------------------------------------
+  // Metadata
+  // ---------------------------------------------------------------------------------------
+
+  /**
+   * The EXIF tags carried from the original to the export: when and where the photo was taken,
+   * what took it, and how. Deliberately a curated list rather than a blind copy — thumbnail and
+   * layout tags describe the ORIGINAL bytes and would be wrong on a re-encoded file.
+   */
+  private val CARRIED_EXIF_TAGS = arrayOf(
+    ExifInterface.TAG_DATETIME,
+    ExifInterface.TAG_DATETIME_ORIGINAL,
+    ExifInterface.TAG_DATETIME_DIGITIZED,
+    ExifInterface.TAG_SUBSEC_TIME,
+    ExifInterface.TAG_MAKE,
+    ExifInterface.TAG_MODEL,
+    ExifInterface.TAG_F_NUMBER,
+    ExifInterface.TAG_EXPOSURE_TIME,
+    ExifInterface.TAG_FOCAL_LENGTH,
+    ExifInterface.TAG_WHITE_BALANCE,
+    ExifInterface.TAG_FLASH,
+    ExifInterface.TAG_GPS_LATITUDE,
+    ExifInterface.TAG_GPS_LATITUDE_REF,
+    ExifInterface.TAG_GPS_LONGITUDE,
+    ExifInterface.TAG_GPS_LONGITUDE_REF,
+    ExifInterface.TAG_GPS_ALTITUDE,
+    ExifInterface.TAG_GPS_ALTITUDE_REF,
+    ExifInterface.TAG_GPS_TIMESTAMP,
+    ExifInterface.TAG_GPS_DATESTAMP
+  )
+
+  /**
+   * Copy the carried EXIF tags from [source] onto [output].
+   *
+   * Only attempted for containers the platform's [ExifInterface] can WRITE: JPEG on every
+   * supported level, PNG and WebP from API 30. HEIF/AVIF are skipped — their orientation is
+   * already handled by the muxer's zero rotation hint and there is no supported write path for
+   * their metadata here. Best-effort throughout: an export is not failed because a tag would not
+   * stick.
+   */
+  private fun copyMetadata(source: File, output: File, format: ImageFormatSupport.Format) {
+    val writable = when (format) {
+      ImageFormatSupport.Format.JPEG -> true
+      ImageFormatSupport.Format.PNG,
+      ImageFormatSupport.Format.WEBP -> Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
+      else -> false
+    }
+    if (!writable) return
+    runCatching {
+      val from = ExifInterface(source.absolutePath)
+      val to = ExifInterface(output.absolutePath)
+      for (tag in CARRIED_EXIF_TAGS) {
+        from.getAttribute(tag)?.let { to.setAttribute(tag, it) }
+      }
+      // The rotation is baked into the exported pixels, so the tag must say "upright". Leaving
+      // the source's value would rotate the already-rotated image a second time.
+      to.setAttribute(
+        ExifInterface.TAG_ORIENTATION,
+        ExifInterface.ORIENTATION_NORMAL.toString()
+      )
+      to.saveAttributes()
+    }.onFailure {
+      Log.w(TAG, "Could not carry EXIF onto ${output.name}", it)
+    }
+  }
+
+  // ---------------------------------------------------------------------------------------
+  // Progress plumbing
+  // ---------------------------------------------------------------------------------------
+
+  /**
+   * Guards the progress contract [export] and [compress] publish: values are monotonic, clamped to
+   * 0..1, and throttled so a per-row or per-buffer callback cannot flood the caller's thread.
+   *
+   * The throttle is deliberately the same pair the video transcode uses
+   * ([PROGRESS_MIN_INTERVAL_MS] / [PROGRESS_MIN_DELTA]), so a still and a clip drive the same
+   * countdown at the same cadence.
+   *
+   * Confined to the worker thread the encode runs on; it is not synchronised.
+   */
+  private class ProgressEmitter(private val sink: ((Float) -> Unit)?) {
+    private var last = -1f
+    private var lastAtMs = 0L
+
+    /**
+     * A measured value from inside a phase. Dropped when it would move the fraction backwards (a
+     * subsample retry re-reads the file from the start) or when it is too soon and too small a
+     * step to be worth a callback.
+     */
+    fun advance(fraction: Float) {
+      val out = sink ?: return
+      val clamped = fraction.coerceIn(0f, 1f)
+      if (clamped <= last) return
+      val now = SystemClock.elapsedRealtime()
+      if (clamped - last < PROGRESS_MIN_DELTA && now - lastAtMs < PROGRESS_MIN_INTERVAL_MS) return
+      last = clamped
+      lastAtMs = now
+      out(clamped)
+    }
+
+    /**
+     * A phase boundary: reported immediately, whatever the throttle would have said. These are the
+     * values a caller's overlay reacts to (the tail hand-over, the terminal 1.0), so they must not
+     * be able to fall inside a throttle window and be lost.
+     */
+    fun report(fraction: Float) {
+      val out = sink ?: return
+      val clamped = fraction.coerceIn(0f, 1f)
+      if (clamped < last) return
+      last = clamped
+      lastAtMs = SystemClock.elapsedRealtime()
+      out(clamped)
+    }
+  }
+
+  /**
+   * Reports how much of a [total]-byte source has been read, as [delegate] is consumed.
+   *
+   * This is how a `BitmapFactory` decode — a single blocking call with no progress of its own —
+   * becomes measurable. `BitmapFactory.decodeFile` is exactly `decodeStream` over a
+   * `FileInputStream`, so wrapping that stream changes nothing about the decode itself. Mark and
+   * reset are deliberately NOT supported (the default), which is also true of the plain
+   * `FileInputStream` the decoder would otherwise be handed.
+   */
+  private class CountingInputStream(
+    private val delegate: InputStream,
+    private val total: Long,
+    private val onRead: (Float) -> Unit
+  ) : InputStream() {
+    private var read = 0L
+
+    override fun read(): Int {
+      val value = delegate.read()
+      if (value >= 0) advance(1L)
+      return value
+    }
+
+    override fun read(b: ByteArray, off: Int, len: Int): Int {
+      val count = delegate.read(b, off, len)
+      if (count > 0) advance(count.toLong())
+      return count
+    }
+
+    override fun skip(n: Long): Long {
+      val skipped = delegate.skip(n)
+      if (skipped > 0L) advance(skipped)
+      return skipped
+    }
+
+    override fun available(): Int = delegate.available()
+
+    override fun close() = delegate.close()
+
+    private fun advance(count: Long) {
+      read += count
+      if (total > 0L) onRead((read.toDouble() / total.toDouble()).toFloat().coerceIn(0f, 1f))
+    }
+  }
+
+  /**
+   * Reports the running total of bytes written through [delegate].
+   *
+   * The encoder counterpart of [CountingInputStream]: `Bitmap.compress` and `PdfDocument.writeTo`
+   * both stream their output as they produce it, so the bytes arriving here are the only signal
+   * either one gives about how far along it is.
+   */
+  private class CountingOutputStream(
+    private val delegate: OutputStream,
+    private val onWritten: (Long) -> Unit
+  ) : OutputStream() {
+    private var written = 0L
+
+    override fun write(b: Int) {
+      delegate.write(b)
+      advance(1L)
+    }
+
+    override fun write(b: ByteArray) {
+      delegate.write(b)
+      advance(b.size.toLong())
+    }
+
+    override fun write(b: ByteArray, off: Int, len: Int) {
+      delegate.write(b, off, len)
+      advance(len.toLong())
+    }
+
+    override fun flush() = delegate.flush()
+
+    override fun close() = delegate.close()
+
+    private fun advance(count: Long) {
+      written += count
+      onWritten(written)
+    }
+  }
+}