feat: SOTA image enhancement with one-click auto-improve (#55)

* feat(image-enhancement): add analysis and correction types

* feat(image-enhancement): implement auto-enhance analysis and correction engine

* test(image-enhancement): add unit tests for auto-enhance engine

* feat(image-enhancement): add API route with analyze endpoint and register in constants/i18n

* feat(image-enhancement): add UI component with mode selector, intensity slider, and analysis badges

* test(image-enhancement): add integration and e2e tests

* fix(image-enhancement): use modulate instead of gamma for exposure correction

Sharp's gamma() only accepts values between 1.0 and 3.0, but brightening
underexposed images computed gamma < 1.0. Switch to modulate({ brightness })
which handles both brightening and darkening correctly.

---------

Co-authored-by: stirling-image <stirling-image@users.noreply.github.com>

apps/api/src/routes/tools/image-enhancement.ts

@@ -0,0 +1,116 @@
+import { analyzeImage, applyCorrections } from "@stirling-image/image-engine";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import sharp from "sharp";
+import { z } from "zod";
+import { autoOrient } from "../../lib/auto-orient.js";
+import { validateImageBuffer } from "../../lib/file-validation.js";
+import { sanitizeFilename } from "../../lib/filename.js";
+import { decodeHeic } from "../../lib/heic-converter.js";
+import { resolveOutputFormat } from "../../lib/output-format.js";
+import { createToolRoute } from "../tool-factory.js";
+
+const settingsSchema = z.object({
+  mode: z.enum(["auto", "portrait", "landscape", "low-light", "food", "document"]).default("auto"),
+  intensity: z.number().min(0).max(100).default(50),
+  corrections: z
+    .object({
+      exposure: z.boolean().default(true),
+      contrast: z.boolean().default(true),
+      whiteBalance: z.boolean().default(true),
+      saturation: z.boolean().default(true),
+      sharpness: z.boolean().default(true),
+      denoise: z.boolean().default(true),
+    })
+    .default({}),
+});
+
+type EnhancementSettings = z.infer<typeof settingsSchema>;
+
+async function processImageEnhancement(
+  inputBuffer: Buffer,
+  settings: EnhancementSettings,
+  filename: string,
+) {
+  const outputFormat = await resolveOutputFormat(inputBuffer, filename);
+  const analysis = await analyzeImage(inputBuffer);
+
+  let image = sharp(inputBuffer);
+  image = applyCorrections(
+    image,
+    analysis.corrections,
+    settings.mode,
+    settings.intensity,
+    settings.corrections,
+  );
+
+  const buffer = await image
+    .toFormat(outputFormat.format, { quality: outputFormat.quality })
+    .toBuffer();
+
+  return { buffer, filename, contentType: outputFormat.contentType };
+}
+
+export function registerImageEnhancement(app: FastifyInstance) {
+  createToolRoute(app, {
+    toolId: "image-enhancement",
+    settingsSchema,
+    process: processImageEnhancement,
+  });
+
+  app.post(
+    "/api/v1/tools/image-enhancement/analyze",
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      let fileBuffer: Buffer | null = null;
+
+      try {
+        const parts = request.parts();
+        for await (const part of parts) {
+          if (part.type === "file") {
+            const chunks: Buffer[] = [];
+            for await (const chunk of part.file) {
+              chunks.push(chunk);
+            }
+            fileBuffer = Buffer.concat(chunks);
+            break;
+          }
+        }
+      } catch (err) {
+        return reply.status(400).send({
+          error: "Failed to parse request",
+          details: err instanceof Error ? err.message : String(err),
+        });
+      }
+
+      if (!fileBuffer || fileBuffer.length === 0) {
+        return reply.status(400).send({ error: "No image file provided" });
+      }
+
+      const validation = await validateImageBuffer(fileBuffer);
+      if (!validation.valid) {
+        return reply.status(400).send({ error: `Invalid image: ${validation.reason}` });
+      }
+
+      if (validation.format === "heif") {
+        try {
+          fileBuffer = await decodeHeic(fileBuffer);
+        } catch (err) {
+          return reply.status(422).send({
+            error: "Failed to decode HEIC file",
+            details: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+
+      try {
+        fileBuffer = await autoOrient(fileBuffer);
+        const analysis = await analyzeImage(fileBuffer);
+        return reply.send(analysis);
+      } catch (err) {
+        return reply.status(422).send({
+          error: "Analysis failed",
+          details: err instanceof Error ? err.message : String(err),
+        });
+      }
+    },
+  );
+}

apps/api/src/routes/tools/index.ts

@@ -20,6 +20,7 @@ import { registerEraseObject } from "./erase-object.js";
 import { registerFavicon } from "./favicon.js";
 import { registerFindDuplicates } from "./find-duplicates.js";
 import { registerGifTools } from "./gif-tools.js";
+import { registerImageEnhancement } from "./image-enhancement.js";
 import { registerImageToPdf } from "./image-to-pdf.js";
 import { registerInfo } from "./info.js";
 import { registerOcr } from "./ocr.js";
@@ -125,6 +126,7 @@ export async function registerToolRoutes(app: FastifyInstance): Promise<void> {
     { id: "blur-faces", register: registerBlurFaces },
     { id: "erase-object", register: registerEraseObject },
     { id: "smart-crop", register: registerSmartCrop },
+    { id: "image-enhancement", register: registerImageEnhancement },
     { id: "content-aware-resize", register: registerContentAwareResize },
   ];
 

apps/web/src/components/tools/image-enhancement-settings.tsx

@@ -0,0 +1,460 @@
+import {
+  Download,
+  FileText,
+  Moon,
+  Mountain,
+  Sparkles,
+  User,
+  UtensilsCrossed,
+  X,
+} from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { ProgressCard } from "@/components/common/progress-card";
+import { useToolProcessor } from "@/hooks/use-tool-processor";
+import { useFileStore } from "@/stores/file-store";
+
+type EnhancementMode = "auto" | "portrait" | "landscape" | "low-light" | "food" | "document";
+
+interface AnalysisScores {
+  exposure: number;
+  contrast: number;
+  whiteBalance: number;
+  saturation: number;
+  sharpness: number;
+  noise: number;
+}
+
+interface CorrectionParams {
+  brightness: number;
+  contrast: number;
+  temperature: number;
+  saturation: number;
+  sharpness: number;
+  denoise: number;
+}
+
+interface AnalysisData {
+  scores: AnalysisScores;
+  corrections: CorrectionParams;
+  issues: string[];
+  suggestedMode: EnhancementMode;
+}
+
+const MODES: { value: EnhancementMode; label: string; icon: typeof Sparkles }[] = [
+  { value: "auto", label: "Auto", icon: Sparkles },
+  { value: "portrait", label: "Portrait", icon: User },
+  { value: "landscape", label: "Landscape", icon: Mountain },
+  { value: "low-light", label: "Low Light", icon: Moon },
+  { value: "food", label: "Food", icon: UtensilsCrossed },
+  { value: "document", label: "Document", icon: FileText },
+];
+
+const PRESET_MULTIPLIERS: Record<EnhancementMode, Record<string, number>> = {
+  auto: {
+    brightness: 1.0,
+    contrast: 1.0,
+    temperature: 1.0,
+    saturation: 1.0,
+    sharpness: 1.0,
+    denoise: 1.0,
+  },
+  portrait: {
+    brightness: 0.8,
+    contrast: 0.7,
+    temperature: 1.2,
+    saturation: 0.6,
+    sharpness: 0.5,
+    denoise: 1.5,
+  },
+  landscape: {
+    brightness: 1.0,
+    contrast: 1.3,
+    temperature: 1.0,
+    saturation: 1.4,
+    sharpness: 1.5,
+    denoise: 0.5,
+  },
+  "low-light": {
+    brightness: 1.8,
+    contrast: 1.5,
+    temperature: 1.0,
+    saturation: 0.8,
+    sharpness: 1.2,
+    denoise: 2.0,
+  },
+  food: {
+    brightness: 0.8,
+    contrast: 1.1,
+    temperature: 1.3,
+    saturation: 1.3,
+    sharpness: 1.2,
+    denoise: 0.5,
+  },
+  document: {
+    brightness: 1.5,
+    contrast: 2.0,
+    temperature: 1.0,
+    saturation: 0.0,
+    sharpness: 2.0,
+    denoise: 2.0,
+  },
+};
+
+const ISSUE_LABELS: Record<string, string> = {
+  underexposed: "Low Exposure",
+  overexposed: "Overexposed",
+  "low-contrast": "Flat Contrast",
+  "color-cast": "Color Cast",
+  desaturated: "Desaturated",
+  "soft-focus": "Soft Focus",
+  noisy: "Noisy",
+};
+
+const ISSUE_TO_TOGGLE: Record<string, string> = {
+  underexposed: "exposure",
+  overexposed: "exposure",
+  "low-contrast": "contrast",
+  "color-cast": "whiteBalance",
+  desaturated: "saturation",
+  "soft-focus": "sharpness",
+  noisy: "denoise",
+};
+
+interface ImageEnhancementControlsProps {
+  settings?: Record<string, unknown>;
+  onChange?: (settings: Record<string, unknown>) => void;
+  onPreviewFilter?: (filter: string) => void;
+}
+
+export function ImageEnhancementControls({
+  settings: initialSettings,
+  onChange,
+  onPreviewFilter,
+}: ImageEnhancementControlsProps) {
+  const { files } = useFileStore();
+  const [mode, setMode] = useState<EnhancementMode>("auto");
+  const [intensity, setIntensity] = useState(50);
+  const [analysis, setAnalysis] = useState<AnalysisData | null>(null);
+  const [analyzing, setAnalyzing] = useState(false);
+  const [toggles, setToggles] = useState<Record<string, boolean>>({
+    exposure: true,
+    contrast: true,
+    whiteBalance: true,
+    saturation: true,
+    sharpness: true,
+    denoise: true,
+  });
+
+  const analyzeAbortRef = useRef<AbortController | null>(null);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  // Analyze image when files change
+  useEffect(() => {
+    if (files.length === 0) {
+      setAnalysis(null);
+      return;
+    }
+
+    analyzeAbortRef.current?.abort();
+    const controller = new AbortController();
+    analyzeAbortRef.current = controller;
+
+    setAnalyzing(true);
+    const formData = new FormData();
+    formData.append("file", files[0]);
+
+    fetch("/api/v1/tools/image-enhancement/analyze", {
+      method: "POST",
+      body: formData,
+      signal: controller.signal,
+    })
+      .then((res) => (res.ok ? res.json() : Promise.reject(new Error("Analysis failed"))))
+      .then((data: AnalysisData) => {
+        setAnalysis(data);
+        if (data.suggestedMode !== "auto") {
+          setMode(data.suggestedMode);
+        }
+      })
+      .catch((err) => {
+        if (err.name !== "AbortError") {
+          console.error("Analysis error:", err);
+        }
+      })
+      .finally(() => setAnalyzing(false));
+
+    return () => controller.abort();
+  }, [files]);
+
+  // Emit settings when mode/intensity/toggles change
+  useEffect(() => {
+    onChangeRef.current?.({ mode, intensity, corrections: toggles });
+  }, [mode, intensity, toggles]);
+
+  // CSS filter preview
+  useEffect(() => {
+    if (!onPreviewFilter || !analysis) {
+      onPreviewFilter?.("");
+      return;
+    }
+
+    const presets = PRESET_MULTIPLIERS[mode];
+    const scale = intensity / 50;
+    const c = analysis.corrections;
+    const parts: string[] = [];
+
+    if (toggles.exposure && Math.abs(c.brightness) > 2) {
+      const adj = c.brightness * (presets.brightness ?? 1) * scale;
+      parts.push(`brightness(${1 + adj / 100})`);
+    }
+    if (toggles.contrast && Math.abs(c.contrast) > 2) {
+      const adj = c.contrast * (presets.contrast ?? 1) * scale;
+      parts.push(`contrast(${1 + adj / 100})`);
+    }
+    if (toggles.saturation && Math.abs(c.saturation) > 2) {
+      const adj = c.saturation * (presets.saturation ?? 1) * scale;
+      parts.push(`saturate(${1 + adj / 100})`);
+    }
+    if (toggles.whiteBalance && Math.abs(c.temperature) > 2) {
+      parts.push("url(#stirling-enhance-temp-filter)");
+    }
+    if (toggles.sharpness && c.sharpness > 2) {
+      parts.push("url(#stirling-enhance-sharpen-filter)");
+    }
+
+    onPreviewFilter(parts.join(" "));
+  }, [analysis, mode, intensity, toggles, onPreviewFilter]);
+
+  const toggleCorrection = (key: string) => {
+    setToggles((prev) => ({ ...prev, [key]: !prev[key] }));
+  };
+
+  const tempAdj = analysis
+    ? (analysis.corrections.temperature * (PRESET_MULTIPLIERS[mode].temperature ?? 1) * intensity) /
+      50 /
+      100
+    : 0;
+  const sharpAdj = analysis
+    ? (analysis.corrections.sharpness * (PRESET_MULTIPLIERS[mode].sharpness ?? 1) * intensity) /
+      50 /
+      100
+    : 0;
+
+  return (
+    <>
+      {/* Hidden SVG filters for preview */}
+      {toggles.whiteBalance && Math.abs(tempAdj) > 0.02 && (
+        <svg width="0" height="0" style={{ position: "absolute" }}>
+          <filter id="stirling-enhance-temp-filter" colorInterpolationFilters="sRGB">
+            <feColorMatrix
+              type="matrix"
+              values={`${1 + tempAdj * 0.15} 0 0 0 0  0 ${1 + tempAdj * 0.05} 0 0 0  0 0 ${1 - tempAdj * 0.15} 0 0  0 0 0 1 0`}
+            />
+          </filter>
+        </svg>
+      )}
+      {toggles.sharpness && sharpAdj > 0.02 && (
+        <svg width="0" height="0" style={{ position: "absolute" }}>
+          <filter id="stirling-enhance-sharpen-filter" colorInterpolationFilters="sRGB">
+            <feConvolveMatrix
+              order="3"
+              preserveAlpha="true"
+              kernelMatrix={`0 ${-sharpAdj} 0 ${-sharpAdj} ${1 + 4 * sharpAdj} ${-sharpAdj} 0 ${-sharpAdj} 0`}
+            />
+          </filter>
+        </svg>
+      )}
+
+      {/* Mode selector */}
+      <p className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/70">
+        Enhancement Mode
+      </p>
+      <div className="grid grid-cols-3 gap-1">
+        {MODES.map(({ value, label, icon: Icon }) => (
+          <button
+            key={value}
+            type="button"
+            onClick={() => setMode(value)}
+            className={`flex items-center justify-center gap-1 text-xs py-2 rounded transition-colors ${
+              mode === value
+                ? "bg-primary text-primary-foreground"
+                : "bg-muted text-muted-foreground hover:bg-primary/10"
+            }`}
+          >
+            <Icon className="h-3 w-3" />
+            {label}
+          </button>
+        ))}
+      </div>
+
+      {/* Intensity slider */}
+      <div className="pt-1">
+        <div className="flex justify-between items-center">
+          <p className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/70">
+            Intensity
+          </p>
+          <span className="text-xs font-mono text-foreground tabular-nums">{intensity}%</span>
+        </div>
+        <input
+          type="range"
+          min={0}
+          max={100}
+          value={intensity}
+          onChange={(e) => setIntensity(Number(e.target.value))}
+          className="w-full mt-1"
+        />
+      </div>
+
+      {/* Analysis badges */}
+      {analyzing && (
+        <div className="flex items-center gap-2 text-xs text-muted-foreground py-1">
+          <div className="h-3 w-3 border border-primary border-t-transparent rounded-full animate-spin" />
+          Analyzing image...
+        </div>
+      )}
+
+      {analysis && !analyzing && (
+        <div className="space-y-2">
+          <p className="text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/70">
+            Detected Issues
+          </p>
+          {analysis.issues.length === 0 ? (
+            <p className="text-xs text-muted-foreground">
+              Image looks good. Fine-tune with the intensity slider.
+            </p>
+          ) : (
+            <div className="flex flex-wrap gap-1">
+              {analysis.issues.map((issue) => {
+                const toggleKey = ISSUE_TO_TOGGLE[issue];
+                const isEnabled = toggleKey ? toggles[toggleKey] !== false : true;
+                return (
+                  <button
+                    key={issue}
+                    type="button"
+                    onClick={() => toggleKey && toggleCorrection(toggleKey)}
+                    className={`inline-flex items-center gap-1 text-[11px] px-2 py-1 rounded-full transition-colors ${
+                      isEnabled
+                        ? "bg-amber-500/15 text-amber-600 dark:text-amber-400"
+                        : "bg-muted text-muted-foreground line-through"
+                    }`}
+                  >
+                    {ISSUE_LABELS[issue] || issue}
+                    {isEnabled && toggleKey && <X className="h-2.5 w-2.5 opacity-60" />}
+                  </button>
+                );
+              })}
+            </div>
+          )}
+
+          {/* Score indicators */}
+          <div className="grid grid-cols-3 gap-x-3 gap-y-1 pt-1">
+            {(
+              [
+                ["Exposure", analysis.scores.exposure],
+                ["Contrast", analysis.scores.contrast],
+                ["White Bal", analysis.scores.whiteBalance],
+                ["Saturation", analysis.scores.saturation],
+                ["Sharpness", analysis.scores.sharpness],
+                ["Noise", analysis.scores.noise],
+              ] as const
+            ).map(([label, score]) => (
+              <div key={label} className="flex items-center gap-1.5">
+                <div className="flex-1 h-1 rounded-full bg-muted overflow-hidden">
+                  <div
+                    className={`h-full rounded-full transition-all ${
+                      score < 35 ? "bg-amber-500" : score > 65 ? "bg-blue-500" : "bg-emerald-500"
+                    }`}
+                    style={{ width: `${score}%` }}
+                  />
+                </div>
+                <span className="text-[10px] text-muted-foreground/60 w-10 shrink-0">{label}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </>
+  );
+}
+
+// Wrapper with process/download flow
+
+export function ImageEnhancementSettings({
+  onPreviewFilter,
+}: {
+  onPreviewFilter?: (filter: string) => void;
+}) {
+  const { files } = useFileStore();
+  const {
+    processFiles,
+    processAllFiles,
+    processing,
+    error,
+    downloadUrl,
+    originalSize,
+    processedSize,
+    progress,
+  } = useToolProcessor("image-enhancement");
+  const [settings, setSettings] = useState<Record<string, unknown>>({});
+
+  const hasFile = files.length > 0;
+
+  const handleProcess = () => {
+    if (files.length > 1) {
+      processAllFiles(files, settings);
+    } else {
+      processFiles(files, settings);
+    }
+  };
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (hasFile && !processing) handleProcess();
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-3">
+      <ImageEnhancementControls onChange={setSettings} onPreviewFilter={onPreviewFilter} />
+
+      {error && <p className="text-xs text-red-500">{error}</p>}
+
+      {originalSize != null && processedSize != null && (
+        <div className="text-xs text-muted-foreground space-y-0.5">
+          <p>Original: {(originalSize / 1024).toFixed(1)} KB</p>
+          <p>Enhanced: {(processedSize / 1024).toFixed(1)} KB</p>
+        </div>
+      )}
+
+      {processing ? (
+        <ProgressCard
+          active={processing}
+          phase={progress.phase === "idle" ? "uploading" : progress.phase}
+          label={files.length > 1 ? `Enhancing ${files.length} images` : "Enhancing image"}
+          percent={progress.percent}
+          elapsed={progress.elapsed}
+        />
+      ) : (
+        <button
+          type="submit"
+          data-testid="image-enhancement-submit"
+          disabled={!hasFile || processing}
+          className="w-full py-2.5 rounded-lg bg-primary text-primary-foreground font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
+        >
+          {files.length > 1 ? `Enhance (${files.length} files)` : "Enhance"}
+        </button>
+      )}
+
+      {downloadUrl && files.length <= 1 && (
+        <a
+          href={downloadUrl}
+          download
+          data-testid="image-enhancement-download"
+          className="w-full py-2.5 rounded-lg border border-primary text-primary font-medium flex items-center justify-center gap-2 hover:bg-primary/5"
+        >
+          <Download className="h-4 w-4" />
+          Download
+        </a>
+      )}
+    </form>
+  );
+}

apps/web/src/lib/suggested-tools.ts

@@ -10,6 +10,7 @@ const TOOL_SUGGESTIONS: Record<string, string[]> = {
   "remove-background": ["resize", "compress", "convert"],
   upscale: ["compress", "convert"],
   "smart-crop": ["resize", "compress"],
+  "image-enhancement": ["adjust-colors", "upscale", "compress"],
   "watermark-text": ["compress", "convert"],
   "watermark-image": ["compress", "convert"],
   "text-overlay": ["compress", "convert"],

apps/web/src/lib/tool-registry.tsx

@@ -234,6 +234,11 @@ const SmartCropSettings = lazy(() =>
     default: m.SmartCropSettings,
   })),
 );
+const ImageEnhancementSettings = lazy(() =>
+  import("@/components/tools/image-enhancement-settings").then((m) => ({
+    default: m.ImageEnhancementSettings,
+  })),
+);
 
 // ── Color tool wrapper ─────────────────────────────────────────────
 // Color tools share a single component but differ by toolId.
@@ -351,6 +356,14 @@ export const toolRegistry = new Map<string, ToolRegistryEntry>([
     },
   ],
   ["smart-crop", { displayMode: "before-after", Settings: SmartCropSettings }],
+  [
+    "image-enhancement",
+    {
+      displayMode: "live-preview" as DisplayMode,
+      livePreview: true,
+      Settings: ImageEnhancementSettings as never,
+    },
+  ],
 ]);
 
 export function getToolRegistryEntry(toolId: string): ToolRegistryEntry | undefined {

packages/image-engine/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./engine.js";
 export * from "./formats/detect.js";
+export { analyzeImage, applyCorrections, scaleCorrections } from "./operations/auto-enhance.js";
 export { brightness } from "./operations/brightness.js";
 export { colorChannels } from "./operations/color-channels.js";
 export { compress } from "./operations/compress.js";

packages/image-engine/src/operations/auto-enhance.ts

@@ -0,0 +1,279 @@
+import sharp from "sharp";
+import type {
+  AnalysisResult,
+  AnalysisScores,
+  CorrectionParams,
+  EnhancementMode,
+  Sharp,
+} from "../types.js";
+
+/**
+ * Preset multipliers applied to auto-computed corrections.
+ * Each value scales the corresponding correction (1.0 = unchanged).
+ */
+const PRESET_MULTIPLIERS: Record<
+  EnhancementMode,
+  {
+    brightness: number;
+    contrast: number;
+    temperature: number;
+    saturation: number;
+    sharpness: number;
+    denoise: number;
+  }
+> = {
+  auto: {
+    brightness: 1.0,
+    contrast: 1.0,
+    temperature: 1.0,
+    saturation: 1.0,
+    sharpness: 1.0,
+    denoise: 1.0,
+  },
+  portrait: {
+    brightness: 0.8,
+    contrast: 0.7,
+    temperature: 1.2,
+    saturation: 0.6,
+    sharpness: 0.5,
+    denoise: 1.5,
+  },
+  landscape: {
+    brightness: 1.0,
+    contrast: 1.3,
+    temperature: 1.0,
+    saturation: 1.4,
+    sharpness: 1.5,
+    denoise: 0.5,
+  },
+  "low-light": {
+    brightness: 1.8,
+    contrast: 1.5,
+    temperature: 1.0,
+    saturation: 0.8,
+    sharpness: 1.2,
+    denoise: 2.0,
+  },
+  food: {
+    brightness: 0.8,
+    contrast: 1.1,
+    temperature: 1.3,
+    saturation: 1.3,
+    sharpness: 1.2,
+    denoise: 0.5,
+  },
+  document: {
+    brightness: 1.5,
+    contrast: 2.0,
+    temperature: 1.0,
+    saturation: 0.0,
+    sharpness: 2.0,
+    denoise: 2.0,
+  },
+};
+
+/**
+ * Analyze an image buffer and return quality scores + computed corrections.
+ * Uses Sharp's stats() for per-channel histogram statistics.
+ */
+export async function analyzeImage(buffer: Buffer): Promise<AnalysisResult> {
+  const image = sharp(buffer);
+  const stats = await image.stats();
+  const meta = await image.metadata();
+
+  const channels = stats.channels;
+  const isGrayscale = channels.length === 1;
+
+  const rCh = channels[0];
+  const gCh = channels[Math.min(1, channels.length - 1)];
+  const bCh = channels[Math.min(2, channels.length - 1)];
+
+  // Overall luminance approximation (BT.601 weights)
+  const meanLuminance = rCh.mean * 0.299 + gCh.mean * 0.587 + bCh.mean * 0.114;
+  const stdevLuminance = rCh.stdev * 0.299 + gCh.stdev * 0.587 + bCh.stdev * 0.114;
+
+  const scores = computeScores(
+    rCh,
+    gCh,
+    bCh,
+    meanLuminance,
+    stdevLuminance,
+    isGrayscale,
+    stats.entropy,
+  );
+  const corrections = computeCorrections(scores);
+  const issues = detectIssues(scores);
+  const suggestedMode = suggestMode(scores, meta);
+
+  return { scores, corrections, issues, suggestedMode };
+}
+
+function computeScores(
+  rCh: sharp.ChannelStats,
+  gCh: sharp.ChannelStats,
+  bCh: sharp.ChannelStats,
+  meanLum: number,
+  stdevLum: number,
+  isGrayscale: boolean,
+  entropy: number,
+): AnalysisScores {
+  const exposureScore = clamp(Math.round((meanLum / 255) * 100), 0, 100);
+
+  const idealStdev = 60;
+  const contrastDeviation = Math.abs(stdevLum - idealStdev) / idealStdev;
+  const contrastScore = clamp(Math.round((1 - contrastDeviation) * 50 + 25), 0, 100);
+
+  const meanR = rCh.mean;
+  const meanG = gCh.mean;
+  const meanB = bCh.mean;
+  const channelSpread = Math.max(meanR, meanG, meanB) - Math.min(meanR, meanG, meanB);
+  const wbScore = isGrayscale ? 50 : clamp(Math.round(50 - channelSpread * 0.8), 0, 100);
+
+  const satScore = isGrayscale ? 50 : clamp(Math.round(channelSpread * 1.2 + 20), 0, 100);
+
+  const sharpnessScore = clamp(Math.round(stdevLum * 0.8 + 10), 0, 100);
+
+  const noiseScore = clamp(Math.round(100 - (entropy - 5) * 20), 0, 100);
+
+  return {
+    exposure: exposureScore,
+    contrast: contrastScore,
+    whiteBalance: wbScore,
+    saturation: satScore,
+    sharpness: sharpnessScore,
+    noise: noiseScore,
+  };
+}
+
+function computeCorrections(scores: AnalysisScores): CorrectionParams {
+  const brightness = clamp(Math.round((50 - scores.exposure) * 1.2), -60, 60);
+  const contrast = clamp(Math.round((50 - scores.contrast) * 0.8), -40, 40);
+  const temperature = clamp(Math.round((50 - scores.whiteBalance) * 0.5), -30, 30);
+
+  const saturation =
+    scores.saturation < 40
+      ? clamp(Math.round((40 - scores.saturation) * 0.6), 0, 30)
+      : scores.saturation > 60
+        ? clamp(Math.round((60 - scores.saturation) * 0.4), -20, 0)
+        : 0;
+
+  const sharpness =
+    scores.sharpness < 40 ? clamp(Math.round((40 - scores.sharpness) * 1.0), 0, 50) : 0;
+
+  const denoise = scores.noise < 25 ? 5 : scores.noise < 35 ? 3 : 0;
+
+  return { brightness, contrast, temperature, saturation, sharpness, denoise };
+}
+
+function detectIssues(scores: AnalysisScores): string[] {
+  const issues: string[] = [];
+  if (scores.exposure < 35) issues.push("underexposed");
+  if (scores.exposure > 70) issues.push("overexposed");
+  if (scores.contrast < 35) issues.push("low-contrast");
+  if (scores.whiteBalance < 35) issues.push("color-cast");
+  if (scores.saturation < 30) issues.push("desaturated");
+  if (scores.sharpness < 35) issues.push("soft-focus");
+  if (scores.noise < 30) issues.push("noisy");
+  return issues;
+}
+
+function suggestMode(scores: AnalysisScores, _meta: sharp.Metadata): EnhancementMode {
+  if (scores.exposure < 30) return "low-light";
+  if (scores.contrast > 60 && scores.saturation < 30) return "document";
+  return "auto";
+}
+
+/**
+ * Apply auto-enhancement corrections to a Sharp pipeline.
+ */
+export function applyCorrections(
+  image: Sharp,
+  corrections: CorrectionParams,
+  mode: EnhancementMode,
+  intensity: number,
+  toggles: Record<string, boolean>,
+): Sharp {
+  const presets = PRESET_MULTIPLIERS[mode];
+  const scale = intensity / 50;
+
+  let result = image;
+
+  if (toggles.exposure !== false) {
+    const adj = corrections.brightness * presets.brightness * scale;
+    if (Math.abs(adj) > 2) {
+      const multiplier = clamp(1 + adj / 100, 0.2, 3.0);
+      result = result.modulate({ brightness: multiplier });
+    }
+  }
+
+  if (toggles.contrast !== false) {
+    const adj = corrections.contrast * presets.contrast * scale;
+    if (Math.abs(adj) > 2) {
+      const slope = 1 + adj / 100;
+      const intercept = 128 * (1 - slope);
+      result = result.linear(slope, intercept);
+    }
+  }
+
+  if (toggles.whiteBalance !== false) {
+    const adj = corrections.temperature * presets.temperature * scale;
+    if (Math.abs(adj) > 2) {
+      const t = adj / 100;
+      result = result.recomb([
+        [1 + t * 0.15, 0, 0],
+        [0, 1 + t * 0.05, 0],
+        [0, 0, 1 - t * 0.15],
+      ]);
+    }
+  }
+
+  if (toggles.saturation !== false) {
+    const adj = corrections.saturation * presets.saturation * scale;
+    if (Math.abs(adj) > 2) {
+      result = result.modulate({ saturation: 1 + adj / 100 });
+    }
+  }
+
+  if (toggles.sharpness !== false) {
+    const adj = corrections.sharpness * presets.sharpness * scale;
+    if (adj > 2) {
+      const sigma = 0.5 + (adj / 100) * 4;
+      result = result.sharpen({ sigma });
+    }
+  }
+
+  if (toggles.denoise !== false) {
+    const adj = corrections.denoise * presets.denoise * scale;
+    if (adj >= 2) {
+      const kernel = adj >= 4 ? 5 : 3;
+      result = result.median(kernel);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Scale corrections by intensity and preset multipliers, returning
+ * CSS-compatible values for the frontend live preview.
+ */
+export function scaleCorrections(
+  corrections: CorrectionParams,
+  mode: EnhancementMode,
+  intensity: number,
+): CorrectionParams {
+  const presets = PRESET_MULTIPLIERS[mode];
+  const scale = intensity / 50;
+  return {
+    brightness: Math.round(corrections.brightness * presets.brightness * scale),
+    contrast: Math.round(corrections.contrast * presets.contrast * scale),
+    temperature: Math.round(corrections.temperature * presets.temperature * scale),
+    saturation: Math.round(corrections.saturation * presets.saturation * scale),
+    sharpness: Math.round(corrections.sharpness * presets.sharpness * scale),
+    denoise: Math.round(corrections.denoise * presets.denoise * scale),
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}

packages/image-engine/src/types.ts

@@ -108,3 +108,45 @@ export interface ColorChannelOptions {
 export interface SharpenOptions {
   value: number; // 0 to 100
 }
+
+export type EnhancementMode = "auto" | "portrait" | "landscape" | "low-light" | "food" | "document";
+
+export interface AnalysisScores {
+  /** 0-100, 50 = ideal exposure */
+  exposure: number;
+  /** 0-100, 50 = ideal contrast */
+  contrast: number;
+  /** 0-100, 50 = neutral white balance */
+  whiteBalance: number;
+  /** 0-100, 50 = ideal saturation */
+  saturation: number;
+  /** 0-100, 50 = ideally sharp */
+  sharpness: number;
+  /** 0-100, 50 = no significant noise */
+  noise: number;
+}
+
+export interface AnalysisResult {
+  scores: AnalysisScores;
+  /** CSS-filter-compatible correction values for live preview */
+  corrections: CorrectionParams;
+  /** Human-readable issue labels, e.g. ["underexposed", "color-cast"] */
+  issues: string[];
+  /** Best-guess preset for this image */
+  suggestedMode: EnhancementMode;
+}
+
+export interface CorrectionParams {
+  /** Maps to CSS brightness() and Sharp gamma. -100 to +100. */
+  brightness: number;
+  /** Maps to CSS contrast() and Sharp linear(). -100 to +100. */
+  contrast: number;
+  /** Maps to recomb matrix / CSS feColorMatrix. -100 to +100. */
+  temperature: number;
+  /** Maps to CSS saturate() and Sharp modulate(). -100 to +100. */
+  saturation: number;
+  /** Maps to SVG feConvolveMatrix and Sharp sharpen(). 0 to 100. */
+  sharpness: number;
+  /** Denoise strength. 0 = off, 1-5 = median kernel size. */
+  denoise: number;
+}

packages/shared/src/constants.ts

@@ -161,6 +161,14 @@ export const TOOLS: Tool[] = [
     icon: "Focus",
     route: "/smart-crop",
   },
+  {
+    id: "image-enhancement",
+    name: "Image Enhancement",
+    description: "One-click auto-improve with smart analysis",
+    category: "ai",
+    icon: "Sparkles",
+    route: "/image-enhancement",
+  },
   // Watermark & Overlay
   {
     id: "watermark-text",

packages/shared/src/i18n/en.ts

@@ -71,6 +71,11 @@ export const en = {
       name: "Smart Crop",
       description: "Smart subject, face, or trim-based cropping",
     },
+    "image-enhancement": {
+      name: "Image Enhancement",
+      description:
+        "One-click auto-improve with smart exposure, contrast, color, and sharpness correction",
+    },
     "content-aware-resize": {
       name: "Content-Aware Resize",
       description: "Intelligently resize images while preserving important content",

tests/e2e/tools-process.spec.ts

@@ -120,6 +120,21 @@ test.describe("Tool processing (core tools)", () => {
     });
   });
 
+  test("image-enhancement processes image", async ({ loggedInPage: page }) => {
+    await page.goto("/image-enhancement");
+    await uploadTestImage(page);
+    // Wait for analysis to complete (badges appear)
+    await expect(
+      page.locator("text=Intensity").or(page.locator("text=Enhancement Mode")),
+    ).toBeVisible({ timeout: 10_000 });
+    // Click Enhance button
+    await page.getByRole("button", { name: /^enhance$/i }).click();
+    await waitForProcessing(page);
+    await expect(page.getByRole("link", { name: /download/i }).first()).toBeVisible({
+      timeout: 15_000,
+    });
+  });
+
   test("border processes image", async ({ loggedInPage: page }) => {
     await page.goto("/border");
     await uploadTestImage(page);

tests/integration/api.test.ts

@@ -3952,3 +3952,107 @@ describe("Edit metadata", () => {
     });
   });
 });
+
+describe("Image Enhancement", () => {
+  it("POST /api/v1/tools/image-enhancement processes an image", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "test.png", contentType: "image/png", content: PNG_200x150 },
+      {
+        name: "settings",
+        content: JSON.stringify({
+          mode: "auto",
+          intensity: 50,
+          corrections: {
+            exposure: true,
+            contrast: true,
+            whiteBalance: true,
+            saturation: true,
+            sharpness: true,
+            denoise: true,
+          },
+        }),
+      },
+    ]);
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image-enhancement",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.jobId).toBeDefined();
+    expect(body.downloadUrl).toBeDefined();
+    expect(body.processedSize).toBeGreaterThan(0);
+  });
+
+  it("POST /api/v1/tools/image-enhancement/analyze returns analysis data", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "test.png", contentType: "image/png", content: PNG_200x150 },
+    ]);
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image-enhancement/analyze",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.scores).toBeDefined();
+    expect(body.corrections).toBeDefined();
+    expect(body.issues).toBeInstanceOf(Array);
+    expect(body.suggestedMode).toBeDefined();
+    expect(typeof body.scores.exposure).toBe("number");
+  });
+
+  it("preserves JPEG format through enhancement", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "photo.jpg", contentType: "image/jpeg", content: JPG_100x100 },
+      {
+        name: "settings",
+        content: JSON.stringify({
+          mode: "auto",
+          intensity: 50,
+        }),
+      },
+    ]);
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image-enhancement",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.downloadUrl).toMatch(/\.jpg/);
+  });
+
+  it("rejects empty file", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "empty.png", contentType: "image/png", content: Buffer.alloc(0) },
+      {
+        name: "settings",
+        content: JSON.stringify({ mode: "auto" }),
+      },
+    ]);
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image-enhancement",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(400);
+  });
+});

tests/unit/auto-enhance.test.ts

@@ -0,0 +1,175 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { analyzeImage, applyCorrections, scaleCorrections } from "@stirling-image/image-engine";
+import sharp from "sharp";
+import { describe, expect, it } from "vitest";
+
+const FIXTURES = join(__dirname, "..", "fixtures");
+const PNG_200x150 = readFileSync(join(FIXTURES, "test-200x150.png"));
+
+describe("analyzeImage", () => {
+  it("returns scores, corrections, issues, and suggestedMode", async () => {
+    const result = await analyzeImage(PNG_200x150);
+    expect(result.scores).toBeDefined();
+    expect(result.corrections).toBeDefined();
+    expect(result.issues).toBeInstanceOf(Array);
+    expect(result.suggestedMode).toBeDefined();
+
+    for (const key of Object.keys(result.scores) as (keyof typeof result.scores)[]) {
+      expect(result.scores[key]).toBeGreaterThanOrEqual(0);
+      expect(result.scores[key]).toBeLessThanOrEqual(100);
+    }
+  });
+
+  it("detects underexposure on a dark image", async () => {
+    const darkBuffer = await sharp({
+      create: { width: 100, height: 100, channels: 3, background: { r: 20, g: 20, b: 20 } },
+    })
+      .png()
+      .toBuffer();
+
+    const result = await analyzeImage(darkBuffer);
+    expect(result.scores.exposure).toBeLessThan(30);
+    expect(result.issues).toContain("underexposed");
+    expect(result.corrections.brightness).toBeGreaterThan(0);
+  });
+
+  it("detects overexposure on a bright image", async () => {
+    const brightBuffer = await sharp({
+      create: { width: 100, height: 100, channels: 3, background: { r: 240, g: 240, b: 240 } },
+    })
+      .png()
+      .toBuffer();
+
+    const result = await analyzeImage(brightBuffer);
+    expect(result.scores.exposure).toBeGreaterThan(70);
+    expect(result.issues).toContain("overexposed");
+    expect(result.corrections.brightness).toBeLessThan(0);
+  });
+
+  it("detects low contrast on a flat image", async () => {
+    const flatBuffer = await sharp({
+      create: { width: 100, height: 100, channels: 3, background: { r: 128, g: 128, b: 128 } },
+    })
+      .png()
+      .toBuffer();
+
+    const result = await analyzeImage(flatBuffer);
+    expect(result.scores.contrast).toBeLessThan(40);
+    expect(result.corrections.contrast).toBeGreaterThan(0);
+  });
+
+  it("handles grayscale images without white balance issues", async () => {
+    const grayBuffer = await sharp({
+      create: { width: 100, height: 100, channels: 3, background: { r: 128, g: 128, b: 128 } },
+    })
+      .grayscale()
+      .png()
+      .toBuffer();
+
+    const result = await analyzeImage(grayBuffer);
+    expect(result.scores.whiteBalance).toBe(50);
+    // Grayscale PNG from .grayscale() retains 3 channels with zero spread,
+    // so saturation formula yields channelSpread * 1.2 + 20 = 20
+    expect(result.scores.saturation).toBe(20);
+  });
+
+  it("suggests low-light mode for very dark images", async () => {
+    const darkBuffer = await sharp({
+      create: { width: 100, height: 100, channels: 3, background: { r: 15, g: 15, b: 15 } },
+    })
+      .png()
+      .toBuffer();
+
+    const result = await analyzeImage(darkBuffer);
+    expect(result.suggestedMode).toBe("low-light");
+  });
+});
+
+describe("scaleCorrections", () => {
+  it("scales corrections by intensity 50 (1x) without change", () => {
+    const base = {
+      brightness: 20,
+      contrast: 10,
+      temperature: 5,
+      saturation: 15,
+      sharpness: 30,
+      denoise: 3,
+    };
+    const scaled = scaleCorrections(base, "auto", 50);
+    expect(scaled.brightness).toBe(20);
+    expect(scaled.contrast).toBe(10);
+  });
+
+  it("scales corrections to zero at intensity 0", () => {
+    const base = {
+      brightness: 20,
+      contrast: 10,
+      temperature: 5,
+      saturation: 15,
+      sharpness: 30,
+      denoise: 3,
+    };
+    const scaled = scaleCorrections(base, "auto", 0);
+    expect(scaled.brightness).toBe(0);
+    expect(scaled.contrast).toBe(0);
+    expect(scaled.sharpness).toBe(0);
+  });
+
+  it("applies preset multipliers for portrait mode", () => {
+    const base = {
+      brightness: 20,
+      contrast: 10,
+      temperature: 5,
+      saturation: 15,
+      sharpness: 30,
+      denoise: 3,
+    };
+    const scaled = scaleCorrections(base, "portrait", 50);
+    expect(scaled.brightness).toBe(16);
+    expect(scaled.contrast).toBe(7);
+  });
+});
+
+describe("applyCorrections", () => {
+  it("produces a valid output buffer", async () => {
+    const corrections = {
+      brightness: -20,
+      contrast: 10,
+      temperature: 0,
+      saturation: 10,
+      sharpness: 20,
+      denoise: 0,
+    };
+    const image = sharp(PNG_200x150);
+    const enhanced = applyCorrections(image, corrections, "auto", 50, {});
+    const buffer = await enhanced.toBuffer();
+    expect(buffer.length).toBeGreaterThan(0);
+  });
+
+  it("respects toggle overrides", async () => {
+    const corrections = {
+      brightness: 40,
+      contrast: 30,
+      temperature: 20,
+      saturation: 20,
+      sharpness: 30,
+      denoise: 3,
+    };
+    const toggles = {
+      exposure: false,
+      contrast: false,
+      whiteBalance: false,
+      saturation: false,
+      sharpness: false,
+      denoise: false,
+    };
+    const image = sharp(PNG_200x150);
+    const enhanced = applyCorrections(image, corrections, "auto", 50, toggles);
+    const enhancedBuf = await enhanced.toBuffer();
+    const originalMeta = await sharp(PNG_200x150).metadata();
+    const enhancedMeta = await sharp(enhancedBuf).metadata();
+    expect(enhancedMeta.width).toBe(originalMeta.width);
+    expect(enhancedMeta.height).toBe(originalMeta.height);
+  });
+});