@pellux/goodvibes-tui 0.18.20 → 0.19.0

package/src/panels/base-panel.ts

@@ -11,14 +11,54 @@ export abstract class BasePanel implements Panel {
   public isPinned = false;
   protected readonly componentHealthMonitor?: ComponentHealthMonitor;
 
+  // -------------------------------------------------------------------------
+  // Timer registry
+  // -------------------------------------------------------------------------
+
+  /** All timers registered via registerTimer(). Cleared automatically on onDestroy(). */
+  private readonly _timers: Set<ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>> = new Set();
+
+  /**
+   * Register a timer id (from setInterval or setTimeout) so it is
+   * automatically cleared when the panel is destroyed. Returns the id
+   * unchanged so the call can be chained inline:
+   *
+   * ```ts
+   * this.registerTimer(setInterval(() => this.refresh(), 5_000));
+   * ```
+   */
+  protected registerTimer<T extends ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>>(id: T): T {
+    this._timers.add(id);
+    return id;
+  }
+
+  /**
+   * Clear a specific timer and remove it from the registry.
+   * Safe to call with an id that was never registered or already cleared.
+   */
+  protected clearTimer(id: ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>): void {
+    clearInterval(id as ReturnType<typeof setInterval>);
+    this._timers.delete(id);
+  }
+
   // -------------------------------------------------------------------------
   // I2: Error surface slot
   // -------------------------------------------------------------------------
 
-  /** Last error message to surface in the panel footer. Auto-cleared on next input. */
+  /**
+   * Last error message to surface in the panel footer.
+   * Auto-cleared on the next keystroke by `ScrollableListPanel.handleInput()` (and any
+   * subclass that calls `super.handleInput()` or manually calls `this.clearError()` at
+   * the start of its handler). BasePanel itself does NOT auto-clear — only subclasses
+   * that opt into the contract do.
+   */
   protected lastError: string | null = null;
 
-  /** Set a transient error message. Triggers a re-render. */
+  /**
+   * Set a transient error message. Triggers a re-render.
+   * The error will be auto-cleared on the next keystroke if the panel extends
+   * `ScrollableListPanel` (which calls `clearError()` at the top of `handleInput()`).
+   */
   protected setError(msg: string): void {
     this.lastError = msg;
     this.needsRender = true;
@@ -66,6 +106,32 @@ export abstract class BasePanel implements Panel {
     this.needsRender = true;
   }
 
+  /**
+   * Run an async operation with the panel's loading spinner visible.
+   * The spinner is always cleared on completion, whether the operation succeeds or throws
+   * (uses try/finally). Rethrows any error so callers can handle it or forward to setError.
+   *
+   * @param label Optional label shown next to the spinner.
+   * @param fn    The async work to run.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await this.withLoading('Loading diff…', () => this.fetchDiff());
+   * } catch (err) {
+   *   this.setError(summarizeError(err));
+   * }
+   * ```
+   */
+  protected async withLoading<T>(label: string | undefined, fn: () => Promise<T>): Promise<T> {
+    this.startLoading(label);
+    try {
+      return await fn();
+    } finally {
+      this.stopLoading();
+    }
+  }
+
   /**
    * Build a spinner Line for the loading state.
    * Returns null when loadingState is not 'loading'.
@@ -107,7 +173,17 @@ export abstract class BasePanel implements Panel {
 
   onActivate(): void { this.needsRender = true; }
   onDeactivate(): void {}
-  onDestroy(): void {}
+
+  /**
+   * Called when the panel is permanently removed. Subclasses should call
+   * `super.onDestroy()` to ensure all registered timers are cleared.
+   */
+  onDestroy(): void {
+    for (const id of this._timers) {
+      clearInterval(id as ReturnType<typeof setInterval>);
+    }
+    this._timers.clear();
+  }
 
   abstract render(width: number, height: number): Line[];
 
@@ -146,4 +222,33 @@ export abstract class BasePanel implements Panel {
   protected reportRenderDuration(durationMs: number, now: number = Date.now()): void {
     this.componentHealthMonitor?.recordRender(this.id, durationMs, now);
   }
+
+  /** Cache of the most recent lines produced by trackedRender. */
+  private _lastTrackedLines: Line[] = [];
+
+  /**
+   * Wrap a render body with canRenderNow throttle check, wall-clock timing,
+   * and automatic reportRenderDuration.
+   *
+   * When throttled, returns the previously cached lines (stale but correctly
+   * sized) rather than empty lines, avoiding a flicker on every skipped frame.
+   *
+   * Usage:
+   * ```ts
+   * render(width: number, height: number): Line[] {
+   *   return this.trackedRender(() => {
+   *     // expensive render logic
+   *     return lines;
+   *   });
+   * }
+   * ```
+   */
+  protected trackedRender(fn: () => Line[]): Line[] {
+    if (!this.canRenderNow()) return this._lastTrackedLines;
+    const start = Date.now();
+    const lines = fn();
+    this.reportRenderDuration(Date.now() - start);
+    this._lastTrackedLines = lines;
+    return lines;
+  }
 }

package/src/panels/communication-panel.ts

@@ -1,6 +1,5 @@
 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 type { UiCommunicationSnapshot, UiReadModel } from '../runtime/ui-read-models.ts';
 import { truncateDisplay } from '../utils/terminal-width.ts';
 import {
@@ -11,10 +10,9 @@ import {
   buildPanelLine,
   buildPanelWorkspace,
   DEFAULT_PANEL_PALETTE,
-  resolvePrimaryScrollableSection,
-  type PanelWorkspaceSection,
+  type PanelPalette,
 } from './polish.ts';
-import { getTrackedVisibleWindow } from '../renderer/surface-layout.ts';
+import { createEmptyLine } from '../types/grid.ts';
 
 const C = {
   ...DEFAULT_PANEL_PALETTE,
@@ -26,14 +24,15 @@ const C = {
   selectBg: '#0f172a',
 } as const;
 
-export class CommunicationPanel extends BasePanel {
+type CommunicationRecord = UiCommunicationSnapshot['records'][number];
+
+export class CommunicationPanel extends ScrollableListPanel<CommunicationRecord> {
   private readonly readModel?: UiReadModel<UiCommunicationSnapshot>;
   private readonly unsub: (() => void) | null;
-  private selectedIndex = 0;
-  private scrollOffset = 0;
 
   public constructor(readModel?: UiReadModel<UiCommunicationSnapshot>) {
     super('communication', 'Communication', 'Y', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.readModel = readModel;
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }
@@ -42,31 +41,40 @@ export class CommunicationPanel extends BasePanel {
     this.unsub?.();
   }
 
-  public handleInput(key: string): boolean {
-    const records = this.records();
-    if (records.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(records.length - 1, this.selectedIndex + 1);
-      this.markDirty();
-      return true;
-    }
-    return false;
+  protected override getPalette(): PanelPalette {
+    return C;
   }
 
-  private records() {
+  protected getItems(): readonly CommunicationRecord[] {
     if (!this.readModel) return [];
-    return [...this.readModel.getSnapshot().records];
+    return this.readModel.getSnapshot().records;
+  }
+
+  protected renderItem(record: CommunicationRecord, index: number, selected: boolean, width: number): Line {
+    const bg = selected ? C.selectBg : undefined;
+    const color = record.status === 'blocked' ? C.error : record.status === 'delivered' ? C.ok : C.info;
+    return buildPanelLine(width, [
+      [' ', C.label, bg],
+      [record.status.padEnd(10), color, bg],
+      [` ${record.kind.padEnd(10)}`, C.info, bg],
+      [` ${truncateDisplay(`${record.fromId} -> ${record.toId}`, 28).padEnd(28)}`, C.value, bg],
+      [` ${truncateDisplay(record.content, Math.max(0, width - 53))}`, C.dim, bg],
+    ]);
+  }
+
+  protected override getEmptyStateMessage(): string {
+    return ' No structured communication recorded yet.';
+  }
+
+  protected override getEmptyStateActions(): Array<{ command: string; summary: string }> {
+    return [
+      { command: '/orchestration', summary: 'review graphs and recursive agent activity' },
+      { command: '/communication', summary: 'reopen this workspace once the runtime emits message traffic' },
+    ];
   }
 
   public render(width: number, height: number): Line[] {
-    this.needsRender = false;
     const intro = 'Structured agent communication, routing policy outcomes, and delivery status across orchestration trees.';
-    const footerLines = [buildPanelLine(width, [['  Up/Down move through messages', C.dim]])];
 
     if (!this.readModel) {
       const workspace = buildPanelWorkspace(width, height, {
@@ -88,104 +96,58 @@ export class CommunicationPanel extends BasePanel {
     }
 
     const snapshot = this.readModel.getSnapshot();
-    const records = this.records();
+    const records = this.getItems();
+
+    const postureLines: Line[] = [
+      buildPanelLine(width, [['  Communication posture', C.label]]),
+      buildKeyValueLine(width, [
+        { label: 'sent', value: String(snapshot.totalSent), valueColor: snapshot.totalSent > 0 ? C.info : C.dim },
+        { label: 'delivered', value: String(snapshot.totalDelivered), valueColor: snapshot.totalDelivered > 0 ? C.ok : C.dim },
+        { label: 'blocked', value: String(snapshot.totalBlocked), valueColor: snapshot.totalBlocked > 0 ? C.error : C.dim },
+      ], C),
+      buildGuidanceLine(width, '/orchestration', 'inspect recursive routing, message handoff, and blocked broadcast posture', C),
+    ];
 
     if (records.length === 0) {
-      const workspace = buildPanelWorkspace(width, height, {
+      return this.renderList(width, height, {
         title: 'Communication Control Room',
-        intro,
-        sections: [{
-          title: 'Communication posture',
-          lines: [
-            buildKeyValueLine(width, [
-              { label: 'sent', value: String(snapshot.totalSent), valueColor: snapshot.totalSent > 0 ? C.info : C.dim },
-              { label: 'delivered', value: String(snapshot.totalDelivered), valueColor: snapshot.totalDelivered > 0 ? C.ok : C.dim },
-              { label: 'blocked', value: String(snapshot.totalBlocked), valueColor: snapshot.totalBlocked > 0 ? C.error : C.dim },
-            ], C),
-            buildGuidanceLine(width, '/communication', 'review structured message flow, delivery posture, and blocked routing decisions', C),
-            ...buildEmptyState(
-              width,
-              ' No structured communication recorded yet.',
-              'Messages, escalations, findings, and handoffs will appear here once orchestration starts routing them through the communication policy.',
-              [
-                { command: '/orchestration', summary: 'review graphs and recursive agent activity' },
-                { command: '/communication', summary: 'reopen this workspace once the runtime emits message traffic' },
-              ],
-              C,
-            ),
-          ],
-        }],
-        palette: C,
+        header: postureLines,
       });
-      while (workspace.length < height) workspace.push(createEmptyLine(width));
-      return workspace;
     }
 
-    this.selectedIndex = Math.min(this.selectedIndex, records.length - 1);
-    const postureLines: Line[] = [
+    this.clampSelection();
+    const selected = records[this.selectedIndex];
+
+    // Update posture with selected info
+    const postureWithSelected: Line[] = [
+      buildPanelLine(width, [['  Communication posture', C.label]]),
       buildKeyValueLine(width, [
         { label: 'sent', value: String(snapshot.totalSent), valueColor: snapshot.totalSent > 0 ? C.info : C.dim },
         { label: 'delivered', value: String(snapshot.totalDelivered), valueColor: snapshot.totalDelivered > 0 ? C.ok : C.dim },
         { label: 'blocked', value: String(snapshot.totalBlocked), valueColor: snapshot.totalBlocked > 0 ? C.error : C.dim },
-        { label: 'selected', value: `${records[this.selectedIndex]?.fromId ?? 'n/a'} -> ${records[this.selectedIndex]?.toId ?? 'n/a'}`, valueColor: C.value },
+        { label: 'selected', value: `${selected?.fromId ?? 'n/a'} -> ${selected?.toId ?? 'n/a'}`, valueColor: C.value },
       ], C),
       buildGuidanceLine(width, '/orchestration', 'inspect recursive routing, message handoff, and blocked broadcast posture', C),
     ];
 
-    const selected = records[this.selectedIndex]!;
-    const detailLines: Line[] = [
-      buildPanelLine(width, [['  Route: ', C.label], [`${selected.scope} / ${selected.kind}`, C.value], ['  Status: ', C.label], [selected.status, selected.status === 'blocked' ? C.error : C.ok]]),
-      buildPanelLine(width, [['  From: ', C.label], [selected.fromId, C.value], ['  To: ', C.label], [selected.toId, C.value]]),
-      buildPanelLine(width, [['  Roles: ', C.label], [`${selected.fromRole ?? 'unknown'} -> ${selected.toRole ?? 'unknown'}`, C.dim]]),
-    ];
-    if (selected.reason) {
-      detailLines.push(buildPanelLine(width, [['  Reason: ', C.label], [truncateDisplay(selected.reason, Math.max(0, width - 11)), C.warn]]));
+    const footerLines: Line[] = [];
+    if (selected) {
+      footerLines.push(
+        buildPanelLine(width, [['  Route: ', C.label], [`${selected.scope} / ${selected.kind}`, C.value], ['  Status: ', C.label], [selected.status, selected.status === 'blocked' ? C.error : C.ok]]),
+        buildPanelLine(width, [['  From: ', C.label], [selected.fromId, C.value], ['  To: ', C.label], [selected.toId, C.value]]),
+        buildPanelLine(width, [['  Roles: ', C.label], [`${selected.fromRole ?? 'unknown'} -> ${selected.toRole ?? 'unknown'}`, C.dim]]),
+      );
+      if (selected.reason) {
+        footerLines.push(buildPanelLine(width, [['  Reason: ', C.label], [truncateDisplay(selected.reason, Math.max(0, width - 11)), C.warn]]));
+      }
+      footerLines.push(...buildBodyText(width, ` Content: ${selected.content}`, C));
     }
-    detailLines.push(...buildBodyText(width, ` Content: ${selected.content}`, C));
-    const postureSection: PanelWorkspaceSection = { title: 'Communication posture', lines: postureLines };
-    const detailSection: PanelWorkspaceSection = { title: 'Selected Message', lines: detailLines };
-    const rawOverviewLines: Line[] = records.map((record, absolute) => {
-      const bg = absolute === this.selectedIndex ? C.selectBg : undefined;
-      const color = record.status === 'blocked' ? C.error : record.status === 'delivered' ? C.ok : C.info;
-      return buildPanelLine(width, [
-        [' ', C.label, bg],
-        [record.status.padEnd(10), color, bg],
-        [` ${record.kind.padEnd(10)}`, C.info, bg],
-        [` ${truncateDisplay(`${record.fromId} -> ${record.toId}`, 28).padEnd(28)}`, C.value, bg],
-        [` ${truncateDisplay(record.content, Math.max(0, width - 53))}`, C.dim, bg],
-      ]);
-    });
-    const resolvedMessagesSection = resolvePrimaryScrollableSection(width, height, {
-      intro,
-      footerLines,
-      palette: C,
-      beforeSections: [postureSection],
-      section: {
-        title: 'Recent Messages',
-        scrollableLines: rawOverviewLines,
-        selectedIndex: this.selectedIndex,
-        scrollOffset: this.scrollOffset,
-        guardRows: 1,
-        minRows: 4,
-        appendWindowSummary: { dimColor: C.dim },
-      },
-      afterSections: [detailSection],
-    });
-    this.scrollOffset = resolvedMessagesSection.scrollOffset;
+    footerLines.push(buildPanelLine(width, [['  Up/Down move through messages', C.dim]]));
 
-    const sections: PanelWorkspaceSection[] = [
-      postureSection,
-      resolvedMessagesSection.section,
-      detailSection,
-    ];
-    const lines = buildPanelWorkspace(width, height, {
+    return this.renderList(width, height, {
       title: 'Communication Control Room',
-      intro,
-      sections,
-      footerLines,
-      palette: C,
+      header: postureWithSelected,
+      footer: footerLines,
     });
-    while (lines.length < height) lines.push(createEmptyLine(width));
-    return lines.slice(0, height);
   }
 }

package/src/panels/context-visualizer-panel.ts

@@ -72,6 +72,7 @@ export class ContextVisualizerPanel extends BasePanel {
   }
 
   render(width: number, height: number): Line[] {
+    return this.trackedRender(() => {
     if (height <= 0 || width <= 0) return [];
 
     const input = this.snapshot.input;
@@ -131,6 +132,7 @@ export class ContextVisualizerPanel extends BasePanel {
       ],
       palette: DEFAULT_PANEL_PALETTE,
     });
+    });
   }
 
   private _renderBar(width: number, barWidth: number, input: number, limit: number): Line {