react-native-ensys-camera-x 1.0.7

package/src/library/compressionEstimate.ts

@@ -0,0 +1,662 @@
+// ── Compression countdown: measured remaining time, seeded by an estimate ───────────────────
+// The library shell's viewer shows a countdown ("Compressing (5s left)") instead of an
+// indeterminate spinner while the displayed image or video is being compressed. Nothing here
+// touches the compression: these are pure functions the screen calls to decide what the line
+// should read, plus the size-band arithmetic the level list quotes.
+//
+// The number is driven by the compressor's OWN progress. Native reports measured progress on the
+// `onCompressionProgress` device event as it works (VideoRotationTranscoder.compress from the
+// encoder's output timestamps, ImageExporter.compress from the encodes its quality search spends),
+// and each report re-derives how long the whole job will take from how long it has taken to reach
+// that point: `total = elapsed / fraction`. The line then reads `total - elapsed`.
+//
+// That is what makes the figure honest in BOTH directions, which counting a fixed up-front
+// estimate down cannot be:
+//   • a job slower than predicted has its total re-derived UPWARD, so the count no longer reaches
+//     zero while the encoder is still running;
+//   • a job faster than predicted has it re-derived DOWNWARD, so the count is not still promising
+//     seconds when the compressed file is already on screen.
+//
+// The line opens by counting UP to the figure — a short, evenly paced ramp that reads as the app
+// working out how long the job will take — and turns around into the countdown the moment the two
+// meet. See the calculation-ramp section further down.
+//
+// The estimate below is still computed up front, but only to seed the first seconds — before
+// there is any measurement to derive a total from — and it is blended out as soon as there is. It
+// is also the whole figure for a source that reports no progress at all (a clip whose container
+// declares no duration has no denominator), which is the one case that still ends in
+// "Finalizing...".
+//
+// Every constant here mirrors the native editor's for the same overlay (MediaPreviewEditor.kt), so
+// both surfaces behave identically for the same media.
+
+import type { CameraTranslationFunction } from '../localization';
+
+/** MB of SOURCE video demuxed + decoded + re-encoded per second. */
+export const COMPRESSION_SOURCE_MB_PER_SECOND = 1.0;
+
+/** Megapixels of decoded frame data processed per second (≈ 2 s per second of 1080p). */
+export const COMPRESSION_MEGAPIXELS_PER_SECOND = 4.0;
+
+/**
+ * Deprecated per-level discount, kept at 1 (no discount).
+ *
+ * They used to model the native transcoder downscaling the frame once the quality ratio dropped
+ * under 0.6, which made a heavy level a cheaper pass. That downscale is gone — every level now
+ * re-encodes at FULL resolution so quality is protected rather than traded away
+ * (`MediaPreviewEditor.estimateCompressionSeconds` dropped its matching discount for the same
+ * reason) — so the pass costs the same at 5% as at 95% and the factor must not shorten the seed.
+ * Left in place, and exported, because they are part of this module's public surface.
+ */
+export const COMPRESSION_DOWNSCALE_QUALITY_CEILING = 60;
+export const COMPRESSION_DOWNSCALED_LEVEL_FACTOR = 1;
+
+/**
+ * Floor: below this there is no countdown worth showing, and it doubles as the allowance for the
+ * fixed codec + muxer setup that no amount of video changes.
+ */
+export const MIN_COMPRESSION_COUNTDOWN_SECONDS = 2;
+
+/** Ceiling: a very long clip shows a bounded number and finishes in "Finalizing..." if need be. */
+export const MAX_COMPRESSION_COUNTDOWN_SECONDS = 180;
+
+/**
+ * Megapixels of STILL image compressed per second, behind {@link estimateImageCompressionSeconds}.
+ *
+ * Much lower than a plain "encode one JPEG" rate because a still compression is not one encode:
+ * the native compressor decodes once and then re-encodes several times while it searches for the
+ * quality that hits the requested size.
+ */
+export const IMAGE_COMPRESSION_MEGAPIXELS_PER_SECOND = 3.0;
+
+/** Ceiling for a still: even a 100 MP source is bounded well below the video ceiling. */
+export const MAX_IMAGE_COMPRESSION_COUNTDOWN_SECONDS = 30;
+
+/** Caption shown once there is no measurable remaining time left to quote. */
+export const COMPRESSION_FINALIZING_LABEL = 'Finalizing...';
+
+/** Caption shown when there is no countdown to display (estimate unavailable). */
+export const COMPRESSION_FALLBACK_LABEL = 'Compressing...';
+
+/**
+ * The quality percentage a dropdown option asks to KEEP (5..99), or 0 for anything that is not a
+ * level (the "Original Video" / "Original Image" entries, which never start a compression).
+ */
+export const parseCompressionPercent = (option: string): number => {
+  const match = /^\s*(\d+(?:\.\d+)?)\s*%\s*$/.exec(option);
+  if (!match) return 0;
+  const percent = Number(match[1]);
+  return Number.isFinite(percent) ? percent : 0;
+};
+
+/**
+ * Durations reach this screen in milliseconds from native metadata but in seconds from some
+ * host-supplied assets, so normalise the same way the media list does: a value large enough to be
+ * an implausible number of seconds is milliseconds.
+ */
+const durationToSeconds = (duration?: number): number => {
+  if (!duration || duration <= 0) return 0;
+  return duration > 1000 ? duration / 1000 : duration;
+};
+
+export interface VideoCompressionEstimateInput {
+  /** Size of the ORIGINAL file in bytes (never a previously compressed copy's). */
+  sizeBytes?: number;
+  /** Duration of the original, in milliseconds (seconds are accepted and normalised). */
+  duration?: number;
+  /** The original's own pixel dimensions. */
+  width?: number;
+  height?: number;
+  /** The selected level: the percentage of the original QUALITY to keep (5..99). Lower = stronger. */
+  percent: number;
+}
+
+/**
+ * How long compressing a clip is expected to take, in whole seconds — the value the countdown
+ * starts at, and only that: measured progress takes the figure over within the first second or so
+ * (see {@link foldCompressionProgress}).
+ *
+ * Two independent predictors are computed and the LARGER is taken, because either one alone is
+ * wrong for a whole class of clip:
+ *
+ *  - **Bytes.** The whole file is demuxed, decoded and re-encoded, so throughput measured in MB of
+ *    SOURCE per second is the most stable single predictor across devices. On its own it
+ *    under-predicts a long, low-bitrate clip (lots of frames, few bytes).
+ *  - **Pixels × frames.** Duration times megapixels per frame is what the codec actually has to
+ *    work on. On its own it under-predicts a short, very high-bitrate clip (few frames, huge
+ *    bytes).
+ *
+ * Every input must come from the ORIGINAL, so picking a second level after a first estimates
+ * against the untouched file rather than the shrunken copy. A clip with no readable metadata at
+ * all falls back to the floor rather than to zero.
+ */
+export const estimateVideoCompressionSeconds = ({
+  sizeBytes,
+  duration,
+  width,
+  height,
+  percent,
+}: VideoCompressionEstimateInput): number => {
+  const megabytes = sizeBytes && sizeBytes > 0 ? sizeBytes / (1024 * 1024) : 0;
+  const fromBytes =
+    megabytes > 0 ? megabytes / COMPRESSION_SOURCE_MB_PER_SECOND : 0;
+
+  const durationSeconds = durationToSeconds(duration);
+  const megapixelsPerFrame =
+    width && height && width > 0 && height > 0
+      ? (width * height) / 1_000_000
+      : 0;
+  const fromPixels =
+    durationSeconds > 0 && megapixelsPerFrame > 0
+      ? (durationSeconds * megapixelsPerFrame) / COMPRESSION_MEGAPIXELS_PER_SECOND
+      : 0;
+
+  const levelFactor =
+    percent < COMPRESSION_DOWNSCALE_QUALITY_CEILING
+      ? COMPRESSION_DOWNSCALED_LEVEL_FACTOR
+      : 1;
+  const estimate = Math.max(fromBytes, fromPixels) * levelFactor;
+
+  return Math.min(
+    MAX_COMPRESSION_COUNTDOWN_SECONDS,
+    Math.max(MIN_COMPRESSION_COUNTDOWN_SECONDS, Math.ceil(estimate))
+  );
+};
+
+export interface ImageCompressionEstimateInput {
+  /** The ORIGINAL still's own pixel dimensions. */
+  width?: number;
+  height?: number;
+}
+
+/**
+ * How long compressing a still is expected to take, in whole seconds — the seed for its countdown.
+ *
+ * A single predictor, unlike the video estimate's two: a still has no duration and no bit rate, so
+ * the only thing that varies is how many pixels there are to decode and re-encode. The requested
+ * level does not enter into it either — the native compressor searches for the quality that hits
+ * the target, so a light level costs the same handful of encodes as a heavy one.
+ *
+ * A still with no readable dimensions falls back to the floor rather than to zero.
+ */
+export const estimateImageCompressionSeconds = ({
+  width,
+  height,
+}: ImageCompressionEstimateInput): number => {
+  const megapixels =
+    width && height && width > 0 && height > 0
+      ? (width * height) / 1_000_000
+      : 0;
+  return Math.min(
+    MAX_IMAGE_COMPRESSION_COUNTDOWN_SECONDS,
+    Math.max(
+      MIN_COMPRESSION_COUNTDOWN_SECONDS,
+      Math.ceil(megapixels / IMAGE_COMPRESSION_MEGAPIXELS_PER_SECOND)
+    )
+  );
+};
+
+/** The countdown's text for a given number of seconds remaining, e.g. `Compressing (5s left)`. */
+export const formatCompressionCountdown = (
+  secondsLeft: number,
+  t?: CameraTranslationFunction
+): string => {
+  const seconds = Math.max(1, Math.ceil(secondsLeft));
+  const translated = t?.('compressingSecondsLeft', seconds);
+  return typeof translated === 'string' && translated.length > 0
+    ? translated
+    : `Compressing (${seconds}s left)`;
+};
+
+// ── Measured progress → remaining time ──────────────────────────────────────────────────────
+// The three functions below are the whole countdown: create a tracker when the compression starts,
+// fold each native progress report into it, and read the line off it as often as you like. They
+// are pure — `now` is always passed in — so the screen owns the clock and the ticking, and the
+// model itself is trivially testable.
+
+/**
+ * Below this fraction, `elapsed / fraction` is dominated by fixed setup cost (codec configuration,
+ * the first decode) and would predict a wildly pessimistic total. Under it the prediction is
+ * blended with the up-front estimate in proportion to how far along it is, so the number is steady
+ * at the start and fully measurement-driven from here on.
+ */
+export const MIN_TRUSTED_COMPRESSION_PROGRESS = 0.08;
+
+/**
+ * At or above this the encoder has finished its frames and the pass is in its tail — flushing,
+ * muxing, reading the output back — real work with no measurable length, which the line reports as
+ * "Finalizing..." rather than quoting seconds it cannot justify.
+ */
+export const COMPRESSION_FINALIZING_PROGRESS = 0.985;
+
+/**
+ * Weight given to a freshly derived total when smoothing. Low enough that a burst of
+ * cheap-to-encode frames cannot make the figure jump, high enough that a genuinely slower job has
+ * the number corrected within a few seconds.
+ */
+export const COMPRESSION_PREDICTION_SMOOTHING = 0.4;
+
+/** How often the screen should re-read the line. Twice a second; the read is one subtraction. */
+export const COMPRESSION_COUNTDOWN_TICK_MS = 500;
+
+// ── The opening "working out how long this will take" ramp ──────────────────────────────────
+// The countdown does not appear at its full figure: it counts UP to it first, one readable step at
+// a time, and only then turns around and counts down. That opening ramp is what tells the user the
+// app is sizing the job up rather than freezing.
+//
+// It is a DISPLAY ramp — it advances on a fixed cadence of its own, never on how fast the encoder
+// happens to report. The measured prediction keeps being re-derived underneath it the whole time
+// (see {@link foldCompressionProgress}); the ramp simply decides what is shown until the two meet.
+// That separation is the point: before it, the figure was whatever the prediction happened to be
+// re-derived to, which early on moves several seconds per report and flickers through numbers far
+// too quickly to read.
+
+/**
+ * One step of the opening ramp: how long each number stays on screen while the total is being
+ * worked out. About three numbers a second — slow enough to read every one of them, quick enough
+ * that the ramp is over in a moment.
+ */
+export const COMPRESSION_CALCULATION_STEP_MS = 300;
+
+/**
+ * The most steps the ramp may take, which is what bounds it in wall-clock time
+ * (`COMPRESSION_CALCULATION_STEP_MS` × this ≈ 3 s). A long job strides in larger increments rather
+ * than taking longer to count up — the ramp must never become the wait it is describing.
+ */
+export const COMPRESSION_CALCULATION_MAX_STEPS = 10;
+
+/**
+ * And it may never spend more than this share of the predicted job counting up either, so a job
+ * that is over in two seconds does not spend most of it ramping.
+ */
+export const COMPRESSION_CALCULATION_MAX_ELAPSED_FRACTION = 0.4;
+
+export interface CompressionProgressTracker {
+  /** `Date.now()` when the compression started. */
+  readonly startedAtMs: number;
+  /** The up-front estimate in seconds, which seeds — and early on partly carries — the total. */
+  readonly estimateSeconds: number;
+  /**
+   * The largest fraction the compressor has reported, or 0 while it has reported nothing at all.
+   * 0 is a real state, not just an initial one: a source with no readable duration reports nothing,
+   * and then the estimate is all there is.
+   */
+  readonly progress: number;
+  /** How long the whole compression is now expected to take, in seconds from its start. */
+  readonly predictedTotalSeconds: number;
+  /**
+   * Seconds the opening ramp adds per step. 1 for anything the ramp can count up to one second at
+   * a time within its step budget, larger for a job long enough that it has to stride.
+   */
+  readonly calculationStepSeconds: number;
+  /**
+   * Where the ramp stops climbing no matter what: the first multiple of
+   * [calculationStepSeconds] at or above the up-front estimate. Normally the ramp ends before this
+   * by meeting the real remaining time; this is the backstop for a prediction that runs away
+   * upward while the ramp is still climbing.
+   */
+  readonly calculationCeilingSeconds: number;
+}
+
+/** A tracker for a compression starting now, seeded by its up-front [estimateSeconds]. */
+export const createCompressionProgressTracker = (
+  estimateSeconds: number,
+  nowMs: number
+): CompressionProgressTracker => {
+  const seconds = Math.max(1, Math.ceil(estimateSeconds));
+  // Step budget: capped both absolutely and as a share of the job, then divided into the estimate
+  // so that every step is the same size and the whole ramp is over within it.
+  const budgetMs = Math.min(
+    COMPRESSION_CALCULATION_STEP_MS * COMPRESSION_CALCULATION_MAX_STEPS,
+    seconds * 1000 * COMPRESSION_CALCULATION_MAX_ELAPSED_FRACTION
+  );
+  const steps = Math.max(
+    1,
+    Math.floor(budgetMs / COMPRESSION_CALCULATION_STEP_MS)
+  );
+  const calculationStepSeconds = Math.max(1, Math.ceil(seconds / steps));
+  return {
+    startedAtMs: nowMs,
+    estimateSeconds: seconds,
+    progress: 0,
+    predictedTotalSeconds: seconds,
+    calculationStepSeconds,
+    calculationCeilingSeconds:
+      calculationStepSeconds * Math.ceil(seconds / calculationStepSeconds),
+  };
+};
+
+/**
+ * Fold one measured progress report (0..1) into [tracker], re-deriving how long the whole
+ * compression will take from how long it has taken to get this far.
+ *
+ * `total = elapsed / fraction` is the entire idea: it is why the displayed figure can stretch as
+ * well as shrink, and therefore why it neither hits zero mid-compression nor lingers after the
+ * work is done. Out-of-order or repeated reports cannot walk the fraction backwards.
+ *
+ * Reports during the opening ramp are folded in exactly like any other: the ramp is a DISPLAY
+ * concern only, so nothing here has to be held back or paused for it. That is what makes the
+ * hand-over accurate — by the time the ramp meets the countdown, the figure it meets has already
+ * had every report so far folded into it.
+ */
+export const foldCompressionProgress = (
+  tracker: CompressionProgressTracker,
+  progress: number,
+  nowMs: number
+): CompressionProgressTracker => {
+  const clamped = Math.min(1, Math.max(0, progress));
+  const nextProgress = Math.max(tracker.progress, clamped);
+
+  const elapsedSeconds = Math.max(0, (nowMs - tracker.startedAtMs) / 1000);
+  if (nextProgress <= 0 || elapsedSeconds <= 0) {
+    return { ...tracker, progress: nextProgress };
+  }
+
+  const measuredTotal = elapsedSeconds / nextProgress;
+  const trust = Math.min(1, nextProgress / MIN_TRUSTED_COMPRESSION_PROGRESS);
+  const blendedTotal =
+    trust * measuredTotal + (1 - trust) * tracker.estimateSeconds;
+  return {
+    ...tracker,
+    progress: nextProgress,
+    predictedTotalSeconds:
+      tracker.predictedTotalSeconds +
+      COMPRESSION_PREDICTION_SMOOTHING *
+        (blendedTotal - tracker.predictedTotalSeconds),
+  };
+};
+
+/** Seconds still to go by the current prediction — the figure the countdown proper reads. */
+const remainingSeconds = (
+  tracker: CompressionProgressTracker,
+  nowMs: number
+): number =>
+  tracker.predictedTotalSeconds -
+  Math.max(0, (nowMs - tracker.startedAtMs) / 1000);
+/** Where the opening ramp has climbed to by [nowMs], in whole seconds. */
+const calculationValueSeconds = (
+  tracker: CompressionProgressTracker,
+  nowMs: number
+): number => {
+  const elapsedMs = Math.max(0, nowMs - tracker.startedAtMs);
+  const stepsTaken = Math.floor(elapsedMs / COMPRESSION_CALCULATION_STEP_MS);
+  return Math.min(
+    tracker.calculationCeilingSeconds,
+    tracker.calculationStepSeconds * (stepsTaken + 1)
+  );
+};
+
+/**
+ * The figure the opening ramp is showing right now, or `null` once it is over and the countdown
+ * proper owns the line.
+ *
+ * The ramp ends the moment its climbing figure REACHES the real remaining time, which is what
+ * makes the hand-over seamless: the last number it shows and the first number the countdown shows
+ * are the same one, arrived at from below. (`remaining` is falling in real time while the ramp
+ * climbs, so the two always meet — the ceiling is only a backstop for a prediction re-derived
+ * upward faster than the ramp can climb.)
+ */
+export const compressionCalculationSeconds = (
+  tracker: CompressionProgressTracker,
+  nowMs: number
+): number | null => {
+  if (tracker.calculationStepSeconds <= 0) return null;
+  const value = calculationValueSeconds(tracker, nowMs);
+  if (value >= tracker.calculationCeilingSeconds) return null;
+  if (value >= remainingSeconds(tracker, nowMs)) return null;
+  return value;
+};
+
+/**
+ * How long the screen should wait before re-reading the line.
+ *
+ * While the ramp is climbing this is the time to its NEXT step, so every number it shows gets the
+ * same {@link COMPRESSION_CALCULATION_STEP_MS} on screen — an even cadence rather than one
+ * quantised to a tick that does not divide it. Afterwards it is the ordinary countdown tick.
+ */
+export const compressionCountdownTickMs = (
+  tracker: CompressionProgressTracker | null,
+  nowMs: number
+): number => {
+  if (!tracker) return COMPRESSION_COUNTDOWN_TICK_MS;
+  if (compressionCalculationSeconds(tracker, nowMs) === null) {
+    return COMPRESSION_COUNTDOWN_TICK_MS;
+  }
+  const elapsedMs = Math.max(0, nowMs - tracker.startedAtMs);
+  return (
+    COMPRESSION_CALCULATION_STEP_MS -
+    (elapsedMs % COMPRESSION_CALCULATION_STEP_MS)
+  );
+};
+
+/**
+ * What the overlay's line should read right now.
+ *
+ * Four cases, in order:
+ *
+ *  1. **The encoder is done and the pass is in its tail** (progress at or above
+ *     {@link COMPRESSION_FINALIZING_PROGRESS}) — "Finalizing...", because flushing and muxing are
+ *     real work of unmeasurable length.
+ *  2. **The opening ramp is still climbing** — its figure, one readable step at a time, until it
+ *     meets the real remaining time (see {@link compressionCalculationSeconds}).
+ *  3. **The prediction is spent and nothing was ever measured** — "Finalizing..." as well: a
+ *     compressor that reports no progress leaves only the estimate, and counting through zero into
+ *     negative numbers would misrepresent what is happening.
+ *  4. **Otherwise** — `predicted total - elapsed`, floored at one second. The floor is reached only
+ *     within about a second of the end (it takes progress above `elapsed / (elapsed + 1)`), and
+ *     case 1 takes over from there.
+ */
+export const compressionCountdownLabel = (
+  tracker: CompressionProgressTracker | null,
+  nowMs: number,
+  t?: CameraTranslationFunction
+): string => {
+  const finalizingLabel = () => {
+    const out = t?.('finalizingCompression');
+    return typeof out === 'string' && out.length > 0
+      ? out
+      : COMPRESSION_FINALIZING_LABEL;
+  };
+  if (!tracker) {
+    const fallback = t?.('compressing');
+    return typeof fallback === 'string' && fallback.length > 0
+      ? fallback
+      : COMPRESSION_FALLBACK_LABEL;
+  }
+  if (tracker.progress >= COMPRESSION_FINALIZING_PROGRESS) {
+    return finalizingLabel();
+  }
+  const calculating = compressionCalculationSeconds(tracker, nowMs);
+  if (calculating !== null) return formatCompressionCountdown(calculating, t);
+  const remaining = remainingSeconds(tracker, nowMs);
+  if (remaining < 1 && tracker.progress <= 0) return finalizingLabel();
+  return formatCompressionCountdown(Math.max(1, remaining), t);
+};
+
+// ── The level ladder and the sizes its rows quote ───────────────────────────────────────────
+// The rows the viewer's compression sheet lists, and the size band each of them promises. Both are
+// the native editor's own (MediaPreviewEditor.estimatedCompressedSize / proportionalTargetRange /
+// ImageExporter.estimateCompressedByteRange), reproduced here so the shell's sheet and the native
+// editor quote the SAME figures for the same file at the same level.
+
+/**
+ * The QUALITY levels the sheet offers, highest quality first — the percentage of the original to
+ * KEEP, which is exactly what the bridge takes (`compressVideo(uri, '45%')`). So the number a row
+ * displays is the number handed to the encoder: no inversion anywhere between the two.
+ *
+ * The native editor's ladder is the same rungs expressed the other way round (percent to SHAVE), so
+ * `95%` quality here is its `5% smaller` row and `5%` quality here is its `95% smaller` row.
+ */
+export const COMPRESSION_QUALITY_LEVELS: readonly number[] = [
+  95, 90, 85, 80, 75, 70, 65, 60, 55, 50, 45, 40, 35, 30, 25, 20, 15, 10, 5,
+];
+
+/**
+ * How far under its ceiling a compression routinely lands, which is the bottom of every quoted band
+ * — for stills because the encoder's size search stops at the highest quality at or under the
+ * target (quality quantisation, a profile pre-cap, a fallback when the target is out of reach), and
+ * for clips because the same fraction is used so a video band and an image band open by the same
+ * amount. Shared verbatim with `ImageExporter.ESTIMATE_SIZE_UNDERSHOOT`.
+ */
+export const ESTIMATE_SIZE_UNDERSHOOT = 0.85;
+
+/**
+ * The quality floor, mirrored from `VideoRotationTranscoder.MIN_BITS_PER_PIXEL_AVC` — the fewest
+ * bits per pixel per frame the native encoder will spend on a full-size frame, however heavy the
+ * level asked for. Kotlin is the source of truth for the value; this copy exists so the sheet does
+ * not quote a size the pipeline deliberately refuses to produce.
+ *
+ * AVC's figure rather than HEVC's on purpose: it is the HIGHER of the two, and the shell cannot know
+ * which codec the device will pick, so assuming AVC keeps every quoted row at or above what will
+ * actually be written. A row that promises slightly less reduction than it delivers is a pleasant
+ * surprise; the other way round is a broken promise.
+ */
+export const MIN_BITS_PER_PIXEL_AVC = 0.065;
+
+/**
+ * How far the floor may push into the clip's own rate, mirroring
+ * `VideoRotationTranscoder.MAX_FLOOR_SOURCE_SHARE`. A clip that already sits below the floor is
+ * honestly cheap rather than under-encoded, so the floor gives way to half its own average rate:
+ * every clip can always be made about twice as small, and past that the picture is protected.
+ */
+export const MAX_FLOOR_SOURCE_SHARE = 0.5;
+
+/**
+ * Frames per second assumed when quoting the floor. The shell has no access to a clip's real frame
+ * rate (nothing on a `CameraAsset` carries it), and 30 is both the overwhelmingly common capture
+ * rate and native's own fallback (`VideoRotationTranscoder.DEFAULT_FRAME_RATE`).
+ */
+export const ASSUMED_VIDEO_FRAME_RATE = 30;
+
+/** The clip facts the quality floor is measured from. All optional: missing any of them drops it. */
+export interface CompressedSizeFrame {
+  /** The clip's pixel dimensions. Orientation does not matter — only the pixel COUNT is used. */
+  readonly width?: number;
+  readonly height?: number;
+  /** Duration in milliseconds (seconds are accepted and normalised). */
+  readonly duration?: number;
+}
+
+/**
+ * The smallest size a full-resolution re-encode of [frame] can honestly come out at, or 0 when the
+ * clip does not describe itself well enough to say.
+ *
+ * `bits-per-pixel × pixels × fps × duration`, capped at {@link MAX_FLOOR_SOURCE_SHARE} of the file's
+ * own average rate. An APPROXIMATION of native's figure rather than a byte-identical copy of it: the
+ * shell cannot read the track's frame rate, nor the split between the video track and the audio the
+ * transcoder copies through untouched. It is close enough for the one job it has — keeping a row from
+ * quoting a reduction the encoder will not perform.
+ */
+const qualityFloorBytes = (
+  originalBytes: number,
+  frame?: CompressedSizeFrame
+): number => {
+  const width = frame?.width ?? 0;
+  const height = frame?.height ?? 0;
+  const seconds = durationToSeconds(frame?.duration);
+  if (width <= 0 || height <= 0 || seconds <= 0) return 0;
+  const floorBits =
+    MIN_BITS_PER_PIXEL_AVC * width * height * ASSUMED_VIDEO_FRAME_RATE * seconds;
+  const floor = Math.floor(floorBits / 8);
+  if (floor <= 0) return 0;
+  return Math.min(floor, Math.floor(originalBytes * MAX_FLOOR_SOURCE_SHARE));
+};
+
+/** A quoted output-size band: [low]..[high], the pair a level row shows as "1.8 – 2.1 MB". */
+export interface CompressedSizeBand {
+  readonly low: number;
+  readonly high: number;
+}
+
+/**
+ * The CEILING a compression at [qualityPercent] is aiming at: [originalBytes] with the shaved share
+ * removed. The single figure a compressed clip is quoted at afterwards, and the top of the band a
+ * row promises beforehand.
+ *
+ * `shave = 100 - qualityPercent`, pinned to the same range the encoder pins it to — 1..99 for a
+ * clip, 1..95 for a still (`ImageExporter.compress`'s own clamp) — and the arithmetic is integer
+ * truncating, exactly as native's is, so the two agree to the byte.
+ *
+ * For a CLIP the result is then raised to the quality floor when [frame] describes the video well
+ * enough to measure one (see {@link qualityFloorBytes}): the native encoder will not take a
+ * full-size frame below that rate, so the heavy rungs all land on the same size and a row that went
+ * on quoting `1% of the original` would be promising a file that is never written. Omit [frame] and
+ * the figure stays purely proportional, as it was before the floor existed.
+ */
+export const compressedCeilingBytes = (
+  originalBytes: number,
+  qualityPercent: number,
+  kind: 'video' | 'image',
+  frame?: CompressedSizeFrame
+): number => {
+  if (!originalBytes || originalBytes <= 0) return 0;
+  const maxShave = kind === 'video' ? 99 : 95;
+  const shave = Math.min(maxShave, Math.max(1, Math.round(100 - qualityPercent)));
+  const proportional = Math.max(1, Math.floor((originalBytes * (100 - shave)) / 100));
+  if (kind !== 'video') return proportional;
+  // Never above the original: a "compressed" row may not read as growth.
+  const floor = Math.min(originalBytes, qualityFloorBytes(originalBytes, frame));
+  return Math.max(proportional, floor);
+};
+
+/**
+ * The band of output sizes a compression at [qualityPercent] is expected to land in, or null when
+ * [originalBytes] is unknown — which drops the size from the row rather than inventing one.
+ *
+ * The top is {@link compressedCeilingBytes}; the bottom is that ceiling scaled by
+ * {@link ESTIMATE_SIZE_UNDERSHOOT}. Both media kinds share the shape deliberately: a still's band is
+ * the encoder's own target arithmetic, and a clip's is the display convention the native menu uses
+ * so a video row and an image row read alike at every rung. [frame] is the clip's own geometry and
+ * duration, which is what lets a video band respect the encoder's quality floor.
+ */
+export const compressedSizeBand = (
+  originalBytes: number,
+  qualityPercent: number,
+  kind: 'video' | 'image',
+  frame?: CompressedSizeFrame
+): CompressedSizeBand | null => {
+  const ceiling = compressedCeilingBytes(originalBytes, qualityPercent, kind, frame);
+  if (ceiling <= 0) return null;
+  const low = Math.min(
+    ceiling,
+    Math.max(1, Math.round(ceiling * ESTIMATE_SIZE_UNDERSHOOT))
+  );
+  return { low, high: ceiling };
+};
+
+/**
+ * The option string the bridge is called with for a quality level — the level itself, as a
+ * percentage. `compressVideo(uri, '45%')` keeps 45% of the quality.
+ */
+export const compressionOptionForQuality = (qualityPercent: number): string =>
+  `${Math.round(qualityPercent)}%`;
+
+/**
+ * The sentinel option for "leave it alone". Native resolves any option starting with `Original`
+ * straight back to the input URI (quality ratio 1.0), and {@link parseCompressionPercent} reads it
+ * as 0, so it never starts a compression on either side. Never displayed — the row's label comes
+ * from the localized `originalVideo` / `originalImage` keys.
+ */
+export const originalCompressionOption = (kind: 'video' | 'image'): string =>
+  kind === 'video' ? 'Original Video' : 'Original Image';
+
+/** True for the {@link originalCompressionOption} sentinels — the rows that compress nothing. */
+export const isOriginalCompressionOption = (option: string): boolean =>
+  /^\s*Original\b/i.test(option);
+
+/**
+ * How much smaller a finished compression came out, as a whole percentage of the original — the
+ * `{1}` of the `compressedToSize` line. Returns null when there is nothing honest to claim (either
+ * size unknown, or an output that did not actually shrink), and the caller falls back to
+ * `compressedToSizeOnly`.
+ */
+export const compressionSavingPercent = (
+  originalBytes: number,
+  compressedBytes: number
+): number | null => {
+  if (!originalBytes || originalBytes <= 0) return null;
+  if (!compressedBytes || compressedBytes <= 0) return null;
+  if (compressedBytes >= originalBytes) return null;
+  const saved = Math.round((1 - compressedBytes / originalBytes) * 100);
+  return saved >= 1 ? saved : null;
+};