fix(ui): scroll branch tree selections (#1058)

Implement scrolling for branch selection prompts
when the terminal cannot show all matching branches.

Add viewport support to `fliptree`
as the renderer that owns line-by-line tree output,
including scroll marker rendering.
Keep `branchtree` as the branch-specific adapter
that passes viewport settings through,
and keep `BranchTreeSelect` responsible for
selection state, filter matching,
and choosing the viewport offset.

Extend the UI script harness
to accept per-script terminal sizes,
and add regression coverage for
constrained-height scrolling
and preserving an already selected branch
when filtering still matches it.

Author: abhinav

.changes/unreleased/Fixed-20260311-060727.yaml

@@ -0,0 +1,3 @@
+kind: Fixed
+body: Branch selection prompt now scrolls when the terminal is too short to show all matching branches.
+time: 2026-03-11T06:07:27.684554-07:00

doc/tapes/20260312-branch-checkout-scroll.gif

@@ -0,0 +1,61 @@
+Output "20260312-branch-checkout-scroll.gif"
+Set Shell "bash"
+Set FontSize 16
+Set Width 480
+Set Height 260
+Set Padding 10
+Set CursorBlink false
+
+Hide
+Type "cd $(mktemp -d) && git init && git commit --allow-empty -m 'Initial commit'" Enter
+Type "alias gs=git-spice" Enter
+Type "gs repo init" Enter Sleep 100ms
+Type "git add lion && gs branch create lion -m 'Add lion'" Enter Sleep 100ms
+Type "touch griffin && git add griffin && gs branch create griffin -m 'Add griffin'" Enter Sleep 100ms
+Type "gs branch checkout main" Enter Sleep 100ms
+Type "touch squid && git add squid && gs branch create squid -m 'Add squid'" Enter Sleep 100ms
+Type "touch kraken && git add kraken && gs branch create kraken -m 'Add kraken'" Enter Sleep 100ms
+Type "gs branch checkout main" Enter Sleep 100ms
+Type "touch snake && git add snake && gs branch create snake -m 'Add snake'" Enter Sleep 100ms
+Type "touch basilisk && git add basilisk && gs branch create basilisk -m 'Add basilisk'" Enter Sleep 100ms
+Type "gs branch checkout main" Enter Sleep 100ms
+Type "touch eagle && git add eagle && gs branch create eagle -m 'Add eagle'" Enter Sleep 100ms
+Type "touch phoenix && git add phoenix && gs branch create phoenix -m 'Add phoenix'" Enter Sleep 100ms
+Type "gs branch checkout main" Enter Sleep 100ms
+Type "touch scorpion && git add scorpion && gs branch create scorpion -m 'Add scorpion'" Enter Sleep 100ms
+Type "touch manticore && git add manticore && gs branch create manticore -m 'Add manticore'" Enter Sleep 100ms
+Type "clear" Enter Sleep 100ms
+Show
+
+Sleep 500ms
+
+Type "gs ls" Enter
+Sleep 2s
+
+Type "gs bco" Enter
+Sleep 2s
+
+Down
+Sleep 300ms
+Down
+Sleep 300ms
+Down
+Sleep 300ms
+Down
+Sleep 300ms
+Down
+Sleep 1s
+
+Down
+Sleep 300ms
+Down
+Sleep 1s
+
+Up
+Sleep 1s
+
+Enter
+Sleep 2s
+
+Type "gs ls" Enter
+Sleep 3s

doc/tapes/20260312-branch-checkout-scroll.tape

@@ -225,6 +225,13 @@ type GraphOptions struct {
 	// HomeDir is used for "~" substitution in worktree paths.
 	// If empty, no substitution is performed.
 	HomeDir string
+
+	// Offset is the number of rendered lines to skip.
+	Offset int
+
+	// Height is the maximum number of rendered lines to show.
+	// Zero or negative means render all lines.
+	Height int
 }
 
 // PushStatusFormat controls how push status is rendered.
@@ -262,18 +269,16 @@ func Write(w io.Writer, g Graph, opts *GraphOptions) error {
 		HomeDir:          opts.HomeDir,
 	}
 
-	treeStyle := &fliptree.Style[*Item]{
-		Joint: ui.NewStyle().Faint(true),
-		NodeMarker: func(item *Item) ui.Style {
-			switch {
-			case item.Disabled:
-				return opts.Style.NodeMarkerDisabled
-			case item.Highlighted:
-				return opts.Style.NodeMarkerHighlighted
-			default:
-				return opts.Style.NodeMarker
-			}
-		},
+	treeStyle := fliptree.DefaultStyle[*Item]()
+	treeStyle.NodeMarker = func(item *Item) ui.Style {
+		switch {
+		case item.Disabled:
+			return opts.Style.NodeMarkerDisabled
+		case item.Highlighted:
+			return opts.Style.NodeMarkerHighlighted
+		default:
+			return opts.Style.NodeMarker
+		}
 	}
 
 	return fliptree.Write(w, fliptree.Graph[*Item]{
@@ -282,8 +287,10 @@ func Write(w io.Writer, g Graph, opts *GraphOptions) error {
 		Edges:  func(item *Item) []int { return item.Aboves },
 		View:   renderer.RenderItem,
 	}, fliptree.Options[*Item]{
-		Theme: opts.Theme,
-		Style: treeStyle,
+		Theme:  opts.Theme,
+		Style:  treeStyle,
+		Offset: opts.Offset,
+		Height: opts.Height,
 	})
 }
 

internal/ui/branchtree/tree.go

@@ -13,6 +13,8 @@ package fliptree
 
 import (
 	"bufio"
+	"bytes"
+	"fmt"
 	"io"
 	"slices"
 	"strings"
@@ -24,6 +26,18 @@ import (
 // DefaultNodeMarker is the marker used for each node in the tree.
 var DefaultNodeMarker = ui.NewStyle().SetString("□")
 
+// DefaultScrollUpMarker is the marker shown
+// when content is scrolled out above the viewport.
+var DefaultScrollUpMarker = ui.NewStyle().
+	Foreground(ui.Gray).
+	SetString("▲▲▲")
+
+// DefaultScrollDownMarker is the marker shown
+// when content is scrolled out below the viewport.
+var DefaultScrollDownMarker = ui.NewStyle().
+	Foreground(ui.Gray).
+	SetString("▼▼▼")
+
 // Graph defines a directed graph.
 type Graph[T any] struct {
 	// Values specifies the value for each node in the graph.
@@ -49,6 +63,15 @@ type Graph[T any] struct {
 type Options[T any] struct {
 	Theme ui.Theme
 	Style *Style[T]
+
+	// Offset states the number of lines to skip before rendering the tree,
+	// and Height states the maximum number of lines to render after that.
+	//
+	// Use these together to render a view of a larger tree.
+	//
+	// A height <= 0 indicates no limit.
+	// Scroll markers are rendered for a height > 0.
+	Offset, Height int
 }
 
 // Style configures the visual appearance of the tree.
@@ -61,6 +84,14 @@ type Style[T any] struct {
 	//
 	// By default, all nodes are marked with [DefaultNodeMarker].
 	NodeMarker func(T) ui.Style
+
+	// ScrollUpMarker is shown above the viewport
+	// when content exists above it.
+	ScrollUpMarker ui.Style
+
+	// ScrollDownMarker is shown below the viewport
+	// when content exists below it.
+	ScrollDownMarker ui.Style
 }
 
 // DefaultStyle returns the default style for rendering trees.
@@ -70,6 +101,8 @@ func DefaultStyle[T any]() *Style[T] {
 		NodeMarker: func(T) ui.Style {
 			return DefaultNodeMarker
 		},
+		ScrollUpMarker:   DefaultScrollUpMarker,
+		ScrollDownMarker: DefaultScrollDownMarker,
 	}
 }
 
@@ -80,15 +113,23 @@ func Write[T any](w io.Writer, g Graph[T], opts Options[T]) error {
 	}
 
 	tw := treeWriter[T]{
-		w:     bufio.NewWriter(w),
-		g:     g,
-		style: newTreeStyle(opts.Style, opts.Theme),
+		w:      bufio.NewWriter(w),
+		g:      g,
+		style:  newTreeStyle(opts.Style, opts.Theme),
+		offset: max(0, opts.Offset),
+		height: opts.Height,
 	}
 	for _, root := range g.Roots {
 		if err := tw.writeTree(root, nil, nil); err != nil {
 			return err
 		}
 	}
+
+	if tw.truncatedBelow {
+		if _, err := fmt.Fprintln(tw.w, tw.style.ScrollDownMarker.String()); err != nil {
+			return err
+		}
+	}
 	return tw.w.Flush()
 }
 
@@ -97,12 +138,38 @@ type treeWriter[T any] struct {
 	g Graph[T]
 
 	lineNum int
-	style   treeStyle[T]
+
+	// Number of rendered tree lines to skip before starting the viewport.
+	offset int
+	// Maximum number of tree content lines to write.
+	// Zero or negative means no viewport limit.
+	height int
+
+	// Number of tree content lines written to the viewport,
+	// excluding scroll markers.
+	wroteLines int
+
+	// Whether the top scroll marker has already been emitted.
+	// This is shown once when offset > 0 and the first viewport line is written.
+	wroteScrollUp bool
+
+	// Whether tree content was cut off at the bottom.
+	// This is true if height > 0,
+	// and the number of lines to write exceeds the height limit.
+	//
+	// This informs the caller whether a bottom scroll marker
+	// should be emitted after the tree is fully rendered.
+	truncatedBelow bool
+	// TODO: maybe we can fold this into the render loop
+
+	style treeStyle[T]
 }
 
 type treeStyle[T any] struct {
-	Joint      lipgloss.Style
-	NodeMarker func(T) lipgloss.Style
+	Joint            lipgloss.Style
+	NodeMarker       func(T) lipgloss.Style
+	ScrollUpMarker   lipgloss.Style
+	ScrollDownMarker lipgloss.Style
 }
 
 func newTreeStyle[T any](s *Style[T], theme ui.Theme) treeStyle[T] {
@@ -111,6 +178,8 @@ func newTreeStyle[T any](s *Style[T], theme ui.Theme) treeStyle[T] {
 		NodeMarker: func(v T) lipgloss.Style {
 			return s.NodeMarker(v).Resolve(theme)
 		},
+		ScrollUpMarker:   s.ScrollUpMarker.Resolve(theme),
+		ScrollDownMarker: s.ScrollDownMarker.Resolve(theme),
 	}
 }
 
@@ -225,25 +294,58 @@ func (tw *treeWriter[T]) writeTree(nodeIdx int, path []int, pathNodeIxes []int)
 		lastJoint = string(_verticalRight) + string(_horizontal)
 	}
 
-	lines := strings.Split(tw.g.View(nodeValue), "\n")
-	for idx, line := range lines {
+	var lineBuffer bytes.Buffer
+	firstLine := true
+	for line := range strings.SplitSeq(tw.g.View(nodeValue), "\n") {
+		lineBuffer.Reset()
+
 		// The text may be multi-line.
 		// Only the first line has a title marker.
-		if idx == 0 {
-			tw.pipes(path, lastJoint, titlePrefix)
+		if firstLine {
+			firstLine = false
+			tw.pipes(&lineBuffer, path, lastJoint, titlePrefix)
 		} else {
-			tw.pipes(path, string(_vertical)+" ", bodyPrefix)
+			tw.pipes(&lineBuffer, path, string(_vertical)+" ", bodyPrefix)
 		}
 
-		_, _ = tw.w.WriteString(line)
-		_, _ = tw.w.WriteString("\n")
-		tw.lineNum++
+		lineBuffer.WriteString(line)
+		tw.writeLine(lineBuffer.Bytes())
 	}
 
 	return nil
 }
 
-func (tw *treeWriter[T]) pipes(path []int, joint string, marker string) {
+// writeLine writes a line of the tree to the output,
+// respecting the scroll offset and height limits.
+//
+// This performs necessary bookkeeping internally.
+func (tw *treeWriter[T]) writeLine(line []byte) {
+	lineNum := tw.lineNum
+	tw.lineNum++
+
+	if lineNum < tw.offset {
+		return
+	}
+
+	if tw.height > 0 && tw.wroteLines >= tw.height {
+		tw.truncatedBelow = true
+		return
+	}
+
+	// If content above the viewport is getting cut off,
+	// we need to add a scroll marker.
+	if !tw.wroteScrollUp && tw.offset > 0 {
+		_, _ = fmt.Fprintln(tw.w, tw.style.ScrollUpMarker.String())
+		tw.wroteScrollUp = true
+	}
+
+	_, _ = tw.w.Write(line)
+	_ = tw.w.WriteByte('\n')
+
+	tw.wroteLines++
+}
+
+func (tw *treeWriter[T]) pipes(buf *bytes.Buffer, path []int, joint string, marker string) {
 	if len(path) == 0 {
 		return
 	}
@@ -254,15 +356,16 @@ func (tw *treeWriter[T]) pipes(path []int, joint string, marker string) {
 	// needs just connecting pipes.
 	for _, pos := range path[:len(path)-1] {
 		if pos > 0 {
-			_, _ = tw.w.WriteString(
+			buf.WriteString(
 				style.Render(string(_vertical) + " "),
 			)
 		} else {
-			_, _ = tw.w.WriteString("  ")
+			buf.WriteString("  ")
 		}
 	}
 
-	_, _ = tw.w.WriteString(style.Render(joint) + marker)
+	buf.WriteString(style.Render(joint))
+	buf.WriteString(marker)
 }
 
 // CycleError is returned when a cycle is detected in the tree.