@startsimpli/ui 0.4.25 → 0.4.26

package/src/components/chat/ChatComposer.tsx

@@ -1,8 +1,15 @@
 'use client'
 
 import * as React from 'react'
-import { SendHorizonal } from 'lucide-react'
+import { Paperclip, RotateCw, SendHorizonal, X } from 'lucide-react'
 import { cn } from '../../lib/utils'
+import type { PendingAttachment } from './types'
+import { formatBytes, isImageName } from './attachment-utils'
+import {
+  useComposerUploads,
+  type AttachmentUploader,
+  type UploadedAttachmentRef,
+} from './useComposerUploads'
 
 export interface ChatComposerProps {
   /** Controlled value. Omit for uncontrolled usage. */
@@ -18,12 +25,63 @@ export interface ChatComposerProps {
   submitLabel?: string
   /** Max rows the textarea grows to before scrolling. Default 10. */
   maxRows?: number
+  /**
+   * Controlled list of pending attachments rendered as chips above the textarea.
+   * The APP owns upload state; the composer is presentation-only here.
+   */
+  attachments?: PendingAttachment[]
+  /**
+   * Fired with the selected files from the attach button, a drag-and-drop onto
+   * the composer, or a clipboard paste of image/file data. Presence of this
+   * handler enables the attach affordances.
+   */
+  onAttachFiles?: (files: File[]) => void
+  /** Remove a pending attachment chip by id. */
+  onRemoveAttachment?: (id: string) => void
+  /** Retry a failed attachment chip by id (shows a retry control on error chips). */
+  onRetryAttachment?: (id: string) => void
+  /**
+   * SELF-MANAGED attachment mode. When provided, the composer drives the entire
+   * upload lifecycle itself (queued/uploading/ready/error chips, downscale,
+   * retry, remove + server-delete, new-deck queue-then-flush-on-`documentId`) by
+   * routing the attach button / drag-drop / paste files through this uploader.
+   * The app's `@startsimpli/api` `AttachmentsApi` structurally satisfies it.
+   *
+   * In this mode the controlled props (`attachments`/`onAttachFiles`/
+   * `onRemoveAttachment`/`onRetryAttachment`) are ignored — the composer owns
+   * the chip state. `onSubmit` still carries text only.
+   */
+  uploader?: AttachmentUploader
+  /**
+   * Document the uploads land on (self-managed mode). May be absent/'new' for a
+   * brand-new document: files are held client-side and auto-upload the moment a
+   * real id arrives.
+   */
+  documentId?: string
+  /** Upload purpose tag for self-managed uploads. Default 'reference'. */
+  attachmentPurpose?: string
+  /** Self-managed mode: fired with the uploaded attachment refs when they change. */
+  onAttachmentsChange?: (refs: UploadedAttachmentRef[]) => void
   className?: string
 }
 
 /**
  * Chat input with auto-growing textarea. Enter submits, Shift+Enter inserts a
  * newline, and large pastes are accepted as-is. Controlled or uncontrolled.
+ *
+ * Reference attachments are supported two ways (submit always carries text only):
+ *
+ *  - SELF-MANAGED (recommended, one line): pass an `uploader` (+ `documentId`).
+ *    The composer drives the full upload lifecycle internally via
+ *    `useComposerUploads` — downscale, progress, retry, remove + server-delete,
+ *    and new-deck queue-then-flush — routing attach button / drag-drop / paste
+ *    files through the uploader. The app wires nothing else.
+ *
+ *  - CONTROLLED (legacy): the app owns upload state and feeds `attachments`
+ *    down; the composer renders chips and surfaces new files via `onAttachFiles`
+ *    (`onRemoveAttachment`/`onRetryAttachment` for chip actions).
+ *
+ * Providing `uploader` switches to self-managed and ignores the controlled props.
  */
 export function ChatComposer({
   value,
@@ -34,12 +92,49 @@ export function ChatComposer({
   busy = false,
   submitLabel = 'Send',
   maxRows = 10,
+  attachments,
+  onAttachFiles,
+  onRemoveAttachment,
+  onRetryAttachment,
+  uploader,
+  documentId,
+  attachmentPurpose,
+  onAttachmentsChange,
   className,
 }: ChatComposerProps) {
   const isControlled = value !== undefined
   const [internal, setInternal] = React.useState('')
   const text = isControlled ? value! : internal
   const textareaRef = React.useRef<HTMLTextAreaElement>(null)
+  const fileInputRef = React.useRef<HTMLInputElement>(null)
+  const [dragOver, setDragOver] = React.useState(false)
+
+  // SELF-MANAGED mode: when an `uploader` is supplied, the composer owns the
+  // upload state and feeds its own chips/handlers in place of the controlled
+  // props. The hook runs unconditionally (Rules of Hooks); a no-op uploader
+  // keeps it inert when in controlled mode.
+  const selfManaged = !!uploader
+  const noopUploader = React.useRef<AttachmentUploader>({
+    async uploadAttachment() {
+      return { id: '', fileUrl: null }
+    },
+    async deleteAttachment() {
+      /* noop */
+    },
+  })
+  const uploads = useComposerUploads(uploader ?? noopUploader.current, documentId, {
+    purpose: attachmentPurpose,
+    onAttachmentsChange,
+  })
+
+  // Resolve effective chips/handlers from whichever mode is active.
+  const effectiveAttachments = selfManaged ? uploads.attachments : attachments
+  const effectiveAttachFiles = selfManaged ? uploads.attachFiles : onAttachFiles
+  const effectiveRemove = selfManaged ? uploads.removeAttachment : onRemoveAttachment
+  const effectiveRetry = selfManaged ? uploads.retryAttachment : onRetryAttachment
+
+  const attachEnabled = !!effectiveAttachFiles && !disabled
+  const chips = effectiveAttachments ?? []
 
   const setText = (next: string) => {
     if (!isControlled) setInternal(next)
@@ -61,6 +156,11 @@ export function ChatComposer({
     if (!canSubmit) return
     onSubmit(text.trim())
     if (!isControlled) setInternal('')
+    // Self-managed chips have been (or are being) uploaded to the document; the
+    // consumer reads them off the server on its turn, so clear them from the
+    // composer once the message goes out. (Controlled mode leaves chip lifecycle
+    // entirely to the app.)
+    if (selfManaged) uploads.clear()
   }
 
   const onKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
@@ -80,34 +180,214 @@ export function ChatComposer({
     submit()
   }
 
+  const emitFiles = (list: FileList | null | undefined) => {
+    if (!attachEnabled || !list || list.length === 0) return
+    effectiveAttachFiles!(Array.from(list))
+  }
+
+  const onPickClick = () => fileInputRef.current?.click()
+
+  const onInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    emitFiles(e.target.files)
+    // reset so picking the same file again re-fires change
+    e.target.value = ''
+  }
+
+  const onDrop = (e: React.DragEvent) => {
+    if (!attachEnabled) return
+    const files = e.dataTransfer?.files
+    if (files && files.length > 0) {
+      e.preventDefault()
+      setDragOver(false)
+      emitFiles(files)
+    }
+  }
+
+  const onDragOver = (e: React.DragEvent) => {
+    if (!attachEnabled) return
+    // Only treat as a file drag (not text selection drags).
+    if (Array.from(e.dataTransfer?.types ?? []).includes('Files')) {
+      e.preventDefault()
+      setDragOver(true)
+    }
+  }
+
+  const onDragLeave = () => setDragOver(false)
+
+  const onPaste = (e: React.ClipboardEvent) => {
+    if (!attachEnabled) return
+    const files = e.clipboardData?.files
+    if (files && files.length > 0) {
+      // Pasted image/file data — capture it as an attachment, not text.
+      e.preventDefault()
+      emitFiles(files)
+    }
+  }
+
   return (
-    <div className={cn('flex items-end gap-2 border-t border-border bg-background p-3', className)}>
-      <textarea
-        ref={textareaRef}
-        value={text}
-        onChange={(e) => setText(e.target.value)}
-        onKeyDown={onKeyDown}
-        placeholder={placeholder}
-        disabled={disabled}
-        rows={1}
-        className={cn(
-          'flex-1 resize-none rounded-lg border border-input bg-background px-3 py-2 text-sm shadow-sm',
-          'placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
-          'disabled:cursor-not-allowed disabled:opacity-50'
+    <div
+      className={cn(
+        'flex flex-col gap-2 border-t border-border bg-background p-3',
+        dragOver && 'ring-2 ring-inset ring-ring',
+        className
+      )}
+      onDrop={onDrop}
+      onDragOver={onDragOver}
+      onDragLeave={onDragLeave}
+    >
+      {chips.length > 0 && (
+        <ul className="flex flex-wrap gap-2" data-testid="chat-attachment-chips">
+          {chips.map((a) => (
+            <AttachmentChip
+              key={a.id}
+              attachment={a}
+              onRemove={effectiveRemove}
+              onRetry={effectiveRetry}
+            />
+          ))}
+        </ul>
+      )}
+      <div className="flex items-end gap-2">
+        {attachEnabled && (
+          <>
+            <input
+              ref={fileInputRef}
+              type="file"
+              multiple
+              className="sr-only"
+              data-testid="chat-attach-input"
+              onChange={onInputChange}
+            />
+            <button
+              type="button"
+              onClick={onPickClick}
+              aria-label="Attach files"
+              className={cn(
+                'inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-input bg-background text-muted-foreground shadow-sm transition-colors',
+                'hover:bg-accent hover:text-foreground'
+              )}
+            >
+              <Paperclip className="h-4 w-4" aria-hidden="true" />
+            </button>
+          </>
         )}
-      />
-      <button
-        type="button"
-        onClick={submit}
-        disabled={!canSubmit}
-        aria-label={submitLabel}
-        className={cn(
-          'inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-primary text-primary-foreground shadow-sm transition-opacity',
-          'hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40'
-        )}
-      >
-        <SendHorizonal className="h-4 w-4" aria-hidden="true" />
-      </button>
+        <textarea
+          ref={textareaRef}
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          onKeyDown={onKeyDown}
+          onPaste={attachEnabled ? onPaste : undefined}
+          placeholder={placeholder}
+          disabled={disabled}
+          rows={1}
+          className={cn(
+            'flex-1 resize-none rounded-lg border border-input bg-background px-3 py-2 text-sm shadow-sm',
+            'placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+            'disabled:cursor-not-allowed disabled:opacity-50'
+          )}
+        />
+        <button
+          type="button"
+          onClick={submit}
+          disabled={!canSubmit}
+          aria-label={submitLabel}
+          className={cn(
+            'inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-primary text-primary-foreground shadow-sm transition-opacity',
+            'hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40'
+          )}
+        >
+          <SendHorizonal className="h-4 w-4" aria-hidden="true" />
+        </button>
+      </div>
     </div>
   )
 }
+
+function AttachmentChip({
+  attachment,
+  onRemove,
+  onRetry,
+}: {
+  attachment: PendingAttachment
+  onRemove?: (id: string) => void
+  onRetry?: (id: string) => void
+}) {
+  const { id, name, status, progress, thumbnailUrl, sizeBytes, error } = attachment
+  const isImage = !!thumbnailUrl && isImageName(name)
+  const pct = Math.round((progress ?? 0) * 100)
+
+  return (
+    <li
+      data-testid={`chat-attachment-${id}`}
+      data-status={status}
+      className={cn(
+        'group relative flex items-center gap-2 rounded-md border border-border bg-muted/40 py-1 pl-1 pr-2 text-xs',
+        status === 'error' && 'border-red-300 bg-red-50 text-red-700'
+      )}
+    >
+      {isImage ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img
+          src={thumbnailUrl}
+          alt={name}
+          className="h-8 w-8 shrink-0 rounded object-cover"
+        />
+      ) : (
+        <span
+          className="flex h-8 w-8 shrink-0 items-center justify-center rounded bg-muted text-muted-foreground"
+          aria-hidden="true"
+        >
+          <Paperclip className="h-4 w-4" />
+        </span>
+      )}
+      <span className="flex min-w-0 flex-col">
+        <span className="max-w-[10rem] truncate font-medium" title={name}>
+          {name}
+        </span>
+        <span className="text-[10px] text-muted-foreground">
+          {status === 'uploading'
+            ? `Uploading… ${pct}%`
+            : status === 'error'
+              ? (error || 'Upload failed')
+              : sizeBytes != null
+                ? formatBytes(sizeBytes)
+                : null}
+        </span>
+      </span>
+      {status === 'error' && onRetry && (
+        <button
+          type="button"
+          onClick={() => onRetry(id)}
+          aria-label={`Retry ${name}`}
+          className="ml-1 inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-red-600 hover:bg-red-100"
+        >
+          <RotateCw className="h-3 w-3" aria-hidden="true" />
+        </button>
+      )}
+      {status === 'uploading' && (
+        <span
+          role="progressbar"
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={pct}
+          className="absolute inset-x-1 bottom-0 h-1 overflow-hidden rounded-full bg-muted"
+        >
+          <span
+            className="block h-full bg-primary transition-[width]"
+            style={{ width: `${pct}%` }}
+          />
+        </span>
+      )}
+      {onRemove && (
+        <button
+          type="button"
+          onClick={() => onRemove(id)}
+          aria-label={`Remove ${name}`}
+          className="ml-1 inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-muted-foreground hover:bg-background hover:text-foreground"
+        >
+          <X className="h-3 w-3" aria-hidden="true" />
+        </button>
+      )}
+    </li>
+  )
+}

package/src/components/chat/ChatMessage.tsx

@@ -1,9 +1,10 @@
 'use client'
 
 import * as React from 'react'
-import { Wrench } from 'lucide-react'
+import { Paperclip, Wrench } from 'lucide-react'
 import { cn } from '../../lib/utils'
-import type { ChatMessageData } from './types'
+import type { ChatMessageAttachment, ChatMessageData } from './types'
+import { isImageName } from './attachment-utils'
 
 export interface ChatMessageProps {
   message: ChatMessageData
@@ -27,8 +28,58 @@ function StreamingDots() {
  * assistant left); `tool` / `status` kinds render as compact centered system
  * rows. Fully generic — no presentation-specific knowledge.
  */
+/** Attachment chips/thumbnails rendered on a message bubble. */
+function MessageAttachments({
+  attachments,
+  isUser,
+}: {
+  attachments: ChatMessageAttachment[]
+  isUser: boolean
+}) {
+  return (
+    <ul className="mt-2 flex flex-wrap gap-2" data-testid="chat-message-attachments">
+      {attachments.map((a) => {
+        const isImage = !!a.fileUrl && isImageName(a.contentType || a.filename)
+        const chip = (
+          <span
+            className={cn(
+              'flex items-center gap-1.5 rounded-md border px-1.5 py-1 text-xs',
+              isUser
+                ? 'border-primary-foreground/30 bg-primary-foreground/10'
+                : 'border-border bg-background/60'
+            )}
+          >
+            <Paperclip className="h-3 w-3 shrink-0" aria-hidden="true" />
+            <span className="max-w-[10rem] truncate" title={a.filename}>
+              {a.filename}
+            </span>
+          </span>
+        )
+        return (
+          <li key={a.id} data-testid={`chat-message-attachment-${a.id}`}>
+            {isImage ? (
+              // eslint-disable-next-line @next/next/no-img-element
+              <img
+                src={a.fileUrl!}
+                alt={a.filename}
+                className="h-16 w-16 rounded-md border border-border object-cover"
+              />
+            ) : a.fileUrl ? (
+              <a href={a.fileUrl} target="_blank" rel="noreferrer" className="hover:opacity-80">
+                {chip}
+              </a>
+            ) : (
+              chip
+            )}
+          </li>
+        )
+      })}
+    </ul>
+  )
+}
+
 export function ChatMessage({ message, renderContent, className }: ChatMessageProps) {
-  const { role, content, status, kind = 'text', toolName } = message
+  const { role, content, status, kind = 'text', toolName, attachments } = message
   const isStreaming = status === 'streaming'
   const isError = status === 'error'
 
@@ -75,6 +126,9 @@ export function ChatMessage({ message, renderContent, className }: ChatMessagePr
       >
         {body}
         {isStreaming && <StreamingDots />}
+        {attachments && attachments.length > 0 && (
+          <MessageAttachments attachments={attachments} isUser={isUser} />
+        )}
       </div>
     </div>
   )

package/src/components/chat/ChatThread.tsx

@@ -14,9 +14,32 @@ export interface ChatThreadProps {
   /** Auto-scroll to the newest message on change. Default true. */
   autoScroll?: boolean
   renderContent?: (content: string, message: ChatMessageData) => React.ReactNode
+  /** Show an animated "working" indicator at the end (the agent is processing). */
+  busy?: boolean
+  /** Label shown next to the working indicator. Default "Working…". */
+  busyLabel?: string
   className?: string
 }
 
+/** Animated three-dot "agent is working" row, aligned like an assistant message. */
+function WorkingIndicator({ label = 'Working…' }: { label?: string }) {
+  return (
+    <div
+      className="flex items-center gap-2 px-1 text-sm text-muted-foreground"
+      role="status"
+      aria-live="polite"
+      data-testid="chat-working-indicator"
+    >
+      <span className="flex gap-1" aria-hidden="true">
+        <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current [animation-delay:-0.3s]" />
+        <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current [animation-delay:-0.15s]" />
+        <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-current" />
+      </span>
+      {label}
+    </div>
+  )
+}
+
 /**
  * Scrollable, auto-scrolling list of chat messages. App-agnostic.
  */
@@ -26,15 +49,18 @@ export function ChatThread({
   renderMessage,
   autoScroll = true,
   renderContent,
+  busy = false,
+  busyLabel,
   className,
 }: ChatThreadProps) {
   const anchorRef = React.useRef<HTMLDivElement>(null)
 
   React.useEffect(() => {
     if (autoScroll) anchorRef.current?.scrollIntoView({ block: 'end' })
-  }, [messages, autoScroll])
+  }, [messages, busy, autoScroll])
 
-  if (messages.length === 0 && emptyState) {
+  // Empty thread + not working → the caller's empty state.
+  if (messages.length === 0 && !busy && emptyState) {
     return (
       <div className={cn('flex h-full items-center justify-center p-6 text-center', className)}>
         {emptyState}
@@ -51,6 +77,7 @@ export function ChatThread({
           <ChatMessage key={m.id} message={m} renderContent={renderContent} />
         )
       )}
+      {busy && <WorkingIndicator label={busyLabel} />}
       <div ref={anchorRef} data-testid="chat-thread-anchor" />
     </div>
   )

package/src/components/chat/attachment-utils.ts

@@ -0,0 +1,24 @@
+/** Small presentation helpers shared by the chat attachment chips/thumbnails. */
+
+/** Human-readable byte size, e.g. 2048 -> "2 KB", 1536000 -> "1.5 MB". */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return ''
+  if (bytes < 1024) return `${bytes} B`
+  const units = ['KB', 'MB', 'GB', 'TB']
+  let value = bytes / 1024
+  let i = 0
+  while (value >= 1024 && i < units.length - 1) {
+    value /= 1024
+    i++
+  }
+  const rounded = value >= 10 || Number.isInteger(value) ? Math.round(value) : Math.round(value * 10) / 10
+  return `${rounded} ${units[i]}`
+}
+
+const IMAGE_EXT = /\.(png|jpe?g|gif|webp|avif|bmp|svg|heic|heif)$/i
+
+/** Whether a filename or content-type looks like a previewable image. */
+export function isImageName(nameOrType: string | undefined | null): boolean {
+  if (!nameOrType) return false
+  return nameOrType.startsWith('image/') || IMAGE_EXT.test(nameOrType)
+}

package/src/components/chat/image-downscale.test.ts

@@ -0,0 +1,28 @@
+import { downscaleImage } from './image-downscale'
+
+function file(name: string, type: string, bytes = 100) {
+  return new File([new Uint8Array(bytes)], name, { type })
+}
+
+describe('downscaleImage (best-effort, jsdom has no canvas/createImageBitmap)', () => {
+  it('returns non-image files untouched', async () => {
+    const f = file('deck.pdf', 'application/pdf')
+    expect(await downscaleImage(f)).toBe(f)
+  })
+
+  it('returns GIFs untouched (may be animated)', async () => {
+    const f = file('anim.gif', 'image/gif')
+    expect(await downscaleImage(f)).toBe(f)
+  })
+
+  it('returns SVGs untouched (vector)', async () => {
+    const f = file('logo.svg', 'image/svg+xml')
+    expect(await downscaleImage(f)).toBe(f)
+  })
+
+  it('falls back to the original image when the environment cannot rasterize', async () => {
+    // In jsdom createImageBitmap is undefined → best-effort returns original.
+    const f = file('photo.png', 'image/png', 5_000_000)
+    expect(await downscaleImage(f)).toBe(f)
+  })
+})

package/src/components/chat/image-downscale.ts

@@ -0,0 +1,88 @@
+/**
+ * Best-effort client-side image downscale for uploads.
+ *
+ * Reference images (e.g. an old deck slide a user drops in to clone the look)
+ * are often multi-MB originals, but the backend reference-extraction normalizes
+ * everything to ~1536px anyway — so uploading full-res is wasteful, slow, and
+ * (on a constrained proxy) can hang. We downscale in the browser first.
+ *
+ * ALWAYS best-effort: any failure (no DOM, unsupported codec, decode error)
+ * returns the ORIGINAL file untouched, so this can never block an upload. Only
+ * raster images above the threshold are touched; non-images, GIFs (possibly
+ * animated), SVGs, and already-small images pass through verbatim.
+ */
+
+export interface DownscaleOptions {
+  /** Max width/height of the output (longest side). Default 1536 (model limit). */
+  maxDim?: number
+  /** JPEG quality 0..1 for the re-encoded output. Default 0.82. */
+  quality?: number
+  /** Skip downscale for files at/under this size when also within maxDim. Default 1.5MB. */
+  sizeThresholdBytes?: number
+}
+
+const DEFAULTS = { maxDim: 1536, quality: 0.82, sizeThresholdBytes: 1_500_000 }
+
+/** True for raster image types we can safely re-encode (excludes gif/svg). */
+function isDownscalableImage(file: File): boolean {
+  return (
+    file.type.startsWith('image/') &&
+    file.type !== 'image/gif' &&
+    file.type !== 'image/svg+xml'
+  )
+}
+
+export async function downscaleImage(file: File, options: DownscaleOptions = {}): Promise<File> {
+  const { maxDim, quality, sizeThresholdBytes } = { ...DEFAULTS, ...options }
+
+  // Bail to the original whenever we can't (or needn't) do better.
+  if (
+    typeof document === 'undefined' ||
+    typeof createImageBitmap === 'undefined' ||
+    !isDownscalableImage(file)
+  ) {
+    return file
+  }
+
+  try {
+    const bitmap = await createImageBitmap(file)
+    const longest = Math.max(bitmap.width, bitmap.height)
+    const scale = Math.min(1, maxDim / longest)
+
+    // Already within bounds and small enough — keep the original (preserves
+    // format/quality; e.g. a crisp PNG screenshot under the threshold).
+    if (scale >= 1 && file.size <= sizeThresholdBytes) {
+      bitmap.close?.()
+      return file
+    }
+
+    const w = Math.max(1, Math.round(bitmap.width * scale))
+    const h = Math.max(1, Math.round(bitmap.height * scale))
+    const canvas = document.createElement('canvas')
+    canvas.width = w
+    canvas.height = h
+    const ctx = canvas.getContext('2d')
+    if (!ctx) {
+      bitmap.close?.()
+      return file
+    }
+    // Flatten onto white so transparency doesn't become black in JPEG.
+    ctx.fillStyle = '#ffffff'
+    ctx.fillRect(0, 0, w, h)
+    ctx.drawImage(bitmap, 0, 0, w, h)
+    bitmap.close?.()
+
+    const blob = await new Promise<Blob | null>((resolve) =>
+      canvas.toBlob(resolve, 'image/jpeg', quality)
+    )
+    if (!blob || blob.size >= file.size) return file // no win → keep original
+
+    const baseName = file.name.replace(/\.[^.]+$/, '') || 'image'
+    return new File([blob], `${baseName}.jpg`, {
+      type: 'image/jpeg',
+      lastModified: file.lastModified,
+    })
+  } catch {
+    return file
+  }
+}