File viewer: render images and PDFs inline

The viewer now shows images and PDFs as themselves instead of the binary-warning banner over lossy UTF-8 bytes. The mode picker offers the concrete detected kind (Image / PDF / Text) with no umbrella term, and "View as text" still drops to the raw byte view for any file.

How it works (macOS, no Rust image decoder, WKWebView decodes natively):
- `viewer_open` classifies the file by magic bytes (`classify_viewer_content`): raster (JPEG/PNG/GIF/WebP/BMP/TIFF), HEIC, conservative SVG, and PDF, local files only. A media open skips the text backend entirely (a `Media` no-op backend), mints a token, and returns `kind` + `mediaToken` + best-effort image dimensions.
- Bytes reach the webview through a new token-guarded `cmdr-media://` async URI scheme, not the asset protocol. The URL carries a 128-bit CSPRNG token, never a path, so a hostile file's content can't name an arbitrary file (unknown token → 404). The handler serves `Content-Type` from magic bytes (never the extension), honors `Range` (206 + inclusive `Content-Range`, 416), and runs its own `spawn_blocking` + timeout → 504 off the IPC thread. The token is dropped at the single `close_session` choke point both teardown paths funnel through.
- Frontend renders `<img>` (fit/zoom/pan, transparency checkerboard, EXIF-upright, loading/error states) and `<embed>` for PDF; every text-only effect and control is data-gated on the backend `kind`. The binary-warning banner is suppressed for rendered media by that same `kind`, so unrendered formats (RAW, AVIF, ICO, Office docs) still warn.

CSP adds the `cmdr-media:` scheme to `img-src` + `object-src` (verified live by the Playwright spec). Covered by Rust unit tests (classifier matrix, range math, token 404), Vitest, and two Playwright E2E specs rendering a real image and PDF under CSP.

Plan and two Opus review rounds: docs/specs/viewer-media-plan.md.

Author: vdavid

apps/desktop/src-tauri/src/commands/file_viewer.rs

@@ -38,6 +38,23 @@ pub async fn viewer_open(path: String, window_label: String) -> Result<ViewerOpe
     .await
 }
 
+/// Opens a fresh, full **text** session for `path`, ignoring media classification.
+///
+/// Backs the viewer's "View as text" override: a media (Image/PDF) session isn't
+/// upgraded in place; the FE calls this, swaps to the returned text session, and closes
+/// the old one. Re-registers the window -> session link so the window-destroyed handler
+/// frees the new session.
+#[tauri::command]
+#[specta::specta]
+pub async fn viewer_open_as_text(path: String, window_label: String) -> Result<ViewerOpenResult, IpcError> {
+    blocking_result_with_timeout(VIEWER_TIMEOUT, move || {
+        let result = file_viewer::open_session_as_text(&path).map_err(|e| e.to_string())?;
+        file_viewer::register_window_session(&window_label, &result.session_id);
+        Ok(result)
+    })
+    .await
+}
+
 /// Fetches a range of lines from a viewer session.
 ///
 /// # Arguments

apps/desktop/src-tauri/src/file_system/volume/manager.rs

@@ -129,6 +129,19 @@ impl VolumeManager {
             .unwrap_or_default()
     }
 
+    /// Returns all registered volumes as (id, handle) pairs. Unlike [`list_volumes`]
+    /// (which returns display names), this hands back the `Volume` handles so callers
+    /// can inspect capabilities (`root`, `supports_local_fs_access`,
+    /// `smb_connection_state`). Used by the file viewer's locality check.
+    ///
+    /// [`list_volumes`]: Self::list_volumes
+    pub fn list_volumes_with_handles(&self) -> Vec<(String, Arc<dyn Volume>)> {
+        self.volumes
+            .read()
+            .map(|volumes| volumes.iter().map(|(id, vol)| (id.clone(), vol.clone())).collect())
+            .unwrap_or_default()
+    }
+
     /// Returns the number of registered volumes.
     pub fn count(&self) -> usize {
         self.volumes.read().map(|v| v.len()).unwrap_or(0)

apps/desktop/src-tauri/src/file_viewer/CLAUDE.md

@@ -16,6 +16,9 @@ open-viewer helper and binary-warning classifier.
   `search_matcher.rs`: `Matcher`, huge-line chunking. `watcher.rs`: shared tail-mode watcher singleton.
 - Backend selection: `< 1MB` -> `FullLoad`; else `ByteSeek` (instant open) with a background `LineIndex` build that
   upgrades when ready. Full per-file roles, Tauri commands, and decision rationale are in [DETAILS.md](DETAILS.md).
+- Media (Image/PDF): `content_kind.rs` (pure `classify_viewer_content`), `media.rs` (the `cmdr-media://` token map),
+  `media_protocol.rs` (the async scheme handler), `media_backend.rs` (no-op `MediaBackend`). See [DETAILS.md](DETAILS.md)
+  § "Media rendering".
 
 ## Must-knows
 
@@ -35,7 +38,11 @@ open-viewer helper and binary-warning classifier.
   rebuilds replace the backend without blocking the `get_lines` read path. Each backend is immutable.
 - **`SESSIONS` is freed on BOTH close paths.** The titlebar-X path never fires `viewer_close`; it's covered by a
   `WindowEvent::Destroyed` branch in `lib.rs::on_window_event` for `viewer-*` labels (via the `WINDOW_TO_SESSION` map).
-  Without it, titlebar-closed viewers leak their session until app quit.
+  Without it, titlebar-closed viewers leak their session until app quit. The `cmdr-media://` token is dropped at this
+  same choke point (`media::drop_token`); don't drop it elsewhere, or a closed viewer leaks a live token mapping a path.
+  The scheme handler serves `Content-Type` from stored magic bytes (never the extension), does its OWN
+  `spawn_blocking` + timeout (504, not `blocking_with_timeout`), and 404s an unknown token. See
+  [DETAILS.md](DETAILS.md) § "Media rendering".
 - **`search_cancel` must not null `session.search`**: the cancel flag is what the search thread writes `Cancelled` into;
   nulling first lands the write in a dropped state and `search_poll` returns `Idle`. See [DETAILS.md](DETAILS.md).
 - **`SearchMatch.column` / `.length` are UTF-16 code units** (match JS `String.substring()`), avoiding a class of

apps/desktop/src-tauri/src/file_viewer/DETAILS.md

@@ -30,6 +30,52 @@ Frontend counterpart: [`apps/desktop/src/routes/viewer/CLAUDE.md`](../../../src/
 - `*_test.rs`: unit tests for each backend: UTF-8 edge cases, search highlighting, checkpoint math, range reads,
   cancellation, encoding detection, UTF-16 newline scanning, encoding-switch rebuild + drain-and-swap
 
+## Media rendering (Image / PDF)
+
+The viewer renders images and PDFs inline instead of showing the binary warning. The backend half:
+
+- `content_kind.rs`: pure `classify_viewer_content(head, ext, is_local) -> ViewerContentKind { Text, Image, Pdf }`.
+  Magic bytes decide (JPEG/PNG/GIF/WebP/BMP/TIFF/HEIC/PDF); the extension is a tiebreaker only, and only for SVG (an
+  `.svg` ext AND an `<svg` root after BOM/prolog/comments/DOCTYPE). Non-local files always classify `Text` (v1 scopes
+  media to local POSIX volumes; MTP has no POSIX path, SMB can block). `media_mime(head, kind)` re-sniffs the magic to
+  pick the served `Content-Type`.
+- `media.rs`: the `cmdr-media://` capability-token registry. `mint_token(entry)` stores
+  `token -> { canonical_path, kind, mime }` (128-bit CSPRNG via `rand`, 32 hex chars) and returns the token;
+  `resolve_token` / `drop_token` round it out. `read_image_dimensions` reads header-only pixel dimensions best-effort
+  (the `image` crate; `None` for HEIC/SVG/errors).
+- `media_protocol.rs`: the async URI scheme handler. Pure helpers (`parse_token_from_uri`, `resolve_range`,
+  `build_response`) are unit-tested; `handle_request` is the thin Tauri shell. It resolves the token (unknown -> 404),
+  then runs its OWN `tauri::async_runtime::spawn_blocking` + `tokio::time::timeout` (expiry -> 504; deliberately NOT
+  `blocking_with_timeout`, which returns an `IpcError`, not an HTTP response). Honors `Range`: 206 with inclusive
+  `Content-Range`/`Accept-Ranges`, end clamped to `size-1`, 416 when unsatisfiable, 200 when no range. `Content-Type`
+  comes from the token's stored magic-byte MIME, never the extension. Registered once in the `lib.rs` builder chain via
+  `register_asynchronous_uri_scheme_protocol(media_protocol::SCHEME, ...)`, before any window exists (correct: `viewer-*`
+  windows are lazy and inherit the app-wide scheme).
+- `media_backend.rs`: `MediaBackend`, a no-op `FileViewerBackend` so a media session can fill the non-optional
+  `backend` field without a text backend. Every text-shaped call returns empty/zero.
+
+Open flow: `open_session` reads the head, classifies, and for a media kind calls `open_media_session`, which mints the
+token, reads dimensions best-effort (header-only, must not extend the open past the metadata read), installs a
+`MediaBackend`, and returns a `ViewerOpenResult` with `kind` + `media_token` + `media_dimensions` and empty text
+fields. Media sessions spawn no watcher and no LineIndex upgrade. `open_session_as_text` (behind the
+`viewer_open_as_text` IPC) forces the text path for the "View as text" override; it returns a fresh full text session
+the FE swaps to (no in-place upgrade).
+
+**Token lifetime == session lifetime.** `close_session` (the single choke point both teardown paths funnel through, the
+`viewer_close` IPC and the `WindowEvent::Destroyed` net via `close_session_for_window`) calls `media::drop_token`, so a
+closed-window viewer can't leave a live token mapping a real path. An unknown token is a 404, covering both
+never-existed and already-dropped.
+
+CSP: `tauri.conf.json` adds `cmdr-media:` to `img-src` and `object-src`. On macOS WKWebView a Tauri custom scheme
+surfaces as `cmdr-media://localhost/...`, so the CSP token is the scheme `cmdr-media:` (verified by `viewer-media.spec.ts`
+E2E rendering a real image + PDF under this CSP with no violation, on macOS 26.5.1 / WKWebView 25F80, 2026-06-14;
+resource origin can differ by Tauri version / platform, e.g. `http://cmdr-media.localhost` on Windows). Access is gated
+by the per-open token in the handler, not by CSP, so the app-wide allowance is acceptable.
+
+FDA: the handler `File::open`s a real path off an IPC-minted token, inheriting the viewer's existing assumption that a
+viewer only opens after the user picked the file (so FDA is already decided). This is NOT a new pre-gate read path
+(`fda_gate.rs`); a stray TCC denial reading bytes here is a real access failure, not a scheme bug.
+
 ## Backend selection logic
 
 ```rust

apps/desktop/src-tauri/src/file_viewer/content_kind.rs

@@ -0,0 +1,205 @@
+//! Content classification for the file viewer: decide whether a file should render
+//! as inline media (an image, a PDF) or fall back to the text pipeline.
+//!
+//! The decision is driven by **magic bytes**, never the extension (a `.jpg` that is
+//! really a PDF/HTML polyglot must never be handed to an `<embed>`/`<iframe>` that
+//! could execute it). The extension is a tiebreaker only, and the SVG case is the
+//! sole place where the extension is load-bearing (see [`classify_viewer_content`]).
+//!
+//! Only **local** files are eligible for media rendering in v1. MTP has no POSIX path
+//! to serve, and SMB paths can block; both stay on the text pipeline. The caller
+//! decides locality and passes it in as `is_local`.
+
+use serde::Serialize;
+
+/// What the viewer should render a file as. The frontend branches on this:
+/// `Image` -> `<img>`, `Pdf` -> `<embed>`, `Text` -> the line pipeline.
+///
+/// "Media" survives only as an internal code word (the `cmdr-media://` scheme and
+/// this enum); users never see it. Future kinds (Markdown, Html) slot in here.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, specta::Type)]
+#[serde(rename_all = "camelCase")]
+pub enum ViewerContentKind {
+    Text,
+    Image,
+    Pdf,
+}
+
+/// Number of head bytes the caller should read and pass to [`classify_viewer_content`].
+/// Enough to cover every magic-byte signature plus the conservative SVG sniff (which
+/// skips a BOM, an XML prolog, comments, and a DOCTYPE before the `<svg` root).
+pub const CLASSIFY_HEAD_LEN: usize = 1024;
+
+/// Classifies a file as [`ViewerContentKind`] from its head bytes, extension, and
+/// locality. Pure: no I/O.
+///
+/// - **Magic bytes decide** the kind (and, downstream, the served `Content-Type`):
+///   JPEG/PNG/GIF/WebP/BMP/TIFF/HEIC -> `Image`, `%PDF-` -> `Pdf`.
+/// - **SVG is the one extension-gated case**: classified `Image` only when `ext` is
+///   `svg` AND the first meaningful token (after a BOM, XML prolog, comments, and a
+///   DOCTYPE) is an `<svg` root. This avoids false-positiving an HTML file that merely
+///   embeds an inline `<svg>`.
+/// - **Non-local -> always `Text`.** v1 scopes media rendering to local files.
+pub fn classify_viewer_content(head: &[u8], ext: Option<&str>, is_local: bool) -> ViewerContentKind {
+    if !is_local {
+        return ViewerContentKind::Text;
+    }
+
+    if let Some(kind) = classify_by_magic(head) {
+        return kind;
+    }
+
+    // SVG is text-shaped, so it has no binary magic. Only treat it as an image when
+    // the extension claims SVG and the content actually opens with an `<svg` root.
+    if ext.is_some_and(|e| e.eq_ignore_ascii_case("svg")) && looks_like_svg_root(head) {
+        return ViewerContentKind::Image;
+    }
+
+    ViewerContentKind::Text
+}
+
+/// The MIME type to serve for a media kind, derived from the same magic bytes the
+/// classifier used. Returns `None` for `Text` (text never flows through the scheme).
+///
+/// For images the exact subtype matters for WKWebView decode hints, so we re-sniff
+/// the magic here rather than carry the subtype through the classifier. SVG has no
+/// magic, so it's the extension-driven fallback when no raster magic matches.
+pub fn media_mime(head: &[u8], kind: ViewerContentKind) -> Option<&'static str> {
+    match kind {
+        ViewerContentKind::Text => None,
+        ViewerContentKind::Pdf => Some("application/pdf"),
+        ViewerContentKind::Image => Some(image_mime(head)),
+    }
+}
+
+/// The image subtype for `head`, falling back to `image/svg+xml` when no raster
+/// magic matches (the classifier only ever reaches `Image` for raster magic or a
+/// confirmed SVG root, so the fallback is exactly the SVG case).
+fn image_mime(head: &[u8]) -> &'static str {
+    match classify_by_magic(head) {
+        Some(ViewerContentKind::Image) => raster_image_mime(head).unwrap_or("application/octet-stream"),
+        _ => "image/svg+xml",
+    }
+}
+
+/// Magic-byte classification for the closed set of formats WKWebView decodes natively.
+/// Returns `None` for anything without a recognized binary signature (text, SVG, etc.).
+fn classify_by_magic(head: &[u8]) -> Option<ViewerContentKind> {
+    if head.starts_with(b"%PDF-") {
+        return Some(ViewerContentKind::Pdf);
+    }
+    if raster_image_mime(head).is_some() {
+        return Some(ViewerContentKind::Image);
+    }
+    None
+}
+
+/// Returns the MIME type if `head` starts with a known raster image signature, else
+/// `None`. The single source of truth for "is this raster image magic?".
+fn raster_image_mime(head: &[u8]) -> Option<&'static str> {
+    // JPEG: FF D8 FF
+    if head.starts_with(&[0xFF, 0xD8, 0xFF]) {
+        return Some("image/jpeg");
+    }
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if head.starts_with(&[0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]) {
+        return Some("image/png");
+    }
+    // GIF: "GIF8" (covers GIF87a and GIF89a)
+    if head.starts_with(b"GIF8") {
+        return Some("image/gif");
+    }
+    // WebP: "RIFF" .... "WEBP"
+    if head.len() >= 12 && head.starts_with(b"RIFF") && &head[8..12] == b"WEBP" {
+        return Some("image/webp");
+    }
+    // BMP: "BM"
+    if head.starts_with(b"BM") {
+        return Some("image/bmp");
+    }
+    // TIFF: "II*\0" (little-endian) or "MM\0*" (big-endian)
+    if head.starts_with(&[0x49, 0x49, 0x2A, 0x00]) || head.starts_with(&[0x4D, 0x4D, 0x00, 0x2A]) {
+        return Some("image/tiff");
+    }
+    // HEIC: ISO-BMFF `ftyp` box at offset 4, with a HEIF/HEIC brand.
+    if is_heic(head) {
+        return Some("image/heic");
+    }
+    None
+}
+
+/// HEIC detection: an ISO base media file (`ftyp` box at offset 4) whose major brand
+/// is one of the HEIF/HEIC family. We check the major brand (bytes 8..12); the brand
+/// list mirrors what ImageIO treats as HEIC-family still images.
+fn is_heic(head: &[u8]) -> bool {
+    if head.len() < 12 || &head[4..8] != b"ftyp" {
+        return false;
+    }
+    matches!(
+        &head[8..12],
+        b"heic" | b"heix" | b"mif1" | b"msf1" | b"heim" | b"heis" | b"hevc" | b"hevx"
+    )
+}
+
+/// Conservative SVG sniff: returns true when the first meaningful token, after
+/// skipping a UTF-8 BOM, leading whitespace, an XML prolog (`<?xml ... ?>`), any
+/// number of comments (`<!-- ... -->`), and a DOCTYPE (`<!DOCTYPE ... >`), is an
+/// `<svg` element open tag.
+fn looks_like_svg_root(head: &[u8]) -> bool {
+    let mut rest = head;
+    // Strip a UTF-8 BOM if present.
+    if let Some(stripped) = rest.strip_prefix(&[0xEF, 0xBB, 0xBF]) {
+        rest = stripped;
+    }
+    loop {
+        rest = skip_ascii_whitespace(rest);
+        if rest.starts_with(b"<?") {
+            // XML prolog / processing instruction: skip to the closing "?>".
+            match find_subslice(rest, b"?>") {
+                Some(i) => rest = &rest[i + 2..],
+                None => return false,
+            }
+        } else if rest.starts_with(b"<!--") {
+            // Comment: skip to the closing "-->".
+            match find_subslice(&rest[4..], b"-->") {
+                Some(i) => rest = &rest[4 + i + 3..],
+                None => return false,
+            }
+        } else if rest.starts_with(b"<!") {
+            // DOCTYPE (or other declaration): skip to the next ">".
+            match find_subslice(rest, b">") {
+                Some(i) => rest = &rest[i + 1..],
+                None => return false,
+            }
+        } else {
+            break;
+        }
+    }
+    // The root element must be `<svg`, followed by whitespace, `>`, or `/`.
+    let Some(after) = rest.strip_prefix(b"<svg") else {
+        return false;
+    };
+    match after.first() {
+        None => true, // truncated head right after "<svg": accept (the head cap clipped it)
+        Some(b) => b.is_ascii_whitespace() || *b == b'>' || *b == b'/',
+    }
+}
+
+fn skip_ascii_whitespace(mut s: &[u8]) -> &[u8] {
+    while let Some((first, rest)) = s.split_first() {
+        if first.is_ascii_whitespace() {
+            s = rest;
+        } else {
+            break;
+        }
+    }
+    s
+}
+
+/// Returns the index of the first occurrence of `needle` in `haystack`, or `None`.
+fn find_subslice(haystack: &[u8], needle: &[u8]) -> Option<usize> {
+    if needle.is_empty() || haystack.len() < needle.len() {
+        return None;
+    }
+    haystack.windows(needle.len()).position(|w| w == needle)
+}