feat(file-viewer): preview media files inline instead of showing "binary file"

Natively renderable files (images, PDFs, audio, video) opened from the
Files tab previously fell back to the generic "binary file" placeholder.
Classify previewable extensions and render a new CodeEditorMediaPreview
component that streams the bytes through the existing authenticated content
endpoint and displays them with the right native element (<img>, <iframe>,
<video controls>, <audio controls>) via a blob: URL. Non-previewable
binaries (zip, exe, avi, mkv, fonts, ...) still show the binary message.
No backend or dependency changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/components/code-editor/hooks/useCodeEditorDocument.ts

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { api } from '../../../utils/api';
 import type { CodeEditorFile } from '../types/types';
 import { isBinaryFile } from '../utils/binaryFile';
+import { getPreviewKind } from '../utils/previewableFile';
 
 type UseCodeEditorDocumentParams = {
   file: CodeEditorFile;
@@ -23,6 +24,9 @@ export const useCodeEditorDocument = ({ file, projectPath }: UseCodeEditorDocume
   const [saveSuccess, setSaveSuccess] = useState(false);
   const [saveError, setSaveError] = useState<string | null>(null);
   const [isBinary, setIsBinary] = useState(false);
+  // Some binaries (images, PDFs, audio, video) can be rendered natively, so the
+  // editor shows an inline preview instead of the generic binary placeholder.
+  const previewKind = getPreviewKind(file.name);
   // `fileProjectId` is the DB primary key passed down from the editor sidebar;
   // the fallback to `projectPath` preserves older callers that didn't yet
   // propagate the identifier.
@@ -38,6 +42,13 @@ export const useCodeEditorDocument = ({ file, projectPath }: UseCodeEditorDocume
         setLoading(true);
         setIsBinary(false);
 
+        // Natively previewable media (image/pdf/audio/video) is rendered by
+        // CodeEditorMediaPreview, so there is nothing to read as text here.
+        if (getPreviewKind(file.name)) {
+          setLoading(false);
+          return;
+        }
+
         // Check if file is binary by extension
         if (isBinaryFile(file.name)) {
           setIsBinary(true);
@@ -134,6 +145,8 @@ export const useCodeEditorDocument = ({ file, projectPath }: UseCodeEditorDocume
     saveSuccess,
     saveError,
     isBinary,
+    previewKind,
+    fileProjectId,
     handleSave,
     handleDownload,
   };

src/components/code-editor/utils/previewableFile.ts

@@ -0,0 +1,31 @@
+// Some binary files can't be edited as text, but the browser can still render
+// them natively (images, PDFs, audio, video). For those we show an inline
+// preview instead of the generic "binary file" placeholder. Anything not listed
+// here (zip, exe, avi, mkv, fonts, ...) falls through to the binary message.
+
+export type PreviewKind = 'image' | 'pdf' | 'video' | 'audio';
+
+// Formats browsers can decode in <img>.
+const IMAGE_EXTENSIONS = new Set([
+  'png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'ico', 'bmp', 'avif', 'apng',
+]);
+
+const PDF_EXTENSIONS = new Set(['pdf']);
+
+// Container/codec combos broadly playable in <video>. Intentionally excludes
+// formats browsers generally can't play (avi, mkv, flv, wmv).
+const VIDEO_EXTENSIONS = new Set(['mp4', 'webm', 'ogv', 'mov', 'm4v']);
+
+// Formats broadly playable in <audio>.
+const AUDIO_EXTENSIONS = new Set([
+  'mp3', 'wav', 'm4a', 'aac', 'flac', 'opus', 'oga', 'ogg', 'weba',
+]);
+
+export const getPreviewKind = (filename: string): PreviewKind | null => {
+  const ext = filename.split('.').pop()?.toLowerCase() ?? '';
+  if (IMAGE_EXTENSIONS.has(ext)) return 'image';
+  if (PDF_EXTENSIONS.has(ext)) return 'pdf';
+  if (VIDEO_EXTENSIONS.has(ext)) return 'video';
+  if (AUDIO_EXTENSIONS.has(ext)) return 'audio';
+  return null;
+};

src/components/code-editor/view/CodeEditor.tsx

@@ -16,6 +16,7 @@ import CodeEditorHeader from './subcomponents/CodeEditorHeader';
 import CodeEditorLoadingState from './subcomponents/CodeEditorLoadingState';
 import CodeEditorSurface from './subcomponents/CodeEditorSurface';
 import CodeEditorBinaryFile from './subcomponents/CodeEditorBinaryFile';
+import CodeEditorMediaPreview from './subcomponents/CodeEditorMediaPreview';
 
 type CodeEditorProps = {
   file: CodeEditorFile;
@@ -58,6 +59,8 @@ export default function CodeEditor({
     saveSuccess,
     saveError,
     isBinary,
+    previewKind,
+    fileProjectId,
     handleSave,
     handleDownload,
   } = useCodeEditorDocument({
@@ -162,6 +165,30 @@ export default function CodeEditor({
     );
   }
 
+  // Natively previewable media (image/pdf/audio/video) is rendered inline
+  // instead of showing the generic "cannot be displayed" placeholder.
+  if (previewKind) {
+    return (
+      <CodeEditorMediaPreview
+        file={file}
+        kind={previewKind}
+        projectId={fileProjectId}
+        isSidebar={isSidebar}
+        isFullscreen={isFullscreen}
+        onClose={onClose}
+        onToggleFullscreen={() => setIsFullscreen((previous) => !previous)}
+        labels={{
+          loading: t('filePreview.loading', 'Loading preview...'),
+          error: t('filePreview.error', 'Unable to display this file.'),
+          openInNewTab: t('filePreview.openInNewTab', 'Open in new tab'),
+          fullscreen: t('actions.fullscreen', 'Fullscreen'),
+          exitFullscreen: t('actions.exitFullscreen', 'Exit fullscreen'),
+          close: t('actions.close', 'Close'),
+        }}
+      />
+    );
+  }
+
   // Binary file display
   if (isBinary) {
     return (

src/components/code-editor/view/subcomponents/CodeEditorMediaPreview.tsx

@@ -0,0 +1,230 @@
+import { useEffect, useState } from 'react';
+import { authenticatedFetch } from '../../../../utils/api';
+import type { CodeEditorFile } from '../../types/types';
+import type { PreviewKind } from '../../utils/previewableFile';
+
+type CodeEditorMediaPreviewProps = {
+  file: CodeEditorFile;
+  kind: PreviewKind;
+  // DB projectId used to build the raw-content URL; falls back to projectPath
+  // for older callers, mirroring useCodeEditorDocument.
+  projectId?: string;
+  isSidebar: boolean;
+  isFullscreen: boolean;
+  onClose: () => void;
+  onToggleFullscreen: () => void;
+  labels: {
+    loading: string;
+    error: string;
+    openInNewTab: string;
+    fullscreen: string;
+    exitFullscreen: string;
+    close: string;
+  };
+};
+
+// MIME type forced onto the blob per kind so the browser picks the right viewer
+// even when the server response was generic (e.g. application/octet-stream).
+const FALLBACK_MIME: Record<PreviewKind, string> = {
+  image: 'application/octet-stream',
+  pdf: 'application/pdf',
+  video: 'video/mp4',
+  audio: 'audio/mpeg',
+};
+
+export default function CodeEditorMediaPreview({
+  file,
+  kind,
+  projectId,
+  isSidebar,
+  isFullscreen,
+  onClose,
+  onToggleFullscreen,
+  labels,
+}: CodeEditorMediaPreviewProps) {
+  const [url, setUrl] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (!projectId) {
+      setError(labels.error);
+      setLoading(false);
+      return;
+    }
+
+    let objectUrl: string | null = null;
+    const controller = new AbortController();
+
+    const loadMedia = async () => {
+      try {
+        setLoading(true);
+        setError(null);
+        setUrl(null);
+
+        // The content endpoint requires the auth header, so we fetch the bytes
+        // ourselves and hand the media element a blob URL instead of a bare src.
+        // Fetching a blob (rather than streaming) also lets <video>/<audio> seek.
+        const contentUrl = `/api/projects/${projectId}/files/content?path=${encodeURIComponent(file.path)}`;
+        const response = await authenticatedFetch(contentUrl, { signal: controller.signal });
+
+        if (!response.ok) {
+          throw new Error(`Request failed with status ${response.status}`);
+        }
+
+        const blob = await response.blob();
+        const typed = blob.type ? blob : new Blob([blob], { type: FALLBACK_MIME[kind] });
+        objectUrl = URL.createObjectURL(typed);
+        setUrl(objectUrl);
+      } catch (loadError: unknown) {
+        if (loadError instanceof Error && loadError.name === 'AbortError') {
+          return;
+        }
+        console.error('Error loading preview:', loadError);
+        setError(labels.error);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadMedia();
+
+    return () => {
+      controller.abort();
+      if (objectUrl) {
+        URL.revokeObjectURL(objectUrl);
+      }
+    };
+  }, [file.path, projectId, kind, labels.error]);
+
+  const renderMedia = () => {
+    if (!url) return null;
+    switch (kind) {
+      case 'image':
+        return (
+          <img
+            src={url}
+            alt={file.name}
+            className="max-h-full max-w-full object-contain"
+          />
+        );
+      case 'pdf':
+        return <iframe src={url} title={file.name} className="h-full w-full border-0 bg-white" />;
+      case 'video':
+        return (
+          <video src={url} controls className="max-h-full max-w-full" autoPlay={false}>
+            {labels.error}
+          </video>
+        );
+      case 'audio':
+        return (
+          <div className="flex w-full max-w-xl flex-col items-center gap-4 px-6">
+            <p className="max-w-full truncate text-sm text-muted-foreground">{file.name}</p>
+            <audio src={url} controls className="w-full">
+              {labels.error}
+            </audio>
+          </div>
+        );
+      default:
+        return null;
+    }
+  };
+
+  const previewBody = (
+    <div className="relative flex h-full w-full flex-col items-center justify-center bg-muted/30 p-2">
+      {loading && (
+        <div className="text-sm text-muted-foreground">{labels.loading}</div>
+      )}
+
+      {!loading && url && renderMedia()}
+
+      {!loading && !url && (
+        <div className="flex flex-col items-center gap-3 p-8 text-center text-muted-foreground">
+          <p className="text-sm">{error || labels.error}</p>
+          <p className="break-all text-xs">{file.path}</p>
+        </div>
+      )}
+    </div>
+  );
+
+  const headerActions = (
+    <div className="flex shrink-0 items-center gap-0.5">
+      {url && (
+        <a
+          href={url}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="flex items-center justify-center rounded-md p-1.5 text-gray-600 hover:bg-gray-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-gray-800 dark:hover:text-white"
+          title={labels.openInNewTab}
+        >
+          <svg className="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
+          </svg>
+        </a>
+      )}
+      {!isSidebar && (
+        <button
+          type="button"
+          onClick={onToggleFullscreen}
+          className="flex items-center justify-center rounded-md p-1.5 text-gray-600 hover:bg-gray-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-gray-800 dark:hover:text-white"
+          title={isFullscreen ? labels.exitFullscreen : labels.fullscreen}
+        >
+          {isFullscreen ? (
+            <svg className="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 9V4.5M9 9H4.5M9 9L3.5 3.5M9 15v4.5M9 15H4.5M9 15l-5.5 5.5M15 9h4.5M15 9V4.5M15 9l5.5-5.5M15 15h4.5M15 15v4.5m0-4.5l5.5 5.5" />
+            </svg>
+          ) : (
+            <svg className="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4" />
+            </svg>
+          )}
+        </button>
+      )}
+      <button
+        type="button"
+        onClick={onClose}
+        className="flex items-center justify-center rounded-md p-1.5 text-gray-600 hover:bg-gray-100 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-gray-800 dark:hover:text-white"
+        title={labels.close}
+      >
+        <svg className="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+        </svg>
+      </button>
+    </div>
+  );
+
+  const header = (
+    <div className="flex flex-shrink-0 items-center justify-between border-b border-border px-3 py-1.5">
+      <div className="flex min-w-0 flex-1 items-center gap-2">
+        <h3 className="truncate text-sm font-medium text-gray-900 dark:text-white">{file.name}</h3>
+      </div>
+      {headerActions}
+    </div>
+  );
+
+  if (isSidebar) {
+    return (
+      <div className="flex h-full w-full flex-col bg-background">
+        {header}
+        {previewBody}
+      </div>
+    );
+  }
+
+  const containerClassName = isFullscreen
+    ? 'fixed inset-0 z-[9999] bg-background flex flex-col'
+    : 'fixed inset-0 z-[9999] md:bg-black/50 md:flex md:items-center md:justify-center md:p-4';
+
+  const innerClassName = isFullscreen
+    ? 'bg-background flex flex-col w-full h-full'
+    : 'bg-background shadow-2xl flex flex-col w-full h-full md:rounded-lg md:shadow-2xl md:w-full md:max-w-6xl md:h-[80vh] md:max-h-[80vh]';
+
+  return (
+    <div className={containerClassName}>
+      <div className={innerClassName}>
+        {header}
+        {previewBody}
+      </div>
+    </div>
+  );
+}

src/i18n/locales/en/codeEditor.json

@@ -32,5 +32,10 @@
   "binaryFile": {
     "title": "Binary File",
     "message": "The file \"{{fileName}}\" cannot be displayed in the text editor because it is a binary file."
+  },
+  "filePreview": {
+    "loading": "Loading preview...",
+    "error": "Unable to display this file.",
+    "openInNewTab": "Open in new tab"
   }
 }