img-upload-kit 1.1.1 → 2.0.1

package/dist/bin.js

@@ -0,0 +1,1186 @@
+#!/usr/bin/env node
+
+// src/cli/commands.ts
+import fs4 from "fs/promises";
+import path4 from "path";
+import { Command } from "commander";
+
+// src/blur/pathMapper.ts
+var DEFAULT_CDN_PATTERNS = [
+  /^https?:\/\/[^/]+\.supabase\.co\/storage\/v1\/object\/public\/([^/]+)\/(.+)$/,
+  /^https?:\/\/[^/]+\.r2\.dev\/(.+)$/,
+  /^https?:\/\/[^/]+\.amazonaws\.com\/(.+)$/,
+  /^https?:\/\/[^/]+\.cloudflare\.com\/(.+)$/,
+  /^https?:\/\/cdn\.[^/]+\/(.+)$/
+];
+function normalizeImagePath(imageSrc, options = {}) {
+  const originalPath = imageSrc;
+  let normalizedPath = imageSrc;
+  let isExternal = false;
+  try {
+    if (imageSrc.startsWith("data:") || imageSrc.startsWith("blob:")) {
+      return {
+        normalizedPath: imageSrc,
+        isExternal: false,
+        originalPath
+      };
+    }
+    const patterns = options.cdnPatterns || DEFAULT_CDN_PATTERNS;
+    if (imageSrc.startsWith("http://") || imageSrc.startsWith("https://")) {
+      const url = new URL(imageSrc);
+      isExternal = true;
+      const cleanUrlNoQuery = `${url.origin}${url.pathname}`;
+      for (const pattern of patterns) {
+        const match = cleanUrlNoQuery.match(pattern);
+        if (match) {
+          const groups = match.slice(1).filter(Boolean);
+          const pathPart = groups.join("/");
+          normalizedPath = "/" + pathPart.replace(/^\/+/, "");
+          break;
+        }
+      }
+      if (normalizedPath === imageSrc) {
+        normalizedPath = url.pathname;
+      }
+    } else {
+      normalizedPath = normalizedPath.split("?")[0].split("#")[0];
+    }
+    normalizedPath = normalizedPath.replace(/\\/g, "/").replace(/^\.\.?\//g, "");
+    if (!normalizedPath.startsWith("/")) {
+      normalizedPath = "/" + normalizedPath;
+    }
+    const prefixesToStrip = options.stripPrefixes || ["/public/"];
+    for (const prefix of prefixesToStrip) {
+      if (normalizedPath.startsWith(prefix)) {
+        normalizedPath = "/" + normalizedPath.slice(prefix.length).replace(/^\/+/, "");
+      }
+    }
+    const segments = normalizedPath.split("/").filter(Boolean);
+    const filename = segments[segments.length - 1];
+    const folder = segments.length > 1 ? segments.slice(0, -1).join("/") : void 0;
+    const dotIdx = filename ? filename.lastIndexOf(".") : -1;
+    const extension = filename && dotIdx > 0 ? filename.slice(dotIdx + 1).toLowerCase() : void 0;
+    return {
+      normalizedPath,
+      folder,
+      filename,
+      extension,
+      isExternal,
+      originalPath
+    };
+  } catch {
+    return {
+      normalizedPath: imageSrc,
+      isExternal: false,
+      originalPath
+    };
+  }
+}
+
+// src/cli/generator.ts
+import fs2 from "fs/promises";
+import path2 from "path";
+
+// src/server/optimization/types.ts
+var BLUR_PLACEHOLDER_WIDTH = 128;
+var BLUR_PLACEHOLDER_FALLBACK_WIDTH = 96;
+var BLUR_PLACEHOLDER_QUALITY = 80;
+var BLUR_PLACEHOLDER_MAX_CHARS = 8e3;
+var EDGE_COLOR_FALLBACK = "#6B7280";
+var EDGE_WHITE_FALLBACK = "#F9FAFB";
+var WHITE_DOMINANCE_RATIO = 1.35;
+
+// src/server/optimization/loadSharp.ts
+var SHARP_MISSING_MESSAGE = "img-upload-kit/server requires `sharp` \u2014 run `npm i sharp`";
+var sharpPromise = null;
+function unwrapDefault(mod) {
+  const record = mod;
+  return record && record.default !== void 0 ? record.default : mod;
+}
+function loadSharp() {
+  if (!sharpPromise) {
+    sharpPromise = import("sharp").then(
+      (mod) => unwrapDefault(mod),
+      (error) => {
+        sharpPromise = null;
+        throw new Error(SHARP_MISSING_MESSAGE, { cause: error });
+      }
+    );
+  }
+  return sharpPromise;
+}
+
+// src/server/optimization/blurGenerator.ts
+import { encode as encodeBlurHash } from "blurhash";
+
+// src/utils/color.ts
+function hexToRgb(hex) {
+  const normalized = hex.replace("#", "");
+  const expanded = normalized.length === 3 ? normalized.split("").map((char) => char + char).join("") : normalized;
+  const padded = expanded.padEnd(6, "0").slice(0, 6);
+  const value = Number.parseInt(padded, 16);
+  if (Number.isNaN(value)) {
+    return { r: 245, g: 245, b: 245 };
+  }
+  return {
+    r: value >> 16 & 255,
+    g: value >> 8 & 255,
+    b: value & 255
+  };
+}
+function rgbToHex(r, g, b) {
+  const clamp = (v) => Math.max(0, Math.min(255, Math.round(v)));
+  const value = clamp(r) << 16 | clamp(g) << 8 | clamp(b);
+  return `#${value.toString(16).padStart(6, "0").toUpperCase()}`;
+}
+
+// src/server/optimization/colorHistogram.ts
+async function extractEnhancedColorFromBuffer(buffer, mode = "balanced") {
+  const sharp = await loadSharp();
+  try {
+    const metadata = await sharp(buffer).metadata();
+    const maxSize = 400;
+    const needsResize = metadata.width && metadata.height && (metadata.width > maxSize || metadata.height > maxSize);
+    if (needsResize) {
+      const resized = await sharp(buffer).resize(maxSize, maxSize, {
+        fit: "inside",
+        kernel: "lanczos3",
+        withoutEnlargement: true
+      }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+      return extractDominantColorHistogramAdvanced(
+        resized.data,
+        resized.info.width,
+        resized.info.height,
+        mode
+      );
+    }
+    const raw = await sharp(buffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return extractDominantColorHistogramAdvanced(
+      raw.data,
+      raw.info.width,
+      raw.info.height,
+      mode
+    );
+  } catch {
+    const stats = await sharp(buffer).resize(64, 64, { fit: "cover", kernel: "lanczos3" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return extractDominantColorHistogram(stats.data);
+  }
+}
+function extractDominantColorHistogramAdvanced(data, width, height, mode) {
+  const colorMap = /* @__PURE__ */ new Map();
+  const bucketSize = 16;
+  const centerWeight = 1.5;
+  const centerX = width / 2 || 1;
+  const centerY = height / 2 || 1;
+  let whiteWeight = 0;
+  for (let i = 0; i < data.length; i += 4) {
+    const alpha = data[i + 3];
+    if (alpha !== void 0 && alpha < 8) continue;
+    const r2 = data[i];
+    const g2 = data[i + 1];
+    const b2 = data[i + 2];
+    const brightness = (r2 + g2 + b2) / 3;
+    if (brightness < 10) continue;
+    const pixelIndex = i / 4;
+    const x = pixelIndex % width;
+    const y = Math.floor(pixelIndex / width);
+    const dx = (x - centerX) / centerX;
+    const dy = (y - centerY) / centerY;
+    const distanceFromCenter = Math.sqrt(dx * dx + dy * dy);
+    let weight = 1;
+    if (mode === "edge") {
+      const edgeThicknessX = Math.max(1, Math.floor(width * 0.12));
+      const edgeThicknessY = Math.max(1, Math.floor(height * 0.12));
+      const onLeftEdge = x < edgeThicknessX;
+      const onRightEdge = x >= width - edgeThicknessX;
+      const onTopEdge = y < edgeThicknessY;
+      const onBottomEdge = y >= height - edgeThicknessY;
+      if (!(onLeftEdge || onRightEdge || onTopEdge || onBottomEdge)) {
+        continue;
+      }
+      const distanceToNearestEdge = Math.min(
+        x,
+        y,
+        width - 1 - x,
+        height - 1 - y
+      );
+      const maxEdgeDistance = Math.max(edgeThicknessX, edgeThicknessY) || 1;
+      const edgeFactor = 1 - distanceToNearestEdge / maxEdgeDistance;
+      weight = 1 + edgeFactor * 3;
+    } else {
+      weight = distanceFromCenter < 0.5 ? centerWeight : 1;
+    }
+    const isNearWhite = r2 >= 245 && g2 >= 245 && b2 >= 245;
+    if (isNearWhite) {
+      whiteWeight += weight;
+      continue;
+    }
+    const bucketR = Math.floor(r2 / bucketSize) * bucketSize;
+    const bucketG = Math.floor(g2 / bucketSize) * bucketSize;
+    const bucketB = Math.floor(b2 / bucketSize) * bucketSize;
+    const key = `${bucketR},${bucketG},${bucketB}`;
+    colorMap.set(key, (colorMap.get(key) || 0) + weight);
+  }
+  if (!colorMap.size) {
+    return whiteWeight > 0 ? EDGE_WHITE_FALLBACK : EDGE_COLOR_FALLBACK;
+  }
+  let maxCount = 0;
+  let dominantColor = "64,64,80";
+  let totalColorWeight = 0;
+  colorMap.forEach((count, color) => {
+    totalColorWeight += count;
+    if (count > maxCount) {
+      maxCount = count;
+      dominantColor = color;
+    }
+  });
+  const whiteDominates = whiteWeight > 0 && whiteWeight >= totalColorWeight * WHITE_DOMINANCE_RATIO;
+  if (whiteDominates) {
+    return EDGE_WHITE_FALLBACK;
+  }
+  const [r, g, b] = dominantColor.split(",").map(Number);
+  return rgbToHex(r, g, b);
+}
+function extractDominantColorHistogram(data) {
+  const colorMap = /* @__PURE__ */ new Map();
+  const bucketSize = 16;
+  let whiteWeight = 0;
+  for (let i = 0; i < data.length; i += 4) {
+    const alpha = data[i + 3];
+    if (alpha !== void 0 && alpha < 8) continue;
+    const r2 = Math.floor(data[i] / bucketSize) * bucketSize;
+    const g2 = Math.floor(data[i + 1] / bucketSize) * bucketSize;
+    const b2 = Math.floor(data[i + 2] / bucketSize) * bucketSize;
+    if (r2 >= 240 && g2 >= 240 && b2 >= 240) {
+      whiteWeight += 1;
+      continue;
+    }
+    const key = `${r2},${g2},${b2}`;
+    colorMap.set(key, (colorMap.get(key) || 0) + 1);
+  }
+  if (!colorMap.size) {
+    return whiteWeight > 0 ? EDGE_WHITE_FALLBACK : EDGE_COLOR_FALLBACK;
+  }
+  let maxCount = 0;
+  let dominantColor = "64,64,80";
+  let totalColorWeight = 0;
+  colorMap.forEach((count, color) => {
+    totalColorWeight += count;
+    if (count > maxCount) {
+      maxCount = count;
+      dominantColor = color;
+    }
+  });
+  const whiteDominates = whiteWeight > 0 && whiteWeight >= totalColorWeight * WHITE_DOMINANCE_RATIO;
+  if (whiteDominates) {
+    return EDGE_WHITE_FALLBACK;
+  }
+  const [r, g, b] = dominantColor.split(",").map(Number);
+  return rgbToHex(r, g, b);
+}
+
+// src/server/optimization/edgeColorExtractor.ts
+async function extractEdgeColorsFromBuffer(buffer) {
+  const sharp = await loadSharp();
+  try {
+    const sample = await sharp(buffer).resize(400, 400, {
+      fit: "inside",
+      kernel: "lanczos3",
+      withoutEnlargement: true
+    }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return computeEdgeColorSet(
+      sample.data,
+      sample.info.width,
+      sample.info.height
+    );
+  } catch {
+    try {
+      const fallback = await extractEnhancedColorFromBuffer(buffer, "edge");
+      return {
+        top: fallback,
+        right: fallback,
+        bottom: fallback,
+        left: fallback
+      };
+    } catch {
+      return {
+        top: EDGE_COLOR_FALLBACK,
+        right: EDGE_COLOR_FALLBACK,
+        bottom: EDGE_COLOR_FALLBACK,
+        left: EDGE_COLOR_FALLBACK
+      };
+    }
+  }
+}
+function computeEdgeColorSet(data, width, height) {
+  const thicknessX = Math.max(2, Math.floor(width * 0.12));
+  const thicknessY = Math.max(2, Math.floor(height * 0.12));
+  const bucketSize = 16;
+  const edgeMaps = {
+    top: /* @__PURE__ */ new Map(),
+    right: /* @__PURE__ */ new Map(),
+    bottom: /* @__PURE__ */ new Map(),
+    left: /* @__PURE__ */ new Map()
+  };
+  const whiteEdgeStrength = {
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0
+  };
+  const accumulateEdgeSample = (edge, weight, key, isWhiteSample) => {
+    if (weight <= 0) return;
+    if (isWhiteSample) {
+      whiteEdgeStrength[edge] += weight;
+      return;
+    }
+    edgeMaps[edge].set(key, (edgeMaps[edge].get(key) || 0) + weight);
+  };
+  for (let i = 0; i < data.length; i += 4) {
+    const r = data[i];
+    const g = data[i + 1];
+    const b = data[i + 2];
+    const alpha = data[i + 3];
+    if (alpha !== void 0 && alpha < 8) continue;
+    const brightness = (r + g + b) / 3;
+    if (brightness < 12) continue;
+    const isNearWhite = r >= 245 && g >= 245 && b >= 245;
+    const pixelIndex = i / 4;
+    const x = pixelIndex % width;
+    const y = Math.floor(pixelIndex / width);
+    const bucketR = Math.floor(r / bucketSize) * bucketSize;
+    const bucketG = Math.floor(g / bucketSize) * bucketSize;
+    const bucketB = Math.floor(b / bucketSize) * bucketSize;
+    const key = `${bucketR},${bucketG},${bucketB}`;
+    const topWeight = y < thicknessY ? 1 + (thicknessY - y) / thicknessY : 0;
+    if (topWeight > 0) {
+      accumulateEdgeSample("top", topWeight, key, isNearWhite);
+    }
+    const bottomWeight = y >= height - thicknessY ? 1 + (y - (height - thicknessY)) / thicknessY : 0;
+    if (bottomWeight > 0) {
+      accumulateEdgeSample("bottom", bottomWeight, key, isNearWhite);
+    }
+    const leftWeight = x < thicknessX ? 1 + (thicknessX - x) / thicknessX : 0;
+    if (leftWeight > 0) {
+      accumulateEdgeSample("left", leftWeight, key, isNearWhite);
+    }
+    const rightWeight = x >= width - thicknessX ? 1 + (x - (width - thicknessX)) / thicknessX : 0;
+    if (rightWeight > 0) {
+      accumulateEdgeSample("right", rightWeight, key, isNearWhite);
+    }
+  }
+  return {
+    top: resolveEdgeColor(edgeMaps.top, whiteEdgeStrength.top),
+    right: resolveEdgeColor(edgeMaps.right, whiteEdgeStrength.right),
+    bottom: resolveEdgeColor(edgeMaps.bottom, whiteEdgeStrength.bottom),
+    left: resolveEdgeColor(edgeMaps.left, whiteEdgeStrength.left)
+  };
+}
+function resolveEdgeColor(map, whiteStrength) {
+  if (!map.size) {
+    return whiteStrength > 0 ? EDGE_WHITE_FALLBACK : EDGE_COLOR_FALLBACK;
+  }
+  let dominantColor = "";
+  let maxCount = 0;
+  let totalColorWeight = 0;
+  map.forEach((count, color) => {
+    totalColorWeight += count;
+    if (count > maxCount) {
+      maxCount = count;
+      dominantColor = color;
+    }
+  });
+  if (!dominantColor) {
+    return whiteStrength > 0 ? EDGE_WHITE_FALLBACK : EDGE_COLOR_FALLBACK;
+  }
+  const whiteDominates = whiteStrength > 0 && (totalColorWeight === 0 || whiteStrength >= totalColorWeight * WHITE_DOMINANCE_RATIO);
+  if (whiteDominates) {
+    return EDGE_WHITE_FALLBACK;
+  }
+  if (dominantColor.startsWith("#")) {
+    return dominantColor.toUpperCase();
+  }
+  const [r, g, b] = dominantColor.split(",").map(Number);
+  return rgbToHex(r, g, b);
+}
+function blendEdgeColors(edgeColors) {
+  const colors = Object.values(edgeColors);
+  if (!colors.length) {
+    return EDGE_COLOR_FALLBACK;
+  }
+  const totals = colors.reduce(
+    (acc, hex) => {
+      const { r, g, b } = hexToRgb(hex || EDGE_COLOR_FALLBACK);
+      acc.r += r;
+      acc.g += g;
+      acc.b += b;
+      return acc;
+    },
+    { r: 0, g: 0, b: 0 }
+  );
+  const count = colors.length;
+  return rgbToHex(totals.r / count, totals.g / count, totals.b / count);
+}
+
+// src/server/optimization/blurGenerator.ts
+function encodeRawBlurHash(data, width, height, componentX = 4, componentY = 3) {
+  const clampedX = Math.max(1, Math.min(Math.round(componentX), width, 9));
+  const clampedY = Math.max(1, Math.min(Math.round(componentY), height, 9));
+  return encodeBlurHash(
+    new Uint8ClampedArray(data),
+    width,
+    height,
+    clampedX,
+    clampedY
+  );
+}
+async function encodeBlurHashString(buffer, componentX = 4, componentY = 3) {
+  const sharp = await loadSharp();
+  const { data, info } = await sharp(buffer).resize(32, 32, { fit: "inside" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return encodeRawBlurHash(
+    data,
+    info.width,
+    info.height,
+    componentX,
+    componentY
+  );
+}
+async function generateBlurPlaceholder(buffer, options = {}) {
+  const targetWidth = options.width ?? BLUR_PLACEHOLDER_WIDTH;
+  const fallbackWidth = options.fallbackWidth ?? BLUR_PLACEHOLDER_FALLBACK_WIDTH;
+  const quality = options.quality ?? BLUR_PLACEHOLDER_QUALITY;
+  const maxChars = options.maxDataUrlChars ?? BLUR_PLACEHOLDER_MAX_CHARS;
+  const sharp = await loadSharp();
+  try {
+    let processBuffer = buffer;
+    const isSvg = /<svg[\s>]/i.test(buffer.toString("utf8", 0, 1024));
+    if (isSvg) {
+      const normalizedSvg = buffer.toString("utf8").replace(/<svg\b/gi, "<svg").replace(/<\/svg\s*>/gi, "</svg>");
+      processBuffer = Buffer.from(normalizedSvg, "utf8");
+    }
+    const baseSize = Math.max(targetWidth, 128);
+    const rawSample = await sharp(processBuffer).rotate().resize(baseSize, baseSize, { fit: "inside", withoutEnlargement: true }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    const rawInput = {
+      raw: {
+        width: rawSample.info.width,
+        height: rawSample.info.height,
+        channels: 4
+      }
+    };
+    const buildPlaceholderDataUrl = async (width) => {
+      const webpBuffer = await sharp(rawSample.data, rawInput).resize(width, width, { fit: "inside", withoutEnlargement: true }).webp({ quality, effort: 6, smartSubsample: true }).toBuffer();
+      return `data:image/webp;base64,${webpBuffer.toString("base64")}`;
+    };
+    let dataURL = await buildPlaceholderDataUrl(targetWidth);
+    if (dataURL.length > maxChars) {
+      dataURL = await buildPlaceholderDataUrl(fallbackWidth);
+    }
+    const edgeColors = computeEdgeColorSet(
+      rawSample.data,
+      rawSample.info.width,
+      rawSample.info.height
+    );
+    const color = blendEdgeColors(edgeColors);
+    let blurHash;
+    if (options.includeBlurHash) {
+      try {
+        const hashSample = rawSample.info.width <= 32 && rawSample.info.height <= 32 ? rawSample : await sharp(rawSample.data, rawInput).resize(32, 32, { fit: "inside" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+        blurHash = encodeRawBlurHash(
+          hashSample.data,
+          hashSample.info.width,
+          hashSample.info.height
+        );
+      } catch {
+        blurHash = void 0;
+      }
+    }
+    return {
+      dataURL,
+      color,
+      ...blurHash && { blurHash }
+    };
+  } catch {
+    return generateFallbackBlur(buffer, options.includeBlurHash);
+  }
+}
+async function generateFallbackBlur(buffer, includeBlurHash) {
+  const sharp = await loadSharp();
+  const tinyBuffer = await sharp(buffer).resize(64, 64, { fit: "cover", kernel: "lanczos3" }).blur(1).webp({
+    quality: 75,
+    effort: 6,
+    smartSubsample: false
+  }).toBuffer();
+  const dataURL = `data:image/webp;base64,${tinyBuffer.toString("base64")}`;
+  const edgeColors = await extractEdgeColorsFromBuffer(buffer);
+  const color = blendEdgeColors(edgeColors);
+  let blurHash;
+  if (includeBlurHash) {
+    try {
+      blurHash = await encodeBlurHashString(tinyBuffer);
+    } catch {
+      blurHash = void 0;
+    }
+  }
+  return { dataURL, color, ...blurHash && { blurHash } };
+}
+
+// src/server/semaphore.ts
+var SemaphoreQueueFullError = class extends Error {
+  status = 503;
+  constructor(message = "Server upload queue is full. Please try again later.") {
+    super(message);
+    this.name = "SemaphoreQueueFullError";
+  }
+};
+function createAbortError(signal) {
+  if (signal?.reason instanceof Error) {
+    return signal.reason;
+  }
+  const err = new Error(
+    typeof signal?.reason === "string" ? signal.reason : "Operation aborted"
+  );
+  err.name = "AbortError";
+  return err;
+}
+var AsyncSemaphore = class {
+  constructor(concurrency, options) {
+    this.concurrency = concurrency;
+    if (concurrency < 1) {
+      throw new Error("AsyncSemaphore concurrency must be >= 1");
+    }
+    if (typeof options === "number") {
+      this.maxQueue = options;
+    } else if (options && typeof options === "object") {
+      this.maxQueue = options.maxQueue;
+    }
+  }
+  concurrency;
+  activeCount = 0;
+  maxQueue;
+  queue = [];
+  get active() {
+    return this.activeCount;
+  }
+  get pending() {
+    return this.queue.length;
+  }
+  async run(task, options = {}) {
+    const { signal, timeoutMs, label = "Semaphore task" } = options;
+    await this.acquire(signal);
+    let rawTaskPromise;
+    try {
+      rawTaskPromise = Promise.resolve().then(task);
+    } catch (syncError) {
+      this.release();
+      throw syncError;
+    }
+    let released = false;
+    const releaseOnce = () => {
+      if (!released) {
+        released = true;
+        this.release();
+      }
+    };
+    void rawTaskPromise.then(
+      () => releaseOnce(),
+      (err) => {
+        const pending = err && typeof err === "object" && "pendingTask" in err ? err.pendingTask : void 0;
+        if (pending && typeof pending.then === "function") {
+          void pending.then(releaseOnce, releaseOnce);
+        } else {
+          releaseOnce();
+        }
+      }
+    );
+    let callerPromise = rawTaskPromise;
+    if (timeoutMs !== void 0 && timeoutMs > 0) {
+      callerPromise = withTimeout(callerPromise, timeoutMs, label);
+    }
+    if (signal) {
+      callerPromise = raceWithAbort(callerPromise, signal);
+    }
+    return callerPromise;
+  }
+  acquire(signal) {
+    if (signal?.aborted) {
+      return Promise.reject(createAbortError(signal));
+    }
+    if (this.activeCount < this.concurrency) {
+      this.activeCount += 1;
+      return Promise.resolve();
+    }
+    if (this.maxQueue !== void 0 && this.queue.length >= this.maxQueue) {
+      return Promise.reject(new SemaphoreQueueFullError());
+    }
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        const idx = this.queue.indexOf(entry);
+        if (idx !== -1) {
+          this.queue.splice(idx, 1);
+        }
+        entry.cancel(createAbortError(signal));
+      };
+      const entry = {
+        grant: () => {
+          signal?.removeEventListener("abort", onAbort);
+          this.activeCount += 1;
+          resolve();
+        },
+        cancel: (reason) => {
+          signal?.removeEventListener("abort", onAbort);
+          reject(reason);
+        }
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.queue.push(entry);
+    });
+  }
+  release() {
+    this.activeCount = Math.max(0, this.activeCount - 1);
+    const next = this.queue.shift();
+    next?.grant();
+  }
+};
+function raceWithAbort(task, signal) {
+  if (signal.aborted) {
+    const err = createAbortError(signal);
+    err.pendingTask = task.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return Promise.reject(err);
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      const err = createAbortError(signal);
+      err.pendingTask = task.then(
+        () => {
+        },
+        () => {
+        }
+      );
+      reject(err);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    task.then(
+      (val) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(val);
+      },
+      (err) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+      }
+    );
+  });
+}
+async function withTimeout(task, timeoutMs, label) {
+  let timeoutHandle = null;
+  const settledTask = task.then(
+    () => {
+    },
+    () => {
+    }
+  );
+  try {
+    return await Promise.race([
+      task,
+      new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+          const err = new Error(
+            `${label} timed out after ${timeoutMs}ms`
+          );
+          err.pendingTask = settledTask;
+          reject(err);
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
+
+// src/cli/scanner.ts
+import fs from "fs/promises";
+import path from "path";
+var SUPPORTED_IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".webp",
+  ".avif",
+  ".svg"
+]);
+var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist"]);
+async function scanImageDirectory(imagesDir) {
+  const rootDir = path.resolve(imagesDir);
+  const rootStats = await fs.stat(rootDir);
+  if (!rootStats.isDirectory()) {
+    throw new Error(`Expected images path to be a directory: ${rootDir}`);
+  }
+  const results = [];
+  async function walk(currentDir) {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) {
+          continue;
+        }
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!SUPPORTED_IMAGE_EXTENSIONS.has(ext)) {
+        continue;
+      }
+      const fileStats = await fs.stat(fullPath);
+      const relPath = path.relative(rootDir, fullPath).split(path.sep).join("/").replace(/\\/g, "/");
+      const relativeKey = relPath.startsWith("/") ? relPath : `/${relPath}`;
+      results.push({
+        absolutePath: fullPath,
+        relativeKey,
+        size: fileStats.size,
+        mtimeMs: fileStats.mtimeMs
+      });
+    }
+  }
+  await walk(rootDir);
+  results.sort((a, b) => a.relativeKey.localeCompare(b.relativeKey));
+  return results;
+}
+
+// src/cli/generator.ts
+var FALLBACK_BLURHASH = "LEHV6nWB2yk8pyo0adR*.7kCMdnj";
+var MANIFEST_VERSION = "2.0";
+async function loadExistingHashes(manifestPath) {
+  try {
+    const parsed = JSON.parse(await fs2.readFile(manifestPath, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "hashes" in parsed && parsed.hashes && typeof parsed.hashes === "object" && !Array.isArray(parsed.hashes)) {
+      return parsed.hashes;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+function canReuseCachedEntry(entry, file, includeMedium) {
+  if (!entry || typeof entry !== "object") return false;
+  if (!entry.hash || !entry.color || !entry.variants?.small) return false;
+  if (!entry.metadata || !entry.metadata.size || !entry.metadata.mtimeMs) {
+    return false;
+  }
+  if (entry.metadata.size !== String(file.size)) {
+    return false;
+  }
+  if (entry.metadata.mtimeMs !== String(Math.round(file.mtimeMs))) {
+    return false;
+  }
+  if (includeMedium && !entry.variants.medium) return false;
+  return true;
+}
+async function resolveImageDimensions(buffer, isSvg) {
+  const sharp = await loadSharp();
+  const metadata = await sharp(buffer).metadata();
+  let { width, height } = metadata;
+  if ((!width || !height) && isSvg) {
+    const svgText = buffer.toString("utf8");
+    const match = svgText.match(
+      /viewBox\s*=\s*["']\s*([\d.-]+)[\s,]+([\d.-]+)[\s,]+([\d.-]+)[\s,]+([\d.-]+)\s*["']/i
+    );
+    if (match) {
+      width = Math.round(Number.parseFloat(match[3]));
+      height = Math.round(Number.parseFloat(match[4]));
+    }
+  }
+  return { width, height };
+}
+async function generateBlurManifest(imagesDir, manifestFile, options = {}) {
+  const outputPath = path2.resolve(manifestFile);
+  const concurrency = Math.max(1, Math.floor(options.concurrency ?? 4));
+  const includeMedium = options.includeMedium ?? true;
+  const force = Boolean(options.force);
+  const files = await scanImageDirectory(imagesDir);
+  const existingHashes = force ? {} : await loadExistingHashes(outputPath);
+  const semaphore = new AsyncSemaphore(concurrency);
+  const generatedEntries = /* @__PURE__ */ new Map();
+  let processed = 0;
+  let cached = 0;
+  let failed = 0;
+  let done = 0;
+  const total = files.length;
+  await Promise.all(
+    files.map(
+      (file) => semaphore.run(async () => {
+        const prior = force ? void 0 : existingHashes[file.relativeKey];
+        try {
+          if (canReuseCachedEntry(prior, file, includeMedium)) {
+            generatedEntries.set(file.relativeKey, prior);
+            cached += 1;
+            return;
+          }
+          const buffer = await fs2.readFile(file.absolutePath);
+          const isSvg = file.relativeKey.toLowerCase().endsWith(".svg");
+          const { width, height } = await resolveImageDimensions(buffer, isSvg);
+          const small = await generateBlurPlaceholder(buffer, {
+            width: 64,
+            fallbackWidth: 48,
+            includeBlurHash: true
+          });
+          const medium = includeMedium ? await generateBlurPlaceholder(buffer, {
+            width: 128,
+            fallbackWidth: 96,
+            includeBlurHash: false
+          }) : void 0;
+          const hash = small.blurHash || await encodeBlurHashString(buffer).catch(() => FALLBACK_BLURHASH);
+          generatedEntries.set(file.relativeKey, {
+            hash,
+            variants: {
+              small: small.dataURL,
+              ...medium ? { medium: medium.dataURL } : {}
+            },
+            color: small.color,
+            ...width ? { width } : {},
+            ...height ? { height } : {},
+            metadata: {
+              size: String(file.size),
+              mtimeMs: String(Math.round(file.mtimeMs))
+            }
+          });
+          processed += 1;
+        } catch (err) {
+          failed += 1;
+          const existing = existingHashes[file.relativeKey];
+          if (existing) {
+            generatedEntries.set(file.relativeKey, existing);
+          }
+          const reason = err instanceof Error ? err.message : String(err);
+          console.warn(
+            `Warning: Failed to generate blur manifest entry for "${file.relativeKey}": ${reason}`
+          );
+        } finally {
+          done += 1;
+          options.onProgress?.(done, total, file.relativeKey);
+        }
+      })
+    )
+  );
+  const orderedHashes = {};
+  for (const file of files) {
+    const entry = generatedEntries.get(file.relativeKey);
+    if (entry) orderedHashes[file.relativeKey] = entry;
+  }
+  const manifest = {
+    version: MANIFEST_VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    totalImages: Object.keys(orderedHashes).length,
+    processedImages: processed,
+    cachedImages: cached,
+    failedImages: failed,
+    hashes: orderedHashes
+  };
+  await fs2.mkdir(path2.dirname(outputPath), { recursive: true });
+  await fs2.writeFile(outputPath, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+  return { manifest, processed, cached, failed, outputPath };
+}
+
+// src/cli/validation.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+var HEX_COLOR_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function toNormalizedKey(key) {
+  return normalizeImagePath(key, { stripPrefixes: [] }).normalizedPath;
+}
+function failValidation(error) {
+  return { valid: false, totalEntries: 0, errors: [error], warnings: [] };
+}
+function isDataImageUrl(value) {
+  return typeof value === "string" && value.startsWith("data:image/");
+}
+function computeKeyDiff(files, hashes) {
+  const diskKeys = new Set(files.map((f) => f.relativeKey));
+  const manifestKeys = Object.keys(hashes);
+  const normalizedSet = new Set(manifestKeys.map(toNormalizedKey));
+  const missingKeys = files.map((f) => f.relativeKey).filter((k) => !(k in hashes) && !normalizedSet.has(k));
+  const orphanedKeys = manifestKeys.filter(
+    (k) => !diskKeys.has(k) && !diskKeys.has(toNormalizedKey(k))
+  );
+  return { missingKeys, orphanedKeys };
+}
+async function readManifestSafe(manifestFile) {
+  try {
+    const parsed = JSON.parse(await fs3.readFile(path3.resolve(manifestFile), "utf8"));
+    if (isPlainObject(parsed) && isPlainObject(parsed.hashes)) {
+      return {
+        exists: true,
+        manifest: parsed,
+        hashes: parsed.hashes
+      };
+    }
+    return { exists: true, hashes: {} };
+  } catch (err) {
+    return { exists: err.code !== "ENOENT", hashes: {} };
+  }
+}
+function validateEntry(key, value, errors, warnings) {
+  if (!key.startsWith("/")) warnings.push(`Entry key "${key}" should start with "/"`);
+  if (!isPlainObject(value)) {
+    errors.push(`Entry "${key}" must be an object`);
+    return;
+  }
+  const entry = value;
+  if (typeof entry.hash !== "string" || entry.hash.trim().length < 6) {
+    errors.push(`Entry "${key}" has missing or invalid BlurHash "hash"`);
+  }
+  if (typeof entry.color !== "string" || !HEX_COLOR_RE.test(entry.color)) {
+    errors.push(`Entry "${key}" has missing or invalid hex "color"`);
+  }
+  if (!isPlainObject(entry.variants)) {
+    errors.push(`Entry "${key}" is missing "variants" object`);
+    return;
+  }
+  if (!isDataImageUrl(entry.variants.small)) {
+    errors.push(`Entry "${key}" is missing valid "variants.small" data URL`);
+  }
+  if (entry.variants.medium !== void 0 && !isDataImageUrl(entry.variants.medium)) {
+    errors.push(`Entry "${key}" has invalid "variants.medium" data URL`);
+  }
+}
+async function validateBlurHashFile(manifestFile) {
+  const resolvedPath = path3.resolve(manifestFile);
+  let raw;
+  try {
+    raw = await fs3.readFile(resolvedPath, "utf8");
+  } catch {
+    return failValidation(`Manifest file not found or unreadable: ${resolvedPath}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return failValidation(`Invalid JSON in manifest: ${err.message}`);
+  }
+  if (!isPlainObject(parsed)) return failValidation("Manifest root must be a JSON object");
+  if (!isPlainObject(parsed.hashes)) return failValidation('Manifest is missing a valid "hashes" object');
+  const errors = [];
+  const warnings = [];
+  if (typeof parsed.version !== "string" || !parsed.version.trim()) {
+    warnings.push('Manifest is missing a "version" string');
+  }
+  if (typeof parsed.generatedAt !== "string" || Number.isNaN(Date.parse(parsed.generatedAt))) {
+    warnings.push('Manifest has missing or invalid "generatedAt" timestamp');
+  }
+  const entries = Object.entries(parsed.hashes);
+  if (typeof parsed.totalImages === "number" && parsed.totalImages !== entries.length) {
+    warnings.push(`Manifest totalImages (${parsed.totalImages}) differs from count (${entries.length})`);
+  }
+  if (entries.length === 0) warnings.push("Manifest contains 0 image entries");
+  for (const [key, value] of entries) validateEntry(key, value, errors, warnings);
+  return { valid: errors.length === 0, totalEntries: entries.length, errors, warnings };
+}
+async function autoSyncCheck(imagesDir, manifestFile) {
+  const [files, loaded] = await Promise.all([scanImageDirectory(imagesDir), readManifestSafe(manifestFile)]);
+  const { missingKeys, orphanedKeys } = computeKeyDiff(files, loaded.hashes);
+  const inSync = loaded.exists && missingKeys.length === 0 && orphanedKeys.length === 0;
+  return { inSync, totalFiles: files.length, totalEntries: Object.keys(loaded.hashes).length, missingKeys, orphanedKeys };
+}
+async function cleanupOrphanedHashes(imagesDir, manifestFile, options) {
+  const dryRun = Boolean(options?.dryRun);
+  const resolvedPath = path3.resolve(manifestFile);
+  const [files, loaded] = await Promise.all([scanImageDirectory(imagesDir), readManifestSafe(resolvedPath)]);
+  if (!loaded.exists || !loaded.manifest) return { removedCount: 0, removedKeys: [], dryRun };
+  const { orphanedKeys } = computeKeyDiff(files, loaded.hashes);
+  if (!dryRun && orphanedKeys.length > 0) {
+    const orphanSet = new Set(orphanedKeys);
+    const hashes = Object.fromEntries(Object.entries(loaded.hashes).filter(([k]) => !orphanSet.has(k)));
+    const updated = { ...loaded.manifest, generatedAt: (/* @__PURE__ */ new Date()).toISOString(), totalImages: Object.keys(hashes).length, hashes };
+    await fs3.writeFile(resolvedPath, `${JSON.stringify(updated, null, 2)}
+`, "utf8");
+  }
+  return { removedCount: orphanedKeys.length, removedKeys: orphanedKeys, dryRun };
+}
+async function generateHealthReport(imagesDir, manifestFile) {
+  const [validation, loaded] = await Promise.all([validateBlurHashFile(manifestFile), readManifestSafe(manifestFile)]);
+  const errors = [...validation.errors];
+  const warnings = [...validation.warnings];
+  let files = [];
+  try {
+    files = await scanImageDirectory(imagesDir);
+  } catch (err) {
+    errors.push(`Failed to scan "${path3.resolve(imagesDir)}": ${err.message}`);
+  }
+  const { missingKeys, orphanedKeys } = computeKeyDiff(files, loaded.hashes);
+  if (missingKeys.length > 0) warnings.push(`${missingKeys.length} missing image(s)`);
+  if (orphanedKeys.length > 0) warnings.push(`${orphanedKeys.length} orphaned entry(ies)`);
+  const totalImagesOnDisk = files.length;
+  const covered = Math.max(0, totalImagesOnDisk - missingKeys.length);
+  const coveragePercent = totalImagesOnDisk === 0 ? validation.valid ? 100 : 0 : Number((covered / totalImagesOnDisk * 100).toFixed(2));
+  return {
+    validManifest: validation.valid,
+    totalImagesOnDisk,
+    totalManifestEntries: validation.totalEntries,
+    coveragePercent,
+    missingKeys,
+    orphanedKeys,
+    errors,
+    warnings
+  };
+}
+
+// src/cli/commands.ts
+var CLI_VERSION = "2.0.0".length > 0 ? "2.0.0" : "2.0.0";
+var DEFAULT_IMAGES_DIR = "public/images";
+var DEFAULT_MANIFEST_FILE = "src/blur-hashes.json";
+function findManifestEntry(hashes, imageKey) {
+  const candidates = [
+    imageKey,
+    normalizeImagePath(imageKey).normalizedPath,
+    normalizeImagePath(imageKey, { stripPrefixes: [] }).normalizedPath
+  ];
+  for (const candidate of candidates) {
+    if (hashes[candidate]) return { key: candidate, entry: hashes[candidate] };
+    const noSlash = candidate.replace(/^\/+/, "");
+    if (hashes[noSlash]) return { key: noSlash, entry: hashes[noSlash] };
+  }
+  return null;
+}
+function createCliProgram() {
+  const program = new Command();
+  program.name("img-upload-kit").description("LQIP, BlurHash, and dominant color manifest CLI tooling").version(CLI_VERSION);
+  program.command("generate").description("Scan an image directory and generate a blur-hashes JSON manifest").option("-d, --dir <dir>", "Source images directory", DEFAULT_IMAGES_DIR).option("-o, --out <file>", "Output manifest JSON path", DEFAULT_MANIFEST_FILE).option("-f, --force", "Force regenerate all entries ignoring cache", false).option("-c, --concurrency <n>", "Max parallel processing workers", "4").option("--no-medium", "Skip generating medium (128px) LQIP variants").action(
+    async (opts) => {
+      const concurrency = Math.max(1, Number.parseInt(opts.concurrency, 10) || 4);
+      const result = await generateBlurManifest(opts.dir, opts.out, {
+        concurrency,
+        force: Boolean(opts.force),
+        includeMedium: opts.medium
+      });
+      console.log(
+        `Generated ${result.outputPath} (total: ${result.manifest.totalImages}, processed: ${result.processed}, cached: ${result.cached}, failed: ${result.failed})`
+      );
+    }
+  );
+  program.command("validate").description("Validate a blur manifest JSON file").option("-f, --file <file>", "Manifest JSON path", DEFAULT_MANIFEST_FILE).action(async (opts) => {
+    const result = await validateBlurHashFile(opts.file);
+    for (const warning of result.warnings) console.warn(`Warning: ${warning}`);
+    if (!result.valid) {
+      for (const error of result.errors) console.error(`Error: ${error}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`Manifest is valid (${result.totalEntries} entries).`);
+  });
+  program.command("sync").description("Check whether disk images and manifest entries are in sync").option("-d, --dir <dir>", "Source images directory", DEFAULT_IMAGES_DIR).option("-f, --file <file>", "Manifest JSON path", DEFAULT_MANIFEST_FILE).option("--fix", "Generate missing and remove orphaned blur manifest entries automatically", false).action(async (opts) => {
+    const sync = await autoSyncCheck(opts.dir, opts.file);
+    if (sync.inSync) {
+      console.log(`In sync (${sync.totalEntries} entries).`);
+      return;
+    }
+    console.log(
+      `Out of sync: ${sync.missingKeys.length} missing, ${sync.orphanedKeys.length} orphaned.`
+    );
+    if (opts.fix) {
+      if (sync.missingKeys.length > 0) {
+        const result = await generateBlurManifest(opts.dir, opts.file);
+        console.log(
+          `Synced manifest (processed: ${result.processed}, cached: ${result.cached}, removed orphans: ${sync.orphanedKeys.length}).`
+        );
+        return;
+      }
+      if (sync.orphanedKeys.length > 0) {
+        const cleaned = await cleanupOrphanedHashes(opts.dir, opts.file);
+        console.log(
+          `Synced manifest (removed ${cleaned.removedCount} orphaned entries).`
+        );
+        return;
+      }
+    }
+    if (!opts.fix) process.exitCode = 1;
+  });
+  program.command("cleanup").description("Remove orphaned entries from the blur manifest").option("-d, --dir <dir>", "Source images directory", DEFAULT_IMAGES_DIR).option("-f, --file <file>", "Manifest JSON path", DEFAULT_MANIFEST_FILE).option("--dry-run", "Preview orphaned keys without writing changes", false).action(async (opts) => {
+    const result = await cleanupOrphanedHashes(opts.dir, opts.file, {
+      dryRun: Boolean(opts.dryRun)
+    });
+    const prefix = result.dryRun ? "[Dry Run] Would remove" : "Removed";
+    console.log(`${prefix} ${result.removedCount} orphaned entries.`);
+  });
+  program.command("health").description("Generate a comprehensive manifest health and coverage report").option("-d, --dir <dir>", "Source images directory", DEFAULT_IMAGES_DIR).option("-f, --file <file>", "Manifest JSON path", DEFAULT_MANIFEST_FILE).action(async (opts) => {
+    const report = await generateHealthReport(opts.dir, opts.file);
+    console.log(
+      `Health: valid=${report.validManifest}, coverage=${report.coveragePercent}% (${report.totalManifestEntries} entries / ${report.totalImagesOnDisk} disk images)`
+    );
+    for (const warning of report.warnings) console.warn(`Warning: ${warning}`);
+    for (const error of report.errors) console.error(`Error: ${error}`);
+    if (!report.validManifest || report.errors.length > 0) {
+      process.exitCode = 1;
+    }
+  });
+  program.command("inspect <imageKey>").description("Inspect a single image entry inside the blur manifest").option("-f, --file <file>", "Manifest JSON path", DEFAULT_MANIFEST_FILE).action(async (imageKey, opts) => {
+    const raw = await fs4.readFile(path4.resolve(opts.file), "utf8");
+    const parsed = JSON.parse(raw);
+    const match = parsed.hashes ? findManifestEntry(parsed.hashes, imageKey) : null;
+    if (!match) {
+      console.error(`Entry not found for key: ${imageKey}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(
+      JSON.stringify(
+        {
+          key: match.key,
+          hash: match.entry.hash,
+          color: match.entry.color,
+          width: match.entry.width,
+          height: match.entry.height,
+          variants: {
+            smallChars: match.entry.variants.small.length,
+            mediumChars: match.entry.variants.medium?.length ?? 0,
+            hasMedium: Boolean(match.entry.variants.medium)
+          },
+          metadata: match.entry.metadata
+        },
+        null,
+        2
+      )
+    );
+  });
+  return program;
+}
+
+// src/cli/index.ts
+var CLI_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "generate",
+  "validate",
+  "sync",
+  "cleanup",
+  "health",
+  "inspect",
+  "help"
+]);
+async function runCli(argv) {
+  const program = createCliProgram();
+  if (!argv) {
+    await program.parseAsync(process.argv);
+    return;
+  }
+  const isUserArgs = argv.length === 0 || CLI_SUBCOMMANDS.has(argv[0]) || argv[0].startsWith("-");
+  await program.parseAsync(argv, isUserArgs ? { from: "user" } : void 0);
+}
+
+// src/cli/bin.ts
+void runCli().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map