feat: image optimization — client-side resize + server-side thumbnails

Avatars/banners now resize to max 512px/1920px and convert to WebP before
upload (zero server cost). Chat image uploads generate an 800px-wide WebP
thumbnail via Sharp; the feed shows the thumbnail, click opens the full-res
original. Adds lazy loading to avatars. Federation-compatible: remote
instances without this feature fall back gracefully.

packages/server/package.json

@@ -23,7 +23,8 @@
     "drizzle-orm": "^0.33.0",
     "fastify": "^4.28.1",
     "jsonwebtoken": "^9.0.2",
-    "livekit-server-sdk": "^2.6.1"
+    "livekit-server-sdk": "^2.6.1",
+    "sharp": "^0.33.0"
   },
   "devDependencies": {
     "@types/bcryptjs": "^2.4.6",

packages/server/src/db/migrate.ts

@@ -44,6 +44,12 @@ export function runMigrations(db: Database.Database): void {
         { name: 'closed', type: 'INTEGER DEFAULT 0' }
       ]
     },
+    {
+      name: 'attachments',
+      columns: [
+        { name: 'thumbnail_filename', type: 'TEXT' }
+      ]
+    },
     {
       name: 'dm_channels',
       columns: [

packages/server/src/db/schema.ts

@@ -85,6 +85,7 @@ export const attachments = sqliteTable('attachments', {
   originalName: text('original_name').notNull(),
   mimetype: text('mimetype').notNull(),
   size: integer('size').notNull(),
+  thumbnailFilename: text('thumbnail_filename'),
   createdAt: integer('created_at').notNull(),
 });
 

packages/server/src/routes/dm.ts

@@ -83,6 +83,7 @@ export function buildDmMessageWithUser(
       originalName: a.originalName,
       mimetype: a.mimetype,
       size: a.size,
+      thumbnailFilename: a.thumbnailFilename ?? null,
       createdAt: a.createdAt,
     })),
     reactions,

packages/server/src/routes/messages.ts

@@ -143,6 +143,7 @@ export function buildMessageWithUser(
       originalName: a.originalName,
       mimetype: a.mimetype,
       size: a.size,
+      thumbnailFilename: a.thumbnailFilename ?? null,
       createdAt: a.createdAt,
     })),
     reactions,

packages/server/src/routes/uploads.ts

@@ -8,6 +8,7 @@ import fs from 'fs';
 import path from 'path';
 import { pipeline } from 'stream/promises';
 import type { Attachment } from '@backspace/shared';
+import { generateThumbnail, isResizableImage } from '../utils/thumbnail.js';
 
 export async function uploadRoutes(app: FastifyInstance): Promise<void> {
   // Ensure upload directory exists
@@ -57,6 +58,12 @@ export async function uploadRoutes(app: FastifyInstance): Promise<void> {
     const now = Date.now();
     const db = getDb();
 
+    // Generate thumbnail for resizable images (non-blocking — upload succeeds regardless)
+    let thumbnailFilename: string | null = null;
+    if (isResizableImage(mimetype)) {
+      thumbnailFilename = await generateThumbnail(filepath, mimetype, config.uploadDir);
+    }
+
     // Save attachment record
     db.insert(schema.attachments).values({
       id,
@@ -64,6 +71,7 @@ export async function uploadRoutes(app: FastifyInstance): Promise<void> {
       originalName,
       mimetype,
       size,
+      thumbnailFilename,
       createdAt: now,
     }).run();
 
@@ -74,6 +82,7 @@ export async function uploadRoutes(app: FastifyInstance): Promise<void> {
       originalName,
       mimetype,
       size,
+      thumbnailFilename: thumbnailFilename ?? undefined,
       createdAt: now,
     };
 

packages/server/src/utils/fileCleanup.ts

@@ -1,11 +1,13 @@
 import fs from 'fs';
 import path from 'path';
 import { config } from '../config.js';
+import { thumbFilename } from './thumbnail.js';
 
 /**
  * Delete a single uploaded file by its stored filename.
  * Uses path.basename() to prevent directory traversal attacks.
  * Tolerates ENOENT (file already gone) but logs other errors.
+ * Also attempts to delete the corresponding thumbnail if one exists.
  */
 export function deleteUploadFile(filename: string): void {
   const safeName = path.basename(filename);
@@ -17,6 +19,15 @@ export function deleteUploadFile(filename: string): void {
       console.error(`Failed to delete upload file ${safeName}:`, err.message);
     }
   }
+
+  // Also attempt to delete the thumbnail variant
+  const thumbName = thumbFilename(safeName);
+  const thumbPath = path.join(config.uploadDir, thumbName);
+  try {
+    fs.unlinkSync(thumbPath);
+  } catch {
+    // Thumbnail may not exist — that's fine
+  }
 }
 
 /**

packages/server/src/utils/thumbnail.ts

@@ -0,0 +1,66 @@
+import path from 'path';
+import sharp from 'sharp';
+
+const RESIZABLE_MIMETYPES = new Set([
+  'image/jpeg',
+  'image/png',
+  'image/webp',
+  'image/gif',
+  'image/avif',
+  'image/tiff',
+]);
+
+const THUMBNAIL_MAX_WIDTH = 800;
+const THUMBNAIL_QUALITY = 80;
+
+/**
+ * Derive a deterministic thumbnail filename from the original.
+ * e.g. "123456789.png" → "123456789_thumb.webp"
+ */
+export function thumbFilename(original: string): string {
+  const parsed = path.parse(original);
+  return `${parsed.name}_thumb.webp`;
+}
+
+/** Check if the given mimetype is a resizable image format. */
+export function isResizableImage(mimetype: string): boolean {
+  return RESIZABLE_MIMETYPES.has(mimetype);
+}
+
+/**
+ * Generate a WebP thumbnail for the given image file.
+ * Returns the thumbnail filename on success, or null if:
+ * - The image is already ≤ THUMBNAIL_MAX_WIDTH px wide
+ * - An error occurs (upload still succeeds without thumbnail)
+ */
+export async function generateThumbnail(
+  originalPath: string,
+  mimetype: string,
+  uploadDir: string,
+): Promise<string | null> {
+  if (!isResizableImage(mimetype)) return null;
+
+  try {
+    const image = sharp(originalPath);
+    const metadata = await image.metadata();
+
+    // Skip if the original is already small enough
+    if (!metadata.width || metadata.width <= THUMBNAIL_MAX_WIDTH) {
+      return null;
+    }
+
+    const originalFilename = path.basename(originalPath);
+    const thumbName = thumbFilename(originalFilename);
+    const thumbPath = path.join(uploadDir, thumbName);
+
+    await sharp(originalPath)
+      .resize({ width: THUMBNAIL_MAX_WIDTH, withoutEnlargement: true })
+      .webp({ quality: THUMBNAIL_QUALITY })
+      .toFile(thumbPath);
+
+    return thumbName;
+  } catch (err) {
+    console.error('Thumbnail generation failed (non-fatal):', err);
+    return null;
+  }
+}

packages/server/src/ws/events.ts

@@ -58,6 +58,7 @@ function getMessageWithUser(messageId: string): MessageWithUser | null {
     originalName: a.originalName,
     mimetype: a.mimetype,
     size: a.size,
+    thumbnailFilename: a.thumbnailFilename ?? null,
     createdAt: a.createdAt,
   }));
 

packages/shared/src/types.ts

@@ -209,6 +209,7 @@ export interface Attachment {
   originalName: string;
   mimetype: string;
   size: number;
+  thumbnailFilename?: string | null;
   createdAt: number;
 }
 

packages/web/src/components/chat/Message.tsx

@@ -263,11 +263,14 @@ export function Message({ message, isCompact, isFirstInGroup }: MessageProps) {
                 {message.attachments.map((att) => {
                   const isImage = att.mimetype.startsWith('image/');
                   const attUrl = att.filename.startsWith('http') ? att.filename : `/api/uploads/${att.filename}`;
+                  const thumbUrl = att.thumbnailFilename
+                    ? (att.thumbnailFilename.startsWith('http') ? att.thumbnailFilename : `/api/uploads/${att.thumbnailFilename}`)
+                    : null;
                   if (isImage) {
                     return (
                       <div key={att.id} className="max-w-fit mt-1 rounded-lg overflow-hidden border border-white/[0.06]">
                         <img
-                          src={attUrl}
+                          src={thumbUrl ?? attUrl}
                           alt={att.originalName}
                           className="max-w-full max-h-[350px] object-contain cursor-pointer hover:brightness-95 transition-all"
                           onClick={() => openImagePreview(attUrl)}

packages/web/src/components/modals/settingsPanels/AccountPanel.tsx

@@ -139,7 +139,7 @@ export function AccountPanel() {
     const previewUrl = URL.createObjectURL(blob);
     setAvatarPreview(previewUrl);
     setAvatarCropSrc(null);
-    const file = new File([blob], 'avatar.png', { type: 'image/png' });
+    const file = new File([blob], 'avatar.webp', { type: blob.type || 'image/webp' });
     setUploadingAvatar(true);
     try {
       const attachment = await api.uploads.upload(file);
@@ -158,7 +158,7 @@ export function AccountPanel() {
     const previewUrl = URL.createObjectURL(blob);
     setBannerPreview(previewUrl);
     setBannerCropSrc(null);
-    const file = new File([blob], 'banner.png', { type: 'image/png' });
+    const file = new File([blob], 'banner.webp', { type: blob.type || 'image/webp' });
     setUploadingBanner(true);
     try {
       const attachment = await api.uploads.upload(file);
@@ -737,6 +737,7 @@ export function AccountPanel() {
         title="Crop Avatar"
         cropShape="round"
         aspectRatio={1}
+        maxOutputDimension={512}
       />
       <ImageCropModal
         isOpen={bannerCropSrc !== null}
@@ -746,6 +747,7 @@ export function AccountPanel() {
         title="Crop Banner"
         cropShape="rect"
         aspectRatio={3}
+        maxOutputDimension={1920}
       />
 
       <DeleteAccountModal

packages/web/src/components/modals/spaceSettingsPanels/OverviewPanel.tsx

@@ -110,7 +110,7 @@ export function OverviewPanel({ spaceId }: OverviewPanelProps) {
     setIconPreview(previewUrl);
     setCropSrc(null);
 
-    const file = new File([blob], 'icon.png', { type: 'image/png' });
+    const file = new File([blob], 'icon.webp', { type: blob.type || 'image/webp' });
     setUploadingIcon(true);
     try {
       const spaceApi = getApiForOrigin(space._instanceOrigin);
@@ -148,7 +148,7 @@ export function OverviewPanel({ spaceId }: OverviewPanelProps) {
     setBannerPreview(previewUrl);
     setBannerCropSrc(null);
 
-    const file = new File([blob], 'banner.png', { type: 'image/png' });
+    const file = new File([blob], 'banner.webp', { type: blob.type || 'image/webp' });
     setUploadingBanner(true);
     try {
       const spaceApi = getApiForOrigin(space._instanceOrigin);
@@ -601,6 +601,7 @@ export function OverviewPanel({ spaceId }: OverviewPanelProps) {
         title="Crop Space Icon"
         cropShape="round"
         aspectRatio={1}
+        maxOutputDimension={512}
       />
 
       <ImageCropModal
@@ -611,6 +612,7 @@ export function OverviewPanel({ spaceId }: OverviewPanelProps) {
         title="Crop Space Banner"
         cropShape="rect"
         aspectRatio={16 / 9}
+        maxOutputDimension={1920}
       />
     </>
   );

packages/web/src/components/ui/Avatar.tsx

@@ -105,6 +105,7 @@ export function Avatar({ src, name, size = 40, status, className = '', onClick,
             src={(src.startsWith('http') || src.startsWith('blob:') || src.startsWith('data:'))
               ? src : `/api/uploads/${src}`}
             alt={name}
+            loading="lazy"
             className="w-full h-full rounded-full object-cover"
             onError={(e) => {
               (e.target as HTMLImageElement).style.display = 'none';

packages/web/src/components/ui/ImageCropModal.tsx

@@ -11,6 +11,8 @@ interface ImageCropModalProps {
   title?: string;
   aspectRatio?: number;
   cropShape?: 'round' | 'rect';
+  maxOutputDimension?: number;
+  outputType?: string;
 }
 
 export function ImageCropModal({
@@ -21,6 +23,8 @@ export function ImageCropModal({
   title = 'Crop Image',
   aspectRatio = 1,
   cropShape = 'round',
+  maxOutputDimension,
+  outputType,
 }: ImageCropModalProps) {
   const [crop, setCrop] = useState({ x: 0, y: 0 });
   const [zoom, setZoom] = useState(1);
@@ -35,7 +39,10 @@ export function ImageCropModal({
     if (!croppedAreaPixels) return;
     setIsProcessing(true);
     try {
-      const blob = await cropImage(imageSrc, croppedAreaPixels);
+      const blob = await cropImage(imageSrc, croppedAreaPixels, outputType ?? 'image/webp', {
+        maxDimension: maxOutputDimension,
+        outputType,
+      });
       onCropComplete(blob);
       onClose();
     } catch {

packages/web/src/utils/assetUrls.ts

@@ -43,7 +43,7 @@ export function normalizeUserAssets<T extends { avatar?: string | null; banner?:
  * Rewrite user.avatar and attachment filenames on a message for remote origins.
  * Also normalizes nested replyTo message assets. Mutates in-place.
  */
-export function normalizeMessageAssets<T extends { user: { avatar?: string | null }; attachments?: { filename: string }[]; replyTo?: { user: { avatar?: string | null }; attachments?: { filename: string }[] } | null }>(
+export function normalizeMessageAssets<T extends { user: { avatar?: string | null }; attachments?: { filename: string; thumbnailFilename?: string | null }[]; replyTo?: { user: { avatar?: string | null }; attachments?: { filename: string; thumbnailFilename?: string | null }[] } | null }>(
   message: T,
   origin: string,
 ): T {
@@ -52,6 +52,9 @@ export function normalizeMessageAssets<T extends { user: { avatar?: string | nul
   if (message.attachments) {
     for (const att of message.attachments) {
       att.filename = resolveAssetUrl(att.filename, origin) ?? att.filename;
+      if (att.thumbnailFilename) {
+        att.thumbnailFilename = resolveAssetUrl(att.thumbnailFilename, origin) ?? att.thumbnailFilename;
+      }
     }
   }
   // Normalize reply-to message assets (remote replies have relative URLs)
@@ -60,6 +63,9 @@ export function normalizeMessageAssets<T extends { user: { avatar?: string | nul
     if (message.replyTo.attachments) {
       for (const att of message.replyTo.attachments) {
         att.filename = resolveAssetUrl(att.filename, origin) ?? att.filename;
+        if (att.thumbnailFilename) {
+          att.thumbnailFilename = resolveAssetUrl(att.thumbnailFilename, origin) ?? att.thumbnailFilename;
+        }
       }
     }
   }

packages/web/src/utils/cropImage.ts

@@ -5,20 +5,35 @@ export interface PixelCrop {
   height: number;
 }
 
-export function cropImage(imageSrc: string, pixelCrop: PixelCrop, outputType = 'image/png'): Promise<Blob> {
+interface CropOptions {
+  maxDimension?: number;
+  quality?: number;
+  outputType?: string;
+}
+
+export function cropImage(
+  imageSrc: string,
+  pixelCrop: PixelCrop,
+  outputType = 'image/webp',
+  options: CropOptions = {},
+): Promise<Blob> {
+  const { maxDimension, quality = 0.85 } = options;
+  const finalType = options.outputType ?? outputType;
+
   return new Promise((resolve, reject) => {
     const img = new Image();
     img.crossOrigin = 'anonymous';
     img.onload = () => {
-      const canvas = document.createElement('canvas');
-      canvas.width = pixelCrop.width;
-      canvas.height = pixelCrop.height;
-      const ctx = canvas.getContext('2d');
-      if (!ctx) {
+      // Step 1: Draw the crop region at original size
+      const cropCanvas = document.createElement('canvas');
+      cropCanvas.width = pixelCrop.width;
+      cropCanvas.height = pixelCrop.height;
+      const cropCtx = cropCanvas.getContext('2d');
+      if (!cropCtx) {
         reject(new Error('Failed to get canvas context'));
         return;
       }
-      ctx.drawImage(
+      cropCtx.drawImage(
         img,
         pixelCrop.x,
         pixelCrop.y,
@@ -29,12 +44,45 @@ export function cropImage(imageSrc: string, pixelCrop: PixelCrop, outputType = '
         pixelCrop.width,
         pixelCrop.height,
       );
-      canvas.toBlob(
+
+      // Step 2: Downscale if either dimension exceeds maxDimension
+      let outputCanvas = cropCanvas;
+      if (maxDimension && (pixelCrop.width > maxDimension || pixelCrop.height > maxDimension)) {
+        const scale = maxDimension / Math.max(pixelCrop.width, pixelCrop.height);
+        const scaledW = Math.round(pixelCrop.width * scale);
+        const scaledH = Math.round(pixelCrop.height * scale);
+        const scaledCanvas = document.createElement('canvas');
+        scaledCanvas.width = scaledW;
+        scaledCanvas.height = scaledH;
+        const scaledCtx = scaledCanvas.getContext('2d');
+        if (!scaledCtx) {
+          reject(new Error('Failed to get scaled canvas context'));
+          return;
+        }
+        scaledCtx.drawImage(cropCanvas, 0, 0, scaledW, scaledH);
+        outputCanvas = scaledCanvas;
+      }
+
+      // Step 3: Export to blob — try WebP first, fall back to PNG if unsupported
+      outputCanvas.toBlob(
         (blob) => {
-          if (blob) resolve(blob);
-          else reject(new Error('Canvas toBlob returned null'));
+          if (blob) {
+            resolve(blob);
+          } else if (finalType === 'image/webp') {
+            // WebP not supported (old Safari) — fall back to PNG
+            outputCanvas.toBlob(
+              (pngBlob) => {
+                if (pngBlob) resolve(pngBlob);
+                else reject(new Error('Canvas toBlob returned null'));
+              },
+              'image/png',
+            );
+          } else {
+            reject(new Error('Canvas toBlob returned null'));
+          }
         },
-        outputType,
+        finalType,
+        quality,
       );
     };
     img.onerror = () => reject(new Error('Failed to load image'));