20260619

docs/ui-layout.md

@@ -0,0 +1,120 @@
+# UI layout boundaries
+
+The UI should follow a FinalShell-style work layout: navigation on the left,
+tabs and terminal workspace in the center, and operational tools as separate
+panels. Keep one terminal per tab. Terminal split panes are intentionally not
+part of the product surface because they couple session lifecycle, resize,
+SFTP, resource sampling, and focus handling too tightly.
+
+## Independent Components
+
+### AppShell
+
+Owns the top-level layout only:
+
+- left navigation width
+- main workspace area
+- top-right global actions
+- modal/popup mounting
+
+It should not own terminal rendering, SFTP state, or session form details.
+
+### ConnectionNavigator
+
+Left-side session tree/list, similar to FinalShell's connection manager:
+
+- session groups
+- saved sessions
+- quick connect entry points
+- edit/delete/import actions
+
+This should replace putting the full session list on the welcome page as the
+primary workflow. The welcome page can remain a light empty state.
+
+### WorkspaceTabs
+
+Owns tab metadata and switching:
+
+- welcome tab
+- terminal tabs
+- close/select/new-tab commands
+
+It should not know about SFTP rows, terminal spans, or resource graphs.
+
+### TerminalWorkspace
+
+Owns the active terminal tab content area:
+
+- one `TerminalView` per active terminal tab
+- keyboard focus routing
+- terminal resize forwarding
+- terminal status line
+
+No split panes. If multiple terminals are needed, open multiple tabs.
+
+### TerminalToolbar
+
+Commands around the terminal should be separate from terminal rendering:
+
+- command input
+- run/save snippet buttons
+- snippet popup
+- find toggle
+- copy/paste/clear actions
+
+This keeps terminal grid rendering focused on VT output and selection.
+
+### FilePanel
+
+SFTP should be an independent panel, not terminal internals:
+
+- remote path
+- remote tree
+- file list
+- upload/download/view/edit/delete
+- loading/status text
+
+It can be docked below or to the right of the terminal, but its data model
+should remain separate from terminal spans and cursor state.
+
+### ResourcePanel
+
+Local/remote machine stats should be independent:
+
+- connection status
+- CPU/memory/swap
+- network graphs
+- disk usage
+
+It may live in the left sidebar initially, but it should not be mixed with
+session navigation logic.
+
+### TransferManager
+
+Global transfer history/progress:
+
+- active transfers
+- completed transfers
+- failed transfers
+- clear/open download folder actions
+
+This remains global because downloads can outlive tab focus.
+
+### SessionEditor
+
+Session creation and editing should stay modal and isolated:
+
+- SSH/Telnet/Serial fields
+- auth fields
+- key picker
+- validation and save/cancel
+
+It should not manipulate tab/terminal models directly.
+
+## Current Refactor Priority
+
+1. Remove terminal split panes and keep one terminal per tab.
+2. Move session navigation out of the welcome screen into an independent left
+   component.
+3. Split `TerminalView` into terminal grid, command toolbar, and SFTP/file panel.
+4. Keep resource stats and transfer manager as independent global panels.