@@ -11,6 +11,7 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { enforcePublicFileRateLimit } from '@/lib/public-shares/rate-limit'
 import { resolveActiveShareByToken } from '@/lib/public-shares/share-manager'
 import { downloadFile } from '@/lib/uploads/core/storage-service'
+import { resolveServableImageBytes } from '@/lib/uploads/server/image-derivative'
 import {
   createErrorResponse,
   createFileResponse,
@@ -31,8 +32,10 @@ const logger = createLogger('PublicFileContentAPI')
  *
  * Generated office docs are stored as source; {@link resolveServableDoc} swaps in
  * their prebuilt compiled binary (read-only, never compiles). Uploaded binaries
- * pass through untouched. A generated doc whose compiled artifact isn't built yet
- * returns 409 rather than serving raw source under a binary content type.
+ * pass through untouched, except under `preview=1`, where a format no browser
+ * decodes is substituted with a renderable derivative. A generated doc whose
+ * compiled artifact isn't built yet returns 409 rather than serving raw source
+ * under a binary content type.
  */
 export const GET = withRouteHandler(
   async (request: NextRequest, context: { params: Promise<{ token: string }> }) => {
@@ -45,6 +48,7 @@ export const GET = withRouteHandler(
       const parsed = await parseRequest(getPublicFileContentContract, request, context)
       if (!parsed.success) return parsed.response
       const { token } = parsed.data.params
+      const preview = parsed.data.query.preview === '1'
 
       const resolved = await resolveActiveShareByToken(token)
       if (!resolved) {
@@ -77,12 +81,20 @@ export const GET = withRouteHandler(
         )
       }
 
-      const buffer = servable.kind === 'artifact' ? servable.buffer : raw
       // This response is `nosniff`, so a stored `application/octet-stream` refuses to render
       // even though the bytes are fine. Resolving from the filename also keeps this route on
       // the same inline allowlist as the workspace serve route.
-      const contentType =
-        servable.kind === 'artifact' ? servable.contentType : getContentType(file.originalName)
+      let buffer = raw
+      let contentType = getContentType(file.originalName)
+      if (servable.kind === 'artifact') {
+        buffer = servable.buffer
+        contentType = servable.contentType
+      } else if (preview) {
+        // Only for a render request: the Download button omits `preview`, so a saved
+        // file is always the bytes that were shared.
+        const image = await resolveServableImageBytes(raw, file.key)
+        if (image) ({ buffer, contentType } = image)
+      }
 
       logger.info('Public shared file served', { token, key: file.key, size: buffer.length })
 
 
@@ -26,27 +26,43 @@ import {
 
 const logger = createLogger('FilesServeAPI')
 
+interface ServeOptions {
+  /** `raw=1` — bypass all resolution and serve the stored source as-is. */
+  raw: boolean
+  /** `preview=1` — the caller renders these bytes rather than saving them. */
+  preview: boolean
+  /** `v=<updatedAt>` — the URL addresses content-immutable bytes. */
+  versioned: boolean
+}
+
 /**
- * Resolves the bytes + content type to serve for a stored file via the shared
- * {@link resolveServableDocBytes} (generated docs → compiled artifact). `raw=1`
- * bypasses resolution and serves the stored source as-is.
+ * Resolves the bytes + content type to serve for a stored file.
+ *
+ * Document compilation is unconditional: a generated `.docx`/`.xlsx`/`.pptx` is
+ * stored as source, so the compiled artifact *is* the file, and every download
+ * routes through here. An image derivative is the opposite — the stored bytes are
+ * the file — so it is served only when the caller asked to preview, never when it
+ * asked to download.
  */
-async function resolveServableBytes(
-  buffer: Buffer,
-  filename: string,
-  storageKey: string,
-  workspaceId: string | undefined,
-  raw: boolean,
-  ownerKey: string | undefined,
+async function resolveServableBytes(params: {
+  buffer: Buffer
+  filename: string
+  storageKey: string
+  workspaceId: string | undefined
+  options: ServeOptions
+  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
+}): Promise<{ buffer: Buffer; contentType: string }> {
+  const { buffer, filename, storageKey, workspaceId, options, ownerKey, signal } = params
+  if (options.raw) return { buffer, contentType: getContentType(filename) }
+
+  if (options.preview) {
+    // 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,
@@ -126,10 +142,14 @@ export const GET = withRouteHandler(
 
       const query = fileServeQuerySchema.parse({
         raw: request.nextUrl.searchParams.get('raw'),
+        preview: request.nextUrl.searchParams.get('preview'),
         v: request.nextUrl.searchParams.get('v'),
       })
-      const raw = query.raw === '1'
-      const versioned = query.v != null
+      const options: ServeOptions = {
+        raw: query.raw === '1',
+        preview: query.preview === '1',
+        versioned: query.v != null,
+      }
 
       const authResult = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
 
@@ -144,10 +164,10 @@ export const GET = withRouteHandler(
       const userId = authResult.userId
 
       if (isUsingCloudStorage()) {
-        return await handleCloudProxy(cloudKey, userId, raw, versioned, request.signal)
+        return await handleCloudProxy(cloudKey, userId, options, request.signal)
       }
 
-      return await handleLocalFile(cloudKey, userId, raw, versioned, request.signal)
+      return await handleLocalFile(cloudKey, userId, options, request.signal)
     } catch (error) {
       // An in-progress/incomplete doc source fails to compile — this is expected
       // mid-generation, not a server fault. Return 409 (not 500) so it isn't an
@@ -174,8 +194,7 @@ export const GET = withRouteHandler(
 async function handleLocalFile(
   filename: string,
   userId: string,
-  raw: boolean,
-  versioned: boolean,
+  options: ServeOptions,
   signal: AbortSignal | undefined
 ): Promise<NextResponse> {
   const ownerKey = `user:${userId}`
@@ -207,23 +226,23 @@ async function handleLocalFile(
     const segment = filename.split('/').pop() || filename
     const displayName = stripStorageKeyPrefix(segment)
     const workspaceId = getWorkspaceIdForCompile(filename)
-    const { buffer: fileBuffer, contentType } = await resolveServableBytes(
-      rawBuffer,
-      displayName,
-      filename,
+    const { buffer: fileBuffer, contentType } = await resolveServableBytes({
+      buffer: rawBuffer,
+      filename: displayName,
+      storageKey: filename,
       workspaceId,
-      raw,
+      options,
       ownerKey,
-      signal
-    )
+      signal,
+    })
 
     logger.info('Local file served', { userId, filename, size: fileBuffer.length })
 
     return createFileResponse({
       buffer: fileBuffer,
       contentType,
       filename: displayName,
-      cacheControl: resolveServeCacheControl(versioned, contextParam),
+      cacheControl: resolveServeCacheControl(options.versioned, contextParam),
     })
   } catch (error) {
     logger.error('Error reading local file:', error)
@@ -234,9 +253,8 @@ async function handleLocalFile(
 async function handleCloudProxy(
   cloudKey: string,
   userId: string,
-  raw = false,
-  versioned = false,
-  signal: AbortSignal | undefined = undefined
+  options: ServeOptions,
+  signal: AbortSignal | undefined
 ): Promise<NextResponse> {
   const ownerKey = `user:${userId}`
   try {
@@ -270,15 +288,15 @@ async function handleCloudProxy(
     const segment = cloudKey.split('/').pop() || 'download'
     const displayName = stripStorageKeyPrefix(segment)
     const workspaceId = getWorkspaceIdForCompile(cloudKey)
-    const { buffer: fileBuffer, contentType } = await resolveServableBytes(
-      rawBuffer,
-      displayName,
-      cloudKey,
+    const { buffer: fileBuffer, contentType } = await resolveServableBytes({
+      buffer: rawBuffer,
+      filename: displayName,
+      storageKey: cloudKey,
       workspaceId,
-      raw,
+      options,
       ownerKey,
-      signal
-    )
+      signal,
+    })
 
     logger.info('Cloud file served', {
       userId,
@@ -291,7 +309,7 @@ async function handleCloudProxy(
       buffer: fileBuffer,
       contentType,
       filename: displayName,
-      cacheControl: resolveServeCacheControl(versioned, context),
+      cacheControl: resolveServeCacheControl(options.versioned, context),
     })
   } catch (error) {
     logger.error('Error downloading from cloud storage:', error)
 
@@ -4,7 +4,7 @@ import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Music } from '@sim/emcn/icons'
 import dynamic from 'next/dynamic'
 import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
-import { getFileExtension, resolveMediaMimeType } from '@/lib/uploads/utils/file-utils'
+import { resolveMediaMimeType } from '@/lib/uploads/utils/file-utils'
 import {
   useWorkspaceFileBinary,
   useWorkspaceFileContent,
@@ -28,6 +28,7 @@ import {
   PreviewErrorBoundary,
   PreviewLoadingFrame,
   resolvePreviewError,
+  UnsupportedPreview,
 } from './preview-shared'
 import { TextEditor } from './text-editor'
 import { useDocPreviewBinary } from './use-doc-preview-binary'
@@ -421,22 +422,3 @@ const MediaPreview = memo(function MediaPreview({
     </div>
   )
 })
-
-const UnsupportedPreview = memo(function UnsupportedPreview({
-  file,
-}: {
-  file: WorkspaceFileRecord
-}) {
-  const ext = getFileExtension(file.name)
-
-  return (
-    <div className='flex flex-1 flex-col items-center justify-center gap-[8px]'>
-      <p className='font-medium text-[14px] text-[var(--text-primary)]'>
-        Preview not available{ext ? ` for .${ext} files` : ' for this file'}
-      </p>
-      <p className='text-[13px] text-[var(--text-muted)]'>
-        Use the download button to view this file
-      </p>
-    </div>
-  )
-})
@@ -0,0 +1,71 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
+import { ImagePreview } from './image-preview'
+
+const file = {
+  id: 'file-1',
+  workspaceId: 'ws-1',
+  name: 'photo.heic',
+  key: 'workspace/ws-1/photo.heic',
+  path: '',
+  size: 1024,
+  type: 'image/heic',
+  uploadedBy: 'user-1',
+  folderId: null,
+  uploadedAt: new Date('2026-01-01T00:00:00Z'),
+  updatedAt: new Date('2026-01-01T00:00:00Z'),
+} satisfies WorkspaceFileRecord
+
+let container: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+  globalThis.IS_REACT_ACT_ENVIRONMENT = true
+  // ZoomablePreview measures its content through one; jsdom has no implementation.
+  globalThis.ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+})
+
+function render() {
+  act(() => root.render(<ImagePreview file={file} />))
+}
+
+describe('ImagePreview', () => {
+  it('requests the preview derivative rather than the stored bytes', () => {
+    render()
+
+    const src = container.querySelector('img')?.getAttribute('src') ?? ''
+    expect(src).toContain('preview=1')
+    expect(src).not.toContain('raw=1')
+  })
+
+  it('falls back to the unsupported state when the image fails to decode', () => {
+    render()
+
+    const img = container.querySelector('img')
+    expect(img).not.toBeNull()
+
+    act(() => {
+      img?.dispatchEvent(new Event('error'))
+    })
+
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.textContent).toContain('Preview not available')
+  })
+})
@@ -3,18 +3,25 @@
 import { memo, useState } from 'react'
 import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
 import { useFileContentSource } from '@/hooks/use-file-content-source'
-import { PREVIEW_LOADING_OVERLAY } from './preview-shared'
+import { PREVIEW_LOADING_OVERLAY, UnsupportedPreview } from './preview-shared'
 import { ZoomablePreview } from './zoomable-preview'
 
 export const ImagePreview = memo(function ImagePreview({ file }: { file: WorkspaceFileRecord }) {
   const source = useFileContentSource()
-  const [hasSettled, setHasSettled] = useState(false)
+  const [status, setStatus] = useState<'loading' | 'loaded' | 'error'>('loading')
   // Version the URL on updatedAt: overwrites keep the same storage key, so an unversioned
   // URL would resolve to a previously cached copy instead of the rewritten bytes.
+  // `preview` lets the server substitute a renderable derivative for a HEIC.
   const serveUrl = source.buildUrl(file.key, {
     version: Number(new Date(file.updatedAt)) || file.size,
+    preview: true,
   })
 
+  // Covers every way the bytes can turn out unrenderable — a derivative the server
+  // declined to build (too large, undecodable) and a corrupt or truncated image
+  // alike — rather than leaving a broken image in the viewer.
+  if (status === 'error') return <UnsupportedPreview file={file} />
+
   return (
     <div className='relative flex min-h-0 flex-1 flex-col'>
       <ZoomablePreview className='flex flex-1' contentClassName='h-full w-full'>
@@ -24,11 +31,11 @@ export const ImagePreview = memo(function ImagePreview({ file }: { file: Workspa
           className='max-h-full max-w-full select-none rounded-md object-contain'
           draggable={false}
           loading='eager'
-          onLoad={() => setHasSettled(true)}
-          onError={() => setHasSettled(true)}
+          onLoad={() => setStatus('loaded')}
+          onError={() => setStatus('error')}
         />
       </ZoomablePreview>
-      {!hasSettled && PREVIEW_LOADING_OVERLAY}
+      {status === 'loading' && PREVIEW_LOADING_OVERLAY}
     </div>
   )
 })