feat(smart-crop): overhaul with face detection, social presets, and 3 modes

Replace the confusing 2-mode smart crop with a clear 3-mode system:
- Subject Focus: Sharp attention/entropy saliency crop with social media presets
- Face Focus: MediaPipe face detection with headshot framing presets
- Auto Trim: Border removal with optional pad-to-square

Adds detectFaces() to AI package, face preset constants, backward
compatibility for old mode names, and comprehensive integration tests.

apps/api/src/openapi.yaml

@@ -780,7 +780,7 @@ paths:
     post:
       tags: [Tools]
       summary: Smart crop
-      description: Automatically crop to the most interesting region at the specified dimensions.
+      description: Smart crop with three modes - subject focus, face focus, or auto trim.
       security:
         - bearerAuth: []
       requestBody:
@@ -799,8 +799,18 @@ paths:
                   type: string
                   description: |
                     JSON string with options:
-                    - `width` (integer, required) — Target width in pixels
+                    - `mode` (string) — "subject" (default), "face", or "trim"
-                    - `height` (integer, required) — Target height in pixels
+                    - `strategy` (string) — "attention" (default) or "entropy" (subject mode)
+                    - `width` (integer) — Target width in pixels (default 1080)
+                    - `height` (integer) — Target height in pixels (default 1080)
+                    - `padding` (integer 0-50) — Padding percentage around focus area
+                    - `facePreset` (string) — "closeup", "head-shoulders", "upper-body", "half-body" (face mode)
+                    - `sensitivity` (number 0-1) — Face detection sensitivity (face mode)
+                    - `threshold` (integer 0-255) — Trim tolerance (trim mode)
+                    - `padToSquare` (boolean) — Pad to square after trimming (trim mode)
+                    - `padColor` (string) — Hex color for padding (trim mode)
+                    - `targetSize` (integer) — Target size for padded output (trim mode)
+                    - `quality` (integer 1-100) — Output quality
       responses:
         "200":
           description: Processed image

apps/api/src/routes/tools/smart-crop.ts

@@ -1,26 +1,178 @@
+import { detectFaces } from "@stirling-image/ai";
+import { SMART_CROP_FACE_PRESETS } from "@stirling-image/shared";
 import type { FastifyInstance } from "fastify";
 import sharp from "sharp";
 import { z } from "zod";
 import { resolveOutputFormat } from "../../lib/output-format.js";
 import { createToolRoute } from "../tool-factory.js";
 
-const settingsSchema = z.object({
+const settingsSchema = z
-  mode: z.enum(["attention", "content"]).default("attention"),
+  .object({
-  width: z.number().int().positive().optional(),
+    mode: z
-  height: z.number().int().positive().optional(),
+      .enum(["subject", "face", "trim", "attention", "content"])
-  threshold: z.number().int().min(0).max(255).default(30),
+      .default("subject")
-  padToSquare: z.boolean().default(false),
+      .transform((v) => {
-  padColor: z.string().default("#ffffff"),
+        if (v === "attention") return "subject" as const;
-  targetSize: z.number().int().positive().optional(),
+        if (v === "content") return "trim" as const;
-  quality: z.number().int().min(1).max(100).optional(),
+        return v;
-});
+      }),
+    strategy: z.enum(["attention", "entropy"]).default("attention"),
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    padding: z.number().int().min(0).max(50).default(0),
+    facePreset: z
+      .enum(["closeup", "head-shoulders", "upper-body", "half-body"])
+      .default("head-shoulders"),
+    sensitivity: z.number().min(0).max(1).default(0.5),
+    threshold: z.number().int().min(0).max(255).default(30),
+    padToSquare: z.boolean().default(false),
+    padColor: z.string().default("#ffffff"),
+    targetSize: z.number().int().positive().optional(),
+    quality: z.number().int().min(1).max(100).optional(),
+  })
+  .transform((s) => ({
+    ...s,
+    mode: s.mode as "subject" | "face" | "trim",
+  }));
+
+function clampRegion(
+  left: number,
+  top: number,
+  cropW: number,
+  cropH: number,
+  imgW: number,
+  imgH: number,
+) {
+  const w = Math.min(cropW, imgW);
+  const h = Math.min(cropH, imgH);
+  let l = left;
+  let t = top;
+
+  if (l < 0) l = 0;
+  if (t < 0) t = 0;
+  if (l + w > imgW) l = imgW - w;
+  if (t + h > imgH) t = imgH - h;
+
+  return {
+    left: Math.round(Math.max(0, l)),
+    top: Math.round(Math.max(0, t)),
+    width: Math.round(w),
+    height: Math.round(h),
+  };
+}
+
+async function processSubject(
+  inputBuffer: Buffer,
+  settings: z.output<typeof settingsSchema>,
+): Promise<Buffer> {
+  const w = settings.width ?? 1080;
+  const h = settings.height ?? 1080;
+  const strategy =
+    settings.strategy === "entropy" ? sharp.strategy.entropy : sharp.strategy.attention;
+
+  if (settings.padding > 0) {
+    const scale = 1 + settings.padding / 100;
+    const oversizeW = Math.round(w * scale);
+    const oversizeH = Math.round(h * scale);
+
+    const oversize = await sharp(inputBuffer)
+      .resize(oversizeW, oversizeH, { fit: "cover", position: strategy })
+      .toBuffer();
+
+    const extractLeft = Math.round((oversizeW - w) / 2);
+    const extractTop = Math.round((oversizeH - h) / 2);
+
+    return sharp(oversize)
+      .extract({ left: extractLeft, top: extractTop, width: w, height: h })
+      .toBuffer();
+  }
+
+  return sharp(inputBuffer).resize(w, h, { fit: "cover", position: strategy }).toBuffer();
+}
+
+async function processFace(
+  inputBuffer: Buffer,
+  settings: z.output<typeof settingsSchema>,
+): Promise<Buffer> {
+  const result = await detectFaces(inputBuffer, { sensitivity: settings.sensitivity });
+
+  if (result.facesDetected === 0) {
+    return processSubject(inputBuffer, { ...settings, strategy: "attention" });
+  }
+
+  const meta = await sharp(inputBuffer).metadata();
+  const imgW = meta.width ?? 1;
+  const imgH = meta.height ?? 1;
+  const targetW = settings.width ?? 1080;
+  const targetH = settings.height ?? 1080;
+
+  const faces = result.faces;
+  const minX = Math.min(...faces.map((f) => f.x));
+  const minY = Math.min(...faces.map((f) => f.y));
+  const maxX = Math.max(...faces.map((f) => f.x + f.w));
+  const maxY = Math.max(...faces.map((f) => f.y + f.h));
+
+  const cx = (minX + maxX) / 2;
+  const cy = (minY + maxY) / 2;
+  const unionH = maxY - minY;
+
+  const preset = SMART_CROP_FACE_PRESETS.find((p) => p.id === settings.facePreset);
+  const multiplier = preset?.multiplier ?? 2.8;
+
+  const aspectRatio = targetW / targetH;
+  let cropH = unionH * multiplier * (1 + settings.padding / 100);
+  let cropW = cropH * aspectRatio;
+
+  if (cropW > imgW) {
+    cropW = imgW;
+    cropH = cropW / aspectRatio;
+  }
+  if (cropH > imgH) {
+    cropH = imgH;
+    cropW = cropH * aspectRatio;
+  }
+
+  const left = cx - cropW / 2;
+  const top = cy - cropH / 2;
+  const region = clampRegion(left, top, cropW, cropH, imgW, imgH);
+
+  if (region.width < 1 || region.height < 1) {
+    return processSubject(inputBuffer, { ...settings, strategy: "attention" });
+  }
+
+  const extracted = await sharp(inputBuffer).extract(region).toBuffer();
+  return sharp(extracted).resize(targetW, targetH, { fit: "fill" }).toBuffer();
+}
+
+async function processTrim(
+  inputBuffer: Buffer,
+  settings: z.output<typeof settingsSchema>,
+): Promise<Buffer> {
+  if (settings.padToSquare || settings.targetSize) {
+    const trimmed = await sharp(inputBuffer)
+      .trim({ threshold: settings.threshold })
+      .toBuffer({ resolveWithObject: true });
+
+    const w = trimmed.info.width;
+    const h = trimmed.info.height;
+    const target = settings.targetSize || Math.max(w, h);
+    const padR = Math.round(Number.parseInt(settings.padColor.slice(1, 3), 16));
+    const padG = Math.round(Number.parseInt(settings.padColor.slice(3, 5), 16));
+    const padB = Math.round(Number.parseInt(settings.padColor.slice(5, 7), 16));
+
+    return sharp(trimmed.data)
+      .resize({
+        width: target,
+        height: target,
+        fit: "contain",
+        background: { r: padR, g: padG, b: padB, alpha: 1 },
+      })
+      .toBuffer();
+  }
+
+  return sharp(inputBuffer).trim({ threshold: settings.threshold }).toBuffer();
+}
 
-/**
- * Smart crop with two modes:
- * - "attention": Sharp's entropy/saliency detection to crop to the most interesting region
- * - "content": Trims uniform-color borders (like GIMP's "Crop to Content"),
- *    optionally pads to a square at a target size
- */
 export function registerSmartCrop(app: FastifyInstance) {
   createToolRoute(app, {
     toolId: "smart-crop",
@@ -29,49 +181,18 @@ export function registerSmartCrop(app: FastifyInstance) {
       const outputFormat = await resolveOutputFormat(inputBuffer, filename, settings.quality);
       let result: Buffer;
 
-      if (settings.mode === "content") {
+      if (settings.mode === "face") {
-        if (settings.padToSquare || settings.targetSize) {
+        result = await processFace(inputBuffer, settings);
-          // Trim first to get dimensions, then pad to square
+      } else if (settings.mode === "trim") {
-          const trimmed = await sharp(inputBuffer)
+        result = await processTrim(inputBuffer, settings);
-            .trim({ threshold: settings.threshold })
-            .toBuffer({ resolveWithObject: true });
-
-          const w = trimmed.info.width;
-          const h = trimmed.info.height;
-          const target = settings.targetSize || Math.max(w, h);
-          const padR = Math.round(parseInt(settings.padColor.slice(1, 3), 16));
-          const padG = Math.round(parseInt(settings.padColor.slice(3, 5), 16));
-          const padB = Math.round(parseInt(settings.padColor.slice(5, 7), 16));
-
-          const padded = await sharp(trimmed.data)
-            .resize({
-              width: target,
-              height: target,
-              fit: "contain",
-              background: { r: padR, g: padG, b: padB, alpha: 1 },
-            })
-            .toFormat(outputFormat.format, { quality: outputFormat.quality })
-            .toBuffer();
-          result = padded;
-        } else {
-          // Simple trim + format in one pass (no intermediate encode)
-          result = await sharp(inputBuffer)
-            .trim({ threshold: settings.threshold })
-            .toFormat(outputFormat.format, { quality: outputFormat.quality })
-            .toBuffer();
-        }
       } else {
-        const w = settings.width ?? 1080;
+        result = await processSubject(inputBuffer, settings);
-        const h = settings.height ?? 1080;
-        result = await sharp(inputBuffer)
-          .resize(w, h, {
-            fit: "cover",
-            position: sharp.strategy.attention,
-          })
-          .toFormat(outputFormat.format, { quality: outputFormat.quality })
-          .toBuffer();
       }
 
+      result = await sharp(result)
+        .toFormat(outputFormat.format, { quality: outputFormat.quality })
+        .toBuffer();
+
       const stem = filename.replace(/\.[^.]+$/, "");
       const outputFilename = `${stem}_smartcrop.${outputFormat.extension}`;
       return { buffer: result, filename: outputFilename, contentType: outputFormat.contentType };

apps/web/src/components/tools/smart-crop-settings.tsx

@@ -1,131 +1,465 @@
-import { useState } from "react";
+import { SMART_CROP_FACE_PRESETS, SOCIAL_MEDIA_PRESETS } from "@stirling-image/shared";
+import { ArrowLeftRight, Info } 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 Mode = "content" | "attention";
+type CropMode = "subject" | "face" | "trim";
+type SubjectTab = "presets" | "custom";
+
+const platforms = [...new Set(SOCIAL_MEDIA_PRESETS.map((p) => p.platform))];
 
 const ASPECT_PRESETS = [
-  { label: "1:1 Square", w: 1080, h: 1080 },
+  { label: "1:1", w: 1080, h: 1080 },
-  { label: "16:9 Landscape", w: 1920, h: 1080 },
+  { label: "4:3", w: 1440, h: 1080 },
-  { label: "9:16 Portrait", w: 1080, h: 1920 },
+  { label: "3:2", w: 1620, h: 1080 },
-  { label: "4:3 Standard", w: 1440, h: 1080 },
+  { label: "16:9", w: 1920, h: 1080 },
-  { label: "3:2 Photo", w: 1620, h: 1080 },
+  { label: "4:5", w: 1080, h: 1350 },
-  { label: "Custom", w: 0, h: 0 },
+  { label: "9:16", w: 1080, h: 1920 },
 ];
 
+function HintIcon({ text }: { text: string }) {
+  return (
+    <span className="relative group">
+      <Info className="h-3 w-3 text-muted-foreground" />
+      <span className="pointer-events-none absolute left-1/2 -translate-x-1/2 bottom-full mb-1.5 w-48 rounded bg-foreground px-2 py-1.5 text-[11px] leading-tight text-background opacity-0 transition-opacity group-hover:opacity-100 z-10">
+        {text}
+      </span>
+    </span>
+  );
+}
+
 export interface SmartCropControlsProps {
   onChange?: (settings: Record<string, unknown>) => void;
 }
 
 export function SmartCropControls({ onChange }: SmartCropControlsProps) {
-  const [mode, setMode] = useState<Mode>("content");
+  const [mode, setMode] = useState<CropMode>("subject");
+  const [subjectTab, setSubjectTab] = useState<SubjectTab>("custom");
+  const [selectedPreset, setSelectedPreset] = useState<string | null>(null);
 
-  // Attention mode state
+  // Subject mode state
+  const [strategy, setStrategy] = useState<"attention" | "entropy">("attention");
+
+  // Face mode state
+  const [facePreset, setFacePreset] = useState("head-shoulders");
+  const [sensitivity, setSensitivity] = useState(50);
+
+  // Shared subject/face state
   const [width, setWidth] = useState("1080");
   const [height, setHeight] = useState("1080");
-  const [preset, setPreset] = useState("1:1 Square");
+  const [padding, setPadding] = useState(0);
 
-  // Content mode state
+  // Trim mode state
   const [threshold, setThreshold] = useState(30);
   const [padToSquare, setPadToSquare] = useState(false);
   const [padColor, setPadColor] = useState("#ffffff");
   const [targetSize, setTargetSize] = useState("1000");
+
+  // Shared
   const [quality, setQuality] = useState(95);
 
-  const emit = (overrides: Record<string, unknown> = {}) => {
+  const onChangeRef = useRef(onChange);
-    if (mode === "content") {
+  useEffect(() => {
-      onChange?.({
+    onChangeRef.current = onChange;
-        mode: "content",
+  });
+
+  useEffect(() => {
+    if (mode === "subject") {
+      onChangeRef.current?.({
+        mode: "subject",
+        strategy,
+        width: Number(width),
+        height: Number(height),
+        padding,
+        quality,
+      });
+    } else if (mode === "face") {
+      onChangeRef.current?.({
+        mode: "face",
+        facePreset,
+        sensitivity: sensitivity / 100,
+        width: Number(width),
+        height: Number(height),
+        padding,
+        quality,
+      });
+    } else {
+      onChangeRef.current?.({
+        mode: "trim",
         threshold,
         padToSquare,
         padColor,
         quality,
         ...(padToSquare ? { targetSize: Number(targetSize) } : {}),
-        ...overrides,
       });
+    }
+  }, [
+    mode,
+    strategy,
+    facePreset,
+    sensitivity,
+    width,
+    height,
+    padding,
+    threshold,
+    padToSquare,
+    padColor,
+    targetSize,
+    quality,
+  ]);
+
+  const handleSocialPreset = (preset: (typeof SOCIAL_MEDIA_PRESETS)[number]) => {
+    const key = `${preset.platform}-${preset.name}`;
+    if (selectedPreset === key) {
+      setSelectedPreset(null);
+      setWidth("1080");
+      setHeight("1080");
     } else {
-      onChange?.({
+      setSelectedPreset(key);
-        mode: "attention",
+      setWidth(String(preset.width));
-        width: Number(width),
+      setHeight(String(preset.height));
-        height: Number(height),
-        quality,
-        ...overrides,
-      });
     }
   };
 
-  const handleModeChange = (m: Mode) => {
+  const handleAspectPreset = (p: (typeof ASPECT_PRESETS)[number]) => {
-    setMode(m);
+    setWidth(String(p.w));
-    if (m === "content") {
+    setHeight(String(p.h));
-      onChange?.({ mode: "content", threshold, padToSquare, padColor, quality });
+    setSelectedPreset(null);
-    } else {
-      onChange?.({ mode: "attention", width: Number(width), height: Number(height), quality });
-    }
   };
 
-  const handlePreset = (label: string) => {
+  const swapDimensions = () => {
-    setPreset(label);
+    const tmp = width;
-    const p = ASPECT_PRESETS.find((a) => a.label === label);
+    setWidth(height);
-    if (p && p.w > 0) {
+    setHeight(tmp);
-      setWidth(String(p.w));
+    setSelectedPreset(null);
-      setHeight(String(p.h));
-      emit({ width: p.w, height: p.h });
-    }
   };
 
+  const modeTabClass = (m: CropMode) =>
+    `flex-1 text-xs py-1.5 rounded ${mode === m ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"}`;
+
+  const subTabClass = (t: SubjectTab) =>
+    `flex-1 text-[11px] py-1 rounded ${subjectTab === t ? "bg-primary/15 text-foreground font-medium" : "text-muted-foreground"}`;
+
+  // Shared dimension inputs with swap button
+  const dimensionInputs = (
+    <div className="flex items-end gap-2">
+      <div className="flex-1">
+        <label htmlFor="sc-width" className="text-xs text-muted-foreground">
+          Width (px)
+        </label>
+        <input
+          id="sc-width"
+          type="number"
+          value={width}
+          onChange={(e) => {
+            setWidth(e.target.value);
+            setSelectedPreset(null);
+          }}
+          min={1}
+          className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
+        />
+      </div>
+      <button
+        type="button"
+        onClick={swapDimensions}
+        className="p-1.5 rounded border border-border text-muted-foreground hover:text-foreground"
+        title="Swap width and height"
+      >
+        <ArrowLeftRight className="h-4 w-4" />
+      </button>
+      <div className="flex-1">
+        <label htmlFor="sc-height" className="text-xs text-muted-foreground">
+          Height (px)
+        </label>
+        <input
+          id="sc-height"
+          type="number"
+          value={height}
+          onChange={(e) => {
+            setHeight(e.target.value);
+            setSelectedPreset(null);
+          }}
+          min={1}
+          className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
+        />
+      </div>
+    </div>
+  );
+
+  // Quick aspect ratio buttons
+  const aspectButtons = (
+    <div className="flex gap-1">
+      {ASPECT_PRESETS.map((p) => {
+        const isActive = width === String(p.w) && height === String(p.h);
+        return (
+          <button
+            key={p.label}
+            type="button"
+            onClick={() => handleAspectPreset(p)}
+            className={`flex-1 text-[11px] py-1.5 rounded ${isActive ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"}`}
+          >
+            {p.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+
+  // Quality slider (shared)
+  const qualitySlider = (
+    <div>
+      <div className="flex justify-between items-center">
+        <label htmlFor="sc-quality" className="text-xs text-muted-foreground">
+          Output Quality
+        </label>
+        <span className="text-xs text-muted-foreground tabular-nums">{quality}%</span>
+      </div>
+      <input
+        id="sc-quality"
+        type="range"
+        min={1}
+        max={100}
+        value={quality}
+        onChange={(e) => setQuality(Number(e.target.value))}
+        className="w-full mt-1"
+      />
+      <p className="text-[10px] text-muted-foreground mt-0.5">
+        For JPEG and WebP outputs. PNG is always lossless.
+      </p>
+    </div>
+  );
+
   return (
     <div className="space-y-4">
-      {/* Mode toggle */}
+      {/* Mode tabs */}
-      <div>
+      <div className="flex gap-1">
-        <label className="text-sm font-medium text-muted-foreground">Mode</label>
+        <button
-        <div className="flex gap-1 mt-1">
+          type="button"
-          <button
+          onClick={() => setMode("subject")}
-            type="button"
+          className={modeTabClass("subject")}
-            onClick={() => handleModeChange("content")}
+        >
-            className={`flex-1 py-2 text-sm rounded-lg font-medium transition-colors ${
+          Subject Focus
-              mode === "content"
+        </button>
-                ? "bg-primary text-primary-foreground"
+        <button type="button" onClick={() => setMode("face")} className={modeTabClass("face")}>
-                : "bg-muted text-muted-foreground hover:text-foreground"
+          Face Focus
-            }`}
+        </button>
-          >
+        <button type="button" onClick={() => setMode("trim")} className={modeTabClass("trim")}>
-            Crop to Content
+          Auto Trim
-          </button>
+        </button>
-          <button
-            type="button"
-            onClick={() => handleModeChange("attention")}
-            className={`flex-1 py-2 text-sm rounded-lg font-medium transition-colors ${
-              mode === "attention"
-                ? "bg-primary text-primary-foreground"
-                : "bg-muted text-muted-foreground hover:text-foreground"
-            }`}
-          >
-            Focus Crop
-          </button>
-        </div>
       </div>
 
-      {mode === "content" ? (
+      {/* ─── Subject Focus ─── */}
-        <>
+      {mode === "subject" && (
+        <div className="space-y-4">
+          {/* Sub-tabs: Presets / Custom */}
+          <div className="flex gap-1">
+            <button
+              type="button"
+              onClick={() => setSubjectTab("custom")}
+              className={subTabClass("custom")}
+            >
+              Custom Size
+            </button>
+            <button
+              type="button"
+              onClick={() => setSubjectTab("presets")}
+              className={subTabClass("presets")}
+            >
+              Social Presets
+            </button>
+          </div>
+
+          {subjectTab === "presets" ? (
+            <div className="space-y-3 max-h-[50vh] overflow-y-auto pr-1">
+              {platforms.map((platform) => (
+                <div key={platform}>
+                  <p className="text-xs font-medium text-muted-foreground mb-1.5">{platform}</p>
+                  <div className="space-y-1">
+                    {SOCIAL_MEDIA_PRESETS.filter((p) => p.platform === platform).map((preset) => {
+                      const key = `${preset.platform}-${preset.name}`;
+                      const isSelected = selectedPreset === key;
+                      return (
+                        <button
+                          key={key}
+                          type="button"
+                          onClick={() => handleSocialPreset(preset)}
+                          className={`w-full flex items-center justify-between px-2.5 py-1.5 rounded border text-sm transition-colors ${
+                            isSelected
+                              ? "border-primary bg-primary/10 text-foreground"
+                              : "border-border text-muted-foreground hover:border-primary/50 hover:text-foreground"
+                          }`}
+                        >
+                          <span>{preset.name}</span>
+                          <span className="text-xs tabular-nums">
+                            {preset.width} x {preset.height}
+                          </span>
+                        </button>
+                      );
+                    })}
+                  </div>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <>
+              {dimensionInputs}
+              {aspectButtons}
+            </>
+          )}
+
+          {/* Strategy toggle */}
+          <div>
+            <div className="flex items-center gap-1.5 mb-1">
+              <span className="text-xs text-muted-foreground">Detection Strategy</span>
+              <HintIcon text="Attention finds the most visually salient region. Entropy finds the area with most detail and information." />
+            </div>
+            <div className="flex gap-1">
+              <button
+                type="button"
+                onClick={() => setStrategy("attention")}
+                className={`flex-1 text-xs py-1.5 rounded ${strategy === "attention" ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"}`}
+              >
+                Attention
+              </button>
+              <button
+                type="button"
+                onClick={() => setStrategy("entropy")}
+                className={`flex-1 text-xs py-1.5 rounded ${strategy === "entropy" ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"}`}
+              >
+                Entropy
+              </button>
+            </div>
+          </div>
+
+          {/* Padding slider */}
+          <div>
+            <div className="flex justify-between items-center">
+              <div className="flex items-center gap-1.5">
+                <label htmlFor="sc-padding" className="text-xs text-muted-foreground">
+                  Padding
+                </label>
+                <HintIcon text="Extra breathing room around the focus area" />
+              </div>
+              <span className="text-xs text-muted-foreground tabular-nums">{padding}%</span>
+            </div>
+            <input
+              id="sc-padding"
+              type="range"
+              min={0}
+              max={30}
+              value={padding}
+              onChange={(e) => setPadding(Number(e.target.value))}
+              className="w-full mt-1"
+            />
+          </div>
+
+          {qualitySlider}
+
+          <p className="text-[10px] text-muted-foreground">
+            Detects the most interesting region using saliency analysis and crops to your target
+            size.
+          </p>
+        </div>
+      )}
+
+      {/* ─── Face Focus ─── */}
+      {mode === "face" && (
+        <div className="space-y-4">
+          {/* Face preset buttons */}
+          <div>
+            <span className="text-xs text-muted-foreground">Framing</span>
+            <div className="flex gap-1 mt-1">
+              {SMART_CROP_FACE_PRESETS.map((p) => (
+                <button
+                  key={p.id}
+                  type="button"
+                  onClick={() => setFacePreset(p.id)}
+                  className={`flex-1 text-[11px] py-1.5 rounded ${facePreset === p.id ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground"}`}
+                >
+                  {p.label}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          {/* Target size */}
+          {dimensionInputs}
+          {aspectButtons}
+
+          {/* Sensitivity slider */}
+          <div>
+            <div className="flex justify-between items-center">
+              <label htmlFor="sc-sensitivity" className="text-xs text-muted-foreground">
+                Detection Sensitivity
+              </label>
+              <span className="text-xs font-mono text-foreground">{sensitivity}%</span>
+            </div>
+            <input
+              id="sc-sensitivity"
+              type="range"
+              min={10}
+              max={90}
+              value={sensitivity}
+              onChange={(e) => setSensitivity(Number(e.target.value))}
+              className="w-full mt-1"
+            />
+            <div className="flex justify-between text-[10px] text-muted-foreground mt-0.5">
+              <span>More faces</span>
+              <span>Fewer false positives</span>
+            </div>
+          </div>
+
+          {/* Padding slider */}
+          <div>
+            <div className="flex justify-between items-center">
+              <div className="flex items-center gap-1.5">
+                <label htmlFor="sc-face-padding" className="text-xs text-muted-foreground">
+                  Face Padding
+                </label>
+                <HintIcon text="Extra space around detected faces" />
+              </div>
+              <span className="text-xs text-muted-foreground tabular-nums">{padding}%</span>
+            </div>
+            <input
+              id="sc-face-padding"
+              type="range"
+              min={0}
+              max={50}
+              value={padding}
+              onChange={(e) => setPadding(Number(e.target.value))}
+              className="w-full mt-1"
+            />
+          </div>
+
+          {qualitySlider}
+
+          <p className="text-[10px] text-muted-foreground">
+            Uses AI face detection to keep faces properly framed. Falls back to Subject Focus if no
+            faces are detected.
+          </p>
+        </div>
+      )}
+
+      {/* ─── Auto Trim ─── */}
+      {mode === "trim" && (
+        <div className="space-y-4">
           {/* Threshold */}
           <div>
             <div className="flex justify-between items-center">
-              <label htmlFor="trim-threshold" className="text-xs text-muted-foreground">
+              <label htmlFor="sc-threshold" className="text-xs text-muted-foreground">
                 Tolerance
               </label>
               <span className="text-xs text-muted-foreground tabular-nums">{threshold}</span>
             </div>
             <input
-              id="trim-threshold"
+              id="sc-threshold"
               type="range"
               min={0}
               max={128}
               value={threshold}
-              onChange={(e) => {
+              onChange={(e) => setThreshold(Number(e.target.value))}
-                const v = Number(e.target.value);
-                setThreshold(v);
-                emit({ threshold: v });
-              }}
               className="w-full mt-1"
             />
             <p className="text-[10px] text-muted-foreground mt-0.5">
@@ -137,16 +471,13 @@ export function SmartCropControls({ onChange }: SmartCropControlsProps) {
           {/* Pad to square */}
           <div className="flex items-center gap-2">
             <input
-              id="pad-square"
+              id="sc-pad-square"
               type="checkbox"
               checked={padToSquare}
-              onChange={(e) => {
+              onChange={(e) => setPadToSquare(e.target.checked)}
-                setPadToSquare(e.target.checked);
-                emit({ padToSquare: e.target.checked });
-              }}
               className="rounded border-border"
             />
-            <label htmlFor="pad-square" className="text-sm text-foreground">
+            <label htmlFor="sc-pad-square" className="text-sm text-foreground">
               Pad to square
             </label>
           </div>
@@ -154,138 +485,41 @@ export function SmartCropControls({ onChange }: SmartCropControlsProps) {
           {padToSquare && (
             <div className="flex gap-2">
               <div className="flex-1">
-                <label htmlFor="target-size" className="text-xs text-muted-foreground">
+                <label htmlFor="sc-target-size" className="text-xs text-muted-foreground">
                   Target size (px)
                 </label>
                 <input
-                  id="target-size"
+                  id="sc-target-size"
                   type="number"
                   value={targetSize}
-                  onChange={(e) => {
+                  onChange={(e) => setTargetSize(e.target.value)}
-                    setTargetSize(e.target.value);
-                    emit({ targetSize: Number(e.target.value) });
-                  }}
                   min={1}
                   className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
                 />
               </div>
               <div>
-                <label htmlFor="pad-color" className="text-xs text-muted-foreground">
+                <label htmlFor="sc-pad-color" className="text-xs text-muted-foreground">
                   Pad color
                 </label>
                 <input
-                  id="pad-color"
+                  id="sc-pad-color"
                   type="color"
                   value={padColor}
-                  onChange={(e) => {
+                  onChange={(e) => setPadColor(e.target.value)}
-                    setPadColor(e.target.value);
-                    emit({ padColor: e.target.value });
-                  }}
                   className="w-12 h-[34px] mt-0.5 rounded border border-border bg-background cursor-pointer"
                 />
               </div>
             </div>
           )}
 
-          <p className="text-[10px] text-muted-foreground">
+          {qualitySlider}
-            Trims uniform-color borders around the subject, like GIMP's "Crop to Content." Enable
-            "Pad to square" to produce e-commerce ready images.
-          </p>
-        </>
-      ) : (
-        <>
-          {/* Aspect ratio preset */}
-          <div>
-            <label
-              htmlFor="smart-crop-preset"
-              className="text-sm font-medium text-muted-foreground"
-            >
-              Target Aspect Ratio
-            </label>
-            <select
-              id="smart-crop-preset"
-              value={preset}
-              onChange={(e) => handlePreset(e.target.value)}
-              className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
-            >
-              {ASPECT_PRESETS.map((p) => (
-                <option key={p.label} value={p.label}>
-                  {p.label}
-                </option>
-              ))}
-            </select>
-          </div>
-
-          {/* Width / Height */}
-          <div className="flex gap-2">
-            <div className="flex-1">
-              <label htmlFor="smart-crop-width" className="text-xs text-muted-foreground">
-                Width (px)
-              </label>
-              <input
-                id="smart-crop-width"
-                type="number"
-                value={width}
-                onChange={(e) => {
-                  setWidth(e.target.value);
-                  setPreset("Custom");
-                  emit({ width: Number(e.target.value) });
-                }}
-                min={1}
-                className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
-              />
-            </div>
-            <div className="flex-1">
-              <label htmlFor="smart-crop-height" className="text-xs text-muted-foreground">
-                Height (px)
-              </label>
-              <input
-                id="smart-crop-height"
-                type="number"
-                value={height}
-                onChange={(e) => {
-                  setHeight(e.target.value);
-                  setPreset("Custom");
-                  emit({ height: Number(e.target.value) });
-                }}
-                min={1}
-                className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
-              />
-            </div>
-          </div>
 
           <p className="text-[10px] text-muted-foreground">
-            Uses entropy-based attention detection to find the most interesting region and crops to
+            Removes uniform-color borders around your subject. Enable "Pad to square" for e-commerce
-            it. Good for thumbnails and social media images.
+            ready images.
           </p>
-        </>
-      )}
-
-      {/* Quality slider */}
-      <div>
-        <div className="flex justify-between items-center">
-          <label htmlFor="smart-crop-quality" className="text-xs text-muted-foreground">
-            Output Quality
-          </label>
-          <span className="text-xs text-muted-foreground tabular-nums">{quality}%</span>
         </div>
-        <input
+      )}
-          id="smart-crop-quality"
-          type="range"
-          min={1}
-          max={100}
-          value={quality}
-          onChange={(e) => {
-            const v = Number(e.target.value);
-            setQuality(v);
-            emit({ quality: v });
-          }}
-          className="w-full mt-1"
-        />
-        <p className="text-[10px] text-muted-foreground mt-0.5">
-          For JPEG and WebP outputs. PNG is always lossless.
-        </p>
-      </div>
     </div>
   );
 }
@@ -296,10 +530,11 @@ export function SmartCropSettings() {
     useToolProcessor("smart-crop");
 
   const [settings, setSettings] = useState<Record<string, unknown>>({
-    mode: "content",
+    mode: "subject",
-    threshold: 30,
+    strategy: "attention",
-    padToSquare: false,
+    width: 1080,
-    padColor: "#ffffff",
+    height: 1080,
+    padding: 0,
     quality: 95,
   });
 
@@ -313,14 +548,16 @@ export function SmartCropSettings() {
 
   const hasFile = files.length > 0;
   const mode = settings.mode as string;
-  const canProcess =
+  const canProcess = mode === "trim" || (Number(settings.width) > 0 && Number(settings.height) > 0);
-    mode === "content" || (Number(settings.width) > 0 && Number(settings.height) > 0);
 
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
     if (hasFile && canProcess && !processing) handleProcess();
   };
 
+  const buttonLabel =
+    mode === "face" ? "Face Crop" : mode === "trim" ? "Trim Borders" : "Smart Crop";
+
   return (
     <form onSubmit={handleSubmit} className="space-y-4">
       <SmartCropControls onChange={setSettings} />
@@ -343,7 +580,7 @@ export function SmartCropSettings() {
           disabled={!hasFile || !canProcess || 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"
         >
-          {mode === "content" ? "Crop to Content" : "Smart Crop"}
+          {files.length > 1 ? `${buttonLabel} (${files.length} files)` : buttonLabel}
         </button>
       )}
     </form>

packages/ai/python/detect_faces.py

@@ -15,6 +15,7 @@ def main():
 
     blur_radius = settings.get("blurRadius", 30)
     sensitivity = settings.get("sensitivity", 0.5)
+    detect_only = settings.get("detectOnly", False)
 
     try:
         emit_progress(10, "Preparing")
@@ -64,26 +65,30 @@ def main():
                     w = int(bbox.width * iw)
                     h = int(bbox.height * ih)
 
-                    # Add padding around the face
+                    if not detect_only:
-                    pad = int(max(w, h) * 0.1)
+                        # Add padding around the face
-                    x1 = max(0, x - pad)
+                        pad = int(max(w, h) * 0.1)
-                    y1 = max(0, y - pad)
+                        x1 = max(0, x - pad)
-                    x2 = min(img.width, x + w + pad)
+                        y1 = max(0, y - pad)
-                    y2 = min(img.height, y + h + pad)
+                        x2 = min(img.width, x + w + pad)
+                        y2 = min(img.height, y + h + pad)
+
+                        face_region = img.crop((x1, y1, x2, y2))
+                        blurred = face_region.filter(
+                            ImageFilter.GaussianBlur(blur_radius)
+                        )
+                        img.paste(blurred, (x1, y1))
+                        emit_progress(
+                            50 + int((i + 1) / num_faces * 40),
+                            f"Blurring face {i + 1} of {num_faces}",
+                        )
 
-                    face_region = img.crop((x1, y1, x2, y2))
-                    blurred = face_region.filter(
-                        ImageFilter.GaussianBlur(blur_radius)
-                    )
-                    img.paste(blurred, (x1, y1))
                     faces.append({"x": x, "y": y, "w": w, "h": h})
-                    emit_progress(
-                        50 + int((i + 1) / num_faces * 40),
-                        f"Blurring face {i + 1} of {num_faces}",
-                    )
 
-            emit_progress(95, "Saving result")
+            if not detect_only:
-            img.save(output_path)
+                emit_progress(95, "Saving result")
+                img.save(output_path)
+
             print(
                 json.dumps(
                     {

packages/ai/src/face-detection.ts

@@ -1,4 +1,5 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type ProgressCallback, runPythonWithProgress } from "./bridge.js";
 
@@ -7,6 +8,10 @@ export interface BlurFacesOptions {
   sensitivity?: number;
 }
 
+export interface DetectFacesOptions {
+  sensitivity?: number;
+}
+
 export interface FaceRegion {
   x: number;
   y: number;
@@ -20,6 +25,11 @@ export interface BlurFacesResult {
   faces: FaceRegion[];
 }
 
+export interface DetectFacesResult {
+  facesDetected: number;
+  faces: FaceRegion[];
+}
+
 export async function blurFaces(
   inputBuffer: Buffer,
   outputDir: string,
@@ -48,3 +58,32 @@ export async function blurFaces(
     faces: result.faces ?? [],
   };
 }
+
+export async function detectFaces(
+  inputBuffer: Buffer,
+  options: DetectFacesOptions = {},
+  onProgress?: ProgressCallback,
+): Promise<DetectFacesResult> {
+  const inputPath = join(tmpdir(), `detect_faces_${Date.now()}.png`);
+
+  try {
+    await writeFile(inputPath, inputBuffer);
+    const { stdout } = await runPythonWithProgress(
+      "detect_faces.py",
+      [inputPath, "unused", JSON.stringify({ ...options, detectOnly: true })],
+      { onProgress },
+    );
+
+    const result = JSON.parse(stdout);
+    if (!result.success) {
+      throw new Error(result.error || "Face detection failed");
+    }
+
+    return {
+      facesDetected: result.facesDetected,
+      faces: result.faces ?? [],
+    };
+  } finally {
+    await unlink(inputPath).catch(() => {});
+  }
+}

packages/ai/src/index.ts

@@ -1,6 +1,7 @@
 export { removeBackground } from "./background-removal.js";
 export { isGpuAvailable, shutdownDispatcher } from "./bridge.js";
-export { blurFaces } from "./face-detection.js";
+export type { DetectFacesResult, FaceRegion } from "./face-detection.js";
+export { blurFaces, detectFaces } from "./face-detection.js";
 export { inpaint } from "./inpainting.js";
 export { extractText } from "./ocr.js";
 export { seamCarve } from "./seam-carving.js";

packages/shared/src/constants.ts

@@ -132,7 +132,7 @@ export const TOOLS: Tool[] = [
   {
     id: "erase-object",
     name: "Object Eraser",
-    description: "Paint over unwanted elements",
+    description: "Remove unwanted objects with AI",
     category: "ai",
     icon: "Wand2",
     route: "/erase-object",
@@ -156,7 +156,7 @@ export const TOOLS: Tool[] = [
   {
     id: "smart-crop",
     name: "Smart Crop",
-    description: "AI detects subject and crops optimally",
+    description: "Smart subject, face, or trim-based cropping",
     category: "ai",
     icon: "Focus",
     route: "/smart-crop",
@@ -354,6 +354,19 @@ export const SOCIAL_MEDIA_PRESETS: SocialMediaPreset[] = [
   { platform: "Threads", name: "Post Image", width: 1080, height: 1080 },
 ];
 
+export interface SmartCropFacePreset {
+  id: string;
+  label: string;
+  multiplier: number;
+}
+
+export const SMART_CROP_FACE_PRESETS: SmartCropFacePreset[] = [
+  { id: "closeup", label: "Close-up", multiplier: 1.8 },
+  { id: "head-shoulders", label: "Head & Shoulders", multiplier: 2.8 },
+  { id: "upper-body", label: "Upper Body", multiplier: 4.5 },
+  { id: "half-body", label: "Half Body", multiplier: 7.0 },
+];
+
 export const APP_VERSION = "1.14.0";
 
 /**

packages/shared/src/i18n/en.ts

@@ -58,7 +58,7 @@ export const en = {
       description: "AI-powered background removal",
     },
     upscale: { name: "Image Upscaling", description: "AI super-resolution enhancement" },
-    "erase-object": { name: "Object Eraser", description: "Paint over unwanted elements" },
+    "erase-object": { name: "Object Eraser", description: "Remove unwanted objects with AI" },
     ocr: {
       name: "OCR / Text Extraction",
       description: "Extract text from images with AI-powered accuracy",
@@ -67,7 +67,10 @@ export const en = {
       name: "Face / PII Blur",
       description: "Auto-detect and blur faces and sensitive info",
     },
-    "smart-crop": { name: "Smart Crop", description: "AI detects subject and crops optimally" },
+    "smart-crop": {
+      name: "Smart Crop",
+      description: "Smart subject, face, or trim-based cropping",
+    },
     "content-aware-resize": {
       name: "Content-Aware Resize",
       description: "Intelligently resize images while preserving important content",

tests/integration/api.test.ts

@@ -3228,6 +3228,98 @@ describe("Smart crop format preservation", () => {
     });
     expect(res.statusCode).toBe(200);
   });
+
+  it("subject mode with entropy strategy", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "photo.jpg", contentType: "image/jpeg", content: JPG_100x100 },
+      {
+        name: "settings",
+        content: JSON.stringify({ mode: "subject", strategy: "entropy", width: 50, height: 50 }),
+      },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/smart-crop",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.downloadUrl).toMatch(/_smartcrop\.jpg/);
+  });
+
+  it("subject mode with padding", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "photo.jpg", contentType: "image/jpeg", content: JPG_100x100 },
+      {
+        name: "settings",
+        content: JSON.stringify({ mode: "subject", width: 50, height: 50, padding: 10 }),
+      },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/smart-crop",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.downloadUrl).toMatch(/_smartcrop\.jpg/);
+  });
+
+  it("trim mode with new mode name", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "photo.png", contentType: "image/png", content: PNG_200x150 },
+      {
+        name: "settings",
+        content: JSON.stringify({ mode: "trim", threshold: 30 }),
+      },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/smart-crop",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.downloadUrl).toMatch(/_smartcrop\.png/);
+  });
+
+  it("defaults to subject mode when no mode specified", async () => {
+    const { body: payload, contentType } = createMultipartPayload([
+      { name: "file", filename: "photo.jpg", contentType: "image/jpeg", content: JPG_100x100 },
+      {
+        name: "settings",
+        content: JSON.stringify({ width: 50, height: 50 }),
+      },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/smart-crop",
+      headers: {
+        authorization: `Bearer ${adminToken}`,
+        "content-type": contentType,
+      },
+      payload,
+    });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.downloadUrl).toMatch(/_smartcrop\.jpg/);
+  });
 });
 
 // ═══════════════════════════════════════════════════════════════════════════