@pellux/goodvibes-agent 0.1.0

package/src/panels/approval-panel.ts

@@ -0,0 +1,150 @@
+import type { Line } from '../types/grid.ts';
+import { ScrollableListPanel } from './scrollable-list-panel.ts';
+import {
+  buildGuidanceLine,
+  buildKeyValueLine,
+  buildPanelLine,
+  DEFAULT_PANEL_PALETTE,
+} from './polish.ts';
+import type { PolicyRuntimeState } from '@/runtime/index.ts';
+import { buildPermissionRuleSuggestions } from '@/runtime/index.ts';
+
+const C = {
+  ...DEFAULT_PANEL_PALETTE,
+  headerBg: '#111827',
+} as const;
+
+const APPROVAL_ROWS = [
+  ['shell', 'why prompted: side effects, destructive ops, secret exposure, escalation', 'review via /security and /policy preflight'],
+  ['file', 'why prompted: config mutation, notebook edits, secret-bearing paths', 'review via /approval review file'],
+  ['network', 'why prompted: external hosts, fetch scope, egress policy', 'review via /approval review network'],
+  ['delegate', 'why prompted: recursive agents, spawn ceilings, write-set inheritance', 'review via /approval review delegate'],
+  ['mcp', 'why prompted: trust escalation, host scope, path scope, coherence mismatch', 'review via /mcp trust and /security'],
+  ['remote', 'why prompted: runner trust, remote write scope, artifact requirements', 'review via /remote and delegated TUI sandbox context'],
+  ['hook', 'why prompted: deny/mutate authority, blocking behavior, runner provenance', 'review via /hooks and /security'],
+  ['plugin', 'why prompted: install/update lifecycle, provenance, capability grants', 'review via /marketplace and /security'],
+  ['sandbox', 'why prompted: WSL/VM isolation changes alter host risk posture', 'delegate sandbox changes to GoodVibes TUI'],
+] as const;
+
+type ApprovalRow = (typeof APPROVAL_ROWS)[number];
+
+export class ApprovalPanel extends ScrollableListPanel<ApprovalRow> {
+  private readonly policyRuntimeState: Pick<PolicyRuntimeState, 'getSnapshot'>;
+
+  public constructor(policyRuntimeState: Pick<PolicyRuntimeState, 'getSnapshot'>) {
+    super('approval', 'Approval', 'A', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
+    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 === 'home') {
+      this.selectedIndex = 0;
+      this.markDirty();
+      return true;
+    }
+    if (key === 'end') {
+      this.selectedIndex = APPROVAL_ROWS.length - 1;
+      this.markDirty();
+      return true;
+    }
+    if (key === 'enter' || key === 'return') {
+      return true;
+    }
+    return super.handleInput(key);
+  }
+
+  public getSelectedCommand(): string | null {
+    const selected = APPROVAL_ROWS[this.selectedIndex] ?? null;
+    return selected ? selected[2].replace('review via ', '').trim() : null;
+  }
+
+  public render(width: number, height: number): Line[] {
+    this.clampSelection();
+    const policySnapshot = this.policyRuntimeState.getSnapshot();
+    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 },
+      ], C));
+      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';
+      const decisionColor = entry.approved === undefined ? C.info : entry.approved ? C.good : C.bad;
+      recentAuditLines.push(buildPanelLine(width, [
+        [`  ${decision.padEnd(8)}`, decisionColor],
+        [`${entry.tool}`.padEnd(14), C.label],
+        [entry.summary.slice(0, Math.max(0, width - 28)), C.value],
+      ]));
+      if (entry.reasons[0]) {
+        recentAuditLines.push(buildPanelLine(width, [[`    ${entry.reasons[0]}`, C.dim]]));
+      }
+    }
+    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]]));
+      ruleSuggestionLines.push(buildGuidanceLine(width, suggestion.command, suggestion.reason, C));
+    }
+    if (ruleSuggestionLines.length === 0) {
+      ruleSuggestionLines.push(buildPanelLine(width, [[`  No repeated denials currently suggest a durable rule.`, C.dim]]));
+    }
+
+    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',
+      header: headerLines,
+      footer: [buildPanelLine(width, [[`  Up/Down move  Home/End jump  selected lane opens the next command path`, C.dim]])],
+    });
+  }
+}

package/src/panels/automation-control-panel.ts

@@ -0,0 +1,212 @@
+import type { Line } from '../types/grid.ts';
+import { createEmptyLine } from '../types/grid.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 {
+  buildEmptyState,
+  buildGuidanceLine,
+  buildKeyValueLine,
+  buildPanelLine,
+  buildPanelWorkspace,
+  DEFAULT_PANEL_PALETTE,
+  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;
+
+function formatTime(value?: number): string {
+  if (!value) return 'n/a';
+  return new Date(value).toLocaleString();
+}
+
+function runStatusColor(status: string): string {
+  if (status === 'completed') return C.ok;
+  if (status === 'failed' || status === 'dead_lettered') return C.error;
+  if (status === 'cancelled') return C.warn;
+  return C.info;
+}
+
+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;
+
+  public constructor(readModel?: UiReadModel<UiAutomationSnapshot>) {
+    super('automation', 'Automation', 'M', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
+    this.readModel = readModel;
+    this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
+  }
+
+  public override onDestroy(): void {
+    this.unsub?.();
+  }
+
+  protected override getPalette(): PanelPalette {
+    return C;
+  }
+
+  private getJobs(): readonly AutomationJob[] {
+    if (!this.readModel) return [];
+    return this.readModel.getSnapshot().jobs;
+  }
+
+  protected getItems(): readonly AutomationRun[] {
+    if (!this.readModel) return [];
+    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 list', summary: 'inspect jobs and run history without mutating schedules' },
+      { command: '/automation jobs', summary: 'review daemon-owned automation jobs from the Agent CLI' },
+    ];
+  }
+
+  public render(width: number, height: number): Line[] {
+    const intro = 'Automation jobs, active runs, deliveries, and failure posture across the shared control plane.';
+
+    if (!this.readModel) {
+      const workspace = buildPanelWorkspace(width, height, {
+        title: 'Automation Control',
+        intro,
+        sections: [{
+          lines: buildEmptyState(
+            width,
+            ' Runtime store not wired.',
+            'This panel needs the shared runtime store to inspect automation jobs, runs, and deliveries.',
+            [{ command: '/schedule list', summary: 'review automation from the shell while the runtime wiring is restored' }],
+            C,
+          ),
+        }],
+        palette: C,
+      });
+      while (workspace.length < height) workspace.push(createEmptyLine(width));
+      return workspace;
+    }
+
+    const snapshot = this.readModel.getSnapshot();
+    const jobs = [...snapshot.jobs];
+    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', 'read-only in Agent; schedule mutation/run controls remain blocked here', C),
+    ];
+
+    if (jobs.length === 0 && runs.length === 0) {
+      return this.renderList(width, height, {
+        title: 'Automation Control',
+        header: headerLines,
+        emptyMessage: ' No automation activity recorded.',
+      });
+    }
+
+    this.clampSelection();
+    const selectedRun = runs[this.selectedIndex];
+    const jobName = selectedRun ? (jobs.find((job) => job.id === selectedRun.jobId)?.name ?? selectedRun.jobId) : 'n/a';
+
+    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]]));
+    }
+
+    // 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',
+      header: headerLines,
+      footer: footerLines,
+    });
+  }
+}

package/src/panels/base-panel.ts

@@ -0,0 +1,254 @@
+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;
+  public isTransient = false;
+  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 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.
+   * 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;
+  }
+
+  /** 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;
+  }
+
+  /**
+   * 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'.
+   *
+   * @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
+   * to use the category default enforced by ComponentHealthMonitor.
+   */
+  public resourceContract: Readonly<ComponentResourceContract> | undefined = undefined;
+
+  /**
+   * Live health state populated by ComponentHealthMonitor.
+   * Read-only from outside the monitor.
+   */
+  public get healthState(): Readonly<ComponentHealthState> | undefined {
+    return this.componentHealthMonitor?.getHealth(this.id);
+  }
+
+  constructor(
+    public readonly id: string,
+    public readonly name: string,
+    public readonly icon: string,
+    public readonly category: PanelCategory,
+    componentHealthMonitor?: ComponentHealthMonitor,
+  ) {
+    this.componentHealthMonitor = componentHealthMonitor;
+  }
+
+  onActivate(): void { this.needsRender = true; }
+  onDeactivate(): 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[];
+
+  /** R2: Mark this panel dirty — it will be re-rendered on the next compositor frame. */
+  public invalidate(): void { this.needsRender = true; }
+
+  /** R2: Called by the compositor after a successful render to clear the dirty flag. */
+  public markRendered(): void { this.needsRender = false; }
+
+  protected markDirty(): void { this.needsRender = true; }
+
+  /**
+   * Check whether the panel is currently permitted to render.
+   *
+   * Consults the shared ComponentHealthMonitor. Returns true if not registered
+   * (unthrottled) or if the monitor permits a render at this moment.
+   *
+   * Call this inside render() or before invoking render() to skip
+   * expensive work when throttled:
+   *
+   * ```ts
+   * render(width, height): Line[] {
+   *   if (!this.canRenderNow()) return this._lastLines ?? [];
+   *   // ... expensive render ...
+   * }
+   * ```
+   */
+  protected canRenderNow(now: number = Date.now()): boolean {
+    return this.componentHealthMonitor?.canRender(this.id, now) ?? true;
+  }
+
+  /**
+   * Report the duration of a completed render to the health monitor.
+   * Call this at the end of render() after measuring wall-clock cost.
+   */
+  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;
+  }
+}