# Ticket 4.4 — File Browser

**Phase**: 4 — Frontend UI
**Priority**: Medium
**Depends on**: 4.1, 1.4

## Description

Sidebar file tree for browsing project files directly from the web UI. Supports directory navigation, file content preview, and live updates when files change.

## Acceptance Criteria

### AC1: Directory tree displays project structure

```gherkin
Given the project has a standard directory structure
When the user opens the file browser panel
Then it shows the root directory contents
And directories are expandable/collapsible
And files show appropriate icons by extension
And the tree is sorted: directories first, then files alphabetically
```

### AC2: File content preview

```gherkin
Given a file "src/index.js" exists
When the user clicks on it in the file tree
Then the file content is displayed in a read-only viewer
And the content has syntax highlighting based on file extension
And line numbers are shown
```

### AC3: Breadcrumb navigation

```gherkin
Given the user is browsing src/components/Button.tsx
When the breadcrumb shows: root > src > components > Button.tsx
Then clicking "src" navigates to the src/ directory
And clicking "root" navigates to the project root
```

### AC4: Binary file handling

```gherkin
Given a file "logo.png" exists
When the user clicks on it
Then it shows "Binary file — cannot preview" instead of garbled content
And image files show a thumbnail preview
```

### AC5: File watcher for live updates

```gherkin
Given the file browser is showing src/
When a new file is created in src/ by the agent
Then the file tree updates to include the new file
And modified files show a visual indicator
And the update happens within 1 second
```

### AC6: Large directory handling

```gherkin
Given a directory contains 500+ files (e.g., node_modules)
When the user expands it
Then only the first 100 entries are shown initially
And a "Show more" link appears
And node_modules is collapsed by default with a hint
```

## Testable Components

| Component | Test Type | What to Assert |
|-----------|-----------|----------------|
| Binary file detection | Unit | Detects binary extensions, returns appropriate flag |
| Directory tree rendering | E2E | Correct folder/file structure with icons |
| Expand/collapse folders | E2E | Click toggles visibility, children loaded lazily |
| File content preview | E2E | Clicking file shows content with syntax highlighting and line numbers |
| Breadcrumb navigation | E2E | Breadcrumb links navigate to correct parent directory |
| File watcher updates | E2E | New/modified files appear in tree without manual refresh |
| Large directory pagination | E2E | Shows first 100 entries with "Show more" link |

## Reference

- Claude-relay file browser: `../claude-relay/lib/public/modules/sidebar.js`
- Claude-relay file API: `../claude-relay/lib/project.js` (fs_list, fs_read handlers)
- OpenCode file API: `GET /file?path=` (list directory), `GET /file/content?path=` (read file), `GET /file/status` (git status)
- File change events via SSE: `file.edited`, `file.watcher.updated` (see ticket 1.3)
