@pellux/goodvibes-agent 0.1.0

package/src/renderer/overlay-box.ts

@@ -0,0 +1,146 @@
+import { createStyledCell, type Line } from '../types/grid.ts';
+import { getOverlayMaxWidth } from './overlay-viewport.ts';
+import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+import { fillWidth, makeLine, writeText } from './fullscreen-primitives.ts';
+
+export interface OverlayBoxPalette {
+  readonly borderFg: string;
+  readonly titleFg: string;
+  readonly bodyFg: string;
+  readonly mutedFg: string;
+  readonly selectedBg: string;
+  readonly titleBg: string;
+  readonly sectionBg: string;
+  readonly inputBg: string;
+  readonly bodyBg: string;
+}
+
+export const DEFAULT_OVERLAY_PALETTE: Readonly<OverlayBoxPalette> = {
+  borderFg: UI_TONES.fg.secondary,
+  titleFg: UI_TONES.fg.primary,
+  bodyFg: UI_TONES.fg.primary,
+  mutedFg: UI_TONES.fg.dim,
+  selectedBg: UI_TONES.bg.selected,
+  titleBg: UI_TONES.bg.title,
+  sectionBg: UI_TONES.bg.section,
+  inputBg: UI_TONES.bg.input,
+  bodyBg: UI_TONES.bg.surface,
+} as const;
+
+export interface OverlayBoxLayout {
+  readonly margin: number;
+  readonly width: number;
+  readonly contentWidth: number;
+  readonly innerWidth: number;
+}
+
+export interface OverlayTextStyle {
+  fg: string;
+  bg?: string;
+  bold?: boolean;
+  dim?: boolean;
+}
+
+export function createOverlayBoxLayout(
+  terminalWidth: number,
+  margin: number,
+  maxWidth: number,
+): OverlayBoxLayout {
+  const resolvedMaxWidth = getOverlayMaxWidth(terminalWidth, margin, maxWidth);
+  const width = Math.max(20, Math.min(terminalWidth - margin * 2, resolvedMaxWidth));
+  const contentWidth = width - 2;
+  const innerWidth = contentWidth - 2;
+  return { margin, width, contentWidth, innerWidth };
+}
+
+export function putOverlayText(
+  line: Line,
+  startX: number,
+  maxWidth: number,
+  text: string,
+  style: OverlayTextStyle,
+): void {
+  writeText(line, startX, maxWidth, text, {
+    fg: style.fg,
+    bg: style.bg ?? '',
+    bold: style.bold ?? false,
+    dim: style.dim ?? false,
+  });
+}
+
+export function createOverlayBorderLine(
+  terminalWidth: number,
+  layout: OverlayBoxLayout,
+  left: string,
+  fill: string,
+  right: string,
+  fg: string = DEFAULT_OVERLAY_PALETTE.borderFg,
+): Line {
+  const line = makeLine(terminalWidth);
+  const leftX = layout.margin;
+  const rightX = layout.margin + layout.width - 1;
+  line[leftX] = createStyledCell(left, { fg });
+  for (let x = leftX + 1; x < rightX; x++) {
+    line[x] = createStyledCell(fill, { fg });
+  }
+  line[rightX] = createStyledCell(right, { fg });
+  return line;
+}
+
+export function createOverlayContentLine(
+  terminalWidth: number,
+  layout: OverlayBoxLayout,
+  borderFg: string = DEFAULT_OVERLAY_PALETTE.borderFg,
+  bg = '',
+): Line {
+  const line = makeLine(terminalWidth);
+  const leftX = layout.margin;
+  const rightX = layout.margin + layout.width - 1;
+  line[leftX] = createStyledCell('│', { fg: borderFg });
+  fillWidth(line, leftX + 1, rightX - leftX - 1, bg);
+  line[rightX] = createStyledCell('│', { fg: borderFg });
+  return line;
+}
+
+export function createOverlayFilledBorderLine(
+  terminalWidth: number,
+  layout: OverlayBoxLayout,
+  left: string,
+  fill: string,
+  right: string,
+  fg: string = DEFAULT_OVERLAY_PALETTE.borderFg,
+  bg = '',
+): Line {
+  const line = makeLine(terminalWidth);
+  const leftX = layout.margin;
+  const rightX = layout.margin + layout.width - 1;
+  line[leftX] = createStyledCell(left, { fg, bg });
+  for (let x = leftX + 1; x < rightX; x++) {
+    line[x] = createStyledCell(fill, { fg, bg });
+  }
+  line[rightX] = createStyledCell(right, { fg, bg });
+  return line;
+}
+
+export function createOverlayFrameLine(
+  terminalWidth: number,
+  layout: OverlayBoxLayout,
+  bg = DEFAULT_OVERLAY_PALETTE.bodyBg,
+): Line {
+  return createOverlayContentLine(terminalWidth, layout, DEFAULT_OVERLAY_PALETTE.borderFg, bg);
+}
+
+export const OVERLAY_GLYPHS = {
+  topLeft: GLYPHS.frame.topLeft,
+  topRight: GLYPHS.frame.topRight,
+  bottomLeft: GLYPHS.frame.bottomLeft,
+  bottomRight: GLYPHS.frame.bottomRight,
+  teeLeft: GLYPHS.frame.teeLeft,
+  teeRight: GLYPHS.frame.teeRight,
+  horizontal: GLYPHS.frame.horizontal,
+  selected: GLYPHS.navigation.selected,
+  expanded: GLYPHS.navigation.expanded,
+  cursor: GLYPHS.surface.cursor,
+  moreAbove: GLYPHS.navigation.moreAbove,
+  moreBelow: GLYPHS.navigation.moreBelow,
+} as const;

package/src/renderer/overlay-viewport.ts

@@ -0,0 +1,104 @@
+import { getSurfaceContentRows } from './surface-layout.ts';
+
+export type OverlayWidthClass = 'narrow' | 'medium' | 'wide';
+
+export function getOverlayWidthClass(viewportWidth: number): OverlayWidthClass {
+  if (viewportWidth < 88) return 'narrow';
+  if (viewportWidth < 120) return 'medium';
+  return 'wide';
+}
+
+export interface OverlayViewportBudgetOptions {
+  readonly chromeRows: number;
+  readonly minContentRows?: number;
+  readonly maxContentRows?: number;
+  readonly targetRatio?: number;
+  readonly minTotalRows?: number;
+  readonly maxTotalRows?: number;
+}
+
+export function getOverlayContentBudget(
+  viewportHeight: number,
+  options: OverlayViewportBudgetOptions,
+): number {
+  const safeViewportHeight = Math.max(8, viewportHeight);
+  const defaultTargetTotalRows = Math.max(12, Math.min(Math.max(12, safeViewportHeight - 3), Math.round(safeViewportHeight * (options.targetRatio ?? 0.45))));
+  const minTotalRows = options.minTotalRows ?? 12;
+  const maxTotalRows = options.maxTotalRows ?? Math.max(minTotalRows, Math.min(22, safeViewportHeight - 2));
+  const targetTotalRows = Math.max(
+    minTotalRows,
+    Math.min(maxTotalRows, defaultTargetTotalRows),
+  );
+  return getSurfaceContentRows({
+    viewportHeight,
+    chromeRows: options.chromeRows,
+    minContentRows: options.minContentRows,
+    maxContentRows: options.maxContentRows,
+    targetRatio: 1,
+    minTotalRows: targetTotalRows,
+    maxTotalRows: targetTotalRows,
+  });
+}
+
+export function getOverlayMaxWidth(
+  terminalWidth: number,
+  margin: number,
+  requestedMaxWidth: number,
+): number {
+  const safeRequested = Math.max(24, requestedMaxWidth);
+  const reservedSideSpace = margin * 2;
+  const viewportBounded = Math.max(24, terminalWidth - reservedSideSpace);
+  return Math.min(safeRequested, viewportBounded);
+}
+
+export interface OverlaySurfaceMetricsOptions {
+  readonly margin?: number;
+  readonly maxWidth?: number;
+  readonly chromeRows: number;
+  readonly minContentRows?: number;
+  readonly maxContentRows?: number;
+  readonly targetRatio?: number;
+  readonly minTotalRows?: number;
+  readonly maxTotalRows?: number;
+}
+
+export interface OverlaySurfaceMetrics {
+  readonly margin: number;
+  readonly boxWidth: number;
+  readonly contentWidth: number;
+  readonly contentRows: number;
+}
+
+export function getStableOverlayContentRows(
+  contentRows: number,
+  minRows = 10,
+): number {
+  return Math.max(contentRows, minRows);
+}
+
+export function getOverlaySurfaceMetrics(
+  viewportWidth: number,
+  viewportHeight: number,
+  options: OverlaySurfaceMetricsOptions,
+): OverlaySurfaceMetrics {
+  // Keep overlays comfortably inset from shell panels and avoid wide, low-information modals.
+  const widthClass = getOverlayWidthClass(viewportWidth);
+  const margin = options.margin ?? (widthClass === 'wide' ? 6 : 4);
+  const defaultMaxWidth = widthClass === 'wide' ? 84 : widthClass === 'medium' ? 78 : 72;
+  const boxWidth = getOverlayMaxWidth(viewportWidth, margin, options.maxWidth ?? defaultMaxWidth);
+  const contentRows = getOverlayContentBudget(viewportHeight, {
+    chromeRows: options.chromeRows,
+    minContentRows: options.minContentRows ?? 8,
+    maxContentRows: options.maxContentRows ?? 14,
+    targetRatio: options.targetRatio ?? 0.45,
+    minTotalRows: options.minTotalRows,
+    maxTotalRows: options.maxTotalRows,
+  });
+
+  return {
+    margin,
+    boxWidth,
+    contentWidth: Math.max(1, boxWidth - 4),
+    contentRows,
+  };
+}

package/src/renderer/panel-composite.ts

@@ -0,0 +1,158 @@
+import type { Line } from '../types/grid.ts';
+import type { Panel } from '../panels/types.ts';
+import type { InputHandler } from '../input/handler.ts';
+import type { PanelManager } from '../panels/panel-manager.ts';
+import type { PanelCompositeData } from './compositor.ts';
+import { createSplitPaneLayout } from './layout-engine.ts';
+import { renderPanelTabBar } from './panel-tab-bar.ts';
+import { renderPanelWorkspaceBar } from './panel-workspace-bar.ts';
+
+/**
+ * R2: Per-panel render cache for dirty-flag skipping.
+ *
+ * Maintainability hazard — mid-render invalidation race:
+ *
+ * If an event listener (e.g. a runtime-bus subscriber) fires DURING a panel's
+ * `render()` call and mutates state such that `needsRender = true`, the
+ * trailing `panel.markRendered()` below will clobber that invalidation back
+ * to `false`, causing the next frame to serve stale cached output until
+ * something else invalidates the panel.
+ *
+ * In practice this is rare because `render()` is synchronous and short, and
+ * runtime-bus listeners that mutate panel state typically run outside the
+ * render pass. Panels that DO expect to mutate from within their own render
+ * path (e.g. deferred lazy-load) should call `this.invalidate()` AFTER the
+ * trailing work so the next frame picks it up.
+ *
+ * The fix (now applied): snapshot `needsRender` before calling `render()` and
+ * only call `markRendered()` when no concurrent invalidation occurred during
+ * the render pass — preserving any mid-render invalidation.
+ */
+interface PanelRenderCache {
+  lines: Line[];
+  width: number;
+  height: number;
+}
+const panelRenderCache = new WeakMap<Panel, PanelRenderCache>();
+/**
+ * Per-panel render-generation counter. Incremented whenever invalidate() fires
+ * on the panel (tracked here externally since Panel does not expose a version).
+ * We monkey-patch each panel the first time it enters renderPanel() by wrapping
+ * its invalidate() to bump the counter stored in this map.
+ *
+ * Race-guard: snapshot the generation before render(), compare after. If it
+ * changed, a mid-render invalidation occurred — leave needsRender=true.
+ */
+const panelRenderGen = new WeakMap<Panel, { gen: number }>();
+
+function getRenderGenState(panel: Panel): { gen: number } {
+  let state = panelRenderGen.get(panel);
+  if (!state) {
+    state = { gen: 0 };
+    panelRenderGen.set(panel, state);
+    // Wrap invalidate() to bump generation counter.
+    const origInvalidate = panel.invalidate.bind(panel);
+    panel.invalidate = () => {
+      state!.gen++;
+      origInvalidate();
+    };
+  }
+  return state;
+}
+
+/** R2: Render a panel, skipping if nothing changed. Returns cached lines on a skip. */
+export function renderPanel(panel: Panel, width: number, height: number): Line[] {
+  const cached = panelRenderCache.get(panel);
+  if (cached && !panel.needsRender && cached.width === width && cached.height === height) {
+    return cached.lines;
+  }
+  // Snapshot render-generation counter BEFORE calling render(). If an event
+  // listener fires during render() and calls panel.invalidate(), the generation
+  // counter will be bumped. We compare after render to detect mid-render races.
+  const genState = getRenderGenState(panel);
+  const genBefore = genState.gen;
+  const lines = panel.render(width, height);
+  // Only call markRendered() when no mid-render invalidation occurred.
+  // If the generation changed during render(), a concurrent invalidate() fired —
+  // leave needsRender=true so the next frame re-renders with the new state.
+  if (genState.gen === genBefore) {
+    panel.markRendered();
+  }
+  // If gen changed, needsRender is already true (invalidate() set it); do not
+  // call markRendered() — the next frame will pick it up.
+  panelRenderCache.set(panel, { lines, width, height });
+  return lines;
+}
+
+export interface PanelCompositeBuildResult {
+  readonly panelData?: PanelCompositeData;
+  readonly panelWidth?: number;
+}
+
+export function buildPanelCompositeData(
+  panelManager: PanelManager,
+  input: InputHandler,
+  panelWidth: number,
+  panelHeight: number,
+): PanelCompositeBuildResult {
+  if (!panelManager.isVisible() || panelManager.getAllOpen().length === 0 || panelWidth <= 0) {
+    return {};
+  }
+
+  const topPane = panelManager.getTopPane();
+  const bottomPane = panelManager.getBottomPane();
+  const focusedPane = panelManager.getFocusedPane();
+  const workspaceTabs = panelManager.getWorkspaceTabs();
+  const verticalSplitRatio = panelManager.getVerticalSplitRatio();
+  const hasBottom = panelManager.isBottomPaneVisible() && bottomPane.panels.length > 0;
+  const workspaceBar = renderPanelWorkspaceBar(workspaceTabs, panelWidth, input.panelFocused);
+
+  let topContent: Line[];
+  let topTabBar: Line | undefined;
+  let bottomTabBar: Line | undefined;
+  let bottomContent: Line[] | undefined;
+
+  const topActivePanel = topPane.panels[topPane.activeIndex] ?? null;
+
+  if (hasBottom) {
+    topTabBar = renderPanelTabBar(
+      topPane.panels,
+      topPane.activeIndex,
+      panelWidth,
+      input.panelFocused && focusedPane === 'top',
+      'top',
+    );
+    const paneLayout = createSplitPaneLayout(Math.max(0, panelHeight - 1), verticalSplitRatio);
+    const topH = paneLayout.topContentRows;
+    const bottomH = paneLayout.bottomContentRows;
+    topContent = topActivePanel ? renderPanel(topActivePanel, panelWidth, topH) : [];
+
+    const bottomActivePanel = bottomPane.panels[bottomPane.activeIndex] ?? null;
+    bottomTabBar = renderPanelTabBar(
+      bottomPane.panels,
+      bottomPane.activeIndex,
+      panelWidth,
+      input.panelFocused && focusedPane === 'bottom',
+      'bottom',
+    );
+    bottomContent = bottomActivePanel ? renderPanel(bottomActivePanel, panelWidth, bottomH) : [];
+  } else {
+    const topH = Math.max(0, panelHeight - 1);
+    topContent = topActivePanel ? renderPanel(topActivePanel, panelWidth, topH) : [];
+  }
+
+  return {
+    panelData: {
+      workspaceBar,
+      topTabBar,
+      topContent,
+      topFocused: input.panelFocused && focusedPane === 'top',
+      bottomTabBar,
+      bottomContent,
+      bottomFocused: input.panelFocused && focusedPane === 'bottom',
+      separator: true,
+      verticalSplitRatio,
+    },
+    panelWidth,
+  };
+}

package/src/renderer/panel-picker-overlay.ts

@@ -0,0 +1,202 @@
+import { type Line } from '../types/grid.ts';
+import { fitDisplay, getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
+import type { PanelPicker } from '../panels/panel-picker.ts';
+import { CATEGORY_LABELS, CATEGORY_ORDER } from '../panels/panel-picker.ts';
+import type { PanelCategory, PanelRegistration } from '../panels/types.ts';
+import {
+  createOverlayBorderLine,
+  createOverlayBoxLayout,
+  createOverlayContentLine,
+  DEFAULT_OVERLAY_PALETTE,
+  putOverlayText,
+} from './overlay-box.ts';
+import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
+
+const TITLE_FG = '#cbd5e1';
+const CATEGORY_FG = '#94a3b8';
+const SELECTED_FG = '#e2e8f0';
+const SELECTED_BG = '#1e293b';
+const BODY_FG = '252';
+const BORDER_FG = DEFAULT_OVERLAY_PALETTE.borderFg;
+
+/**
+ * Render the panel picker modal as Line[] for overlay in the viewport.
+ * Panels are grouped by category. Category headers are inserted between groups.
+ * When a search query is active a search-bar row is shown beneath the title.
+ */
+export function renderPanelPickerOverlay(
+  picker: PanelPicker,
+  width: number,
+  viewportHeight = 24,
+): Line[] {
+  if (!picker.active) return [];
+
+  const lines: Line[] = [];
+  const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
+    margin: 4,
+    maxWidth: 72,
+    chromeRows: picker.searchQuery.length > 0 ? 7 : 6,
+    minContentRows: 6,
+    maxContentRows: 10,
+  });
+  const layout = createOverlayBoxLayout(width, metrics.margin, metrics.boxWidth);
+  const contentW = layout.innerWidth;
+  const titleFg = TITLE_FG;
+  const borderFg = BORDER_FG;
+
+  // ── Title bar ──────────────────────────────────────────────────────────────
+  const titleLine = createOverlayBorderLine(width, layout, '┌', '─', '┐', borderFg);
+  putOverlayText(titleLine, layout.margin + 2, layout.width - 4, 'Open Panel Workspace', { fg: titleFg, bold: true });
+  lines.push(titleLine);
+
+  // ── Search bar (shown when query is non-empty) ──────────────────────────────
+  if (picker.searchQuery.length > 0) {
+    const searchLine = createOverlayContentLine(width, layout, borderFg);
+    const searchLabel = '\u2315 ';
+    const queryAvail = contentW - getDisplayWidth(searchLabel);
+    const queryText = fitDisplay(picker.searchQuery, queryAvail);
+    putOverlayText(searchLine, layout.margin + 2, getDisplayWidth(searchLabel), searchLabel, { fg: titleFg });
+    putOverlayText(searchLine, layout.margin + 2 + getDisplayWidth(searchLabel), queryAvail, queryText, { fg: titleFg });
+    lines.push(searchLine);
+
+    lines.push(createOverlayBorderLine(width, layout, '├', '─', '┤', borderFg));
+  } else {
+    const placeholder = ' Browse by category or start typing to filter by panel name, purpose, or category.';
+    const row = createOverlayContentLine(width, layout, borderFg);
+    putOverlayText(row, layout.margin + 2, contentW, fitDisplay(placeholder, contentW), { fg: '244', dim: true });
+    lines.push(row);
+  }
+
+  const visible = picker.getVisible();
+
+  if (visible.length === 0) {
+    const noResults = 'No panels match your search';
+    const noRow = createOverlayContentLine(width, layout, borderFg);
+    putOverlayText(noRow, layout.margin + 2, contentW, fitDisplay(noResults, contentW), { fg: '244', dim: true });
+    lines.push(noRow);
+  } else {
+    // Build a flat render list of { type: 'header' | 'item', ... } entries
+    // so we can compute the correct scroll window over all rows.
+    type HeaderEntry = { type: 'header'; category: PanelCategory };
+    type ItemEntry   = { type: 'item';   reg: PanelRegistration; flatIndex: number };
+    type RenderEntry = HeaderEntry | ItemEntry;
+
+    const renderEntries: RenderEntry[] = [];
+
+    // When no search query, group by category; when searching, show flat list
+    // with a single "Results" header.
+    if (picker.searchQuery.length === 0) {
+      const byCategory = new Map<PanelCategory, PanelRegistration[]>();
+      for (const reg of visible) {
+        const group = byCategory.get(reg.category) ?? [];
+        group.push(reg);
+        byCategory.set(reg.category, group);
+      }
+      let flatIndex = 0;
+      for (const cat of CATEGORY_ORDER) {
+        const group = byCategory.get(cat);
+        if (!group || group.length === 0) continue;
+        renderEntries.push({ type: 'header', category: cat });
+        for (const reg of group) {
+          renderEntries.push({ type: 'item', reg, flatIndex });
+          flatIndex++;
+        }
+      }
+    } else {
+      for (let i = 0; i < visible.length; i++) {
+        renderEntries.push({ type: 'item', reg: visible[i], flatIndex: i });
+      }
+    }
+
+    // Compute scroll window: ensure the selected item row stays visible.
+    // Find the render-entry index of the selected item.
+    const selectedEntryIdx = renderEntries.findIndex(
+      e => e.type === 'item' && e.flatIndex === picker.selectedIndex,
+    );
+    const total = renderEntries.length;
+    const maxVisible = metrics.contentRows;
+    let startEntry = 0;
+    if (total > maxVisible && selectedEntryIdx >= 0) {
+      startEntry = Math.max(
+        0,
+        Math.min(
+          selectedEntryIdx - Math.floor(maxVisible / 2),
+          total - maxVisible,
+        ),
+      );
+    }
+    const endEntry = Math.min(startEntry + maxVisible, total);
+
+    for (let i = startEntry; i < endEntry; i++) {
+      const entry = renderEntries[i];
+
+      if (entry.type === 'header') {
+        // Category header row
+        const label = CATEGORY_LABELS[entry.category].toUpperCase();
+        const headerRow = createOverlayContentLine(width, layout, borderFg);
+        putOverlayText(headerRow, layout.margin + 2, contentW, fitDisplay(`  ${label}`, contentW), { fg: CATEGORY_FG, dim: true });
+        lines.push(headerRow);
+      } else {
+        const { reg, flatIndex } = entry;
+        const isSelected = flatIndex === picker.selectedIndex;
+        const indicator = isSelected ? '\u25b6 ' : '  ';
+
+        // icon (1 char) + 2 spaces + name
+        const iconStr = reg.icon + '  ';
+        const iconW = getDisplayWidth(iconStr);
+
+        // separator between name and description: ' \u2014 '
+        const sep = ' \u2014 ';
+        const sepW = getDisplayWidth(sep);
+
+        // Allocate space: indicator(2) + icon(iconW) + name + sep + desc fills contentW
+        const nameMaxW = Math.max(8, Math.floor((contentW - 2 - iconW - sepW) * 0.35));
+        const descMaxW = contentW - 2 - iconW - nameMaxW - sepW;
+
+        const nameRaw = reg.name;
+        const nameStr = fitDisplay(nameRaw, nameMaxW);
+
+        const descRaw = reg.description;
+        const descStr = fitDisplay(descRaw, descMaxW);
+
+        const row = createOverlayContentLine(width, layout, borderFg, isSelected ? SELECTED_BG : '');
+        const rowText = indicator + iconStr + nameStr + sep + descStr;
+        putOverlayText(row, layout.margin + 2, contentW, fitDisplay(truncateDisplay(rowText, contentW), contentW), {
+          fg: isSelected ? SELECTED_FG : BODY_FG,
+          bg: isSelected ? SELECTED_BG : '',
+          bold: isSelected,
+        });
+        lines.push(row);
+      }
+    }
+
+    const selected = picker.getSelected();
+    if (selected) {
+      lines.push(createOverlayBorderLine(width, layout, '├', '─', '┤', borderFg));
+      const categoryLabel = CATEGORY_LABELS[selected.category].toUpperCase();
+      const selectedLine = createOverlayContentLine(width, layout, borderFg);
+      putOverlayText(selectedLine, layout.margin + 2, contentW, fitDisplay(`${selected.icon} ${selected.name}  [${categoryLabel}]`, contentW), { fg: SELECTED_FG });
+      lines.push(selectedLine);
+      const desc = fitDisplay(truncateDisplay(selected.description, contentW), contentW);
+      const descRow = createOverlayContentLine(width, layout, borderFg);
+      putOverlayText(descRow, layout.margin + 2, contentW, desc, { fg: '244', dim: true });
+      lines.push(descRow);
+    }
+
+    // ── Scroll indicator ───────────────────────────────────────────────────
+    if (total > maxVisible) {
+      const scrollInfo = `${picker.selectedIndex + 1}/${visible.length}`;
+      const scrollRow = createOverlayContentLine(width, layout, borderFg);
+      putOverlayText(scrollRow, layout.margin + 2 + Math.max(0, contentW - getDisplayWidth(scrollInfo)), getDisplayWidth(scrollInfo), scrollInfo, { fg: '240', dim: true });
+      lines.push(scrollRow);
+    }
+  }
+
+  // ── Bottom border with hints ───────────────────────────────────────────────
+  const hints = '[Up/Down] Navigate  [Enter] Open  [/] Filter  [Esc] Cancel';
+  const bottomLine = createOverlayBorderLine(width, layout, '└', '─', '┘', borderFg);
+  putOverlayText(bottomLine, layout.margin + 2, layout.width - 4, truncateDisplay(hints, layout.width - 4), { fg: '240', dim: true });
+  lines.push(bottomLine);
+
+  return lines;
+}

package/src/renderer/panel-tab-bar.ts

@@ -0,0 +1,69 @@
+import { type Line } from '../types/grid.ts';
+import type { Panel } from '../panels/types.ts';
+import { renderTabStrip } from './tab-strip.ts';
+
+const ACTIVE_FG = '#e2e8f0';
+const ACTIVE_FG_UNFOCUSED = '#94a3b8';
+const ACTIVE_BG = '#1e293b';
+const INACTIVE_FG = '244';
+const SEPARATOR_FG = '238';
+const CLOSE_FG = '238';
+const LABEL_FG = '#cbd5e1';
+const LABEL_BG = '#0f172a';
+
+/**
+ * Render the panel tab bar.
+ *
+ * Shows open panel tabs with the active one highlighted.
+ * Format: │ icon Name │ icon Name │ ...
+ *
+ * Active tab:   slate-white, bold, bg #1e293b
+ * Inactive tab: grey (244), no background
+ * Separators:   │ in dim grey (238)
+ * Overflow:     > right scroll indicator (stateless - shows when tabs extend beyond width)
+ * Close button: x at far right for active tab
+ */
+export function renderPanelTabBar(
+  panels: Panel[],
+  activeIndex: number,
+  width: number,
+  focused: boolean = true,
+  paneLabel?: string,
+): Line {
+  if (panels.length === 0) return renderTabStrip({ width, tabs: [], style: {
+    activeFg: ACTIVE_FG,
+    activeBg: ACTIVE_BG,
+    activeBold: focused,
+    inactiveFg: INACTIVE_FG,
+    separatorFg: SEPARATOR_FG,
+    labelFg: LABEL_FG,
+    labelBg: focused ? LABEL_BG : '',
+    labelBold: focused,
+    overflowFg: SEPARATOR_FG,
+    trailingFg: focused ? ACTIVE_FG_UNFOCUSED : INACTIVE_FG,
+  } });
+
+  const tabs = panels.map((panel, index) => ({
+    label: `${panel.icon} ${panel.name}`,
+    active: index === activeIndex,
+  }));
+
+  return renderTabStrip({
+    width,
+    tabs,
+    prefixLabel: paneLabel ? ` ${paneLabel.toUpperCase()} ` : undefined,
+    suffixLabel: ` ${panels.length}  x `,
+    style: {
+      activeFg: focused ? ACTIVE_FG : ACTIVE_FG_UNFOCUSED,
+      activeBg: ACTIVE_BG,
+      activeBold: focused,
+      inactiveFg: INACTIVE_FG,
+      separatorFg: SEPARATOR_FG,
+      labelFg: LABEL_FG,
+      labelBg: focused ? LABEL_BG : '',
+      labelBold: focused,
+      overflowFg: SEPARATOR_FG,
+      trailingFg: CLOSE_FG,
+    },
+  });
+}