Image Editing & Processing Pipeline — Developer Guide

Overview

The Image Editing & Processing Pipeline provides two complementary capabilities:

1. Processing Pipeline Visualization — Granular stage indicators during image uploads (Uploading → Optimizing → Thumbnails → LQIP → Background Removal → Complete)
2. Post-Upload Image Editing — Client-side crop, rotate, flip, and resize tools via a modal editor that re-uploads through the existing presigned URL flow

All image transformations happen client-side using the Canvas API. The server's sharp pipeline handles final optimization (WebP conversion, thumbnail generation, LQIP) on re-upload via confirmUpload.

Architecture

graph LR
    A["User clicks Edit"] --> B["ImageEditorModal opens"]
    B --> C["Canvas API loads image"]
    C --> D{Tool Selection}
    D -->|Crop| E["CropOverlay.svelte"]
    D -->|Rotate| F["rotateCanvas() / flipCanvas()"]
    D -->|Resize| G["resizeCanvas()"]
    E --> H["canvasToFile() → JPEG"]
    F --> H
    G --> H
    H --> I["uploadFile() with stages"]
    I --> J["requestUploadUrl"]
    J --> K["PUT to S3"]
    K --> L["confirmUpload"]
    L --> M["Server: sharp pipeline"]
    M --> N["WebP + Thumbnails + LQIP"]
    N --> O["Updated image in gallery"]

    style B fill:#667eea,color:#fff
    style M fill:#22c55e,color:#fff

Processing Pipeline Stages

The upload flow emits stage transitions for UI feedback. The backend processes these atomically during confirmUpload, but the frontend simulates transitions for a polished user experience.

Usage in MediaUploader

The pipeline indicator renders as a horizontal dot array inside the upload progress card:

• Green dot = completed stage
• Pulsing accent dot = active stage
• Gray dot = pending stage

Component Reference

ImageEditorModal

Full-featured modal image editor opened from the MediaUploader's edit button.

Props

Tools

CropOverlay

SVG-based interactive crop selection rendered over the image preview.

Props

Features

• 8 drag handles (corners + edges)
• Rule-of-thirds grid overlay
• Dark mask outside selection
• Dimension badge in natural pixels
• Touch support for mobile
• Constrained to canvas bounds

MediaUploader Enhancements

The existing MediaUploader component now includes:

Utility Functions

`imageProcessingUtils.ts`

Constants

File Reference

Integration Examples

Opening the Editor from Custom Code

<script lang="ts">
  import ImageEditorModal from '$lib/components/manage/ImageEditorModal.svelte';

  let showEditor = $state(false);

  function handleSave(newImage: { id?: string; url: string; blurDataUrl?: string }) {
    console.log('Edited image:', newImage.url);
    showEditor = false;
  }
</script>

{#if showEditor}
  <ImageEditorModal
    src="https://cdn.example.com/image.jpg"
    filename="product-hero"
    maletId="malet-123"
    onSave={handleSave}
    onClose={() => { showEditor = false; }}
  />
{/if}

Listening for Pipeline Stage Changes

import { uploadFile } from '$lib/media';

const result = await uploadFile(file, {
  maletId: 'malet-123',
  removeBackground: true,
  onProgress: (percent) => console.log(`Upload: ${percent}%`),
  onStageChange: (stage) => console.log(`Stage: ${stage}`)
});

Related

• Media Infrastructure — Upload pipeline architecture, S3 flow, CDN rewriting
• Media Intelligence — EXIF extraction, SHA-256 deduplication
• Imaging Subgraph — AI background removal, shadow generation