agents-inc/web-files-image-handling

Image Handling Patterns

Quick Guide: Use URL.createObjectURL() for image previews (most efficient). Resize/compress with Canvas API before upload. Always cleanup object URLs with URL.revokeObjectURL() to prevent memory leaks. Handle EXIF orientation for mobile photos only when processing for upload (modern browsers auto-rotate for display). Use step-down scaling for quality preservation on large reductions.

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST cleanup object URLs with URL.revokeObjectURL() in useEffect cleanup or when replacing URLs)

(You MUST check browser context before applying EXIF orientation - modern browsers auto-rotate, manual handling causes double rotation)

(You MUST use step-down scaling when reducing images by more than 50% - single-pass resize loses quality)

(You MUST limit canvas dimensions to browser maximums (typically 4096px) - larger canvases crash browsers)

</critical_requirements>

---

Auto-detection: image preview, URL.createObjectURL, revokeObjectURL, canvas resize, image compression, EXIF orientation, toBlob, toDataURL, FileReader image, image thumbnail, client-side resize, image crop, canvas drawImage, createImageBitmap, image quality

When to use:

• Creating image previews before upload
• Resizing or compressing images client-side
• Handling EXIF orientation from mobile photos
• Converting between image formats (JPEG/PNG/WebP)
• Generating thumbnails from user-selected images
• Implementing image cropping interfaces

When NOT to use:

• Server-side image processing (not client-side scope)
• Image CDN/optimization services (infrastructure concern)
• Complex image editing (consider dedicated libraries like Fabric.js or Konva)

---

<philosophy>

Philosophy

Client-side image handling improves UX by providing instant previews and reducing upload sizes before they hit your server. The key insight is that preview and processing have different optimal approaches - URL.createObjectURL() for previews (fast, memory-efficient), Canvas API for processing (resize, compress, convert).

Core Principles:

1. Object URLs for preview - No file reading, instant display, must cleanup
2. Canvas for processing - Resize, compress, convert formats
3. Memory management is critical - Leaked object URLs accumulate indefinitely
4. EXIF awareness - Modern browsers auto-rotate for display; manual handling only for upload processing
5. Progressive quality - Step-down scaling preserves sharpness on large reductions

Preview Method Comparison:

| Method | Speed | Memory | Use Case | | ---------------------------- | ------- | ------------------ | -------------------- | | URL.createObjectURL() | Instant | Low (reference) | Display previews | | FileReader.readAsDataURL() | Slow | High (full Base64) | Need data URL string | | Canvas toDataURL() | Medium | Medium | After processing |

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Object URL Preview with Cleanup

Use URL.createObjectURL() for instant image previews. Always cleanup to prevent memory leaks. The critical pattern is revoking the previous URL before creating a new one, and revoking in the useEffect cleanup.

// The essential cleanup pattern
useEffect(() => {
  const url = URL.createObjectURL(file);
  setPreviewUrl(url);
  return () => URL.revokeObjectURL(url); // MUST cleanup
}, [file]);

Why good: Instant preview without reading file into memory, cleanup prevents memory leaks

// BAD: No cleanup - memory leak
const [preview] = useState(() => URL.createObjectURL(file));
// URL never revoked - memory accumulates indefinitely!

Why bad: Object URL never revoked, browser holds blob reference indefinitely, compounds with each file selection

See examples/core.md Pattern 1-2 for complete hook and component implementations.

---

Pattern 2: Canvas Resize with Quality Preservation

Resize images using Canvas API. Key concerns: clamp dimensions to browser limits (4096px safe max), enable imageSmoothingQuality: "high", fill white background for JPEG (transparency becomes black otherwise).

const MAX_CANVAS_DIMENSION = 4096;

// Clamp to browser limits, maintain aspect ratio
const ratio = Math.min(maxWidth / img.width, maxHeight / img.height);
const width = Math.round(img.width * Math.min(ratio, 1));
const height = Math.round(img.height * Math.min(ratio, 1));

ctx.imageSmoothingEnabled = true;
ctx.imageSmoothingQuality = "high";
if (mimeType === "image/jpeg") {
  ctx.fillStyle = "#ffffff";
  ctx.fillRect(0, 0, width, height); // White bg for JPEG
}
ctx.drawImage(img, 0, 0, width, height);

See examples/core.md Pattern 3 for dimension validation, examples/canvas.md for complete resize pipeline.

---

Pattern 3: Step-Down Scaling

For reductions >50%, scale in multiple passes to preserve sharpness. A 4000px to 100px single-pass resize produces blurry results; two intermediate steps maintain quality.

const STEP_DOWN_THRESHOLD = 0.5;
const reductionRatio = targetWidth / img.width;

if (reductionRatio < STEP_DOWN_THRESHOLD) {
  // Multi-pass: 4000 -> 400 -> 100 (two steps)
  const factor = Math.pow(targetWidth / img.width, 1 / steps);
  for (let i = 0; i < steps; i++) {
    /* scale by factor each step */
  }
} else {
  // Single-pass is fine for small reductions
}

See examples/canvas.md Pattern 1 for complete step-down implementation with automatic strategy selection.

---

Pattern 4: EXIF Orientation

Modern browsers (2020+) auto-rotate images for display via CSS image-orientation: from-image (default). Manual EXIF handling is only needed when:

• Processing images for upload (server may strip EXIF and not rotate)
• Using Node.js canvas (no auto-rotation)
• Needing to detect orientation programmatically

// For DISPLAY: modern browsers handle it - do nothing
<img src={URL.createObjectURL(file)} /> // Auto-rotated

// For UPLOAD PROCESSING: normalize before sending to server
const orientation = await getExifOrientation(file); // Read from JPEG header
if (orientation !== 1) {
  const normalized = await normalizeOrientation(file);
  await uploadToServer(normalized);
}

// To BYPASS auto-rotation (show raw orientation)
<img src={url} style={{ imageOrientation: 'none' }} />

Gotcha: Applying normalizeOrientation() then displaying via <img> causes double-rotation in modern browsers.

See examples/core.md Pattern 4 for EXIF parsing implementation.

---

Pattern 5: Format Conversion

Convert between JPEG/PNG/WebP with format-appropriate quality defaults. Key detail: JPEG cannot represent transparency, so fill white background before conversion.

const FORMAT_QUALITY_DEFAULTS: Record<string, number> = {
  "image/jpeg": 0.85,
  "image/webp": 0.82,
  "image/png": 1, // Lossless - quality param ignored
};

WebP is supported in all modern browsers (including Safari 14+). For target file size, use binary search over quality parameter.

See examples/canvas.md Pattern 2 for binary search quality targeting.

---

Pattern 6: Cropping

Canvas-based cropping using drawImage() with source rectangle parameters. Validate crop region is within image bounds, support resize-during-crop for generating specific output dimensions.

// drawImage(source, sx, sy, sw, sh, dx, dy, dw, dh)
ctx.drawImage(
  img,
  cropX,
  cropY,
  cropWidth,
  cropHeight,
  0,
  0,
  outputWidth,
  outputHeight,
);

See examples/canvas.md Pattern 3 for complete crop implementation with aspect ratio helper.

</patterns>

---

Detailed Resources:

• examples/core.md - Preview hooks, components, dimension validation, EXIF parsing
• examples/preview.md - Drag-and-drop, thumbnails, gallery grid
• examples/canvas.md - Resize pipeline, target-size compression, cropping, watermarks, filters
• reference.md - Decision frameworks, constants reference, browser compatibility, anti-patterns

---

<red_flags>

RED FLAGS

High Priority Issues:

• Not calling URL.revokeObjectURL() - causes memory leaks that accumulate indefinitely
• Canvas dimensions exceeding 4096px - crashes browser tab or silently fails
• Double EXIF rotation - applying manual rotation in browsers that auto-rotate (all modern browsers since 2020)

Medium Priority Issues:

• Using FileReader.readAsDataURL() for preview - slow and memory-intensive vs object URLs
• Single-pass resize for large reductions (>50%) - results in blurry/aliased images
• Creating object URLs inside render functions - creates new URL every render cycle

Gotchas & Edge Cases:

• Object URLs persist until page unload even without cleanup (but waste memory)
• Canvas toBlob() is async, toDataURL() is sync - prefer toBlob for performance
• PNG with transparency converted to JPEG needs white background fill (otherwise black)
• Very large images may exceed WebGL limits even within canvas dimension limits
• Node.js canvas does NOT auto-rotate EXIF - still needs manual handling server-side
• Use image-orientation: none CSS to bypass browser auto-rotation when needed

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST cleanup object URLs with URL.revokeObjectURL() in useEffect cleanup or when replacing URLs)

(You MUST check browser context before applying EXIF orientation - modern browsers auto-rotate, manual handling causes double rotation)

(You MUST use step-down scaling when reducing images by more than 50% - single-pass resize loses quality)

(You MUST limit canvas dimensions to browser maximums (typically 4096px) - larger canvases crash browsers)

Failure to follow these rules will cause memory leaks, browser crashes, and poor image quality.

</critical_reminders>