@pellux/goodvibes-tui 0.26.0 → 0.28.0

package/src/panels/docs-panel.ts

@@ -4,7 +4,7 @@
 
 import type { Line } from '../types/grid.ts';
 import { BasePanel } from './base-panel.ts';
-import { buildPanelLine, buildPanelWorkspace, buildSearchInputLine, resolveScrollablePanelSection, DEFAULT_PANEL_PALETTE } from './polish.ts';
+import { buildKeyboardHints, buildPanelLine, buildPanelWorkspace, buildSearchInputLine, resolveScrollablePanelSection, extendPalette, DEFAULT_PANEL_PALETTE } from './polish.ts';
 import type { ProviderModelCatalogQuery, ToolCatalogQuery } from '../runtime/ui-service-queries.ts';
 import {
   getPanelSearchFocusTransition,
@@ -14,22 +14,12 @@ import {
   isPanelSearchPrintable,
 } from './search-focus.ts';
 
-const C = {
-  headerBg:   '#1a1a2e',
-  headerFg:   '#ffffff',
-  statusBar:  '#222233',
-  statusFg:   '#aaaaaa',
-  sectionFg:  '#00ffff',
-  sectionBg:  '#0d1a2a',
-  toolFg:     '#88ccff',
-  descFg:     '#aaaaaa',
-  keyFg:      '#ffcc44',
-  valueFg:    '#ccccdd',
-  dimFg:      '#555566',
-  selected:   '#00ffff',
-  selectedBg: '#1a2a3a',
-  searchFg:   '#ffffff',
-} as const;
+const C = extendPalette(DEFAULT_PANEL_PALETTE, {
+  // Panel-specific domain colors with no clean shared equivalent.
+  sectionFg: '#00ffff',
+  toolFg:    '#88ccff',
+  selected:  '#00ffff',
+});
 
 // ---------------------------------------------------------------------------
 // Hardcoded keyboard shortcut reference
@@ -68,7 +58,7 @@ interface FlatRow {
 }
 
 function renderRow(width: number, row: FlatRow, isCursor: boolean): Line {
-  const bg = isCursor ? C.selectedBg : row.bg;
+  const bg = isCursor ? C.selectBg : row.bg;
   return buildPanelLine(width, [
     [isCursor ? '▸' : ' ', C.selected, bg],
     [row.text, isCursor ? C.selected : row.fg, bg],
@@ -162,9 +152,24 @@ export class DocsPanel extends BasePanel {
         buildSearchInputLine(width, '', searchLine.trimStart(), DEFAULT_PANEL_PALETTE, { active: this.searching }),
       ],
     } as const;
+    // Context-aware footer: while searching, surface only the keys that work in
+    // the search field; otherwise surface section + navigation keys.
+    const footerLines = [this.searching
+      ? buildKeyboardHints(width, [
+          { keys: 'type', label: 'filter' },
+          { keys: 'Enter/Esc', label: 'apply / exit search' },
+          { keys: '↓', label: 'back to list' },
+        ], DEFAULT_PANEL_PALETTE)
+      : buildKeyboardHints(width, [
+          { keys: 't/m/k', label: 'tools / models / shortcuts' },
+          { keys: '↑/↓', label: 'navigate' },
+          { keys: '/', label: 'search' },
+        ], DEFAULT_PANEL_PALETTE)];
+
     const sectionWindow = resolveScrollablePanelSection(width, height, {
       intro: 'Browse built-in tool docs, available models, and keyboard shortcuts from one shared reference surface.',
       palette: DEFAULT_PANEL_PALETTE,
+      footerLines,
       beforeSections: [controlsSection],
       section: {
         title: sectionLabel,
@@ -186,6 +191,7 @@ export class DocsPanel extends BasePanel {
         controlsSection,
         sectionWindow.section.lines.length > 0 ? sectionWindow.section : { title: sectionLabel, lines: [buildPanelLine(width, [[' No matching docs', DEFAULT_PANEL_PALETTE.dim]])] },
       ],
+      footerLines,
       palette: DEFAULT_PANEL_PALETTE,
     });
   }
@@ -217,13 +223,13 @@ export class DocsPanel extends BasePanel {
       const tools = this.toolRegistry?.list() ?? [];
       const filtered = q ? tools.filter(t => t.definition.name.toLowerCase().includes(q) || (t.definition.description ?? '').toLowerCase().includes(q)) : tools;
       if (filtered.length === 0) {
-        rows.push({ kind: 'empty', text: ' No tools match.', fg: C.dimFg, bg: '' });
+        rows.push({ kind: 'empty', text: q ? ` No tools match "${this.searchQuery}". Press Esc to clear the filter.` : ' Tool registry not wired into this session.', fg: C.dim, bg: '' });
       } else {
         rows.push({ kind: 'header', text: ` Tools (${filtered.length})`, fg: C.sectionFg, bg: C.sectionBg, bold: true });
         for (const tool of filtered) {
           rows.push({ kind: 'item', text: `  ${tool.definition.name}`, fg: C.toolFg, bg: '', bold: true });
           if (tool.definition.description) {
-            rows.push({ kind: 'detail', text: `    ${tool.definition.description}`, fg: C.descFg, bg: '' });
+            rows.push({ kind: 'detail', text: `    ${tool.definition.description}`, fg: C.label, bg: '' });
           }
           const metadata: string[] = [];
           if (tool.definition.sideEffects && tool.definition.sideEffects.length > 0) {
@@ -239,7 +245,7 @@ export class DocsPanel extends BasePanel {
             metadata.push('streaming');
           }
           if (metadata.length > 0) {
-            rows.push({ kind: 'detail', text: `    ${metadata.join('  |  ')}`, fg: C.dimFg, bg: '' });
+            rows.push({ kind: 'detail', text: `    ${metadata.join('  |  ')}`, fg: C.dim, bg: '' });
           }
         }
       }
@@ -247,7 +253,7 @@ export class DocsPanel extends BasePanel {
       const models = this.providerRegistry?.listModels() ?? [];
       const filtered = q ? models.filter(m => m.id.toLowerCase().includes(q) || m.displayName.toLowerCase().includes(q) || m.provider.toLowerCase().includes(q)) : models;
       if (filtered.length === 0) {
-        rows.push({ kind: 'empty', text: ' No models match.', fg: C.dimFg, bg: '' });
+        rows.push({ kind: 'empty', text: q ? ` No models match "${this.searchQuery}". Press Esc to clear the filter.` : ' Provider registry not wired into this session.', fg: C.dim, bg: '' });
       } else {
         // Group by provider
         const byProvider = new Map<string, typeof filtered>();
@@ -262,7 +268,7 @@ export class DocsPanel extends BasePanel {
             const ctxK = m.contextWindow > 0 ? `${(m.contextWindow / 1000).toFixed(0)}k` : '?';
             const caps = [m.contextWindow > 0 ? `ctx:${ctxK}` : ''].filter(Boolean).join(' ');
             rows.push({ kind: 'item', text: `  ${m.displayName}  ${caps}`, fg: C.toolFg, bg: '' });
-            rows.push({ kind: 'detail', text: `    ${m.id}`, fg: C.descFg, bg: '' });
+            rows.push({ kind: 'detail', text: `    ${m.id}`, fg: C.label, bg: '' });
           }
         }
       }
@@ -272,7 +278,7 @@ export class DocsPanel extends BasePanel {
       rows.push({ kind: 'header', text: ' Keyboard Shortcuts', fg: C.sectionFg, bg: C.sectionBg, bold: true });
       for (const s of filtered) {
         const key = s.key.padEnd(16);
-        rows.push({ kind: 'item', text: `  ${key} ${s.desc}`, fg: C.valueFg, bg: '' });
+        rows.push({ kind: 'item', text: `  ${key} ${s.desc}`, fg: C.value, bg: '' });
       }
     }
 

package/src/panels/eval-panel.ts

@@ -6,15 +6,21 @@
  */
 
 import { BasePanel } from './base-panel.ts';
+import { truncateDisplay } from '../utils/terminal-width.ts';
 import type { Line } from '../types/grid.ts';
 import type { KeyName } from './types.ts';
 import { createEmptyLine } from '../types/grid.ts';
 import {
+  buildAlignedRow,
   buildEmptyState,
+  buildKeyboardHints,
+  buildMeterLine,
   buildPanelLine,
   buildPanelWorkspace,
+  buildTable,
   resolveScrollablePanelSection,
   DEFAULT_PANEL_PALETTE,
+  extendPalette,
 } from './polish.ts';
 
 // ── EvalRegistry ─────────────────────────────────────────────────────────────
@@ -25,6 +31,7 @@ import type {
   EvalGateResult,
   EvalDimension,
 } from '@/runtime/index.ts';
+import { formatShortDuration } from '../utils/format-duration.ts';
 
 /**
  * Holds the latest eval run state for display in EvalPanel.
@@ -78,24 +85,19 @@ export class EvalRegistry {
   }
 }
 
-// ── Colour palette (hex fg colours for createStyledCell) ─────────────────────
+// ── Colour palette (no inline hex in render bodies) ──────────────────────────
 
-const C = {
-  ...DEFAULT_PANEL_PALETTE,
+const C = extendPalette(DEFAULT_PANEL_PALETTE, {
   header:   '#94a3b8',
   headerBg: '#1e293b',
   cyan:     '#38bdf8',
   green:    '#22c55e',
   yellow:   '#eab308',
   red:      '#ef4444',
-  dim:      '#4b5563',
-  label:    '#64748b',
-  value:    '#e2e8f0',
-  selected: '#f1f5f9',
-  sep:      '#1e293b',
   white:    '#cbd5e1',
+  selected: '#f1f5f9',
   selectBg: '#0f172a',
-} as const;
+});
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -106,8 +108,7 @@ function scoreColor(score: number): string {
 }
 
 function fmtTime(ms: number): string {
-  if (ms < 1000) return `${ms.toFixed(0)}ms`;
-  return `${(ms / 1000).toFixed(1)}s`;
+  return formatShortDuration(ms);
 }
 
 const DIMENSION_ORDER: EvalDimension[] = ['safety', 'quality', 'latency', 'cost', 'recovery'];
@@ -207,15 +208,6 @@ export class EvalPanel extends BasePanel {
     const gates = this._registry.getGateResults();
     const intro = 'Evaluation harness runs, gates, scenario scorecards, and regression indicators for model and product validation.';
 
-    const running = this._registry.isRunning();
-    const lastRun = this._registry.getLastRunAt();
-    const summaryLine = buildPanelLine(width, [
-      ['  state: ', C.label],
-      [running ? 'running' : 'idle', running ? C.yellow : C.dim],
-      ['  last: ', C.label],
-      [lastRun ? new Date(lastRun).toLocaleTimeString() : 'n/a', C.dim],
-    ]);
-
     if (suites.length === 0) {
       const workspace = buildPanelWorkspace(width, height, {
         title: 'Eval Harness',
@@ -223,7 +215,7 @@ export class EvalPanel extends BasePanel {
         sections: [{
           title: 'Status',
           lines: [
-            summaryLine,
+            this._statusLine(width),
             ...buildEmptyState(
               width,
               ' No results yet.',
@@ -241,17 +233,37 @@ export class EvalPanel extends BasePanel {
 
     const lines: Line[] = [];
     if (this._mode === 'list') {
-      this._renderList(lines, suites, gates, width, height, intro, summaryLine);
+      this._renderList(lines, suites, gates, width, height, intro);
     } else {
       const suite = suites[this._selectedSuiteIdx];
       if (suite) {
-        this._renderDetail(lines, suite, width, height, intro, summaryLine);
+        this._renderDetail(lines, suite, width, height, intro);
       }
     }
 
     return lines;
   }
 
+  // ── Shared summary line ───────────────────────────────────────────────────
+
+  private _statusLine(width: number): Line {
+    const running = this._registry.isRunning();
+    const lastRun = this._registry.getLastRunAt();
+    const suites = this._registry.getSuiteResults();
+    const passed = suites.filter((s) => s.passed).length;
+    const failed = suites.length - passed;
+    return buildPanelLine(width, [
+      ['  state ', C.label],
+      [running ? 'running' : 'idle', running ? C.yellow : C.dim],
+      ['  passed ', C.label],
+      [String(passed), passed > 0 ? C.green : C.dim],
+      ['  failed ', C.label],
+      [String(failed), failed > 0 ? C.red : C.dim],
+      ['  last ', C.label],
+      [lastRun ? new Date(lastRun).toLocaleTimeString() : 'n/a', C.dim],
+    ]);
+  }
+
   // ── List view ────────────────────────────────────────────────────────────────
 
   private _renderList(
@@ -259,49 +271,70 @@ export class EvalPanel extends BasePanel {
     suites: EvalSuiteResult[],
     gates: EvalGateResult[],
     width: number,
-    _height: number,
+    height: number,
     intro: string,
-    summaryLine: Line,
   ): void {
     const gateMap = new Map(gates.map((g) => [g.suite, g]));
-    const sectionLines: Line[] = [
-      summaryLine,
-      buildPanelLine(width, [
-      ['Suite'.padEnd(28), C.header],
-      ['Score'.padEnd(8), C.header],
-      ['Pass'.padEnd(6), C.header],
-      ['Gate'.padEnd(6), C.header],
-      ['Duration', C.header],
-      ]),
-    ];
 
-    suites.forEach((suite, idx) => {
+    const tableRows = suites.map((suite, idx) => {
       const selected = idx === this._selectedSuiteIdx;
       const gate = gateMap.get(suite.suite);
       const gateStr = gate ? (gate.passed ? 'ok' : 'FAIL') : '-';
       const gateColor = gate ? (gate.passed ? C.green : C.red) : C.dim;
       const durationMs = suite.finishedAt - suite.startedAt;
-      const scoreC = scoreColor(suite.meanScore);
-      const passC = suite.passed ? C.green : C.red;
-      const nameColor = selected ? C.selected : C.white;
-      const bg = selected ? C.selectBg : undefined;
-      const prefix = selected ? '▸ ' : '  ';
-      const name = suite.suite.slice(0, 24).padEnd(26);
-
-      sectionLines.push(buildPanelLine(width, [
-        [prefix + name, nameColor, bg],
-        [suite.meanScore.toFixed(1).padEnd(8), scoreC, bg],
-        [(suite.passed ? 'PASS' : 'FAIL').padEnd(6), passC, bg],
-        [gateStr.padEnd(6), gateColor, bg],
-        [fmtTime(durationMs), C.dim, bg],
-      ]));
+      return {
+        selected,
+        cells: [
+          { text: suite.suite, fg: selected ? C.selected : C.white, bold: selected },
+          { text: suite.meanScore.toFixed(1), fg: scoreColor(suite.meanScore) },
+          { text: suite.passed ? 'PASS' : 'FAIL', fg: suite.passed ? C.green : C.red },
+          { text: gateStr, fg: gateColor },
+          { text: fmtTime(durationMs), fg: C.dim },
+        ],
+      };
     });
 
-    sectionLines.push(buildPanelLine(width, [[' Enter/l: detail  j/k: navigate', C.dim]]));
-    lines.push(...buildPanelWorkspace(width, _height, {
+    const tableLines = buildTable(width, [
+      { label: 'Suite' },
+      { label: 'Score', width: 7, align: 'right' },
+      { label: 'Pass', width: 6 },
+      { label: 'Gate', width: 6 },
+      { label: 'Duration', width: 10, align: 'right' },
+    ], tableRows, C, { selectedBg: C.selectBg });
+
+    const selectedSuite = suites[this._selectedSuiteIdx];
+    const detailLines: Line[] = [];
+    if (selectedSuite) {
+      const passCount = selectedSuite.results.filter((r) => r.scorecard.passed).length;
+      detailLines.push(buildPanelLine(width, [
+        [' selected ', C.label],
+        [selectedSuite.suite, C.cyan],
+        ['  scenarios ', C.label],
+        [`${passCount}/${selectedSuite.results.length} passed`, passCount === selectedSuite.results.length ? C.green : C.yellow],
+      ]));
+      const meterW = Math.max(10, Math.min(30, width - 24));
+      detailLines.push(buildMeterLine(width, Math.round((selectedSuite.meanScore / 100) * meterW), meterW, {
+        filled: scoreColor(selectedSuite.meanScore),
+        empty: C.empty,
+        label: C.label,
+      }, { prefix: ' mean ', suffix: ` ${selectedSuite.meanScore.toFixed(1)}/100 ` }));
+    }
+
+    const footer = buildKeyboardHints(width, [
+      { keys: `${this._selectedSuiteIdx + 1}/${suites.length}`, label: 'suite' },
+      { keys: '↑/↓', label: 'navigate' },
+      { keys: 'Enter', label: 'open detail' },
+    ], C);
+
+    lines.push(...buildPanelWorkspace(width, height, {
       title: 'Eval Harness',
       intro,
-      sections: [{ title: 'Suites', lines: sectionLines }],
+      sections: [
+        { lines: [this._statusLine(width)] },
+        { title: 'Suites', lines: tableLines },
+        ...(detailLines.length > 0 ? [{ title: 'Selected Suite', lines: detailLines }] : []),
+      ],
+      footerLines: [footer],
       palette: C,
     }));
   }
@@ -314,16 +347,19 @@ export class EvalPanel extends BasePanel {
     width: number,
     height: number,
     intro: string,
-    summaryLine: Line,
   ): void {
-    const sectionLines: Line[] = [
-      summaryLine,
+    const passCount = suite.results.filter((r) => r.scorecard.passed).length;
+    const headerLines: Line[] = [
+      this._statusLine(width),
       buildPanelLine(width, [
-      [`Suite: ${suite.suite}`, C.cyan],
-      ['  mean=', C.label],
-      [suite.meanScore.toFixed(1), scoreColor(suite.meanScore)],
-      ['  ', C.label],
-      [suite.passed ? 'PASS' : 'FAIL', suite.passed ? C.green : C.red],
+        [' suite ', C.label],
+        [suite.suite, C.cyan],
+        ['  mean ', C.label],
+        [suite.meanScore.toFixed(1), scoreColor(suite.meanScore)],
+        ['  ', C.label],
+        [suite.passed ? 'PASS' : 'FAIL', suite.passed ? C.green : C.red],
+        ['  scenarios ', C.label],
+        [`${passCount}/${suite.results.length} passed`, passCount === suite.results.length ? C.green : C.yellow],
       ]),
     ];
 
@@ -333,23 +369,32 @@ export class EvalPanel extends BasePanel {
       this._renderScenarioBlock(allDetailLines, result, selected, width);
     });
 
+    const footer = buildKeyboardHints(width, [
+      { keys: `${this._selectedScenarioIdx + 1}/${suite.results.length}`, label: 'scenario' },
+      { keys: 'Esc', label: 'back' },
+      { keys: '↑/↓', label: 'navigate' },
+      { keys: 'PgUp/PgDn', label: 'scroll' },
+    ], C);
+
     const detailSection = resolveScrollablePanelSection(width, height, {
       intro,
+      footerLines: [footer],
       palette: C,
-      beforeSections: [{ title: 'Scenario Detail', lines: sectionLines }],
+      beforeSections: [{ title: `Scenario Detail · ${suite.suite}`, lines: headerLines }],
       section: {
         scrollableLines: allDetailLines,
         scrollOffset: this._scrollOffset,
         minRows: 1,
+        appendWindowSummary: { dimColor: C.dim },
       },
     });
     this._scrollOffset = detailSection.scrollOffset;
-    sectionLines.push(...detailSection.section.lines);
-    sectionLines.push(buildPanelLine(width, [[' Esc/q: back  j/k: scenario  PgUp/PgDn: scroll', C.dim]]));
+
     lines.push(...buildPanelWorkspace(width, height, {
       title: 'Eval Harness',
       intro,
-      sections: [{ title: 'Scenario Detail', lines: sectionLines }],
+      sections: [{ title: `Scenario Detail · ${suite.suite}`, lines: [...headerLines, ...detailSection.section.lines] }],
+      footerLines: [footer],
       palette: C,
     }));
   }
@@ -361,37 +406,41 @@ export class EvalPanel extends BasePanel {
     width: number,
   ): void {
     const sc = result.scorecard;
-    const prefix = selected ? '▸ ' : '  ';
-    const nameColor = selected ? C.selected : C.white;
     const scoreC = scoreColor(sc.compositeScore);
     const passC = sc.passed ? C.green : C.red;
-    const nameLen = Math.max(1, width - 22);
 
-    lines.push(buildPanelLine(width, [
-      [prefix + result.scenario.name.slice(0, nameLen).padEnd(nameLen + 2), nameColor, selected ? C.selectBg : undefined],
-      [sc.compositeScore.toFixed(1).padStart(5), scoreC, selected ? C.selectBg : undefined],
-      ['  ', C.label, selected ? C.selectBg : undefined],
-      [sc.passed ? 'PASS' : 'FAIL', passC, selected ? C.selectBg : undefined],
-    ]));
+    lines.push(buildAlignedRow(
+      width,
+      [
+        { text: result.scenario.name, fg: selected ? C.selected : C.white, bold: selected },
+        { text: sc.compositeScore.toFixed(1), fg: scoreC },
+        { text: sc.passed ? 'PASS' : 'FAIL', fg: passC },
+      ],
+      [
+        { width: Math.max(8, width - 16) },
+        { width: 6, align: 'right' },
+        { width: 5 },
+      ],
+      { gap: 1, selected, selectedBg: C.selectBg, marker: '▸' },
+    ));
 
     if (selected) {
       for (const dim of DIMENSION_ORDER) {
         const d = sc.dimensions.find((x) => x.dimension === dim);
         if (!d) continue;
         const filled = Math.round(d.score / 10);
-        const bar = '#'.repeat(filled) + '.'.repeat(10 - filled);
-        lines.push(buildPanelLine(width, [
-          ['    ' + dim.padEnd(10) + ' ', C.label],
-          [bar, scoreColor(d.score)],
-          [` ${d.score.toFixed(0).padStart(3)}/100`, C.value],
-        ]));
+        lines.push(buildMeterLine(width, filled, 10, {
+          filled: scoreColor(d.score),
+          empty: C.empty,
+          label: C.label,
+        }, { prefix: `    ${dim.padEnd(9)} `, suffix: ` ${d.score.toFixed(0).padStart(3)}/100 ` }));
       }
 
       if (sc.notes && sc.notes.length > 0) {
         for (const note of sc.notes) {
           lines.push(buildPanelLine(width, [
             ['    ! ', C.yellow],
-            [note.slice(0, width - 6), C.yellow],
+            [truncateDisplay(note, Math.max(8, width - 6)), C.yellow],
           ]));
         }
       }

package/src/panels/expandable-list-panel.ts

@@ -0,0 +1,189 @@
+import type { Line } from '../types/grid.ts';
+import { createEmptyLine } from '../types/grid.ts';
+import { ScrollableListPanel } from './scrollable-list-panel.ts';
+import {
+  buildKeyboardHints,
+  buildPanelWorkspace,
+  resolveScrollablePanelSection,
+} from './polish.ts';
+
+// ---------------------------------------------------------------------------
+// ExpandableListPanel<T>
+// ---------------------------------------------------------------------------
+
+/**
+ * A list panel with a built-in master → detail drill-down.
+ *
+ * Encapsulates the collapse/expand + detail-view pattern that was previously
+ * hand-rolled in git, tool-inspector, agent-inspector, approval, and wrfc
+ * panels: a scrollable list where pressing Enter/→ on a row opens a scrollable
+ * detail view for that item, and Esc/← returns to the list.
+ *
+ * Subclasses implement (in addition to the `ScrollableListPanel` contract):
+ *   - `getDetailLines(item, width)` — the detail body for the expanded item.
+ *
+ * Optionally override:
+ *   - `getDetailTitle(item)` — detail-view title (defaults to `this.name`).
+ *   - `getListHints()` / `getDetailHints()` — footer keyboard hints per mode.
+ *   - `renderListView(width, height)` — the list-mode body (defaults to
+ *     `renderList` with the list hints footer).
+ *
+ * Do NOT override `render()`; it dispatches between list and detail modes.
+ */
+export abstract class ExpandableListPanel<T> extends ScrollableListPanel<T> {
+  /** The item currently expanded into the detail view, or null in list mode. */
+  protected expandedItem: T | null = null;
+  /** First visible row of the detail view. */
+  protected detailScroll = 0;
+
+  /** Render the detail body lines for an expanded item. */
+  protected abstract getDetailLines(item: T, width: number): readonly Line[];
+
+  /** Title shown above the detail view. */
+  protected getDetailTitle(_item: T): string {
+    return this.name;
+  }
+
+  /** Keyboard hints shown in list mode. */
+  protected getListHints(): ReadonlyArray<{ keys: string; label: string }> {
+    return [
+      { keys: '↑/↓', label: 'move' },
+      { keys: 'Enter', label: 'open' },
+    ];
+  }
+
+  /** Keyboard hints shown in detail mode. */
+  protected getDetailHints(): ReadonlyArray<{ keys: string; label: string }> {
+    return [
+      { keys: '↑/↓', label: 'scroll' },
+      { keys: 'Esc', label: 'back' },
+    ];
+  }
+
+  protected isExpanded(): boolean {
+    return this.expandedItem !== null;
+  }
+
+  /** Expand the currently selected item into the detail view. */
+  protected expandSelected(): void {
+    const items = this.getItems();
+    const item = items[this.selectedIndex];
+    if (item === undefined) return;
+    this.expandedItem = item;
+    this.detailScroll = 0;
+    this.needsRender = true;
+  }
+
+  /** Collapse the detail view back to the list. */
+  protected collapse(): void {
+    if (this.expandedItem === null) return;
+    this.expandedItem = null;
+    this.detailScroll = 0;
+    this.needsRender = true;
+  }
+
+  // -------------------------------------------------------------------------
+  // Input
+  // -------------------------------------------------------------------------
+
+  handleInput(key: string): boolean {
+    if (this.expandedItem !== null) {
+      // Detail mode: scroll the detail body; Esc/← collapses.
+      if (this.lastError !== null) this.clearError();
+      switch (key) {
+        case 'escape':
+        case 'left':
+        case 'h':
+          this.collapse();
+          return true;
+        case 'up':
+        case 'k':
+          this.detailScroll = Math.max(0, this.detailScroll - 1);
+          this.needsRender = true;
+          return true;
+        case 'down':
+        case 'j':
+          this.detailScroll += 1;
+          this.needsRender = true;
+          return true;
+        case 'pageup':
+          this.detailScroll = Math.max(0, this.detailScroll - this.getPageSize());
+          this.needsRender = true;
+          return true;
+        case 'pagedown':
+          this.detailScroll += this.getPageSize();
+          this.needsRender = true;
+          return true;
+        case 'home':
+        case 'g':
+          this.detailScroll = 0;
+          this.needsRender = true;
+          return true;
+        default:
+          return false;
+      }
+    }
+
+    // List mode: Enter/→ expands; everything else is list navigation.
+    if (key === 'enter' || key === 'return' || key === 'right' || key === 'l') {
+      if (this.getItems().length === 0) return false;
+      this.expandSelected();
+      return true;
+    }
+    return super.handleInput(key);
+  }
+
+  handleScroll(deltaRows: number): boolean {
+    if (this.expandedItem !== null) {
+      const rows = Math.trunc(deltaRows);
+      if (rows === 0) return false;
+      this.detailScroll = Math.max(0, this.detailScroll + rows);
+      this.needsRender = true;
+      return true;
+    }
+    return super.handleScroll(deltaRows);
+  }
+
+  // -------------------------------------------------------------------------
+  // Render
+  // -------------------------------------------------------------------------
+
+  render(width: number, height: number): Line[] {
+    if (this.expandedItem !== null) {
+      return this.renderDetailView(width, height, this.expandedItem);
+    }
+    return this.renderListView(width, height);
+  }
+
+  /** List-mode body. Override for a custom header; defaults to renderList. */
+  protected renderListView(width: number, height: number): Line[] {
+    return this.renderList(width, height, { hints: this.getListHints() });
+  }
+
+  /** Detail-mode body — scrollable detail lines + standardized chrome. */
+  protected renderDetailView(width: number, height: number, item: T): Line[] {
+    this.needsRender = false;
+    const palette = this.getPalette();
+    const detailLines = [...this.getDetailLines(item, width)];
+    const footer = buildKeyboardHints(width, this.getDetailHints(), palette);
+
+    const resolved = resolveScrollablePanelSection(width, height, {
+      palette,
+      afterSections: [{ lines: [footer] }],
+      section: {
+        scrollableLines: detailLines,
+        scrollOffset: this.detailScroll,
+        appendWindowSummary: detailLines.length > 5 ? { dimColor: palette.dim } : undefined,
+      },
+    });
+    this.detailScroll = resolved.scrollOffset;
+
+    const lines = buildPanelWorkspace(width, height, {
+      title: this.getDetailTitle(item),
+      sections: [resolved.section, { lines: [footer] }],
+      palette,
+    });
+    while (lines.length < height) lines.push(createEmptyLine(width));
+    return lines.slice(0, height);
+  }
+}