Make the model selection screen work well on smaller-height terminals

Author: jahooma

cli/src/components/freebuff-model-selector.tsx

@@ -1,6 +1,12 @@
 import { TextAttributes } from '@opentui/core'
 import { useKeyboard } from '@opentui/react'
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 
 import { Button } from './button'
 import {
@@ -24,7 +30,7 @@ import {
 } from '../utils/freebuff-model-navigation'
 
 import type { FreebuffModelOption } from '@codebuff/common/constants/freebuff-models'
-import type { KeyEvent } from '@opentui/core'
+import type { KeyEvent, ScrollBoxRenderable } from '@opentui/core'
 
 // Section grouping: premium models share one quota pool, unlimited has none.
 // Putting the tier on a section header lets each row drop its redundant
@@ -58,8 +64,22 @@ type Section = {
  * PREMIUM section header. Names align in a column so taglines line up across
  * rows. On narrow terminals the secondary details (warning / deployment
  * hours) drop onto an indented second line under the row.
+ *
+ * On short terminals the parent passes `maxHeight`: the row list then lives
+ * in a scrollbox capped at that many rows, a scrollbar appears when the
+ * models don't all fit, and Tab/arrow navigation keeps the focused row
+ * scrolled into view.
  */
-export const FreebuffModelSelector: React.FC = () => {
+interface FreebuffModelSelectorProps {
+  /** Max vertical rows the picker may occupy. When the rendered rows exceed
+   *  this, the list scrolls (scrollbar shown, focused row kept in view);
+   *  otherwise the scrollbox shrinks to fit and no scrollbar appears. */
+  maxHeight: number
+}
+
+export const FreebuffModelSelector: React.FC<FreebuffModelSelectorProps> = ({
+  maxHeight,
+}) => {
   const theme = useTheme()
   // contentMaxWidth (not terminalWidth) is the real budget — the parent
   // waiting-room screen wraps this picker in a `maxWidth: contentMaxWidth`
@@ -217,6 +237,50 @@ export const FreebuffModelSelector: React.FC = () => {
     }
   }, [availableModels, contentMaxWidth, deploymentAvailabilityLabel, showTagline])
 
+  // Flattened vertical layout: every model's top offset + height within the
+  // scroll content, plus the total. Mirrors the JSX below exactly so the
+  // auto-scroll math lands the focused row precisely. A button is 2 border
+  // rows + its text line(s); in wrapDetails mode a row with a warning or
+  // deployment-hours label spills its details onto a second indented line.
+  // Headers add 1 row; sections after the first add 1 row of marginTop.
+  const SECTION_GAP = 1
+  const { totalHeight, offsetById } = useMemo(() => {
+    const offsets: Record<string, { top: number; height: number }> = {}
+    let y = 0
+    sections.forEach((section, idx) => {
+      if (idx > 0) y += SECTION_GAP
+      if (section.label) y += 1
+      section.models.forEach((m) => {
+        const wraps =
+          wrapDetails && (!!m.warning || m.availability === 'deployment_hours')
+        const h = 2 /* borders */ + (wraps ? 2 : 1)
+        offsets[m.id] = { top: y, height: h }
+        y += h
+      })
+    })
+    return { totalHeight: y, offsetById: offsets }
+  }, [sections, wrapDetails])
+
+  const needsScroll = totalHeight > maxHeight
+  const scrollViewportHeight = Math.max(1, Math.min(totalHeight, maxHeight))
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null)
+
+  // Keep the keyboard-focused row inside the viewport as the user Tabs/arrows
+  // through a list taller than the available rows.
+  useEffect(() => {
+    const sb = scrollRef.current
+    if (!sb || !needsScroll) return
+    const entry = offsetById[focusedId]
+    if (!entry) return
+    const viewportHeight = sb.viewport.height
+    const currentScroll = sb.scrollTop
+    if (entry.top < currentScroll) {
+      sb.scrollTop = entry.top
+    } else if (entry.top + entry.height > currentScroll + viewportHeight) {
+      sb.scrollTop = entry.top + entry.height - viewportHeight
+    }
+  }, [focusedId, offsetById, needsScroll])
+
   const isJoinable = useCallback(
     (modelId: string) => {
       if (!isFreebuffModelAvailable(modelId, new Date(now))) return false
@@ -376,30 +440,61 @@ export const FreebuffModelSelector: React.FC = () => {
     )
   }
 
-  return (
+  const sectionsContent = sections.map((section, sectionIdx) => (
     <box
+      key={section.key}
       style={{
         flexDirection: 'column',
         alignItems: 'flex-start',
         gap: 0,
+        marginTop: sectionIdx === 0 ? 0 : SECTION_GAP,
       }}
     >
-      {sections.map((section, sectionIdx) => (
-        <box
-          key={section.key}
-          style={{
-            flexDirection: 'column',
-            alignItems: 'flex-start',
-            gap: 0,
-            marginTop: sectionIdx === 0 ? 0 : 1,
-          }}
-        >
-          {section.label && (
-            <text style={{ fg: theme.muted }}>{section.label}</text>
-          )}
-          {section.models.map(renderModelButton)}
-        </box>
-      ))}
+      {section.label && (
+        <text style={{ fg: theme.muted }}>{section.label}</text>
+      )}
+      {section.models.map(renderModelButton)}
     </box>
+  ))
+
+  // Scrollbox clamped to the rows the parent can spare. When everything fits
+  // it shrinks to the content height and no scrollbar shows, so tall
+  // terminals look exactly like a plain column.
+  return (
+    <scrollbox
+      ref={scrollRef}
+      scrollX={false}
+      scrollbarOptions={{ visible: false }}
+      verticalScrollbarOptions={{
+        visible: needsScroll,
+        trackOptions: { width: 1 },
+      }}
+      style={{
+        height: scrollViewportHeight,
+        // A scrollbox stretches to fill its parent, which would left-align
+        // the picker; pin it to the button column width (plus a gutter for
+        // the scrollbar) so the landing block stays content-sized and the
+        // parent can center it as it did before this was a scrollbox.
+        width: buttonOuterWidth + (needsScroll ? 1 : 0),
+        flexShrink: 0,
+        rootOptions: {
+          flexDirection: 'row',
+          backgroundColor: 'transparent',
+        },
+        wrapperOptions: {
+          border: false,
+          backgroundColor: 'transparent',
+          flexDirection: 'column',
+        },
+        contentOptions: {
+          flexDirection: 'column',
+          alignItems: 'flex-start',
+          gap: 0,
+          backgroundColor: 'transparent',
+        },
+      }}
+    >
+      {sectionsContent}
+    </scrollbox>
   )
 }

cli/src/components/limited-landing-panel.tsx

@@ -1,25 +1,33 @@
 import { TextAttributes } from '@opentui/core'
 import { useKeyboard } from '@opentui/react'
-import React, { useCallback, useState } from 'react'
+import React, { useCallback, useRef, useState } from 'react'
 
 import { Button } from './button'
 import { joinFreebuffQueue } from '../hooks/use-freebuff-session'
+import { useTerminalDimensions } from '../hooks/use-terminal-dimensions'
 import { useTheme } from '../hooks/use-theme'
 import {
   getFreebuffModel,
   LIMITED_FREEBUFF_MODEL_ID,
 } from '@codebuff/common/constants/freebuff-models'
 
-import type { KeyEvent } from '@opentui/core'
+import type { KeyEvent, ScrollBoxRenderable } from '@opentui/core'
 
 interface LimitedLandingPanelProps {
   /** Pre-composed session-counter line (e.g. "0 of 5 sessions used · resets
    *  in 8h 21m"). Parent owns the colors so the "used" count can flip to
    *  the warning color when exhausted without this component re-deriving the
    *  quota math. */
   sessionCounter: React.ReactNode
+  /** Plain-text form of the same counter, used only to measure how many rows
+   *  it wraps to so the scroll budget is exact. */
+  sessionCounterText: string
   /** True when the shared per-day quota is fully spent. Disables the CTA. */
   isQuotaExhausted: boolean
+  /** Max vertical rows the panel may occupy. When its content is taller the
+   *  panel scrolls (scrollbar shown) instead of letting flexbox compress the
+   *  bordered button onto its own border. */
+  maxHeight: number
 }
 
 /**
@@ -32,11 +40,48 @@ interface LimitedLandingPanelProps {
  */
 export const LimitedLandingPanel: React.FC<LimitedLandingPanelProps> = ({
   sessionCounter,
+  sessionCounterText,
   isQuotaExhausted,
+  maxHeight,
 }) => {
   const theme = useTheme()
+  const { contentMaxWidth } = useTerminalDimensions()
   const model = getFreebuffModel(LIMITED_FREEBUFF_MODEL_ID)
   const [pending, setPending] = useState(false)
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null)
+
+  // Rendered height of the panel, matching the JSX below row-for-row so the
+  // scroll budget is exact: name + warning (each wrap-aware) + the counter
+  // line with its 1-row top/bottom margins + the 3-row bordered button.
+  const wrappedRows = (text: string) =>
+    Math.max(1, Math.ceil(text.length / contentMaxWidth))
+  const contentHeight =
+    wrappedRows(model.displayName) +
+    (model.warning ? wrappedRows(model.warning) : 0) +
+    1 /* counter marginTop */ +
+    wrappedRows(sessionCounterText) +
+    1 /* counter marginBottom */ +
+    3 /* button: 2 border rows + label */
+  const needsScroll = contentHeight > maxHeight
+  const viewportHeight = Math.max(1, Math.min(contentHeight, maxHeight))
+
+  // A scrollbox stretches to fill its parent, which would left-align the
+  // panel; the old plain box sized to its content and the parent centered
+  // it. Restore that by pinning the scrollbox to its content width (widest
+  // of name / warning / counter / the bordered button) so `alignItems:
+  // 'center'` on the parent can center the whole block again.
+  const BUTTON_LABEL = 'Start session   Enter'
+  const BUTTON_CHROME = 6 // 2 border + 4 padding (paddingLeft/Right 2)
+  const panelWidth =
+    Math.min(
+      contentMaxWidth,
+      Math.max(
+        model.displayName.length,
+        model.warning?.length ?? 0,
+        sessionCounterText.length,
+        BUTTON_LABEL.length + BUTTON_CHROME,
+      ),
+    ) + (needsScroll ? 1 : 0) /* scrollbar gutter */
 
   const interactable = !pending && !isQuotaExhausted
 
@@ -64,24 +109,54 @@ export const LimitedLandingPanel: React.FC<LimitedLandingPanelProps> = ({
   )
 
   return (
-    <box
+    <scrollbox
+      ref={scrollRef}
+      scrollX={false}
+      scrollbarOptions={{ visible: false }}
+      verticalScrollbarOptions={{
+        visible: needsScroll,
+        trackOptions: { width: 1 },
+      }}
       style={{
-        flexDirection: 'column',
-        alignItems: 'flex-start',
-        gap: 0,
+        height: viewportHeight,
+        width: panelWidth,
+        alignSelf: 'center',
+        flexShrink: 0,
+        rootOptions: {
+          flexDirection: 'row',
+          backgroundColor: 'transparent',
+        },
+        wrapperOptions: {
+          border: false,
+          backgroundColor: 'transparent',
+          flexDirection: 'column',
+        },
+        contentOptions: {
+          flexDirection: 'column',
+          alignItems: 'flex-start',
+          gap: 0,
+          backgroundColor: 'transparent',
+        },
       }}
     >
-      <text style={{ wrapMode: 'word' }}>
+      <text style={{ wrapMode: 'word', flexShrink: 0 }}>
         <span fg={theme.foreground} attributes={TextAttributes.BOLD}>
           {model.displayName}
         </span>
       </text>
       {model.warning && (
-        <text style={{ fg: theme.muted, wrapMode: 'word' }}>
+        <text style={{ fg: theme.muted, wrapMode: 'word', flexShrink: 0 }}>
           {model.warning}
         </text>
       )}
-      <text style={{ marginTop: 1, marginBottom: 1, wrapMode: 'word' }}>
+      <text
+        style={{
+          marginTop: 1,
+          marginBottom: 1,
+          wrapMode: 'word',
+          flexShrink: 0,
+        }}
+      >
         {sessionCounter}
       </text>
       <Button
@@ -91,6 +166,7 @@ export const LimitedLandingPanel: React.FC<LimitedLandingPanelProps> = ({
           borderColor: interactable ? theme.primary : theme.border,
           paddingLeft: 2,
           paddingRight: 2,
+          flexShrink: 0,
         }}
         border={['top', 'bottom', 'left', 'right']}
       >
@@ -107,6 +183,6 @@ export const LimitedLandingPanel: React.FC<LimitedLandingPanelProps> = ({
           )}
         </text>
       </Button>
-    </box>
+    </scrollbox>
   )
 }