@pellux/goodvibes-tui 0.18.19 → 0.18.23

package/src/panels/approval-panel.ts

@@ -1,14 +1,10 @@
 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 {
   buildGuidanceLine,
   buildKeyValueLine,
   buildPanelLine,
-  buildPanelWorkspace,
   DEFAULT_PANEL_PALETTE,
-  resolvePrimaryScrollableSection,
-  type PanelWorkspaceSection,
 } from './polish.ts';
 import type { PolicyRuntimeState } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-runtime';
 import { buildPermissionRuleSuggestions } from '@pellux/goodvibes-sdk/platform/runtime/permissions/rule-suggestions';
@@ -30,9 +26,9 @@ const APPROVAL_ROWS = [
   ['sandbox', 'why prompted: WSL/VM isolation changes alter host risk posture', 'review via /sandbox preset and /sandbox review'],
 ] as const;
 
-export class ApprovalPanel extends BasePanel {
-  private selectedIndex = 0;
-  private scrollOffset = 0;
+type ApprovalRow = (typeof APPROVAL_ROWS)[number];
+
+export class ApprovalPanel extends ScrollableListPanel<ApprovalRow> {
   private readonly policyRuntimeState: Pick<PolicyRuntimeState, 'getSnapshot'>;
 
   public constructor(policyRuntimeState: Pick<PolicyRuntimeState, 'getSnapshot'>) {
@@ -40,17 +36,23 @@ export class ApprovalPanel extends BasePanel {
     this.policyRuntimeState = policyRuntimeState;
   }
 
+  protected override getPalette() { return C; }
+  protected override getEmptyStateMessage() { return ' No approval lanes defined.'; }
+
+  protected getItems(): readonly ApprovalRow[] {
+    return APPROVAL_ROWS;
+  }
+
+  protected renderItem(row: ApprovalRow, index: number, selected: boolean, width: number): Line {
+    const bg = selected ? C.selectBg : undefined;
+    return buildPanelLine(width, [
+      ['  ', C.label],
+      [row[0].padEnd(10), C.info, bg],
+      [row[1].slice(0, Math.max(0, width - 18)), C.value, bg],
+    ]);
+  }
+
   public handleInput(key: string): boolean {
-    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(APPROVAL_ROWS.length - 1, this.selectedIndex + 1);
-      this.markDirty();
-      return true;
-    }
     if (key === 'home') {
       this.selectedIndex = 0;
       this.markDirty();
@@ -64,7 +66,7 @@ export class ApprovalPanel extends BasePanel {
     if (key === 'enter' || key === 'return') {
       return true;
     }
-    return false;
+    return super.handleInput(key);
   }
 
   public getSelectedCommand(): string | null {
@@ -73,25 +75,16 @@ export class ApprovalPanel extends BasePanel {
   }
 
   public render(width: number, height: number): Line[] {
-    this.needsRender = false;
+    this.clampSelection();
     const policySnapshot = this.policyRuntimeState.getSnapshot();
-    const postureLines = [
-      buildKeyValueLine(width, [
-        { label: 'why prompted', value: 'risk summary', valueColor: C.value },
-        { label: 'what-if', value: '/policy simulate + preflight', valueColor: C.info },
-        { label: 'operator', value: '/security + /cockpit', valueColor: C.good },
-      ], C),
-      buildKeyValueLine(width, [
-        { label: 'recent approvals', value: String(policySnapshot.recentPermissionAudit.filter((entry) => entry.approved === true).length), valueColor: C.good },
-        { label: 'recent denials', value: String(policySnapshot.recentPermissionAudit.filter((entry) => entry.approved === false).length), valueColor: C.bad },
-        { label: 'pending', value: String(policySnapshot.recentPermissionAudit.filter((entry) => entry.approved === undefined).length), valueColor: C.info },
-      ], C),
-      buildGuidanceLine(width, '/approval review shell', 'inspect the highest-risk approval lane and refine scoped review posture', C),
-    ];
-    const footerLines = [buildPanelLine(width, [[`  Up/Down move  Home/End jump  selected lane opens the next command path`, C.dim]])];
+    const approvalCount = policySnapshot.recentPermissionAudit.filter((e) => e.approved === true).length;
+    const denialCount = policySnapshot.recentPermissionAudit.filter((e) => e.approved === false).length;
+    const pendingCount = policySnapshot.recentPermissionAudit.filter((e) => e.approved === undefined).length;
+
     const selected = APPROVAL_ROWS[this.selectedIndex] ?? null;
     const detailLines: Line[] = [];
     if (selected) {
+      detailLines.push(buildPanelLine(width, [['  Selected Lane', C.label]]));
       detailLines.push(buildKeyValueLine(width, [
         { label: 'lane', value: selected[0], valueColor: C.info },
         { label: 'next review', value: selected[2], valueColor: C.dim },
@@ -99,6 +92,7 @@ export class ApprovalPanel extends BasePanel {
       detailLines.push(buildPanelLine(width, [[` ${selected[1]}`, C.value]]));
       detailLines.push(buildGuidanceLine(width, selected[2].replace('review via ', ''), `open the ${selected[0]} review path`, C));
     }
+
     const recentAuditLines: Line[] = [];
     for (const entry of policySnapshot.recentPermissionAudit.slice(0, 5)) {
       const decision = entry.approved === undefined ? 'pending' : entry.approved ? 'approved' : 'denied';
@@ -115,6 +109,7 @@ export class ApprovalPanel extends BasePanel {
     if (recentAuditLines.length === 0) {
       recentAuditLines.push(buildPanelLine(width, [[`  No recent approval pressure. Live requests and decisions will appear here.`, C.dim]]));
     }
+
     const ruleSuggestionLines: Line[] = [];
     for (const suggestion of buildPermissionRuleSuggestions(policySnapshot.recentPermissionAudit).slice(0, 3)) {
       ruleSuggestionLines.push(buildPanelLine(width, [[`  ${suggestion.summary}`, C.info]]));
@@ -123,47 +118,32 @@ export class ApprovalPanel extends BasePanel {
     if (ruleSuggestionLines.length === 0) {
       ruleSuggestionLines.push(buildPanelLine(width, [[`  No repeated denials currently suggest a durable rule.`, C.dim]]));
     }
-    const postureSection: PanelWorkspaceSection = { title: 'Approval posture', lines: postureLines };
-    const selectedSection: PanelWorkspaceSection = { title: 'Selected Lane', lines: detailLines };
-    const pressureSection: PanelWorkspaceSection = { title: 'Recent Pressure', lines: recentAuditLines };
-    const rulesSection: PanelWorkspaceSection = { title: 'Rule Suggestions', lines: ruleSuggestionLines };
-    const resolvedLanesSection = resolvePrimaryScrollableSection(width, height, {
-      intro: 'Action-specific review lanes for approvals, denials, escalations, and preflight guidance.',
-      footerLines,
-      palette: C,
-      beforeSections: [postureSection, selectedSection, pressureSection, rulesSection],
-      section: {
-        title: 'Review Lanes',
-        scrollableLines: APPROVAL_ROWS.map((row, absolute) => {
-          const bg = absolute === this.selectedIndex ? C.selectBg : undefined;
-          return buildPanelLine(width, [
-            ['  ', C.label],
-            [row[0].padEnd(10), C.info, bg],
-            [row[1].slice(0, Math.max(0, width - 18)), C.value, bg],
-          ]);
-        }),
-        selectedIndex: this.selectedIndex,
-        scrollOffset: this.scrollOffset,
-        guardRows: 1,
-        minRows: 4,
-        appendWindowSummary: { dimColor: C.dim },
-      },
-    });
-    this.scrollOffset = resolvedLanesSection.scrollOffset;
-    const lines = buildPanelWorkspace(width, height, {
+
+    const headerLines: Line[] = [
+      buildPanelLine(width, [['  Approval posture', C.label]]),
+      buildKeyValueLine(width, [
+        { label: 'why prompted', value: 'risk summary', valueColor: C.value },
+        { label: 'what-if', value: '/policy simulate + preflight', valueColor: C.info },
+        { label: 'operator', value: '/security + /cockpit', valueColor: C.good },
+      ], C),
+      buildPanelLine(width, [
+        ['  \u2713 ', C.good],
+        [`approvals (${approvalCount})  `, C.good],
+        ['\u2715 ', C.bad],
+        [`denials (${denialCount})  `, C.bad],
+        ['\u25cb ', C.info],
+        [`pending (${pendingCount})`, C.info],
+      ]),
+      buildGuidanceLine(width, '/approval review shell', 'inspect the highest-risk approval lane and refine scoped review posture', C),
+      ...detailLines,
+      ...recentAuditLines,
+      ...ruleSuggestionLines,
+    ];
+
+    return this.renderList(width, height, {
       title: 'Approval Control Room',
-      intro: 'Action-specific review lanes for approvals, denials, escalations, and preflight guidance.',
-      sections: [
-        postureSection,
-        selectedSection,
-        pressureSection,
-        rulesSection,
-        resolvedLanesSection.section,
-      ],
-      footerLines,
-      palette: C,
+      header: headerLines,
+      footer: [buildPanelLine(width, [[`  Up/Down move  Home/End jump  selected lane opens the next command path`, C.dim]])],
     });
-    while (lines.length < height) lines.push(createEmptyLine(width));
-    return lines.slice(0, height);
   }
 }

package/src/panels/automation-control-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 type { UiAutomationSnapshot, UiReadModel } from '../runtime/ui-read-models.ts';
 import { truncateDisplay } from '../utils/terminal-width.ts';
 import {
@@ -10,8 +10,7 @@ import {
   buildPanelLine,
   buildPanelWorkspace,
   DEFAULT_PANEL_PALETTE,
-  resolvePrimaryScrollableSection,
-  type PanelWorkspaceSection,
+  type PanelPalette,
 } from './polish.ts';
 
 const C = {
@@ -37,11 +36,12 @@ function runStatusColor(status: string): string {
   return C.info;
 }
 
-export class AutomationControlPanel extends BasePanel {
+type AutomationRun = UiAutomationSnapshot['runs'][number];
+type AutomationJob = UiAutomationSnapshot['jobs'][number];
+
+export class AutomationControlPanel extends ScrollableListPanel<AutomationRun> {
   private readonly readModel?: UiReadModel<UiAutomationSnapshot>;
   private readonly unsub: (() => void) | null;
-  private selectedIndex = 0;
-  private scrollOffset = 0;
 
   public constructor(readModel?: UiReadModel<UiAutomationSnapshot>) {
     super('automation', 'Automation', 'M', 'monitoring');
@@ -53,29 +53,45 @@ export class AutomationControlPanel extends BasePanel {
     this.unsub?.();
   }
 
-  public handleInput(key: string): boolean {
-    const runs = this.runs();
-    if (runs.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(runs.length - 1, this.selectedIndex + 1);
-      this.markDirty();
-      return true;
-    }
-    return false;
+  protected override getPalette(): PanelPalette {
+    return C;
+  }
+
+  private getJobs(): readonly AutomationJob[] {
+    if (!this.readModel) return [];
+    return this.readModel.getSnapshot().jobs;
   }
 
-  private runs() {
+  protected getItems(): readonly AutomationRun[] {
     if (!this.readModel) return [];
-    return [...this.readModel.getSnapshot().runs];
+    return this.readModel.getSnapshot().runs;
+  }
+
+  protected renderItem(run: AutomationRun, _index: number, selected: boolean, width: number): Line {
+    const bg = selected ? C.selectBg : undefined;
+    const jobs = this.getJobs();
+    const name = jobs.find((job) => job.id === run.jobId)?.name ?? run.jobId;
+    return buildPanelLine(width, [
+      [' ', C.label, bg],
+      [run.status.padEnd(11), runStatusColor(run.status), bg],
+      [` ${truncateDisplay(name, 22).padEnd(22)}`, C.value, bg],
+      [` ${truncateDisplay(run.target.kind, 12).padEnd(12)}`, C.info, bg],
+      [` ${truncateDisplay(formatTime(run.queuedAt), Math.max(0, width - 49))}`, C.dim, bg],
+    ]);
+  }
+
+  protected override getEmptyStateMessage(): string {
+    return ' No automation activity recorded.';
+  }
+
+  protected override getEmptyStateActions(): Array<{ command: string; summary: string }> {
+    return [
+      { command: '/schedule add cron 0 * * * * repo sweep', summary: 'create a recurring automation job' },
+      { command: '/schedule list', summary: 'inspect jobs and run history from the shell' },
+    ];
   }
 
   public render(width: number, height: number): Line[] {
-    this.needsRender = false;
     const intro = 'Automation jobs, active runs, deliveries, and failure posture across the shared control plane.';
 
     if (!this.readModel) {
@@ -99,155 +115,97 @@ export class AutomationControlPanel extends BasePanel {
 
     const snapshot = this.readModel.getSnapshot();
     const jobs = [...snapshot.jobs];
-    const runs = this.runs();
-
-    const summarySection: PanelWorkspaceSection = {
-      title: 'Posture',
-      lines: [
-        buildKeyValueLine(width, [
-          { label: 'jobs', value: String(snapshot.totalJobs), valueColor: snapshot.totalJobs > 0 ? C.info : C.dim },
-          { label: 'runs', value: String(snapshot.totalRuns), valueColor: snapshot.totalRuns > 0 ? C.value : C.dim },
-          { label: 'active', value: String(snapshot.activeRunIds.length), valueColor: snapshot.activeRunIds.length > 0 ? C.warn : C.dim },
-          { label: 'failed', value: String(snapshot.totalFailed), valueColor: snapshot.totalFailed > 0 ? C.error : C.dim },
-        ], C),
-        buildKeyValueLine(width, [
-          { label: 'deliveries ok', value: String(snapshot.deliveryTotals.succeeded), valueColor: snapshot.deliveryTotals.succeeded > 0 ? C.ok : C.dim },
-          { label: 'delivery fail', value: String(snapshot.deliveryTotals.failed), valueColor: snapshot.deliveryTotals.failed > 0 ? C.error : C.dim },
-          { label: 'dead letters', value: String(snapshot.deliveryTotals.deadLettered), valueColor: snapshot.deliveryTotals.deadLettered > 0 ? C.warn : C.dim },
-          { label: 'sources', value: String(snapshot.sourceCount), valueColor: snapshot.sourceCount > 0 ? C.info : C.dim },
-        ], C),
-        buildGuidanceLine(width, '/schedule list', 'manage jobs and use the web or surface controls for retries, delivery, and cross-surface sessions', C),
-      ],
-    };
+    const runs = this.getItems();
+
+    const headerLines: Line[] = [
+      buildKeyValueLine(width, [
+        { label: 'jobs', value: String(snapshot.totalJobs), valueColor: snapshot.totalJobs > 0 ? C.info : C.dim },
+        { label: 'runs', value: String(snapshot.totalRuns), valueColor: snapshot.totalRuns > 0 ? C.value : C.dim },
+        { label: 'active', value: String(snapshot.activeRunIds.length), valueColor: snapshot.activeRunIds.length > 0 ? C.warn : C.dim },
+        { label: 'failed', value: String(snapshot.totalFailed), valueColor: snapshot.totalFailed > 0 ? C.error : C.dim },
+      ], C),
+      buildKeyValueLine(width, [
+        { label: 'deliveries ok', value: String(snapshot.deliveryTotals.succeeded), valueColor: snapshot.deliveryTotals.succeeded > 0 ? C.ok : C.dim },
+        { label: 'delivery fail', value: String(snapshot.deliveryTotals.failed), valueColor: snapshot.deliveryTotals.failed > 0 ? C.error : C.dim },
+        { label: 'dead letters', value: String(snapshot.deliveryTotals.deadLettered), valueColor: snapshot.deliveryTotals.deadLettered > 0 ? C.warn : C.dim },
+        { label: 'sources', value: String(snapshot.sourceCount), valueColor: snapshot.sourceCount > 0 ? C.info : C.dim },
+      ], C),
+      buildGuidanceLine(width, '/schedule list', 'manage jobs and use the web or surface controls for retries, delivery, and cross-surface sessions', C),
+    ];
 
     if (jobs.length === 0 && runs.length === 0) {
-      const workspace = buildPanelWorkspace(width, height, {
+      return this.renderList(width, height, {
         title: 'Automation Control',
-        intro,
-        sections: [
-          summarySection,
-          {
-            lines: buildEmptyState(
-              width,
-              ' No automation activity recorded.',
-              'Create a job, run one manually, or let a watcher/surface trigger automation to populate this control room.',
-              [
-                { command: '/schedule add cron 0 * * * * repo sweep', summary: 'create a recurring automation job' },
-                { command: '/schedule list', summary: 'inspect jobs and run history from the shell' },
-              ],
-              C,
-            ),
-          },
-        ],
-        palette: C,
+        header: headerLines,
+        emptyMessage: ' No automation activity recorded.',
       });
-      while (workspace.length < height) workspace.push(createEmptyLine(width));
-      return workspace;
     }
 
-    this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, runs.length - 1));
+    this.clampSelection();
     const selectedRun = runs[this.selectedIndex];
     const jobName = selectedRun ? (jobs.find((job) => job.id === selectedRun.jobId)?.name ?? selectedRun.jobId) : 'n/a';
 
-    const jobSection: PanelWorkspaceSection = {
-      title: 'Jobs',
-      lines: jobs.slice(0, 6).map((job) => buildPanelLine(width, [
-        [' ', C.label],
-        [job.enabled ? 'ENABLED ' : 'PAUSED  ', job.enabled ? C.ok : C.warn],
-        [truncateDisplay(job.name, 24).padEnd(24), C.value],
-        [` next ${truncateDisplay(formatTime(job.nextRunAt), Math.max(0, width - 43))}`, C.dim],
-      ])),
-    };
-
-    const detailSection: PanelWorkspaceSection = selectedRun
-      ? {
-          title: 'Selected Run',
-          lines: [
-            buildPanelLine(width, [
-              ['  Run: ', C.label],
-              [selectedRun.id, C.value],
-              ['  Status: ', C.label],
-              [selectedRun.status, runStatusColor(selectedRun.status)],
-            ]),
-            buildPanelLine(width, [
-              ['  Job: ', C.label],
-              [jobName, C.value],
-              ['  Agent: ', C.label],
-              [selectedRun.agentId ?? 'n/a', C.info],
-            ]),
-            buildPanelLine(width, [
-              ['  Queue: ', C.label],
-              [formatTime(selectedRun.queuedAt), C.dim],
-              ['  End: ', C.label],
-              [formatTime(selectedRun.endedAt), C.dim],
-            ]),
-            buildPanelLine(width, [
-              ['  Trigger: ', C.label],
-              [selectedRun.triggeredBy.kind, C.info],
-              ['  Target: ', C.label],
-              [selectedRun.target.kind, C.value],
-            ]),
-            buildPanelLine(width, [
-              ['  Deliveries: ', C.label],
-              [String(selectedRun.deliveryIds.length), selectedRun.deliveryIds.length > 0 ? C.info : C.dim],
-              ['  Route: ', C.label],
-              [selectedRun.routeId ?? 'n/a', C.dim],
-            ]),
-            ...(selectedRun.error ? [
-              buildPanelLine(width, [
-                ['  Error: ', C.label],
-                [truncateDisplay(selectedRun.error, Math.max(0, width - 10)), C.error],
-              ]),
-            ] : []),
-          ],
-        }
-      : {
-          title: 'Selected Run',
-          lines: [buildPanelLine(width, [['  No run selected.', C.dim]])],
-        };
-
-    const resolvedRuns = resolvePrimaryScrollableSection(width, height, {
-      intro,
-      footerLines: [buildPanelLine(width, [['  Up/Down move through runs', C.dim]])],
-      palette: C,
-      beforeSections: [summarySection],
-      section: {
-        title: 'Recent Runs',
-        scrollableLines: runs.map((run, absolute) => {
-          const bg = absolute === this.selectedIndex ? C.selectBg : undefined;
-          const name = jobs.find((job) => job.id === run.jobId)?.name ?? run.jobId;
-          return buildPanelLine(width, [
-            [' ', C.label, bg],
-            [run.status.padEnd(11), runStatusColor(run.status), bg],
-            [` ${truncateDisplay(name, 22).padEnd(22)}`, C.value, bg],
-            [` ${truncateDisplay(run.target.kind, 12).padEnd(12)}`, C.info, bg],
-            [` ${truncateDisplay(formatTime(run.queuedAt), Math.max(0, width - 49))}`, C.dim, bg],
-          ]);
-        }),
-        selectedIndex: this.selectedIndex,
-        scrollOffset: this.scrollOffset,
-        guardRows: 1,
-        minRows: 5,
-        appendWindowSummary: { dimColor: C.dim },
-      },
-      afterSections: [detailSection, jobSection],
-    });
-    this.scrollOffset = resolvedRuns.scrollOffset;
+    const footerLines: Line[] = [];
+    if (selectedRun) {
+      footerLines.push(
+        buildPanelLine(width, [
+          ['  Run: ', C.label],
+          [selectedRun.id, C.value],
+          ['  Status: ', C.label],
+          [selectedRun.status, runStatusColor(selectedRun.status)],
+        ]),
+        buildPanelLine(width, [
+          ['  Job: ', C.label],
+          [jobName, C.value],
+          ['  Agent: ', C.label],
+          [selectedRun.agentId ?? 'n/a', C.info],
+        ]),
+        buildPanelLine(width, [
+          ['  Queue: ', C.label],
+          [formatTime(selectedRun.queuedAt), C.dim],
+          ['  End: ', C.label],
+          [formatTime(selectedRun.endedAt), C.dim],
+        ]),
+        buildPanelLine(width, [
+          ['  Trigger: ', C.label],
+          [selectedRun.triggeredBy.kind, C.info],
+          ['  Target: ', C.label],
+          [selectedRun.target.kind, C.value],
+        ]),
+        buildPanelLine(width, [
+          ['  Deliveries: ', C.label],
+          [String(selectedRun.deliveryIds.length), selectedRun.deliveryIds.length > 0 ? C.info : C.dim],
+          ['  Route: ', C.label],
+          [selectedRun.routeId ?? 'n/a', C.dim],
+        ]),
+      );
+      if (selectedRun.error) {
+        footerLines.push(buildPanelLine(width, [
+          ['  Error: ', C.label],
+          [truncateDisplay(selectedRun.error, Math.max(0, width - 10)), C.error],
+        ]));
+      }
+    } else {
+      footerLines.push(buildPanelLine(width, [['  No run selected.', C.dim]]));
+    }
 
-    const sections: PanelWorkspaceSection[] = [
-      summarySection,
-      resolvedRuns.section,
-      detailSection,
-      jobSection,
-    ];
-    const lines = buildPanelWorkspace(width, height, {
+    // Jobs quick view
+    if (jobs.length > 0) {
+      footerLines.push(
+        ...jobs.slice(0, 6).map((job) => buildPanelLine(width, [
+          [' ', C.label],
+          [job.enabled ? 'ENABLED ' : 'PAUSED  ', job.enabled ? C.ok : C.warn],
+          [truncateDisplay(job.name, 24).padEnd(24), C.value],
+          [` next ${truncateDisplay(formatTime(job.nextRunAt), Math.max(0, width - 43))}`, C.dim],
+        ])),
+      );
+    }
+    footerLines.push(buildPanelLine(width, [['  Up/Down move through runs', C.dim]]));
+
+    return this.renderList(width, height, {
       title: 'Automation Control',
-      intro,
-      sections,
-      footerLines: [buildPanelLine(width, [['  Up/Down move through runs', C.dim]])],
-      palette: C,
+      header: headerLines,
+      footer: footerLines,
     });
-    while (lines.length < height) lines.push(createEmptyLine(width));
-    return lines.slice(0, height);
   }
 }

package/src/panels/base-panel.ts

@@ -2,6 +2,8 @@ import type { Line } from '../types/grid.ts';
 import type { Panel, PanelCategory } from './types.ts';
 import type { ComponentResourceContract, ComponentHealthState } from '../runtime/perf/panel-contracts.ts';
 import type { ComponentHealthMonitor } from '../runtime/perf/panel-health-monitor.ts';
+import { UIFactory } from '../renderer/ui-factory.ts';
+import { SPINNER_FRAMES } from '../renderer/progress.ts';
 
 export abstract class BasePanel implements Panel {
   public needsRender = true;
@@ -9,6 +11,75 @@ export abstract class BasePanel implements Panel {
   public isPinned = false;
   protected readonly componentHealthMonitor?: ComponentHealthMonitor;
 
+  // -------------------------------------------------------------------------
+  // I2: Error surface slot
+  // -------------------------------------------------------------------------
+
+  /** Last error message to surface in the panel footer. Auto-cleared on next input. */
+  protected lastError: string | null = null;
+
+  /** Set a transient error message. Triggers a re-render. */
+  protected setError(msg: string): void {
+    this.lastError = msg;
+    this.needsRender = true;
+  }
+
+  /** Clear the current error. */
+  protected clearError(): void {
+    this.lastError = null;
+  }
+
+  /**
+   * Build a single error Line for display above the hints footer.
+   * Returns null when there is no active error.
+   *
+   * Color: bold red foreground (palette-consistent: #ef4444).
+   */
+  protected renderErrorLine(width: number): Line | null {
+    if (!this.lastError) return null;
+    return UIFactory.stringToLine(
+      ` ✕ ${this.lastError}`.padEnd(width).slice(0, width),
+      width,
+      { fg: '#ef4444', bold: true },
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // I3: Loading spinner slot
+  // -------------------------------------------------------------------------
+
+  /** Tracks the loading label for the spinner (undefined = no spinner active). */
+  protected loadingState: 'idle' | 'loading' | 'error' = 'idle';
+  private _loadingLabel = '';
+
+  /** Begin loading. Triggers a re-render. */
+  protected startLoading(label = 'Loading...'): void {
+    this.loadingState = 'loading';
+    this._loadingLabel = label;
+    this.needsRender = true;
+  }
+
+  /** End loading (returns to idle). Triggers a re-render. */
+  protected stopLoading(): void {
+    this.loadingState = 'idle';
+    this._loadingLabel = '';
+    this.needsRender = true;
+  }
+
+  /**
+   * Build a spinner Line for the loading state.
+   * Returns null when loadingState is not 'loading'.
+   *
+   * @param width  Panel width in columns.
+   * @param frame  Current animation frame index (caller increments each render).
+   */
+  protected renderLoadingLine(width: number, frame = 0): Line | null {
+    if (this.loadingState !== 'loading') return null;
+    const spinner = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? SPINNER_FRAMES[0]!;
+    const text = ` ${spinner} ${this._loadingLabel}`;
+    return UIFactory.stringToLine(text.padEnd(width).slice(0, width), width, { fg: '135', bold: true });
+  }
+
   /**
    * Optional resource contract for this panel.
    * Override in subclasses to declare a custom contract; leave undefined