From ca564177fa5d5d8a6af49163c7ded2d6c86a6ec0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 24 Jan 2026 00:40:54 +0000
Subject: [PATCH 01/16] Feature: Add file viewer with search (F3)

Add a text file viewer that opens in a separate window when pressing F3.
Includes case-insensitive search with match highlighting, line numbers,
and keyboard navigation (Cmd+F to search, ESC to close).
---
 .../src-tauri/src/commands/file_system.rs     | 143 ++++++
 apps/desktop/src-tauri/src/lib.rs             |   1 +
 .../lib/file-explorer/DualPaneExplorer.svelte |  27 ++
 .../lib/file-explorer/FunctionKeyBar.svelte   |   5 +-
 .../lib/file-explorer/FunctionKeyBar.test.ts  |  22 +-
 .../src/lib/file-viewer/open-viewer.ts        |  22 +
 .../src/lib/file-viewer/viewer-search.test.ts |  86 ++++
 .../src/lib/file-viewer/viewer-search.ts      |  39 ++
 apps/desktop/src/lib/tauri-commands.ts        |  17 +
 apps/desktop/src/routes/+page.svelte          |   7 +
 apps/desktop/src/routes/viewer/+page.svelte   | 408 ++++++++++++++++++
 docs/features/file-viewer.md                  |  58 +++
 docs/specs/viewer-tasks.md                    |  19 +
 13 files changed, 846 insertions(+), 8 deletions(-)
 create mode 100644 apps/desktop/src/lib/file-viewer/open-viewer.ts
 create mode 100644 apps/desktop/src/lib/file-viewer/viewer-search.test.ts
 create mode 100644 apps/desktop/src/lib/file-viewer/viewer-search.ts
 create mode 100644 apps/desktop/src/routes/viewer/+page.svelte
 create mode 100644 docs/features/file-viewer.md
 create mode 100644 docs/specs/viewer-tasks.md

diff --git a/apps/desktop/src-tauri/src/commands/file_system.rs b/apps/desktop/src-tauri/src/commands/file_system.rs
index 61b96075..e2539d2c 100644
--- a/apps/desktop/src-tauri/src/commands/file_system.rs
+++ b/apps/desktop/src-tauri/src/commands/file_system.rs
@@ -561,6 +561,70 @@ pub fn start_selection_drag(
     Err("Drag operation is not yet supported on this platform".to_string())
 }
 
+// ============================================================================
+// File viewer
+// ============================================================================
+
+/// Result of reading a file's content for the viewer.
+#[derive(Debug, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FileContentResult {
+    /// The text content of the file (UTF-8 lossy decoded).
+    pub content: String,
+    /// Total number of lines.
+    pub line_count: usize,
+    /// File size in bytes.
+    pub size: u64,
+    /// The file name (last component of the path).
+    pub file_name: String,
+}
+
+/// Reads a file's content as text for the file viewer.
+///
+/// Returns the full file content as a UTF-8 string (lossy — invalid bytes become replacement chars).
+/// Not optimized for huge files; intended for reasonably-sized text files.
+///
+/// # Arguments
+/// * `path` - Absolute path to the file. Supports tilde expansion (~).
+#[tauri::command]
+pub fn read_file_content(path: String) -> Result<FileContentResult, String> {
+    let expanded = expand_tilde(&path);
+    let file_path = PathBuf::from(&expanded);
+
+    if !file_path.exists() {
+        return Err(format!("File not found: {}", path));
+    }
+    if file_path.is_dir() {
+        return Err("Cannot view a directory".to_string());
+    }
+
+    let metadata = std::fs::metadata(&file_path).map_err(|e| match e.kind() {
+        std::io::ErrorKind::PermissionDenied => format!("Permission denied: {}", path),
+        _ => format!("Cannot read file metadata: {}", e),
+    })?;
+
+    let size = metadata.len();
+    let bytes = std::fs::read(&file_path).map_err(|e| match e.kind() {
+        std::io::ErrorKind::PermissionDenied => format!("Permission denied: {}", path),
+        _ => format!("Failed to read file: {}", e),
+    })?;
+
+    let content = String::from_utf8_lossy(&bytes).into_owned();
+    let line_count = content.lines().count().max(1);
+
+    let file_name = file_path
+        .file_name()
+        .map(|n| n.to_string_lossy().into_owned())
+        .unwrap_or_else(|| path.clone());
+
+    Ok(FileContentResult {
+        content,
+        line_count,
+        size,
+        file_name,
+    })
+}
+
 /// Expands tilde (~) to the user's home directory.
 fn expand_tilde(path: &str) -> String {
     if (path.starts_with("~/") || path == "~")
@@ -660,4 +724,83 @@ mod tests {
         let result = create_directory("/nonexistent_path_12345".to_string(), "test".to_string());
         assert!(result.is_err());
     }
+
+    // ========================================================================
+    // read_file_content tests
+    // ========================================================================
+
+    #[test]
+    fn test_read_file_content_success() {
+        let tmp = create_test_dir("read_content_ok");
+        let file_path = tmp.join("hello.txt");
+        fs::write(&file_path, "line 1\nline 2\nline 3\n").unwrap();
+
+        let result = read_file_content(file_path.to_string_lossy().to_string());
+        assert!(result.is_ok());
+        let res = result.unwrap();
+        assert_eq!(res.file_name, "hello.txt");
+        assert_eq!(res.line_count, 3);
+        assert!(res.content.starts_with("line 1"));
+        assert_eq!(res.size, 21);
+        cleanup_test_dir(&tmp);
+    }
+
+    #[test]
+    fn test_read_file_content_empty_file() {
+        let tmp = create_test_dir("read_content_empty");
+        let file_path = tmp.join("empty.txt");
+        fs::write(&file_path, "").unwrap();
+
+        let result = read_file_content(file_path.to_string_lossy().to_string());
+        assert!(result.is_ok());
+        let res = result.unwrap();
+        assert_eq!(res.content, "");
+        assert_eq!(res.line_count, 1); // At least 1
+        assert_eq!(res.size, 0);
+        cleanup_test_dir(&tmp);
+    }
+
+    #[test]
+    fn test_read_file_content_not_found() {
+        let result = read_file_content("/nonexistent_file_12345.txt".to_string());
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("File not found"));
+    }
+
+    #[test]
+    fn test_read_file_content_directory() {
+        let tmp = create_test_dir("read_content_dir");
+        let result = read_file_content(tmp.to_string_lossy().to_string());
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Cannot view a directory"));
+        cleanup_test_dir(&tmp);
+    }
+
+    #[test]
+    fn test_read_file_content_binary() {
+        let tmp = create_test_dir("read_content_binary");
+        let file_path = tmp.join("binary.bin");
+        fs::write(&file_path, b"\x00\x01\x02\xff\xfe").unwrap();
+
+        let result = read_file_content(file_path.to_string_lossy().to_string());
+        assert!(result.is_ok());
+        // Binary content is lossy-decoded, should contain replacement characters
+        let res = result.unwrap();
+        assert!(res.content.contains('\u{FFFD}'));
+        cleanup_test_dir(&tmp);
+    }
+
+    #[test]
+    fn test_read_file_content_single_line_no_newline() {
+        let tmp = create_test_dir("read_content_single");
+        let file_path = tmp.join("single.txt");
+        fs::write(&file_path, "hello world").unwrap();
+
+        let result = read_file_content(file_path.to_string_lossy().to_string());
+        assert!(result.is_ok());
+        let res = result.unwrap();
+        assert_eq!(res.line_count, 1);
+        assert_eq!(res.content, "hello world");
+        cleanup_test_dir(&tmp);
+    }
 }
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 7b8e580a..c473f8d9 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -280,6 +280,7 @@ pub fn run() {
             commands::file_system::get_operation_status,
             commands::file_system::get_listing_stats,
             commands::file_system::start_selection_drag,
+            commands::file_system::read_file_content,
             commands::font_metrics::store_font_metrics,
             commands::font_metrics::has_font_metrics,
             commands::icons::get_icons,
diff --git a/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte b/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte
index 4f87291d..85e1b5df 100644
--- a/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte
+++ b/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte
@@ -48,6 +48,7 @@
         type NavigationHistory,
     } from './navigation-history'
     import { initNetworkDiscovery, cleanupNetworkDiscovery } from '$lib/network-store.svelte'
+    import { openFileViewer } from '$lib/file-viewer/open-viewer'
     import { getAppLogger } from '$lib/logger'
 
     const log = getAppLogger('fileExplorer')
@@ -539,6 +540,13 @@
             return
         }
 
+        // F3 - View file
+        if (e.key === 'F3') {
+            e.preventDefault()
+            void openViewerForCursor()
+            return
+        }
+
         // F5 - Copy dialog
         if (e.key === 'F5') {
             e.preventDefault()
@@ -921,6 +929,25 @@
         containerElement?.focus()
     }
 
+    /** Opens the file viewer for the file under the cursor. */
+    export async function openViewerForCursor() {
+        const paneRef = focusedPane === 'left' ? leftPaneRef : rightPaneRef
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        const listingId = paneRef?.getListingId?.() as string | undefined
+        if (!listingId) return
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        const cursorIndex = paneRef?.getCursorIndex?.() as number | undefined
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+        const hasParent = paneRef?.hasParentEntry?.() as boolean | undefined
+        const backendIndex = toBackendCursorIndex(cursorIndex ?? -1, hasParent ?? false)
+        if (backendIndex === null) return
+
+        const file = await getFileAt(listingId, backendIndex, showHiddenFiles)
+        if (!file || file.isDirectory || file.name === '..') return
+
+        void openFileViewer(file.path)
+    }
+
     /** Opens the copy dialog with the current selection info. */
     export async function openCopyDialog() {
         const isLeft = focusedPane === 'left'
diff --git a/apps/desktop/src/lib/file-explorer/FunctionKeyBar.svelte b/apps/desktop/src/lib/file-explorer/FunctionKeyBar.svelte
index 7e3a26e1..04a8925d 100644
--- a/apps/desktop/src/lib/file-explorer/FunctionKeyBar.svelte
+++ b/apps/desktop/src/lib/file-explorer/FunctionKeyBar.svelte
@@ -1,12 +1,13 @@
 <script lang="ts">
     interface Props {
         visible?: boolean
+        onView?: () => void
         onEdit?: () => void
         onCopy?: () => void
         onNewFolder?: () => void
     }
 
-    const { visible = true, onEdit, onCopy, onNewFolder }: Props = $props()
+    const { visible = true, onView, onEdit, onCopy, onNewFolder }: Props = $props()
 </script>
 
 {#if visible}
@@ -17,7 +18,7 @@
             e.preventDefault()
         }}
     >
-        <button disabled tabindex={-1} aria-label="View (F3) — not yet available">
+        <button onclick={onView} tabindex={-1} aria-label="View file (F3)">
             <kbd>F3</kbd><span>View</span>
         </button>
         <button onclick={onEdit} tabindex={-1} aria-label="Edit file (F4)">
diff --git a/apps/desktop/src/lib/file-explorer/FunctionKeyBar.test.ts b/apps/desktop/src/lib/file-explorer/FunctionKeyBar.test.ts
index bcc234d1..e9cdc401 100644
--- a/apps/desktop/src/lib/file-explorer/FunctionKeyBar.test.ts
+++ b/apps/desktop/src/lib/file-explorer/FunctionKeyBar.test.ts
@@ -18,31 +18,41 @@ describe('FunctionKeyBar', () => {
         expect(target.querySelector('.function-key-bar')).toBeNull()
     })
 
-    it('disables F3, F6, and F8 buttons', () => {
+    it('disables F6 and F8 buttons', () => {
         const target = document.createElement('div')
         mount(FunctionKeyBar, { target, props: { visible: true } })
 
         const buttons = target.querySelectorAll('button')
-        // F3 (index 0), F6 (index 3), F8 (index 5)
-        expect(buttons[0].disabled).toBe(true)
+        // F6 (index 3), F8 (index 5)
         expect(buttons[3].disabled).toBe(true)
         expect(buttons[5].disabled).toBe(true)
     })
 
-    it('enables F4, F5, and F7 buttons', () => {
+    it('enables F3, F4, F5, and F7 buttons', () => {
         const target = document.createElement('div')
         mount(FunctionKeyBar, {
             target,
-            props: { visible: true, onEdit: () => {}, onCopy: () => {}, onNewFolder: () => {} },
+            props: { visible: true, onView: () => {}, onEdit: () => {}, onCopy: () => {}, onNewFolder: () => {} },
         })
 
         const buttons = target.querySelectorAll('button')
-        // F4 (index 1), F5 (index 2), F7 (index 4)
+        // F3 (index 0), F4 (index 1), F5 (index 2), F7 (index 4)
+        expect(buttons[0].disabled).toBe(false)
         expect(buttons[1].disabled).toBe(false)
         expect(buttons[2].disabled).toBe(false)
         expect(buttons[4].disabled).toBe(false)
     })
 
+    it('calls onView when F3 button is clicked', () => {
+        const onView = vi.fn()
+        const target = document.createElement('div')
+        mount(FunctionKeyBar, { target, props: { visible: true, onView } })
+
+        const buttons = target.querySelectorAll('button')
+        buttons[0].click()
+        expect(onView).toHaveBeenCalledOnce()
+    })
+
     it('calls onEdit when F4 button is clicked', () => {
         const onEdit = vi.fn()
         const target = document.createElement('div')
diff --git a/apps/desktop/src/lib/file-viewer/open-viewer.ts b/apps/desktop/src/lib/file-viewer/open-viewer.ts
new file mode 100644
index 00000000..b41f436a
--- /dev/null
+++ b/apps/desktop/src/lib/file-viewer/open-viewer.ts
@@ -0,0 +1,22 @@
+/** Opens a file viewer window for the given file path. Multiple viewers can be open at once. */
+export async function openFileViewer(filePath: string): Promise<void> {
+    const { WebviewWindow } = await import('@tauri-apps/api/webviewWindow')
+
+    // Use a unique label per viewer instance (timestamp-based)
+    const label = `viewer-${Date.now()}`
+    const encodedPath = encodeURIComponent(filePath)
+
+    new WebviewWindow(label, {
+        url: `/viewer?path=${encodedPath}`,
+        title: filePath.split('/').pop() ?? 'Viewer',
+        width: 800,
+        height: 600,
+        minWidth: 400,
+        minHeight: 300,
+        resizable: true,
+        minimizable: true,
+        maximizable: true,
+        closable: true,
+        focus: true,
+    })
+}
diff --git a/apps/desktop/src/lib/file-viewer/viewer-search.test.ts b/apps/desktop/src/lib/file-viewer/viewer-search.test.ts
new file mode 100644
index 00000000..9dd26c93
--- /dev/null
+++ b/apps/desktop/src/lib/file-viewer/viewer-search.test.ts
@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest'
+import { findMatches, nextMatchIndex, prevMatchIndex } from './viewer-search'
+
+describe('findMatches', () => {
+    it('returns empty array for empty query', () => {
+        expect(findMatches(['hello world'], '')).toEqual([])
+    })
+
+    it('finds a single match on a single line', () => {
+        const matches = findMatches(['hello world'], 'world')
+        expect(matches).toEqual([{ line: 0, start: 6, length: 5 }])
+    })
+
+    it('finds multiple matches on the same line', () => {
+        const matches = findMatches(['foo bar foo baz foo'], 'foo')
+        expect(matches).toHaveLength(3)
+        expect(matches[0]).toEqual({ line: 0, start: 0, length: 3 })
+        expect(matches[1]).toEqual({ line: 0, start: 8, length: 3 })
+        expect(matches[2]).toEqual({ line: 0, start: 16, length: 3 })
+    })
+
+    it('finds matches across multiple lines', () => {
+        const matches = findMatches(['first line', 'second test', 'third line'], 'line')
+        expect(matches).toHaveLength(2)
+        expect(matches[0]).toEqual({ line: 0, start: 6, length: 4 })
+        expect(matches[1]).toEqual({ line: 2, start: 6, length: 4 })
+    })
+
+    it('is case-insensitive', () => {
+        const matches = findMatches(['Hello WORLD'], 'hello')
+        expect(matches).toHaveLength(1)
+        expect(matches[0]).toEqual({ line: 0, start: 0, length: 5 })
+    })
+
+    it('returns empty for no matches', () => {
+        expect(findMatches(['hello world'], 'xyz')).toEqual([])
+    })
+
+    it('handles empty lines', () => {
+        const matches = findMatches(['', 'hello', ''], 'hello')
+        expect(matches).toEqual([{ line: 1, start: 0, length: 5 }])
+    })
+
+    it('handles overlapping potential matches (non-overlapping search)', () => {
+        // "aaa" in "aaaa" should find at 0 and 1 (overlapping start positions)
+        const matches = findMatches(['aaaa'], 'aaa')
+        expect(matches).toHaveLength(2)
+        expect(matches[0]).toEqual({ line: 0, start: 0, length: 3 })
+        expect(matches[1]).toEqual({ line: 0, start: 1, length: 3 })
+    })
+
+    it('handles special regex characters in query', () => {
+        const matches = findMatches(['price is $10.00'], '$10')
+        expect(matches).toEqual([{ line: 0, start: 9, length: 3 }])
+    })
+})
+
+describe('nextMatchIndex', () => {
+    it('returns -1 for zero total', () => {
+        expect(nextMatchIndex(0, 0)).toBe(-1)
+    })
+
+    it('advances to the next index', () => {
+        expect(nextMatchIndex(0, 5)).toBe(1)
+        expect(nextMatchIndex(3, 5)).toBe(4)
+    })
+
+    it('wraps around at the end', () => {
+        expect(nextMatchIndex(4, 5)).toBe(0)
+    })
+})
+
+describe('prevMatchIndex', () => {
+    it('returns -1 for zero total', () => {
+        expect(prevMatchIndex(0, 0)).toBe(-1)
+    })
+
+    it('moves to the previous index', () => {
+        expect(prevMatchIndex(3, 5)).toBe(2)
+        expect(prevMatchIndex(1, 5)).toBe(0)
+    })
+
+    it('wraps around at the beginning', () => {
+        expect(prevMatchIndex(0, 5)).toBe(4)
+    })
+})
diff --git a/apps/desktop/src/lib/file-viewer/viewer-search.ts b/apps/desktop/src/lib/file-viewer/viewer-search.ts
new file mode 100644
index 00000000..7316e655
--- /dev/null
+++ b/apps/desktop/src/lib/file-viewer/viewer-search.ts
@@ -0,0 +1,39 @@
+/** A single search match location. */
+export interface SearchMatch {
+    /** 0-based line index */
+    line: number
+    /** 0-based character offset within the line */
+    start: number
+    /** Length of the match in characters */
+    length: number
+}
+
+/** Finds all occurrences of a query in the given lines (case-insensitive). */
+export function findMatches(lines: string[], query: string): SearchMatch[] {
+    if (!query) return []
+    const lowerQuery = query.toLowerCase()
+    const matches: SearchMatch[] = []
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const lowerLine = lines[lineIdx].toLowerCase()
+        let offset = 0
+        while (offset < lowerLine.length) {
+            const idx = lowerLine.indexOf(lowerQuery, offset)
+            if (idx === -1) break
+            matches.push({ line: lineIdx, start: idx, length: query.length })
+            offset = idx + 1
+        }
+    }
+    return matches
+}
+
+/** Navigates to the next match index, wrapping around. */
+export function nextMatchIndex(current: number, total: number): number {
+    if (total === 0) return -1
+    return (current + 1) % total
+}
+
+/** Navigates to the previous match index, wrapping around. */
+export function prevMatchIndex(current: number, total: number): number {
+    if (total === 0) return -1
+    return (current - 1 + total) % total
+}
diff --git a/apps/desktop/src/lib/tauri-commands.ts b/apps/desktop/src/lib/tauri-commands.ts
index 31b975b4..416a2812 100644
--- a/apps/desktop/src/lib/tauri-commands.ts
+++ b/apps/desktop/src/lib/tauri-commands.ts
@@ -283,6 +283,23 @@ export async function createDirectory(parentPath: string, name: string): Promise
     return invoke<string>('create_directory', { parentPath, name })
 }
 
+// ============================================================================
+// File viewer
+// ============================================================================
+
+/** Result of reading a file's content for the viewer. */
+export interface FileContentResult {
+    content: string
+    lineCount: number
+    size: number
+    fileName: string
+}
+
+/** Reads a file's text content for the file viewer. Binary bytes are lossy-decoded. */
+export async function readFileContent(path: string): Promise<FileContentResult> {
+    return invoke<FileContentResult>('read_file_content', { path })
+}
+
 /**
  * Opens a file with the system's default application.
  * @param path - Path to the file to open.
diff --git a/apps/desktop/src/routes/+page.svelte b/apps/desktop/src/routes/+page.svelte
index 24aa5d03..4cee3179 100644
--- a/apps/desktop/src/routes/+page.svelte
+++ b/apps/desktop/src/routes/+page.svelte
@@ -45,6 +45,7 @@
         handleSelectionAction: (action: string, startIndex?: number, endIndex?: number) => void
         openCopyDialog: () => Promise<void>
         openNewFolderDialog: () => Promise<void>
+        openViewerForCursor: () => Promise<void>
     }
 
     let showFdaPrompt = $state(false)
@@ -373,6 +374,11 @@
         explorerRef?.refocus()
     }
 
+    function handleFnView() {
+        void explorerRef?.openViewerForCursor()
+        explorerRef?.refocus()
+    }
+
     async function handleFnEdit() {
         const entry = explorerRef?.getFileAndPathUnderCursor()
         if (entry) {
@@ -652,6 +658,7 @@
     {#if showApp}
         <FunctionKeyBar
             visible={showFunctionKeyBar}
+            onView={handleFnView}
             onEdit={() => void handleFnEdit()}
             onCopy={handleFnCopy}
             onNewFolder={handleFnNewFolder}
diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
new file mode 100644
index 00000000..7d716901
--- /dev/null
+++ b/apps/desktop/src/routes/viewer/+page.svelte
@@ -0,0 +1,408 @@
+<script lang="ts" module>
+    function formatSize(bytes: number): string {
+        if (bytes < 1024) return `${String(bytes)} B`
+        if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+        if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+        return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
+    }
+</script>
+
+<script lang="ts">
+    import { onMount, tick } from 'svelte'
+    import { findMatches, nextMatchIndex, prevMatchIndex, type SearchMatch } from '$lib/file-viewer/viewer-search'
+
+    let content = $state('')
+    let lines = $state<string[]>([])
+    let fileName = $state('')
+    let lineCount = $state(0)
+    let fileSize = $state(0)
+    let error = $state('')
+    let loading = $state(true)
+
+    // Search state
+    let searchVisible = $state(false)
+    let searchQuery = $state('')
+    let matches = $state<SearchMatch[]>([])
+    let currentMatchIndex = $state(-1)
+    let searchInputRef: HTMLInputElement | undefined = $state()
+
+    // Viewer container ref for scrolling
+    let viewerRef: HTMLDivElement | undefined = $state()
+
+    // Compute line number gutter width based on total lines
+    const gutterWidth = $derived(String(lineCount).length)
+
+    // Update matches when query or content changes
+    $effect(() => {
+        if (searchQuery && lines.length > 0) {
+            matches = findMatches(lines, searchQuery)
+            currentMatchIndex = matches.length > 0 ? 0 : -1
+        } else {
+            matches = []
+            currentMatchIndex = -1
+        }
+    })
+
+    // Scroll to current match when it changes
+    $effect(() => {
+        if (currentMatchIndex >= 0 && matches[currentMatchIndex]) {
+            scrollToMatch(matches[currentMatchIndex])
+        }
+    })
+
+    function scrollToMatch(match: SearchMatch) {
+        if (!viewerRef) return
+        const lineEl = viewerRef.querySelector(`[data-line="${String(match.line)}"]`)
+        if (lineEl) {
+            lineEl.scrollIntoView({ block: 'center', behavior: 'smooth' })
+        }
+    }
+
+    function openSearch() {
+        searchVisible = true
+        void tick().then(() => {
+            searchInputRef?.focus()
+            searchInputRef?.select()
+        })
+    }
+
+    function closeSearch() {
+        searchVisible = false
+        searchQuery = ''
+        matches = []
+        currentMatchIndex = -1
+    }
+
+    function findNext() {
+        if (matches.length === 0) return
+        currentMatchIndex = nextMatchIndex(currentMatchIndex, matches.length)
+    }
+
+    function findPrev() {
+        if (matches.length === 0) return
+        currentMatchIndex = prevMatchIndex(currentMatchIndex, matches.length)
+    }
+
+    async function closeWindow() {
+        try {
+            const { getCurrentWindow } = await import('@tauri-apps/api/window')
+            await getCurrentWindow().close()
+        } catch {
+            // Not in Tauri environment
+        }
+    }
+
+    function handleKeyDown(e: KeyboardEvent) {
+        // Cmd+F or Ctrl+F: open search
+        if ((e.metaKey || e.ctrlKey) && e.key === 'f') {
+            e.preventDefault()
+            openSearch()
+            return
+        }
+
+        // Escape: close search first, then close window
+        if (e.key === 'Escape') {
+            e.preventDefault()
+            if (searchVisible) {
+                closeSearch()
+            } else {
+                void closeWindow()
+            }
+            return
+        }
+
+        // Enter in search: find next (Shift+Enter: find previous)
+        if (e.key === 'Enter' && searchVisible) {
+            e.preventDefault()
+            if (e.shiftKey) {
+                findPrev()
+            } else {
+                findNext()
+            }
+        }
+    }
+
+    /** Renders a line with search highlights. Returns an array of segments. */
+    function getHighlightedSegments(lineIdx: number, lineText: string) {
+        const lineMatches = matches.filter((m) => m.line === lineIdx)
+        if (lineMatches.length === 0) {
+            return [{ text: lineText, highlight: false, active: false }]
+        }
+
+        const segments: Array<{ text: string; highlight: boolean; active: boolean }> = []
+        let pos = 0
+        for (const m of lineMatches) {
+            if (m.start > pos) {
+                segments.push({ text: lineText.slice(pos, m.start), highlight: false, active: false })
+            }
+            const isActive = matches.indexOf(m) === currentMatchIndex
+            segments.push({ text: lineText.slice(m.start, m.start + m.length), highlight: true, active: isActive })
+            pos = m.start + m.length
+        }
+        if (pos < lineText.length) {
+            segments.push({ text: lineText.slice(pos), highlight: false, active: false })
+        }
+        return segments
+    }
+
+    onMount(async () => {
+        // Hide the loading screen
+        const loadingScreen = document.getElementById('loading-screen')
+        if (loadingScreen) {
+            loadingScreen.style.display = 'none'
+        }
+
+        // Get file path from URL query parameter
+        const params = new URLSearchParams(window.location.search)
+        const filePath = params.get('path')
+
+        if (!filePath) {
+            error = 'No file path specified'
+            loading = false
+            return
+        }
+
+        try {
+            const { readFileContent } = await import('$lib/tauri-commands')
+            const result = await readFileContent(filePath)
+            content = result.content
+            lines = content.split('\n')
+            fileName = result.fileName
+            lineCount = result.lineCount
+            fileSize = result.size
+
+            // Set window title
+            try {
+                const { getCurrentWindow } = await import('@tauri-apps/api/window')
+                await getCurrentWindow().setTitle(`${result.fileName} — Viewer`)
+            } catch {
+                // Not in Tauri environment
+            }
+        } catch (e) {
+            error = typeof e === 'string' ? e : 'Failed to read file'
+        } finally {
+            loading = false
+        }
+    })
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="viewer-container" onkeydown={handleKeyDown} tabindex={-1} bind:this={viewerRef}>
+    {#if searchVisible}
+        <div class="search-bar" role="search">
+            <input
+                bind:this={searchInputRef}
+                bind:value={searchQuery}
+                type="text"
+                placeholder="Find in file..."
+                aria-label="Search text"
+                class="search-input"
+            />
+            <span class="match-count" aria-live="polite">
+                {#if matches.length > 0}
+                    {currentMatchIndex + 1} of {matches.length}
+                {:else if searchQuery}
+                    No matches
+                {/if}
+            </span>
+            <button
+                onclick={findPrev}
+                disabled={matches.length === 0}
+                aria-label="Previous match"
+                title="Previous match (Shift+Enter)">&#x25B2;</button
+            >
+            <button
+                onclick={findNext}
+                disabled={matches.length === 0}
+                aria-label="Next match"
+                title="Next match (Enter)">&#x25BC;</button
+            >
+            <button onclick={closeSearch} aria-label="Close search" title="Close (Escape)">&#x2715;</button>
+        </div>
+    {/if}
+
+    {#if loading}
+        <div class="status-message">Loading...</div>
+    {:else if error}
+        <div class="status-message error">{error}</div>
+    {:else}
+        <div class="file-content" role="document" aria-label="File content: {fileName}">
+            {#each lines as line, idx}
+                <div class="line" data-line={idx}>
+                    <span class="line-number" style="width: {gutterWidth}ch" aria-hidden="true">{idx + 1}</span>
+                    <span class="line-text"
+                        >{#each getHighlightedSegments(idx, line) as seg}{#if seg.highlight}<mark
+                                    class:active={seg.active}>{seg.text}</mark
+                                >{:else}{seg.text}{/if}{/each}{#if line === ''}{'\n'}{/if}</span
+                    >
+                </div>
+            {/each}
+        </div>
+    {/if}
+
+    <div class="status-bar" aria-label="File information">
+        <span>{fileName}</span>
+        <span>{lineCount} {lineCount === 1 ? 'line' : 'lines'}</span>
+        <span>{formatSize(fileSize)}</span>
+        <span class="shortcut-hint">Ctrl+F search &middot; Esc close</span>
+    </div>
+</div>
+
+<style>
+    .viewer-container {
+        display: flex;
+        flex-direction: column;
+        height: 100vh;
+        font-family: var(--font-system);
+        background: var(--color-bg-primary);
+        color: var(--color-text-primary);
+        outline: none;
+    }
+
+    .search-bar {
+        display: flex;
+        align-items: center;
+        gap: var(--spacing-xs);
+        padding: var(--spacing-xs) var(--spacing-sm);
+        background: var(--color-bg-secondary);
+        border-bottom: 1px solid var(--color-border-primary);
+        flex-shrink: 0;
+    }
+
+    .search-input {
+        flex: 1;
+        max-width: 300px;
+        padding: 3px 8px;
+        border: 1px solid var(--color-border-primary);
+        border-radius: 4px;
+        background: var(--color-bg-primary);
+        color: var(--color-text-primary);
+        font-size: var(--font-size-sm);
+        font-family: var(--font-system);
+    }
+
+    .search-input:focus {
+        border-color: var(--color-accent);
+        outline: none;
+    }
+
+    .match-count {
+        font-size: 11px;
+        color: var(--color-text-secondary);
+        min-width: 70px;
+    }
+
+    .search-bar button {
+        background: var(--color-bg-tertiary);
+        border: 1px solid var(--color-border-secondary);
+        border-radius: 3px;
+        color: var(--color-text-primary);
+        font-size: 11px;
+        padding: 2px 6px;
+        cursor: pointer;
+        line-height: 1;
+    }
+
+    .search-bar button:hover:not(:disabled) {
+        background: var(--color-button-hover);
+    }
+
+    .search-bar button:disabled {
+        opacity: 0.4;
+        cursor: default;
+    }
+
+    .file-content {
+        flex: 1;
+        overflow: auto;
+        font-family: 'SF Mono', Menlo, Monaco, Consolas, monospace;
+        font-size: 12px;
+        line-height: 1.5;
+        padding: var(--spacing-xs) 0;
+        user-select: text;
+        -webkit-user-select: text;
+        cursor: text;
+    }
+
+    .line {
+        display: flex;
+        padding: 0 var(--spacing-sm);
+        min-height: 18px;
+    }
+
+    .line:hover {
+        background: var(--color-bg-hover);
+    }
+
+    .line-number {
+        display: inline-block;
+        text-align: right;
+        color: var(--color-text-muted);
+        padding-right: var(--spacing-sm);
+        margin-right: var(--spacing-sm);
+        border-right: 1px solid var(--color-border-secondary);
+        flex-shrink: 0;
+        user-select: none;
+        -webkit-user-select: none;
+    }
+
+    .line-text {
+        white-space: pre;
+        word-break: break-all;
+        flex: 1;
+        min-width: 0;
+    }
+
+    mark {
+        background: #fff3a8;
+        color: #000;
+        border-radius: 2px;
+        padding: 0 1px;
+    }
+
+    mark.active {
+        background: #ff9632;
+        color: #fff;
+    }
+
+    @media (prefers-color-scheme: dark) {
+        mark {
+            background: #665d20;
+            color: #fff;
+        }
+        mark.active {
+            background: #cc6600;
+            color: #fff;
+        }
+    }
+
+    .status-bar {
+        display: flex;
+        align-items: center;
+        gap: var(--spacing-md);
+        padding: var(--spacing-xs) var(--spacing-sm);
+        background: var(--color-bg-secondary);
+        border-top: 1px solid var(--color-border-primary);
+        font-size: 11px;
+        color: var(--color-text-secondary);
+        flex-shrink: 0;
+    }
+
+    .shortcut-hint {
+        margin-left: auto;
+        color: var(--color-text-muted);
+    }
+
+    .status-message {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        flex: 1;
+        color: var(--color-text-secondary);
+        font-size: var(--font-size-sm);
+    }
+
+    .status-message.error {
+        color: var(--color-error);
+    }
+</style>
diff --git a/docs/features/file-viewer.md b/docs/features/file-viewer.md
new file mode 100644
index 00000000..c6d58bd8
--- /dev/null
+++ b/docs/features/file-viewer.md
@@ -0,0 +1,58 @@
+# File viewer
+
+View a file's text content in a dedicated window via F3. Includes search with match highlighting.
+
+## User interaction
+
+Press **F3** to open the file under the cursor in a new viewer window. Multiple viewer windows can be open at the same
+time. Each window remembers its size and position between sessions.
+
+### Viewing
+
+- File content is displayed with line numbers in a monospace font.
+- A status bar shows the file name, line count, and file size.
+- Text is selectable for copying.
+
+### Search
+
+- **Cmd+F** (or **Ctrl+F**): Open the search bar.
+- Type to find matches (case-insensitive). The match count is shown.
+- **Enter**: Jump to next match.
+- **Shift+Enter**: Jump to previous match.
+- Matches are highlighted in the content. The active match uses a distinct color.
+- Search wraps around at the end/beginning of the file.
+
+### Keyboard shortcuts
+
+- **Escape**: Close search bar if open, or close the viewer window.
+- **Cmd+F / Ctrl+F**: Open or focus the search bar.
+- **Enter / Shift+Enter**: Next/previous match (when search is open).
+
+### Limitations
+
+- Not optimized for very large files. The entire file is loaded into memory.
+- Binary files are shown with lossy UTF-8 decoding (replacement characters for invalid bytes).
+- Directories can't be viewed (F3 does nothing when the cursor is on a folder).
+
+## Implementation
+
+### Backend
+
+- **Command**: `read_file_content(path)` in `apps/desktop/src-tauri/src/commands/file_system.rs`
+- Returns `FileContentResult { content, lineCount, size, fileName }`
+- Uses `String::from_utf8_lossy` for binary-safe reading
+- Supports tilde expansion for the path
+
+### Frontend
+
+- **Route**: `apps/desktop/src/routes/viewer/+page.svelte` — the viewer window's page
+- **Search utilities**: `apps/desktop/src/lib/file-viewer/viewer-search.ts`
+- **Window opener**: `apps/desktop/src/lib/file-viewer/open-viewer.ts`
+- **Key binding**: F3 handler in `DualPaneExplorer.svelte` calls `openViewerForCursor()`
+- **Function key bar**: F3 button in `FunctionKeyBar.svelte`
+- **Tauri wrapper**: `readFileContent()` in `$lib/tauri-commands.ts`
+
+### Window management
+
+Each viewer opens as a new `WebviewWindow` with a unique label (`viewer-{timestamp}`). The file path is passed as a URL
+query parameter. Window size and position are persisted by `tauri-plugin-window-state`.
diff --git a/docs/specs/viewer-tasks.md b/docs/specs/viewer-tasks.md
new file mode 100644
index 00000000..ddfb4b04
--- /dev/null
+++ b/docs/specs/viewer-tasks.md
@@ -0,0 +1,19 @@
+# File viewer — task list
+
+## Tasks
+
+- [x] Create this task list
+- [x] Add `read_file_content` Rust command (reads file, returns text + metadata)
+- [x] Add Rust tests for the command
+- [x] Create `/viewer` SvelteKit route with `FileViewer` component
+- [x] Wire F3 key binding in `DualPaneExplorer` and enable F3 in `FunctionKeyBar`
+- [x] Open viewer in a new Tauri window (unique label per file, multiple allowed)
+- [x] Persist window size/position via `tauri-plugin-window-state`
+- [x] Display file content with line numbers and monospace font
+- [x] Add search functionality (Cmd+F / Ctrl+F, find next/previous, match count)
+- [x] ESC closes the viewer window (or closes search bar if open)
+- [x] Add `readFileContent` wrapper in `tauri-commands.ts`
+- [x] Write Vitest unit tests for viewer search utilities
+- [x] Document in `docs/features/file-viewer.md`
+- [x] Run checker script, fix any issues
+- [x] Create PR

From 5a81a52e4c941a43d4f2e10031301316884cd78b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 24 Jan 2026 00:51:53 +0000
Subject: [PATCH 02/16] Fix ESLint errors in file viewer

- Extract function key handling to reduce handleKeyDown complexity
- Fix template literal type in open-viewer.ts
- Add keys to {#each} blocks in viewer page
- Remove useless mustache interpolation
---
 .../lib/file-explorer/DualPaneExplorer.svelte | 69 ++++++++-----------
 .../src/lib/file-viewer/open-viewer.ts        |  2 +-
 apps/desktop/src/routes/viewer/+page.svelte   |  6 +-
 3 files changed, 34 insertions(+), 43 deletions(-)

diff --git a/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte b/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte
index 85e1b5df..9987cdf1 100644
--- a/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte
+++ b/apps/desktop/src/lib/file-explorer/DualPaneExplorer.svelte
@@ -505,6 +505,35 @@
         return false
     }
 
+    /** Handles function key shortcuts (F1-F7). Returns true if a function key was handled. */
+    function handleFunctionKey(e: KeyboardEvent): boolean {
+        switch (e.key) {
+            case 'F1':
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+                rightPaneRef?.closeVolumeChooser()
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+                leftPaneRef?.toggleVolumeChooser()
+                return true
+            case 'F2':
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+                leftPaneRef?.closeVolumeChooser()
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+                rightPaneRef?.toggleVolumeChooser()
+                return true
+            case 'F3':
+                void openViewerForCursor()
+                return true
+            case 'F5':
+                void openCopyDialog()
+                return true
+            case 'F7':
+                void openNewFolderDialog()
+                return true
+            default:
+                return false
+        }
+    }
+
     function handleKeyDown(e: KeyboardEvent) {
         if (e.key === 'Tab') {
             e.preventDefault()
@@ -518,46 +547,8 @@
             return
         }
 
-        // F1 or ⌥F1 - Open left pane volume chooser
-        if (e.key === 'F1') {
-            e.preventDefault()
-            // Close right pane's volume chooser before toggling left (only one can be open)
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-            rightPaneRef?.closeVolumeChooser()
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-            leftPaneRef?.toggleVolumeChooser()
-            return
-        }
-
-        // F2 or ⌥F2 - Open right pane volume chooser
-        if (e.key === 'F2') {
-            e.preventDefault()
-            // Close left pane's volume chooser before toggling right (only one can be open)
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-            leftPaneRef?.closeVolumeChooser()
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-            rightPaneRef?.toggleVolumeChooser()
-            return
-        }
-
-        // F3 - View file
-        if (e.key === 'F3') {
-            e.preventDefault()
-            void openViewerForCursor()
-            return
-        }
-
-        // F5 - Copy dialog
-        if (e.key === 'F5') {
-            e.preventDefault()
-            void openCopyDialog()
-            return
-        }
-
-        // F7 - New folder dialog
-        if (e.key === 'F7') {
+        if (handleFunctionKey(e)) {
             e.preventDefault()
-            void openNewFolderDialog()
             return
         }
 
diff --git a/apps/desktop/src/lib/file-viewer/open-viewer.ts b/apps/desktop/src/lib/file-viewer/open-viewer.ts
index b41f436a..1d064ad4 100644
--- a/apps/desktop/src/lib/file-viewer/open-viewer.ts
+++ b/apps/desktop/src/lib/file-viewer/open-viewer.ts
@@ -3,7 +3,7 @@ export async function openFileViewer(filePath: string): Promise<void> {
     const { WebviewWindow } = await import('@tauri-apps/api/webviewWindow')
 
     // Use a unique label per viewer instance (timestamp-based)
-    const label = `viewer-${Date.now()}`
+    const label = `viewer-${String(Date.now())}`
     const encodedPath = encodeURIComponent(filePath)
 
     new WebviewWindow(label, {
diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
index 7d716901..f11270ea 100644
--- a/apps/desktop/src/routes/viewer/+page.svelte
+++ b/apps/desktop/src/routes/viewer/+page.svelte
@@ -227,13 +227,13 @@
         <div class="status-message error">{error}</div>
     {:else}
         <div class="file-content" role="document" aria-label="File content: {fileName}">
-            {#each lines as line, idx}
+            {#each lines as line, idx (idx)}
                 <div class="line" data-line={idx}>
                     <span class="line-number" style="width: {gutterWidth}ch" aria-hidden="true">{idx + 1}</span>
                     <span class="line-text"
-                        >{#each getHighlightedSegments(idx, line) as seg}{#if seg.highlight}<mark
+                        >{#each getHighlightedSegments(idx, line) as seg, segIdx (segIdx)}{#if seg.highlight}<mark
                                     class:active={seg.active}>{seg.text}</mark
-                                >{:else}{seg.text}{/if}{/each}{#if line === ''}{'\n'}{/if}</span
+                                >{:else}{seg.text}{/if}{/each}</span
                     >
                 </div>
             {/each}

From 2963ee788ff2fd2c0c85c798ddff41671fd7ab7a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 24 Jan 2026 06:53:04 +0000
Subject: [PATCH 03/16] Add open-viewer.ts to coverage allowlist

Depends on Tauri WebviewWindow API, not unit-testable.
---
 apps/desktop/coverage-allowlist.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/desktop/coverage-allowlist.json b/apps/desktop/coverage-allowlist.json
index 9bcec038..c0b0fb83 100644
--- a/apps/desktop/coverage-allowlist.json
+++ b/apps/desktop/coverage-allowlist.json
@@ -18,6 +18,7 @@
         "file-explorer/SelectionInfo.svelte": { "reason": "Logic tested in selection-info-utils.ts, DOM-dependent" },
         "file-explorer/ShareBrowser.svelte": { "reason": "Network component, needs integration tests" },
         "file-explorer/SortableHeader.svelte": { "reason": "Simple UI component, display only" },
+        "file-viewer/open-viewer.ts": { "reason": "Depends on Tauri WebviewWindow API" },
         "font-metrics/measure.ts": { "reason": "Depends on DOM APIs" },
         "icon-cache.ts": { "reason": "Depends on Tauri APIs" },
         "licensing-store.svelte.ts": { "reason": "Depends on Tauri store APIs" },

From c7a1336132fc626d612daf26dd3565ae8ff8b68f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 24 Jan 2026 16:47:52 +0000
Subject: [PATCH 04/16] Feature: Three-backend viewer architecture with virtual
 scrolling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the simple read_file_content approach with a session-based three-backend
architecture that handles files of any size:

- FullLoadBackend: files ≤ 1 MB, instant random access in RAM
- ByteSeekBackend: instant open for large files, byte-offset seeking
- LineIndexBackend: sparse line index (every 256 lines), built in background

ViewerSession orchestrator picks the right backend and transparently upgrades
from ByteSeek to LineIndex once the background scan completes.

Frontend uses virtual scrolling (only renders visible lines + 50-line buffer)
with on-demand line fetching from the backend. Search runs server-side with
cancellation support and progress reporting.

64 new Rust tests covering all backends and orchestrator. Old client-side
search utilities removed.
---
 apps/desktop/src-tauri/Cargo.lock             |   1 +
 apps/desktop/src-tauri/Cargo.toml             |   1 +
 .../src-tauri/src/commands/file_system.rs     | 143 -------
 .../src-tauri/src/commands/file_viewer.rs     |  66 ++++
 apps/desktop/src-tauri/src/commands/mod.rs    |   1 +
 .../src-tauri/src/file_viewer/byte_seek.rs    | 279 ++++++++++++++
 .../src/file_viewer/byte_seek_test.rs         | 280 ++++++++++++++
 .../src-tauri/src/file_viewer/full_load.rs    | 174 +++++++++
 .../src/file_viewer/full_load_test.rs         | 238 ++++++++++++
 .../src-tauri/src/file_viewer/line_index.rs   | 337 +++++++++++++++++
 .../src/file_viewer/line_index_test.rs        | 269 +++++++++++++
 apps/desktop/src-tauri/src/file_viewer/mod.rs | 139 +++++++
 .../src-tauri/src/file_viewer/session.rs      | 324 ++++++++++++++++
 .../src-tauri/src/file_viewer/session_test.rs | 254 +++++++++++++
 apps/desktop/src-tauri/src/lib.rs             |   8 +-
 .../src/lib/file-viewer/viewer-search.test.ts |  86 -----
 .../src/lib/file-viewer/viewer-search.ts      |  39 --
 apps/desktop/src/lib/tauri-commands.ts        |  81 +++-
 apps/desktop/src/routes/viewer/+page.svelte   | 357 ++++++++++++++----
 docs/features/file-viewer.md                  |  65 +++-
 docs/specs/viewer-tasks.md                    |  19 +-
 21 files changed, 2794 insertions(+), 367 deletions(-)
 create mode 100644 apps/desktop/src-tauri/src/commands/file_viewer.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/byte_seek.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/full_load.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/full_load_test.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/line_index.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/line_index_test.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/mod.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/session.rs
 create mode 100644 apps/desktop/src-tauri/src/file_viewer/session_test.rs
 delete mode 100644 apps/desktop/src/lib/file-viewer/viewer-search.test.ts
 delete mode 100644 apps/desktop/src/lib/file-viewer/viewer-search.ts

diff --git a/apps/desktop/src-tauri/Cargo.lock b/apps/desktop/src-tauri/Cargo.lock
index 6cf132e3..7854ff19 100644
--- a/apps/desktop/src-tauri/Cargo.lock
+++ b/apps/desktop/src-tauri/Cargo.lock
@@ -1012,6 +1012,7 @@ dependencies = [
  "image",
  "libc",
  "log",
+ "memchr",
  "notify",
  "notify-debouncer-full",
  "objc2 0.6.3",
diff --git a/apps/desktop/src-tauri/Cargo.toml b/apps/desktop/src-tauri/Cargo.toml
index 6bc176b6..6f68d928 100644
--- a/apps/desktop/src-tauri/Cargo.toml
+++ b/apps/desktop/src-tauri/Cargo.toml
@@ -60,6 +60,7 @@ futures-util = "0.3"
 tower-http = { version = "0.6", features = ["cors"] }
 tauri-plugin-updater = "2"
 tauri-plugin-process = "2"
+memchr = "2"
 
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"
diff --git a/apps/desktop/src-tauri/src/commands/file_system.rs b/apps/desktop/src-tauri/src/commands/file_system.rs
index e2539d2c..61b96075 100644
--- a/apps/desktop/src-tauri/src/commands/file_system.rs
+++ b/apps/desktop/src-tauri/src/commands/file_system.rs
@@ -561,70 +561,6 @@ pub fn start_selection_drag(
     Err("Drag operation is not yet supported on this platform".to_string())
 }
 
-// ============================================================================
-// File viewer
-// ============================================================================
-
-/// Result of reading a file's content for the viewer.
-#[derive(Debug, serde::Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct FileContentResult {
-    /// The text content of the file (UTF-8 lossy decoded).
-    pub content: String,
-    /// Total number of lines.
-    pub line_count: usize,
-    /// File size in bytes.
-    pub size: u64,
-    /// The file name (last component of the path).
-    pub file_name: String,
-}
-
-/// Reads a file's content as text for the file viewer.
-///
-/// Returns the full file content as a UTF-8 string (lossy — invalid bytes become replacement chars).
-/// Not optimized for huge files; intended for reasonably-sized text files.
-///
-/// # Arguments
-/// * `path` - Absolute path to the file. Supports tilde expansion (~).
-#[tauri::command]
-pub fn read_file_content(path: String) -> Result<FileContentResult, String> {
-    let expanded = expand_tilde(&path);
-    let file_path = PathBuf::from(&expanded);
-
-    if !file_path.exists() {
-        return Err(format!("File not found: {}", path));
-    }
-    if file_path.is_dir() {
-        return Err("Cannot view a directory".to_string());
-    }
-
-    let metadata = std::fs::metadata(&file_path).map_err(|e| match e.kind() {
-        std::io::ErrorKind::PermissionDenied => format!("Permission denied: {}", path),
-        _ => format!("Cannot read file metadata: {}", e),
-    })?;
-
-    let size = metadata.len();
-    let bytes = std::fs::read(&file_path).map_err(|e| match e.kind() {
-        std::io::ErrorKind::PermissionDenied => format!("Permission denied: {}", path),
-        _ => format!("Failed to read file: {}", e),
-    })?;
-
-    let content = String::from_utf8_lossy(&bytes).into_owned();
-    let line_count = content.lines().count().max(1);
-
-    let file_name = file_path
-        .file_name()
-        .map(|n| n.to_string_lossy().into_owned())
-        .unwrap_or_else(|| path.clone());
-
-    Ok(FileContentResult {
-        content,
-        line_count,
-        size,
-        file_name,
-    })
-}
-
 /// Expands tilde (~) to the user's home directory.
 fn expand_tilde(path: &str) -> String {
     if (path.starts_with("~/") || path == "~")
@@ -724,83 +660,4 @@ mod tests {
         let result = create_directory("/nonexistent_path_12345".to_string(), "test".to_string());
         assert!(result.is_err());
     }
-
-    // ========================================================================
-    // read_file_content tests
-    // ========================================================================
-
-    #[test]
-    fn test_read_file_content_success() {
-        let tmp = create_test_dir("read_content_ok");
-        let file_path = tmp.join("hello.txt");
-        fs::write(&file_path, "line 1\nline 2\nline 3\n").unwrap();
-
-        let result = read_file_content(file_path.to_string_lossy().to_string());
-        assert!(result.is_ok());
-        let res = result.unwrap();
-        assert_eq!(res.file_name, "hello.txt");
-        assert_eq!(res.line_count, 3);
-        assert!(res.content.starts_with("line 1"));
-        assert_eq!(res.size, 21);
-        cleanup_test_dir(&tmp);
-    }
-
-    #[test]
-    fn test_read_file_content_empty_file() {
-        let tmp = create_test_dir("read_content_empty");
-        let file_path = tmp.join("empty.txt");
-        fs::write(&file_path, "").unwrap();
-
-        let result = read_file_content(file_path.to_string_lossy().to_string());
-        assert!(result.is_ok());
-        let res = result.unwrap();
-        assert_eq!(res.content, "");
-        assert_eq!(res.line_count, 1); // At least 1
-        assert_eq!(res.size, 0);
-        cleanup_test_dir(&tmp);
-    }
-
-    #[test]
-    fn test_read_file_content_not_found() {
-        let result = read_file_content("/nonexistent_file_12345.txt".to_string());
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("File not found"));
-    }
-
-    #[test]
-    fn test_read_file_content_directory() {
-        let tmp = create_test_dir("read_content_dir");
-        let result = read_file_content(tmp.to_string_lossy().to_string());
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("Cannot view a directory"));
-        cleanup_test_dir(&tmp);
-    }
-
-    #[test]
-    fn test_read_file_content_binary() {
-        let tmp = create_test_dir("read_content_binary");
-        let file_path = tmp.join("binary.bin");
-        fs::write(&file_path, b"\x00\x01\x02\xff\xfe").unwrap();
-
-        let result = read_file_content(file_path.to_string_lossy().to_string());
-        assert!(result.is_ok());
-        // Binary content is lossy-decoded, should contain replacement characters
-        let res = result.unwrap();
-        assert!(res.content.contains('\u{FFFD}'));
-        cleanup_test_dir(&tmp);
-    }
-
-    #[test]
-    fn test_read_file_content_single_line_no_newline() {
-        let tmp = create_test_dir("read_content_single");
-        let file_path = tmp.join("single.txt");
-        fs::write(&file_path, "hello world").unwrap();
-
-        let result = read_file_content(file_path.to_string_lossy().to_string());
-        assert!(result.is_ok());
-        let res = result.unwrap();
-        assert_eq!(res.line_count, 1);
-        assert_eq!(res.content, "hello world");
-        cleanup_test_dir(&tmp);
-    }
 }
diff --git a/apps/desktop/src-tauri/src/commands/file_viewer.rs b/apps/desktop/src-tauri/src/commands/file_viewer.rs
new file mode 100644
index 00000000..bc9b333f
--- /dev/null
+++ b/apps/desktop/src-tauri/src/commands/file_viewer.rs
@@ -0,0 +1,66 @@
+//! Tauri commands for the file viewer.
+
+use crate::file_viewer::{self, LineChunk, SearchPollResult, SeekTarget, ViewerOpenResult};
+
+/// Opens a viewer session for the given file.
+/// Returns session metadata + initial lines from the start of the file.
+#[tauri::command]
+pub fn viewer_open(path: String) -> Result<ViewerOpenResult, String> {
+    file_viewer::open_session(&path).map_err(|e| e.to_string())
+}
+
+/// Fetches a range of lines from a viewer session.
+///
+/// # Arguments
+/// * `session_id` - The session ID from `viewer_open`.
+/// * `target_type` - One of "line", "byte", or "fraction".
+/// * `target_value` - The seek value (line number, byte offset, or fraction 0.0-1.0).
+/// * `count` - Number of lines to fetch.
+#[tauri::command]
+pub fn viewer_get_lines(
+    session_id: String,
+    target_type: String,
+    target_value: f64,
+    count: usize,
+) -> Result<LineChunk, String> {
+    let target = match target_type.as_str() {
+        "line" => SeekTarget::Line(target_value as usize),
+        "byte" => SeekTarget::ByteOffset(target_value as u64),
+        "fraction" => SeekTarget::Fraction(target_value),
+        other => {
+            return Err(format!(
+                "Unknown target type: {}. Use 'line', 'byte', or 'fraction'.",
+                other
+            ));
+        }
+    };
+    file_viewer::get_lines(&session_id, target, count).map_err(|e| e.to_string())
+}
+
+/// Starts a background search in the viewer session.
+/// Poll with `viewer_search_poll` to get results.
+#[tauri::command]
+pub fn viewer_search_start(session_id: String, query: String) -> Result<(), String> {
+    if query.is_empty() {
+        return Err("Search query cannot be empty".to_string());
+    }
+    file_viewer::search_start(&session_id, query).map_err(|e| e.to_string())
+}
+
+/// Polls search progress and current matches.
+#[tauri::command]
+pub fn viewer_search_poll(session_id: String) -> Result<SearchPollResult, String> {
+    file_viewer::search_poll(&session_id).map_err(|e| e.to_string())
+}
+
+/// Cancels an ongoing search.
+#[tauri::command]
+pub fn viewer_search_cancel(session_id: String) -> Result<(), String> {
+    file_viewer::search_cancel(&session_id).map_err(|e| e.to_string())
+}
+
+/// Closes a viewer session and frees resources.
+#[tauri::command]
+pub fn viewer_close(session_id: String) -> Result<(), String> {
+    file_viewer::close_session(&session_id).map_err(|e| e.to_string())
+}
diff --git a/apps/desktop/src-tauri/src/commands/mod.rs b/apps/desktop/src-tauri/src/commands/mod.rs
index 3c856815..d120d4e7 100644
--- a/apps/desktop/src-tauri/src/commands/mod.rs
+++ b/apps/desktop/src-tauri/src/commands/mod.rs
@@ -1,6 +1,7 @@
 //! Tauri commands module.
 
 pub mod file_system;
+pub mod file_viewer;
 pub mod font_metrics;
 pub mod icons;
 pub mod licensing;
diff --git a/apps/desktop/src-tauri/src/file_viewer/byte_seek.rs b/apps/desktop/src-tauri/src/file_viewer/byte_seek.rs
new file mode 100644
index 00000000..6b0e6d4f
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/byte_seek.rs
@@ -0,0 +1,279 @@
+//! ByteSeekBackend — byte-offset seeking with no pre-scan.
+//!
+//! Opens the file and can immediately serve lines at any byte position.
+//! Scans backward up to MAX_BACKWARD_SCAN bytes to find a newline boundary.
+//! If no newline is found (for example, in a binary file), treats the seek position as a line start.
+//!
+//! Supports Fraction seeking by multiplying fraction × total_bytes.
+//! Does NOT support Line seeking (use LineIndexBackend for that).
+
+use std::fs::File;
+use std::io::{Read, Seek, SeekFrom};
+use std::path::Path;
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use memchr::memchr;
+
+use super::{
+    BackendCapabilities, FileViewerBackend, LineChunk, MAX_BACKWARD_SCAN, SearchMatch, SeekTarget, ViewerError,
+};
+
+pub struct ByteSeekBackend {
+    path: std::path::PathBuf,
+    total_bytes: u64,
+    file_name: String,
+}
+
+impl ByteSeekBackend {
+    pub fn open(path: &Path) -> Result<Self, ViewerError> {
+        let metadata = std::fs::metadata(path).map_err(|e| match e.kind() {
+            std::io::ErrorKind::NotFound => ViewerError::NotFound(path.display().to_string()),
+            _ => ViewerError::from(e),
+        })?;
+        if metadata.is_dir() {
+            return Err(ViewerError::IsDirectory);
+        }
+
+        let file_name = path
+            .file_name()
+            .map(|n| n.to_string_lossy().into_owned())
+            .unwrap_or_else(|| path.display().to_string());
+
+        Ok(Self {
+            path: path.to_path_buf(),
+            total_bytes: metadata.len(),
+            file_name,
+        })
+    }
+
+    /// Given a byte offset, scan backward to find the start of the line containing that offset.
+    /// Returns the byte offset of the line start.
+    fn find_line_start(&self, file: &mut File, offset: u64) -> std::io::Result<u64> {
+        if offset == 0 {
+            return Ok(0);
+        }
+
+        // How far back can we go?
+        let scan_len = (offset as usize).min(MAX_BACKWARD_SCAN);
+        let scan_start = offset - scan_len as u64;
+
+        file.seek(SeekFrom::Start(scan_start))?;
+        let mut buf = vec![0u8; scan_len];
+        let bytes_read = file.read(&mut buf)?;
+        let buf = &buf[..bytes_read];
+
+        // Search backward for '\n' — the line starts right after the last newline before offset.
+        // We search in reverse using memchr on the reversed slice approach.
+        if let Some(pos) = buf.iter().rposition(|&b| b == b'\n') {
+            // Line starts right after this newline
+            Ok(scan_start + pos as u64 + 1)
+        } else {
+            // No newline found within MAX_BACKWARD_SCAN — treat scan_start as line start
+            // (or if scan_start == 0, the file starts here)
+            Ok(scan_start)
+        }
+    }
+
+    /// Read `count` lines starting from `byte_offset`.
+    /// Returns the lines and the byte offset just past the last line read.
+    fn read_lines_from(&self, start_offset: u64, count: usize) -> Result<(Vec<String>, u64), ViewerError> {
+        let mut file = File::open(&self.path)?;
+        file.seek(SeekFrom::Start(start_offset))?;
+
+        let mut lines = Vec::with_capacity(count);
+        let mut current_offset = start_offset;
+
+        // Read in chunks for efficiency
+        let chunk_size: usize = 64 * 1024; // 64 KB read buffer
+        let mut buf = vec![0u8; chunk_size];
+        let mut leftover = Vec::new();
+
+        'outer: while lines.len() < count && current_offset < self.total_bytes {
+            let bytes_read = file.read(&mut buf)?;
+            if bytes_read == 0 {
+                break;
+            }
+
+            // Prepend any leftover from previous chunk
+            let mut combined = Vec::new();
+            let data: &[u8] = if leftover.is_empty() {
+                &buf[..bytes_read]
+            } else {
+                combined.reserve(leftover.len() + bytes_read);
+                combined.extend_from_slice(&leftover);
+                combined.extend_from_slice(&buf[..bytes_read]);
+                leftover.clear();
+                &combined
+            };
+
+            let mut pos = 0;
+            while pos < data.len() && lines.len() < count {
+                if let Some(nl_pos) = memchr(b'\n', &data[pos..]) {
+                    let line_bytes = &data[pos..pos + nl_pos];
+                    let line = String::from_utf8_lossy(line_bytes).into_owned();
+                    lines.push(line);
+                    current_offset += (nl_pos + 1) as u64; // +1 for newline
+                    pos += nl_pos + 1;
+                } else {
+                    // No newline in remaining data — save as leftover
+                    leftover.extend_from_slice(&data[pos..]);
+                    continue 'outer;
+                }
+            }
+        }
+
+        // If there's leftover data (last line without newline), add it
+        if !leftover.is_empty() && lines.len() < count {
+            let line = String::from_utf8_lossy(&leftover).into_owned();
+            current_offset += leftover.len() as u64;
+            lines.push(line);
+        }
+
+        Ok((lines, current_offset))
+    }
+
+    fn resolve_byte_offset(&self, target: &SeekTarget) -> u64 {
+        match target {
+            SeekTarget::ByteOffset(offset) => (*offset).min(self.total_bytes),
+            SeekTarget::Fraction(f) => {
+                let f = f.clamp(0.0, 1.0);
+                (f * self.total_bytes as f64) as u64
+            }
+            SeekTarget::Line(_) => {
+                // ByteSeek doesn't support line-based seeking; default to start
+                0
+            }
+        }
+    }
+}
+
+impl FileViewerBackend for ByteSeekBackend {
+    fn get_lines(&self, target: &SeekTarget, count: usize) -> Result<LineChunk, ViewerError> {
+        let raw_offset = self.resolve_byte_offset(target);
+
+        // Find the actual line start by scanning backward
+        let mut file = File::open(&self.path)?;
+        let line_start = self.find_line_start(&mut file, raw_offset)?;
+
+        let (lines, _end_offset) = self.read_lines_from(line_start, count)?;
+
+        Ok(LineChunk {
+            lines,
+            // We don't know the line number in byte-seek mode
+            first_line_number: 0,
+            byte_offset: line_start,
+            total_lines: None,
+            total_bytes: self.total_bytes,
+        })
+    }
+
+    fn search(&self, query: &str, cancel: &AtomicBool, results: &Mutex<Vec<SearchMatch>>) -> Result<u64, ViewerError> {
+        let query_lower = query.to_lowercase();
+        let mut file = File::open(&self.path)?;
+        file.seek(SeekFrom::Start(0))?;
+
+        let chunk_size: usize = 1024 * 1024; // 1 MB chunks
+        let mut buf = vec![0u8; chunk_size];
+        let mut line_number: usize = 0;
+        let mut scanned: u64 = 0;
+        let mut leftover = Vec::new();
+
+        loop {
+            if cancel.load(Ordering::Relaxed) {
+                break;
+            }
+
+            let bytes_read = file.read(&mut buf)?;
+            if bytes_read == 0 {
+                break;
+            }
+
+            // Combine leftover + new data into a working buffer
+            let mut combined = Vec::new();
+            let data: &[u8] = if leftover.is_empty() {
+                &buf[..bytes_read]
+            } else {
+                combined.reserve(leftover.len() + bytes_read);
+                combined.extend_from_slice(&leftover);
+                combined.extend_from_slice(&buf[..bytes_read]);
+                leftover.clear();
+                &combined
+            };
+
+            let mut pos = 0;
+            while pos < data.len() {
+                if cancel.load(Ordering::Relaxed) {
+                    return Ok(scanned);
+                }
+
+                if let Some(nl_pos) = memchr(b'\n', &data[pos..]) {
+                    let line_bytes = &data[pos..pos + nl_pos];
+                    let line = String::from_utf8_lossy(line_bytes);
+                    let line_lower = line.to_lowercase();
+
+                    let mut search_start = 0;
+                    while let Some(match_pos) = line_lower[search_start..].find(&query_lower) {
+                        let col = search_start + match_pos;
+                        let mut matches = results.lock().unwrap();
+                        matches.push(SearchMatch {
+                            line: line_number,
+                            column: col,
+                            length: query.len(),
+                        });
+                        search_start = col + 1;
+                    }
+
+                    scanned += (nl_pos + 1) as u64;
+                    pos += nl_pos + 1;
+                    line_number += 1;
+                } else {
+                    // Incomplete line — save as leftover for next iteration
+                    leftover.extend_from_slice(&data[pos..]);
+                    break;
+                }
+            }
+        }
+
+        // Handle last line without newline
+        if !leftover.is_empty() {
+            let line = String::from_utf8_lossy(&leftover);
+            let line_lower = line.to_lowercase();
+            let mut search_start = 0;
+            while let Some(match_pos) = line_lower[search_start..].find(&query_lower) {
+                let col = search_start + match_pos;
+                let mut matches = results.lock().unwrap();
+                matches.push(SearchMatch {
+                    line: line_number,
+                    column: col,
+                    length: query.len(),
+                });
+                search_start = col + 1;
+            }
+            scanned += leftover.len() as u64;
+        }
+
+        Ok(scanned)
+    }
+
+    fn capabilities(&self) -> BackendCapabilities {
+        BackendCapabilities {
+            supports_line_seek: false,
+            supports_byte_seek: true,
+            supports_fraction_seek: true,
+            knows_total_lines: false,
+        }
+    }
+
+    fn total_bytes(&self) -> u64 {
+        self.total_bytes
+    }
+
+    fn total_lines(&self) -> Option<usize> {
+        None
+    }
+
+    fn file_name(&self) -> &str {
+        &self.file_name
+    }
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs b/apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs
new file mode 100644
index 00000000..1b53592c
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs
@@ -0,0 +1,280 @@
+//! Tests for ByteSeekBackend.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::sync::atomic::AtomicBool;
+
+use super::byte_seek::ByteSeekBackend;
+use super::{FileViewerBackend, SearchMatch, SeekTarget};
+
+fn create_test_dir(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("cmdr_viewer_byte_{}", name));
+    let _ = fs::remove_dir_all(&dir);
+    fs::create_dir_all(&dir).expect("Failed to create test directory");
+    dir
+}
+
+fn cleanup(path: &Path) {
+    let _ = fs::remove_dir_all(path);
+}
+
+fn write_test_file(dir: &Path, name: &str, content: &str) -> PathBuf {
+    let file = dir.join(name);
+    fs::write(&file, content).unwrap();
+    file
+}
+
+#[test]
+fn open_succeeds() {
+    let dir = create_test_dir("open");
+    let file = write_test_file(&dir, "test.txt", "hello world\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    assert_eq!(backend.file_name(), "test.txt");
+    assert_eq!(backend.total_bytes(), 12);
+    assert_eq!(backend.total_lines(), None); // ByteSeek doesn't know total lines
+
+    cleanup(&dir);
+}
+
+#[test]
+fn open_not_found() {
+    let result = ByteSeekBackend::open(&PathBuf::from("/nonexistent_byte_seek_test.txt"));
+    assert!(result.is_err());
+}
+
+#[test]
+fn open_directory_fails() {
+    let dir = create_test_dir("open_dir");
+    let result = ByteSeekBackend::open(&dir);
+    assert!(result.is_err());
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_from_start() {
+    let dir = create_test_dir("lines_start");
+    let file = write_test_file(&dir, "test.txt", "line 1\nline 2\nline 3\nline 4\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let chunk = backend.get_lines(&SeekTarget::ByteOffset(0), 3).unwrap();
+
+    assert_eq!(chunk.lines, vec!["line 1", "line 2", "line 3"]);
+    assert_eq!(chunk.byte_offset, 0);
+    assert_eq!(chunk.total_lines, None);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_from_middle_byte_offset() {
+    let dir = create_test_dir("lines_mid");
+    // "line 1\n" = 7 bytes, so byte 7 starts "line 2"
+    let file = write_test_file(&dir, "test.txt", "line 1\nline 2\nline 3\nline 4\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let chunk = backend.get_lines(&SeekTarget::ByteOffset(7), 2).unwrap();
+
+    assert_eq!(chunk.lines, vec!["line 2", "line 3"]);
+    assert_eq!(chunk.byte_offset, 7);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_with_backward_scan() {
+    let dir = create_test_dir("backward_scan");
+    // Seeking to byte 10 (middle of "line 2") should scan back to start of "line 2"
+    let file = write_test_file(&dir, "test.txt", "line 1\nline 2\nline 3\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let chunk = backend.get_lines(&SeekTarget::ByteOffset(10), 2).unwrap();
+
+    // Should find start of "line 2" (byte 7)
+    assert_eq!(chunk.byte_offset, 7);
+    assert_eq!(chunk.lines[0], "line 2");
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_by_fraction() {
+    let dir = create_test_dir("fraction");
+    let content = "line 1\nline 2\nline 3\nline 4\nline 5\n";
+    let file = write_test_file(&dir, "test.txt", content);
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+
+    // Fraction 0.0 should start at beginning
+    let chunk = backend.get_lines(&SeekTarget::Fraction(0.0), 1).unwrap();
+    assert_eq!(chunk.byte_offset, 0);
+    assert_eq!(chunk.lines[0], "line 1");
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_fraction_end() {
+    let dir = create_test_dir("fraction_end");
+    let content = "line 1\nline 2\nline 3\n";
+    let file = write_test_file(&dir, "test.txt", content);
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+
+    // Fraction 1.0 should go to end (byte 21)
+    let chunk = backend.get_lines(&SeekTarget::Fraction(1.0), 1).unwrap();
+    // Should find the last line or be at/near end
+    assert!(chunk.byte_offset > 0);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_line_target_defaults_to_start() {
+    let dir = create_test_dir("line_target");
+    let file = write_test_file(&dir, "test.txt", "a\nb\nc\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    // ByteSeek doesn't support line seeking — defaults to start
+    let chunk = backend.get_lines(&SeekTarget::Line(5), 2).unwrap();
+    assert_eq!(chunk.byte_offset, 0);
+    assert_eq!(chunk.lines[0], "a");
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_last_line_no_newline() {
+    let dir = create_test_dir("no_trailing_nl");
+    let file = write_test_file(&dir, "test.txt", "line 1\nline 2");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let chunk = backend.get_lines(&SeekTarget::ByteOffset(0), 10).unwrap();
+
+    assert_eq!(chunk.lines, vec!["line 1", "line 2"]);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_finds_matches() {
+    let dir = create_test_dir("search");
+    let file = write_test_file(&dir, "test.txt", "hello world\nfoo bar\nhello again\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 2);
+    assert_eq!(matches[0].line, 0);
+    assert_eq!(matches[0].column, 0);
+    assert_eq!(matches[1].line, 2);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_case_insensitive() {
+    let dir = create_test_dir("search_case");
+    let file = write_test_file(&dir, "test.txt", "Hello\nHELLO\nhello\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 3);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_cancellation() {
+    let dir = create_test_dir("search_cancel");
+    let content = "hello world\n".repeat(10000);
+    let file = write_test_file(&dir, "test.txt", &content);
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let cancel = AtomicBool::new(true); // Pre-cancelled
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    // Should stop early
+    assert!(matches.len() < 10000);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_no_matches() {
+    let dir = create_test_dir("search_none");
+    let file = write_test_file(&dir, "test.txt", "abc\ndef\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("xyz", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 0);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn capabilities_correct() {
+    let dir = create_test_dir("caps");
+    let file = write_test_file(&dir, "test.txt", "test\n");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    let caps = backend.capabilities();
+
+    assert!(!caps.supports_line_seek);
+    assert!(caps.supports_byte_seek);
+    assert!(caps.supports_fraction_seek);
+    assert!(!caps.knows_total_lines);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn backward_scan_with_no_newline_caps_at_max() {
+    let dir = create_test_dir("no_nl");
+    // Write a file with no newlines (simulates binary)
+    let content = "x".repeat(20000);
+    let file = write_test_file(&dir, "test.bin", &content);
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+
+    // Seek to byte 15000 — backward scan of 8192 bytes won't find '\n'
+    let chunk = backend.get_lines(&SeekTarget::ByteOffset(15000), 1).unwrap();
+
+    // Should fall back to scan_start = 15000 - 8192 = 6808
+    assert_eq!(chunk.byte_offset, 15000 - 8192);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn empty_file() {
+    let dir = create_test_dir("empty");
+    let file = write_test_file(&dir, "empty.txt", "");
+
+    let backend = ByteSeekBackend::open(&file).unwrap();
+    assert_eq!(backend.total_bytes(), 0);
+
+    let chunk = backend.get_lines(&SeekTarget::ByteOffset(0), 10).unwrap();
+    // Empty file should produce empty lines
+    assert!(chunk.lines.is_empty() || (chunk.lines.len() == 1 && chunk.lines[0].is_empty()));
+
+    cleanup(&dir);
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/full_load.rs b/apps/desktop/src-tauri/src/file_viewer/full_load.rs
new file mode 100644
index 00000000..333e15f6
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/full_load.rs
@@ -0,0 +1,174 @@
+//! FullLoadBackend — loads entire file into memory.
+//!
+//! Best for files under FULL_LOAD_THRESHOLD (1 MB). Provides instant random
+//! access by line number and fast search since all content is in RAM.
+
+use std::path::Path;
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use super::{BackendCapabilities, FileViewerBackend, LineChunk, SearchMatch, SeekTarget, ViewerError};
+
+pub struct FullLoadBackend {
+    lines: Vec<String>,
+    /// Byte offset of each line start (parallel to `lines`).
+    line_offsets: Vec<u64>,
+    total_bytes: u64,
+    file_name: String,
+}
+
+impl FullLoadBackend {
+    pub fn open(path: &Path) -> Result<Self, ViewerError> {
+        let metadata = std::fs::metadata(path).map_err(|e| match e.kind() {
+            std::io::ErrorKind::NotFound => ViewerError::NotFound(path.display().to_string()),
+            _ => ViewerError::from(e),
+        })?;
+        if metadata.is_dir() {
+            return Err(ViewerError::IsDirectory);
+        }
+
+        let total_bytes = metadata.len();
+        let bytes = std::fs::read(path)?;
+        let content = String::from_utf8_lossy(&bytes);
+
+        let mut lines = Vec::new();
+        let mut line_offsets = Vec::new();
+        let mut offset: u64 = 0;
+
+        for line in content.split('\n') {
+            line_offsets.push(offset);
+            lines.push(line.to_string());
+            // +1 for the '\n' delimiter (even if last line has none, offset won't be used beyond)
+            offset += line.len() as u64 + 1;
+        }
+
+        // If file ends without newline and content is non-empty, the split gives correct result.
+        // If file is empty, we still want at least one empty line.
+        if lines.is_empty() {
+            lines.push(String::new());
+            line_offsets.push(0);
+        }
+
+        let file_name = path
+            .file_name()
+            .map(|n| n.to_string_lossy().into_owned())
+            .unwrap_or_else(|| path.display().to_string());
+
+        Ok(Self {
+            lines,
+            line_offsets,
+            total_bytes,
+            file_name,
+        })
+    }
+
+    /// Create from in-memory content (for testing).
+    #[cfg(test)]
+    pub fn from_content(content: &str, file_name: &str) -> Self {
+        let total_bytes = content.len() as u64;
+        let mut lines = Vec::new();
+        let mut line_offsets = Vec::new();
+        let mut offset: u64 = 0;
+
+        for line in content.split('\n') {
+            line_offsets.push(offset);
+            lines.push(line.to_string());
+            offset += line.len() as u64 + 1;
+        }
+
+        if lines.is_empty() {
+            lines.push(String::new());
+            line_offsets.push(0);
+        }
+
+        Self {
+            lines,
+            line_offsets,
+            total_bytes,
+            file_name: file_name.to_string(),
+        }
+    }
+
+    fn resolve_target(&self, target: &SeekTarget) -> usize {
+        match target {
+            SeekTarget::Line(n) => (*n).min(self.lines.len().saturating_sub(1)),
+            SeekTarget::ByteOffset(offset) => {
+                // Binary search for the line containing this byte offset
+                match self.line_offsets.binary_search(offset) {
+                    Ok(idx) => idx,
+                    Err(idx) => idx.saturating_sub(1),
+                }
+            }
+            SeekTarget::Fraction(f) => {
+                let f = f.clamp(0.0, 1.0);
+                let max_line = self.lines.len().saturating_sub(1);
+                (f * max_line as f64).round() as usize
+            }
+        }
+    }
+}
+
+impl FileViewerBackend for FullLoadBackend {
+    fn get_lines(&self, target: &SeekTarget, count: usize) -> Result<LineChunk, ViewerError> {
+        let start = self.resolve_target(target);
+        let end = (start + count).min(self.lines.len());
+        let chunk_lines: Vec<String> = self.lines[start..end].to_vec();
+
+        Ok(LineChunk {
+            lines: chunk_lines,
+            first_line_number: start,
+            byte_offset: self.line_offsets.get(start).copied().unwrap_or(0),
+            total_lines: Some(self.lines.len()),
+            total_bytes: self.total_bytes,
+        })
+    }
+
+    fn search(&self, query: &str, cancel: &AtomicBool, results: &Mutex<Vec<SearchMatch>>) -> Result<u64, ViewerError> {
+        let query_lower = query.to_lowercase();
+        let mut scanned: u64 = 0;
+
+        for (line_idx, line) in self.lines.iter().enumerate() {
+            if cancel.load(Ordering::Relaxed) {
+                break;
+            }
+
+            let line_lower = line.to_lowercase();
+            let mut search_start = 0;
+            while let Some(pos) = line_lower[search_start..].find(&query_lower) {
+                let col = search_start + pos;
+                let mut matches = results.lock().unwrap();
+                matches.push(SearchMatch {
+                    line: line_idx,
+                    column: col,
+                    length: query.len(),
+                });
+                search_start = col + 1;
+            }
+
+            scanned += line.len() as u64 + 1; // +1 for newline
+        }
+
+        Ok(scanned)
+    }
+
+    fn capabilities(&self) -> BackendCapabilities {
+        BackendCapabilities {
+            supports_line_seek: true,
+            supports_byte_seek: true,
+            supports_fraction_seek: true,
+            knows_total_lines: true,
+        }
+    }
+
+    fn total_bytes(&self) -> u64 {
+        self.total_bytes
+    }
+
+    fn total_lines(&self) -> Option<usize> {
+        Some(self.lines.len())
+    }
+
+    fn file_name(&self) -> &str {
+        &self.file_name
+    }
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/full_load_test.rs b/apps/desktop/src-tauri/src/file_viewer/full_load_test.rs
new file mode 100644
index 00000000..c5f32bed
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/full_load_test.rs
@@ -0,0 +1,238 @@
+//! Tests for FullLoadBackend.
+
+use std::fs;
+use std::path::PathBuf;
+use std::sync::Mutex;
+use std::sync::atomic::AtomicBool;
+
+use super::full_load::FullLoadBackend;
+use super::{FileViewerBackend, SearchMatch, SeekTarget};
+
+fn create_test_dir(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("cmdr_viewer_full_{}", name));
+    let _ = fs::remove_dir_all(&dir);
+    fs::create_dir_all(&dir).expect("Failed to create test directory");
+    dir
+}
+
+fn cleanup(path: &PathBuf) {
+    let _ = fs::remove_dir_all(path);
+}
+
+#[test]
+fn open_reads_lines_correctly() {
+    let dir = create_test_dir("open_lines");
+    let file = dir.join("test.txt");
+    fs::write(&file, "line 1\nline 2\nline 3\n").unwrap();
+
+    let backend = FullLoadBackend::open(&file).unwrap();
+    assert_eq!(backend.total_lines(), Some(4)); // 3 lines + trailing empty
+    assert_eq!(backend.file_name(), "test.txt");
+    assert_eq!(backend.total_bytes(), 21);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn open_empty_file() {
+    let dir = create_test_dir("open_empty");
+    let file = dir.join("empty.txt");
+    fs::write(&file, "").unwrap();
+
+    let backend = FullLoadBackend::open(&file).unwrap();
+    assert_eq!(backend.total_lines(), Some(1)); // At least one line
+    assert_eq!(backend.total_bytes(), 0);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn open_not_found() {
+    let result = FullLoadBackend::open(&PathBuf::from("/nonexistent_viewer_test_12345.txt"));
+    assert!(result.is_err());
+}
+
+#[test]
+fn open_directory_fails() {
+    let dir = create_test_dir("open_dir");
+    let result = FullLoadBackend::open(&dir);
+    assert!(result.is_err());
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_from_start() {
+    let backend = FullLoadBackend::from_content("alpha\nbeta\ngamma\ndelta\nepsilon", "test.txt");
+
+    let chunk = backend.get_lines(&SeekTarget::Line(0), 3).unwrap();
+    assert_eq!(chunk.lines, vec!["alpha", "beta", "gamma"]);
+    assert_eq!(chunk.first_line_number, 0);
+    assert_eq!(chunk.total_lines, Some(5));
+}
+
+#[test]
+fn get_lines_from_middle() {
+    let backend = FullLoadBackend::from_content("a\nb\nc\nd\ne\nf\ng", "test.txt");
+
+    let chunk = backend.get_lines(&SeekTarget::Line(3), 2).unwrap();
+    assert_eq!(chunk.lines, vec!["d", "e"]);
+    assert_eq!(chunk.first_line_number, 3);
+}
+
+#[test]
+fn get_lines_past_end() {
+    let backend = FullLoadBackend::from_content("a\nb\nc", "test.txt");
+
+    let chunk = backend.get_lines(&SeekTarget::Line(10), 5).unwrap();
+    // Should clamp to last line
+    assert_eq!(chunk.first_line_number, 2);
+    assert_eq!(chunk.lines, vec!["c"]);
+}
+
+#[test]
+fn get_lines_by_byte_offset() {
+    let backend = FullLoadBackend::from_content("abc\ndef\nghi", "test.txt");
+
+    // Byte offset 4 is start of "def"
+    let chunk = backend.get_lines(&SeekTarget::ByteOffset(4), 2).unwrap();
+    assert_eq!(chunk.first_line_number, 1);
+    assert_eq!(chunk.lines, vec!["def", "ghi"]);
+}
+
+#[test]
+fn get_lines_by_fraction() {
+    let backend = FullLoadBackend::from_content("a\nb\nc\nd\ne", "test.txt");
+
+    // Fraction 0.5 on 5 lines = line 2 or 3
+    let chunk = backend.get_lines(&SeekTarget::Fraction(0.5), 1).unwrap();
+    assert!(chunk.first_line_number == 2 || chunk.first_line_number == 3);
+}
+
+#[test]
+fn get_lines_fraction_zero() {
+    let backend = FullLoadBackend::from_content("a\nb\nc", "test.txt");
+
+    let chunk = backend.get_lines(&SeekTarget::Fraction(0.0), 1).unwrap();
+    assert_eq!(chunk.first_line_number, 0);
+    assert_eq!(chunk.lines, vec!["a"]);
+}
+
+#[test]
+fn get_lines_fraction_one() {
+    let backend = FullLoadBackend::from_content("a\nb\nc", "test.txt");
+
+    let chunk = backend.get_lines(&SeekTarget::Fraction(1.0), 1).unwrap();
+    assert_eq!(chunk.first_line_number, 2);
+    assert_eq!(chunk.lines, vec!["c"]);
+}
+
+#[test]
+fn search_finds_matches() {
+    let backend = FullLoadBackend::from_content("hello world\nfoo bar\nhello again", "test.txt");
+
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    let scanned = backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 2);
+    assert_eq!(matches[0].line, 0);
+    assert_eq!(matches[0].column, 0);
+    assert_eq!(matches[1].line, 2);
+    assert_eq!(matches[1].column, 0);
+    assert!(scanned > 0);
+}
+
+#[test]
+fn search_case_insensitive() {
+    let backend = FullLoadBackend::from_content("Hello World\nHELLO\nhello", "test.txt");
+
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 3);
+}
+
+#[test]
+fn search_multiple_per_line() {
+    let backend = FullLoadBackend::from_content("aaa", "test.txt");
+
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("aa", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    // "aaa" contains "aa" at positions 0 and 1
+    assert_eq!(matches.len(), 2);
+    assert_eq!(matches[0].column, 0);
+    assert_eq!(matches[1].column, 1);
+}
+
+#[test]
+fn search_cancellation() {
+    let backend = FullLoadBackend::from_content(&"line with hello\n".repeat(10000), "test.txt");
+
+    let cancel = AtomicBool::new(true); // Already cancelled
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    // Should find zero or very few matches since cancelled immediately
+    assert!(matches.len() < 10000);
+}
+
+#[test]
+fn search_no_matches() {
+    let backend = FullLoadBackend::from_content("abc\ndef\nghi", "test.txt");
+
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("xyz", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 0);
+}
+
+#[test]
+fn capabilities_correct() {
+    let backend = FullLoadBackend::from_content("test", "test.txt");
+    let caps = backend.capabilities();
+
+    assert!(caps.supports_line_seek);
+    assert!(caps.supports_byte_seek);
+    assert!(caps.supports_fraction_seek);
+    assert!(caps.knows_total_lines);
+}
+
+#[test]
+fn binary_content_handled() {
+    let dir = create_test_dir("binary");
+    let file = dir.join("binary.bin");
+    fs::write(&file, b"\x00\x01\x02\xff\xfe\n\x03\x04").unwrap();
+
+    let backend = FullLoadBackend::open(&file).unwrap();
+    let chunk = backend.get_lines(&SeekTarget::Line(0), 10).unwrap();
+
+    // Should have 2 lines (split on \n)
+    assert_eq!(chunk.lines.len(), 2);
+    // Binary bytes become replacement characters
+    assert!(chunk.lines[0].contains('\u{FFFD}'));
+
+    cleanup(&dir);
+}
+
+#[test]
+fn single_line_no_newline() {
+    let backend = FullLoadBackend::from_content("just one line", "test.txt");
+
+    assert_eq!(backend.total_lines(), Some(1));
+    let chunk = backend.get_lines(&SeekTarget::Line(0), 10).unwrap();
+    assert_eq!(chunk.lines, vec!["just one line"]);
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/line_index.rs b/apps/desktop/src-tauri/src/file_viewer/line_index.rs
new file mode 100644
index 00000000..cc01ad41
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/line_index.rs
@@ -0,0 +1,337 @@
+//! LineIndexBackend — sparse line-offset index for efficient line-based seeking.
+//!
+//! Stores byte offsets every INDEX_CHECKPOINT_INTERVAL lines (256 by default).
+//! Memory: O(total_lines / 256) — a 10M-line file uses ~40 KB of index.
+//!
+//! The index is built by scanning the file for newlines using memchr (SIMD-accelerated).
+//! After scanning, supports O(1) line-based seeking via the checkpoint array.
+
+use std::fs::File;
+use std::io::{Read, Seek, SeekFrom};
+use std::path::Path;
+use std::sync::Mutex;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use memchr::memchr;
+
+use super::{
+    BackendCapabilities, FileViewerBackend, INDEX_CHECKPOINT_INTERVAL, LineChunk, SearchMatch, SeekTarget, ViewerError,
+};
+
+/// A checkpoint in the line index: (line_number, byte_offset).
+#[derive(Debug, Clone)]
+struct Checkpoint {
+    line: usize,
+    offset: u64,
+}
+
+pub struct LineIndexBackend {
+    path: std::path::PathBuf,
+    total_bytes: u64,
+    file_name: String,
+    /// Sparse index: one checkpoint every INDEX_CHECKPOINT_INTERVAL lines.
+    checkpoints: Vec<Checkpoint>,
+    /// Total lines discovered during scan.
+    total_lines: usize,
+}
+
+impl LineIndexBackend {
+    /// Build the line index by scanning the file. This is blocking and should be run
+    /// in a background thread for large files. Checks `cancel` periodically.
+    pub fn open(path: &Path, cancel: &AtomicBool) -> Result<Self, ViewerError> {
+        let metadata = std::fs::metadata(path).map_err(|e| match e.kind() {
+            std::io::ErrorKind::NotFound => ViewerError::NotFound(path.display().to_string()),
+            _ => ViewerError::from(e),
+        })?;
+        if metadata.is_dir() {
+            return Err(ViewerError::IsDirectory);
+        }
+
+        let total_bytes = metadata.len();
+        let file_name = path
+            .file_name()
+            .map(|n| n.to_string_lossy().into_owned())
+            .unwrap_or_else(|| path.display().to_string());
+
+        // Scan the file to build the sparse line index
+        let mut file = File::open(path)?;
+        let mut checkpoints = Vec::new();
+        let chunk_size: usize = 256 * 1024; // 256 KB scan buffer
+        let mut buf = vec![0u8; chunk_size];
+        let mut line_number: usize = 0;
+        let mut byte_offset: u64 = 0;
+
+        // First line always starts at offset 0
+        checkpoints.push(Checkpoint { line: 0, offset: 0 });
+
+        loop {
+            if cancel.load(Ordering::Relaxed) {
+                return Err(ViewerError::Io("Scan cancelled".to_string()));
+            }
+
+            let bytes_read = file.read(&mut buf)?;
+            if bytes_read == 0 {
+                break;
+            }
+
+            let data = &buf[..bytes_read];
+            let mut pos = 0;
+
+            while pos < data.len() {
+                if let Some(nl_pos) = memchr(b'\n', &data[pos..]) {
+                    line_number += 1;
+                    let nl_byte_offset = byte_offset + (pos + nl_pos) as u64 + 1;
+
+                    // Store checkpoint every N lines
+                    if line_number.is_multiple_of(INDEX_CHECKPOINT_INTERVAL) {
+                        checkpoints.push(Checkpoint {
+                            line: line_number,
+                            offset: nl_byte_offset,
+                        });
+                    }
+
+                    pos += nl_pos + 1;
+                } else {
+                    break;
+                }
+            }
+
+            byte_offset += bytes_read as u64;
+        }
+
+        // total_lines is line_number + 1 (for the last line, which may not end with \n)
+        // But if the file ends with \n, the last "line" is empty — we still count it.
+        let total_lines = line_number + 1;
+
+        Ok(Self {
+            path: path.to_path_buf(),
+            total_bytes,
+            file_name,
+            checkpoints,
+            total_lines,
+        })
+    }
+
+    /// Find the checkpoint at or before the given line number.
+    fn find_checkpoint(&self, target_line: usize) -> &Checkpoint {
+        // Binary search for the largest checkpoint with line <= target_line
+        let idx = match self.checkpoints.binary_search_by_key(&target_line, |cp| cp.line) {
+            Ok(i) => i,
+            Err(i) => i.saturating_sub(1),
+        };
+        &self.checkpoints[idx]
+    }
+
+    /// Read forward from a byte offset, skipping `lines_to_skip` lines,
+    /// then returning the next `count` lines.
+    fn read_lines_from_checkpoint(
+        &self,
+        start_offset: u64,
+        lines_to_skip: usize,
+        count: usize,
+    ) -> Result<Vec<String>, ViewerError> {
+        let mut file = File::open(&self.path)?;
+        file.seek(SeekFrom::Start(start_offset))?;
+
+        let chunk_size: usize = 64 * 1024;
+        let mut buf = vec![0u8; chunk_size];
+        let mut lines = Vec::new();
+        let mut skipped: usize = 0;
+        let mut leftover = Vec::new();
+
+        'outer: loop {
+            let bytes_read = file.read(&mut buf)?;
+            if bytes_read == 0 {
+                break;
+            }
+
+            let mut combined = Vec::new();
+            let data: &[u8] = if leftover.is_empty() {
+                &buf[..bytes_read]
+            } else {
+                combined.reserve(leftover.len() + bytes_read);
+                combined.extend_from_slice(&leftover);
+                combined.extend_from_slice(&buf[..bytes_read]);
+                leftover.clear();
+                &combined
+            };
+
+            let mut pos = 0;
+            while pos < data.len() {
+                if let Some(nl_pos) = memchr(b'\n', &data[pos..]) {
+                    if skipped < lines_to_skip {
+                        skipped += 1;
+                        pos += nl_pos + 1;
+                        continue;
+                    }
+
+                    let line_bytes = &data[pos..pos + nl_pos];
+                    lines.push(String::from_utf8_lossy(line_bytes).into_owned());
+                    pos += nl_pos + 1;
+
+                    if lines.len() >= count {
+                        break 'outer;
+                    }
+                } else {
+                    leftover.extend_from_slice(&data[pos..]);
+                    continue 'outer;
+                }
+            }
+        }
+
+        // Handle last line without newline
+        if !leftover.is_empty() && lines.len() < count && skipped >= lines_to_skip {
+            lines.push(String::from_utf8_lossy(&leftover).into_owned());
+        }
+
+        Ok(lines)
+    }
+
+    fn resolve_target(&self, target: &SeekTarget) -> usize {
+        match target {
+            SeekTarget::Line(n) => (*n).min(self.total_lines.saturating_sub(1)),
+            SeekTarget::ByteOffset(offset) => {
+                // Find the checkpoint closest to this byte offset
+                let idx = match self.checkpoints.binary_search_by_key(offset, |cp| cp.offset) {
+                    Ok(i) => i,
+                    Err(i) => i.saturating_sub(1),
+                };
+                self.checkpoints[idx].line
+            }
+            SeekTarget::Fraction(f) => {
+                let f = f.clamp(0.0, 1.0);
+                let max_line = self.total_lines.saturating_sub(1);
+                (f * max_line as f64).round() as usize
+            }
+        }
+    }
+}
+
+impl FileViewerBackend for LineIndexBackend {
+    fn get_lines(&self, target: &SeekTarget, count: usize) -> Result<LineChunk, ViewerError> {
+        let target_line = self.resolve_target(target);
+        let checkpoint = self.find_checkpoint(target_line);
+        let lines_to_skip = target_line - checkpoint.line;
+
+        let lines = self.read_lines_from_checkpoint(checkpoint.offset, lines_to_skip, count)?;
+
+        // Calculate byte offset of the target line (approximate — it's the checkpoint offset)
+        let byte_offset = checkpoint.offset;
+
+        Ok(LineChunk {
+            lines,
+            first_line_number: target_line,
+            byte_offset,
+            total_lines: Some(self.total_lines),
+            total_bytes: self.total_bytes,
+        })
+    }
+
+    fn search(&self, query: &str, cancel: &AtomicBool, results: &Mutex<Vec<SearchMatch>>) -> Result<u64, ViewerError> {
+        // Stream through file in 1 MB chunks, same as ByteSeekBackend
+        let query_lower = query.to_lowercase();
+        let mut file = File::open(&self.path)?;
+        file.seek(SeekFrom::Start(0))?;
+
+        let chunk_size: usize = 1024 * 1024;
+        let mut buf = vec![0u8; chunk_size];
+        let mut line_number: usize = 0;
+        let mut scanned: u64 = 0;
+        let mut leftover = Vec::new();
+
+        loop {
+            if cancel.load(Ordering::Relaxed) {
+                break;
+            }
+
+            let bytes_read = file.read(&mut buf)?;
+            if bytes_read == 0 {
+                break;
+            }
+
+            let mut combined = Vec::new();
+            let data: &[u8] = if leftover.is_empty() {
+                &buf[..bytes_read]
+            } else {
+                combined.reserve(leftover.len() + bytes_read);
+                combined.extend_from_slice(&leftover);
+                combined.extend_from_slice(&buf[..bytes_read]);
+                leftover.clear();
+                &combined
+            };
+
+            let mut pos = 0;
+            while pos < data.len() {
+                if cancel.load(Ordering::Relaxed) {
+                    return Ok(scanned);
+                }
+
+                if let Some(nl_pos) = memchr(b'\n', &data[pos..]) {
+                    let line_bytes = &data[pos..pos + nl_pos];
+                    let line = String::from_utf8_lossy(line_bytes);
+                    let line_lower = line.to_lowercase();
+
+                    let mut search_start = 0;
+                    while let Some(match_pos) = line_lower[search_start..].find(&query_lower) {
+                        let col = search_start + match_pos;
+                        let mut matches = results.lock().unwrap();
+                        matches.push(SearchMatch {
+                            line: line_number,
+                            column: col,
+                            length: query.len(),
+                        });
+                        search_start = col + 1;
+                    }
+
+                    scanned += (nl_pos + 1) as u64;
+                    pos += nl_pos + 1;
+                    line_number += 1;
+                } else {
+                    leftover.extend_from_slice(&data[pos..]);
+                    break;
+                }
+            }
+        }
+
+        // Handle last line
+        if !leftover.is_empty() {
+            let line = String::from_utf8_lossy(&leftover);
+            let line_lower = line.to_lowercase();
+            let mut search_start = 0;
+            while let Some(match_pos) = line_lower[search_start..].find(&query_lower) {
+                let col = search_start + match_pos;
+                let mut matches = results.lock().unwrap();
+                matches.push(SearchMatch {
+                    line: line_number,
+                    column: col,
+                    length: query.len(),
+                });
+                search_start = col + 1;
+            }
+            scanned += leftover.len() as u64;
+        }
+
+        Ok(scanned)
+    }
+
+    fn capabilities(&self) -> BackendCapabilities {
+        BackendCapabilities {
+            supports_line_seek: true,
+            supports_byte_seek: true,
+            supports_fraction_seek: true,
+            knows_total_lines: true,
+        }
+    }
+
+    fn total_bytes(&self) -> u64 {
+        self.total_bytes
+    }
+
+    fn total_lines(&self) -> Option<usize> {
+        Some(self.total_lines)
+    }
+
+    fn file_name(&self) -> &str {
+        &self.file_name
+    }
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/line_index_test.rs b/apps/desktop/src-tauri/src/file_viewer/line_index_test.rs
new file mode 100644
index 00000000..a4fd759a
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/line_index_test.rs
@@ -0,0 +1,269 @@
+//! Tests for LineIndexBackend.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::sync::atomic::AtomicBool;
+
+use super::line_index::LineIndexBackend;
+use super::{FileViewerBackend, INDEX_CHECKPOINT_INTERVAL, SearchMatch, SeekTarget};
+
+fn create_test_dir(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("cmdr_viewer_lidx_{}", name));
+    let _ = fs::remove_dir_all(&dir);
+    fs::create_dir_all(&dir).expect("Failed to create test directory");
+    dir
+}
+
+fn cleanup(path: &Path) {
+    let _ = fs::remove_dir_all(path);
+}
+
+fn write_test_file(dir: &Path, name: &str, content: &str) -> PathBuf {
+    let file = dir.join(name);
+    fs::write(&file, content).unwrap();
+    file
+}
+
+#[test]
+fn open_builds_index() {
+    let dir = create_test_dir("open");
+    let file = write_test_file(&dir, "test.txt", "line 1\nline 2\nline 3\n");
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    assert_eq!(backend.total_lines(), Some(4)); // 3 lines + trailing empty
+    assert_eq!(backend.file_name(), "test.txt");
+    assert_eq!(backend.total_bytes(), 21);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn open_not_found() {
+    let cancel = AtomicBool::new(false);
+    let result = LineIndexBackend::open(&PathBuf::from("/nonexistent_lidx_test.txt"), &cancel);
+    assert!(result.is_err());
+}
+
+#[test]
+fn open_directory_fails() {
+    let dir = create_test_dir("open_dir");
+    let cancel = AtomicBool::new(false);
+    let result = LineIndexBackend::open(&dir, &cancel);
+    assert!(result.is_err());
+    cleanup(&dir);
+}
+
+#[test]
+fn open_cancellation() {
+    let dir = create_test_dir("cancel");
+    // Create a file with enough lines to potentially hit the cancel check
+    let content = "line\n".repeat(1000);
+    let file = write_test_file(&dir, "test.txt", &content);
+
+    let cancel = AtomicBool::new(true); // Pre-cancelled
+    let result = LineIndexBackend::open(&file, &cancel);
+    assert!(result.is_err());
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_from_start() {
+    let dir = create_test_dir("lines_start");
+    let file = write_test_file(&dir, "test.txt", "alpha\nbeta\ngamma\ndelta\n");
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    let chunk = backend.get_lines(&SeekTarget::Line(0), 3).unwrap();
+    assert_eq!(chunk.lines, vec!["alpha", "beta", "gamma"]);
+    assert_eq!(chunk.first_line_number, 0);
+    assert_eq!(chunk.total_lines, Some(5));
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_from_middle() {
+    let dir = create_test_dir("lines_mid");
+    let file = write_test_file(&dir, "test.txt", "a\nb\nc\nd\ne\nf\n");
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    let chunk = backend.get_lines(&SeekTarget::Line(3), 2).unwrap();
+    assert_eq!(chunk.lines, vec!["d", "e"]);
+    assert_eq!(chunk.first_line_number, 3);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_past_end() {
+    let dir = create_test_dir("lines_end");
+    let file = write_test_file(&dir, "test.txt", "a\nb\nc\n");
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    let chunk = backend.get_lines(&SeekTarget::Line(10), 5).unwrap();
+    // Should clamp to last line
+    assert_eq!(chunk.first_line_number, 3); // 4 lines (including trailing empty), last is index 3
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_by_fraction() {
+    let dir = create_test_dir("fraction");
+    let content = "line 1\nline 2\nline 3\nline 4\nline 5\n";
+    let file = write_test_file(&dir, "test.txt", content);
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    // Fraction 0.0 = first line
+    let chunk = backend.get_lines(&SeekTarget::Fraction(0.0), 1).unwrap();
+    assert_eq!(chunk.first_line_number, 0);
+    assert_eq!(chunk.lines[0], "line 1");
+
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_no_trailing_newline() {
+    let dir = create_test_dir("no_trail");
+    let file = write_test_file(&dir, "test.txt", "a\nb\nc");
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    let chunk = backend.get_lines(&SeekTarget::Line(0), 10).unwrap();
+    assert_eq!(chunk.lines, vec!["a", "b", "c"]);
+    assert_eq!(backend.total_lines(), Some(3));
+
+    cleanup(&dir);
+}
+
+#[test]
+fn sparse_index_checkpoints() {
+    let dir = create_test_dir("checkpoints");
+    // Create a file with more than INDEX_CHECKPOINT_INTERVAL lines
+    let line_count = INDEX_CHECKPOINT_INTERVAL * 3 + 50;
+    let content: String = (0..line_count).map(|i| format!("line {:06}\n", i)).collect();
+    let file = write_test_file(&dir, "test.txt", &content);
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    // Should have total_lines correct
+    assert_eq!(backend.total_lines(), Some(line_count + 1)); // +1 for trailing empty
+
+    // Seek to a line past the first checkpoint
+    let target_line = INDEX_CHECKPOINT_INTERVAL + 10;
+    let chunk = backend.get_lines(&SeekTarget::Line(target_line), 3).unwrap();
+    assert_eq!(chunk.first_line_number, target_line);
+    assert_eq!(chunk.lines[0], format!("line {:06}", target_line));
+
+    // Seek to a line past the second checkpoint
+    let target_line2 = INDEX_CHECKPOINT_INTERVAL * 2 + 5;
+    let chunk2 = backend.get_lines(&SeekTarget::Line(target_line2), 2).unwrap();
+    assert_eq!(chunk2.first_line_number, target_line2);
+    assert_eq!(chunk2.lines[0], format!("line {:06}", target_line2));
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_finds_matches() {
+    let dir = create_test_dir("search");
+    let file = write_test_file(&dir, "test.txt", "hello world\nfoo bar\nhello again\n");
+
+    let cancel_scan = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel_scan).unwrap();
+
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 2);
+    assert_eq!(matches[0].line, 0);
+    assert_eq!(matches[1].line, 2);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_case_insensitive() {
+    let dir = create_test_dir("search_case");
+    let file = write_test_file(&dir, "test.txt", "Hello\nHELLO\nhello\n");
+
+    let cancel_scan = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel_scan).unwrap();
+
+    let cancel = AtomicBool::new(false);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert_eq!(matches.len(), 3);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_cancellation() {
+    let dir = create_test_dir("search_cancel");
+    let content = "hello world\n".repeat(10000);
+    let file = write_test_file(&dir, "test.txt", &content);
+
+    let cancel_scan = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel_scan).unwrap();
+
+    let cancel = AtomicBool::new(true);
+    let results: Mutex<Vec<SearchMatch>> = Mutex::new(Vec::new());
+
+    backend.search("hello", &cancel, &results).unwrap();
+    let matches = results.lock().unwrap();
+
+    assert!(matches.len() < 10000);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn capabilities_correct() {
+    let dir = create_test_dir("caps");
+    let file = write_test_file(&dir, "test.txt", "test\n");
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+    let caps = backend.capabilities();
+
+    assert!(caps.supports_line_seek);
+    assert!(caps.supports_byte_seek);
+    assert!(caps.supports_fraction_seek);
+    assert!(caps.knows_total_lines);
+
+    cleanup(&dir);
+}
+
+#[test]
+fn empty_file() {
+    let dir = create_test_dir("empty");
+    let file = write_test_file(&dir, "test.txt", "");
+
+    let cancel = AtomicBool::new(false);
+    let backend = LineIndexBackend::open(&file, &cancel).unwrap();
+
+    assert_eq!(backend.total_bytes(), 0);
+    assert_eq!(backend.total_lines(), Some(1)); // One empty line
+
+    cleanup(&dir);
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/mod.rs b/apps/desktop/src-tauri/src/file_viewer/mod.rs
new file mode 100644
index 00000000..b64a0e9b
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/mod.rs
@@ -0,0 +1,139 @@
+//! File viewer module — on-demand line serving with three backend strategies.
+//!
+//! Backends:
+//! - `FullLoadBackend`: loads entire file into memory (small files, <1 MB)
+//! - `LineIndexBackend`: sparse line-offset index, O(lines/256) memory
+//! - `ByteSeekBackend`: byte-offset seeking, no pre-scan needed (instant open)
+
+mod byte_seek;
+mod full_load;
+mod line_index;
+mod session;
+
+#[cfg(test)]
+mod byte_seek_test;
+#[cfg(test)]
+mod full_load_test;
+#[cfg(test)]
+mod line_index_test;
+#[cfg(test)]
+mod session_test;
+
+pub use session::{
+    SearchPollResult, ViewerOpenResult, close_session, get_lines, open_session, search_cancel, search_poll,
+    search_start,
+};
+
+use serde::Serialize;
+
+/// Maximum file size for FullLoadBackend (1 MB).
+const FULL_LOAD_THRESHOLD: u64 = 1024 * 1024;
+
+/// Interval between line index checkpoints (every 256 lines).
+const INDEX_CHECKPOINT_INTERVAL: usize = 256;
+
+/// Maximum bytes to scan backward when seeking by byte offset.
+const MAX_BACKWARD_SCAN: usize = 8192;
+
+/// Where to seek in the file.
+#[derive(Debug, Clone)]
+pub enum SeekTarget {
+    /// Jump to a specific line number (0-based).
+    Line(usize),
+    /// Jump to a byte offset and find the surrounding line.
+    ByteOffset(u64),
+    /// Jump to a fraction of the file (0.0 = start, 1.0 = end).
+    Fraction(f64),
+}
+
+/// A chunk of lines returned by a backend.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LineChunk {
+    /// The lines of text.
+    pub lines: Vec<String>,
+    /// The 0-based line number of the first line in this chunk.
+    pub first_line_number: usize,
+    /// Byte offset of the first line in the file.
+    pub byte_offset: u64,
+    /// Total number of lines in the file (known after full scan or full load).
+    pub total_lines: Option<usize>,
+    /// Total file size in bytes.
+    pub total_bytes: u64,
+}
+
+/// A search match found by a backend.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SearchMatch {
+    /// 0-based line number.
+    pub line: usize,
+    /// Column (byte offset within the line) where the match starts.
+    pub column: usize,
+    /// Length of the match in bytes.
+    pub length: usize,
+}
+
+/// What a backend can do.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BackendCapabilities {
+    pub supports_line_seek: bool,
+    pub supports_byte_seek: bool,
+    pub supports_fraction_seek: bool,
+    pub knows_total_lines: bool,
+}
+
+/// Errors from the viewer backends.
+#[derive(Debug, Clone)]
+pub enum ViewerError {
+    Io(String),
+    NotFound(String),
+    IsDirectory,
+    SessionNotFound(String),
+}
+
+impl std::fmt::Display for ViewerError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Io(msg) => write!(f, "{}", msg),
+            Self::NotFound(path) => write!(f, "File not found: {}", path),
+            Self::IsDirectory => write!(f, "Cannot view a directory"),
+            Self::SessionNotFound(id) => write!(f, "Viewer session not found: {}", id),
+        }
+    }
+}
+
+impl From<std::io::Error> for ViewerError {
+    fn from(e: std::io::Error) -> Self {
+        Self::Io(e.to_string())
+    }
+}
+
+/// The interface all viewer backends implement.
+pub trait FileViewerBackend: Send + Sync {
+    /// Fetch a range of lines starting from the given target.
+    fn get_lines(&self, target: &SeekTarget, count: usize) -> Result<LineChunk, ViewerError>;
+
+    /// Search for a query string, populating matches into the provided vec.
+    /// Checks the cancel flag periodically and stops early if set.
+    /// Returns the total number of bytes scanned (for progress reporting).
+    fn search(
+        &self,
+        query: &str,
+        cancel: &std::sync::atomic::AtomicBool,
+        matches: &std::sync::Mutex<Vec<SearchMatch>>,
+    ) -> Result<u64, ViewerError>;
+
+    /// What this backend can do.
+    fn capabilities(&self) -> BackendCapabilities;
+
+    /// Total file size in bytes.
+    fn total_bytes(&self) -> u64;
+
+    /// Total lines if known (only FullLoad and completed LineIndex know this).
+    fn total_lines(&self) -> Option<usize>;
+
+    /// File name (last path component).
+    fn file_name(&self) -> &str;
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/session.rs b/apps/desktop/src-tauri/src/file_viewer/session.rs
new file mode 100644
index 00000000..f1420f35
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/session.rs
@@ -0,0 +1,324 @@
+//! ViewerSession — orchestrates file viewer backends and manages session lifecycle.
+//!
+//! Opens a file, picks the right backend based on file size, and provides a session-based
+//! API for the frontend. Sessions are cached by ID and cleaned up on close.
+
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, LazyLock, Mutex};
+use std::thread;
+
+use serde::Serialize;
+
+use super::byte_seek::ByteSeekBackend;
+use super::full_load::FullLoadBackend;
+use super::line_index::LineIndexBackend;
+use super::{
+    BackendCapabilities, FULL_LOAD_THRESHOLD, FileViewerBackend, LineChunk, SearchMatch, SeekTarget, ViewerError,
+};
+
+/// Which backend strategy is active for a session.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum BackendType {
+    FullLoad,
+    ByteSeek,
+    LineIndex,
+}
+
+/// Result returned when opening a viewer session.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ViewerOpenResult {
+    pub session_id: String,
+    pub file_name: String,
+    pub total_bytes: u64,
+    pub total_lines: Option<usize>,
+    pub backend_type: BackendType,
+    pub capabilities: BackendCapabilities,
+    /// Initial chunk of lines from the start of the file.
+    pub initial_lines: LineChunk,
+}
+
+/// Status of an ongoing search.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum SearchStatus {
+    /// Search is running. `bytes_scanned` shows progress.
+    Running,
+    /// Search completed.
+    Done,
+    /// Search was cancelled.
+    Cancelled,
+    /// No search is active.
+    Idle,
+}
+
+/// Result from polling search progress.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SearchPollResult {
+    pub status: SearchStatus,
+    pub matches: Vec<SearchMatch>,
+    pub total_bytes: u64,
+    pub bytes_scanned: u64,
+}
+
+/// Internal state for an active search.
+struct SearchState {
+    cancel: Arc<AtomicBool>,
+    matches: Arc<Mutex<Vec<SearchMatch>>>,
+    bytes_scanned: Arc<Mutex<u64>>,
+    status: Arc<Mutex<SearchStatus>>,
+}
+
+/// A viewer session wraps a backend and tracks search state.
+struct ViewerSession {
+    backend: Box<dyn FileViewerBackend>,
+    backend_type: BackendType,
+    search: Option<SearchState>,
+    /// Set when upgrading from ByteSeek to LineIndex in the background.
+    upgrading: Option<Arc<AtomicBool>>,
+    path: PathBuf,
+}
+
+/// Global session cache.
+static SESSIONS: LazyLock<Mutex<HashMap<String, ViewerSession>>> = LazyLock::new(|| Mutex::new(HashMap::new()));
+
+/// Number of initial lines to return on open.
+const INITIAL_LINE_COUNT: usize = 200;
+
+/// Generates a unique session ID.
+fn generate_session_id() -> String {
+    uuid::Uuid::new_v4().to_string()
+}
+
+/// Expands tilde (~) to the user's home directory.
+fn expand_tilde(path: &str) -> String {
+    if (path.starts_with("~/") || path == "~")
+        && let Some(home) = dirs::home_dir()
+    {
+        return path.replacen("~", &home.to_string_lossy(), 1);
+    }
+    path.to_string()
+}
+
+/// Opens a viewer session for the given file path.
+/// Picks the backend based on file size:
+/// - Under 1 MB: FullLoad (instant, full random access)
+/// - Over 1 MB: ByteSeek first (instant open), then upgrades to LineIndex in background
+pub fn open_session(path: &str) -> Result<ViewerOpenResult, ViewerError> {
+    let expanded = expand_tilde(path);
+    let file_path = PathBuf::from(&expanded);
+
+    if !file_path.exists() {
+        return Err(ViewerError::NotFound(path.to_string()));
+    }
+    if file_path.is_dir() {
+        return Err(ViewerError::IsDirectory);
+    }
+
+    let metadata = std::fs::metadata(&file_path)?;
+    let file_size = metadata.len();
+
+    let (backend, backend_type, upgrading): (Box<dyn FileViewerBackend>, BackendType, Option<Arc<AtomicBool>>) =
+        if file_size <= FULL_LOAD_THRESHOLD {
+            let b = FullLoadBackend::open(&file_path)?;
+            (Box::new(b), BackendType::FullLoad, None)
+        } else {
+            // Start with ByteSeek (instant), then upgrade to LineIndex in background
+            let b = ByteSeekBackend::open(&file_path)?;
+            let cancel = Arc::new(AtomicBool::new(false));
+            (Box::new(b), BackendType::ByteSeek, Some(cancel))
+        };
+
+    // Get initial lines
+    let initial_lines = backend.get_lines(&SeekTarget::Line(0), INITIAL_LINE_COUNT)?;
+    let capabilities = backend.capabilities();
+    let total_bytes = backend.total_bytes();
+    let total_lines = backend.total_lines();
+    let file_name = backend.file_name().to_string();
+
+    let session_id = generate_session_id();
+
+    // If we're using ByteSeek, start background upgrade to LineIndex
+    let upgrade_cancel = upgrading.clone();
+    if upgrade_cancel.is_some() {
+        let session_id_clone = session_id.clone();
+        let path_clone = file_path.clone();
+        let cancel_clone = upgrade_cancel.clone().unwrap();
+
+        thread::spawn(move || {
+            let cancel_flag = &cancel_clone;
+            match LineIndexBackend::open(&path_clone, cancel_flag) {
+                Ok(new_backend) => {
+                    if !cancel_flag.load(Ordering::Relaxed) {
+                        let mut sessions = SESSIONS.lock().unwrap();
+                        if let Some(session) = sessions.get_mut(&session_id_clone) {
+                            session.backend = Box::new(new_backend);
+                            session.backend_type = BackendType::LineIndex;
+                            session.upgrading = None;
+                        }
+                    }
+                }
+                Err(_) => {
+                    // If upgrade fails, keep using ByteSeek — it still works fine
+                }
+            }
+        });
+    }
+
+    let session = ViewerSession {
+        backend,
+        backend_type: backend_type.clone(),
+        search: None,
+        upgrading: upgrade_cancel,
+        path: file_path,
+    };
+
+    let result = ViewerOpenResult {
+        session_id: session_id.clone(),
+        file_name,
+        total_bytes,
+        total_lines,
+        backend_type,
+        capabilities,
+        initial_lines,
+    };
+
+    SESSIONS.lock().unwrap().insert(session_id, session);
+
+    Ok(result)
+}
+
+/// Gets a range of lines from a session.
+pub fn get_lines(session_id: &str, target: SeekTarget, count: usize) -> Result<LineChunk, ViewerError> {
+    let sessions = SESSIONS.lock().unwrap();
+    let session = sessions
+        .get(session_id)
+        .ok_or(ViewerError::SessionNotFound(session_id.to_string()))?;
+    session.backend.get_lines(&target, count)
+}
+
+/// Starts a background search in the given session.
+/// Any previous search is cancelled first.
+pub fn search_start(session_id: &str, query: String) -> Result<(), ViewerError> {
+    // First, cancel any existing search
+    search_cancel(session_id)?;
+
+    let cancel = Arc::new(AtomicBool::new(false));
+    let matches: Arc<Mutex<Vec<SearchMatch>>> = Arc::new(Mutex::new(Vec::new()));
+    let bytes_scanned: Arc<Mutex<u64>> = Arc::new(Mutex::new(0));
+    let status: Arc<Mutex<SearchStatus>> = Arc::new(Mutex::new(SearchStatus::Running));
+
+    let search_state = SearchState {
+        cancel: cancel.clone(),
+        matches: matches.clone(),
+        bytes_scanned: bytes_scanned.clone(),
+        status: status.clone(),
+    };
+
+    // Get the file path from the session to open a fresh file handle in the search thread
+    let path = {
+        let mut sessions = SESSIONS.lock().unwrap();
+        let session = sessions
+            .get_mut(session_id)
+            .ok_or(ViewerError::SessionNotFound(session_id.to_string()))?;
+        session.search = Some(search_state);
+        session.path.clone()
+    };
+
+    // Spawn search thread — creates its own backend for searching
+    let cancel_clone = cancel.clone();
+    let matches_clone = matches;
+    let bytes_scanned_clone = bytes_scanned;
+    let status_clone = status;
+
+    thread::spawn(move || {
+        // Use ByteSeekBackend for streaming search (low memory, works on any file)
+        let backend = match ByteSeekBackend::open(&path) {
+            Ok(b) => b,
+            Err(_) => {
+                *status_clone.lock().unwrap() = SearchStatus::Done;
+                return;
+            }
+        };
+
+        let result = backend.search(&query, &cancel_clone, &matches_clone);
+        let final_scanned: u64 = result.unwrap_or_default();
+
+        *bytes_scanned_clone.lock().unwrap() = final_scanned;
+
+        let final_status = if cancel_clone.load(Ordering::Relaxed) {
+            SearchStatus::Cancelled
+        } else {
+            SearchStatus::Done
+        };
+        *status_clone.lock().unwrap() = final_status;
+    });
+
+    Ok(())
+}
+
+/// Polls search progress for a session.
+pub fn search_poll(session_id: &str) -> Result<SearchPollResult, ViewerError> {
+    let sessions = SESSIONS.lock().unwrap();
+    let session = sessions
+        .get(session_id)
+        .ok_or(ViewerError::SessionNotFound(session_id.to_string()))?;
+
+    let total_bytes = session.backend.total_bytes();
+
+    match &session.search {
+        None => Ok(SearchPollResult {
+            status: SearchStatus::Idle,
+            matches: Vec::new(),
+            total_bytes,
+            bytes_scanned: 0,
+        }),
+        Some(search) => {
+            let status = search.status.lock().unwrap().clone();
+            let matches = search.matches.lock().unwrap().clone();
+            let bytes_scanned = *search.bytes_scanned.lock().unwrap();
+
+            Ok(SearchPollResult {
+                status,
+                matches,
+                total_bytes,
+                bytes_scanned,
+            })
+        }
+    }
+}
+
+/// Cancels an ongoing search.
+pub fn search_cancel(session_id: &str) -> Result<(), ViewerError> {
+    let mut sessions = SESSIONS.lock().unwrap();
+    let session = sessions
+        .get_mut(session_id)
+        .ok_or(ViewerError::SessionNotFound(session_id.to_string()))?;
+
+    if let Some(search) = &session.search {
+        search.cancel.store(true, Ordering::Relaxed);
+    }
+    session.search = None;
+
+    Ok(())
+}
+
+/// Closes a viewer session and frees resources.
+pub fn close_session(session_id: &str) -> Result<(), ViewerError> {
+    let mut sessions = SESSIONS.lock().unwrap();
+    if let Some(session) = sessions.remove(session_id) {
+        // Cancel any ongoing search
+        if let Some(search) = &session.search {
+            search.cancel.store(true, Ordering::Relaxed);
+        }
+        // Cancel any ongoing upgrade
+        if let Some(upgrade_cancel) = &session.upgrading {
+            upgrade_cancel.store(true, Ordering::Relaxed);
+        }
+    }
+    Ok(())
+}
diff --git a/apps/desktop/src-tauri/src/file_viewer/session_test.rs b/apps/desktop/src-tauri/src/file_viewer/session_test.rs
new file mode 100644
index 00000000..0e0c1aea
--- /dev/null
+++ b/apps/desktop/src-tauri/src/file_viewer/session_test.rs
@@ -0,0 +1,254 @@
+//! Tests for ViewerSession orchestrator.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::thread;
+use std::time::Duration;
+
+use super::FULL_LOAD_THRESHOLD;
+use super::session::{self, SearchStatus};
+
+fn create_test_dir(name: &str) -> PathBuf {
+    let dir = std::env::temp_dir().join(format!("cmdr_viewer_session_{}", name));
+    let _ = fs::remove_dir_all(&dir);
+    fs::create_dir_all(&dir).expect("Failed to create test directory");
+    dir
+}
+
+fn cleanup(path: &Path) {
+    let _ = fs::remove_dir_all(path);
+}
+
+fn write_test_file(dir: &Path, name: &str, content: &str) -> PathBuf {
+    let file = dir.join(name);
+    fs::write(&file, content).unwrap();
+    file
+}
+
+#[test]
+fn open_small_file_uses_full_load() {
+    let dir = create_test_dir("small");
+    let file = write_test_file(&dir, "test.txt", "hello\nworld\n");
+
+    let result = session::open_session(file.to_str().unwrap()).unwrap();
+    assert_eq!(result.file_name, "test.txt");
+    assert_eq!(result.total_bytes, 12);
+    assert_eq!(result.total_lines, Some(3));
+    assert!(matches!(result.backend_type, session::BackendType::FullLoad));
+    assert!(result.capabilities.supports_line_seek);
+    assert!(result.capabilities.knows_total_lines);
+
+    // Initial lines should be populated
+    assert!(!result.initial_lines.lines.is_empty());
+    assert_eq!(result.initial_lines.first_line_number, 0);
+
+    // Cleanup session
+    session::close_session(&result.session_id).unwrap();
+    cleanup(&dir);
+}
+
+#[test]
+fn open_large_file_uses_byte_seek() {
+    let dir = create_test_dir("large");
+    // Create a file larger than FULL_LOAD_THRESHOLD
+    let line = "x".repeat(100) + "\n";
+    let line_count = (FULL_LOAD_THRESHOLD as usize / line.len()) + 100;
+    let content: String = line.repeat(line_count);
+    let file = write_test_file(&dir, "big.txt", &content);
+
+    let result = session::open_session(file.to_str().unwrap()).unwrap();
+    assert!(result.total_bytes > FULL_LOAD_THRESHOLD);
+    assert!(matches!(result.backend_type, session::BackendType::ByteSeek));
+    assert!(!result.capabilities.supports_line_seek);
+    assert!(!result.capabilities.knows_total_lines);
+
+    // Should still have initial lines
+    assert!(!result.initial_lines.lines.is_empty());
+
+    session::close_session(&result.session_id).unwrap();
+    cleanup(&dir);
+}
+
+#[test]
+fn open_not_found() {
+    let result = session::open_session("/nonexistent_session_test.txt");
+    assert!(result.is_err());
+}
+
+#[test]
+fn open_directory_fails() {
+    let dir = create_test_dir("dir_fail");
+    let result = session::open_session(dir.to_str().unwrap());
+    assert!(result.is_err());
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_after_open() {
+    let dir = create_test_dir("get_lines");
+    let file = write_test_file(&dir, "test.txt", "a\nb\nc\nd\ne\n");
+
+    let open_result = session::open_session(file.to_str().unwrap()).unwrap();
+
+    let chunk = session::get_lines(&open_result.session_id, super::SeekTarget::Line(2), 3).unwrap();
+    assert_eq!(chunk.first_line_number, 2);
+    assert_eq!(chunk.lines, vec!["c", "d", "e"]);
+
+    session::close_session(&open_result.session_id).unwrap();
+    cleanup(&dir);
+}
+
+#[test]
+fn get_lines_invalid_session() {
+    let result = session::get_lines("nonexistent-session-id", super::SeekTarget::Line(0), 10);
+    assert!(result.is_err());
+}
+
+#[test]
+fn close_session_cleans_up() {
+    let dir = create_test_dir("close");
+    let file = write_test_file(&dir, "test.txt", "test\n");
+
+    let open_result = session::open_session(file.to_str().unwrap()).unwrap();
+    let sid = open_result.session_id.clone();
+
+    // Session should work
+    assert!(session::get_lines(&sid, super::SeekTarget::Line(0), 1).is_ok());
+
+    // Close it
+    session::close_session(&sid).unwrap();
+
+    // Now it should fail
+    assert!(session::get_lines(&sid, super::SeekTarget::Line(0), 1).is_err());
+
+    cleanup(&dir);
+}
+
+#[test]
+fn search_start_and_poll() {
+    let dir = create_test_dir("search");
+    let file = write_test_file(&dir, "test.txt", "hello world\nfoo bar\nhello again\n");
+
+    let open_result = session::open_session(file.to_str().unwrap()).unwrap();
+    let sid = &open_result.session_id;
+
+    // Start search
+    session::search_start(sid, "hello".to_string()).unwrap();
+
+    // Poll until done (with timeout)
+    let mut done = false;
+    for _ in 0..100 {
+        let poll = session::search_poll(sid).unwrap();
+        if matches!(poll.status, SearchStatus::Done) {
+            assert_eq!(poll.matches.len(), 2);
+            done = true;
+            break;
+        }
+        thread::sleep(Duration::from_millis(10));
+    }
+    assert!(done, "Search did not complete in time");
+
+    session::close_session(sid).unwrap();
+    cleanup(&dir);
+}
+
+#[test]
+fn search_cancel_works() {
+    let dir = create_test_dir("search_cancel");
+    let content = "hello world\n".repeat(100000);
+    let file = write_test_file(&dir, "test.txt", &content);
+
+    let open_result = session::open_session(file.to_str().unwrap()).unwrap();
+    let sid = &open_result.session_id;
+
+    session::search_start(sid, "hello".to_string()).unwrap();
+
+    // Cancel immediately
+    session::search_cancel(sid).unwrap();
+
+    // Poll should show cancelled or idle (since we removed the search state)
+    let poll = session::search_poll(sid).unwrap();
+    assert!(matches!(poll.status, SearchStatus::Idle));
+
+    session::close_session(sid).unwrap();
+    cleanup(&dir);
+}
+
+#[test]
+fn search_poll_no_active_search() {
+    let dir = create_test_dir("poll_idle");
+    let file = write_test_file(&dir, "test.txt", "test\n");
+
+    let open_result = session::open_session(file.to_str().unwrap()).unwrap();
+    let sid = &open_result.session_id;
+
+    let poll = session::search_poll(sid).unwrap();
+    assert!(matches!(poll.status, SearchStatus::Idle));
+
+    session::close_session(sid).unwrap();
+    cleanup(&dir);
+}
+
+#[test]
+fn tilde_expansion() {
+    // open_session should handle ~ paths
+    let result = session::open_session("~/nonexistent_file_tilde_test.txt");
+    // Should get NotFound rather than a panic/crash
+    assert!(result.is_err());
+}
+
+#[test]
+fn large_file_upgrades_to_line_index() {
+    let dir = create_test_dir("upgrade");
+    // Create a file larger than FULL_LOAD_THRESHOLD (1 MB) with known lines.
+    // Each line is ~115 bytes ("line 00000000 " + 100 x's + "\n").
+    let padding = "x".repeat(100);
+    let line_count = (FULL_LOAD_THRESHOLD as usize / 100) + 200;
+    let content: String = (0..line_count)
+        .map(|i| format!("line {:08} {}\n", i, padding))
+        .collect();
+    let file = write_test_file(&dir, "upgrade.txt", &content);
+
+    let open_result = session::open_session(file.to_str().unwrap()).unwrap();
+    let sid = &open_result.session_id;
+
+    // Initially ByteSeek
+    assert!(matches!(open_result.backend_type, session::BackendType::ByteSeek));
+
+    // Wait for upgrade to complete (should be fast for a ~1MB file)
+    thread::sleep(Duration::from_millis(500));
+
+    // After upgrade, get_lines with Line target should work correctly
+    let chunk = session::get_lines(sid, super::SeekTarget::Line(10), 3).unwrap();
+    // If upgraded to LineIndex, first_line_number should be correct
+    // If still ByteSeek, it will default to 0
+    // We check that it works either way
+    assert!(!chunk.lines.is_empty());
+
+    session::close_session(sid).unwrap();
+    cleanup(&dir);
+}
+
+#[test]
+fn multiple_sessions() {
+    let dir = create_test_dir("multi");
+    let file1 = write_test_file(&dir, "a.txt", "file a\n");
+    let file2 = write_test_file(&dir, "b.txt", "file b\n");
+
+    let res1 = session::open_session(file1.to_str().unwrap()).unwrap();
+    let res2 = session::open_session(file2.to_str().unwrap()).unwrap();
+
+    assert_ne!(res1.session_id, res2.session_id);
+    assert_eq!(res1.file_name, "a.txt");
+    assert_eq!(res2.file_name, "b.txt");
+
+    // Both should work independently
+    let chunk1 = session::get_lines(&res1.session_id, super::SeekTarget::Line(0), 1).unwrap();
+    let chunk2 = session::get_lines(&res2.session_id, super::SeekTarget::Line(0), 1).unwrap();
+    assert_eq!(chunk1.lines[0], "file a");
+    assert_eq!(chunk2.lines[0], "file b");
+
+    session::close_session(&res1.session_id).unwrap();
+    session::close_session(&res2.session_id).unwrap();
+    cleanup(&dir);
+}
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index c473f8d9..3f5325d9 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -45,6 +45,7 @@ pub mod benchmark;
 mod commands;
 pub mod config;
 mod file_system;
+pub(crate) mod file_viewer;
 mod font_metrics;
 pub mod icons;
 pub mod licensing;
@@ -280,7 +281,12 @@ pub fn run() {
             commands::file_system::get_operation_status,
             commands::file_system::get_listing_stats,
             commands::file_system::start_selection_drag,
-            commands::file_system::read_file_content,
+            commands::file_viewer::viewer_open,
+            commands::file_viewer::viewer_get_lines,
+            commands::file_viewer::viewer_search_start,
+            commands::file_viewer::viewer_search_poll,
+            commands::file_viewer::viewer_search_cancel,
+            commands::file_viewer::viewer_close,
             commands::font_metrics::store_font_metrics,
             commands::font_metrics::has_font_metrics,
             commands::icons::get_icons,
diff --git a/apps/desktop/src/lib/file-viewer/viewer-search.test.ts b/apps/desktop/src/lib/file-viewer/viewer-search.test.ts
deleted file mode 100644
index 9dd26c93..00000000
--- a/apps/desktop/src/lib/file-viewer/viewer-search.test.ts
+++ /dev/null
@@ -1,86 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { findMatches, nextMatchIndex, prevMatchIndex } from './viewer-search'
-
-describe('findMatches', () => {
-    it('returns empty array for empty query', () => {
-        expect(findMatches(['hello world'], '')).toEqual([])
-    })
-
-    it('finds a single match on a single line', () => {
-        const matches = findMatches(['hello world'], 'world')
-        expect(matches).toEqual([{ line: 0, start: 6, length: 5 }])
-    })
-
-    it('finds multiple matches on the same line', () => {
-        const matches = findMatches(['foo bar foo baz foo'], 'foo')
-        expect(matches).toHaveLength(3)
-        expect(matches[0]).toEqual({ line: 0, start: 0, length: 3 })
-        expect(matches[1]).toEqual({ line: 0, start: 8, length: 3 })
-        expect(matches[2]).toEqual({ line: 0, start: 16, length: 3 })
-    })
-
-    it('finds matches across multiple lines', () => {
-        const matches = findMatches(['first line', 'second test', 'third line'], 'line')
-        expect(matches).toHaveLength(2)
-        expect(matches[0]).toEqual({ line: 0, start: 6, length: 4 })
-        expect(matches[1]).toEqual({ line: 2, start: 6, length: 4 })
-    })
-
-    it('is case-insensitive', () => {
-        const matches = findMatches(['Hello WORLD'], 'hello')
-        expect(matches).toHaveLength(1)
-        expect(matches[0]).toEqual({ line: 0, start: 0, length: 5 })
-    })
-
-    it('returns empty for no matches', () => {
-        expect(findMatches(['hello world'], 'xyz')).toEqual([])
-    })
-
-    it('handles empty lines', () => {
-        const matches = findMatches(['', 'hello', ''], 'hello')
-        expect(matches).toEqual([{ line: 1, start: 0, length: 5 }])
-    })
-
-    it('handles overlapping potential matches (non-overlapping search)', () => {
-        // "aaa" in "aaaa" should find at 0 and 1 (overlapping start positions)
-        const matches = findMatches(['aaaa'], 'aaa')
-        expect(matches).toHaveLength(2)
-        expect(matches[0]).toEqual({ line: 0, start: 0, length: 3 })
-        expect(matches[1]).toEqual({ line: 0, start: 1, length: 3 })
-    })
-
-    it('handles special regex characters in query', () => {
-        const matches = findMatches(['price is $10.00'], '$10')
-        expect(matches).toEqual([{ line: 0, start: 9, length: 3 }])
-    })
-})
-
-describe('nextMatchIndex', () => {
-    it('returns -1 for zero total', () => {
-        expect(nextMatchIndex(0, 0)).toBe(-1)
-    })
-
-    it('advances to the next index', () => {
-        expect(nextMatchIndex(0, 5)).toBe(1)
-        expect(nextMatchIndex(3, 5)).toBe(4)
-    })
-
-    it('wraps around at the end', () => {
-        expect(nextMatchIndex(4, 5)).toBe(0)
-    })
-})
-
-describe('prevMatchIndex', () => {
-    it('returns -1 for zero total', () => {
-        expect(prevMatchIndex(0, 0)).toBe(-1)
-    })
-
-    it('moves to the previous index', () => {
-        expect(prevMatchIndex(3, 5)).toBe(2)
-        expect(prevMatchIndex(1, 5)).toBe(0)
-    })
-
-    it('wraps around at the beginning', () => {
-        expect(prevMatchIndex(0, 5)).toBe(4)
-    })
-})
diff --git a/apps/desktop/src/lib/file-viewer/viewer-search.ts b/apps/desktop/src/lib/file-viewer/viewer-search.ts
deleted file mode 100644
index 7316e655..00000000
--- a/apps/desktop/src/lib/file-viewer/viewer-search.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-/** A single search match location. */
-export interface SearchMatch {
-    /** 0-based line index */
-    line: number
-    /** 0-based character offset within the line */
-    start: number
-    /** Length of the match in characters */
-    length: number
-}
-
-/** Finds all occurrences of a query in the given lines (case-insensitive). */
-export function findMatches(lines: string[], query: string): SearchMatch[] {
-    if (!query) return []
-    const lowerQuery = query.toLowerCase()
-    const matches: SearchMatch[] = []
-    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
-        const lowerLine = lines[lineIdx].toLowerCase()
-        let offset = 0
-        while (offset < lowerLine.length) {
-            const idx = lowerLine.indexOf(lowerQuery, offset)
-            if (idx === -1) break
-            matches.push({ line: lineIdx, start: idx, length: query.length })
-            offset = idx + 1
-        }
-    }
-    return matches
-}
-
-/** Navigates to the next match index, wrapping around. */
-export function nextMatchIndex(current: number, total: number): number {
-    if (total === 0) return -1
-    return (current + 1) % total
-}
-
-/** Navigates to the previous match index, wrapping around. */
-export function prevMatchIndex(current: number, total: number): number {
-    if (total === 0) return -1
-    return (current - 1 + total) % total
-}
diff --git a/apps/desktop/src/lib/tauri-commands.ts b/apps/desktop/src/lib/tauri-commands.ts
index 416a2812..6bcbcac3 100644
--- a/apps/desktop/src/lib/tauri-commands.ts
+++ b/apps/desktop/src/lib/tauri-commands.ts
@@ -287,17 +287,82 @@ export async function createDirectory(parentPath: string, name: string): Promise
 // File viewer
 // ============================================================================
 
-/** Result of reading a file's content for the viewer. */
-export interface FileContentResult {
-    content: string
-    lineCount: number
-    size: number
+/** A chunk of lines returned by the viewer backend. */
+export interface LineChunk {
+    lines: string[]
+    firstLineNumber: number
+    byteOffset: number
+    totalLines: number | null
+    totalBytes: number
+}
+
+/** Backend capabilities. */
+export interface BackendCapabilities {
+    supportsLineSeek: boolean
+    supportsByteSeek: boolean
+    supportsFractionSeek: boolean
+    knowsTotalLines: boolean
+}
+
+/** Result from opening a viewer session. */
+export interface ViewerOpenResult {
+    sessionId: string
     fileName: string
+    totalBytes: number
+    totalLines: number | null
+    backendType: 'fullLoad' | 'byteSeek' | 'lineIndex'
+    capabilities: BackendCapabilities
+    initialLines: LineChunk
+}
+
+/** A search match found in the file. */
+export interface ViewerSearchMatch {
+    line: number
+    column: number
+    length: number
+}
+
+/** Result from polling search progress. */
+export interface SearchPollResult {
+    status: 'running' | 'done' | 'cancelled' | 'idle'
+    matches: ViewerSearchMatch[]
+    totalBytes: number
+    bytesScanned: number
+}
+
+/** Opens a viewer session for a file. Returns session metadata + initial lines. */
+export async function viewerOpen(path: string): Promise<ViewerOpenResult> {
+    return invoke<ViewerOpenResult>('viewer_open', { path })
+}
+
+/** Fetches lines from a viewer session. */
+export async function viewerGetLines(
+    sessionId: string,
+    targetType: 'line' | 'byte' | 'fraction',
+    targetValue: number,
+    count: number,
+): Promise<LineChunk> {
+    return invoke<LineChunk>('viewer_get_lines', { sessionId, targetType, targetValue, count })
+}
+
+/** Starts a background search in the viewer session. */
+export async function viewerSearchStart(sessionId: string, query: string): Promise<void> {
+    return invoke<void>('viewer_search_start', { sessionId, query })
+}
+
+/** Polls search progress and matches. */
+export async function viewerSearchPoll(sessionId: string): Promise<SearchPollResult> {
+    return invoke<SearchPollResult>('viewer_search_poll', { sessionId })
+}
+
+/** Cancels an ongoing search. */
+export async function viewerSearchCancel(sessionId: string): Promise<void> {
+    return invoke<void>('viewer_search_cancel', { sessionId })
 }
 
-/** Reads a file's text content for the file viewer. Binary bytes are lossy-decoded. */
-export async function readFileContent(path: string): Promise<FileContentResult> {
-    return invoke<FileContentResult>('read_file_content', { path })
+/** Closes a viewer session and frees resources. */
+export async function viewerClose(sessionId: string): Promise<void> {
+    return invoke<void>('viewer_close', { sessionId })
 }
 
 /**
diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
index f11270ea..0454a6f1 100644
--- a/apps/desktop/src/routes/viewer/+page.svelte
+++ b/apps/desktop/src/routes/viewer/+page.svelte
@@ -5,57 +5,178 @@
         if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
         return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
     }
+
+    const LINE_HEIGHT = 18
+    const BUFFER_LINES = 50
+    const FETCH_BATCH = 500
+    const SEARCH_POLL_INTERVAL = 100
 </script>
 
 <script lang="ts">
-    import { onMount, tick } from 'svelte'
-    import { findMatches, nextMatchIndex, prevMatchIndex, type SearchMatch } from '$lib/file-viewer/viewer-search'
+    import { onMount, onDestroy, tick } from 'svelte'
+    import type { ViewerSearchMatch } from '$lib/tauri-commands'
 
-    let content = $state('')
-    let lines = $state<string[]>([])
     let fileName = $state('')
-    let lineCount = $state(0)
-    let fileSize = $state(0)
+    let totalLines = $state<number | null>(null)
+    let totalBytes = $state(0)
     let error = $state('')
     let loading = $state(true)
+    let sessionId = $state('')
+    let backendType = $state<'fullLoad' | 'byteSeek' | 'lineIndex'>('fullLoad')
+
+    // Line cache: lineNumber -> text
+    let lineCache = $state<Map<number, string>>(new Map())
+    // The range of lines currently in cache
+    let cachedFrom = $state(0)
+    let cachedTo = $state(0)
+
+    // Virtual scroll state
+    let scrollTop = $state(0)
+    let viewportHeight = $state(600)
+    let contentRef: HTMLDivElement | undefined = $state()
+
+    // Derived: which lines are visible
+    const visibleFrom = $derived(Math.max(0, Math.floor(scrollTop / LINE_HEIGHT) - BUFFER_LINES))
+    const visibleTo = $derived(
+        Math.min(estimatedTotalLines(), Math.ceil((scrollTop + viewportHeight) / LINE_HEIGHT) + BUFFER_LINES),
+    )
+    const visibleLines = $derived(getVisibleLines())
+    const gutterWidth = $derived(String(estimatedTotalLines()).length)
 
     // Search state
     let searchVisible = $state(false)
     let searchQuery = $state('')
-    let matches = $state<SearchMatch[]>([])
+    let searchMatches = $state<ViewerSearchMatch[]>([])
     let currentMatchIndex = $state(-1)
+    let searchStatus = $state<'idle' | 'running' | 'done' | 'cancelled'>('idle')
+    let searchProgress = $state(0)
     let searchInputRef: HTMLInputElement | undefined = $state()
+    let searchPollTimer: ReturnType<typeof setInterval> | undefined
 
-    // Viewer container ref for scrolling
-    let viewerRef: HTMLDivElement | undefined = $state()
+    // Track pending fetches to avoid duplicate requests
+    let fetchingRange = $state(false)
 
-    // Compute line number gutter width based on total lines
-    const gutterWidth = $derived(String(lineCount).length)
+    function estimatedTotalLines(): number {
+        if (totalLines !== null) return totalLines
+        // Estimate based on average 80 bytes per line
+        return Math.max(1, Math.ceil(totalBytes / 80))
+    }
 
-    // Update matches when query or content changes
-    $effect(() => {
-        if (searchQuery && lines.length > 0) {
-            matches = findMatches(lines, searchQuery)
-            currentMatchIndex = matches.length > 0 ? 0 : -1
-        } else {
-            matches = []
-            currentMatchIndex = -1
+    function getVisibleLines(): Array<{ lineNumber: number; text: string }> {
+        const result: Array<{ lineNumber: number; text: string }> = []
+        const end = Math.min(visibleTo, estimatedTotalLines())
+        for (let i = visibleFrom; i < end; i++) {
+            result.push({ lineNumber: i, text: lineCache.get(i) ?? '' })
         }
-    })
+        return result
+    }
 
-    // Scroll to current match when it changes
+    // Fetch lines when visible range changes
     $effect(() => {
-        if (currentMatchIndex >= 0 && matches[currentMatchIndex]) {
-            scrollToMatch(matches[currentMatchIndex])
+        const from = visibleFrom
+        const to = visibleTo
+        if (sessionId && !fetchingRange) {
+            // Check if we need to fetch
+            if (from < cachedFrom || to > cachedTo) {
+                void fetchLines(from, to)
+            }
         }
     })
 
-    function scrollToMatch(match: SearchMatch) {
-        if (!viewerRef) return
-        const lineEl = viewerRef.querySelector(`[data-line="${String(match.line)}"]`)
-        if (lineEl) {
-            lineEl.scrollIntoView({ block: 'center', behavior: 'smooth' })
+    async function fetchLines(from: number, to: number) {
+        if (!sessionId || fetchingRange) return
+        fetchingRange = true
+        try {
+            const { viewerGetLines } = await import('$lib/tauri-commands')
+            // Fetch a larger batch to reduce round-trips
+            const fetchFrom = Math.max(0, from - BUFFER_LINES)
+            const fetchCount = Math.min(FETCH_BATCH, to - fetchFrom + BUFFER_LINES * 2)
+            const chunk = await viewerGetLines(sessionId, 'line', fetchFrom, fetchCount)
+
+            // Update cache
+            const newCache = new Map(lineCache)
+            for (let i = 0; i < chunk.lines.length; i++) {
+                newCache.set(chunk.firstLineNumber + i, chunk.lines[i])
+            }
+            lineCache = newCache
+            cachedFrom = Math.min(cachedFrom, chunk.firstLineNumber)
+            cachedTo = Math.max(cachedTo, chunk.firstLineNumber + chunk.lines.length)
+
+            // Update totalLines if backend now knows it
+            if (chunk.totalLines !== null) {
+                totalLines = chunk.totalLines
+            }
+        } catch {
+            // Fetch failed, will retry on next scroll
+        } finally {
+            fetchingRange = false
+        }
+    }
+
+    function handleScroll() {
+        if (contentRef) {
+            scrollTop = contentRef.scrollTop
+            viewportHeight = contentRef.clientHeight
+        }
+    }
+
+    // Search functions
+    async function startSearch(query: string) {
+        if (!sessionId || !query) return
+        searchMatches = []
+        currentMatchIndex = -1
+        searchStatus = 'running'
+        searchProgress = 0
+
+        try {
+            const { viewerSearchStart } = await import('$lib/tauri-commands')
+            await viewerSearchStart(sessionId, query)
+            pollSearch()
+        } catch {
+            searchStatus = 'idle'
+        }
+    }
+
+    function pollSearch() {
+        stopSearchPoll()
+        searchPollTimer = setInterval(async () => {
+            if (!sessionId) return
+            try {
+                const { viewerSearchPoll } = await import('$lib/tauri-commands')
+                const result = await viewerSearchPoll(sessionId)
+                searchMatches = result.matches
+                searchProgress = totalBytes > 0 ? result.bytesScanned / totalBytes : 0
+                if (currentMatchIndex === -1 && result.matches.length > 0) {
+                    currentMatchIndex = 0
+                }
+                if (result.status !== 'running') {
+                    searchStatus = result.status as 'done' | 'cancelled' | 'idle'
+                    stopSearchPoll()
+                }
+            } catch {
+                stopSearchPoll()
+                searchStatus = 'idle'
+            }
+        }, SEARCH_POLL_INTERVAL)
+    }
+
+    function stopSearchPoll() {
+        if (searchPollTimer) {
+            clearInterval(searchPollTimer)
+            searchPollTimer = undefined
+        }
+    }
+
+    async function cancelSearch() {
+        stopSearchPoll()
+        if (!sessionId) return
+        try {
+            const { viewerSearchCancel } = await import('$lib/tauri-commands')
+            await viewerSearchCancel(sessionId)
+        } catch {
+            // Ignore
         }
+        searchStatus = 'idle'
     }
 
     function openSearch() {
@@ -69,21 +190,55 @@
     function closeSearch() {
         searchVisible = false
         searchQuery = ''
-        matches = []
+        void cancelSearch()
+        searchMatches = []
         currentMatchIndex = -1
+        searchProgress = 0
     }
 
     function findNext() {
-        if (matches.length === 0) return
-        currentMatchIndex = nextMatchIndex(currentMatchIndex, matches.length)
+        if (searchMatches.length === 0) return
+        currentMatchIndex = (currentMatchIndex + 1) % searchMatches.length
+        scrollToMatch(searchMatches[currentMatchIndex])
     }
 
     function findPrev() {
-        if (matches.length === 0) return
-        currentMatchIndex = prevMatchIndex(currentMatchIndex, matches.length)
+        if (searchMatches.length === 0) return
+        currentMatchIndex = (currentMatchIndex - 1 + searchMatches.length) % searchMatches.length
+        scrollToMatch(searchMatches[currentMatchIndex])
+    }
+
+    function scrollToMatch(match: ViewerSearchMatch) {
+        if (!contentRef) return
+        const targetScroll = match.line * LINE_HEIGHT - viewportHeight / 2
+        contentRef.scrollTop = Math.max(0, targetScroll)
     }
 
+    // Debounce search input
+    let searchDebounceTimer: ReturnType<typeof setTimeout> | undefined
+    $effect(() => {
+        const query = searchQuery
+        if (searchDebounceTimer) clearTimeout(searchDebounceTimer)
+        if (query && searchVisible) {
+            searchDebounceTimer = setTimeout(() => {
+                void startSearch(query)
+            }, 300)
+        } else {
+            void cancelSearch()
+            searchMatches = []
+            currentMatchIndex = -1
+        }
+    })
+
     async function closeWindow() {
+        if (sessionId) {
+            try {
+                const { viewerClose } = await import('$lib/tauri-commands')
+                await viewerClose(sessionId)
+            } catch {
+                // Ignore
+            }
+        }
         try {
             const { getCurrentWindow } = await import('@tauri-apps/api/window')
             await getCurrentWindow().close()
@@ -93,14 +248,12 @@
     }
 
     function handleKeyDown(e: KeyboardEvent) {
-        // Cmd+F or Ctrl+F: open search
         if ((e.metaKey || e.ctrlKey) && e.key === 'f') {
             e.preventDefault()
             openSearch()
             return
         }
 
-        // Escape: close search first, then close window
         if (e.key === 'Escape') {
             e.preventDefault()
             if (searchVisible) {
@@ -111,7 +264,6 @@
             return
         }
 
-        // Enter in search: find next (Shift+Enter: find previous)
         if (e.key === 'Enter' && searchVisible) {
             e.preventDefault()
             if (e.shiftKey) {
@@ -122,9 +274,9 @@
         }
     }
 
-    /** Renders a line with search highlights. Returns an array of segments. */
-    function getHighlightedSegments(lineIdx: number, lineText: string) {
-        const lineMatches = matches.filter((m) => m.line === lineIdx)
+    /** Highlights search matches within a line. */
+    function getHighlightedSegments(lineNumber: number, lineText: string) {
+        const lineMatches = searchMatches.filter((m) => m.line === lineNumber)
         if (lineMatches.length === 0) {
             return [{ text: lineText, highlight: false, active: false }]
         }
@@ -132,12 +284,16 @@
         const segments: Array<{ text: string; highlight: boolean; active: boolean }> = []
         let pos = 0
         for (const m of lineMatches) {
-            if (m.start > pos) {
-                segments.push({ text: lineText.slice(pos, m.start), highlight: false, active: false })
+            if (m.column > pos) {
+                segments.push({ text: lineText.slice(pos, m.column), highlight: false, active: false })
             }
-            const isActive = matches.indexOf(m) === currentMatchIndex
-            segments.push({ text: lineText.slice(m.start, m.start + m.length), highlight: true, active: isActive })
-            pos = m.start + m.length
+            const isActive = searchMatches.indexOf(m) === currentMatchIndex
+            segments.push({
+                text: lineText.slice(m.column, m.column + m.length),
+                highlight: true,
+                active: isActive,
+            })
+            pos = m.column + m.length
         }
         if (pos < lineText.length) {
             segments.push({ text: lineText.slice(pos), highlight: false, active: false })
@@ -146,13 +302,11 @@
     }
 
     onMount(async () => {
-        // Hide the loading screen
         const loadingScreen = document.getElementById('loading-screen')
         if (loadingScreen) {
             loadingScreen.style.display = 'none'
         }
 
-        // Get file path from URL query parameter
         const params = new URLSearchParams(window.location.search)
         const filePath = params.get('path')
 
@@ -163,13 +317,23 @@
         }
 
         try {
-            const { readFileContent } = await import('$lib/tauri-commands')
-            const result = await readFileContent(filePath)
-            content = result.content
-            lines = content.split('\n')
+            const { viewerOpen } = await import('$lib/tauri-commands')
+            const result = await viewerOpen(filePath)
+
+            sessionId = result.sessionId
             fileName = result.fileName
-            lineCount = result.lineCount
-            fileSize = result.size
+            totalBytes = result.totalBytes
+            totalLines = result.totalLines
+            backendType = result.backendType
+
+            // Populate cache with initial lines
+            const newCache = new Map<number, string>()
+            for (let i = 0; i < result.initialLines.lines.length; i++) {
+                newCache.set(result.initialLines.firstLineNumber + i, result.initialLines.lines[i])
+            }
+            lineCache = newCache
+            cachedFrom = result.initialLines.firstLineNumber
+            cachedTo = result.initialLines.firstLineNumber + result.initialLines.lines.length
 
             // Set window title
             try {
@@ -184,10 +348,15 @@
             loading = false
         }
     })
+
+    onDestroy(() => {
+        stopSearchPoll()
+        if (searchDebounceTimer) clearTimeout(searchDebounceTimer)
+    })
 </script>
 
 <!-- svelte-ignore a11y_no_static_element_interactions -->
-<div class="viewer-container" onkeydown={handleKeyDown} tabindex={-1} bind:this={viewerRef}>
+<div class="viewer-container" onkeydown={handleKeyDown} tabindex={-1}>
     {#if searchVisible}
         <div class="search-bar" role="search">
             <input
@@ -199,21 +368,23 @@
                 class="search-input"
             />
             <span class="match-count" aria-live="polite">
-                {#if matches.length > 0}
-                    {currentMatchIndex + 1} of {matches.length}
-                {:else if searchQuery}
+                {#if searchMatches.length > 0}
+                    {currentMatchIndex + 1} of {searchMatches.length}
+                {:else if searchStatus === 'running'}
+                    Searching... {Math.round(searchProgress * 100)}%
+                {:else if searchQuery && searchStatus === 'done'}
                     No matches
                 {/if}
             </span>
             <button
                 onclick={findPrev}
-                disabled={matches.length === 0}
+                disabled={searchMatches.length === 0}
                 aria-label="Previous match"
                 title="Previous match (Shift+Enter)">&#x25B2;</button
             >
             <button
                 onclick={findNext}
-                disabled={matches.length === 0}
+                disabled={searchMatches.length === 0}
                 aria-label="Next match"
                 title="Next match (Enter)">&#x25BC;</button
             >
@@ -226,24 +397,41 @@
     {:else if error}
         <div class="status-message error">{error}</div>
     {:else}
-        <div class="file-content" role="document" aria-label="File content: {fileName}">
-            {#each lines as line, idx (idx)}
-                <div class="line" data-line={idx}>
-                    <span class="line-number" style="width: {gutterWidth}ch" aria-hidden="true">{idx + 1}</span>
-                    <span class="line-text"
-                        >{#each getHighlightedSegments(idx, line) as seg, segIdx (segIdx)}{#if seg.highlight}<mark
-                                    class:active={seg.active}>{seg.text}</mark
-                                >{:else}{seg.text}{/if}{/each}</span
-                    >
+        <div
+            class="file-content"
+            role="document"
+            aria-label="File content: {fileName}"
+            bind:this={contentRef}
+            onscroll={handleScroll}
+        >
+            <div class="scroll-spacer" style="height: {estimatedTotalLines() * LINE_HEIGHT}px">
+                <div class="lines-container" style="transform: translateY({visibleFrom * LINE_HEIGHT}px)">
+                    {#each visibleLines as { lineNumber, text } (lineNumber)}
+                        <div class="line" data-line={lineNumber}>
+                            <span class="line-number" style="width: {gutterWidth}ch" aria-hidden="true"
+                                >{lineNumber + 1}</span
+                            >
+                            <span class="line-text"
+                                >{#each getHighlightedSegments(lineNumber, text) as seg, segIdx (segIdx)}{#if seg.highlight}<mark
+                                            class:active={seg.active}>{seg.text}</mark
+                                        >{:else}{seg.text}{/if}{/each}</span
+                            >
+                        </div>
+                    {/each}
                 </div>
-            {/each}
+            </div>
         </div>
     {/if}
 
     <div class="status-bar" aria-label="File information">
         <span>{fileName}</span>
-        <span>{lineCount} {lineCount === 1 ? 'line' : 'lines'}</span>
-        <span>{formatSize(fileSize)}</span>
+        {#if totalLines !== null}
+            <span>{totalLines} {totalLines === 1 ? 'line' : 'lines'}</span>
+        {/if}
+        <span>{formatSize(totalBytes)}</span>
+        {#if backendType !== 'fullLoad'}
+            <span class="backend-badge">{backendType === 'lineIndex' ? 'indexed' : 'streaming'}</span>
+        {/if}
         <span class="shortcut-hint">Ctrl+F search &middot; Esc close</span>
     </div>
 </div>
@@ -315,19 +503,33 @@
     .file-content {
         flex: 1;
         overflow: auto;
-        font-family: 'SF Mono', Menlo, Monaco, Consolas, monospace;
+        font-family:
+            SF Mono,
+            Menlo,
+            Monaco,
+            Consolas,
+            monospace;
         font-size: 12px;
         line-height: 1.5;
-        padding: var(--spacing-xs) 0;
         user-select: text;
         -webkit-user-select: text;
         cursor: text;
     }
 
+    .scroll-spacer {
+        position: relative;
+    }
+
+    .lines-container {
+        position: absolute;
+        left: 0;
+        right: 0;
+    }
+
     .line {
         display: flex;
         padding: 0 var(--spacing-sm);
-        min-height: 18px;
+        height: 18px;
     }
 
     .line:hover {
@@ -351,6 +553,7 @@
         word-break: break-all;
         flex: 1;
         min-width: 0;
+        overflow: hidden;
     }
 
     mark {
@@ -388,6 +591,14 @@
         flex-shrink: 0;
     }
 
+    .backend-badge {
+        padding: 1px 4px;
+        border-radius: 3px;
+        background: var(--color-bg-tertiary);
+        color: var(--color-text-muted);
+        font-size: 10px;
+    }
+
     .shortcut-hint {
         margin-left: auto;
         color: var(--color-text-muted);
diff --git a/docs/features/file-viewer.md b/docs/features/file-viewer.md
index c6d58bd8..b5f49755 100644
--- a/docs/features/file-viewer.md
+++ b/docs/features/file-viewer.md
@@ -1,6 +1,7 @@
 # File viewer
 
-View a file's text content in a dedicated window via F3. Includes search with match highlighting.
+View a file's text content in a dedicated window via F3. Supports instant viewing of files of any size with virtual
+scrolling and background search.
 
 ## User interaction
 
@@ -9,17 +10,19 @@ time. Each window remembers its size and position between sessions.
 
 ### Viewing
 
-- File content is displayed with line numbers in a monospace font.
-- A status bar shows the file name, line count, and file size.
+- Content is displayed with line numbers in a monospace font.
+- Virtual scrolling: only visible lines are rendered, so even multi-GB files open instantly.
+- A status bar shows file name, line count (when known), file size, and backend mode.
 - Text is selectable for copying.
 
 ### Search
 
 - **Cmd+F** (or **Ctrl+F**): Open the search bar.
-- Type to find matches (case-insensitive). The match count is shown.
+- Type to find matches (case-insensitive, 300ms debounce). Match count is shown.
+- For large files, search runs in the background with a progress indicator.
 - **Enter**: Jump to next match.
 - **Shift+Enter**: Jump to previous match.
-- Matches are highlighted in the content. The active match uses a distinct color.
+- Matches are highlighted. The active match uses a distinct color.
 - Search wraps around at the end/beginning of the file.
 
 ### Keyboard shortcuts
@@ -30,27 +33,59 @@ time. Each window remembers its size and position between sessions.
 
 ### Limitations
 
-- Not optimized for very large files. The entire file is loaded into memory.
 - Binary files are shown with lossy UTF-8 decoding (replacement characters for invalid bytes).
 - Directories can't be viewed (F3 does nothing when the cursor is on a folder).
 
-## Implementation
+## Architecture
 
-### Backend
+### Three-backend strategy
 
-- **Command**: `read_file_content(path)` in `apps/desktop/src-tauri/src/commands/file_system.rs`
-- Returns `FileContentResult { content, lineCount, size, fileName }`
-- Uses `String::from_utf8_lossy` for binary-safe reading
-- Supports tilde expansion for the path
+The viewer uses a `FileViewerBackend` trait with three implementations, chosen based on file size:
+
+1. **FullLoadBackend** (files ≤ 1 MB): Loads entire file into memory. Instant random access by line number, byte
+   offset, or fraction. Full search in RAM.
+
+2. **ByteSeekBackend** (files > 1 MB, initial): Opens the file handle immediately with no pre-scan. Seeks by byte
+   offset or fraction. Scans backward up to 8 KB to find a newline boundary. Used as the instant-open strategy before
+   the line index finishes building.
+
+3. **LineIndexBackend** (files > 1 MB, after scan): Builds a sparse index of newline positions (one checkpoint every
+   256 lines). Memory: O(total_lines / 256). Supports O(1) line-based seeking. Built in a background thread using
+   SIMD-accelerated `memchr` for newline scanning.
+
+### Session orchestrator
+
+`ViewerSession` manages the lifecycle:
+- Opens with FullLoad for small files, ByteSeek for large files
+- For large files, spawns a background thread to build the LineIndex
+- When the index is ready, transparently upgrades from ByteSeek to LineIndex
+- Manages search state (start, poll, cancel) with cancellation support
+
+### Tauri commands
+
+- `viewer_open(path)` → session ID + metadata + initial lines
+- `viewer_get_lines(session_id, target_type, target_value, count)` → line chunk
+- `viewer_search_start(session_id, query)` → starts background search
+- `viewer_search_poll(session_id)` → matches + progress + status
+- `viewer_search_cancel(session_id)` → cancels running search
+- `viewer_close(session_id)` → frees resources
 
 ### Frontend
 
-- **Route**: `apps/desktop/src/routes/viewer/+page.svelte` — the viewer window's page
-- **Search utilities**: `apps/desktop/src/lib/file-viewer/viewer-search.ts`
+- **Route**: `apps/desktop/src/routes/viewer/+page.svelte` — virtual scrolling viewer
 - **Window opener**: `apps/desktop/src/lib/file-viewer/open-viewer.ts`
 - **Key binding**: F3 handler in `DualPaneExplorer.svelte` calls `openViewerForCursor()`
 - **Function key bar**: F3 button in `FunctionKeyBar.svelte`
-- **Tauri wrapper**: `readFileContent()` in `$lib/tauri-commands.ts`
+- **Tauri wrappers**: `viewerOpen()`, `viewerGetLines()`, etc. in `$lib/tauri-commands.ts`
+
+### Virtual scrolling
+
+The frontend only renders lines that are in or near the viewport:
+- Line height is fixed at 18px
+- A scroll spacer div provides the full scrollable height
+- On scroll, the visible range is recalculated and lines are fetched from the backend
+- Lines are cached client-side to avoid redundant requests
+- Buffer of 50 lines above/below the viewport for smooth scrolling
 
 ### Window management
 
diff --git a/docs/specs/viewer-tasks.md b/docs/specs/viewer-tasks.md
index ddfb4b04..66f2f28b 100644
--- a/docs/specs/viewer-tasks.md
+++ b/docs/specs/viewer-tasks.md
@@ -1,6 +1,6 @@
 # File viewer — task list
 
-## Tasks
+## Phase 1: Basic viewer (done)
 
 - [x] Create this task list
 - [x] Add `read_file_content` Rust command (reads file, returns text + metadata)
@@ -16,4 +16,19 @@
 - [x] Write Vitest unit tests for viewer search utilities
 - [x] Document in `docs/features/file-viewer.md`
 - [x] Run checker script, fix any issues
-- [x] Create PR
+
+## Phase 2: Three-backend architecture + virtual scrolling
+
+- [x] Design `FileViewerBackend` trait with SeekTarget, LineChunk, SearchMatch types
+- [x] Implement `FullLoadBackend` (files ≤ 1 MB, in-memory)
+- [x] Implement `ByteSeekBackend` (byte-offset seeking, no pre-scan, 8 KB backward cap)
+- [x] Implement `LineIndexBackend` (sparse index, checkpoint every 256 lines, cancellable scan)
+- [x] Implement `ViewerSession` orchestrator (picks strategy, background upgrade)
+- [x] Add Tauri commands: viewer_open, viewer_get_lines, viewer_search_start/poll/cancel, viewer_close
+- [x] Write 64 Rust tests covering all three backends + session orchestrator
+- [x] Update frontend to virtual scrolling (renders only visible lines)
+- [x] Add new TypeScript wrappers (viewerOpen, viewerGetLines, etc.)
+- [x] Implement backend-side search with polling + progress indicator
+- [x] Remove old `read_file_content` command and `viewer-search.ts` utilities
+- [x] Update documentation
+- [x] Run checks, fix issues

From 3590c49626666955ea2e7f0a3bbdd7dfa9ee0abd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 24 Jan 2026 17:14:09 +0000
Subject: [PATCH 05/16] Fix ESLint errors in file viewer

- Use SvelteMap instead of Map for reactive line cache
- Extract async poll logic out of setInterval callback
- Remove unnecessary type assertion on search status
- Use await instead of return for void invoke calls
---
 apps/desktop/src/lib/tauri-commands.ts      |  6 +--
 apps/desktop/src/routes/viewer/+page.svelte | 50 +++++++++++----------
 2 files changed, 29 insertions(+), 27 deletions(-)

diff --git a/apps/desktop/src/lib/tauri-commands.ts b/apps/desktop/src/lib/tauri-commands.ts
index 6bcbcac3..ced1c568 100644
--- a/apps/desktop/src/lib/tauri-commands.ts
+++ b/apps/desktop/src/lib/tauri-commands.ts
@@ -347,7 +347,7 @@ export async function viewerGetLines(
 
 /** Starts a background search in the viewer session. */
 export async function viewerSearchStart(sessionId: string, query: string): Promise<void> {
-    return invoke<void>('viewer_search_start', { sessionId, query })
+    await invoke('viewer_search_start', { sessionId, query })
 }
 
 /** Polls search progress and matches. */
@@ -357,12 +357,12 @@ export async function viewerSearchPoll(sessionId: string): Promise<SearchPollRes
 
 /** Cancels an ongoing search. */
 export async function viewerSearchCancel(sessionId: string): Promise<void> {
-    return invoke<void>('viewer_search_cancel', { sessionId })
+    await invoke('viewer_search_cancel', { sessionId })
 }
 
 /** Closes a viewer session and frees resources. */
 export async function viewerClose(sessionId: string): Promise<void> {
-    return invoke<void>('viewer_close', { sessionId })
+    await invoke('viewer_close', { sessionId })
 }
 
 /**
diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
index 0454a6f1..c98d7424 100644
--- a/apps/desktop/src/routes/viewer/+page.svelte
+++ b/apps/desktop/src/routes/viewer/+page.svelte
@@ -14,6 +14,7 @@
 
 <script lang="ts">
     import { onMount, onDestroy, tick } from 'svelte'
+    import { SvelteMap } from 'svelte/reactivity'
     import type { ViewerSearchMatch } from '$lib/tauri-commands'
 
     let fileName = $state('')
@@ -25,7 +26,7 @@
     let backendType = $state<'fullLoad' | 'byteSeek' | 'lineIndex'>('fullLoad')
 
     // Line cache: lineNumber -> text
-    let lineCache = $state<Map<number, string>>(new Map())
+    const lineCache = new SvelteMap<number, string>()
     // The range of lines currently in cache
     let cachedFrom = $state(0)
     let cachedTo = $state(0)
@@ -94,11 +95,9 @@
             const chunk = await viewerGetLines(sessionId, 'line', fetchFrom, fetchCount)
 
             // Update cache
-            const newCache = new Map(lineCache)
             for (let i = 0; i < chunk.lines.length; i++) {
-                newCache.set(chunk.firstLineNumber + i, chunk.lines[i])
+                lineCache.set(chunk.firstLineNumber + i, chunk.lines[i])
             }
-            lineCache = newCache
             cachedFrom = Math.min(cachedFrom, chunk.firstLineNumber)
             cachedTo = Math.max(cachedTo, chunk.firstLineNumber + chunk.lines.length)
 
@@ -139,25 +138,29 @@
 
     function pollSearch() {
         stopSearchPoll()
-        searchPollTimer = setInterval(async () => {
-            if (!sessionId) return
-            try {
-                const { viewerSearchPoll } = await import('$lib/tauri-commands')
-                const result = await viewerSearchPoll(sessionId)
-                searchMatches = result.matches
-                searchProgress = totalBytes > 0 ? result.bytesScanned / totalBytes : 0
-                if (currentMatchIndex === -1 && result.matches.length > 0) {
-                    currentMatchIndex = 0
-                }
-                if (result.status !== 'running') {
-                    searchStatus = result.status as 'done' | 'cancelled' | 'idle'
-                    stopSearchPoll()
-                }
-            } catch {
+        searchPollTimer = setInterval(() => {
+            void pollSearchTick()
+        }, SEARCH_POLL_INTERVAL)
+    }
+
+    async function pollSearchTick() {
+        if (!sessionId) return
+        try {
+            const { viewerSearchPoll } = await import('$lib/tauri-commands')
+            const result = await viewerSearchPoll(sessionId)
+            searchMatches = result.matches
+            searchProgress = totalBytes > 0 ? result.bytesScanned / totalBytes : 0
+            if (currentMatchIndex === -1 && result.matches.length > 0) {
+                currentMatchIndex = 0
+            }
+            if (result.status !== 'running') {
+                searchStatus = result.status
                 stopSearchPoll()
-                searchStatus = 'idle'
             }
-        }, SEARCH_POLL_INTERVAL)
+        } catch {
+            stopSearchPoll()
+            searchStatus = 'idle'
+        }
     }
 
     function stopSearchPoll() {
@@ -327,11 +330,10 @@
             backendType = result.backendType
 
             // Populate cache with initial lines
-            const newCache = new Map<number, string>()
+            lineCache.clear()
             for (let i = 0; i < result.initialLines.lines.length; i++) {
-                newCache.set(result.initialLines.firstLineNumber + i, result.initialLines.lines[i])
+                lineCache.set(result.initialLines.firstLineNumber + i, result.initialLines.lines[i])
             }
-            lineCache = newCache
             cachedFrom = result.initialLines.firstLineNumber
             cachedTo = result.initialLines.firstLineNumber + result.initialLines.lines.length
 

From 4f337733f84ac51fdc93b0b96e26f50bc74648dd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 24 Jan 2026 17:48:35 +0000
Subject: [PATCH 06/16] Fix stylelint font-family-name-quotes error

---
 apps/desktop/src/routes/viewer/+page.svelte | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
index c98d7424..053707bc 100644
--- a/apps/desktop/src/routes/viewer/+page.svelte
+++ b/apps/desktop/src/routes/viewer/+page.svelte
@@ -505,12 +505,7 @@
     .file-content {
         flex: 1;
         overflow: auto;
-        font-family:
-            SF Mono,
-            Menlo,
-            Monaco,
-            Consolas,
-            monospace;
+        font-family: 'SF Mono', Menlo, Monaco, Consolas, monospace;
         font-size: 12px;
         line-height: 1.5;
         user-select: text;

From d6aff953659e7683e08577fdaa5071db35acd915 Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Tue, 27 Jan 2026 22:51:38 +0100
Subject: [PATCH 07/16] Bugfix: Accept first click on the main window

To change file focus right when clicking
---
 apps/desktop/src-tauri/tauri.conf.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src-tauri/tauri.conf.json b/apps/desktop/src-tauri/tauri.conf.json
index 41bc4b16..9ccfe96b 100644
--- a/apps/desktop/src-tauri/tauri.conf.json
+++ b/apps/desktop/src-tauri/tauri.conf.json
@@ -24,7 +24,8 @@
           "x": 9,
           "y": 17
         },
-        "hiddenTitle": true
+        "hiddenTitle": true,
+        "acceptFirstMouse": true
       }
     ],
     "security": {

From f075865d6269ec451f0f776d20e9f91fc09f16f0 Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 00:04:51 +0100
Subject: [PATCH 08/16] Viwer: Add shortcuts

---
 apps/desktop/src/routes/viewer/+page.svelte | 69 ++++++++++++++++++++-
 1 file changed, 66 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
index 053707bc..9b35a0da 100644
--- a/apps/desktop/src/routes/viewer/+page.svelte
+++ b/apps/desktop/src/routes/viewer/+page.svelte
@@ -35,6 +35,7 @@
     let scrollTop = $state(0)
     let viewportHeight = $state(600)
     let contentRef: HTMLDivElement | undefined = $state()
+    let containerRef: HTMLDivElement | undefined = $state()
 
     // Derived: which lines are visible
     const visibleFrom = $derived(Math.max(0, Math.floor(scrollTop / LINE_HEIGHT) - BUFFER_LINES))
@@ -239,7 +240,7 @@
                 const { viewerClose } = await import('$lib/tauri-commands')
                 await viewerClose(sessionId)
             } catch {
-                // Ignore
+                // Ignore - session cleanup is best-effort
             }
         }
         try {
@@ -250,6 +251,57 @@
         }
     }
 
+    function scrollByLines(lines: number) {
+        if (contentRef) {
+            contentRef.scrollTop = Math.max(0, contentRef.scrollTop + lines * LINE_HEIGHT)
+        }
+    }
+
+    function scrollByPages(pages: number) {
+        if (contentRef) {
+            const pageSize = contentRef.clientHeight - LINE_HEIGHT // Overlap by 1 line
+            contentRef.scrollTop = Math.max(0, contentRef.scrollTop + pages * pageSize)
+        }
+    }
+
+    function scrollToStart() {
+        if (contentRef) {
+            contentRef.scrollTop = 0
+        }
+    }
+
+    function scrollToEnd() {
+        if (contentRef) {
+            contentRef.scrollTop = contentRef.scrollHeight - contentRef.clientHeight
+        }
+    }
+
+    /** Handle navigation keys (arrows, page up/down, home/end). Returns true if handled. */
+    function handleNavigationKey(key: string): boolean {
+        switch (key) {
+            case 'ArrowUp':
+                scrollByLines(-1)
+                return true
+            case 'ArrowDown':
+                scrollByLines(1)
+                return true
+            case 'PageUp':
+                scrollByPages(-1)
+                return true
+            case 'PageDown':
+                scrollByPages(1)
+                return true
+            case 'Home':
+                scrollToStart()
+                return true
+            case 'End':
+                scrollToEnd()
+                return true
+            default:
+                return false
+        }
+    }
+
     function handleKeyDown(e: KeyboardEvent) {
         if ((e.metaKey || e.ctrlKey) && e.key === 'f') {
             e.preventDefault()
@@ -274,6 +326,13 @@
             } else {
                 findNext()
             }
+            return
+        }
+
+        // Navigation keys (only when search input is not focused)
+        const isSearchInputFocused = searchVisible && document.activeElement === searchInputRef
+        if (!isSearchInputFocused && handleNavigationKey(e.key)) {
+            e.preventDefault()
         }
     }
 
@@ -348,6 +407,9 @@
             error = typeof e === 'string' ? e : 'Failed to read file'
         } finally {
             loading = false
+            // Auto-focus the container so keyboard events work immediately
+            await tick()
+            containerRef?.focus()
         }
     })
 
@@ -357,8 +419,9 @@
     })
 </script>
 
-<!-- svelte-ignore a11y_no_static_element_interactions -->
-<div class="viewer-container" onkeydown={handleKeyDown} tabindex={-1}>
+<svelte:window on:keydown={handleKeyDown} />
+
+<div class="viewer-container" bind:this={containerRef} tabindex={-1}>
     {#if searchVisible}
         <div class="search-bar" role="search">
             <input

From 30aa3ed7bb8158081dea61901a04e1698d086b71 Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 00:05:22 +0100
Subject: [PATCH 09/16] Viewer: Suppress main window shortcuts

---
 apps/desktop/src-tauri/src/lib.rs | 52 +++++++++++++++++--------------
 1 file changed, 29 insertions(+), 23 deletions(-)

diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 3f5325d9..757e24cd 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -185,8 +185,8 @@ pub fn run() {
                 // We just need to read and emit it, not toggle again
                 let new_state = check_item.is_checked().unwrap_or(true);
 
-                // Emit event to frontend with the new state
-                let _ = app.emit("settings-changed", serde_json::json!({ "showHiddenFiles": new_state }));
+                // Emit event to frontend with the new state (main window only)
+                let _ = app.emit_to("main", "settings-changed", serde_json::json!({ "showHiddenFiles": new_state }));
             } else if id == VIEW_MODE_FULL_ID || id == VIEW_MODE_BRIEF_ID {
                 // Handle view mode toggle (radio button behavior)
                 let menu_state = app.state::<MenuState<tauri::Wry>>();
@@ -202,31 +202,36 @@ pub fn run() {
                     let _ = full_item.set_checked(is_full);
                     let _ = brief_item.set_checked(!is_full);
 
-                    // Emit event to frontend
+                    // Emit event to frontend (main window only)
                     let mode = if is_full { "full" } else { "brief" };
-                    let _ = app.emit("view-mode-changed", serde_json::json!({ "mode": mode }));
+                    let _ = app.emit_to("main", "view-mode-changed", serde_json::json!({ "mode": mode }));
                 }
             } else if id == GO_BACK_ID || id == GO_FORWARD_ID || id == GO_PARENT_ID {
-                // Handle Go menu navigation actions
-                let action = match id {
-                    GO_BACK_ID => "back",
-                    GO_FORWARD_ID => "forward",
-                    GO_PARENT_ID => "parent",
-                    _ => return,
-                };
-                let _ = app.emit("navigation-action", serde_json::json!({ "action": action }));
+                // Handle Go menu navigation actions - only when main window is focused
+                // This prevents shortcuts from affecting main window when viewer is open
+                if let Some(main_window) = app.get_webview_window("main") {
+                    if main_window.is_focused().unwrap_or(false) {
+                        let action = match id {
+                            GO_BACK_ID => "back",
+                            GO_FORWARD_ID => "forward",
+                            GO_PARENT_ID => "parent",
+                            _ => return,
+                        };
+                        let _ = app.emit_to("main", "navigation-action", serde_json::json!({ "action": action }));
+                    }
+                }
             } else if id == ABOUT_ID {
-                // Emit event to show our custom About window
-                let _ = app.emit("show-about", ());
+                // Emit event to show our custom About window (main window only)
+                let _ = app.emit_to("main", "show-about", ());
             } else if id == ENTER_LICENSE_KEY_ID {
-                // Emit event to show the license key entry dialog
-                let _ = app.emit("show-license-key-dialog", ());
+                // Emit event to show the license key entry dialog (main window only)
+                let _ = app.emit_to("main", "show-license-key-dialog", ());
             } else if id == COMMAND_PALETTE_ID {
-                // Emit event to show the command palette
-                let _ = app.emit("show-command-palette", ());
+                // Emit event to show the command palette (main window only)
+                let _ = app.emit_to("main", "show-command-palette", ());
             } else if id == SWITCH_PANE_ID {
-                // Emit event to switch pane
-                let _ = app.emit("switch-pane", ());
+                // Emit event to switch pane (main window only)
+                let _ = app.emit_to("main", "switch-pane", ());
             } else if id == SORT_BY_NAME_ID
                 || id == SORT_BY_EXTENSION_ID
                 || id == SORT_BY_SIZE_ID
@@ -242,11 +247,12 @@ pub fn run() {
                     SORT_BY_CREATED_ID => "created",
                     _ => return,
                 };
-                let _ = app.emit("menu-sort", serde_json::json!({ "action": "sortBy", "value": column }));
+                let _ = app.emit_to("main", "menu-sort", serde_json::json!({ "action": "sortBy", "value": column }));
             } else if id == SORT_ASCENDING_ID || id == SORT_DESCENDING_ID {
-                // Handle sort order
+                // Handle sort order (main window only)
                 let order = if id == SORT_ASCENDING_ID { "asc" } else { "desc" };
-                let _ = app.emit(
+                let _ = app.emit_to(
+                    "main",
                     "menu-sort",
                     serde_json::json!({ "action": "sortOrder", "value": order }),
                 );

From 9a5b1d702d8b6cce5a2d6d4b16e96d81d41192de Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 00:05:38 +0100
Subject: [PATCH 10/16] Viewer: Fix ESC shortcut behavior

---
 apps/desktop/src-tauri/capabilities/viewer.json | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 apps/desktop/src-tauri/capabilities/viewer.json

diff --git a/apps/desktop/src-tauri/capabilities/viewer.json b/apps/desktop/src-tauri/capabilities/viewer.json
new file mode 100644
index 00000000..acae5efa
--- /dev/null
+++ b/apps/desktop/src-tauri/capabilities/viewer.json
@@ -0,0 +1,16 @@
+{
+    "$schema": "../gen/schemas/desktop-schema.json",
+    "identifier": "viewer",
+    "description": "Capability for file viewer windows",
+    "windows": [
+        "viewer-*"
+    ],
+    "permissions": [
+        "core:window:allow-close",
+        "core:window:allow-set-title",
+        "core:window:allow-set-focus",
+        "core:window:allow-get-all-windows",
+        "core:event:default",
+        "window-state:default"
+    ]
+}

From 5f99ec444d0fc6e1dc4ab70a6eb7db5d549ca46f Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 01:16:55 +0100
Subject: [PATCH 11/16] Viewer: Separate layout from main window

---
 apps/desktop/src/routes/(main)/+layout.svelte | 35 +++++++++++++++++++
 .../src/routes/{ => (main)}/+page.svelte      |  0
 apps/desktop/src/routes/+layout.svelte        | 31 ++++------------
 apps/desktop/src/routes/viewer/+layout.svelte |  2 ++
 4 files changed, 43 insertions(+), 25 deletions(-)
 create mode 100644 apps/desktop/src/routes/(main)/+layout.svelte
 rename apps/desktop/src/routes/{ => (main)}/+page.svelte (100%)
 create mode 100644 apps/desktop/src/routes/viewer/+layout.svelte

diff --git a/apps/desktop/src/routes/(main)/+layout.svelte b/apps/desktop/src/routes/(main)/+layout.svelte
new file mode 100644
index 00000000..24a0fc05
--- /dev/null
+++ b/apps/desktop/src/routes/(main)/+layout.svelte
@@ -0,0 +1,35 @@
+<script lang="ts">
+    /**
+     * Main window layout - includes updater, notifications, and window state.
+     * Only used for the main file manager window.
+     */
+    import { onMount } from 'svelte'
+    import { initWindowStateListener } from '$lib/window-state'
+    import { startUpdateChecker } from '$lib/updater.svelte'
+    import AiNotification from '$lib/AiNotification.svelte'
+    import UpdateNotification from '$lib/UpdateNotification.svelte'
+
+    onMount(() => {
+        // Initialize window state persistence on resize
+        // This ensures window size/position survives hot reloads
+        void initWindowStateListener()
+
+        // Start checking for updates (skips in dev mode)
+        return startUpdateChecker()
+    })
+</script>
+
+<UpdateNotification />
+<AiNotification />
+<div class="page-wrapper">
+    <slot />
+</div>
+
+<style>
+    .page-wrapper {
+        display: flex;
+        flex-direction: column;
+        flex: 1;
+        min-height: 0;
+    }
+</style>
diff --git a/apps/desktop/src/routes/+page.svelte b/apps/desktop/src/routes/(main)/+page.svelte
similarity index 100%
rename from apps/desktop/src/routes/+page.svelte
rename to apps/desktop/src/routes/(main)/+page.svelte
diff --git a/apps/desktop/src/routes/+layout.svelte b/apps/desktop/src/routes/+layout.svelte
index 41b0ded9..574a2ffd 100644
--- a/apps/desktop/src/routes/+layout.svelte
+++ b/apps/desktop/src/routes/+layout.svelte
@@ -1,35 +1,16 @@
 <script lang="ts">
+    /**
+     * Root layout - minimal, just CSS and logger.
+     * Main-window-specific features (updater, notifications) are in (main)/+layout.svelte.
+     * Other windows (viewer, debug) get only this minimal layout.
+     */
     import { onMount } from 'svelte'
     import '../app.css'
-    import { initWindowStateListener } from '$lib/window-state'
-    import { startUpdateChecker } from '$lib/updater.svelte'
-    import AiNotification from '$lib/AiNotification.svelte'
-    import UpdateNotification from '$lib/UpdateNotification.svelte'
     import { initLogger } from '$lib/logger'
 
     onMount(() => {
-        // Initialize logging first
         void initLogger()
-        // Initialize window state persistence on resize
-        // This ensures window size/position survives hot reloads
-        void initWindowStateListener()
-
-        // Start checking for updates (skips in dev mode)
-        return startUpdateChecker()
     })
 </script>
 
-<UpdateNotification />
-<AiNotification />
-<div class="page-wrapper">
-    <slot />
-</div>
-
-<style>
-    .page-wrapper {
-        display: flex;
-        flex-direction: column;
-        flex: 1;
-        min-height: 0;
-    }
-</style>
+<slot />
diff --git a/apps/desktop/src/routes/viewer/+layout.svelte b/apps/desktop/src/routes/viewer/+layout.svelte
new file mode 100644
index 00000000..43ec548a
--- /dev/null
+++ b/apps/desktop/src/routes/viewer/+layout.svelte
@@ -0,0 +1,2 @@
+<!-- Viewer uses root layout (CSS + logger). No updater, notifications, or window state. -->
+<slot />

From 767f857cb69b905328a54feda43fdb79b89f619f Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 01:21:21 +0100
Subject: [PATCH 12/16] CI: Fix desktop-e2e-linux running criteria

---
 .github/workflows/ci.yml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1c54a578..9a2208f5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -173,7 +173,11 @@ jobs:
         name: Desktop E2E (Linux)
         runs-on: ubuntu-latest
         needs: [changes, desktop-rust, desktop-svelte]
-        if: needs.changes.outputs.desktop == 'true'
+        if: |
+            always() &&
+            needs.changes.outputs.desktop == 'true' &&
+            !contains(needs.*.result, 'failure') &&
+            !contains(needs.*.result, 'cancelled')
 
         steps:
             - name: Checkout code

From e29e039b7cb6fc176dd568e914380a07afbbe828 Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 01:21:44 +0100
Subject: [PATCH 13/16] Claude: Remove post-tool-use command

---
 .claude/settings.json | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/.claude/settings.json b/.claude/settings.json
index e29af6de..7c72b49e 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -15,17 +15,6 @@
           }
         ]
       }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash -c '\"$(git rev-parse --show-toplevel)/.claude/hooks/post-edit-format.sh\"'"
-          }
-        ]
-      }
     ]
   }
 }

From 20e99f4b55c727b8c3f6796aa590f99f346a2237 Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 01:22:12 +0100
Subject: [PATCH 14/16] Viewer: Remove unneeded capability

---
 apps/desktop/src-tauri/capabilities/viewer.json | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/apps/desktop/src-tauri/capabilities/viewer.json b/apps/desktop/src-tauri/capabilities/viewer.json
index acae5efa..71cbde24 100644
--- a/apps/desktop/src-tauri/capabilities/viewer.json
+++ b/apps/desktop/src-tauri/capabilities/viewer.json
@@ -10,7 +10,6 @@
         "core:window:allow-set-title",
         "core:window:allow-set-focus",
         "core:window:allow-get-all-windows",
-        "core:event:default",
-        "window-state:default"
+        "core:event:default"
     ]
 }

From 14e957a6ef8bc27f139819bbdc521969a03d0c40 Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 13:21:47 +0100
Subject: [PATCH 15/16] Viewer: Test and fix up

Now it works very well in all three modes, and displays state nicely on the UI.
---
 .../src-tauri/src/commands/file_viewer.rs     |  27 +-
 .../src-tauri/src/file_viewer/byte_seek.rs    |  48 ++-
 .../src/file_viewer/byte_seek_test.rs         |  13 +-
 apps/desktop/src-tauri/src/file_viewer/mod.rs |   4 +-
 .../src-tauri/src/file_viewer/session.rs      | 108 +++++-
 apps/desktop/src-tauri/src/lib.rs             |  33 +-
 apps/desktop/src/lib/logger.ts                |   3 +-
 apps/desktop/src/lib/tauri-commands.ts        |  16 +
 apps/desktop/src/routes/viewer/+page.svelte   | 311 ++++++++++++++----
 9 files changed, 471 insertions(+), 92 deletions(-)

diff --git a/apps/desktop/src-tauri/src/commands/file_viewer.rs b/apps/desktop/src-tauri/src/commands/file_viewer.rs
index bc9b333f..47a21276 100644
--- a/apps/desktop/src-tauri/src/commands/file_viewer.rs
+++ b/apps/desktop/src-tauri/src/commands/file_viewer.rs
@@ -1,6 +1,7 @@
 //! Tauri commands for the file viewer.
 
-use crate::file_viewer::{self, LineChunk, SearchPollResult, SeekTarget, ViewerOpenResult};
+use crate::file_viewer::{self, LineChunk, SearchPollResult, SeekTarget, ViewerOpenResult, ViewerSessionStatus};
+use log::debug;
 
 /// Opens a viewer session for the given file.
 /// Returns session metadata + initial lines from the start of the file.
@@ -34,7 +35,23 @@ pub fn viewer_get_lines(
             ));
         }
     };
-    file_viewer::get_lines(&session_id, target, count).map_err(|e| e.to_string())
+
+    debug!(
+        "viewer_get_lines: session={}, target_type={}, target_value={}, count={}",
+        session_id, target_type, target_value, count
+    );
+
+    let result = file_viewer::get_lines(&session_id, target, count).map_err(|e| e.to_string())?;
+
+    debug!(
+        "viewer_get_lines: returned {} lines, first_line_number={}, byte_offset={}, first_line_preview={:?}",
+        result.lines.len(),
+        result.first_line_number,
+        result.byte_offset,
+        result.lines.first().map(|s| s.chars().take(50).collect::<String>())
+    );
+
+    Ok(result)
 }
 
 /// Starts a background search in the viewer session.
@@ -59,6 +76,12 @@ pub fn viewer_search_cancel(session_id: String) -> Result<(), String> {
     file_viewer::search_cancel(&session_id).map_err(|e| e.to_string())
 }
 
+/// Gets the current status of a viewer session (backend type, indexing state).
+#[tauri::command]
+pub fn viewer_get_status(session_id: String) -> Result<ViewerSessionStatus, String> {
+    file_viewer::get_session_status(&session_id).map_err(|e| e.to_string())
+}
+
 /// Closes a viewer session and frees resources.
 #[tauri::command]
 pub fn viewer_close(session_id: String) -> Result<(), String> {
diff --git a/apps/desktop/src-tauri/src/file_viewer/byte_seek.rs b/apps/desktop/src-tauri/src/file_viewer/byte_seek.rs
index 6b0e6d4f..576a4ee6 100644
--- a/apps/desktop/src-tauri/src/file_viewer/byte_seek.rs
+++ b/apps/desktop/src-tauri/src/file_viewer/byte_seek.rs
@@ -13,6 +13,7 @@ use std::path::Path;
 use std::sync::Mutex;
 use std::sync::atomic::{AtomicBool, Ordering};
 
+use log::debug;
 use memchr::memchr;
 
 use super::{
@@ -140,9 +141,15 @@ impl ByteSeekBackend {
                 let f = f.clamp(0.0, 1.0);
                 (f * self.total_bytes as f64) as u64
             }
-            SeekTarget::Line(_) => {
-                // ByteSeek doesn't support line-based seeking; default to start
-                0
+            SeekTarget::Line(line_num) => {
+                // ByteSeek doesn't have a line index, so estimate using average line length (80 chars)
+                // This is a rough approximation but much better than returning 0
+                let estimated_offset = (*line_num as u64) * 80;
+                debug!(
+                    "ByteSeekBackend: Line({}) requested, estimating byte offset {} (using avg 80 chars/line)",
+                    line_num, estimated_offset
+                );
+                estimated_offset.min(self.total_bytes)
             }
         }
     }
@@ -152,16 +159,47 @@ impl FileViewerBackend for ByteSeekBackend {
     fn get_lines(&self, target: &SeekTarget, count: usize) -> Result<LineChunk, ViewerError> {
         let raw_offset = self.resolve_byte_offset(target);
 
+        debug!(
+            "ByteSeekBackend::get_lines: target={:?}, resolved to byte offset {}",
+            target, raw_offset
+        );
+
         // Find the actual line start by scanning backward
         let mut file = File::open(&self.path)?;
         let line_start = self.find_line_start(&mut file, raw_offset)?;
 
+        debug!(
+            "ByteSeekBackend::get_lines: line_start={} (after backward scan)",
+            line_start
+        );
+
         let (lines, _end_offset) = self.read_lines_from(line_start, count)?;
 
+        // Estimate line number based on byte position and average line length
+        // This is an approximation, but better than always returning 0
+        let estimated_line_number = if line_start == 0 {
+            0
+        } else {
+            // Use the lines we just read to estimate avg line length
+            let avg_line_len = if !lines.is_empty() {
+                let total_bytes_in_chunk: usize = lines.iter().map(|l| l.len() + 1).sum(); // +1 for newline
+                total_bytes_in_chunk / lines.len()
+            } else {
+                80 // fallback assumption
+            };
+            (line_start as usize) / avg_line_len.max(1)
+        };
+
+        debug!(
+            "ByteSeekBackend::get_lines: returning {} lines, estimated first_line_number={} (based on avg line len)",
+            lines.len(),
+            estimated_line_number
+        );
+
         Ok(LineChunk {
             lines,
-            // We don't know the line number in byte-seek mode
-            first_line_number: 0,
+            // Estimate line number based on byte offset
+            first_line_number: estimated_line_number,
             byte_offset: line_start,
             total_lines: None,
             total_bytes: self.total_bytes,
diff --git a/apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs b/apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs
index 1b53592c..71177fd6 100644
--- a/apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs
+++ b/apps/desktop/src-tauri/src/file_viewer/byte_seek_test.rs
@@ -131,16 +131,23 @@ fn get_lines_fraction_end() {
 }
 
 #[test]
-fn get_lines_line_target_defaults_to_start() {
+fn get_lines_line_target_estimates_offset() {
     let dir = create_test_dir("line_target");
     let file = write_test_file(&dir, "test.txt", "a\nb\nc\n");
 
     let backend = ByteSeekBackend::open(&file).unwrap();
-    // ByteSeek doesn't support line seeking — defaults to start
-    let chunk = backend.get_lines(&SeekTarget::Line(5), 2).unwrap();
+    // ByteSeek estimates byte offset using avg 80 chars/line
+    // Line(0) should give offset 0
+    let chunk = backend.get_lines(&SeekTarget::Line(0), 2).unwrap();
     assert_eq!(chunk.byte_offset, 0);
     assert_eq!(chunk.lines[0], "a");
 
+    // Line(5) on a tiny file clamps to file size, giving last line
+    let chunk2 = backend.get_lines(&SeekTarget::Line(5), 2).unwrap();
+    // 5 * 80 = 400, clamped to 6 bytes (file size), backward scan finds last newline
+    assert_eq!(chunk2.byte_offset, 6); // At EOF
+    assert!(chunk2.lines.is_empty()); // No lines after EOF
+
     cleanup(&dir);
 }
 
diff --git a/apps/desktop/src-tauri/src/file_viewer/mod.rs b/apps/desktop/src-tauri/src/file_viewer/mod.rs
index b64a0e9b..8620b126 100644
--- a/apps/desktop/src-tauri/src/file_viewer/mod.rs
+++ b/apps/desktop/src-tauri/src/file_viewer/mod.rs
@@ -20,8 +20,8 @@ mod line_index_test;
 mod session_test;
 
 pub use session::{
-    SearchPollResult, ViewerOpenResult, close_session, get_lines, open_session, search_cancel, search_poll,
-    search_start,
+    SearchPollResult, ViewerOpenResult, ViewerSessionStatus, close_session, get_lines, get_session_status,
+    open_session, search_cancel, search_poll, search_start,
 };
 
 use serde::Serialize;
diff --git a/apps/desktop/src-tauri/src/file_viewer/session.rs b/apps/desktop/src-tauri/src/file_viewer/session.rs
index f1420f35..a3e298cb 100644
--- a/apps/desktop/src-tauri/src/file_viewer/session.rs
+++ b/apps/desktop/src-tauri/src/file_viewer/session.rs
@@ -8,7 +8,9 @@ use std::path::PathBuf;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, LazyLock, Mutex};
 use std::thread;
+use std::time::Duration;
 
+use log::debug;
 use serde::Serialize;
 
 use super::byte_seek::ByteSeekBackend;
@@ -35,10 +37,24 @@ pub struct ViewerOpenResult {
     pub file_name: String,
     pub total_bytes: u64,
     pub total_lines: Option<usize>,
+    /// Estimated total lines based on initial sample (for ByteSeek where total_lines is unknown).
+    /// Calculated as total_bytes / avg_bytes_per_line from initial lines.
+    pub estimated_total_lines: usize,
     pub backend_type: BackendType,
     pub capabilities: BackendCapabilities,
     /// Initial chunk of lines from the start of the file.
     pub initial_lines: LineChunk,
+    /// Whether background indexing is in progress (for ByteSeek -> LineIndex upgrade).
+    pub is_indexing: bool,
+}
+
+/// Current status of a viewer session.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ViewerSessionStatus {
+    pub backend_type: BackendType,
+    pub is_indexing: bool,
+    pub total_lines: Option<usize>,
 }
 
 /// Status of an ongoing search.
@@ -89,6 +105,11 @@ static SESSIONS: LazyLock<Mutex<HashMap<String, ViewerSession>>> = LazyLock::new
 /// Number of initial lines to return on open.
 const INITIAL_LINE_COUNT: usize = 200;
 
+/// Maximum time to spend building the line index before giving up.
+/// If indexing takes longer, the session stays in ByteSeek (streaming) mode.
+/// This prevents hammering slow disks or network drives.
+const INDEXING_TIMEOUT_SECS: u64 = 5;
+
 /// Generates a unique session ID.
 fn generate_session_id() -> String {
     uuid::Uuid::new_v4().to_string()
@@ -142,28 +163,60 @@ pub fn open_session(path: &str) -> Result<ViewerOpenResult, ViewerError> {
 
     let session_id = generate_session_id();
 
-    // If we're using ByteSeek, start background upgrade to LineIndex
+    // If we're using ByteSeek, start background upgrade to LineIndex with timeout
     let upgrade_cancel = upgrading.clone();
-    if upgrade_cancel.is_some() {
+    let is_indexing = upgrade_cancel.is_some();
+    if let Some(cancel_flag) = upgrade_cancel.clone() {
         let session_id_clone = session_id.clone();
         let path_clone = file_path.clone();
-        let cancel_clone = upgrade_cancel.clone().unwrap();
+        let cancel_for_indexer = cancel_flag.clone();
+        let cancel_for_timeout = cancel_flag.clone();
 
+        // Spawn timeout thread that cancels indexing after INDEXING_TIMEOUT_SECS
+        let session_id_for_timeout = session_id.clone();
         thread::spawn(move || {
-            let cancel_flag = &cancel_clone;
-            match LineIndexBackend::open(&path_clone, cancel_flag) {
+            thread::sleep(Duration::from_secs(INDEXING_TIMEOUT_SECS));
+            // If still indexing (flag not already set), cancel it
+            if !cancel_for_timeout.load(Ordering::Relaxed) {
+                debug!(
+                    "Indexing timeout reached for session {}, cancelling",
+                    session_id_for_timeout
+                );
+                cancel_for_timeout.store(true, Ordering::Relaxed);
+                // Mark session as no longer indexing
+                if let Ok(mut sessions) = SESSIONS.lock()
+                    && let Some(session) = sessions.get_mut(&session_id_for_timeout)
+                {
+                    session.upgrading = None;
+                }
+            }
+        });
+
+        // Spawn indexing thread
+        thread::spawn(move || {
+            match LineIndexBackend::open(&path_clone, &cancel_for_indexer) {
                 Ok(new_backend) => {
-                    if !cancel_flag.load(Ordering::Relaxed) {
+                    if !cancel_for_indexer.load(Ordering::Relaxed) {
                         let mut sessions = SESSIONS.lock().unwrap();
                         if let Some(session) = sessions.get_mut(&session_id_clone) {
+                            debug!(
+                                "Indexing completed for session {}, upgrading to LineIndex",
+                                session_id_clone
+                            );
                             session.backend = Box::new(new_backend);
                             session.backend_type = BackendType::LineIndex;
                             session.upgrading = None;
                         }
                     }
                 }
-                Err(_) => {
-                    // If upgrade fails, keep using ByteSeek — it still works fine
+                Err(e) => {
+                    debug!("Indexing failed for session {}: {}", session_id_clone, e);
+                    // Mark as no longer indexing
+                    if let Ok(mut sessions) = SESSIONS.lock()
+                        && let Some(session) = sessions.get_mut(&session_id_clone)
+                    {
+                        session.upgrading = None;
+                    }
                 }
             }
         });
@@ -177,14 +230,33 @@ pub fn open_session(path: &str) -> Result<ViewerOpenResult, ViewerError> {
         path: file_path,
     };
 
+    // Calculate estimated total lines from the initial sample
+    let estimated_total_lines = if let Some(lines) = total_lines {
+        // If we know the exact count, use it
+        lines
+    } else if !initial_lines.lines.is_empty() {
+        // Estimate from initial sample: total_bytes / avg_bytes_per_line
+        let total_bytes_in_sample: usize = initial_lines.lines.iter().map(|l| l.len() + 1).sum(); // +1 for newline
+        let avg_bytes_per_line = total_bytes_in_sample / initial_lines.lines.len();
+        if avg_bytes_per_line > 0 {
+            (total_bytes as usize) / avg_bytes_per_line
+        } else {
+            (total_bytes as usize) / 80 // fallback
+        }
+    } else {
+        (total_bytes as usize) / 80 // fallback for empty files
+    };
+
     let result = ViewerOpenResult {
         session_id: session_id.clone(),
         file_name,
         total_bytes,
         total_lines,
+        estimated_total_lines,
         backend_type,
         capabilities,
         initial_lines,
+        is_indexing,
     };
 
     SESSIONS.lock().unwrap().insert(session_id, session);
@@ -192,12 +264,32 @@ pub fn open_session(path: &str) -> Result<ViewerOpenResult, ViewerError> {
     Ok(result)
 }
 
+/// Gets the current status of a session (backend type, indexing state).
+pub fn get_session_status(session_id: &str) -> Result<ViewerSessionStatus, ViewerError> {
+    let sessions = SESSIONS.lock().unwrap();
+    let session = sessions
+        .get(session_id)
+        .ok_or(ViewerError::SessionNotFound(session_id.to_string()))?;
+
+    Ok(ViewerSessionStatus {
+        backend_type: session.backend_type.clone(),
+        is_indexing: session.upgrading.is_some(),
+        total_lines: session.backend.total_lines(),
+    })
+}
+
 /// Gets a range of lines from a session.
 pub fn get_lines(session_id: &str, target: SeekTarget, count: usize) -> Result<LineChunk, ViewerError> {
     let sessions = SESSIONS.lock().unwrap();
     let session = sessions
         .get(session_id)
         .ok_or(ViewerError::SessionNotFound(session_id.to_string()))?;
+
+    debug!(
+        "get_lines: session={}, backend_type={:?}, target={:?}, count={}",
+        session_id, session.backend_type, target, count
+    );
+
     session.backend.get_lines(&target, count)
 }
 
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 757e24cd..5cd564fe 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -186,7 +186,11 @@ pub fn run() {
                 let new_state = check_item.is_checked().unwrap_or(true);
 
                 // Emit event to frontend with the new state (main window only)
-                let _ = app.emit_to("main", "settings-changed", serde_json::json!({ "showHiddenFiles": new_state }));
+                let _ = app.emit_to(
+                    "main",
+                    "settings-changed",
+                    serde_json::json!({ "showHiddenFiles": new_state }),
+                );
             } else if id == VIEW_MODE_FULL_ID || id == VIEW_MODE_BRIEF_ID {
                 // Handle view mode toggle (radio button behavior)
                 let menu_state = app.state::<MenuState<tauri::Wry>>();
@@ -209,16 +213,16 @@ pub fn run() {
             } else if id == GO_BACK_ID || id == GO_FORWARD_ID || id == GO_PARENT_ID {
                 // Handle Go menu navigation actions - only when main window is focused
                 // This prevents shortcuts from affecting main window when viewer is open
-                if let Some(main_window) = app.get_webview_window("main") {
-                    if main_window.is_focused().unwrap_or(false) {
-                        let action = match id {
-                            GO_BACK_ID => "back",
-                            GO_FORWARD_ID => "forward",
-                            GO_PARENT_ID => "parent",
-                            _ => return,
-                        };
-                        let _ = app.emit_to("main", "navigation-action", serde_json::json!({ "action": action }));
-                    }
+                if let Some(main_window) = app.get_webview_window("main")
+                    && main_window.is_focused().unwrap_or(false)
+                {
+                    let action = match id {
+                        GO_BACK_ID => "back",
+                        GO_FORWARD_ID => "forward",
+                        GO_PARENT_ID => "parent",
+                        _ => return,
+                    };
+                    let _ = app.emit_to("main", "navigation-action", serde_json::json!({ "action": action }));
                 }
             } else if id == ABOUT_ID {
                 // Emit event to show our custom About window (main window only)
@@ -247,7 +251,11 @@ pub fn run() {
                     SORT_BY_CREATED_ID => "created",
                     _ => return,
                 };
-                let _ = app.emit_to("main", "menu-sort", serde_json::json!({ "action": "sortBy", "value": column }));
+                let _ = app.emit_to(
+                    "main",
+                    "menu-sort",
+                    serde_json::json!({ "action": "sortBy", "value": column }),
+                );
             } else if id == SORT_ASCENDING_ID || id == SORT_DESCENDING_ID {
                 // Handle sort order (main window only)
                 let order = if id == SORT_ASCENDING_ID { "asc" } else { "desc" };
@@ -289,6 +297,7 @@ pub fn run() {
             commands::file_system::start_selection_drag,
             commands::file_viewer::viewer_open,
             commands::file_viewer::viewer_get_lines,
+            commands::file_viewer::viewer_get_status,
             commands::file_viewer::viewer_search_start,
             commands::file_viewer::viewer_search_poll,
             commands::file_viewer::viewer_search_cancel,
diff --git a/apps/desktop/src/lib/logger.ts b/apps/desktop/src/lib/logger.ts
index 4528c6cb..616bc3cf 100644
--- a/apps/desktop/src/lib/logger.ts
+++ b/apps/desktop/src/lib/logger.ts
@@ -39,7 +39,8 @@ const debugCategories: string[] = [
     // 'fileExplorer',
     // 'dragDrop',
     // 'licensing',
-    'copyProgress', // Enable to debug copy operation progress events
+    // 'copyProgress', // Enable to debug copy operation progress events
+    // 'viewer', // Enable to debug file viewer streaming/caching
 ]
 
 /**
diff --git a/apps/desktop/src/lib/tauri-commands.ts b/apps/desktop/src/lib/tauri-commands.ts
index ced1c568..c4309087 100644
--- a/apps/desktop/src/lib/tauri-commands.ts
+++ b/apps/desktop/src/lib/tauri-commands.ts
@@ -310,9 +310,20 @@ export interface ViewerOpenResult {
     fileName: string
     totalBytes: number
     totalLines: number | null
+    /** Estimated total lines based on initial sample (for ByteSeek where totalLines is unknown) */
+    estimatedTotalLines: number
     backendType: 'fullLoad' | 'byteSeek' | 'lineIndex'
     capabilities: BackendCapabilities
     initialLines: LineChunk
+    /** Whether background indexing is in progress */
+    isIndexing: boolean
+}
+
+/** Current status of a viewer session. */
+export interface ViewerSessionStatus {
+    backendType: 'fullLoad' | 'byteSeek' | 'lineIndex'
+    isIndexing: boolean
+    totalLines: number | null
 }
 
 /** A search match found in the file. */
@@ -360,6 +371,11 @@ export async function viewerSearchCancel(sessionId: string): Promise<void> {
     await invoke('viewer_search_cancel', { sessionId })
 }
 
+/** Gets the current status of a viewer session (backend type, indexing state). */
+export async function viewerGetStatus(sessionId: string): Promise<ViewerSessionStatus> {
+    return invoke<ViewerSessionStatus>('viewer_get_status', { sessionId })
+}
+
 /** Closes a viewer session and frees resources. */
 export async function viewerClose(sessionId: string): Promise<void> {
     await invoke('viewer_close', { sessionId })
diff --git a/apps/desktop/src/routes/viewer/+page.svelte b/apps/desktop/src/routes/viewer/+page.svelte
index 9b35a0da..85a1bece 100644
--- a/apps/desktop/src/routes/viewer/+page.svelte
+++ b/apps/desktop/src/routes/viewer/+page.svelte
@@ -10,26 +10,40 @@
     const BUFFER_LINES = 50
     const FETCH_BATCH = 500
     const SEARCH_POLL_INTERVAL = 100
+    // Must match INDEXING_TIMEOUT_SECS in src-tauri/src/file_viewer/session.rs
+    const INDEXING_TIMEOUT_SECS = 5
 </script>
 
 <script lang="ts">
     import { onMount, onDestroy, tick } from 'svelte'
     import { SvelteMap } from 'svelte/reactivity'
-    import type { ViewerSearchMatch } from '$lib/tauri-commands'
+    import {
+        viewerOpen,
+        viewerGetLines,
+        viewerGetStatus,
+        viewerClose,
+        viewerSearchStart,
+        viewerSearchPoll,
+        viewerSearchCancel,
+        feLog,
+        type ViewerSearchMatch,
+        type BackendCapabilities,
+    } from '$lib/tauri-commands'
+    import { getCurrentWindow } from '@tauri-apps/api/window'
 
     let fileName = $state('')
     let totalLines = $state<number | null>(null)
+    let estimatedLines = $state(1) // Backend's estimate based on initial sample
     let totalBytes = $state(0)
     let error = $state('')
     let loading = $state(true)
     let sessionId = $state('')
     let backendType = $state<'fullLoad' | 'byteSeek' | 'lineIndex'>('fullLoad')
+    let capabilities = $state<BackendCapabilities | null>(null)
+    let isIndexing = $state(false)
 
-    // Line cache: lineNumber -> text
+    // Line cache: lineNumber -> text (sparse - may have gaps)
     const lineCache = new SvelteMap<number, string>()
-    // The range of lines currently in cache
-    let cachedFrom = $state(0)
-    let cachedTo = $state(0)
 
     // Virtual scroll state
     let scrollTop = $state(0)
@@ -44,6 +58,8 @@
     )
     const visibleLines = $derived(getVisibleLines())
     const gutterWidth = $derived(String(estimatedTotalLines()).length)
+    // Derive current mode: if we started with byteSeek but now have totalLines, we upgraded to lineIndex
+    const currentMode = $derived(backendType === 'byteSeek' && totalLines !== null ? 'lineIndex' : backendType)
 
     // Search state
     let searchVisible = $state(false)
@@ -55,13 +71,24 @@
     let searchInputRef: HTMLInputElement | undefined = $state()
     let searchPollTimer: ReturnType<typeof setInterval> | undefined
 
-    // Track pending fetches to avoid duplicate requests
-    let fetchingRange = $state(false)
+    // Fetch state: debounce timer and request ID for cancellation
+    let fetchDebounceTimer: ReturnType<typeof setTimeout> | undefined
+    let currentFetchId = 0 // Incremented on each fetch, used to ignore stale responses
+    const FETCH_DEBOUNCE_MS = 100
+
+    // Indexing status polling
+    let indexingPollTimer: ReturnType<typeof setInterval> | undefined
+    const INDEXING_POLL_INTERVAL = 500
+
+    // Window lifecycle state: prevents closing before WebKit is fully initialized
+    let windowReady = $state(false)
+    let closeRequested = $state(false)
 
     function estimatedTotalLines(): number {
+        // Use exact count if known (FullLoad or LineIndex backends)
         if (totalLines !== null) return totalLines
-        // Estimate based on average 80 bytes per line
-        return Math.max(1, Math.ceil(totalBytes / 80))
+        // Otherwise use backend's estimate based on initial sample (ByteSeek backend)
+        return estimatedLines
     }
 
     function getVisibleLines(): Array<{ lineNumber: number; text: string }> {
@@ -73,43 +100,114 @@
         return result
     }
 
-    // Fetch lines when visible range changes
+    /** Check if we need to fetch lines - returns true if any visible lines are missing from cache */
+    function needsFetch(from: number, to: number): boolean {
+        // Check a few sample points to avoid iterating the whole range
+        const samplesToCheck = [from, Math.floor((from + to) / 2), to - 1]
+        for (const line of samplesToCheck) {
+            if (line >= 0 && !lineCache.has(line)) {
+                return true
+            }
+        }
+        return false
+    }
+
+    // Fetch lines when visible range changes (debounced)
     $effect(() => {
         const from = visibleFrom
         const to = visibleTo
-        if (sessionId && !fetchingRange) {
-            // Check if we need to fetch
-            if (from < cachedFrom || to > cachedTo) {
-                void fetchLines(from, to)
-            }
+        if (sessionId && needsFetch(from, to)) {
+            scheduleFetch(from, to)
         }
     })
 
+    function scheduleFetch(from: number, to: number) {
+        // Clear any pending fetch
+        if (fetchDebounceTimer) {
+            clearTimeout(fetchDebounceTimer)
+        }
+        // Schedule new fetch after debounce
+        fetchDebounceTimer = setTimeout(() => {
+            void fetchLines(from, to)
+        }, FETCH_DEBOUNCE_MS)
+    }
+
+    /** Update totalLines while preserving scroll fraction to prevent jump when height shrinks */
+    function updateTotalLines(newTotal: number) {
+        const oldEstimate = estimatedTotalLines()
+        if (!contentRef || oldEstimate === 0 || newTotal === oldEstimate) {
+            totalLines = newTotal
+            return
+        }
+        // Calculate current scroll fraction before updating
+        const oldHeight = oldEstimate * LINE_HEIGHT
+        const scrollFraction = contentRef.scrollTop / oldHeight
+        feLog(
+            `[viewer] totalLines changed: ${String(oldEstimate)} -> ${String(newTotal)}, preserving scroll fraction ${scrollFraction.toFixed(3)}`,
+        )
+        totalLines = newTotal
+        // Restore scroll fraction after DOM updates using rAF to run after browser's scroll clamping
+        const newHeight = newTotal * LINE_HEIGHT
+        const newScrollTop = Math.round(scrollFraction * newHeight)
+        const ref = contentRef // Capture reference for rAF callback
+        requestAnimationFrame(() => {
+            ref.scrollTop = newScrollTop
+        })
+    }
+
     async function fetchLines(from: number, to: number) {
-        if (!sessionId || fetchingRange) return
-        fetchingRange = true
+        if (!sessionId) return
+
+        // Increment fetch ID to invalidate any in-flight requests
+        const fetchId = ++currentFetchId
+
         try {
-            const { viewerGetLines } = await import('$lib/tauri-commands')
             // Fetch a larger batch to reduce round-trips
             const fetchFrom = Math.max(0, from - BUFFER_LINES)
             const fetchCount = Math.min(FETCH_BATCH, to - fetchFrom + BUFFER_LINES * 2)
-            const chunk = await viewerGetLines(sessionId, 'line', fetchFrom, fetchCount)
+
+            // Decide seek type based on backend capabilities
+            const supportsLineSeek = capabilities?.supportsLineSeek ?? false
+            const seekType = supportsLineSeek ? 'line' : 'fraction'
+            const seekValue = supportsLineSeek ? fetchFrom : fetchFrom / estimatedTotalLines()
+
+            feLog(
+                `[viewer] fetchLines[${String(fetchId)}]: requesting ${seekType}=${String(seekValue)} count=${String(fetchCount)}`,
+            )
+
+            const chunk = await viewerGetLines(sessionId, seekType, seekValue, fetchCount)
+
+            // Check if this response is still relevant (no newer fetch started)
+            if (fetchId !== currentFetchId) {
+                feLog(
+                    `[viewer] fetchLines[${String(fetchId)}]: discarding stale response (current=${String(currentFetchId)})`,
+                )
+                return
+            }
+
+            // When using fraction seek, cache at the requested position since backend's line number
+            // estimate may differ from frontend's estimate (different avg line length assumptions).
+            // For line seek, use backend's authoritative line numbers.
+            const cacheStartLine = seekType === 'fraction' ? fetchFrom : chunk.firstLineNumber
+
+            feLog(
+                `[viewer] fetchLines[${String(fetchId)}]: received ${String(chunk.lines.length)} lines, backend says firstLine=${String(chunk.firstLineNumber)}, caching at ${String(cacheStartLine)}`,
+            )
 
             // Update cache
             for (let i = 0; i < chunk.lines.length; i++) {
-                lineCache.set(chunk.firstLineNumber + i, chunk.lines[i])
+                lineCache.set(cacheStartLine + i, chunk.lines[i])
             }
-            cachedFrom = Math.min(cachedFrom, chunk.firstLineNumber)
-            cachedTo = Math.max(cachedTo, chunk.firstLineNumber + chunk.lines.length)
 
             // Update totalLines if backend now knows it
-            if (chunk.totalLines !== null) {
-                totalLines = chunk.totalLines
+            if (chunk.totalLines !== null && chunk.totalLines !== totalLines) {
+                updateTotalLines(chunk.totalLines)
+            }
+        } catch (e) {
+            // Only log if this is still the current request
+            if (fetchId === currentFetchId) {
+                feLog(`[viewer] fetchLines[${String(fetchId)}]: failed with error ${String(e)}`)
             }
-        } catch {
-            // Fetch failed, will retry on next scroll
-        } finally {
-            fetchingRange = false
         }
     }
 
@@ -129,7 +227,6 @@
         searchProgress = 0
 
         try {
-            const { viewerSearchStart } = await import('$lib/tauri-commands')
             await viewerSearchStart(sessionId, query)
             pollSearch()
         } catch {
@@ -147,7 +244,6 @@
     async function pollSearchTick() {
         if (!sessionId) return
         try {
-            const { viewerSearchPoll } = await import('$lib/tauri-commands')
             const result = await viewerSearchPoll(sessionId)
             searchMatches = result.matches
             searchProgress = totalBytes > 0 ? result.bytesScanned / totalBytes : 0
@@ -175,7 +271,6 @@
         stopSearchPoll()
         if (!sessionId) return
         try {
-            const { viewerSearchCancel } = await import('$lib/tauri-commands')
             await viewerSearchCancel(sessionId)
         } catch {
             // Ignore
@@ -183,6 +278,40 @@
         searchStatus = 'idle'
     }
 
+    // Indexing status polling functions
+    function startIndexingPoll() {
+        stopIndexingPoll()
+        indexingPollTimer = setInterval(() => {
+            void pollIndexingStatus()
+        }, INDEXING_POLL_INTERVAL)
+    }
+
+    async function pollIndexingStatus() {
+        if (!sessionId) return
+        try {
+            const status = await viewerGetStatus(sessionId)
+            backendType = status.backendType
+            isIndexing = status.isIndexing
+            if (status.totalLines !== null) {
+                totalLines = status.totalLines
+            }
+            // Stop polling when indexing is done
+            if (!status.isIndexing) {
+                feLog(`[viewer] Indexing finished, backendType=${status.backendType}`)
+                stopIndexingPoll()
+            }
+        } catch {
+            stopIndexingPoll()
+        }
+    }
+
+    function stopIndexingPoll() {
+        if (indexingPollTimer) {
+            clearInterval(indexingPollTimer)
+            indexingPollTimer = undefined
+        }
+    }
+
     function openSearch() {
         searchVisible = true
         void tick().then(() => {
@@ -234,21 +363,41 @@
         }
     })
 
-    async function closeWindow() {
+    function closeWindow() {
+        // If window isn't ready yet, queue the close for when it is
+        if (!windowReady) {
+            feLog('[viewer] closeWindow: window not ready, queueing close')
+            closeRequested = true
+            return
+        }
+
+        const start = performance.now()
+        feLog('[viewer] closeWindow: starting')
+
+        // Session cleanup first (fire-and-forget) - do this before closing
         if (sessionId) {
-            try {
-                const { viewerClose } = await import('$lib/tauri-commands')
-                await viewerClose(sessionId)
-            } catch {
+            viewerClose(sessionId).catch(() => {
                 // Ignore - session cleanup is best-effort
-            }
-        }
-        try {
-            const { getCurrentWindow } = await import('@tauri-apps/api/window')
-            await getCurrentWindow().close()
-        } catch {
-            // Not in Tauri environment
+            })
         }
+
+        const currentWindow = getCurrentWindow()
+
+        // Use double requestAnimationFrame to let WebKit finish pending content inset
+        // updates before destroying the WebPageProxy. Single rAF isn't enough - we need
+        // to wait for the current frame to complete AND the next frame to start.
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                feLog(`[viewer] closeWindow: calling close() after ${String(Math.round(performance.now() - start))}ms`)
+                currentWindow.close().catch((e: unknown) => {
+                    feLog(`[viewer] closeWindow: close failed: ${String(e)}`)
+                })
+            })
+        })
+
+        // NOTE: Don't call getAllWindows().setFocus() here - it can trigger WebKit to
+        // recalculate content insets on the dying window, causing a crash. macOS will
+        // automatically focus the main window when this one closes.
     }
 
     function scrollByLines(lines: number) {
@@ -311,10 +460,11 @@
 
         if (e.key === 'Escape') {
             e.preventDefault()
+            feLog(`[viewer] ESC pressed, searchVisible=${String(searchVisible)}, windowReady=${String(windowReady)}`)
             if (searchVisible) {
                 closeSearch()
             } else {
-                void closeWindow()
+                closeWindow()
             }
             return
         }
@@ -379,43 +529,65 @@
         }
 
         try {
-            const { viewerOpen } = await import('$lib/tauri-commands')
             const result = await viewerOpen(filePath)
 
             sessionId = result.sessionId
             fileName = result.fileName
             totalBytes = result.totalBytes
             totalLines = result.totalLines
+            estimatedLines = result.estimatedTotalLines
             backendType = result.backendType
+            capabilities = result.capabilities
+            isIndexing = result.isIndexing
+
+            feLog(
+                `[viewer] Opened file: ${result.fileName}, ${String(result.totalBytes)} bytes, totalLines=${String(result.totalLines)}, estimatedTotalLines=${String(result.estimatedTotalLines)}, backend=${result.backendType}, isIndexing=${String(result.isIndexing)}`,
+            )
+
+            // Start polling for indexing status if indexing is in progress
+            if (result.isIndexing) {
+                startIndexingPoll()
+            }
 
             // Populate cache with initial lines
             lineCache.clear()
             for (let i = 0; i < result.initialLines.lines.length; i++) {
                 lineCache.set(result.initialLines.firstLineNumber + i, result.initialLines.lines[i])
             }
-            cachedFrom = result.initialLines.firstLineNumber
-            cachedTo = result.initialLines.firstLineNumber + result.initialLines.lines.length
-
-            // Set window title
-            try {
-                const { getCurrentWindow } = await import('@tauri-apps/api/window')
-                await getCurrentWindow().setTitle(`${result.fileName} — Viewer`)
-            } catch {
-                // Not in Tauri environment
-            }
+
+            feLog(`[viewer] Initial cache: ${String(result.initialLines.lines.length)} lines loaded`)
+
+            // Set window title (fire-and-forget, don't block)
+            getCurrentWindow()
+                .setTitle(`${result.fileName} — Viewer`)
+                .catch(() => {
+                    // Not in Tauri environment
+                })
         } catch (e) {
             error = typeof e === 'string' ? e : 'Failed to read file'
+            feLog(`[viewer] Failed to open file: ${String(e)}`)
         } finally {
             loading = false
             // Auto-focus the container so keyboard events work immediately
             await tick()
             containerRef?.focus()
+
+            // Mark window as ready after WebKit has had a frame to settle
+            requestAnimationFrame(() => {
+                windowReady = true
+                feLog(`[viewer] Window ready, closeRequested=${String(closeRequested)}`)
+                if (closeRequested) {
+                    closeWindow()
+                }
+            })
         }
     })
 
     onDestroy(() => {
         stopSearchPoll()
+        stopIndexingPoll()
         if (searchDebounceTimer) clearTimeout(searchDebounceTimer)
+        if (fetchDebounceTimer) clearTimeout(fetchDebounceTimer)
     })
 </script>
 
@@ -494,8 +666,29 @@
             <span>{totalLines} {totalLines === 1 ? 'line' : 'lines'}</span>
         {/if}
         <span>{formatSize(totalBytes)}</span>
-        {#if backendType !== 'fullLoad'}
-            <span class="backend-badge">{backendType === 'lineIndex' ? 'indexed' : 'streaming'}</span>
+        {#if currentMode === 'fullLoad'}
+            <span
+                class="backend-badge"
+                title="You have the file entirely in memory. You can quickly scroll to any line.">in memory</span
+            >
+        {:else if currentMode === 'lineIndex'}
+            <span
+                class="backend-badge"
+                title="You have the file indexed, so the line numbers are accurate, and you can quickly scroll to any point."
+                >indexed</span
+            >
+        {:else if isIndexing}
+            <span
+                class="backend-badge"
+                title="This is a large file in streaming mode. We're building an index in background (max {INDEXING_TIMEOUT_SECS} sec)... Line numbers are currently approximate."
+                >streaming, indexing...</span
+            >
+        {:else}
+            <span
+                class="backend-badge"
+                title="This is a large file in streaming mode. Indexing would've taken longer than {INDEXING_TIMEOUT_SECS} sec, so we didn't do it. The line numbers are estimates."
+                >streaming</span
+            >
         {/if}
         <span class="shortcut-hint">Ctrl+F search &middot; Esc close</span>
     </div>
@@ -506,7 +699,7 @@
         display: flex;
         flex-direction: column;
         height: 100vh;
-        font-family: var(--font-system);
+        font-family: var(--font-system) sans-serif;
         background: var(--color-bg-primary);
         color: var(--color-text-primary);
         outline: none;
@@ -531,7 +724,7 @@
         background: var(--color-bg-primary);
         color: var(--color-text-primary);
         font-size: var(--font-size-sm);
-        font-family: var(--font-system);
+        font-family: var(--font-system) sans-serif;
     }
 
     .search-input:focus {

From add670017742765e5be624e12d24d8143019de23 Mon Sep 17 00:00:00 2001
From: David Veszelovszki <veszelovszki@gmail.com>
Date: Wed, 28 Jan 2026 13:22:05 +0100
Subject: [PATCH 16/16] Disable AI mode in dev by default

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 9a5eb062..83f6ba40 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
     "packageManager": "pnpm@10.27.0",
     "scripts": {
         "preinstall": "npx only-allow pnpm",
-        "dev": "CMDR_REAL_AI=1 RUST_LOG=${RUST_LOG:-smb=warn,sspi=warn,info} pnpm --filter @cmdr/desktop tauri dev",
+        "dev": "RUST_LOG=${RUST_LOG:-smb=warn,sspi=warn,info} pnpm --filter @cmdr/desktop tauri dev",
         "dev:ai-debug": "CMDR_REAL_AI=1 RUST_LOG=cmdr_lib::ai=debug,smb=warn,sspi=warn,info pnpm --filter @cmdr/desktop tauri dev",
         "build": "pnpm --filter @cmdr/desktop tauri build",
         "dev:website": "pnpm --filter @cmdr/website dev",