TUI shell · Epic · Cohesive coco ui navigation model

[gfargo]

Vision

Evolve coco ui from "Ink runtime that opens at one of three views via --view" into a true navigable shell, where every git surface is reachable from every other one and the UX between screens feels designed, not glued. Long-term ambition: coco ui is the daily driver for git — power, flow, and functionality on par with lazygit, gitui, and k9s.

Design pillars

• Stateful navigation — view stack with push/pop/replace; named intents (openDiffForCommit, openComposeForFile, etc.); preserved context across transitions (selected commit follows the user between history and diff).
• Cross-view keybindings — global jumps (g h/g s/g d/g c/g b/g t) plus contextual transitions (enter on a commit → diff for that commit; c from any view with a dirty tree → compose).
• Persistent shell chrome — header with breadcrumb, status/footer with view-aware hints, view-agnostic help overlay grouped by Global vs This view.
• Promotable surfaces — branches, tags, stash, and commit compose all become first-class views over time, not modals nested inside other views.
• Power features — command palette (:), global search across views, configurable keymaps.
• Discipline — preserve coco log stdout/JSON output, lazy-load expensive detail, and stay friendly to NO_COLOR / ASCII terminals.

Phased plan

Phase	Issue	Description
1	#740	Navigation primitives & view stack (plumbing)
2	#741	Persistent shell chrome (header, footer, help)
3	#742	Cross-view keybindings & contextual transitions
4	#743	Promote commit compose to a top-level view
5	#744	Promote branches, tags, and stash to top-level views
6	#745	Command palette and global search
7	#746	Polish pass: empty/loading/error states + theming audit

Phases land in roughly that order. 1 and 2 are foundation. 3 is the user-visible unlock. 4 and 5 can run in parallel after 3 lands. 6 depends on the bulk of the surface area existing. 7 is last-mile.

Inspirations

• lazygit — tabbed surfaces, numbered jumps, contextual help, optimistic UI.
• gitui — modal feel, fast navigation, branch-as-resource.
• k9s — : command palette, view stack, status-driven chrome.
• yazi — peek/preview pane discipline, stateful tabs.

Non-goals (for this epic)

• Replacing coco commit, coco changelog, etc. as separate commands — those stay. coco ui is an additive interactive surface.
• Custom rendering engines — we stay on Ink + React 19.
• Mouse support — keyboard-first throughout.