@takazudo/zudo-image-tweaker 0.1.0

package/dist/product-photo/index.js

@@ -0,0 +1,189 @@
+import P from "node:path";
+import { pathToFileURL as L } from "node:url";
+import m from "sharp";
+const Y = { r: 0, g: 0, b: 0, alpha: 0 }, D = { lightX: 0.3, lightY: 0.25, strength: 0.12, spread: 1.3 }, j = [
+  { blur: 100, opacity: 0.25, offsetX: 10, offsetY: 8, fadeStartRatio: -0.1 },
+  { blur: 40, opacity: 0.35, offsetX: 8, offsetY: 6, fadeStartRatio: 0 }
+], x = { blur: 8, opacity: 0.55, offsetX: 4, offsetY: 3 }, F = {
+  squash: 0.25,
+  offsetX: 65,
+  offsetY: 35,
+  blur: 75,
+  opacity: 0.45
+}, G = [
+  { blur: 120, opacity: 0.3, offsetX: 62, offsetY: 55, fadeStartRatio: -0.1 },
+  { blur: 52, opacity: 0.45, offsetX: 58, offsetY: 50, fadeStartRatio: 0 }
+], X = { blur: 12, opacity: 0.5, offsetX: 55, offsetY: 45 };
+async function q(o, t = {}) {
+  const { mode: n = "grounded", vignette: e, contactShadow: f, bottomShadows: s, projectedShadow: u } = t, { width: r, height: a } = await m(o).metadata();
+  if (!r || !a)
+    throw new Error("generateShadowLayers: could not read alphaImage dimensions.");
+  const c = await m(o).extractChannel(3).toColourspace("b-w").raw().toBuffer(), l = U(c, r, a), w = { ...D, ...e }, d = W(r, a, w);
+  if (n === "floating") {
+    const p = { ...F, ...u }, [g, B] = _(G, s), i = { ...X, ...f };
+    return Promise.all([
+      d,
+      H(c, r, a, l, p),
+      h(c, r, a, l, g),
+      h(c, r, a, l, B),
+      M(c, r, a, i)
+    ]);
+  }
+  const [y, b] = _(j, s), S = { ...x, ...f };
+  return Promise.all([
+    d,
+    h(c, r, a, l, y),
+    h(c, r, a, l, b),
+    M(c, r, a, S)
+  ]);
+}
+function _(o, t) {
+  return o.map((n, e) => ({ ...n, ...t?.[e] }));
+}
+function A(o) {
+  return Number.isFinite(o) ? Math.min(1, Math.max(0, o)) : 0;
+}
+function U(o, t, n) {
+  let e = n, f = 0, s = t, u = 0;
+  for (let r = 0; r < n; r++)
+    for (let a = 0; a < t; a++)
+      o[r * t + a] > 0 && (r < e && (e = r), r > f && (f = r), a < s && (s = a), a > u && (u = a));
+  return e > f ? null : { top: e, bottom: f + 1, left: s, right: u + 1 };
+}
+async function M(o, t, n, { blur: e, opacity: f, offsetX: s, offsetY: u }) {
+  const r = k(o, t, n, s, u), a = await m(r, { raw: { width: t, height: n, channels: 1 } }).toColourspace("b-w").blur(Math.max(e, 0.3)).linear(A(f), 0).png().toBuffer();
+  return C(a, t, n);
+}
+async function H(o, t, n, e, { squash: f, offsetX: s, offsetY: u, blur: r, opacity: a }) {
+  if (!e) return I(t, n);
+  const c = e.right - e.left, l = e.bottom - e.top, w = Buffer.alloc(c * l);
+  for (let B = 0; B < l; B++)
+    for (let i = 0; i < c; i++)
+      w[B * c + i] = o[(e.top + B) * t + (e.left + i)];
+  const d = Math.max(1, Math.round(l * f)), y = await m(w, { raw: { width: c, height: l, channels: 1 } }).toColourspace("b-w").resize(c, d, { fit: "fill" }).raw().toBuffer(), b = Buffer.alloc(t * n, 0), S = e.left + s, p = e.bottom + u;
+  for (let B = 0; B < d; B++) {
+    const i = p + B;
+    if (!(i < 0 || i >= n))
+      for (let T = 0; T < c; T++) {
+        const E = S + T;
+        E < 0 || E >= t || (b[i * t + E] = y[B * c + T]);
+      }
+  }
+  const g = await m(b, { raw: { width: t, height: n, channels: 1 } }).toColourspace("b-w").blur(Math.max(r, 0.3)).linear(A(a), 0).png().toBuffer();
+  return C(g, t, n);
+}
+async function h(o, t, n, e, { blur: f, opacity: s, offsetX: u, offsetY: r, fadeStartRatio: a }) {
+  if (!e) return I(t, n);
+  const c = A(s), l = k(o, t, n, u, r), w = await m(l, { raw: { width: t, height: n, channels: 1 } }).toColourspace("b-w").blur(Math.max(f, 0.3)).raw().toBuffer(), d = e.top + (e.bottom - e.top) * (0.5 + a), y = (e.bottom - d) * 0.5, b = Buffer.alloc(t * n, 0);
+  for (let p = 0; p < n; p++) {
+    let g;
+    p <= d ? g = 0 : y > 0 && p <= d + y ? g = (p - d) / y : g = 1;
+    const B = g * c;
+    for (let i = 0; i < t; i++)
+      b[p * t + i] = Math.round(w[p * t + i] * B);
+  }
+  const S = await m(b, { raw: { width: t, height: n, channels: 1 } }).toColourspace("b-w").png().toBuffer();
+  return C(S, t, n);
+}
+async function W(o, t, { lightX: n, lightY: e, strength: f, spread: s }) {
+  const u = A(f), r = Buffer.alloc(o * t, 0), a = o * n, c = t * e, l = Math.min(o, t) / 2, w = s * s;
+  for (let y = 0; y < t; y++) {
+    const b = (y - c) / l, S = b * b;
+    for (let p = 0; p < o; p++) {
+      const g = (p - a) / l, B = g * g + S, i = Math.min(1, (B / w) ** 0.75) * u * 255;
+      r[y * o + p] = Math.round(i);
+    }
+  }
+  const d = await m(r, { raw: { width: o, height: t, channels: 1 } }).toColourspace("b-w").png().toBuffer();
+  return C(d, o, t);
+}
+function k(o, t, n, e, f) {
+  const s = Buffer.alloc(t * n, 0);
+  for (let u = 0; u < n; u++) {
+    const r = u + f;
+    if (!(r < 0 || r >= n))
+      for (let a = 0; a < t; a++) {
+        const c = a + e;
+        c < 0 || c >= t || (s[r * t + c] = o[u * t + a]);
+      }
+  }
+  return s;
+}
+const R = /* @__PURE__ */ new Map();
+function $(o, t) {
+  const n = `${o}x${t}`;
+  let e = R.get(n);
+  return e || (e = m({ create: { width: o, height: t, channels: 3, background: { r: 0, g: 0, b: 0 } } }).png().toBuffer(), R.set(n, e)), e;
+}
+async function C(o, t, n) {
+  const e = await $(t, n);
+  return { buffer: await m(e).joinChannel(o).png().toBuffer(), blend: "multiply", offset: { x: 0, y: 0 } };
+}
+async function I(o, t) {
+  return { buffer: await m({ create: { width: o, height: t, channels: 4, background: Y } }).png().toBuffer(), blend: "multiply", offset: { x: 0, y: 0 } };
+}
+const v = 1600, V = 1440, Z = 90, N = { r: 0, g: 0, b: 0, alpha: 0 }, O = "@imgly/background-removal-node";
+async function ct(o) {
+  const t = await z(), n = Q(o), f = await (await t.removeBackground(n)).arrayBuffer();
+  return Buffer.from(f);
+}
+async function z() {
+  try {
+    return await import("@imgly/background-removal-node");
+  } catch (o) {
+    if (!K(o)) throw o;
+    const t = `Optional peer dependency "${O}" is not installed. Install it with: npm install ${O} (or pnpm add / yarn add ${O}).`, n = new Error(t);
+    throw n.code = "ERR_OPTIONAL_PEER_MISSING", n;
+  }
+}
+const J = /cannot find (?:package|module)\s+['"]([^'"]+)['"]/i;
+function K(o) {
+  let t = o;
+  for (let n = 0; n < 5 && t instanceof Error; n++) {
+    if (t.message.match(J)?.[1] === O) return !0;
+    t = t.cause;
+  }
+  return !1;
+}
+function Q(o) {
+  return Buffer.isBuffer(o) || o instanceof URL ? o : L(P.resolve(o)).href;
+}
+async function ft(o, t = {}) {
+  const { threshold: n = 10 } = t;
+  return m(o).trim({ background: N, threshold: n }).png().toBuffer();
+}
+async function st(o, t) {
+  const { background: n, size: e = v, quality: f = Z, shadow: s = !1 } = t, u = t.fit ?? Math.round(e * (V / v));
+  if (n == null)
+    throw new Error(
+      "composeProductPhoto requires a `background`: an image path/Buffer, or a flat `{ color }` fill."
+    );
+  const r = Math.round((e - u) / 2), a = await m(o).resize(u, u, { fit: "contain", background: N }).png().toBuffer(), c = nt(n, e);
+  let l;
+  if (s) {
+    const y = await m({
+      create: { width: e, height: e, channels: 4, background: N }
+    }).composite([{ input: a, left: r, top: r }]).png().toBuffer();
+    l = [...(await q(y, s === !0 ? {} : s)).map(tt), { input: y, left: 0, top: 0 }];
+  } else
+    l = [{ input: a, left: r, top: r }];
+  const { data: w, info: d } = await c.composite(l).jpeg({ quality: f }).toBuffer({ resolveWithObject: !0 });
+  return { buffer: w, width: d.width, height: d.height, format: "jpeg" };
+}
+function tt(o) {
+  return { input: o.buffer, left: o.offset.x, top: o.offset.y, blend: o.blend };
+}
+function ot(o) {
+  return typeof o == "object" && !Buffer.isBuffer(o) && "color" in o;
+}
+function nt(o, t) {
+  return ot(o) ? m({
+    create: { width: t, height: t, channels: 3, background: o.color }
+  }) : m(o).resize(t, t, { fit: "cover" });
+}
+export {
+  ft as alphaTrim,
+  st as composeProductPhoto,
+  q as generateShadowLayers,
+  ct as removeBackground
+};

package/dist/product-photo/shadow.d.ts

@@ -0,0 +1,48 @@
+export type ShadowMode = 'grounded' | 'floating';
+export type ShadowBlend = 'multiply' | 'over';
+export interface ShadowLayer {
+    buffer: Buffer;
+    blend: ShadowBlend;
+    offset: {
+        x: number;
+        y: number;
+    };
+}
+export interface ShadowTuning {
+    blur: number;
+    /** Valid range 0..1. Out-of-range values are clamped (prevents 8-bit raw-buffer wraparound). */
+    opacity: number;
+    offsetX: number;
+    offsetY: number;
+}
+export interface BottomShadowTuning extends ShadowTuning {
+    fadeStartRatio: number;
+}
+export interface ProjectedShadowTuning extends ShadowTuning {
+    squash: number;
+}
+export interface VignetteTuning {
+    lightX: number;
+    lightY: number;
+    /** Valid range 0..1. Out-of-range values are clamped (prevents 8-bit raw-buffer wraparound). */
+    strength: number;
+    spread: number;
+}
+export interface GenerateShadowLayersOptions {
+    mode?: ShadowMode;
+    vignette?: Partial<VignetteTuning>;
+    contactShadow?: Partial<ShadowTuning>;
+    bottomShadows?: Array<Partial<BottomShadowTuning> | undefined>;
+    projectedShadow?: Partial<ProjectedShadowTuning>;
+}
+/**
+ * Generate shadow/vignette layers for a product image that already has
+ * transparent background and sits at its final position on a
+ * canvas-sized (fully transparent elsewhere) RGBA image.
+ *
+ * Returns layers in back-to-front composite order. Each layer is already
+ * sized to match `alphaImage` and pre-positioned, so `offset` is always
+ * `{ x: 0, y: 0 }` — callers composite with `left/top: offset.x/y` and the
+ * given `blend` mode.
+ */
+export declare function generateShadowLayers(alphaImage: string | Buffer, options?: GenerateShadowLayersOptions): Promise<ShadowLayer[]>;

package/dist/run-BIjGA2Fu.js

@@ -0,0 +1,22 @@
+import { execFile as a } from "node:child_process";
+import c from "node:path";
+import { promisify as u } from "node:util";
+const m = u(a), f = 6e4;
+async function E(r, t, o = {}) {
+  const { timeoutMs: i = f, killSignal: n = "SIGKILL" } = o, { stdout: e, stderr: s } = await m(r, t, {
+    timeout: i,
+    killSignal: n
+  });
+  return { stdout: e, stderr: s };
+}
+function M(r) {
+  return c.resolve(r);
+}
+function T(r) {
+  return r?.code === "ENOENT";
+}
+export {
+  M as a,
+  T as i,
+  E as r
+};

package/dist/square/index.d.ts

@@ -0,0 +1,98 @@
+import { type Color } from 'sharp';
+export interface SquareResult {
+    buffer: Buffer;
+    width: number;
+    height: number;
+}
+export type SquareAnchor = 'top' | 'center' | 'bottom';
+export interface CropToSquareOptions {
+    /**
+     * Which part of the image to keep.
+     * For PORTRAIT images (h > w): top=keep top rows, bottom=keep bottom rows.
+     * For LANDSCAPE images (w > h): top=keep left columns, bottom=keep right columns
+     * (the anchor names refer to the crop axis edge, not an absolute screen position).
+     */
+    anchor?: SquareAnchor;
+}
+export interface PadToSquareOptions {
+    background?: Color;
+}
+export interface PadToSquareCenteredOptions {
+    background?: Color;
+}
+export interface InsetOnSquareOptions {
+    /** Fractional border per edge (0 <= margin < 0.5). Default 0.10. */
+    margin?: number;
+    background?: Color;
+}
+export interface TrimPadSquareOptions {
+    /** Fractional border on the content's longer axis (0 <= margin < 0.5). Default 0.10. */
+    margin?: number;
+    /** 0..255; pixels with all of R,G,B >= this are treated as background. Default 245. */
+    threshold?: number;
+    background?: Color;
+}
+/**
+ * Crop an image to a square using sharp extract.
+ *
+ * @returns output dimensions (always square)
+ */
+export declare function cropToSquare(input: Buffer, opts?: CropToSquareOptions): Promise<SquareResult>;
+/**
+ * Extend canvas to square adding background color ONLY on the narrow axis:
+ *   portrait  (h > w): pad LEFT  by (h−w) — content becomes right-aligned
+ *   landscape (w > h): pad TOP   by (w−h) — content becomes bottom-aligned
+ *   square    (h = w): no-op
+ *
+ * Right and bottom are NEVER extended.
+ *
+ * @returns output dimensions (always square)
+ */
+export declare function padToSquare(input: Buffer, opts?: PadToSquareOptions): Promise<SquareResult>;
+/**
+ * Extend canvas to square adding background color SYMMETRICALLY on BOTH sides
+ * of the narrow axis, keeping the original content CENTERED (no crop):
+ *   portrait  (h > w): pad LEFT and RIGHT by (h−w)/2 each — content stays horizontally centered
+ *   landscape (w > h): pad TOP and BOTTOM by (w−h)/2 each — content stays vertically centered
+ *   square    (h = w): no-op
+ *
+ * When the difference is odd, the extra single pixel is added to the
+ * right (portrait) / bottom (landscape) so the output stays square.
+ *
+ * @returns output dimensions (always square)
+ */
+export declare function padToSquareCentered(input: Buffer, opts?: PadToSquareCenteredOptions): Promise<SquareResult>;
+/**
+ * Shrink a SQUARE image's content and center it on a background-color square canvas
+ * of the SAME side length, leaving a `margin*N` border on every edge:
+ *   content scales to round(N·(1−2·margin)), centered on an N×N canvas.
+ *   margin 0.10 (default) → content ~80%, with a 10% border all around.
+ *
+ * Intended for square inputs. For a non-square input the SHORTER side is treated
+ * as N, the content is scaled to fit inside the inset box preserving aspect
+ * ratio, and centered on the N×N canvas.
+ *
+ * NOTE: insets the WHOLE input, so any pre-existing border STACKS on top of the
+ * new one (a 10% inset of an image already framed at 10% yields ~18%). Use
+ * trimPadSquare instead when an EXACT margin is required regardless of input.
+ *
+ * @returns output dimensions (always square N×N)
+ */
+export declare function insetOnSquare(input: Buffer, opts?: InsetOnSquareOptions): Promise<SquareResult>;
+/**
+ * Trim the near-background border down to the content bounding box, then pad
+ * a SQUARE canvas leaving an EXACT `margin` fraction on the content's LONGER
+ * axis.
+ *
+ * This differs from insetOnSquare in one decisive way: the existing border is
+ * REMOVED first, so a pre-framed image does not stack margins. A portrait subject
+ * ends up with `margin` border top + bottom (the binding axis) and larger symmetric
+ * left/right margins; landscape is the reverse. The trimmed content is composited
+ * 1:1 (never resampled) onto the square, so no detail is lost.
+ *
+ * Background detection: a pixel counts as background when all of R,G,B are >=
+ * `threshold`. Tune `threshold` down if subtle shadows must be kept as content.
+ *
+ * @returns square output dimensions
+ */
+export declare function trimPadSquare(input: Buffer, opts?: TrimPadSquareOptions): Promise<SquareResult>;

package/dist/square/index.js

@@ -0,0 +1,89 @@
+import l from "sharp";
+const p = { r: 255, g: 255, b: 255, alpha: 1 };
+async function m(h) {
+  const s = await l(h).rotate().png().toBuffer(), e = l(s), i = await e.metadata();
+  if (!i.width || !i.height)
+    throw new Error("Could not read dimensions from input image");
+  return { img: e, width: i.width, height: i.height };
+}
+async function E(h, s = {}) {
+  const e = s.anchor ?? "center";
+  if (!["top", "center", "bottom"].includes(e))
+    throw new Error(`Invalid anchor "${e}". Must be top | center | bottom.`);
+  const { img: i, width: n, height: o } = await m(h), c = Math.min(n, o);
+  let a = 0, f = 0;
+  if (n >= o) {
+    const t = n - c;
+    e === "top" ? a = 0 : e === "center" ? a = Math.floor(t / 2) : a = t;
+  } else {
+    const t = o - c;
+    e === "top" ? f = 0 : e === "center" ? f = Math.floor(t / 2) : f = t;
+  }
+  return { buffer: await i.extract({ left: a, top: f, width: c, height: c }).toBuffer(), width: c, height: c };
+}
+async function I(h, s = {}) {
+  const e = s.background ?? p, { img: i, width: n, height: o } = await m(h);
+  if (n === o)
+    return { buffer: await i.toBuffer(), width: n, height: o };
+  let c;
+  o > n ? c = { top: 0, bottom: 0, left: o - n, right: 0, background: e } : c = { top: n - o, bottom: 0, left: 0, right: 0, background: e };
+  const a = await i.ensureAlpha().extend(c).toBuffer(), f = Math.max(n, o);
+  return { buffer: a, width: f, height: f };
+}
+async function S(h, s = {}) {
+  const e = s.background ?? p, { img: i, width: n, height: o } = await m(h);
+  if (n === o)
+    return { buffer: await i.toBuffer(), width: n, height: o };
+  let c;
+  if (o > n) {
+    const r = o - n, t = Math.floor(r / 2), u = r - t;
+    c = { top: 0, bottom: 0, left: t, right: u, background: e };
+  } else {
+    const r = n - o, t = Math.floor(r / 2), u = r - t;
+    c = { top: t, bottom: u, left: 0, right: 0, background: e };
+  }
+  const a = await i.ensureAlpha().extend(c).toBuffer(), f = Math.max(n, o);
+  return { buffer: a, width: f, height: f };
+}
+async function X(h, s = {}) {
+  const e = s.margin ?? 0.1, i = s.background ?? p;
+  if (!(e >= 0 && e < 0.5))
+    throw new Error(`Invalid margin "${e}". Must be 0 ≤ margin < 0.5.`);
+  const { img: n, width: o, height: c } = await m(h), a = Math.min(o, c), f = Math.max(1, Math.round(a * (1 - 2 * e))), { data: r, info: t } = await n.resize(f, f, { fit: "inside" }).toBuffer({ resolveWithObject: !0 }), u = Math.round((a - t.width) / 2), g = Math.round((a - t.height) / 2);
+  return { buffer: await l({
+    create: { width: a, height: a, channels: 4, background: i }
+  }).composite([{ input: r, top: g, left: u }]).png().toBuffer(), width: a, height: a };
+}
+const k = 10;
+function A(h, s, e, i, n) {
+  let o = s, c = e, a = -1, f = -1;
+  for (let r = 0; r < e; r++)
+    for (let t = 0; t < s; t++) {
+      const u = (r * s + t) * i, g = h[u], w = h[u + 1], d = h[u + 2];
+      (i >= 4 ? h[u + 3] : 255) <= k || g >= n && w >= n && d >= n || (t < o && (o = t), t > a && (a = t), r < c && (c = r), r > f && (f = r));
+    }
+  return a < 0 ? null : { minX: o, minY: c, maxX: a, maxY: f };
+}
+async function q(h, s = {}) {
+  const e = s.margin ?? 0.1, i = s.threshold ?? 245, n = s.background ?? p;
+  if (!(e >= 0 && e < 0.5))
+    throw new Error(`Invalid margin "${e}". Must be 0 ≤ margin < 0.5.`);
+  if (!Number.isInteger(i) || i < 0 || i > 255)
+    throw new Error(`Invalid threshold "${i}". Must be an integer 0 ≤ threshold ≤ 255.`);
+  const { img: o, width: c, height: a } = await m(h), { data: f, info: r } = await o.clone().ensureAlpha().raw().toBuffer({ resolveWithObject: !0 }), t = A(f, r.width, r.height, r.channels, i);
+  if (!t) {
+    const b = Math.max(c, a);
+    return { buffer: await l({
+      create: { width: b, height: b, channels: 4, background: n }
+    }).png().toBuffer(), width: b, height: b };
+  }
+  const u = t.maxX - t.minX + 1, g = t.maxY - t.minY + 1, w = Math.max(u, g), d = Math.round(w / (1 - 2 * e)), M = await o.extract({ left: t.minX, top: t.minY, width: u, height: g }).toBuffer(), x = Math.round((d - u) / 2), B = Math.round((d - g) / 2);
+  return { buffer: await l({ create: { width: d, height: d, channels: 4, background: n } }).composite([{ input: M, top: B, left: x }]).png().toBuffer(), width: d, height: d };
+}
+export {
+  E as cropToSquare,
+  X as insetOnSquare,
+  I as padToSquare,
+  S as padToSquareCentered,
+  q as trimPadSquare
+};

package/dist/variants/engine.d.ts

@@ -0,0 +1,38 @@
+import { type ImageEntry, type ItemResult, type ProcessFailure, type ProcessImagesConfig, type ProcessOneConfig, type ProcessSummary } from './types.js';
+/** Source file extensions the directory scanner treats as images. */
+export declare const SUPPORTED_IMAGE_EXTENSIONS: string[];
+export declare const IMAGE_EXTENSION_REGEX: RegExp;
+/**
+ * Thrown for a stage-specific processing failure. `processImages` catches
+ * it to record which pipeline stage failed; a caller invoking `processOne`
+ * directly can read `stage` and the underlying `cause`.
+ */
+export declare class VariantProcessingError extends Error {
+    readonly stage: ProcessFailure['stage'];
+    constructor(stage: ProcessFailure['stage'], cause: unknown);
+}
+/**
+ * The widths actually emitted for a source: every configured width that
+ * doesn't upscale it (via `/exif`'s pickVariantWidths), or — when the
+ * source is smaller than every configured width — a single variant at the
+ * source's own width so even a tiny image gets one representation.
+ */
+export declare function selectVariantWidths(sourceWidth: number, widths: number[]): number[];
+/**
+ * Process a single image end-to-end: HEIC conversion, content-hash cache
+ * check, corruption repair, blurhash, width variants (or byte-for-byte
+ * passthrough for animated GIF/WebP/APNG — see ANIMATED_PAGE_FORMATS), and
+ * optional OGP — dispatched by the entry's tag.
+ *
+ * Throws {@link VariantProcessingError} on a genuine processing failure
+ * (carrying the failing `stage`); returns a `skipped` result for a
+ * deliberate skip (cache hit, or a non-image guard trip).
+ */
+export declare function processOne(entry: ImageEntry, config: ProcessOneConfig): Promise<ItemResult>;
+/**
+ * Process every source image from `inputDir` and/or an explicit `files`
+ * list, with bounded concurrency and a collect-and-continue error policy:
+ * one bad file lands in `ProcessSummary.failed[]` and never aborts the run.
+ * Orphan output directories are pruned only when `cleanupOrphans` is set.
+ */
+export declare function processImages(config: ProcessImagesConfig): Promise<ProcessSummary>;

package/dist/variants/feature-detect.d.ts

@@ -0,0 +1,8 @@
+/** Whether the `file` type-identification binary is available. */
+export declare function hasFileBinary(): Promise<boolean>;
+/** Whether ImageMagick's `magick` binary is available. */
+export declare function hasMagick(): Promise<boolean>;
+/** Whether `ffmpeg` is available. */
+export declare function hasFfmpeg(): Promise<boolean>;
+/** Clear the memoised detection results. For tests only. */
+export declare function resetFeatureDetectionCache(): void;

package/dist/variants/hash-cache.d.ts

@@ -0,0 +1,63 @@
+import type { TagMode, VariantMetadata } from './types.js';
+/** The engine's per-image cache sidecar. Purely internal — not a metadata DB. */
+export interface CacheEntry {
+    /** Content hash of the source file the cached outputs were produced from. */
+    hash: string;
+    /**
+     * Fingerprint of the output-affecting config (quality, widths, OGP options,
+     * …) the cached outputs were produced with. A change invalidates the cache
+     * even when the source bytes are unchanged.
+     */
+    configHash: string;
+    /**
+     * The tag mode the cached outputs were produced under. Renaming a source
+     * to change only its tag (e.g. `photo__og.jpg` → `photo__ogonly.jpg`)
+     * keeps the same bytes and slug, so the mode is compared to stop the old
+     * outputs from satisfying the new mode's expected-output subset.
+     */
+    mode: TagMode;
+    /** Whether the source was handled as an animated passthrough (GIF/WebP/APNG). */
+    animated: boolean;
+    /**
+     * The exact filenames this run emitted into the slug directory. Compared
+     * against the current config's expected filenames so a changed custom
+     * `outputName` scheme — including at the sub-min-width fallback, which the
+     * config fingerprint can't capture pre-probe — is treated as a miss rather
+     * than a stale hit on a lingering older-scheme file.
+     */
+    outputs: string[];
+    /**
+     * On-disk byte size of every filename in `outputs`, keyed by filename.
+     * Validated against the actual file size on a cache hit so a truncated
+     * output — e.g. one left by a crash mid-write under an older, non-atomic
+     * version — is treated as a miss instead of a poisoned hit. An entry
+     * written before this field existed lacks it entirely, which the cache
+     * check reads as "unverifiable" and reprocesses once.
+     */
+    outputSizes: Record<string, number>;
+    /** Last emitted metadata record (null for OGP-only images), replayed on a cache hit. */
+    metadata: VariantMetadata | null;
+}
+/** Content-hash a file's bytes with xxhash (64-bit), returned as a hex string. */
+export declare function hashFile(filePath: string): Promise<string>;
+/**
+ * Produce `filePath` atomically: `produce` writes to a sibling temp path in
+ * the SAME directory, which is then renamed over the target. rename(2) is
+ * atomic within a filesystem, so a reader never observes a half-written file
+ * and a crash before the rename leaves the previous version intact — never a
+ * truncated one at the final path. On any failure the temp file is removed.
+ *
+ * Invariant this establishes for every cached output: a file that exists at
+ * its final path is complete. `produce`'s return value (e.g. sharp's
+ * OutputInfo) is passed through so callers keep the size/metadata they need.
+ */
+export declare function writeAtomicVia<T>(filePath: string, produce: (tmpPath: string) => Promise<T>): Promise<T>;
+/**
+ * Write `data` to `filePath` atomically via {@link writeAtomicVia}: staged in
+ * a sibling temp file, then renamed over the target.
+ */
+export declare function writeFileAtomic(filePath: string, data: string | Buffer): Promise<void>;
+/** Read and parse a cache sidecar, or null when it's absent or unparseable. */
+export declare function readCache(cachePath: string): Promise<CacheEntry | null>;
+/** Atomically write a cache sidecar. */
+export declare function writeCache(cachePath: string, entry: CacheEntry): Promise<void>;

package/dist/variants/heic.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether a source should be treated as HEIC/HEIF. Trusts the extension
+ * for `.heic`/`.heif`, and additionally sniffs `.jpg`/`.jpeg` files with
+ * the `file` binary because cameras and messaging apps routinely hand out
+ * HEIF payloads under a `.jpg` name. When `file` is unavailable, only the
+ * extension is consulted.
+ */
+export declare function isHeicSource(inputPath: string): Promise<boolean>;
+/**
+ * Heuristic guard against non-image files that were saved with an image
+ * extension — most commonly an HTML error page or a plain-text response
+ * downloaded to `photo.jpg`. Returns false (don't skip) whenever `file`
+ * can't make the determination.
+ */
+export declare function isNonImageFile(inputPath: string): Promise<boolean>;

package/dist/variants/index.d.ts

@@ -0,0 +1,5 @@
+export { IMAGE_EXTENSION_REGEX, SUPPORTED_IMAGE_EXTENSIONS, processImages, processOne, selectVariantWidths, VariantProcessingError, } from './engine.js';
+export { defaultTagParser, noTagParser } from './tags.js';
+export { PHOTO_VARIANT_WIDTHS, photoVariantsPreset } from './presets.js';
+export { DEFAULT_CACHE_FILENAME, DEFAULT_CONCURRENCY, DEFAULT_FORMATS, DEFAULT_OGP_FILENAME, DEFAULT_QUALITY, DEFAULT_WIDTHS, } from './types.js';
+export type { ImageEntry, ItemResult, ItemStatus, OgpOutput, OutputNameFn, ParsedTag, ProcessFailure, ProcessImagesConfig, ProcessOneConfig, ProcessSummary, TagMode, TagParser, VariantMetadata, VariantOutput, } from './types.js';

package/dist/variants/index.js

@@ -0,0 +1,19 @@
+import { D as E, a as T, b as r, c as A, d as e, e as _, I, P as D, S as o, V as t, f as F, n as L, p as N, g as O, h as P, s as U } from "../presets-PTxNoMdy.js";
+export {
+  E as DEFAULT_CACHE_FILENAME,
+  T as DEFAULT_CONCURRENCY,
+  r as DEFAULT_FORMATS,
+  A as DEFAULT_OGP_FILENAME,
+  e as DEFAULT_QUALITY,
+  _ as DEFAULT_WIDTHS,
+  I as IMAGE_EXTENSION_REGEX,
+  D as PHOTO_VARIANT_WIDTHS,
+  o as SUPPORTED_IMAGE_EXTENSIONS,
+  t as VariantProcessingError,
+  F as defaultTagParser,
+  L as noTagParser,
+  N as photoVariantsPreset,
+  O as processImages,
+  P as processOne,
+  U as selectVariantWidths
+};

package/dist/variants/presets.d.ts

@@ -0,0 +1,18 @@
+/** Width ladder the photo preset emits. */
+export declare const PHOTO_VARIANT_WIDTHS: number[];
+/**
+ * Config fragment reproducing the source photo pipeline on top of the same
+ * engine: a smaller [400, 800, 1600] width ladder, EXIF orientation baked
+ * into pixels and all metadata stripped (see the `stripMetadata` behavior
+ * matrix in ProcessOneConfig), and no OGP or filename-tag dispatch (every
+ * file is a plain full-variant image).
+ *
+ * Spread it into a call and add the paths, e.g.
+ * `processImages({ ...photoVariantsPreset, inputDir, outputDir })`.
+ */
+export declare const photoVariantsPreset: {
+    widths: number[];
+    bakeExifOrientation: true;
+    stripMetadata: true;
+    tagParser: import("./types.js").TagParser;
+};

package/dist/variants/repair.d.ts

@@ -0,0 +1,28 @@
+/** Whether an error looks like recoverable bitstream corruption rather than a non-image. */
+export declare function isCorruptionError(error: unknown): boolean;
+export interface RepairCorruptedImageOptions {
+    /**
+     * Before attempting repair, copy the untouched corrupt source to a sibling
+     * `<name>.corrupted.bak`. Off by default — repair otherwise never touches the
+     * caller's file at all. An existing `.bak` is kept, never overwritten.
+     * @default false
+     */
+    backupCorrupted?: boolean;
+}
+/**
+ * Attempt to recover a corrupt image by re-encoding it through an external
+ * tool, returning a clean image buffer or null if repair isn't possible.
+ *
+ * Repair is best-effort and entirely optional. When ImageMagick (`magick`) is
+ * available it is tried twice — first a strip + colourspace normalise, then a
+ * format-swap re-decode through the sibling raster format (jpg<->png), which
+ * recovers a bitstream the same-format pass can't. `ffmpeg` is tried last.
+ * Each strategy runs only if its binary is feature-detected; on a machine with
+ * neither (e.g. plain Linux without ImageMagick) this warns and returns null
+ * rather than failing — a missing optional binary must never break a run.
+ *
+ * The caller's source file is never modified. With `backupCorrupted` set, a
+ * sibling `<name>.corrupted.bak` copy is written before the attempt (the source
+ * itself is still left untouched); by default no backup is made.
+ */
+export declare function repairCorruptedImage(inputPath: string, options?: RepairCorruptedImageOptions): Promise<Buffer | null>;