@pellux/goodvibes-tui 0.26.0 → 0.28.0

package/src/panels/routes-panel.ts

@@ -4,9 +4,11 @@ import { ScrollableListPanel } from './scrollable-list-panel.ts';
 import type { UiReadModel, UiRoutesSnapshot } from '../runtime/ui-read-models.ts';
 import { truncateDisplay } from '../utils/terminal-width.ts';
 import {
+  buildDetailBlock,
   buildEmptyState,
   buildGuidanceLine,
   buildKeyValueLine,
+  buildKeyboardHints,
   buildPanelLine,
   buildPanelWorkspace,
   buildStatusPill,
@@ -39,10 +41,20 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
   public constructor(readModel?: UiReadModel<UiRoutesSnapshot>) {
     super('routes', 'Routes', 'R', 'monitoring');
     this.showSelectionGutter = true; // I5: non-color selection affordance
+    this.filterEnabled = true;
+    this.filterLabel = 'Filter routes';
     this.readModel = readModel;
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }
 
+  protected override filterMatches(binding: RouteBinding, q: string): boolean {
+    return binding.surfaceKind.toLowerCase().includes(q)
+      || (binding.title ?? '').toLowerCase().includes(q)
+      || binding.externalId.toLowerCase().includes(q)
+      || (binding.sessionId ?? '').toLowerCase().includes(q)
+      || (binding.runId ?? '').toLowerCase().includes(q);
+  }
+
   public override onDestroy(): void {
     this.unsub?.();
   }
@@ -127,7 +139,7 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
     this.clampSelection();
     const selected = bindings[this.selectedIndex]!;
 
-    const footerLines: Line[] = [
+    const detailRows: Line[] = [
       buildPanelLine(width, [
         ['  Binding: ', C.label],
         [selected.id, C.value],
@@ -159,20 +171,30 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
     ];
 
     if (surfaceEntries.length > 0) {
-      footerLines.push(
-        ...surfaceEntries.slice(0, 6).map(([surface, ids]) => buildPanelLine(width, [
+      detailRows.push(
+        ...surfaceEntries.slice(0, 4).map(([surface, ids]) => buildPanelLine(width, [
           [' ', C.label],
           [surface.padEnd(10), C.info],
           [` ${String(ids.length)} binding(s)`, C.value],
         ])),
       );
     }
-    footerLines.push(buildPanelLine(width, [['  Up/Down move through route bindings', C.dim]]));
+
+    const hints = this.filterActive
+      ? [{ keys: 'type', label: 'filter' }, { keys: 'Enter', label: 'apply' }, { keys: 'Esc', label: 'clear' }]
+      : [
+          { keys: 'Up/Down', label: 'move' },
+          { keys: '/communication', label: 'inspect flow' },
+          { keys: '/', label: 'filter' },
+        ];
 
     return this.renderList(width, height, {
       title: 'Route Bindings',
       header: headerLines,
-      footer: footerLines,
+      footer: [
+        ...buildDetailBlock(width, `Binding · ${selected.surfaceKind}`, detailRows, C),
+        buildKeyboardHints(width, hints, C),
+      ],
     });
   }
 }

package/src/panels/sandbox-panel.ts

@@ -5,9 +5,11 @@ import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { buildSandboxReview, listSandboxPresets, listSandboxProfiles } from '@/runtime/index.ts';
 import type { SandboxSessionRegistry } from '@/runtime/index.ts';
 import {
+  buildAlignedRow,
   buildBodyText,
   buildEmptyState,
   buildGuidanceLine,
+  buildKeyboardHints,
   buildKeyValueLine,
   buildPanelLine,
   buildPanelWorkspace,
@@ -125,7 +127,10 @@ export class SandboxPanel extends BasePanel {
       buildGuidanceLine(width, '/sandbox wrapper-test <profile>', 'validate the wrapper bridge contract before wiring a real guest transport', C),
       buildGuidanceLine(width, '/sandbox session run <id> <command> [args...]', 'execute through a tracked sandbox session and capture runtime metadata on the session record', C),
       buildGuidanceLine(width, 'GV_SANDBOX_WRAPPER_MODE=host-exec', 'validate the wrapper contract on the host before wiring a real guest transport', C),
-      buildPanelLine(width, [[`  Up/Down move  Home/End jump  focus=profiles+sessions`, C.dim]]),
+      buildKeyboardHints(width, [
+        { keys: '↑/↓', label: 'select profile/session' },
+        { keys: 'Home/End', label: 'jump to first profile / first session' },
+      ], C),
     ];
 
     const selectionLines: Line[] = [];
@@ -185,41 +190,71 @@ export class SandboxPanel extends BasePanel {
       ));
     } else {
       for (const session of sessions) {
-        const bg = selectedSession?.id === session.id ? C.headerBg : undefined;
-        sessionLines.push(buildPanelLine(width, [
-          ['  ', C.label],
-          [session.profileId.padEnd(15), C.info, bg],
-          [session.state.padEnd(10), session.state === 'running' ? C.good : session.state === 'failed' ? C.bad : C.warn, bg],
-          [(session.shared ? 'shared' : 'dedicated').padEnd(12), C.value, bg],
-          [String(session.resolvedBackend ?? session.backend).padEnd(8), C.dim, bg],
-          [` ${(session.startupStatus ?? 'n/a').slice(0, 8).padEnd(8)}`, session.startupStatus === 'verified' ? C.good : session.startupStatus === 'failed' ? C.bad : C.warn, bg],
-          [` ${String(session.executionCount ?? 0).padStart(3)}x`, C.info, bg],
-          [` ${session.id.slice(0, Math.max(8, Math.min(14, width - 64)))}`, C.dim, bg],
-        ]));
+        const selectedRow = selectedSession?.id === session.id;
+        sessionLines.push(buildAlignedRow(
+          width,
+          [
+            { text: session.profileId, fg: C.info },
+            { text: session.state, fg: session.state === 'running' ? C.good : session.state === 'failed' ? C.bad : C.warn },
+            { text: session.shared ? 'shared' : 'dedicated', fg: C.value },
+            { text: String(session.resolvedBackend ?? session.backend), fg: C.dim },
+            { text: session.startupStatus ?? 'n/a', fg: session.startupStatus === 'verified' ? C.good : session.startupStatus === 'failed' ? C.bad : C.warn },
+            { text: `${session.executionCount ?? 0}x`, fg: C.info },
+            { text: session.id, fg: C.dim },
+          ],
+          [
+            { width: 15 },
+            { width: 10 },
+            { width: 12 },
+            { width: 8 },
+            { width: 9 },
+            { width: 5, align: 'right' },
+            { width: Math.max(8, width - 72) },
+          ],
+          { selected: selectedRow, selectedBg: C.headerBg },
+        ));
       }
     }
 
     const presetLines: Line[] = [];
     for (const preset of presets.slice(0, 2)) {
-      presetLines.push(buildPanelLine(width, [
-        ['  ', C.label],
-        [preset.id.padEnd(18), C.info],
-        [preset.config.replIsolation.padEnd(16), C.value],
-        [preset.config.mcpIsolation.padEnd(16), C.dim],
-        [preset.config.windowsMode, C.warn],
-      ]));
+      presetLines.push(buildAlignedRow(
+        width,
+        [
+          { text: preset.id, fg: C.info },
+          { text: preset.config.replIsolation, fg: C.value },
+          { text: preset.config.mcpIsolation, fg: C.dim },
+          { text: preset.config.windowsMode, fg: C.warn },
+        ],
+        [
+          { width: 18 },
+          { width: 16 },
+          { width: 16 },
+          { width: Math.max(8, width - 62) },
+        ],
+        {},
+      ));
     }
 
     const profileLines: Line[] = [];
     for (const profile of profiles) {
-      const bg = selectedProfile?.id === profile.id ? C.headerBg : undefined;
-      profileLines.push(buildPanelLine(width, [
-        ['  ', C.label],
-        [profile.id.padEnd(15), C.info, bg],
-        [profile.isolation.padEnd(14), C.value, bg],
-        [profile.kind.padEnd(12), C.dim, bg],
-        [` vm=${profile.requiresVm ? 'yes' : 'no'}`, profile.requiresVm ? C.good : C.warn, bg],
-      ]));
+      const selectedRow = selectedProfile?.id === profile.id;
+      profileLines.push(buildAlignedRow(
+        width,
+        [
+          { text: profile.id, fg: C.info },
+          { text: profile.isolation, fg: C.value },
+          { text: profile.kind, fg: C.dim },
+          { text: `vm=${profile.requiresVm ? 'yes' : 'no'}`, fg: profile.requiresVm ? C.good : C.warn },
+        ],
+        [
+          { width: 15 },
+          { width: 14 },
+          { width: 12 },
+          { width: Math.max(6, width - 53) },
+        ],
+        { selected: selectedRow, selectedBg: C.headerBg },
+      ));
     }
     const postureSection: PanelWorkspaceSection = { title: 'Sandbox posture', lines: overviewLines };
     const selectedSection: PanelWorkspaceSection = { title: selectedProfile ? 'Selected Profile' : 'Selected Session', lines: selectionLines };

package/src/panels/schedule-panel.ts

@@ -1,13 +1,16 @@
 import { BasePanel } from './base-panel.ts';
 import { type Line } from '../types/grid.ts';
+import { fitDisplay, truncateDisplay } from '../utils/terminal-width.ts';
 import type { AutomationManager } from '@pellux/goodvibes-sdk/platform/automation';
 import type { AutomationJob } from '@pellux/goodvibes-sdk/platform/automation';
 import type { AutomationRun } from '@pellux/goodvibes-sdk/platform/automation';
 import type { AutomationScheduleDefinition } from '@pellux/goodvibes-sdk/platform/automation';
 import {
   buildEmptyState,
+  buildKeyboardHints,
   buildPanelLine,
   buildPanelWorkspace,
+  extendPalette,
   resolveScrollablePanelSection,
   DEFAULT_PANEL_PALETTE,
   type PanelWorkspaceSection,
@@ -17,12 +20,9 @@ import {
 // Colors
 // ---------------------------------------------------------------------------
 
-const C = {
-  header: '#00d7ff',
-  sectionHeader: '244',
+const C = extendPalette(DEFAULT_PANEL_PALETTE, {
   enabled: '#5fd700',
   disabled: '#6c6c6c',
-  selected: '#1c1c1c',
   selectedFg: '#ffffff',
   id: '238',
   cron: '#af87ff',
@@ -32,8 +32,7 @@ const C = {
   runCount: '#ffaf00',
   statusRunning: '#5fd700',
   statusFailed: '#ff5f5f',
-  hint: '240',
-} as const;
+});
 
 // ---------------------------------------------------------------------------
 // View items
@@ -90,11 +89,16 @@ export class SchedulePanel extends BasePanel {
   private refreshTimerId: ReturnType<typeof setInterval> | null = null;
   private readonly automationManager: ScheduleAutomationManager;
 
-  constructor(automationManager: ScheduleAutomationManager) {
+  constructor(automationManager: ScheduleAutomationManager, private readonly requestRender: () => void = () => {}) {
     super('schedule', 'Schedule', 'Z', 'agent');
     this.automationManager = automationManager;
   }
 
+  private _markDirtyAndRender(): void {
+    this.markDirty();
+    this.requestRender();
+  }
+
   // -------------------------------------------------------------------------
   // Lifecycle
   // -------------------------------------------------------------------------
@@ -103,12 +107,12 @@ export class SchedulePanel extends BasePanel {
     super.onActivate();
     void this.automationManager.start().then(() => {
       this.rebuild();
-      this.markDirty();
+      this._markDirtyAndRender();
     });
     this.rebuild();
     this.refreshTimerId = this.registerTimer(setInterval(() => {
       this.rebuild();
-      this.markDirty();
+      this._markDirtyAndRender();
     }, 5_000));
   }
 
@@ -224,14 +228,19 @@ export class SchedulePanel extends BasePanel {
             lines: buildEmptyState(
               width,
               ' No scheduled tasks',
-              'Use /schedule add to create a recurring task. Scheduled runs and history will appear here.',
-              [],
+              'Create a recurring task and its next-run timing, run history, and enablement state will appear here.',
+              [
+                { command: '/schedule add cron 0 * * * * repo sweep', summary: 'create a recurring cron task' },
+                { command: '/schedule list', summary: 'inspect scheduled tasks from the shell' },
+              ],
               DEFAULT_PANEL_PALETTE,
             ),
           },
         ],
         footerLines: [
-          buildPanelLine(width, [[' Up/Down', DEFAULT_PANEL_PALETTE.info], [' navigate', DEFAULT_PANEL_PALETTE.dim], ['   Space', DEFAULT_PANEL_PALETTE.info], [' toggle', DEFAULT_PANEL_PALETTE.dim], ['   r', DEFAULT_PANEL_PALETTE.info], [' run now', DEFAULT_PANEL_PALETTE.dim], ['   R', DEFAULT_PANEL_PALETTE.info], [' refresh', DEFAULT_PANEL_PALETTE.dim]]),
+          buildKeyboardHints(width, [
+            { keys: '/schedule add', label: 'create a task' },
+          ], DEFAULT_PANEL_PALETTE),
         ],
         palette: DEFAULT_PANEL_PALETTE,
       });
@@ -239,6 +248,7 @@ export class SchedulePanel extends BasePanel {
 
     const taskItems = this.items.filter((item): item is Extract<ViewItem, { kind: 'task' }> => item.kind === 'task');
     this.selectedIndex = Math.max(0, Math.min(this.selectedIndex, taskItems.length - 1));
+    const dueSoon = tasks.filter((task: AutomationJob) => typeof task.nextRunAt === 'number').length;
     const summarySection: PanelWorkspaceSection = {
       title: 'Summary',
       lines: [
@@ -247,14 +257,28 @@ export class SchedulePanel extends BasePanel {
           [String(tasks.length), DEFAULT_PANEL_PALETTE.value],
           ['   Enabled ', DEFAULT_PANEL_PALETTE.label],
           [String(enabled), enabled > 0 ? DEFAULT_PANEL_PALETTE.good : DEFAULT_PANEL_PALETTE.dim],
+          ['   Paused ', DEFAULT_PANEL_PALETTE.label],
+          [String(tasks.length - enabled), tasks.length - enabled > 0 ? DEFAULT_PANEL_PALETTE.warn : DEFAULT_PANEL_PALETTE.dim],
+          ['   Scheduled ', DEFAULT_PANEL_PALETTE.label],
+          [String(dueSoon), dueSoon > 0 ? DEFAULT_PANEL_PALETTE.info : DEFAULT_PANEL_PALETTE.dim],
         ]),
       ],
     };
+    const selectedTask = taskItems[this.selectedIndex]?.task;
+    const toggleLabel = selectedTask
+      ? (selectedTask.enabled ? 'pause task' : 'enable task')
+      : 'toggle';
+    const footerLines = [
+      buildKeyboardHints(width, [
+        { keys: 'Up/Down', label: 'navigate' },
+        { keys: 'Space', label: toggleLabel },
+        { keys: 'r', label: 'run now' },
+        { keys: 'R', label: 'refresh' },
+      ], DEFAULT_PANEL_PALETTE),
+    ];
     const scheduledTasksSection = resolveScrollablePanelSection(width, height, {
       intro: 'Review recurring scheduled tasks, next run timing, recent history, and enablement state.',
-      footerLines: [
-        buildPanelLine(width, [[' Up/Down', DEFAULT_PANEL_PALETTE.info], [' navigate', DEFAULT_PANEL_PALETTE.dim], ['   Space', DEFAULT_PANEL_PALETTE.info], [' toggle', DEFAULT_PANEL_PALETTE.dim], ['   r', DEFAULT_PANEL_PALETTE.info], [' run now', DEFAULT_PANEL_PALETTE.dim], ['   R', DEFAULT_PANEL_PALETTE.info], [' refresh', DEFAULT_PANEL_PALETTE.dim]]),
-      ],
+      footerLines,
       palette: DEFAULT_PANEL_PALETTE,
       beforeSections: [summarySection],
       section: {
@@ -275,9 +299,7 @@ export class SchedulePanel extends BasePanel {
       title: ' Schedule',
       intro: 'Review recurring scheduled tasks, next run timing, recent history, and enablement state.',
       sections,
-      footerLines: [
-        buildPanelLine(width, [[' Up/Down', DEFAULT_PANEL_PALETTE.info], [' navigate', DEFAULT_PANEL_PALETTE.dim], ['   Space', DEFAULT_PANEL_PALETTE.info], [' toggle', DEFAULT_PANEL_PALETTE.dim], ['   r', DEFAULT_PANEL_PALETTE.info], [' run now', DEFAULT_PANEL_PALETTE.dim], ['   R', DEFAULT_PANEL_PALETTE.info], [' refresh', DEFAULT_PANEL_PALETTE.dim]]),
-      ],
+      footerLines,
       palette: DEFAULT_PANEL_PALETTE,
     });
   }
@@ -289,16 +311,16 @@ export class SchedulePanel extends BasePanel {
    *   Row 3:          prompt preview  [history]
    */
   private renderTask(task: AutomationJob, history: AutomationRun[], selected: boolean, width: number): Line[] {
-    const bg = selected ? C.selected : undefined;
+    const bg = selected ? C.selectBg : undefined;
     const fgBase = selected ? C.selectedFg : undefined;
 
     const bullet = task.enabled ? '* ' : 'o ';
     const bulletFg = task.enabled ? C.enabled : C.disabled;
-    const nameStr = task.name.length > 28 ? task.name.slice(0, 25) + '...' : task.name.padEnd(28);
+    const nameStr = fitDisplay(task.name, 28);
     const scheduleText = formatSchedule(task.schedule);
     const row1 = buildPanelLine(width, [
       [bullet, bulletFg, bg],
-      [task.id.slice(0, 12), fgBase ?? C.id, bg],
+      [fitDisplay(task.id, 12), fgBase ?? C.id, bg],
       ['  ', fgBase ?? C.prompt, bg],
       [nameStr, fgBase ?? C.prompt, bg],
       ['  ', fgBase ?? C.prompt, bg],
@@ -321,9 +343,7 @@ export class SchedulePanel extends BasePanel {
 
     const maxPromptLen = Math.max(20, width - indent.length - 30);
     const prompt = task.execution.prompt ?? task.description ?? '';
-    const promptPreview = prompt.length > maxPromptLen
-      ? prompt.slice(0, maxPromptLen - 1) + '\u2026'
-      : prompt;
+    const promptPreview = truncateDisplay(prompt, maxPromptLen);
 
     // Show last 3 run statuses as colored dots
     const recentRuns = history.slice(-3);

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

@@ -5,6 +5,7 @@ import type { PanelCategory } from './types.ts';
 import type { ComponentHealthMonitor } from '../runtime/perf/panel-health-monitor.ts';
 import {
   buildEmptyState,
+  buildKeyboardHints,
   buildPanelWorkspace,
   buildSearchInputLine,
   DEFAULT_PANEL_PALETTE,
@@ -56,6 +57,96 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
    */
   protected showSelectionGutter = false;
 
+  // -------------------------------------------------------------------------
+  // Opt-in inline filter ( / to filter, Esc to clear )
+  // -------------------------------------------------------------------------
+  // Set `filterEnabled = true` and override `filterMatches()` to give a list
+  // panel a `/`-to-filter affordance that coexists with single-letter action
+  // keys (filtering is modal: action keys work until you press `/`). A filter
+  // input line is auto-rendered at the top of the list.
+  protected filterEnabled = false;
+  protected filterQuery = '';
+  protected filterActive = false;
+  /** Short noun shown in the filter hint, e.g. "Filter sessions". */
+  protected filterLabel = 'Filter';
+
+  /** Override to define what the lower-cased filter query matches for an item. */
+  protected filterMatches(_item: T, _query: string): boolean {
+    return false;
+  }
+
+  /**
+   * The list after applying the active filter — used for both display and
+   * navigation. Identical to `getItems()` unless a filter is enabled and a
+   * non-empty query is set, so existing panels are unaffected.
+   */
+  protected getVisibleItems(): readonly T[] {
+    const all = this.getItems();
+    const q = this.filterQuery.trim().toLowerCase();
+    if (!this.filterEnabled || !q) return all;
+    return all.filter((item) => this.filterMatches(item, q));
+  }
+
+  /**
+   * Filter-mode key handling. Returns `true`/`false` when consumed/ignored in
+   * filter context, or `null` to fall through to normal navigation.
+   */
+  private _handleFilterKey(key: string): boolean | null {
+    if (!this.filterEnabled) return null;
+    if (this.filterActive) {
+      if (key === 'escape') {
+        this.filterActive = false;
+        this.filterQuery = '';
+        this.selectedIndex = 0;
+        this.needsRender = true;
+        return true;
+      }
+      if (key === 'return' || key === 'enter') {
+        this.filterActive = false; // commit; keep the query applied
+        this.needsRender = true;
+        return true;
+      }
+      if (key === 'backspace' || key === 'delete') {
+        this.filterQuery = this.filterQuery.slice(0, -1);
+        this.selectedIndex = 0;
+        this.needsRender = true;
+        return true;
+      }
+      // Arrow/paging keys navigate the filtered list — fall through.
+      if (key === 'up' || key === 'down' || key === 'pageup' || key === 'pagedown' || key === 'home' || key === 'end') {
+        return null;
+      }
+      // Any printable character (including j/k/g/G) extends the query.
+      if (key.length === 1 && key >= ' ') {
+        this.filterQuery += key;
+        this.selectedIndex = 0;
+        this.needsRender = true;
+        return true;
+      }
+      return false;
+    }
+    if (key === '/') {
+      this.filterActive = true;
+      this.needsRender = true;
+      return true;
+    }
+    return null;
+  }
+
+  /** The filter input line shown at the top of the list when filtering is enabled. */
+  protected buildFilterLine(width: number): Line {
+    const palette = this.getPalette();
+    const label = this.filterActive ? `[${this.filterLabel}] ` : `${this.filterLabel}: `;
+    const value = this.filterActive
+      ? `${this.filterQuery}_`
+      : this.filterQuery || '(/ to filter)';
+    return buildSearchInputLine(width, label, value, palette, {
+      active: false,
+      bg: this.filterActive ? palette.inputBg : palette.sectionBg,
+      valueColor: this.filterActive ? palette.info : (this.filterQuery ? palette.value : palette.dim),
+    });
+  }
+
   constructor(
     id: string,
     name: string,
@@ -143,7 +234,11 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     // call this.clearError() at the start of their handler.
     if (this.lastError !== null) this.clearError();
 
-    const items = this.getItems();
+    // Opt-in inline filter consumes input before navigation when active.
+    const filterResult = this._handleFilterKey(key);
+    if (filterResult !== null) return filterResult;
+
+    const items = this.getVisibleItems();
     const total = items.length;
 
     switch (key) {
@@ -202,7 +297,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
 
   handleScroll(deltaRows: number): boolean {
     if (this.lastError !== null) this.clearError();
-    const total = this.getItems().length;
+    const total = this.getVisibleItems().length;
     const rows = Math.trunc(deltaRows);
     if (total === 0 || rows === 0) return false;
     const next = Math.max(0, Math.min(total - 1, this.selectedIndex + rows));
@@ -221,7 +316,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
    * Must be called after any data refresh that may shrink the list.
    */
   protected clampSelection(): void {
-    const total = this.getItems().length;
+    const total = this.getVisibleItems().length;
     if (total === 0) {
       this.selectedIndex = 0;
     } else {
@@ -253,6 +348,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     options: {
       readonly header?: readonly Line[];
       readonly footer?: readonly Line[];
+      readonly hints?: ReadonlyArray<{ keys: string; label: string }>;
       readonly emptyMessage?: string;
       readonly title?: string;
       readonly spinnerFrame?: number;
@@ -260,19 +356,32 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
   ): Line[] {
     this.needsRender = false;
     const palette = this.getPalette();
-    const items = this.getItems();
+    const items = this.getVisibleItems();
     const title = options.title ?? this.name;
 
+    // Auto-inject the filter input line at the top of the header when filtering
+    // is enabled, so every filterable panel gets the same affordance for free.
+    const baseHeader = options.header ? [...options.header as Line[]] : [];
+    const header: Line[] | undefined = this.filterEnabled
+      ? [this.buildFilterLine(width), ...baseHeader]
+      : (options.header ? baseHeader : undefined);
+
+    // Standardized keyboard-hints footer row (rendered below any explicit footer).
+    const hintsLine = options.hints && options.hints.length > 0
+      ? buildKeyboardHints(width, options.hints, palette)
+      : null;
+
     // I2: inject error line into footer when present
     const errorLine = this.renderErrorLine(width);
     const baseFooter = options.footer ? [...options.footer as Line[]] : [];
+    if (hintsLine) baseFooter.push(hintsLine);
     const effectiveFooter: Line[] = errorLine ? [errorLine, ...baseFooter] : baseFooter;
 
     // I3: if loading, show spinner in place of normal content
     const spinnerLine = this.renderLoadingLine(width, options.spinnerFrame ?? 0);
     if (spinnerLine) {
       const loadingSection = { lines: [spinnerLine] };
-      const headerSection = options.header ? [{ lines: options.header as Line[] }] : [];
+      const headerSection = header ? [{ lines: header }] : [];
       const lines = buildPanelWorkspace(width, height, {
         title,
         sections: [...headerSection, loadingSection],
@@ -306,17 +415,22 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
 
     // Empty state
     if (scrollableLines.length === 0) {
+      // Distinguish "filter hides everything" from "genuinely empty".
+      const filteredToEmpty = this.filterEnabled && this.filterQuery.trim() !== '' && this.getItems().length > 0;
+      const emptyMessage = filteredToEmpty
+        ? ` No matches for "${this.filterQuery.trim()}"`
+        : (options.emptyMessage ?? this.getEmptyStateMessage());
       const emptyLines = buildEmptyState(
         width,
-        options.emptyMessage ?? this.getEmptyStateMessage(),
-        '',
-        this.getEmptyStateActions(),
+        emptyMessage,
+        filteredToEmpty ? 'Press Esc to clear the filter.' : '',
+        filteredToEmpty ? [] : this.getEmptyStateActions(),
         palette,
       );
       const lines = buildPanelWorkspace(width, height, {
         title,
         sections: [
-          ...(options.header ? [{ lines: options.header as Line[] }] : []),
+          ...(header ? [{ lines: header }] : []),
           { lines: emptyLines },
           ...(effectiveFooter.length > 0 ? [{ lines: effectiveFooter }] : []),
         ],
@@ -327,7 +441,7 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     }
 
     // Resolve scrollable section (updates scrollStart)
-    const beforeSections = options.header ? [{ lines: options.header as Line[] }] : [];
+    const beforeSections = header ? [{ lines: header }] : [];
     const afterSections = effectiveFooter.length > 0 ? [{ lines: effectiveFooter }] : [];
 
     const resolved = resolveScrollablePanelSection(width, height, {