@takazudo/zudo-image-tweaker 0.1.0

package/dist/budget/index.js

@@ -0,0 +1,157 @@
+import b from "node:fs/promises";
+import m from "sharp";
+const T = 400, _ = 0.85, L = 3e4, A = 100 * 1024 * 1024, y = [90, 82, 75, 65, 55, 45, 35], W = 95, S = [95, 85, 75, 65, 50], B = [100, 90, 80, 65, 50];
+async function Q(t, n) {
+  const {
+    maxBytes: e,
+    format: r,
+    exactWidth: c,
+    qualityLadder: s,
+    minWidth: h = T,
+    widthStepFactor: o = _,
+    paletteQuantization: f = !0,
+    fetchTimeoutMs: u = L,
+    maxInputBytes: a = A
+  } = n, i = await I(t, { fetchTimeoutMs: u, maxInputBytes: a }), d = await m(i).metadata();
+  if (N(d.format, d.pages))
+    return { ok: !1, reason: "animated-gif-skipped", steps: [] };
+  if (!d.width || !d.height)
+    throw new Error("Could not read image dimensions from source");
+  const l = k(r, !!d.hasAlpha, c !== void 0);
+  if (c !== void 0)
+    return D(i, {
+      format: l,
+      exactWidth: c,
+      maxBytes: e,
+      qualityLadder: s ?? (l === "jpeg" ? y : S),
+      paletteQuantization: f
+    });
+  const p = U(d.orientation) ? d.height : d.width;
+  return $(i, {
+    format: l,
+    sourceWidth: p,
+    maxBytes: e,
+    qualityLadder: s ?? (l === "jpeg" ? y : B),
+    minWidth: h,
+    widthStepFactor: o,
+    paletteQuantization: f
+  });
+}
+async function D(t, n) {
+  const { format: e, exactWidth: r, maxBytes: c, qualityLadder: s, paletteQuantization: h } = n, o = [], f = /* @__PURE__ */ new Set();
+  for (const u of s) {
+    const a = E(e, u, h);
+    if (f.has(a))
+      continue;
+    f.add(a);
+    const i = await F(t, e, r, u, h);
+    if (o.push({ width: r, quality: u, bytes: i.length }), i.length <= c)
+      return { ok: !0, buffer: i, format: e, width: r, quality: u, bytes: i.length, steps: o };
+  }
+  return { ok: !1, reason: "unreachable-budget", steps: o };
+}
+async function F(t, n, e, r, c) {
+  const s = m(t).rotate().resize(e, null, { withoutEnlargement: !1 });
+  return n === "png" ? s.png(w(r, c)).toBuffer() : s.jpeg({ quality: r, mozjpeg: !0 }).toBuffer();
+}
+async function $(t, n) {
+  const { format: e, sourceWidth: r, maxBytes: c, qualityLadder: s, minWidth: h, widthStepFactor: o, paletteQuantization: f } = n, u = [];
+  let a = r;
+  for (; ; ) {
+    const i = /* @__PURE__ */ new Set();
+    for (const l of s) {
+      const p = E(e, l, f);
+      if (i.has(p))
+        continue;
+      i.add(p);
+      const g = await x(t, e, a === r ? null : a, l, f);
+      if (u.push({ width: a, quality: l, bytes: g.length }), g.length <= c)
+        return { ok: !0, buffer: g, format: e, width: a, quality: l, bytes: g.length, steps: u };
+    }
+    const d = Math.round(a * o);
+    if (d < h || d >= a) {
+      if (a > h) {
+        a = h;
+        continue;
+      }
+      break;
+    }
+    a = d;
+  }
+  return { ok: !1, reason: "unreachable-budget", steps: u };
+}
+async function x(t, n, e, r, c) {
+  let s = m(t).rotate();
+  return e && (s = s.resize(e, null, { fit: "inside", withoutEnlargement: !0 })), n === "png" ? s.png(w(r, c)).toBuffer() : s.jpeg({ quality: r, mozjpeg: !0 }).toBuffer();
+}
+function w(t, n) {
+  const e = { compressionLevel: 9, effort: 10 };
+  return n && t < W ? (e.palette = !0, e.colors = t >= 70 ? 256 : t >= 45 ? 16 : 4, e.dither = 1) : e.palette = !1, e;
+}
+function E(t, n, e) {
+  return JSON.stringify(t === "png" ? w(n, e) : { quality: n });
+}
+function U(t) {
+  return t !== void 0 && t >= 5 && t <= 8;
+}
+function N(t, n) {
+  return t === "gif" && n !== void 0 && n > 1;
+}
+function k(t, n, e) {
+  return t === "jpeg" || t === "png" ? t : t === void 0 && e || n ? "png" : "jpeg";
+}
+function z(t) {
+  return /^https?:\/\//i.test(t);
+}
+async function I(t, n) {
+  if (Buffer.isBuffer(t))
+    return t;
+  if (z(t))
+    return R(t, n);
+  try {
+    return await b.readFile(t);
+  } catch (e) {
+    throw new Error(`Failed to read local file "${t}": ${e.message}`, { cause: e });
+  }
+}
+async function R(t, { fetchTimeoutMs: n, maxInputBytes: e }) {
+  const r = new AbortController(), c = new Error(`Failed to fetch "${t}": timed out after ${n}ms`), s = setTimeout(() => r.abort(c), n), h = (o) => {
+    throw r.signal.reason === c ? c : o instanceof Error && o.message.includes("exceeds the maximum input size") ? o : new Error(`Failed to fetch "${t}": ${o.message}`, { cause: o });
+  };
+  try {
+    let o;
+    try {
+      o = await fetch(t, { signal: r.signal });
+    } catch (i) {
+      throw h(i), i;
+    }
+    if (!o.ok)
+      throw r.abort(), new Error(`Failed to fetch "${t}": HTTP ${o.status} ${o.statusText}`);
+    const f = Number(o.headers.get("content-length"));
+    if (Number.isFinite(f) && f > e)
+      throw r.abort(), new Error(
+        `Remote input "${t}" declares ${f} bytes, which exceeds the maximum input size of ${e} bytes`
+      );
+    if (!o.body)
+      return Buffer.alloc(0);
+    const u = [];
+    let a = 0;
+    try {
+      for await (const i of o.body) {
+        if (a += i.byteLength, a > e)
+          throw r.abort(), new Error(
+            `Remote input "${t}" exceeds the maximum input size of ${e} bytes (aborted after ${a} bytes)`
+          );
+        u.push(i);
+      }
+    } catch (i) {
+      h(i);
+    }
+    return Buffer.concat(u);
+  } finally {
+    clearTimeout(s);
+  }
+}
+export {
+  Q as encodeUnderByteBudget
+};

package/dist/calibrate/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Background-color calibration: sample the background color from an
+ * image's four corners, derive a target color by averaging that sample
+ * across a set of reference images, and normalize a new image's
+ * background toward that target.
+ *
+ * Correction is selective: each pixel is blended toward its target-scaled
+ * value by a weight built from a saturation-gate ramp times a circular
+ * hue-distance falloff around the *sampled* background hue (not the
+ * target hue), so neutrals, grays, and dark pixels are left untouched
+ * while only background-colored pixels move. When the sampled background
+ * is itself achromatic (its saturation falls below `saturationGate.from`)
+ * there is no coherent hue to match against, so every pixel gets zero
+ * weight rather than being compared to a meaningless hue reading of 0.
+ *
+ * EXIF orientation is applied before any pixel is read or written (via
+ * sharp's `.rotate()` with no arguments) — camera photos with a
+ * non-default orientation tag are sampled and corrected in their
+ * upright, displayed orientation, not their as-stored one.
+ *
+ * HEIC/HEIF decoding is feature-detected via macOS `sips` (invoked with
+ * `execFile` argument arrays, never a shell string) because this module
+ * carries no Node-native HEIC decoder. `sampleBackgroundColor` and
+ * `normalizeBackgroundColor` throw a descriptive error for `.heic`/`.heif`
+ * input on any platform where `sips` is unavailable (Linux, Windows) —
+ * pre-convert such inputs to JPEG/PNG (e.g. via the sibling `/heif`
+ * module, which does carry a Node-native fallback) before calling into
+ * this module. Buffer input bypasses HEIC handling entirely; only a
+ * string path is checked for a `.heic`/`.heif` extension. A `sips` failure
+ * for any reason other than being absent (e.g. an HDR "gain map" HEIC
+ * whose auxiliary-image references exceed the system libheif's limit —
+ * see `/heif`'s module doc for the full explanation) is rethrown wrapped
+ * with the same pre-convert-via-`/heif` guidance (issue #34).
+ *
+ * ICC profile (issue #35): `normalizeBackgroundColor` samples and corrects
+ * pixels via a raw decode, which yields the source's literal device-space
+ * sample values without any colour-space conversion (verified empirically:
+ * a Display-P3-tagged source's raw pixels are numerically unchanged from
+ * its stored bytes). All arithmetic — sampling, target-ratio scaling,
+ * hue/saturation gating — therefore stays self-consistent in that same
+ * device space throughout. To avoid re-interpreting those device-space
+ * values as sRGB (which would shift the rendered colour for any
+ * wide-gamut source), the source's ICC profile, if present, is re-attached
+ * byte-identically to the output via `sharp#withIccProfile` pointed at a
+ * temp file holding the extracted profile bytes — this only tags the
+ * output, it does not run a colour transform, because the pipeline is
+ * built from a raw pixel buffer with no profile of its own to transform
+ * from (see the `withIccProfile` call site below for the same reasoning
+ * `/heif` documents for its APP2 splice). EXIF and all other metadata are
+ * always dropped: the raw-buffer re-encode carries no EXIF forward and
+ * this module never re-attaches any (unlike ICC, which is deliberately
+ * restored) — there is no `stripMetadata`-style opt-out.
+ */
+export interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+export interface SaturationGate {
+    /** Saturation (0-1) below which a pixel is treated as neutral. */
+    from: number;
+    /** Saturation (0-1) at and above which a pixel gets full correction weight. */
+    to: number;
+}
+export interface SampleBackgroundColorOptions {
+    /** Size (px) of each square corner patch sampled. @default 50 */
+    patchSize?: number;
+    /**
+     * HEIC/HEIF input only: kill the `sips` conversion subprocess if it
+     * hasn't exited after this many ms. @default 60000
+     */
+    sipsTimeoutMs?: number;
+}
+export interface NormalizeBackgroundColorOptions {
+    /** Color to move the sampled background toward. */
+    target: RgbColor;
+    /** Size (px) of each corner patch used to sample the current background. @default 50 */
+    patchSize?: number;
+    /** Hue-distance falloff radius, in degrees, around the sampled background hue. @default 60 */
+    hueRadiusDeg?: number;
+    /** Saturation ramp gating which pixels are eligible for correction. @default { from: 0.08, to: 0.25 } */
+    saturationGate?: SaturationGate;
+    /** Per-channel scale-factor clamp [min, max] applied to target/current ratios. @default [0.5, 2.0] */
+    channelClamp?: [number, number];
+    /** Output encoding. Inferred from `input`'s extension when it's a path (default jpeg); defaults to jpeg for Buffer input. */
+    format?: 'jpeg' | 'png' | 'webp' | 'tiff';
+    /**
+     * HEIC/HEIF input only: kill the `sips` conversion subprocess if it
+     * hasn't exited after this many ms. @default 60000
+     */
+    sipsTimeoutMs?: number;
+}
+export interface NormalizeBackgroundColorResult {
+    buffer: Buffer;
+    applied: {
+        scaleR: number;
+        scaleG: number;
+        scaleB: number;
+    };
+}
+/**
+ * Sample the background color of an image by averaging four square
+ * patches, one from each corner (with a small margin so patches don't
+ * touch the exact edge).
+ */
+export declare function sampleBackgroundColor(input: string | Buffer, opts?: SampleBackgroundColorOptions): Promise<RgbColor>;
+/**
+ * Derive a target background color by sampling each reference image's
+ * background (see {@link sampleBackgroundColor}) and averaging the
+ * results.
+ */
+export declare function calibrateTargetFromSamples(inputs: Array<string | Buffer>, opts?: SampleBackgroundColorOptions): Promise<RgbColor>;
+/**
+ * Normalize an image's background color toward `opts.target`. The image is
+ * converted (if HEIC/HEIF) and decoded to raw pixels exactly once; the
+ * current background is sampled directly from that raw buffer (see
+ * {@link sampleBackgroundFromRawBuffer}) rather than via a second decode.
+ * Each channel's target/current ratio becomes that channel's scale factor,
+ * clamped to `opts.channelClamp`. Per pixel, the scaled value is blended
+ * in proportional to {@link computeCorrectionWeight}, so only pixels close
+ * in hue to the *sampled* background — and saturated enough to carry that
+ * hue reliably — move; neutrals and dark pixels are returned unchanged.
+ *
+ * ICC: the source's ICC profile, if present, is re-attached byte-identically
+ * to the output (see the module doc comment for why re-attaching rather
+ * than transforming is correct here). EXIF and all other metadata are
+ * always dropped — see the module doc comment's "EXIF" note.
+ */
+export declare function normalizeBackgroundColor(input: string | Buffer, opts: NormalizeBackgroundColorOptions): Promise<NormalizeBackgroundColorResult>;

package/dist/calibrate/index.js

@@ -0,0 +1,206 @@
+import { randomUUID as O } from "node:crypto";
+import T from "node:fs/promises";
+import R from "node:os";
+import P from "node:path";
+import y from "sharp";
+import { r as Z, a as z, i as Q } from "../run-BIjGA2Fu.js";
+const U = 6e4, j = 50, s = 5, V = 60, Y = { from: 0.08, to: 0.25 }, tt = [0.5, 2], et = 30;
+function rt(t) {
+  return /\.hei[cf]$/i.test(t);
+}
+async function nt(t, r) {
+  const e = P.join(R.tmpdir(), `zit-calibrate-${process.pid}-${O()}.jpg`);
+  try {
+    await Z(
+      "sips",
+      [
+        "-s",
+        "format",
+        "jpeg",
+        "-s",
+        "formatOptions",
+        "95",
+        z(t),
+        "--out",
+        e
+      ],
+      { timeoutMs: r }
+    );
+  } catch (n) {
+    if (await T.rm(e, { force: !0 }), Q(n))
+      return null;
+    throw new Error(
+      `HEIC/HEIF conversion via 'sips' failed for '${t}': ${n.message}. This can happen with HDR "gain map" HEIC files, which the system libheif that \`sips\` relies on may reject via a strict auxiliary-image-reference limit. Pre-convert '` + t + "' via the sibling /heif module (whose Node fallback does not carry that limit) before calling this function.",
+      { cause: n }
+    );
+  }
+  return e;
+}
+async function L(t, r) {
+  if (typeof t == "string" && rt(t)) {
+    const e = await nt(t, r);
+    if (!e)
+      throw new Error(
+        `HEIC/HEIF decoding requires macOS 'sips', which is unavailable on this platform. Pre-convert '${t}' to JPEG/PNG (e.g. via the sibling /heif module) before calling this function.`
+      );
+    return { sharpInput: e, cleanup: () => T.rm(e, { force: !0 }) };
+  }
+  return { sharpInput: t, cleanup: async () => {
+  } };
+}
+async function ot(t) {
+  const { width: r = 0, height: e = 0, orientation: n } = await y(t).metadata();
+  return n !== void 0 && n >= 5 && n <= 8 ? { width: e, height: r } : { width: r, height: e };
+}
+function at(t) {
+  let r = 0, e = 0, n = 0;
+  const o = t.length / 3;
+  for (let a = 0; a < t.length; a += 3)
+    r += t[a], e += t[a + 1], n += t[a + 2];
+  return {
+    r: Math.round(r / o),
+    g: Math.round(e / o),
+    b: Math.round(n / o)
+  };
+}
+function $(t) {
+  const r = t.length;
+  return {
+    r: Math.round(t.reduce((e, n) => e + n.r, 0) / r),
+    g: Math.round(t.reduce((e, n) => e + n.g, 0) / r),
+    b: Math.round(t.reduce((e, n) => e + n.b, 0) / r)
+  };
+}
+async function it(t, r = {}) {
+  const e = r.patchSize ?? j, n = r.sipsTimeoutMs ?? U, o = e + s * 2, { sharpInput: a, cleanup: i } = await L(t, n);
+  try {
+    const { width: u, height: f } = await ot(a);
+    if (!u || !f || u < o || f < o)
+      throw new Error(
+        `Image too small (${u ?? 0}x${f ?? 0}). Minimum ${o}x${o} required.`
+      );
+    const h = [
+      { left: s, top: s },
+      { left: u - e - s, top: s },
+      { left: s, top: f - e - s },
+      { left: u - e - s, top: f - e - s }
+    ], c = [];
+    for (const m of h) {
+      const { data: l } = await y(a).rotate().extract({ left: m.left, top: m.top, width: e, height: e }).removeAlpha().raw().toBuffer({ resolveWithObject: !0 });
+      c.push(at(l));
+    }
+    return $(c);
+  } finally {
+    await i();
+  }
+}
+async function bt(t, r = {}) {
+  if (t.length === 0)
+    throw new Error("calibrateTargetFromSamples requires at least one reference image.");
+  const e = await Promise.all(t.map((n) => it(n, r)));
+  return $(e);
+}
+function N(t, r, e) {
+  return Math.min(Math.max(t, r), e);
+}
+function v(t) {
+  return t < 0 ? 0 : t > 255 ? 255 : Math.round(t);
+}
+function q(t, r, e) {
+  const n = Math.max(t, r, e), o = Math.min(t, r, e), a = n - o;
+  if (a === 0) return 0;
+  let i;
+  return n === t ? i = (r - e) / a % 6 : n === r ? i = (e - t) / a + 2 : i = (t - r) / a + 4, i *= 60, i < 0 && (i += 360), i;
+}
+function k(t, r, e) {
+  const n = Math.max(t, r, e), o = Math.min(t, r, e);
+  return n === 0 ? 0 : (n - o) / n;
+}
+function st(t, r, e, n, o, a, i) {
+  if (Math.max(t, r, e) < et || o < i.from) return 0;
+  const f = k(t, r, e);
+  if (f < i.from) return 0;
+  const h = q(t, r, e);
+  let c = Math.abs(h - n);
+  c > 180 && (c = 360 - c);
+  const m = c < a ? 1 - c / a : 0, l = i.to - i.from;
+  return (l > 0 ? N((f - i.from) / l, 0, 1) : f >= i.from ? 1 : 0) * m;
+}
+function ct(t) {
+  if (typeof t != "string") return "jpeg";
+  const r = P.extname(t).toLowerCase();
+  return r === ".png" ? "png" : r === ".webp" ? "webp" : r === ".tiff" || r === ".tif" ? "tiff" : "jpeg";
+}
+function ft(t, r) {
+  switch (r) {
+    case "png":
+      return t.png();
+    case "webp":
+      return t.webp({ quality: 95 });
+    case "tiff":
+      return t.tiff({ quality: 95 });
+    default:
+      return t.jpeg({ quality: 95 });
+  }
+}
+function lt(t, r, e, n, o, a) {
+  let i = 0, u = 0, f = 0;
+  for (let c = 0; c < a; c++) {
+    let m = ((o + c) * r + n) * e;
+    for (let l = 0; l < a; l++)
+      i += t[m], u += t[m + 1], f += t[m + 2], m += e;
+  }
+  const h = a * a;
+  return {
+    r: Math.round(i / h),
+    g: Math.round(u / h),
+    b: Math.round(f / h)
+  };
+}
+function ht(t, r, e, n, o) {
+  const a = [
+    { left: s, top: s },
+    { left: r - o - s, top: s },
+    { left: s, top: e - o - s },
+    { left: r - o - s, top: e - o - s }
+  ];
+  return $(
+    a.map((i) => lt(t, r, n, i.left, i.top, o))
+  );
+}
+async function yt(t, r) {
+  const {
+    target: e,
+    patchSize: n = j,
+    hueRadiusDeg: o = V,
+    saturationGate: a = Y,
+    channelClamp: i = tt,
+    format: u,
+    sipsTimeoutMs: f = U
+  } = r;
+  if (!Number.isInteger(n) || n <= 0)
+    throw new Error(`patchSize must be a positive integer, got ${n}`);
+  const h = n + s * 2, { sharpInput: c, cleanup: m } = await L(t, f);
+  let l = null;
+  try {
+    const { hasAlpha: D, icc: _ } = await y(c).metadata(), F = y(c).rotate(), { data: W, info: p } = await (D ? F.ensureAlpha() : F.removeAlpha()).raw().toBuffer({ resolveWithObject: !0 }), A = p.channels, w = Buffer.from(W);
+    if (!p.width || !p.height || p.width < h || p.height < h)
+      throw new Error(
+        `Image too small (${p.width ?? 0}x${p.height ?? 0}). Minimum ${h}x${h} required.`
+      );
+    const d = ht(w, p.width, p.height, A, n), [G, J] = i, C = (g, M) => M === 0 ? 1 : N(g / M, G, J), S = C(e.r, d.r), H = C(e.g, d.g), B = C(e.b, d.b), K = q(d.r, d.g, d.b), X = k(d.r, d.g, d.b);
+    for (let g = 0; g < w.length; g += A) {
+      const M = w[g], E = w[g + 1], x = w[g + 2], I = st(M, E, x, K, X, o, a);
+      I > 0.01 && (w[g] = v(M + I * (M * S - M)), w[g + 1] = v(E + I * (E * H - E)), w[g + 2] = v(x + I * (x * B - x)));
+    }
+    let b = y(w, { raw: { width: p.width, height: p.height, channels: A } });
+    return _ && (l = P.join(R.tmpdir(), `zit-calibrate-icc-${process.pid}-${O()}.icc`), await T.writeFile(l, _), b = b.withIccProfile(l)), b = ft(b, u ?? ct(t)), { buffer: await b.toBuffer(), applied: { scaleR: S, scaleG: H, scaleB: B } };
+  } finally {
+    l && await T.rm(l, { force: !0 }), await m();
+  }
+}
+export {
+  bt as calibrateTargetFromSamples,
+  yt as normalizeBackgroundColor,
+  it as sampleBackgroundColor
+};

package/dist/composite/index.d.ts

@@ -0,0 +1,50 @@
+import { type SharpInput } from 'sharp';
+/** Anything sharp() itself accepts as an image source. */
+export type ImageInput = SharpInput;
+/** Corner the overlay is anchored to. Only 'bottom-right' ships in v1. */
+export type CompositePosition = 'bottom-right';
+export interface CompositeOverlayOptions {
+    /**
+     * Overlay width as a percentage (0-100) of the base image's SHORTER side
+     * (min(width, height)). The overlay is always forced to a 1:1 square at
+     * this size. Sizing off the shorter side (rather than width alone) keeps
+     * the badge from overflowing the base on its narrow axis for landscape
+     * (or portrait) images.
+     */
+    widthPercent: number;
+    /**
+     * Gap from the base image's edges, as a percentage of the base image's
+     * SHORTER side (used for both the horizontal and vertical offset) — same
+     * basis as `widthPercent`, for the same reason.
+     */
+    paddingPercent: number;
+    /** @default 'bottom-right' */
+    position?: CompositePosition;
+}
+export interface CompositeOverlayResult {
+    buffer: Buffer;
+    width: number;
+    height: number;
+}
+/**
+ * Composites `overlay` onto a corner of `base` and returns the result.
+ *
+ * The output buffer is always re-encoded as PNG, regardless of `base`'s
+ * original format.
+ */
+export declare function compositeOverlay(base: ImageInput, overlay: ImageInput, options: CompositeOverlayOptions): Promise<CompositeOverlayResult>;
+export interface CompositeBatchItem {
+    /** Caller-chosen identifier echoed back in the result (e.g. a filename or slug). */
+    ref: string;
+    image: ImageInput;
+}
+export interface CompositeBatchOptions extends CompositeOverlayOptions {
+    /** Max number of composites running at once. @default 4 */
+    concurrency?: number;
+}
+export interface CompositeBatchResult {
+    baseRef: string;
+    overlayRef: string;
+    result: CompositeOverlayResult;
+}
+export declare function compositeBatch(bases: CompositeBatchItem[], overlays: CompositeBatchItem[], options: CompositeBatchOptions): Promise<CompositeBatchResult[]>;

package/dist/composite/index.js

@@ -0,0 +1,56 @@
+import l from "sharp";
+async function g(r, n, i) {
+  const { widthPercent: t, paddingPercent: a, position: o = "bottom-right" } = i, f = l(r).rotate(), u = await f.metadata(), { width: c, height: h } = y(u);
+  if (!c || !h)
+    throw new Error("compositeOverlay: could not read base image dimensions");
+  const s = Math.min(c, h), e = Math.round(s * (t / 100));
+  if (!Number.isFinite(e) || e <= 0)
+    throw new Error(
+      `compositeOverlay: widthPercent ${t} of base shorter side ${s}px rounds to a non-positive overlay size`
+    );
+  const d = Math.round(s * (a / 100)), { left: p, top: w } = b(o, c, h, e, d);
+  if (p < 0 || w < 0)
+    throw new Error(
+      `compositeOverlay: overlay (${e}px) plus padding (${d}px) does not fit within the ${c}x${h} base image at position "${o}" — reduce widthPercent/paddingPercent`
+    );
+  const m = await l(n).rotate().resize(e, e, { fit: "cover" }).toBuffer();
+  return { buffer: await f.composite([{ input: m, left: p, top: w }]).png().toBuffer(), width: c, height: h };
+}
+function y(r) {
+  const { width: n, height: i, orientation: t } = r;
+  return t !== void 0 && t >= 5 && t <= 8 ? { width: i, height: n } : { width: n, height: i };
+}
+function b(r, n, i, t, a) {
+  if (r === "bottom-right")
+    return {
+      left: n - t - a,
+      top: i - t - a
+    };
+  {
+    const o = r;
+    throw new Error(`compositeOverlay: unsupported position "${String(o)}"`);
+  }
+}
+async function x(r, n, i) {
+  const { concurrency: t = 4, ...a } = i;
+  if (!Number.isFinite(t) || t < 1)
+    throw new Error(`compositeBatch: concurrency must be a finite number >= 1, received ${t}`);
+  const o = [];
+  for (const s of r)
+    for (const e of n)
+      o.push({ base: s, overlay: e });
+  const f = new Array(o.length);
+  let u = 0;
+  async function c() {
+    for (; u < o.length; ) {
+      const s = u++, { base: e, overlay: d } = o[s], p = await g(e.image, d.image, a);
+      f[s] = { baseRef: e.ref, overlayRef: d.ref, result: p };
+    }
+  }
+  const h = Math.max(1, Math.min(Math.floor(t), o.length));
+  return await Promise.all(Array.from({ length: h }, () => c())), f;
+}
+export {
+  x as compositeBatch,
+  g as compositeOverlay
+};

package/dist/exif/index.d.ts

@@ -0,0 +1,41 @@
+import { type SharpInput } from 'sharp';
+/**
+ * Extract the capture date from a raw EXIF buffer. A bounded TIFF/IFD parse
+ * resolves the tags in preference order — `DateTimeOriginal`, then
+ * `DateTimeDigitized`, then IFD0 `DateTime` — so edited photos (where
+ * `DateTime` is the modification date) still return when they were shot.
+ * Buffers that aren't TIFF-parseable fall back to scanning the bytes for the
+ * first timestamp-shaped text, preserving the previous behavior. Timestamps
+ * are interpreted as UTC (EXIF dates carry no time zone). Returns `null`
+ * when no usable date is found; never throws on malformed input.
+ */
+export declare function parseExifDate(buffer: Buffer | Uint8Array | null | undefined): Date | null;
+/**
+ * Physically rotate/flip pixel data to match the source's EXIF `Orientation`
+ * tag, then re-encode without metadata — except the ICC profile, which is
+ * retained with the pixel values untouched (`keepIccProfile`). Use this
+ * before serving an image so viewers that ignore EXIF orientation still
+ * display it upright.
+ *
+ * Retaining the profile keeps this usable as a mid-pipeline step (issue
+ * #71): a downstream encode can still choose to carry the profile through
+ * or to drop it — sharp's default pipeline genuinely converts pixels to
+ * sRGB via the embedded profile before dropping it. Stripping the profile
+ * HERE would lock a wide-gamut source into an early sRGB conversion.
+ */
+export declare function bakeOrientation(input: SharpInput): Promise<Buffer>;
+/**
+ * Re-encode an image with all metadata (EXIF, ICC profile, XMP, …) removed,
+ * without altering pixel orientation.
+ */
+export declare function stripExif(input: SharpInput): Promise<Buffer>;
+export type Orientation = 'landscape' | 'portrait' | 'square';
+/**
+ * Classify a pixel dimension pair as landscape, portrait, or square.
+ */
+export declare function deriveOrientation(width: number, height: number): Orientation;
+/**
+ * Filter a list of candidate variant widths down to those that don't exceed
+ * the source's width, preserving input order — never upscale.
+ */
+export declare function pickVariantWidths(srcWidth: number, widths: number[]): number[];