@takazudo/zudo-image-tweaker 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Takatsudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @takazudo/zudo-image-tweaker
+
+A sharp-based image-tweaking toolkit, exposed as focused subpath modules so
+consumers only pull in the code paths (and native/optional dependencies)
+they actually use.
+
+## Install
+
+```sh
+pnpm add @takazudo/zudo-image-tweaker
+# npm install @takazudo/zudo-image-tweaker
+# yarn add @takazudo/zudo-image-tweaker
+```
+
+## Modules
+
+| Subpath | Description | Docs |
+|---|---|---|
+| `@takazudo/zudo-image-tweaker/variants` | Multi-width WebP variant engine (content-hash cache, repair, tag dispatch). | [variants](https://zudo-image-tweaker.takazudomodular.com/docs/reference/variants/) |
+| `@takazudo/zudo-image-tweaker/heif` | HEIC/HEIF → JPEG conversion with ICC profile preservation. | [heif](https://zudo-image-tweaker.takazudomodular.com/docs/reference/heif/) |
+| `@takazudo/zudo-image-tweaker/ogp` | Social-card (Open Graph / Twitter card) image compositor. | [ogp](https://zudo-image-tweaker.takazudomodular.com/docs/reference/ogp/) |
+| `@takazudo/zudo-image-tweaker/budget` | Byte-budget encode ladder. | [budget](https://zudo-image-tweaker.takazudomodular.com/docs/reference/budget/) |
+| `@takazudo/zudo-image-tweaker/square` | Five-mode square-crop toolbox. | [square](https://zudo-image-tweaker.takazudomodular.com/docs/reference/square/) |
+| `@takazudo/zudo-image-tweaker/product-photo` | ML background removal + procedural shadows for product photography. | [product-photo](https://zudo-image-tweaker.takazudomodular.com/docs/reference/product-photo/) |
+| `@takazudo/zudo-image-tweaker/calibrate` | Background color normalization. | [calibrate](https://zudo-image-tweaker.takazudomodular.com/docs/reference/calibrate/) |
+| `@takazudo/zudo-image-tweaker/composite` | Overlay batch compositing. | [composite](https://zudo-image-tweaker.takazudomodular.com/docs/reference/composite/) |
+| `@takazudo/zudo-image-tweaker/blurhash` | BlurHash placeholder generation. | [blurhash](https://zudo-image-tweaker.takazudomodular.com/docs/reference/blurhash/) |
+| `@takazudo/zudo-image-tweaker/exif` | EXIF metadata extraction. | [exif](https://zudo-image-tweaker.takazudomodular.com/docs/reference/exif/) |
+| `@takazudo/zudo-image-tweaker/browser` | Client-side upload preparation pipeline. | [browser](https://zudo-image-tweaker.takazudomodular.com/docs/reference/browser/) |
+
+Each link above goes to that module's reference page on the
+[docs site](https://zudo-image-tweaker.takazudomodular.com/docs/reference/).
+
+## Optional peer dependencies
+
+`@imgly/background-removal-node`, `exifr`, and `heic2any` are optional peer
+dependencies, dynamically imported only by the modules that need them
+(`product-photo` uses `@imgly/background-removal-node`; `browser` uses both
+`exifr` and `heic2any`). Install them only if you use those modules. `/exif`
+has no optional peer dependency — it parses the raw EXIF buffer directly.
+`/heif`'s HEIC decoder (`heic-decode`) is a regular dependency and is always
+installed.
+
+## Security notes
+
+### `/heif`
+
+`convertHeifToJpeg`'s Node/WASM fallback (`heic-decode` → bundled
+`libheif-js` 1.19.8) predates the libheif 1.22.0 heap-overflow and
+infinite-loop-DoS fixes. Only decode HEIC/HEIF files from sources you
+trust. The `maxInputBytes` option (default 256 MiB) rejects oversized
+inputs before they reach the decoder, but that's defense-in-depth, not a
+substitute for trusting the source.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/blurhash/index.d.ts

@@ -0,0 +1,35 @@
+import { type SharpInput } from 'sharp';
+export interface EncodeImageToBlurhashOptions {
+    /** Horizontal component count passed to the blurhash algorithm. */
+    componentsX?: number;
+    /** Vertical component count passed to the blurhash algorithm. */
+    componentsY?: number;
+    /** Size (both dimensions) the source is downsampled to before encoding. */
+    rawSize?: number;
+}
+/**
+ * Encode an image into a blurhash string. Downsamples the source with sharp,
+ * then feeds the raw RGBA pixels to the blurhash algorithm.
+ */
+export declare function encodeImageToBlurhash(input: SharpInput, options?: EncodeImageToBlurhashOptions): Promise<string>;
+export interface BlurhashToDataUriOptions {
+    /** Output width and height, in pixels, of the decoded PNG. */
+    size?: number;
+}
+/**
+ * Decode a blurhash string into a tiny PNG data URI, suitable for use as a
+ * placeholder while the full image loads.
+ */
+export declare function blurhashToDataUri(hash: string, options?: BlurhashToDataUriOptions): Promise<string>;
+export interface BatchBlurhashToDataUriOptions {
+    /** Number of hashes decoded concurrently per batch. */
+    chunkSize?: number;
+    /** Output width and height, in pixels, of each decoded PNG. */
+    size?: number;
+}
+/**
+ * Decode many blurhash strings into PNG data URIs, processing them in
+ * chunks so a large batch doesn't spawn unbounded concurrent sharp work.
+ * Output order matches the input order.
+ */
+export declare function batchBlurhashToDataUri(hashes: string[], options?: BatchBlurhashToDataUriOptions): Promise<string[]>;

package/dist/blurhash/index.js

@@ -0,0 +1,40 @@
+import { encode as p, decode as g } from "blurhash";
+import u from "sharp";
+const a = 1, c = 9;
+function h(t, n) {
+  if (!Number.isInteger(t) || t < a || t > c)
+    throw new Error(
+      `encodeImageToBlurhash: ${n} must be an integer between ${a} and ${c}, got ${t}`
+    );
+}
+async function b(t, n = {}) {
+  const { componentsX: e = 4, componentsY: r = 4, rawSize: o = 32 } = n;
+  h(e, "componentsX"), h(r, "componentsY");
+  const { data: i, info: s } = await u(t).rotate().raw().ensureAlpha().resize(o, o, { fit: "inside" }).toBuffer({ resolveWithObject: !0 });
+  return p(new Uint8ClampedArray(i), s.width, s.height, e, r);
+}
+async function d(t, n = {}) {
+  const { size: e = 16 } = n;
+  if (!Number.isInteger(e) || e <= 0)
+    throw new Error(`blurhashToDataUri: size must be a positive integer, got ${e}`);
+  const r = g(t, e, e);
+  return `data:image/png;base64,${(await u(Buffer.from(r), {
+    raw: { width: e, height: e, channels: 4 }
+  }).png({ compressionLevel: 9 }).toBuffer()).toString("base64")}`;
+}
+async function B(t, n = {}) {
+  const { chunkSize: e = 20, size: r } = n;
+  if (!Number.isInteger(e) || e < 1)
+    throw new Error(`batchBlurhashToDataUri: chunkSize must be a positive integer, got ${e}`);
+  const o = [];
+  for (let i = 0; i < t.length; i += e) {
+    const s = t.slice(i, i + e), f = await Promise.all(s.map((m) => d(m, { size: r })));
+    o.push(...f);
+  }
+  return o;
+}
+export {
+  B as batchBlurhashToDataUri,
+  d as blurhashToDataUri,
+  b as encodeImageToBlurhash
+};

package/dist/browser/exif-orientation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Decide whether a raw EXIF `Orientation` tag value (0x0112, values 1-8)
+ * requires baking pixels upright before upload.
+ *
+ * Orientation `1` (or a missing/malformed tag) means the pixels are already
+ * upright — no canvas round-trip needed. Any other valid value (2-8) means
+ * the decoder must rotate/flip on display, so we bake it in via canvas
+ * before the bytes leave the browser (see `bakeOrientation` in
+ * `prepare-upload.ts`, which delegates the actual rotate/flip math to
+ * `createImageBitmap(..., { imageOrientation: 'from-image' })`).
+ */
+export declare function needsOrientationBake(exifOrientation: number | undefined): boolean;

package/dist/browser/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Client-safe subpath: browser upload-preparation pipeline. Must never
+ * import `sharp` or any `node:` builtin — see `browser-chunk-guard.test.ts`.
+ */
+export { prepareImageForUpload, HEIC_DECODE_FAILED_MESSAGE, ORIENTATION_BAKE_FAILED_MESSAGE_PREFIX, MISSING_EXIFR_MESSAGE, MISSING_HEIC2ANY_MESSAGE, DEFAULT_MAX_CANVAS_AREA, type PrepareImageForUploadOptions, type PreparedImage, } from './prepare-upload.js';
+export { deriveGeometry, deriveOrientation, roundAspectRatio, type Dimensions, type DerivedGeometry, type Orientation, } from './orientation.js';
+export { needsOrientationBake } from './exif-orientation.js';

package/dist/browser/index.js

@@ -0,0 +1,160 @@
+function E(e, t) {
+  return e === t ? "square" : e > t ? "landscape" : "portrait";
+}
+function y(e, t) {
+  return !Number.isFinite(e) || !Number.isFinite(t) || t === 0 ? 0 : Math.round(e / t * 1e4) / 1e4;
+}
+function T(e, t) {
+  return {
+    dimensions: { w: e, h: t },
+    aspectRatio: y(e, t),
+    orientation: E(e, t)
+  };
+}
+function b(e) {
+  return e !== void 0 && e >= 2 && e <= 8;
+}
+const p = /^image\/(heic|heif)$/i, I = /\.(heic|heif)$/i, A = 4096 * 4096, M = "Install heic2any to decode HEIC in the browser", D = "Install exifr to enable EXIF reading (capture date + orientation baking)";
+class f extends Error {
+  constructor(t) {
+    super(t), this.name = "MissingPeerError";
+  }
+}
+function C(e) {
+  return p.test(e.type) || I.test(e.name);
+}
+function N(e) {
+  const t = e.lastIndexOf(".");
+  return t > 0 ? e.slice(0, t) : e;
+}
+const O = {
+  "image/jpeg": "jpg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/heic": "heic",
+  "image/heif": "heif"
+};
+function _(e) {
+  return O[e.toLowerCase()] ?? "bin";
+}
+function x(e, t) {
+  if (e instanceof File) return e;
+  const r = e.type || "application/octet-stream", o = `${N(t)}.${_(r)}`;
+  return new File([e], o, { type: r });
+}
+async function F(e, t) {
+  let r;
+  try {
+    ({ default: r } = await import("heic2any"));
+  } catch {
+    throw new f(M);
+  }
+  const o = await r({ blob: e, toType: "image/jpeg", quality: t });
+  return Array.isArray(o) ? o[0] : o;
+}
+async function w(e, t) {
+  let r;
+  try {
+    r = await import("exifr");
+  } catch {
+    throw new f(D);
+  }
+  try {
+    const o = t ? ["DateTimeOriginal", "CreateDate", "ModifyDate", "Orientation"] : ["DateTimeOriginal", "CreateDate", "ModifyDate"], s = await r.parse(e, { pick: o, translateValues: !1 }), n = s?.DateTimeOriginal ?? s?.CreateDate ?? s?.ModifyDate ?? null;
+    let a = null;
+    if (n instanceof Date && !Number.isNaN(n.getTime()))
+      a = n;
+    else if (typeof n == "string") {
+      const c = new Date(n);
+      Number.isNaN(c.getTime()) || (a = c);
+    }
+    const l = t && typeof s?.Orientation == "number" ? s.Orientation : void 0;
+    return { takenAt: a, exifOrientation: l };
+  } catch {
+    return { takenAt: null, exifOrientation: void 0 };
+  }
+}
+const S = "Could not decode HEIC image — heic2any failed and the browser cannot decode HEIC natively. Try saving as JPEG and uploading again.", v = "Could not bake image orientation: ";
+async function k(e) {
+  const t = URL.createObjectURL(e);
+  try {
+    const r = await new Promise((o, s) => {
+      const n = new Image();
+      n.onload = () => o(n), n.onerror = () => s(new Error("Failed to decode image for dimensions")), n.src = t;
+    });
+    return { width: r.naturalWidth, height: r.naturalHeight };
+  } finally {
+    URL.revokeObjectURL(t);
+  }
+}
+async function H(e, t, r, o) {
+  const s = await createImageBitmap(e, { imageOrientation: "from-image" });
+  try {
+    let n = s.width, a = s.height;
+    const l = n * a;
+    if (l > o) {
+      const i = Math.sqrt(o / l);
+      n = Math.max(1, Math.floor(n * i)), a = Math.max(1, Math.floor(a * i));
+    }
+    const c = document.createElement("canvas");
+    c.width = n, c.height = a;
+    const m = c.getContext("2d");
+    if (!m) throw new Error("2D canvas context is unavailable");
+    m.drawImage(s, 0, 0, n, a);
+    const u = t === "image/png" || t === "image/webp" ? t : "image/jpeg", d = await new Promise((i) => c.toBlob(i, u, r));
+    if (!d) throw new Error("Canvas toBlob produced no data");
+    const h = c.width, g = c.height;
+    return c.width = 0, c.height = 0, { blob: d, width: h, height: g };
+  } finally {
+    s.close();
+  }
+}
+async function R(e, t = {}) {
+  const r = t.heicQuality ?? 0.9, o = t.bakeQuality ?? 0.92, s = t.maxCanvasArea ?? A, n = C(e);
+  let a = e, l = !1;
+  if (n)
+    try {
+      a = await F(e, r), l = !0;
+    } catch (i) {
+      if (i instanceof f) throw i;
+    }
+  const { takenAt: c, exifOrientation: m } = l ? await w(e, !1) : await w(a, !0), u = b(m);
+  let d, h, g;
+  try {
+    if (u) {
+      const i = await H(a, e.type, o, s);
+      d = i.blob, h = i.width, g = i.height;
+    } else {
+      const i = await k(a);
+      d = a, h = i.width, g = i.height;
+    }
+  } catch (i) {
+    if (n && !l)
+      throw new Error(S);
+    if (u)
+      throw new Error(`${v}${i.message}`);
+    d = a, h = 0, g = 0;
+  }
+  return {
+    // Preserve the source name base and give the output an extension that
+    // matches its ACTUAL MIME. Unchanged originals pass through untouched.
+    file: x(d, e.name),
+    width: h,
+    height: g,
+    takenAt: c,
+    orientation: E(h, g),
+    transcodedFromHeic: l
+  };
+}
+export {
+  A as DEFAULT_MAX_CANVAS_AREA,
+  S as HEIC_DECODE_FAILED_MESSAGE,
+  D as MISSING_EXIFR_MESSAGE,
+  M as MISSING_HEIC2ANY_MESSAGE,
+  v as ORIENTATION_BAKE_FAILED_MESSAGE_PREFIX,
+  T as deriveGeometry,
+  E as deriveOrientation,
+  b as needsOrientationBake,
+  R as prepareImageForUpload,
+  y as roundAspectRatio
+};

package/dist/browser/orientation-semantics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reference implementation of the 8 EXIF `Orientation` tag transforms (values
+ * 1-8), expressed as pure grid permutations.
+ *
+ * This does NOT mirror any code path inside `bakeOrientation`
+ * (`prepare-upload.ts`): that function deliberately delegates the actual
+ * rotate/flip math to `createImageBitmap(..., { imageOrientation: 'from-image'
+ * })` rather than hand-rolling the 8-case matrix itself (see its doc comment).
+ * There is therefore no in-repo "pure orientation function" for production
+ * code to share with this one.
+ *
+ * Its purpose is different: it's an independently-reasoned oracle for what
+ * each orientation value is SUPPOSED to do to a grid of pixels, used to
+ * compute expected outputs for both `orientation-semantics.test.ts` (below)
+ * and the real-browser CDP smoke test in
+ * `scripts/browser-orientation-smoke.mjs` (see issue #52) — so the smoke test
+ * can assert Chrome's actual `imageOrientation: 'from-image'` behaviour
+ * against a formally-derived expectation instead of a hand-wavy "looks right".
+ *
+ * Transform definitions (standard EXIF/TIFF orientation semantics, matching
+ * the well-known PIL `ImageOps.exif_transpose` table):
+ *   1 = normal (no-op)
+ *   2 = mirror horizontal
+ *   3 = rotate 180
+ *   4 = mirror vertical
+ *   5 = transpose (mirror across the top-left/bottom-right diagonal)
+ *   6 = rotate 90 CW
+ *   7 = transverse (mirror across the top-right/bottom-left diagonal)
+ *   8 = rotate 90 CCW
+ */
+/** A grid of pixels/values, indexed `grid[row][col]`. */
+export type Grid<T> = readonly T[][];
+/**
+ * Apply the display-transform implied by a raw EXIF `Orientation` value
+ * (1-8) to a grid, returning the upright arrangement.
+ */
+export declare function applyExifOrientationToGrid<T>(grid: Grid<T>, orientation: number): T[][];

package/dist/browser/orientation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Derive width/height, aspect ratio, and orientation classification from a
+ * decoded image's dimensions.
+ *
+ * Pure utility — kept framework-agnostic so it can be unit-tested without
+ * touching the DOM or the Canvas API.
+ */
+export type Orientation = 'landscape' | 'portrait' | 'square';
+export interface Dimensions {
+    w: number;
+    h: number;
+}
+export interface DerivedGeometry {
+    dimensions: Dimensions;
+    aspectRatio: number;
+    orientation: Orientation;
+}
+export declare function deriveOrientation(w: number, h: number): Orientation;
+/**
+ * Round to 4 decimal places. Returns `0` when `h` is 0 (or either input is
+ * non-finite) to avoid surfacing `Infinity`/`NaN` downstream; callers should
+ * treat a 0 aspect ratio as "unknown".
+ */
+export declare function roundAspectRatio(w: number, h: number): number;
+export declare function deriveGeometry(w: number, h: number): DerivedGeometry;

package/dist/browser/prepare-upload.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Client-side pre-upload pipeline:
+ *
+ * 1. If the file is HEIC/HEIF, transcode to JPEG using `heic2any`. On failure
+ *    we keep the raw HEIC bytes so a later step (or the server) can still
+ *    deal with it.
+ * 2. Read EXIF with `exifr` — `DateTimeOriginal`/`CreateDate`/`ModifyDate`
+ *    for `takenAt`, plus the raw `Orientation` tag.
+ * 3. If the orientation tag says the image isn't already upright, bake the
+ *    rotation into the pixels via canvas so the bytes leaving the browser
+ *    need no further EXIF-orientation handling downstream.
+ * 4. Decode the final bytes once to measure width/height.
+ *
+ * ## Optional peer dependencies
+ *
+ * `exifr` and `heic2any` are optional peer dependencies and are always
+ * dynamic-imported so this subpath never forces them into a consumer's
+ * bundle unless the pipeline actually runs:
+ *
+ * - `exifr` enables EXIF reading — both the capture date (`takenAt`) and the
+ *   orientation-bake guarantee. If it isn't installed the pipeline throws
+ *   {@link MISSING_EXIFR_MESSAGE} rather than silently dropping metadata and
+ *   shipping images the decoder still has to rotate on display.
+ * - `heic2any` enables HEIC/HEIF decoding in the browser. If it isn't
+ *   installed and a HEIC/HEIF file is submitted, the pipeline throws
+ *   {@link MISSING_HEIC2ANY_MESSAGE} rather than misreporting the absence as a
+ *   generic decode failure.
+ */
+import { type Orientation } from './orientation.js';
+/**
+ * Conservative default cap on the pixel area of the bake canvas.
+ *
+ * Safari/iOS historically refuse to allocate canvases beyond ~16.7M pixels
+ * (≈4096×4096 on older devices) and, rather than throwing, hand back a
+ * silently blank canvas — so an uncapped full-resolution bake produces empty
+ * output on exactly the devices that need orientation baking most. We downscale
+ * to fit this budget instead. Override via `maxCanvasArea` when the target
+ * environment is known to allow more.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas#maximum_canvas_size
+ */
+export declare const DEFAULT_MAX_CANVAS_AREA: number;
+/**
+ * Thrown when a HEIC/HEIF file is submitted but the optional `heic2any` peer
+ * dependency is not installed. Exported so callers/tests can assert against the
+ * wording without duplicating it.
+ */
+export declare const MISSING_HEIC2ANY_MESSAGE = "Install heic2any to decode HEIC in the browser";
+/**
+ * Thrown when the pipeline needs to read EXIF (always) but the optional `exifr`
+ * peer dependency is not installed. `exifr` is required for every image — the
+ * capture date is read even for plain JPEGs that need no orientation bake — so
+ * the message names EXIF reading, not just baking. Exported so callers/tests
+ * can assert against the wording without duplicating it.
+ */
+export declare const MISSING_EXIFR_MESSAGE = "Install exifr to enable EXIF reading (capture date + orientation baking)";
+export interface PrepareImageForUploadOptions {
+    /** JPEG quality (0-1) used when transcoding HEIC/HEIF to JPEG. Default 0.9. */
+    heicQuality?: number;
+    /**
+     * Quality (0-1) used when re-encoding after an orientation bake. Applies to
+     * every lossy output type this pipeline can emit — JPEG and WebP alike.
+     * Default 0.92.
+     */
+    bakeQuality?: number;
+    /**
+     * Maximum pixel area (width × height) of the bake canvas. Inputs larger than
+     * this are downscaled to fit before baking, so oversized images produce a
+     * correctly-downscaled result instead of Safari's silently-blank output.
+     * Default {@link DEFAULT_MAX_CANVAS_AREA}.
+     */
+    maxCanvasArea?: number;
+}
+export interface PreparedImage {
+    /** The upload-ready bytes: JPEG when HEIC was transcoded or orientation was baked, otherwise the original file. */
+    file: File | Blob;
+    width: number;
+    height: number;
+    /** EXIF capture date, if present and parseable. */
+    takenAt: Date | null;
+    orientation: Orientation;
+    transcodedFromHeic: boolean;
+}
+/**
+ * User-facing error message emitted when a HEIC file failed `heic2any`
+ * transcoding AND the browser also cannot decode the raw HEIC bytes for
+ * dimensions (neither `createImageBitmap` nor `<img>` support HEIC
+ * natively in most browsers). Exported so callers/tests can assert against
+ * it without duplicating the wording.
+ */
+export declare const HEIC_DECODE_FAILED_MESSAGE = "Could not decode HEIC image \u2014 heic2any failed and the browser cannot decode HEIC natively. Try saving as JPEG and uploading again.";
+/**
+ * Prefix for the error thrown when EXIF said the image needs an orientation
+ * bake but the bake itself failed (createImageBitmap/canvas/toBlob). We
+ * throw rather than silently falling back to un-rotated bytes + a 0x0
+ * placeholder — that would quietly violate the "stored originals are
+ * upright" guarantee this pipeline exists to provide.
+ */
+export declare const ORIENTATION_BAKE_FAILED_MESSAGE_PREFIX = "Could not bake image orientation: ";
+export declare function prepareImageForUpload(file: File, opts?: PrepareImageForUploadOptions): Promise<PreparedImage>;

package/dist/budget/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Encode an image so its output stays under a byte-count ceiling, by
+ * progressively lowering quality (and, when quality alone isn't enough,
+ * width) until the result fits.
+ *
+ * Two presets cover the two shapes this problem takes in practice:
+ *
+ * - **Exact-width preset** (`exactWidth` set): the output width is fixed —
+ *   smaller sources are upscaled to it, larger ones downscaled — and only
+ *   compression quality steps down across a small ladder of rungs matched
+ *   to the output format (for PNG, palette quantization engages below the
+ *   near-lossless top rung). Useful when a downstream consumer requires an
+ *   exact pixel width regardless of size.
+ * - **Step-down preset** (`exactWidth` omitted): the source's aspect ratio
+ *   is kept, output format auto-detects JPEG vs PNG from the alpha
+ *   channel, and once the quality ladder at the current width is
+ *   exhausted the width itself steps down (down to `minWidth`) before the
+ *   ladder is retried. Useful when only a total byte ceiling matters, not
+ *   an exact width.
+ *
+ * Both presets share the same budget-loop, GIF-skip, and input-loading
+ * machinery; `qualityLadder`, `minWidth`, `widthStepFactor`, and
+ * `paletteQuantization` let a caller override either preset's defaults.
+ */
+export interface Step {
+    width: number;
+    quality: number;
+    bytes: number;
+}
+export type BudgetResult = {
+    ok: true;
+    buffer: Buffer;
+    format: 'jpeg' | 'png';
+    width: number;
+    quality: number;
+    bytes: number;
+    steps: Step[];
+} | {
+    ok: false;
+    reason: 'unreachable-budget' | 'animated-gif-skipped';
+    steps: Step[];
+};
+export interface EncodeUnderByteBudgetOptions {
+    /** Byte-count ceiling the encoded output must not exceed. */
+    maxBytes: number;
+    /**
+     * Explicit output format, or `'auto'` to detect from the source's alpha
+     * channel (PNG when present, JPEG otherwise). Defaults to `'png'` when
+     * `exactWidth` is set and this is omitted, `'auto'` behavior otherwise.
+     */
+    format?: 'jpeg' | 'png' | 'auto';
+    /** Fixed output width; enables the exact-width preset. Upscales smaller sources. */
+    exactWidth?: number;
+    /** Overrides the default quality rungs tried at each width. */
+    qualityLadder?: number[];
+    /** Step-down preset only: width floor the step-down loop won't go below. Defaults to 400. */
+    minWidth?: number;
+    /** Step-down preset only: multiplier applied to width on each step-down. Defaults to 0.85. */
+    widthStepFactor?: number;
+    /** Whether the lower quality rungs may engage palette quantization for PNG output. Defaults to true. */
+    paletteQuantization?: boolean;
+    /** Remote-URL inputs only: milliseconds before the fetch is aborted. Defaults to 30000. */
+    fetchTimeoutMs?: number;
+    /** Remote-URL inputs only: byte cap on the downloaded input. Defaults to 100MB. */
+    maxInputBytes?: number;
+}
+/**
+ * Encode `input` into a buffer no larger than `options.maxBytes`, stepping
+ * down quality (and, in the step-down preset, width) until it fits.
+ * Never throws for an unreachable budget or an animated GIF — both are
+ * reported through the returned result's `ok: false` shape.
+ */
+export declare function encodeUnderByteBudget(input: Buffer | string, options: EncodeUnderByteBudgetOptions): Promise<BudgetResult>;