@pellux/goodvibes-tui 0.28.0 → 1.0.0

package/src/panels/routes-panel.ts

@@ -1,12 +1,13 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine } from '../types/grid.ts';
 import { ScrollableListPanel } from './scrollable-list-panel.ts';
+import type { PanelIntegrationContext } from './types.ts';
+import { SessionBrowserPanel } from './session-browser-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,
@@ -16,16 +17,9 @@ import {
   type PanelPalette,
 } from './polish.ts';
 
-const C = {
-  ...DEFAULT_PANEL_PALETTE,
-  header: '#94a3b8',
-  headerBg: '#1e293b',
-  ok: '#22c55e',
-  warn: '#eab308',
-  error: '#ef4444',
-  info: '#38bdf8',
-  selectBg: '#0f172a',
-} as const;
+// Base chrome only — title band, state colors, and text tokens all come
+// straight from DEFAULT_PANEL_PALETTE (WO-002).
+const C = DEFAULT_PANEL_PALETTE;
 
 function formatTime(value?: number): string {
   if (!value) return 'n/a';
@@ -34,12 +28,20 @@ function formatTime(value?: number): string {
 
 type RouteBinding = UiRoutesSnapshot['bindings'][number];
 
+// Set by handleInput (enter/c) and consumed on the very next
+// handlePanelIntegrationAction dispatch of that same key — handleInput has
+// no access to the panelManager.
+type PendingRouteAction =
+  | { readonly kind: 'open-session'; readonly sessionId: string }
+  | { readonly kind: 'open-communication' };
+
 export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
   private readonly readModel?: UiReadModel<UiRoutesSnapshot>;
   private readonly unsub: (() => void) | null;
+  private pendingAction: PendingRouteAction | null = null;
 
   public constructor(readModel?: UiReadModel<UiRoutesSnapshot>) {
-    super('routes', 'Routes', 'R', 'monitoring');
+    super('routes', 'Routes', 'R', 'runtime-ops');
     this.showSelectionGutter = true; // I5: non-color selection affordance
     this.filterEnabled = true;
     this.filterLabel = 'Filter routes';
@@ -47,6 +49,42 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }
 
+  public override handleInput(key: string): boolean {
+    if (!this.filterActive) {
+      // Enter jumps to the session browser focused on this binding's session
+      // — a direct panel jump instead of a printed slash-command signpost.
+      if (key === 'enter' || key === 'return') {
+        const selected = this.getSelectedItem();
+        if (selected?.sessionId) {
+          this.pendingAction = { kind: 'open-session', sessionId: selected.sessionId };
+          return true;
+        }
+        return false;
+      }
+      // c opens the communication panel to inspect routed message flow.
+      if (key === 'c') {
+        this.pendingAction = { kind: 'open-communication' };
+        return true;
+      }
+    }
+    return super.handleInput(key);
+  }
+
+  public handlePanelIntegrationAction(_key: string, ctx: PanelIntegrationContext): boolean {
+    if (!this.pendingAction) return false;
+    const action = this.pendingAction;
+    this.pendingAction = null;
+    if (action.kind === 'open-communication') {
+      ctx.panelManager.open('communication');
+      return true;
+    }
+    const panel = ctx.panelManager.open('sessions');
+    if (panel instanceof SessionBrowserPanel) {
+      panel.focusSession(action.sessionId);
+    }
+    return true;
+  }
+
   protected override filterMatches(binding: RouteBinding, q: string): boolean {
     return binding.surfaceKind.toLowerCase().includes(q)
       || (binding.title ?? '').toLowerCase().includes(q)
@@ -121,11 +159,10 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
     const headerLines: Line[] = [
       buildKeyValueLine(width, [
         { label: 'bindings', value: String(snapshot.totalBindings), valueColor: snapshot.totalBindings > 0 ? C.info : C.dim },
-        { label: 'active', value: String(snapshot.activeBindingIds.length), valueColor: snapshot.activeBindingIds.length > 0 ? C.ok : C.dim },
-        { label: 'resolved', value: String(snapshot.totalResolved), valueColor: snapshot.totalResolved > 0 ? C.ok : C.dim },
-        { label: 'failures', value: String(snapshot.totalFailures), valueColor: snapshot.totalFailures > 0 ? C.error : C.dim },
+        { label: 'active', value: String(snapshot.activeBindingIds.length), valueColor: snapshot.activeBindingIds.length > 0 ? C.good : C.dim },
+        { label: 'resolved', value: String(snapshot.totalResolved), valueColor: snapshot.totalResolved > 0 ? C.good : C.dim },
+        { label: 'failures', value: String(snapshot.totalFailures), valueColor: snapshot.totalFailures > 0 ? C.bad : C.dim },
       ], C),
-      buildGuidanceLine(width, '/communication', 'inspect routed message flow and delivery behavior across bound surfaces', C),
     ];
 
     if (bindings.length === 0) {
@@ -137,9 +174,12 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
     }
 
     this.clampSelection();
-    const selected = bindings[this.selectedIndex]!;
+    // Detail must describe the row the (possibly filtered) list highlights —
+    // getItems() would desync under an applied filter, and a filter that
+    // matches nothing leaves no selection at all.
+    const selected = this.getSelectedItem();
 
-    const detailRows: Line[] = [
+    const detailRows: Line[] = selected ? [
       buildPanelLine(width, [
         ['  Binding: ', C.label],
         [selected.id, C.value],
@@ -168,9 +208,9 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
         ['  Last seen: ', C.label],
         [formatTime(selected.lastSeenAt), C.dim],
       ]),
-    ];
+    ] : [];
 
-    if (surfaceEntries.length > 0) {
+    if (selected && surfaceEntries.length > 0) {
       detailRows.push(
         ...surfaceEntries.slice(0, 4).map(([surface, ids]) => buildPanelLine(width, [
           [' ', C.label],
@@ -184,7 +224,8 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
       ? [{ keys: 'type', label: 'filter' }, { keys: 'Enter', label: 'apply' }, { keys: 'Esc', label: 'clear' }]
       : [
           { keys: 'Up/Down', label: 'move' },
-          { keys: '/communication', label: 'inspect flow' },
+          ...(selected?.sessionId ? [{ keys: 'Enter', label: 'open session' }] : []),
+          { keys: 'c', label: 'communication' },
           { keys: '/', label: 'filter' },
         ];
 
@@ -192,7 +233,7 @@ export class RoutesPanel extends ScrollableListPanel<RouteBinding> {
       title: 'Route Bindings',
       header: headerLines,
       footer: [
-        ...buildDetailBlock(width, `Binding · ${selected.surfaceKind}`, detailRows, C),
+        ...(selected ? buildDetailBlock(width, `Binding · ${selected.surfaceKind}`, detailRows, C) : []),
         buildKeyboardHints(width, hints, C),
       ],
     });

package/src/panels/sandbox-panel.ts

@@ -3,7 +3,9 @@ import { createEmptyLine } from '../types/grid.ts';
 import { BasePanel } from './base-panel.ts';
 import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import { buildSandboxReview, listSandboxPresets, listSandboxProfiles } from '@/runtime/index.ts';
-import type { SandboxSessionRegistry } from '@/runtime/index.ts';
+import type { SandboxProfile, SandboxReview, SandboxSession, SandboxSessionRegistry } from '@/runtime/index.ts';
+import { type ConfirmState, handleConfirmInput, renderConfirmLines } from './confirm-state.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import {
   buildAlignedRow,
   buildBodyText,
@@ -15,34 +17,137 @@ import {
   buildPanelWorkspace,
   resolveStackedScrollableSections,
   DEFAULT_PANEL_PALETTE,
+  type PanelPalette,
   type PanelWorkspaceSection,
 } from './polish.ts';
 
-const C = {
-  ...DEFAULT_PANEL_PALETTE,
-  header: '#e2e8f0',
-  headerBg: '#0f172a',
-} as const;
+// Base chrome only — title band comes straight from DEFAULT_PANEL_PALETTE
+// (WO-002).
+const C = DEFAULT_PANEL_PALETTE;
+
+/** Poll cadence for live session-state refresh; SandboxSessionRegistry has no event subscription. */
+const POLL_INTERVAL_MS = 3_000;
+
+type Selectable =
+  | { readonly kind: 'profile'; readonly id: SandboxProfile['id'] }
+  | { readonly kind: 'session'; readonly id: string };
+
+/**
+ * One contextual next-step line, derived from the current review/session
+ * state instead of the previous nine-line guidance wall. Picks the single
+ * most relevant action given host warnings, QEMU config gaps, and whether
+ * any session is running yet.
+ */
+function buildContextualGuidance(width: number, review: SandboxReview, sessionCount: number, palette: PanelPalette): Line {
+  if (review.host.warnings.length > 0) {
+    return buildGuidanceLine(width, '/sandbox review', `resolve ${review.host.warnings.length} host warning(s) before enabling QEMU-backed execution`, palette);
+  }
+  if (review.config.vmBackend === 'qemu' && !review.config.qemuImagePath) {
+    return buildGuidanceLine(width, '/sandbox set-qemu-image <path>', 'set the guest image path before enabling QEMU-backed session execution', palette);
+  }
+  if (review.config.vmBackend === 'qemu' && !review.config.qemuExecWrapper) {
+    return buildGuidanceLine(width, '/sandbox set-qemu-wrapper <path>', 'configure the host bridge that actually executes commands inside the QEMU guest', palette);
+  }
+  if (sessionCount === 0) {
+    return buildGuidanceLine(width, 's', 'select a profile below and press s to start a sandbox session', palette);
+  }
+  return buildGuidanceLine(width, '/sandbox session run <id> <command> [args...]', 'run a custom command against a running session from the command line', palette);
+}
+
+const SANDBOX_HINTS = [
+  { keys: '↑/↓', label: 'select' },
+  { keys: 'Home/End', label: 'first profile/session' },
+  { keys: 's', label: 'start' },
+  { keys: 'x', label: 'stop' },
+  { keys: 'e', label: 'execute probe' },
+] as const;
 
 export class SandboxPanel extends BasePanel {
   private selectedIndex = 0;
-  private scrollOffset = 0;
+
+  /**
+   * The profile/session row under the cursor. This panel owns its own
+   * selection state (`selectedIndex` navigates the combined `_selectable()`
+   * list directly), so every selected-row read routes through this one
+   * accessor — indexing the `_selectable()` list by the cursor directly is
+   * banned by the no-raw-selectedindex-read architecture rule.
+   */
+  private selectedSelectable(): Selectable | undefined {
+    return this._selectable().at(this.selectedIndex);
+  }
+
+  private sessionsScrollOffset = 0;
+  private profilesScrollOffset = 0;
+  private confirm: ConfirmState<string> | null = null;
   private readonly config: ConfigManager;
   private readonly sessions: SandboxSessionRegistry;
+  private readonly requestRender: () => void;
 
   public constructor(
     config: ConfigManager,
     sessions: SandboxSessionRegistry,
+    requestRender: () => void = () => {},
   ) {
-    super('sandbox', 'Sandbox', 'X', 'monitoring');
+    super('sandbox', 'Sandbox', '▪', 'security-policy');
     this.config = config;
     this.sessions = sessions;
+    this.requestRender = requestRender;
+    // Live state: SandboxSessionRegistry has no event subscription, so poll
+    // for session state changes (start/stop/execute results) while the
+    // panel is registered.
+    this.registerTimer(setInterval(() => {
+      this.markDirty();
+      this.requestRender();
+    }, POLL_INTERVAL_MS));
+  }
+
+  private _selectable(): Selectable[] {
+    const profiles = listSandboxProfiles(this.config);
+    const sessions = this.sessions.list();
+    return [
+      ...profiles.map((profile): Selectable => ({ kind: 'profile', id: profile.id })),
+      ...sessions.map((session): Selectable => ({ kind: 'session', id: session.id })),
+    ];
   }
 
   public handleInput(key: string): boolean {
-    const profileCount = listSandboxProfiles(this.config).length;
-    const sessionCount = this.sessions.list().length;
-    const itemCount = profileCount + sessionCount;
+    if (this.lastError !== null) this.clearError();
+
+    const confirmResult = handleConfirmInput(this.confirm, key);
+    if (confirmResult === 'confirmed') {
+      const sessionId = this.confirm!.subject;
+      this.confirm = null;
+      this.sessions.stop(sessionId);
+      this.markDirty();
+      return true;
+    }
+    if (confirmResult === 'cancelled') {
+      this.confirm = null;
+      this.markDirty();
+      return true;
+    }
+    if (confirmResult === 'absorbed') return true;
+
+    const selectable = this._selectable();
+    const profileCount = selectable.filter((entry) => entry.kind === 'profile').length;
+    const sessionCount = selectable.length - profileCount;
+    const selected = this.selectedSelectable();
+
+    if (key === 's' && selected?.kind === 'profile') {
+      void this._startSession(selected.id);
+      return true;
+    }
+    if (key === 'x' && selected?.kind === 'session') {
+      this.confirm = { subject: selected.id, label: `sandbox session ${selected.id}`, verb: 'Stop' };
+      this.markDirty();
+      return true;
+    }
+    if (key === 'e' && selected?.kind === 'session') {
+      void this._executeProbe(selected.id);
+      return true;
+    }
+
+    const itemCount = selectable.length;
     if (itemCount === 0) return false;
     if (key === 'up' || key === 'k') {
       this.selectedIndex = Math.max(0, this.selectedIndex - 1);
@@ -67,18 +172,57 @@ export class SandboxPanel extends BasePanel {
     return false;
   }
 
+  /** Start a sandbox session for `profileId` via the shared registry, then repaint. */
+  private async _startSession(profileId: SandboxProfile['id']): Promise<void> {
+    try {
+      await this.sessions.start(profileId, undefined, this.config);
+    } catch (err) {
+      this.setError(summarizeError(err));
+    } finally {
+      this.markDirty();
+      this.requestRender();
+    }
+  }
+
+  /**
+   * Execute a lightweight liveness probe against the selected session so its
+   * live state (last run, exit status, stdout/stderr preview) is genuinely
+   * populated from `SandboxSessionRegistry.execute()`. Panels have no
+   * free-text input widget today, so this proves the execute verb is wired
+   * without inventing one; `/sandbox session run <id> <command> [args...]`
+   * remains available for arbitrary commands.
+   */
+  private async _executeProbe(sessionId: string): Promise<void> {
+    try {
+      this.sessions.execute(sessionId, process.execPath, ['-e', "console.log('sandbox panel probe ok')"], this.config, { timeoutMs: 5_000 });
+    } catch (err) {
+      this.setError(summarizeError(err));
+    } finally {
+      this.markDirty();
+      this.requestRender();
+    }
+  }
+
   public render(width: number, height: number): Line[] {
     this.needsRender = false;
+
+    if (this.confirm) {
+      const lines = buildPanelWorkspace(width, height, {
+        title: 'Sandbox Control Room',
+        sections: [{ title: 'Confirmation', lines: renderConfirmLines(width, this.confirm) }],
+        palette: C,
+      });
+      while (lines.length < height) lines.push(createEmptyLine(width));
+      return lines.slice(0, height);
+    }
+
     const review = buildSandboxReview(this.config);
     const profiles = listSandboxProfiles(this.config);
     const presets = listSandboxPresets();
     const sessions = this.sessions.list();
-    const selectable = [
-      ...profiles.map((profile) => ({ kind: 'profile' as const, id: profile.id })),
-      ...sessions.map((session) => ({ kind: 'session' as const, id: session.id })),
-    ];
+    const selectable = this._selectable();
     this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, selectable.length - 1));
-    const selected = selectable[this.selectedIndex] ?? null;
+    const selected = this.selectedSelectable() ?? null;
     const selectedProfile = selected?.kind === 'profile'
       ? profiles.find((profile) => profile.id === selected.id) ?? null
       : null;
@@ -118,19 +262,9 @@ export class SandboxPanel extends BasePanel {
       buildKeyValueLine(width, [
         { label: 'guest workspace', value: review.config.qemuWorkspacePath || '(not configured)', valueColor: review.config.qemuWorkspacePath ? C.value : C.warn },
       ], C),
-      buildGuidanceLine(width, '/sandbox review', 'inspect local vs QEMU posture, host readiness, and isolation defaults', C),
-      buildGuidanceLine(width, '/sandbox set-qemu-image <path>', 'set the guest image path before enabling QEMU-backed session execution', C),
-      buildGuidanceLine(width, '/sandbox scaffold-qemu-wrapper <path>', 'generate a host-side wrapper scaffold with a bring-up bridge mode and a real guest handoff contract', C),
-      buildGuidanceLine(width, '/sandbox set-qemu-wrapper <path>', 'configure the host bridge that actually executes commands inside the QEMU guest', C),
-      buildGuidanceLine(width, '/sandbox set-qemu-guest-host <host>', 'switch wrapper-backed execution from host bridge mode to real guest SSH transport', C),
-      buildGuidanceLine(width, '/sandbox guest-test <profile>', 'verify SSH guest transport plus workspace projection against the configured QEMU guest host', C),
-      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),
-      buildKeyboardHints(width, [
-        { keys: '↑/↓', label: 'select profile/session' },
-        { keys: 'Home/End', label: 'jump to first profile / first session' },
-      ], C),
+      // Single contextual next-step line (replaces the former nine-line
+      // guidance wall) — the only buildGuidanceLine call in this panel.
+      buildContextualGuidance(width, review, sessions.length, C),
     ];
 
     const selectionLines: Line[] = [];
@@ -184,8 +318,8 @@ export class SandboxPanel extends BasePanel {
       sessionLines.push(...buildEmptyState(
         width,
         ' No active sandbox sessions.',
-        'Start a sandbox session from a profile to make the running VM/session posture visible here.',
-        [{ command: '/sandbox session start <profile>', summary: 'start a sandbox session and capture its VM/session record' }],
+        'Select a profile above and press s to start a sandbox session.',
+        [],
         C,
       ));
     } else {
@@ -261,10 +395,7 @@ export class SandboxPanel extends BasePanel {
     const presetsSection: PanelWorkspaceSection = { title: 'Presets', lines: presetLines };
     const [sessionsSection, profilesSection] = resolveStackedScrollableSections(width, height, {
       intro,
-      footerLines: [
-        buildGuidanceLine(width, '/sandbox presets', 'compare secure, balanced, and shared sandbox operating modes', C),
-        buildGuidanceLine(width, '/sandbox apply-preset <id>', 'change local vs QEMU isolation policy without editing config by hand', C),
-      ],
+      footerLines: [buildKeyboardHints(width, SANDBOX_HINTS, C)],
       palette: C,
       beforeSections: [
         postureSection,
@@ -275,7 +406,7 @@ export class SandboxPanel extends BasePanel {
           title: 'Sessions',
           scrollableLines: sessionLines,
           selectedIndex: selectedSession ? Math.max(0, sessions.findIndex((session) => session.id === selectedSession.id)) : undefined,
-          scrollOffset: this.scrollOffset,
+          scrollOffset: this.sessionsScrollOffset,
           minRows: 2,
           weight: 1,
           appendWindowSummary: sessions.length > 0 ? {
@@ -287,7 +418,7 @@ export class SandboxPanel extends BasePanel {
           title: 'Profiles',
           scrollableLines: profileLines,
           selectedIndex: selectedProfile ? Math.max(0, profiles.findIndex((profile) => profile.id === selectedProfile.id)) : undefined,
-          scrollOffset: this.scrollOffset,
+          scrollOffset: this.profilesScrollOffset,
           minRows: 2,
           weight: 1,
           appendWindowSummary: profiles.length > 0 ? {
@@ -298,7 +429,8 @@ export class SandboxPanel extends BasePanel {
       ],
       afterSections: [presetsSection],
     });
-    this.scrollOffset = sessionsSection?.scrollOffset ?? this.scrollOffset;
+    this.sessionsScrollOffset = sessionsSection?.scrollOffset ?? this.sessionsScrollOffset;
+    this.profilesScrollOffset = profilesSection?.scrollOffset ?? this.profilesScrollOffset;
 
     const sections: PanelWorkspaceSection[] = [
       postureSection,
@@ -308,14 +440,14 @@ export class SandboxPanel extends BasePanel {
       profilesSection?.section ?? { title: 'Profiles', lines: profileLines },
     ];
 
+    const errorLine = this.renderErrorLine(width);
+    if (errorLine) sections.push({ title: 'Error', lines: [errorLine] });
+
     const lines = buildPanelWorkspace(width, height, {
       title: 'Sandbox Control Room',
       intro,
       sections,
-      footerLines: [
-        buildGuidanceLine(width, '/sandbox presets', 'compare secure, balanced, and shared sandbox operating modes', C),
-        buildGuidanceLine(width, '/sandbox apply-preset <id>', 'change local vs QEMU isolation policy without editing config by hand', C),
-      ],
+      footerLines: [buildKeyboardHints(width, SANDBOX_HINTS, C)],
       palette: C,
     });
     while (lines.length < height) lines.push(createEmptyLine(width));

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

@@ -13,11 +13,6 @@ import {
   type PanelPalette,
 } from './polish.ts';
 import { GLYPHS } from '../renderer/ui-primitives.ts';
-import {
-  isPanelSearchBackspace,
-  isPanelSearchCancel,
-  isPanelSearchPrintable,
-} from './search-focus.ts';
 
 // ---------------------------------------------------------------------------
 // ScrollableListPanel<T>
@@ -87,6 +82,25 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     return all.filter((item) => this.filterMatches(item, q));
   }
 
+  /**
+   * The item currently under the cursor, resolved against the FILTERED list
+   * that navigation actually moves over (`getVisibleItems()`) — never the raw
+   * `getItems()` source.
+   *
+   * Subclasses MUST read the selected row through this method (or, when a
+   * function also needs the list for counts/windows, through a function-scope
+   * `const visible = this.getVisibleItems()` local — indexing that local, never
+   * the raw source). Indexing a raw item array (`this.rows`, `this.entries`,
+   * `getItems()`, …) with `this.selectedIndex` silently returns the wrong row
+   * whenever a filter is active, because `selectedIndex` is an offset into the
+   * visible list, not the raw one. The `no-raw-selectedindex-read` architecture
+   * rule enforces this by banning the `[this.selectedIndex]` token outside the
+   * base classes.
+   */
+  protected getSelectedItem(): T | undefined {
+    return this.getVisibleItems()[this.selectedIndex];
+  }
+
   /**
    * Filter-mode key handling. Returns `true`/`false` when consumed/ignored in
    * filter context, or `null` to fall through to normal navigation.
@@ -473,133 +487,3 @@ export abstract class ScrollableListPanel<T> extends BasePanel {
     return lines.slice(0, height);
   }
 }
-
-// ---------------------------------------------------------------------------
-// SearchableListPanel<T>
-// ---------------------------------------------------------------------------
-
-/**
- * Extends `ScrollableListPanel<T>` with inline search/filter support.
- *
- * Subclasses implement:
- *   - `getAllItems()` — the full (unfiltered) item list
- *   - `matchesSearch(item, query)` — case-insensitive filter predicate
- *
- * `getItems()` is implemented here and returns filtered results. Do NOT
- * override `getItems()` in subclasses — override `getAllItems()` instead.
- *
- * Search state:
- *   - Printable characters append to `searchQuery`.
- *   - Backspace/Delete removes the last character.
- *   - Escape clears the query.
- *   - Navigation keys (up/down/etc.) are forwarded to the parent.
- *
- * Render the search input line by calling `buildSearchInput(width)` from
- * your panel's header builder.
- */
-export abstract class SearchableListPanel<T> extends ScrollableListPanel<T> {
-  protected searchQuery = '';
-
-  private _filteredItems: readonly T[] = [];
-  private _filterDirty = true;
-
-  // -------------------------------------------------------------------------
-  // Abstract — subclasses must implement
-  // -------------------------------------------------------------------------
-
-  /** Return the full unfiltered item list. */
-  protected abstract getAllItems(): readonly T[];
-
-  /** Return true if `item` matches the search `query`. */
-  protected abstract matchesSearch(item: T, query: string): boolean;
-
-  // -------------------------------------------------------------------------
-  // getItems — returns filtered list (do NOT override in subclasses)
-  // -------------------------------------------------------------------------
-
-  protected getItems(): readonly T[] {
-    if (this._filterDirty) {
-      const all = this.getAllItems();
-      this._filteredItems = this.searchQuery
-        ? all.filter((item) => this.matchesSearch(item, this.searchQuery))
-        : all;
-      this._filterDirty = false;
-      // Clamp after filter to keep selection in bounds
-      this.clampSelection();
-    }
-    return this._filteredItems;
-  }
-
-  /**
-   * Mark the filter cache as stale.
-   * Call this whenever `getAllItems()` returns new data.
-   */
-  protected invalidateFilter(): void {
-    this._filterDirty = true;
-    this.needsRender = true;
-  }
-
-  // -------------------------------------------------------------------------
-  // Input — search first, navigation second
-  // -------------------------------------------------------------------------
-
-  handleInput(key: string): boolean {
-    // Backspace: trim query
-    if (isPanelSearchBackspace(key)) {
-      if (this.searchQuery.length > 0) {
-        this.searchQuery = this.searchQuery.slice(0, -1);
-        this._filterDirty = true;
-        this.needsRender = true;
-        return true;
-      }
-      return false;
-    }
-
-    // Escape: clear query
-    if (isPanelSearchCancel(key)) {
-      if (this.searchQuery.length > 0) {
-        this.searchQuery = '';
-        this._filterDirty = true;
-        this.needsRender = true;
-        return true;
-      }
-      return false;
-    }
-
-    // Printable characters: append to query
-    if (isPanelSearchPrintable(key)) {
-      this.searchQuery += key;
-      this._filterDirty = true;
-      this.needsRender = true;
-      return true;
-    }
-
-    // Navigation and Enter: delegate to parent
-    return super.handleInput(key);
-  }
-
-  /**
-   * Build the filter input `Line` for use in a panel header section.
-   *
-   * Renders the filter label and current query with context-sensitive formatting:
-   *
-   * - **Focused** (`focused = true`): `[Filter] query_`  — active, bold, cursor visible
-   * - **Unfocused** (`focused = false`): `Filter: query`  — dim, no cursor
-   *
-   * @param width   Panel width in columns.
-   * @param label   Label text (default: `'Filter'`).
-   * @param focused Whether the filter input is currently active.
-   */
-  protected buildFilterInputLine(width: number, label = 'Filter', focused: boolean): Line {
-    const palette = this.getPalette();
-    const formattedLabel = focused ? `[${label}] ` : `${label}: `;
-    const value = focused ? `${this.searchQuery}_` : this.searchQuery;
-    // Pass active:false when focused to prevent buildSearchInputLine from converting the
-    // trailing '_' cursor to the block-glyph (GLYPHS.surface.cursor). The focused visual
-    // affordance is provided by the '[Label] ' bracket format and explicit inputBg/info colors.
-    const opts = focused
-      ? { active: false, bg: palette.inputBg, valueColor: palette.info }
-      : { active: false };
-    return buildSearchInputLine(width, formattedLabel, value, palette, opts);
-  }
-}