File Tree Browser

Overview

A hierarchical file browser that displays a project's directory structure using OutlineGroup/List with lazy child loading, git status badges, configurable ignore patterns, and SF Symbol icons themed by file type. Serves as the primary navigation sidebar for project-based workflows.

Terminology

Behavioral Requirements

Tree display

• outline-group-hierarchy: The file tree MUST render using List + OutlineGroup to provide expandable/collapsible directory hierarchy.
• lazy-child-loading: The tree MUST use lazy child loading — children MUST be loaded on demand when a directory is expanded, not when the tree is first rendered.
• parallel-top-level-scan: Top-level directories MUST be scanned in parallel via OperationQueue for faster initial load.
• sidebar-list-style: The tree MUST use .listStyle(.sidebar) on Apple platforms.

Sorting

• dirs-first-alpha-sort: Entries MUST be sorted with directories first, then files. Within each group, entries MUST be sorted alphabetically using case-insensitive comparison.

Filtering and visibility

• fnmatch-ignore-patterns: Ignore patterns MUST use POSIX fnmatch() wildcards (*, ?). Entries matching any ignore pattern MUST be hidden from the tree.
• show-dotfiles: Hidden files (dotfiles) MUST be shown in the tree.
• hide-ds-store: .DS_Store files MUST always be hidden regardless of ignore patterns (hardcoded skip).

Packages

• package-dir-display: Directories recognized as packages (e.g., .catnip-proj and other registered package extensions) MUST be displayed as single non-expandable items with the package icon.

Selection

• single-file-selection: The tree MUST support single file selection via a selection binding.

Git status integration

• git-status-badge: Each file row MUST display a git status badge when the file has a git status. The badge MUST be right-aligned, use a monospaced font, and be colored per status type. Badge rendering MUST delegate to git-status-indicator.md.
• git-debounce-refresh: Git status MUST refresh with a 0.5-second debounce after file changes to prevent thrashing.
• git-background-fetch: Git status MUST be fetched on a background queue and MUST NOT block the main thread.

Status bar integration

• sync-status-bar: During directory sync operations, a status bar overlay MUST be shown. Display MUST delegate to status-bar.md.

Directory sync lifecycle

• delegate-directory-sync: File system monitoring and sync behavior MUST delegate to directory-sync.md.

Appearance

Row layout

┌──────────────────────────────────────────────┐
│  📁 Sources                              M   │
│    📄 App.swift                          A   │
│    📄 ContentView.swift                  M   │
│  📁 Tests                                    │
│  📦 MyPlugin.catnip-proj                     │
│  📄 Package.swift                            │
│  📄 README.md                                │
│  📄 .gitignore                               │
└──────────────────────────────────────────────┘

• Row content: Icon (colored per type) + file name + optional git status badge (right-aligned)
• File name: Single line, truncated with middle truncation if too long
• Tooltip: Full path of the entry
• Icon size: Body-scaled SF Symbol
• List style: .sidebar on Apple platforms

Icon theming

Packages

Special directories

Files by extension

Defaults

States

Accessibility

• row-accessible-label: Each row MUST have an accessibility label that includes the entry name and type (file or directory).
• git-badge-accessible: Git status badges MUST have accessibility labels with the full status name (e.g., "Modified") rather than the single character.
• keyboard-tree-nav: The tree MUST be navigable via keyboard — arrow keys to move between rows, Right arrow to expand, Left arrow to collapse.
• voiceover-row-announce: VoiceOver MUST announce the entry name, type, and git status (if any) when a row gains focus.
• icon-shape-not-color: Color MUST NOT be the sole differentiator for file type icons — the distinct SF Symbol shapes provide differentiation without color.

Conformance Test Vectors

Edge Cases

• Empty project directory: Tree SHOULD display an empty state rather than a blank sidebar. MAY delegate to an empty-state component.
• Very deep nesting (20+ levels): Tree MUST remain scrollable and responsive. Indentation SHOULD cap or compress at extreme depths.
• Very large directory (10k+ entries): Lazy loading (lazy-child-loading) and parallel scanning (parallel-top-level-scan) mitigate load time. The tree SHOULD remain responsive.
• Permission denied on directory: The directory SHOULD show as non-expandable. An error SHOULD be logged but not surfaced to the user as a modal alert.
• Symlink loops: The scanner MUST detect and break symlink cycles to prevent infinite recursion.
• File disappears between scan and display: The tree SHOULD gracefully handle stale entries — remove them on next refresh rather than crash.
• Ignore pattern changed while tree is visible: Tree MUST fully resync to apply new pattern.
• Directory renamed externally: Directory sync (delegate-directory-sync) handles this — tree updates on next sync cycle.
• No git repository: Git status badges not shown, no error. Tree renders without badges.
• File tree does NOT include a search/filter UI: This is noted as a future option and is explicitly out of scope for this spec.

Configuration

This ingredient has no configurable options.

Project Settings

• per-project-settings: Both settings MUST be configured per-project.
• setting-change-resync: Changing either setting MUST trigger a full resync of the file tree.

Logging

Subsystem: {{bundle_id}} | Category: FileTreeBrowser

Accessibility Options

Platform Notes

• SwiftUI: Use List with OutlineGroup and .listStyle(.sidebar). Model FileTreeNode as an ObservableObject with @Published children: [FileTreeNode]? (nil = not yet loaded, empty = loaded but empty). Load children on OutlineGroup's children keypath access. Git status fetched via a separate provider running on a background DispatchQueue. Parallel scanning via OperationQueue with maxConcurrentOperationCount set to maxScanWorkers. Ignore patterns evaluated using fnmatch() from Darwin. Icons via Image(systemName:) with .foregroundStyle() for theming. Tooltips via .help() modifier (macOS).
• visionOS: Same SwiftUI implementation as macOS. List renders in a volume or window with standard sidebar appearance. No platform-specific adjustments beyond standard visionOS adaptations.
• iOS: Same SwiftUI implementation. Sidebar presented in NavigationSplitView sidebar column. Disclosure indicators use standard iOS chevron style.

Design Decisions

None yet -- decisions made during implementation should be recorded here.

Change History