@@ -13,6 +13,7 @@ import { CopilotFiles, isUsingCloudStorage } from '@/lib/uploads'
 import type { StorageContext } from '@/lib/uploads/config'
 import { parseWorkspaceFileKey } from '@/lib/uploads/contexts/workspace/workspace-file-manager'
 import { downloadFile } from '@/lib/uploads/core/storage-service'
+import { resolveServableImageBytes } from '@/lib/uploads/server/image-derivative'
 import { inferContextFromKey } from '@/lib/uploads/utils/file-utils'
 import { verifyFileAccess } from '@/app/api/files/authorization'
 import {
@@ -30,15 +31,23 @@ const logger = createLogger('FilesServeAPI')
  * {@link resolveServableDocBytes} (generated docs → compiled artifact). `raw=1`
  * bypasses resolution and serves the stored source as-is.
  */
-async function compileDocumentIfNeeded(
+async function resolveServableBytes(
   buffer: Buffer,
   filename: string,
+  storageKey: string,
   workspaceId: string | undefined,
   raw: boolean,
   ownerKey: string | undefined,
   signal: AbortSignal | undefined
 ): Promise<{ buffer: Buffer; contentType: string }> {
   if (raw) return { buffer, contentType: getContentType(filename) }
+
+  // Images resolve first and independently of the document path: a HEIF has no
+  // compiled-source concept, and its derivative is keyed by storage key rather
+  // than by source hash.
+  const image = await resolveServableImageBytes(buffer, storageKey)
+  if (image) return image
+
   return resolveServableDocBytes({
     rawBuffer: buffer,
     fileName: filename,
@@ -198,9 +207,10 @@ async function handleLocalFile(
     const segment = filename.split('/').pop() || filename
     const displayName = stripStorageKeyPrefix(segment)
     const workspaceId = getWorkspaceIdForCompile(filename)
-    const { buffer: fileBuffer, contentType } = await compileDocumentIfNeeded(
+    const { buffer: fileBuffer, contentType } = await resolveServableBytes(
       rawBuffer,
       displayName,
+      filename,
       workspaceId,
       raw,
       ownerKey,
@@ -260,9 +270,10 @@ async function handleCloudProxy(
     const segment = cloudKey.split('/').pop() || 'download'
     const displayName = stripStorageKeyPrefix(segment)
     const workspaceId = getWorkspaceIdForCompile(cloudKey)
-    const { buffer: fileBuffer, contentType } = await compileDocumentIfNeeded(
+    const { buffer: fileBuffer, contentType } = await resolveServableBytes(
       rawBuffer,
       displayName,
+      cloudKey,
       workspaceId,
       raw,
       ownerKey,
 
@@ -227,13 +227,15 @@ describe('resolveFileCategory — formats accepted on upload must be previewable
     ['image.bmp', 'image/bmp'],
     ['image.avif', 'image/avif'],
     ['favicon.ico', 'image/x-icon'],
+    ['photo.heic', 'image/heic'],
+    ['photo.heif', 'image/heif'],
   ])('%s previews as an image', (filename, mimeType) => {
     expect(resolveFileCategory(mimeType, filename)).toBe('image-previewable')
     expect(resolveFileCategory('application/octet-stream', filename)).toBe('image-previewable')
   })
 
-  it.each(['image.tiff', 'photo.heic'])(
-    '%s stays unsupported — no browser renders it in an <img>',
+  it.each(['image.tiff', 'scan.tif'])(
+    '%s stays unsupported — nothing decodes it on either side',
     (filename) => {
       expect(resolveFileCategory(null, filename)).toBe('unsupported')
     }
 
@@ -44,10 +44,12 @@ const IFRAME_PREVIEWABLE_MIME_TYPES = new Set([
 const IFRAME_PREVIEWABLE_EXTENSIONS = new Set(['pdf'])
 
 /**
- * Image formats every supported browser decodes natively. `.tif`/`.tiff` and
- * `.heic`/`.heif` are accepted uploads but deliberately absent — no browser renders
- * them in an `<img>`, so they stay on the download-only path rather than showing a
- * broken image.
+ * Formats the image viewer can show. Most are decoded by the browser directly;
+ * `.heic`/`.heif` are not — no browser outside Safari renders them — but the serve
+ * route transcodes them to JPEG, so an `<img>` pointed at it works.
+ *
+ * `.tif`/`.tiff` are accepted uploads and deliberately absent: nothing decodes them
+ * on either side, so they stay download-only rather than showing a broken image.
  */
 const IMAGE_PREVIEWABLE_MIME_TYPES = new Set([
   'image/png',
@@ -58,6 +60,8 @@ const IMAGE_PREVIEWABLE_MIME_TYPES = new Set([
   'image/bmp',
   'image/x-icon',
   'image/vnd.microsoft.icon',
+  'image/heic',
+  'image/heif',
 ])
 const IMAGE_PREVIEWABLE_EXTENSIONS = new Set([
   'png',
@@ -68,6 +72,8 @@ const IMAGE_PREVIEWABLE_EXTENSIONS = new Set([
   'avif',
   'bmp',
   'ico',
+  'heic',
+  'heif',
 ])
 
 const AUDIO_PREVIEWABLE_MIME_TYPES = new Set([
 
@@ -0,0 +1,89 @@
+/**
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockDownloadFile, mockUploadFile, mockTranscode } = vi.hoisted(() => ({
+  mockDownloadFile: vi.fn(),
+  mockUploadFile: vi.fn(),
+  mockTranscode: vi.fn(),
+}))
+
+vi.mock('@/lib/uploads/core/storage-service', () => ({
+  downloadFile: mockDownloadFile,
+  uploadFile: mockUploadFile,
+}))
+
+vi.mock('@/lib/uploads/server/heic', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@/lib/uploads/server/heic')>()),
+  transcodeHeicToJpeg: mockTranscode,
+}))
+
+import { resolveServableImageBytes } from '@/lib/uploads/server/image-derivative'
+
+/** An ISO-BMFF `ftyp` box declaring a HEVC-coded HEIF still. */
+function heifBytes(): Buffer {
+  const header = Buffer.alloc(16)
+  header.writeUInt32BE(16, 0)
+  header.write('ftyp', 4, 'ascii')
+  header.write('heic', 8, 'ascii')
+  return header
+}
+
+const JPEG = Buffer.from([0xff, 0xd8, 0xff, 0xe0])
+
+describe('resolveServableImageBytes', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockDownloadFile.mockRejectedValue(new Error('not found'))
+    mockUploadFile.mockResolvedValue(undefined)
+    mockTranscode.mockResolvedValue(JPEG)
+  })
+
+  it('leaves non-HEIF bytes untouched', async () => {
+    expect(await resolveServableImageBytes(JPEG, 'workspace/ws/a.jpg')).toBeNull()
+    expect(mockDownloadFile).not.toHaveBeenCalled()
+    expect(mockTranscode).not.toHaveBeenCalled()
+  })
+
+  it('transcodes and caches on a miss', async () => {
+    const result = await resolveServableImageBytes(heifBytes(), 'workspace/ws/a.heic')
+
+    expect(result).toEqual({ buffer: JPEG, contentType: 'image/jpeg' })
+    expect(mockTranscode).toHaveBeenCalledOnce()
+    expect(mockUploadFile).toHaveBeenCalledOnce()
+  })
+
+  it('serves the cached derivative without decoding again', async () => {
+    const cached = Buffer.from([0xff, 0xd8, 0xca, 0xce])
+    mockDownloadFile.mockResolvedValue(cached)
+
+    const result = await resolveServableImageBytes(heifBytes(), 'workspace/ws/a.heic')
+
+    expect(result).toEqual({ buffer: cached, contentType: 'image/jpeg' })
+    expect(mockTranscode).not.toHaveBeenCalled()
+  })
+
+  it('keys the derivative by storage key, so replaced content misses the old entry', async () => {
+    await resolveServableImageBytes(heifBytes(), 'workspace/ws/111-a.heic')
+    await resolveServableImageBytes(heifBytes(), 'workspace/ws/222-a.heic')
+
+    const [first, second] = mockUploadFile.mock.calls.map((call) => call[0].customKey)
+    expect(first).not.toEqual(second)
+  })
+
+  it('still serves the image when caching the derivative fails', async () => {
+    mockUploadFile.mockRejectedValue(new Error('s3 down'))
+
+    const result = await resolveServableImageBytes(heifBytes(), 'workspace/ws/a.heic')
+
+    expect(result).toEqual({ buffer: JPEG, contentType: 'image/jpeg' })
+  })
+
+  it('falls back to the stored bytes when the decode fails', async () => {
+    mockTranscode.mockResolvedValue(null)
+
+    expect(await resolveServableImageBytes(heifBytes(), 'workspace/ws/a.heic')).toBeNull()
+    expect(mockUploadFile).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto'
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { downloadFile, uploadFile } from '@/lib/uploads/core/storage-service'
+import { isHeifContainer, transcodeHeicToJpeg } from '@/lib/uploads/server/heic'
+
+const logger = createLogger('ImageDerivative')
+
+/**
+ * Keyed by the source's storage key rather than a hash of its bytes. Workspace keys
+ * are regenerated on every content replacement, so the key is already a content
+ * version — using it avoids streaming the whole original just to hash it.
+ */
+function derivativeKey(storageKey: string): string {
+  const hash = createHash('sha256').update(storageKey, 'utf-8').digest('hex')
+  return `image-derivative/${hash}.jpg`
+}
+
+async function loadDerivative(storageKey: string): Promise<Buffer | null> {
+  try {
+    return await downloadFile({ key: derivativeKey(storageKey), context: 'copilot' })
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Stores the derivative, swallowing failure.
+ *
+ * Unlike the compiled-doc store — which throws, because its serve path is load-only
+ * and cannot rebuild a missing artifact — a miss here is fully recoverable: the next
+ * read transcodes again. Failing the request would turn a cache problem into a broken
+ * image for bytes we have already rendered successfully.
+ */
+async function storeDerivative(storageKey: string, jpeg: Buffer): Promise<void> {
+  try {
+    await uploadFile({
+      file: jpeg,
+      fileName: 'derivative.jpg',
+      contentType: 'image/jpeg',
+      context: 'copilot',
+      customKey: derivativeKey(storageKey),
+      preserveKey: true,
+    })
+  } catch (error) {
+    logger.warn('Failed to store image derivative', {
+      storageKey,
+      error: getErrorMessage(error),
+    })
+  }
+}
+
+/**
+ * A browser-renderable form of stored image bytes, or `null` when the stored bytes
+ * are already renderable and should be served untouched.
+ *
+ * Only HEIF needs this today: no browser outside Safari decodes it, and serving it
+ * under `X-Content-Type-Options: nosniff` guarantees a broken image. The transcoded
+ * JPEG is cached, because a preview is re-fetched on every view and the WebAssembly
+ * decode costs roughly a second for a phone photo.
+ *
+ * The original always remains the stored object — downloads and `raw=1` serve it
+ * untouched, so this never rewrites what a user gets back.
+ */
+export async function resolveServableImageBytes(
+  buffer: Buffer,
+  storageKey: string
+): Promise<{ buffer: Buffer; contentType: string } | null> {
+  if (!isHeifContainer(buffer)) return null
+
+  const cached = await loadDerivative(storageKey)
+  if (cached) return { buffer: cached, contentType: 'image/jpeg' }
+
+  const jpeg = await transcodeHeicToJpeg(buffer)
+  if (!jpeg) return null
+
+  await storeDerivative(storageKey, jpeg)
+  return { buffer: jpeg, contentType: 'image/jpeg' }
+}