feat: improve remove background with edge smoothing, color decontamination, output formats

- Expose birefnet-hr-matting in UI (People/Ultra) and fix model defaults
  (People/Max now uses birefnet-matting for true alpha matting)
- Add output format selector (PNG/WebP/AVIF) with lossless alpha support
- Add edge smoothing post-processing (Off/Light/Medium/Strong) via
  morphological mask refinement to reduce gray halo artifacts
- Add color decontamination to remove background color spill from
  semi-transparent edge pixels
- Thread new settings through full stack: frontend -> API schema ->
  Python sidecar -> Sharp effects pipeline
- Add i18n keys for all 21 locales
- Add unit tests for new option serialization (3 tests)
- Add integration tests for new settings validation (4 tests)

apps/api/src/lib/bg-effects.ts

@@ -1,5 +1,26 @@
 import sharp from "sharp";
 
+export type BgOutputFormat = "png" | "webp" | "avif";
+
+export const BG_OUTPUT_FORMATS: BgOutputFormat[] = ["png", "webp", "avif"];
+
+export const BG_FORMAT_CONTENT_TYPES: Record<BgOutputFormat, string> = {
+  png: "image/png",
+  webp: "image/webp",
+  avif: "image/avif",
+};
+
+function toOutputFormat(pipeline: sharp.Sharp, format: BgOutputFormat): Promise<Buffer> {
+  switch (format) {
+    case "webp":
+      return pipeline.webp({ lossless: true }).toBuffer();
+    case "avif":
+      return pipeline.avif({ lossless: true }).toBuffer();
+    default:
+      return pipeline.png().toBuffer();
+  }
+}
+
 /**
  * Background removal post-processing effects.
  * All effects use Sharp (libvips) for fast server-side image manipulation.
@@ -182,6 +203,7 @@ export async function applyEffects(
     blurIntensity?: number;
     shadowEnabled?: boolean;
     shadowOpacity?: number;
+    outputFormat?: BgOutputFormat;
   },
 ): Promise<Buffer> {
   const meta = await sharp(subjectBuffer).metadata();
@@ -238,13 +260,12 @@ export async function applyEffects(
   }
   // else: transparent - no background layer
 
+  const fmt = settings.outputFormat ?? "png";
+
   // Step 3: Composite subject onto background
   if (background) {
-    return sharp(background)
-      .composite([{ input: subject, blend: "over" }])
-      .png()
-      .toBuffer();
+    return toOutputFormat(sharp(background).composite([{ input: subject, blend: "over" }]), fmt);
   }
 
-  return subject;
+  return toOutputFormat(sharp(subject), fmt);
 }

apps/api/src/routes/tools/remove-background.ts

@@ -6,7 +6,11 @@ import { getBundleForTool, TOOL_BUNDLE_MAP } from "@snapotter/shared";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { autoOrient } from "../../lib/auto-orient.js";
-import { applyEffects } from "../../lib/bg-effects.js";
+import {
+  applyEffects,
+  BG_FORMAT_CONTENT_TYPES,
+  type BgOutputFormat,
+} from "../../lib/bg-effects.js";
 import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
@@ -28,6 +32,9 @@ const settingsSchema = z.object({
   blurIntensity: z.number().min(0).max(100).optional(),
   shadowEnabled: z.boolean().optional(),
   shadowOpacity: z.number().min(0).max(100).optional(),
+  outputFormat: z.enum(["png", "webp", "avif"]).optional(),
+  edgeRefine: z.number().int().min(0).max(3).optional(),
+  decontaminate: z.boolean().optional(),
 });
 
 /**
@@ -176,7 +183,11 @@ export function registerRemoveBackground(app: FastifyInstance) {
         const transparentResult = await removeBackground(
           fileBuffer,
           join(workspacePath, "output"),
-          { model: settings.model },
+          {
+            model: settings.model,
+            edgeRefine: settings.edgeRefine,
+            decontaminate: settings.decontaminate,
+          },
           onProgress,
         );
 
@@ -265,6 +276,7 @@ export function registerRemoveBackground(app: FastifyInstance) {
         blurIntensity: z.number().min(0).max(100).optional(),
         shadowEnabled: z.boolean().optional(),
         shadowOpacity: z.number().min(0).max(100).optional(),
+        outputFormat: z.enum(["png", "webp", "avif"]).optional(),
       });
 
       try {
@@ -308,6 +320,7 @@ export function registerRemoveBackground(app: FastifyInstance) {
         }
 
         // Apply effects using cached mask + original
+        const fmt = (settings.outputFormat ?? "png") as BgOutputFormat;
         const resultBuffer = await applyEffects(maskBuffer, originalBuffer, {
           backgroundType: settings.backgroundType,
           backgroundColor: settings.backgroundColor,
@@ -319,10 +332,11 @@ export function registerRemoveBackground(app: FastifyInstance) {
           blurIntensity: settings.blurIntensity,
           shadowEnabled: settings.shadowEnabled,
           shadowOpacity: settings.shadowOpacity,
+          outputFormat: fmt,
         });
 
         // Save the final output
-        const outputFilename = `${baseName}_nobg.png`;
+        const outputFilename = `${baseName}_nobg.${fmt}`;
         const outputPath = join(workspacePath, "output", outputFilename);
         await writeFile(outputPath, resultBuffer);
 
@@ -354,9 +368,10 @@ export function registerRemoveBackground(app: FastifyInstance) {
       const transparentResult = await removeBackground(
         orientedBuffer,
         join(workspacePath, "output"),
-        { model: s.model },
+        { model: s.model, edgeRefine: s.edgeRefine, decontaminate: s.decontaminate },
       );
 
+      const fmt = (s.outputFormat ?? "png") as BgOutputFormat;
       const resultBuffer = await applyEffects(transparentResult, orientedBuffer, {
         backgroundType: s.backgroundType,
         backgroundColor: s.backgroundColor,
@@ -367,10 +382,15 @@ export function registerRemoveBackground(app: FastifyInstance) {
         blurIntensity: s.blurIntensity,
         shadowEnabled: s.shadowEnabled,
         shadowOpacity: s.shadowOpacity,
+        outputFormat: fmt,
       });
 
-      const outputFilename = `${filename.replace(/\.[^.]+$/, "")}_nobg.png`;
-      return { buffer: resultBuffer, filename: outputFilename, contentType: "image/png" };
+      const outputFilename = `${filename.replace(/\.[^.]+$/, "")}_nobg.${fmt}`;
+      return {
+        buffer: resultBuffer,
+        filename: outputFilename,
+        contentType: BG_FORMAT_CONTENT_TYPES[fmt],
+      };
     },
   });
 }