@pellux/goodvibes-tui 0.18.13 → 0.18.18

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

@@ -0,0 +1,407 @@
+import type { Line } from '../types/grid.ts';
+import { createEmptyLine } from '../types/grid.ts';
+import { BasePanel } from './base-panel.ts';
+import type { PanelCategory } from './types.ts';
+import type { ComponentHealthMonitor } from '../runtime/perf/panel-health-monitor.ts';
+import {
+  buildEmptyState,
+  buildPanelWorkspace,
+  DEFAULT_PANEL_PALETTE,
+  resolveScrollablePanelSection,
+  type PanelPalette,
+} from './polish.ts';
+import {
+  isPanelSearchBackspace,
+  isPanelSearchCancel,
+  isPanelSearchPrintable,
+} from './search-focus.ts';
+
+// ---------------------------------------------------------------------------
+// ScrollableListPanel<T>
+// ---------------------------------------------------------------------------
+
+/**
+ * Base class for all list-based panels that require scroll/cursor navigation.
+ *
+ * Subclasses implement:
+ *   - `getItems()` — the ordered list of items to display
+ *   - `renderItem(item, index, selected, width)` — one `Line` per item
+ *
+ * Optionally override:
+ *   - `getEmptyStateMessage()` / `getEmptyStateActions()` — empty-state copy
+ *   - `onSelect(item)` — called when the user presses Enter
+ *   - `onAction(item, action)` — for secondary key bindings
+ *   - `getPalette()` — colour palette (defaults to `DEFAULT_PANEL_PALETTE`)
+ *   - `getPageSize()` — rows per page-up/page-down (default 10)
+ *
+ * `renderList()` produces the full `Line[]` output that a trivial panel's
+ * `render()` can return directly:
+ *
+ * ```ts
+ * render(width: number, height: number): Line[] {
+ *   return this.renderList(width, height, { header: this.buildHeader(width) });
+ * }
+ * ```
+ */
+export abstract class ScrollableListPanel<T> extends BasePanel {
+  protected selectedIndex = 0;
+  /** Tracks the first visible row index; kept in sync with resolveScrollablePanelSection. */
+  protected scrollStart = 0;
+
+  constructor(
+    id: string,
+    name: string,
+    icon: string,
+    category: PanelCategory,
+    componentHealthMonitor?: ComponentHealthMonitor,
+  ) {
+    super(id, name, icon, category, componentHealthMonitor);
+  }
+
+  // -------------------------------------------------------------------------
+  // Abstract — subclasses must implement
+  // -------------------------------------------------------------------------
+
+  /** Return the full ordered list of items to display. */
+  protected abstract getItems(): readonly T[];
+
+  /** Render a single item as one terminal `Line`. */
+  protected abstract renderItem(
+    item: T,
+    index: number,
+    selected: boolean,
+    width: number,
+  ): Line;
+
+  // -------------------------------------------------------------------------
+  // Optional overrides
+  // -------------------------------------------------------------------------
+
+  /** Short label shown in the empty-state title. */
+  protected getEmptyStateMessage(): string {
+    return 'No items';
+  }
+
+  /** Suggested actions shown in the empty state. */
+  protected getEmptyStateActions(): Array<{ command: string; summary: string }> {
+    return [];
+  }
+
+  /** Called when the user presses Enter on the selected item. */
+  protected onSelect(_item: T): void {}
+
+  /** Called for secondary key bindings (e.g. 'd' for delete). */
+  protected onAction(_item: T, _action: string): void {}
+
+  /** Colour palette used by `renderList()`. */
+  protected getPalette(): PanelPalette {
+    return DEFAULT_PANEL_PALETTE;
+  }
+
+  /**
+   * Rows to jump on pageup / pagedown.
+   * Override in `render()` to pass the actual visible row count:
+   *
+   * ```ts
+   * this._pageSize = Math.max(1, visibleRows - 2);
+   * ```
+   */
+  protected getPageSize(): number {
+    return 10;
+  }
+
+  // -------------------------------------------------------------------------
+  // Navigation — consistent across ALL panels
+  // -------------------------------------------------------------------------
+
+  handleInput(key: string): boolean {
+    const items = this.getItems();
+    const total = items.length;
+
+    switch (key) {
+      case 'up':
+      case 'k':
+        if (total === 0) return false;
+        this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+        this.needsRender = true;
+        return true;
+
+      case 'down':
+      case 'j':
+        if (total === 0) return false;
+        this.selectedIndex = Math.min(total - 1, this.selectedIndex + 1);
+        this.needsRender = true;
+        return true;
+
+      case 'pageup':
+        if (total === 0) return false;
+        this.selectedIndex = Math.max(0, this.selectedIndex - this.getPageSize());
+        this.needsRender = true;
+        return true;
+
+      case 'pagedown':
+        if (total === 0) return false;
+        this.selectedIndex = Math.min(total - 1, this.selectedIndex + this.getPageSize());
+        this.needsRender = true;
+        return true;
+
+      case 'home':
+      case 'g':
+        if (total === 0) return false;
+        this.selectedIndex = 0;
+        this.needsRender = true;
+        return true;
+
+      case 'end':
+      case 'G':
+        if (total === 0) return false;
+        this.selectedIndex = total - 1;
+        this.needsRender = true;
+        return true;
+
+      case 'return':
+      case 'enter': {
+        if (total === 0) return false;
+        const item = items[this.selectedIndex];
+        if (item !== undefined) this.onSelect(item);
+        return true;
+      }
+
+      default:
+        return false;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Scroll state helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Clamp `selectedIndex` to the current item count.
+   * Must be called after any data refresh that may shrink the list.
+   */
+  protected clampSelection(): void {
+    const total = this.getItems().length;
+    if (total === 0) {
+      this.selectedIndex = 0;
+    } else {
+      this.selectedIndex = Math.min(this.selectedIndex, total - 1);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Render helper — the main convenience entry point
+  // -------------------------------------------------------------------------
+
+  /**
+   * Render the full panel including optional header/footer and an empty state.
+   *
+   * Uses `resolveScrollablePanelSection` + `buildPanelWorkspace` internally,
+   * keeping `scrollStart` in sync after each call.
+   *
+   * @param width  Panel width in columns.
+   * @param height Panel height in rows.
+   * @param options.header  Lines prepended as the first workspace section.
+   * @param options.footer  Lines appended as the last workspace section.
+   * @param options.emptyMessage  Override for the empty-state title text.
+   * @param options.title  Workspace title (defaults to `this.name`).
+   */
+  protected renderList(
+    width: number,
+    height: number,
+    options: {
+      readonly header?: readonly Line[];
+      readonly footer?: readonly Line[];
+      readonly emptyMessage?: string;
+      readonly title?: string;
+    } = {},
+  ): Line[] {
+    this.needsRender = false;
+    const palette = this.getPalette();
+    const items = this.getItems();
+    const title = options.title ?? this.name;
+
+    // Build all item lines (pre-render for resolveScrollablePanelSection)
+    const scrollableLines: Line[] = items.map((item, index) =>
+      this.renderItem(item, index, index === this.selectedIndex, width),
+    );
+
+    // Empty state
+    if (scrollableLines.length === 0) {
+      const emptyLines = buildEmptyState(
+        width,
+        options.emptyMessage ?? this.getEmptyStateMessage(),
+        '',
+        this.getEmptyStateActions(),
+        palette,
+      );
+      const lines = buildPanelWorkspace(width, height, {
+        title,
+        sections: [
+          ...(options.header ? [{ lines: options.header as Line[] }] : []),
+          { lines: emptyLines },
+          ...(options.footer ? [{ lines: options.footer as Line[] }] : []),
+        ],
+        palette,
+      });
+      while (lines.length < height) lines.push(createEmptyLine(width));
+      return lines.slice(0, height);
+    }
+
+    // Resolve scrollable section (updates scrollStart)
+    const beforeSections = options.header ? [{ lines: options.header as Line[] }] : [];
+    const afterSections = options.footer ? [{ lines: options.footer as Line[] }] : [];
+
+    const resolved = resolveScrollablePanelSection(width, height, {
+      palette,
+      beforeSections,
+      afterSections,
+      section: {
+        scrollableLines,
+        selectedIndex: this.selectedIndex,
+        scrollOffset: this.scrollStart,
+        guardRows: 1,
+        appendWindowSummary: scrollableLines.length > 5 ? { dimColor: palette.dim } : undefined,
+      },
+    });
+    this.scrollStart = resolved.scrollOffset;
+
+    const sections = [
+      ...beforeSections,
+      resolved.section,
+      ...afterSections,
+    ];
+
+    const lines = buildPanelWorkspace(width, height, {
+      title,
+      sections,
+      palette,
+    });
+    while (lines.length < height) lines.push(createEmptyLine(width));
+    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 search input `Line` suitable for use in a panel header.
+   *
+   * Import `buildSearchInputLine` from `./polish.ts` and call it with
+   * `this.searchQuery`. Convenience wrapper:
+   *
+   * ```ts
+   * import { buildSearchInputLine } from './polish.ts';
+   *
+   * private buildHeader(width: number): Line[] {
+   *   return [buildSearchInputLine(width, 'Filter', this.searchQuery, this.getPalette(), {})];
+   * }
+   * ```
+   *
+   * This method is intentionally left as a documentation reference rather
+   * than a concrete implementation to avoid coupling the base class to a
+   * specific label or search-input layout.
+   */
+}

package/src/panels/services-panel.ts

@@ -5,7 +5,7 @@ import {
   type ServiceConfig,
   type ServiceInspection,
   type ServiceConnectionTestResult,
-} from '../config/service-registry.ts';
+} from '@pellux/goodvibes-sdk/platform/config/service-registry';
 import type { ServiceInspectionQuery, SubscriptionAccessQuery } from '../runtime/ui-service-queries.ts';
 import {
   buildEmptyState,

package/src/panels/subscription-panel.ts

@@ -2,7 +2,7 @@ import type { Line } from '../types/grid.ts';
 import { createEmptyLine } from '../types/grid.ts';
 import { BasePanel } from './base-panel.ts';
 import type { ProviderSubscription, PendingSubscriptionLogin } from '@pellux/goodvibes-sdk/platform/config/subscriptions';
-import { listBuiltinSubscriptionProviders } from '../config/subscription-providers.ts';
+import { listBuiltinSubscriptionProviders } from '@pellux/goodvibes-sdk/platform/config/subscription-providers';
 import type { ServiceInspectionQuery, SubscriptionAccessQuery } from '../runtime/ui-service-queries.ts';
 import {
   buildDetailBlock,

package/src/panels/types.ts

@@ -22,6 +22,12 @@ export interface Panel {
   isPinned: boolean;
   needsRender: boolean;
 
+  // Dirty-flag contract (R2: activated panel render skipping)
+  /** Mark this panel as needing a re-render on the next frame. */
+  invalidate(): void;
+  /** Called by the compositor after a successful render to clear the dirty flag. */
+  markRendered(): void;
+
   // Resource contract (optional — panels may declare resource requirements)
   resourceContract?: Readonly<ComponentResourceContract>;
 

package/src/panels/worktree-panel.ts

@@ -1,6 +1,6 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine } from '../types/grid.ts';
-import { BasePanel } from './base-panel.ts';
+import { ScrollableListPanel } from './scrollable-list-panel.ts';
 import { buildKeyValueLine, buildPanelLine, buildPanelWorkspace, DEFAULT_PANEL_PALETTE, resolvePrimaryScrollableSection, type PanelWorkspaceSection } from './polish.ts';
 import { summarizeWorktreeOwnership, type WorktreeRegistry, type WorktreeStatusRecord } from '@pellux/goodvibes-sdk/platform/runtime/worktree/registry';
 
@@ -22,10 +22,8 @@ function stateColor(state: WorktreeStatusRecord['state']): string {
   }
 }
 
-export class WorktreePanel extends BasePanel {
+export class WorktreePanel extends ScrollableListPanel<WorktreeStatusRecord> {
   private rows: WorktreeStatusRecord[] = [];
-  private selectedIndex = 0;
-  private scrollOffset = 0;
   private loading = false;
   private readonly worktreeRegistry: WorktreeRegistry;
 
@@ -45,18 +43,21 @@ export class WorktreePanel extends BasePanel {
       void this.refresh();
       return true;
     }
-    if (this.rows.length === 0) return false;
-    if (key === 'up' || key === 'k') {
-      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
-      this.markDirty();
-      return true;
-    }
-    if (key === 'down' || key === 'j') {
-      this.selectedIndex = Math.min(this.rows.length - 1, this.selectedIndex + 1);
-      this.markDirty();
-      return true;
-    }
-    return false;
+    return super.handleInput(key);
+  }
+
+  protected getItems(): readonly WorktreeStatusRecord[] {
+    return this.rows;
+  }
+
+  protected renderItem(row: WorktreeStatusRecord, index: number, _selected: boolean, width: number): Line {
+    const bg = index === this.selectedIndex ? C.headerBg : undefined;
+    return buildPanelLine(width, [
+      [` ${row.kind}`.padEnd(14), C.info, bg],
+      [` ${row.state}`.padEnd(16), stateColor(row.state), bg],
+      [` ${row.branch}`.padEnd(24), C.value, bg],
+      [` ${row.path}`.slice(0, Math.max(0, width - 56)), C.dim, bg],
+    ]);
   }
 
   private async refresh(): Promise<void> {
@@ -64,7 +65,7 @@ export class WorktreePanel extends BasePanel {
     this.markDirty();
     try {
       this.rows = await this.worktreeRegistry.list();
-      this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, this.rows.length - 1));
+      this.clampSelection();
     } finally {
       this.loading = false;
       this.markDirty();
@@ -155,14 +156,14 @@ export class WorktreePanel extends BasePanel {
             ]);
           }),
           selectedIndex: this.selectedIndex,
-          scrollOffset: this.scrollOffset,
+          scrollOffset: this.scrollStart,
           guardRows: 1,
           minRows: 4,
           appendWindowSummary: { dimColor: C.dim },
         },
         afterSections: [detailSection],
       });
-      this.scrollOffset = resolvedWorktreesSection.scrollOffset;
+      this.scrollStart = resolvedWorktreesSection.scrollOffset;
       sections.push(resolvedWorktreesSection.section);
       sections.push(detailSection);
     }

package/src/renderer/buffer.ts

@@ -31,4 +31,23 @@ export class TerminalBuffer {
     newBuf.cells = this.cells.map(line => line.map(cell => ({ ...cell })));
     return newBuf;
   }
+
+  /**
+   * Reset all cells in-place to empty, reusing this buffer instance.
+   * If dimensions changed, reallocates cells array.
+   */
+  public reset(width: number, height: number): void {
+    if (width !== this.width || height !== this.height) {
+      this.width = width;
+      this.height = height;
+      this.cells = Array.from({ length: height }, () => createEmptyLine(width));
+    } else {
+      for (let y = 0; y < this.height; y++) {
+        const row = this.cells[y]!;
+        for (let x = 0; x < this.width; x++) {
+          row[x] = createEmptyCell();
+        }
+      }
+    }
+  }
 }

package/src/renderer/compositor.ts

@@ -54,24 +54,33 @@ export interface CompositeRequest {
  * Decoupled from global state — all needed data is passed as parameters.
  */
 export class Compositor {
-  private lastBuffer: TerminalBuffer | null = null;
+  /** Double-buffer reuse: back is written, front is the last-rendered reference. */
+  private frontBuffer: TerminalBuffer | null = null;
+  private backBuffer: TerminalBuffer | null = null;
   private diffEngine = new DiffEngine();
 
   constructor(private stdout: NodeJS.WriteStream) {}
 
   /** Exposed for unit tests — returns the last composited buffer. */
   public get lastBufferForTest(): TerminalBuffer | null {
-    return this.lastBuffer;
+    return this.frontBuffer;
   }
 
   public resetDiff(): void {
     this.diffEngine.reset();
-    this.lastBuffer = null;
+    this.frontBuffer = null;
+    this.backBuffer = null;
   }
 
   public composite(params: CompositeRequest): void {
     const { width, height, header, viewport, footer, selection, search, panel, panelWidth } = params;
-    const newBuffer = new TerminalBuffer(width, height);
+    // R3: Reuse back-buffer instead of allocating each frame
+    if (!this.backBuffer) {
+      this.backBuffer = new TerminalBuffer(width, height);
+    } else {
+      this.backBuffer.reset(width, height);
+    }
+    const newBuffer = this.backBuffer;
 
     const hasPanel = panel !== undefined && panelWidth !== undefined && panelWidth > 0;
     const leftWidth = hasPanel ? Math.max(1, width - panelWidth - 1) : width;
@@ -251,11 +260,15 @@ export class Compositor {
     });
 
     // 4. Diff and Render
-    const diff = this.diffEngine.diff(this.lastBuffer, newBuffer);
+    // R3: Diff against front-buffer (last-rendered), then swap front/back — no clone() needed
+    const diff = this.diffEngine.diff(this.frontBuffer, newBuffer);
     if (diff) {
       this.stdout.write(diff);
     }
 
-    this.lastBuffer = newBuffer.clone();
+    // Swap: back (just written) becomes the new front reference; old front becomes the next back
+    const swap = this.frontBuffer;
+    this.frontBuffer = this.backBuffer;
+    this.backBuffer = swap;
   }
 }

package/src/renderer/panel-composite.ts

@@ -1,4 +1,5 @@
 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';
@@ -6,6 +7,26 @@ 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. */
+interface PanelRenderCache {
+  lines: Line[];
+  width: number;
+  height: number;
+}
+const panelRenderCache = new WeakMap<Panel, PanelRenderCache>();
+
+/** R2: Render a panel, skipping if nothing changed. Returns cached lines on a skip. */
+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;
+  }
+  const lines = panel.render(width, height);
+  panel.markRendered();
+  panelRenderCache.set(panel, { lines, width, height });
+  return lines;
+}
+
 export interface PanelCompositeBuildResult {
   readonly panelData?: PanelCompositeData;
   readonly panelWidth?: number;
@@ -47,7 +68,7 @@ export function buildPanelCompositeData(
     const paneLayout = createSplitPaneLayout(Math.max(0, panelHeight - 1), verticalSplitRatio);
     const topH = paneLayout.topContentRows;
     const bottomH = paneLayout.bottomContentRows;
-    topContent = topActivePanel ? topActivePanel.render(panelWidth, topH) : [];
+    topContent = topActivePanel ? renderPanel(topActivePanel, panelWidth, topH) : [];
 
     const bottomActivePanel = bottomPane.panels[bottomPane.activeIndex] ?? null;
     bottomTabBar = renderPanelTabBar(
@@ -57,10 +78,10 @@ export function buildPanelCompositeData(
       input.panelFocused && focusedPane === 'bottom',
       'bottom',
     );
-    bottomContent = bottomActivePanel ? bottomActivePanel.render(panelWidth, bottomH) : [];
+    bottomContent = bottomActivePanel ? renderPanel(bottomActivePanel, panelWidth, bottomH) : [];
   } else {
     const topH = Math.max(0, panelHeight - 1);
-    topContent = topActivePanel ? topActivePanel.render(panelWidth, topH) : [];
+    topContent = topActivePanel ? renderPanel(topActivePanel, panelWidth, topH) : [];
   }
 
   return {