Proposal: sidebar destination selection

[pmarchini]

Summary

Faro currently exposes one sidebar webview and switches between home, path, and setup as internal routes inside that surface.

That keeps the VS Code container simple, but it also mixes three distinct concerns behind one composite view:

• onboarding and orientation
• path reading and navigation
• agent/tooling setup

This creates both product complexity and implementation complexity, and it limits future refactors because route-specific UI concerns remain coupled through one webview shell.

Goal

Choose a clearer top-level navigation model for the Faro sidebar that:

• lowers cognitive complexity for users
• lowers architectural complexity in the UI layer
• stays aligned with VS Code-native navigation affordances
• keeps future refactors easier and more local

Option A: Three Views

Split the current composite sidebar into three separate VS Code views under the Faro container:

• Home
• Path
• Setup

Why consider this:

• each view owns one coherent responsibility
• route-switching logic inside one composite provider can be removed or reduced sharply
• route-specific loading and transient state can stay local to the relevant view
• future refactors can target one destination without reopening the entire shell

Hard constraint:

• common UI building blocks MUST be extracted before or alongside the split
• separate views MUST reuse shared UI modules for repeated presentation and interaction patterns
• shared building blocks MUST cover repeated CSS tokens, layout primitives, action bars, cards, empty states, notices, and modal/confirmation surfaces
• the split is not acceptable if it creates parallel styling systems or diverging implementations of the same UI behavior

Option B: One View With Three Commands

Keep one Faro webview, but replace the current in-webview route buttons with three VS Code-native commands exposed from the view title area:

• Open Home
• Open Path
• Open Setup

Why consider this:

• it keeps the current architecture mostly intact
• it uses VS Code-native chrome more effectively than custom route buttons inside the webview
• it reduces visible in-webview navigation without requiring a larger split across multiple views
• it is likely the smallest migration from the current implementation

Constraint:

• command-based selection should map onto one canonical selected-destination state
• the UI must not depend on a native dropdown passing arbitrary values directly into the webview
• route-specific cleanup and loading behavior must remain explicit and testable

Decision Criteria

Evaluate the two options against:

• cognitive load for users
• cognitive load in the codebase
• alignment with VS Code-native navigation patterns
• migration cost from the current implementation
• ease of future refactors
• ability to preserve shared UI consistency without duplication

Recommendation Shape

• prefer Option A if the priority is reducing long-term UI and architectural complexity
• prefer Option B if the priority is incremental delivery with minimal churn to the current implementation

Option A is the stronger long-term structural move, but only if shared UI building blocks are extracted as a hard requirement rather than deferred cleanup.

Proposal File

This issue tracks the proposal captured in:

• proposals/todo/sidebar-destination-selection.md