@pellux/goodvibes-tui 0.27.0 → 0.29.0

package/src/panels/policy-panel.ts

@@ -1,28 +1,34 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine } from '../types/grid.ts';
+import { truncateDisplay } from '../utils/terminal-width.ts';
 import { BasePanel } from './base-panel.ts';
-import type { PolicyRuntimeState } from '@/runtime/index.ts';
-import type { PolicyPanelSnapshot } from '../runtime/diagnostics/panels/policy.ts';
+import type {
+  PolicyRuntimeState,
+  PolicyBundleVersion,
+  PolicyDiffResult,
+  DivergenceDashboardSnapshot,
+  DivergenceStats,
+  PermissionAuditEntry,
+  PolicyLintFinding,
+  PolicySimulationSummary,
+  PolicyPreflightReview,
+} from '@/runtime/index.ts';
 import {
+  buildEmptyState,
+  buildKeyboardHints,
+  buildKeyValueLine,
   buildPanelLine,
   buildPanelWorkspace,
   resolveScrollablePanelSection,
   DEFAULT_PANEL_PALETTE,
 } from './polish.ts';
+import { type ConfirmState, handleConfirmInput, renderConfirmLines } from './confirm-state.ts';
+import type { PanelIntegrationContext } from './types.ts';
 
-const C = {
-  ...DEFAULT_PANEL_PALETTE,
-  header: '#94a3b8',
-  headerBg: '#1e293b',
-  label: '#64748b',
-  value: '#e2e8f0',
-  dim: '#475569',
-  ok: '#22c55e',
-  warn: '#eab308',
-  error: '#ef4444',
-  info: '#38bdf8',
-  empty: '#334155',
-} as const;
+// Base chrome only — no domain accents needed; the title band, state colors,
+// and text tokens all come straight from DEFAULT_PANEL_PALETTE (WO-002).
+const C = DEFAULT_PANEL_PALETTE;
 
 function fmtTime(value: string | undefined): string {
   if (!value) return 'n/a';
@@ -37,9 +43,9 @@ function fmtRate(value: number | undefined): string {
 function gateColor(status: string | undefined): string {
   switch (status) {
     case 'allowed':
-      return C.ok;
+      return C.good;
     case 'blocked':
-      return C.error;
+      return C.bad;
     case 'no_data':
       return C.warn;
     default:
@@ -47,13 +53,49 @@ function gateColor(status: string | undefined): string {
   }
 }
 
+/**
+ * A point-in-time snapshot of policy state for diagnostics rendering.
+ */
+interface PolicyPanelSnapshot {
+  /** The currently enforced bundle, or null if no policy is active. */
+  current: PolicyBundleVersion | null;
+  /** The pending candidate bundle, or null if none loaded. */
+  candidate: PolicyBundleVersion | null;
+  /** History of previous active bundles (most recent first). */
+  history: PolicyBundleVersion[];
+  /** Diff between current and candidate, or null if unavailable. */
+  diff: PolicyDiffResult | null;
+  /** Divergence dashboard snapshot, or null if no panel attached. */
+  divergence: DivergenceDashboardSnapshot | null;
+  /** Recent permission requests and decisions for operator audit review. */
+  recentPermissionAudit: readonly PermissionAuditEntry[];
+  /** Policy lint findings for current and candidate bundles. */
+  lintFindings: readonly PolicyLintFinding[];
+  /** Concrete scenario results from the most recent policy simulation run. */
+  lastSimulationSummary: PolicySimulationSummary | null;
+  /** Most recent proactive policy preflight review. */
+  lastPreflightReview: PolicyPreflightReview | null;
+  /** ISO 8601 timestamp of when this snapshot was captured. */
+  capturedAt: string;
+}
+
+/** Subactions dispatched through `/policy <name>` via `dispatchPolicyCommand`. */
+type PolicyDispatchAction = 'simulate' | 'preflight' | 'lint' | 'promote' | 'rollback';
+
 export class PolicyPanel extends BasePanel {
   private readonly _state: PolicyRuntimeState;
   private readonly _unsub: (() => void) | null;
   private _scrollOffset = 0;
 
+  // Inline confirm for the gate-aware promote/rollback actions.
+  private _confirm: ConfirmState<PolicyDispatchAction> | null = null;
+
+  // Pending dispatch resolved via handlePanelIntegrationAction, which is the
+  // only place `executeCommand` is available (mirrors IncidentReviewPanel).
+  private _pendingAction: PolicyDispatchAction | null = null;
+
   public constructor(state: PolicyRuntimeState) {
-    super('policy', 'Policy', 'U', 'monitoring');
+    super('policy', 'Policy', '▭', 'security-policy');
     this._state = state;
     this._unsub = state.subscribe(() => this.markDirty());
   }
@@ -68,6 +110,22 @@ export class PolicyPanel extends BasePanel {
   }
 
   public handleInput(key: string): boolean {
+    if (this._confirm) {
+      const outcome = handleConfirmInput(this._confirm, key);
+      if (outcome === 'confirmed') {
+        this._pendingAction = this._confirm.subject;
+        this._confirm = null;
+        this.markDirty();
+        return true;
+      }
+      if (outcome === 'cancelled') {
+        this._confirm = null;
+        this.markDirty();
+        return true;
+      }
+      return true; // absorbed — keep the confirm dialog pending
+    }
+
     if (key === 'up' || key === 'k') {
       this._scrollOffset = Math.max(0, this._scrollOffset - 1);
       this.markDirty();
@@ -78,7 +136,45 @@ export class PolicyPanel extends BasePanel {
       this.markDirty();
       return true;
     }
+    if (key === 's') {
+      this._pendingAction = 'simulate';
+      return true;
+    }
+    if (key === 'f') {
+      this._pendingAction = 'preflight';
+      return true;
+    }
+    if (key === 'l') {
+      this._pendingAction = 'lint';
+      return true;
+    }
+    if (key === 'p') {
+      const snapshot = this._state.getSnapshot();
+      if (!snapshot.candidate) return false;
+      const gateStatus = snapshot.divergence?.gate.status ?? 'no_data';
+      this._confirm = {
+        subject: 'promote',
+        label: `promote ${snapshot.candidate.bundle.bundleId} (gate: ${gateStatus})`,
+        verb: 'Promote',
+      };
+      this.markDirty();
+      return true;
+    }
+    if (key === 'b') {
+      const snapshot = this._state.getSnapshot();
+      if (!snapshot.current) return false;
+      this._confirm = {
+        subject: 'rollback',
+        label: `rollback active bundle ${snapshot.current.bundle.bundleId}`,
+        verb: 'Rollback',
+      };
+      this.markDirty();
+      return true;
+    }
     if (key === 'r') {
+      // Trend-record is only meaningful once a simulation dashboard exists;
+      // otherwise there is nothing to sample and the key is a no-op.
+      if (!this._state.getDashboard()) return false;
       this._state.recordTrendEntry();
       this.markDirty();
       return true;
@@ -86,25 +182,60 @@ export class PolicyPanel extends BasePanel {
     return false;
   }
 
+  public handlePanelIntegrationAction(_key: string, ctx: PanelIntegrationContext): boolean {
+    if (!this._pendingAction) return false;
+    const action = this._pendingAction;
+    this._pendingAction = null;
+    void ctx.executeCommand?.('policy', [action]).catch((err) => {
+      logger.debug('policy panel command dispatch failed', { err, action });
+    });
+    return true;
+  }
+
   public render(width: number, height: number): Line[] {
     this.needsRender = false;
+    if (this._confirm) {
+      const lines = buildPanelWorkspace(width, height, {
+        title: 'Policy And Governance',
+        sections: [{ title: 'Confirmation', lines: renderConfirmLines(width, this._confirm) }],
+        palette: C,
+      });
+      while (lines.length < height) {
+        lines.push(createEmptyLine(width));
+      }
+      return lines.slice(0, height);
+    }
     const snapshot = this._state.getSnapshot();
+    const summaryLine = this._buildSummary(width, snapshot);
     const content = this._buildContent(width, snapshot);
+    const dashboardActive = snapshot.divergence !== null;
+    const hintsLine = buildKeyboardHints(width, [
+      { keys: '↑/↓', label: 'scroll' },
+      { keys: 's', label: 'simulate' },
+      { keys: 'f', label: 'preflight' },
+      { keys: 'l', label: 'lint' },
+      { keys: 'p', label: 'promote' },
+      { keys: 'b', label: 'rollback' },
+      ...(dashboardActive ? [{ keys: 'r', label: 'record divergence snapshot' }] : []),
+    ], C);
+    const summarySection = { lines: [summaryLine] };
     const governanceSection = resolveScrollablePanelSection(width, height, {
-      footerLines: [buildPanelLine(width, [['  Up/Down scroll  r record divergence trend snapshot', C.dim]])],
+      footerLines: [hintsLine],
       palette: C,
+      beforeSections: [summarySection],
       section: {
         title: 'Governance',
         scrollableLines: content,
         scrollOffset: this._scrollOffset,
         minRows: 4,
+        appendWindowSummary: content.length > 0 ? { dimColor: C.dim } : undefined,
       },
     });
     this._scrollOffset = governanceSection.scrollOffset;
     const lines = buildPanelWorkspace(width, height, {
       title: 'Policy And Governance',
-      sections: [governanceSection.section],
-      footerLines: [buildPanelLine(width, [['  Up/Down scroll  r record divergence trend snapshot', C.dim]])],
+      sections: [summarySection, governanceSection.section],
+      footerLines: [hintsLine],
       palette: C,
     });
     while (lines.length < height) {
@@ -113,6 +244,28 @@ export class PolicyPanel extends BasePanel {
     return lines.slice(0, height);
   }
 
+  /** Top-of-panel posture summary: the highest-signal governance state at a glance. */
+  private _buildSummary(width: number, snapshot: PolicyPanelSnapshot): Line {
+    const preflight = snapshot.lastPreflightReview;
+    const divergence = snapshot.divergence;
+    const lintCount = snapshot.lintFindings.length;
+    const preflightStatus = preflight ? preflight.status : 'none';
+    const preflightColor = !preflight
+      ? C.dim
+      : preflight.status === 'pass'
+        ? C.good
+        : preflight.status === 'warn'
+          ? C.warn
+          : C.bad;
+    const gateStatus = divergence?.gate.status ?? 'n/a';
+    return buildKeyValueLine(width, [
+      { label: 'bundles', value: `${snapshot.current ? 1 : 0}+${snapshot.candidate ? 1 : 0}c`, valueColor: snapshot.current || snapshot.candidate ? C.value : C.dim },
+      { label: 'preflight', value: preflightStatus.toUpperCase(), valueColor: preflightColor },
+      { label: 'gate', value: gateStatus, valueColor: gateColor(gateStatus) },
+      { label: 'lint', value: String(lintCount), valueColor: lintCount > 0 ? C.warn : C.dim },
+    ], C);
+  }
+
   private _buildContent(width: number, snapshot: PolicyPanelSnapshot): Line[] {
     const lines: Line[] = [];
     const current = snapshot.current;
@@ -123,8 +276,22 @@ export class PolicyPanel extends BasePanel {
     const simulationSummary = snapshot.lastSimulationSummary;
     const preflightReview = snapshot.lastPreflightReview;
 
-    if (!current && !candidate) {
-      lines.push(buildPanelLine(width, [[' No policy bundles loaded. Use /policy load to begin.', C.empty]]));
+    const nothingRecorded = !current && !candidate && !divergence
+      && snapshot.history.length === 0 && permissionAudit.length === 0
+      && lintFindings.length === 0 && !simulationSummary && !preflightReview;
+    if (nothingRecorded) {
+      // No divergence dashboard exists in this branch by construction
+      // (nothingRecorded requires !divergence), so the gate is honestly 'n/a'.
+      lines.push(...buildEmptyState(
+        width,
+        ' No policy bundles loaded.',
+        'Bundle: none active, none candidate. Gate: n/a.',
+        [
+          { command: '/policy load', summary: 'load a policy bundle to begin governance review' },
+        ],
+        C,
+      ));
+      return lines;
     }
 
     if (current) {
@@ -160,17 +327,41 @@ export class PolicyPanel extends BasePanel {
     }
 
     if (snapshot.diff) {
+      const diff = snapshot.diff;
       lines.push(buildPanelLine(width, [[' Diff', C.label]]));
       lines.push(buildPanelLine(width, [
+        ['  ', C.label],
+        [`${diff.fromBundleId} -> ${diff.toBundleId}`, C.value],
         ['  Changes: ', C.label],
-        [String(snapshot.diff.totalChanges), C.value],
-        ['  Added: ', C.label],
-        [String(snapshot.diff.added.length), C.ok],
-        ['  Removed: ', C.label],
-        [String(snapshot.diff.removed.length), C.error],
-        ['  Changed: ', C.label],
-        [String(snapshot.diff.changed.length), C.warn],
+        [String(diff.totalChanges), C.value],
       ]));
+      if (diff.added.length > 0) {
+        lines.push(buildPanelLine(width, [['  Added', C.good]]));
+        for (const rule of diff.added.slice(0, 5)) {
+          lines.push(buildPanelLine(width, [
+            ['    + ', C.good],
+            [truncateDisplay(`${rule.id} (${rule.type}, effect=${rule.effect})`, Math.max(0, width - 6)), C.value],
+          ]));
+        }
+      }
+      if (diff.removed.length > 0) {
+        lines.push(buildPanelLine(width, [['  Removed', C.bad]]));
+        for (const rule of diff.removed.slice(0, 5)) {
+          lines.push(buildPanelLine(width, [
+            ['    - ', C.bad],
+            [truncateDisplay(`${rule.id} (${rule.type}, effect=${rule.effect})`, Math.max(0, width - 6)), C.value],
+          ]));
+        }
+      }
+      if (diff.changed.length > 0) {
+        lines.push(buildPanelLine(width, [['  Changed', C.warn]]));
+        for (const change of diff.changed.slice(0, 5)) {
+          lines.push(buildPanelLine(width, [
+            ['    ~ ', C.warn],
+            [truncateDisplay(change.ruleId, Math.max(0, width - 6)), C.value],
+          ]));
+        }
+      }
     }
 
     if (divergence) {
@@ -189,6 +380,35 @@ export class PolicyPanel extends BasePanel {
         ['  Trend points: ', C.label],
         [String(divergence.trend.length), C.value],
       ]));
+      const prefixEntries = Object.entries(divergence.report.byCommandPrefix);
+      if (prefixEntries.length > 0) {
+        lines.push(buildPanelLine(width, [['  Divergence by command prefix', C.label]]));
+        for (const [prefix, stats] of prefixEntries.slice(0, 5)) {
+          lines.push(buildPanelLine(width, [
+            ['    ', C.label],
+            [truncateDisplay(prefix, Math.max(0, Math.floor(width * 0.4))), C.value],
+            ['  ', C.label],
+            [fmtRate(stats.divergenceRate), stats.divergenceRate > 0 ? C.warn : C.good],
+            ['  ', C.label],
+            [`${stats.total}/${stats.totalEvaluations}`, C.dim],
+          ]));
+        }
+      }
+      const classEntries = Object.entries(divergence.report.byToolClass) as Array<[string, DivergenceStats | undefined]>;
+      const populatedClassEntries = classEntries.filter((entry): entry is [string, DivergenceStats] => entry[1] !== undefined);
+      if (populatedClassEntries.length > 0) {
+        lines.push(buildPanelLine(width, [['  Divergence by tool class', C.label]]));
+        for (const [cls, stats] of populatedClassEntries.slice(0, 5)) {
+          lines.push(buildPanelLine(width, [
+            ['    ', C.label],
+            [truncateDisplay(cls, Math.max(0, Math.floor(width * 0.4))), C.value],
+            ['  ', C.label],
+            [fmtRate(stats.divergenceRate), stats.divergenceRate > 0 ? C.warn : C.good],
+            ['  ', C.label],
+            [`${stats.total}/${stats.totalEvaluations}`, C.dim],
+          ]));
+        }
+      }
     }
 
     if (snapshot.history.length > 0) {
@@ -209,7 +429,7 @@ export class PolicyPanel extends BasePanel {
       lines.push(buildPanelLine(width, [[' Permission Audit', C.label]]));
       for (const entry of permissionAudit.slice(0, 5)) {
         const outcome = entry.approved === undefined ? 'pending' : entry.approved ? 'approved' : 'denied';
-        const outcomeColor = entry.approved === undefined ? C.warn : entry.approved ? C.ok : C.error;
+        const outcomeColor = entry.approved === undefined ? C.warn : entry.approved ? C.good : C.bad;
         lines.push(buildPanelLine(width, [
           ['  ', C.label],
           [entry.tool, C.value],
@@ -220,7 +440,7 @@ export class PolicyPanel extends BasePanel {
         ]));
         lines.push(buildPanelLine(width, [
           ['    ', C.label],
-          [entry.summary.slice(0, Math.max(0, width - 6)), C.dim],
+          [truncateDisplay(entry.summary, Math.max(0, width - 6)), C.dim],
         ]));
       }
     }
@@ -228,29 +448,24 @@ export class PolicyPanel extends BasePanel {
     if (lintFindings.length > 0) {
       lines.push(buildPanelLine(width, [[' Policy Lint', C.label]]));
       for (const finding of lintFindings.slice(0, 5)) {
-        const color = finding.severity === 'error' ? C.error : finding.severity === 'warn' ? C.warn : C.info;
+        const color = finding.severity === 'error' ? C.bad : finding.severity === 'warn' ? C.warn : C.info;
         lines.push(buildPanelLine(width, [
           ['  ', C.label],
           [finding.severity.toUpperCase(), color],
           ['  ', C.label],
-          [finding.message.slice(0, Math.max(0, width - 14)), color],
+          [truncateDisplay(finding.message, Math.max(0, width - 14)), color],
         ]));
       }
     }
 
-    if (!preflightReview) {
-      if (!current && !candidate && !divergence && snapshot.history.length === 0 && permissionAudit.length === 0 && lintFindings.length === 0 && !simulationSummary) {
-        lines.push(buildPanelLine(width, [[' Preflight Review', C.label]]));
-        lines.push(buildPanelLine(width, [['  No proactive preflight review recorded yet.', C.empty]]));
-      }
-    } else {
+    if (preflightReview) {
       lines.push(buildPanelLine(width, [[' Preflight Review', C.label]]));
       const statusColor =
         preflightReview.status === 'pass'
-          ? C.ok
+          ? C.good
           : preflightReview.status === 'warn'
             ? C.warn
-            : C.error;
+            : C.bad;
       lines.push(buildPanelLine(width, [
         ['  Status: ', C.label],
         [preflightReview.status.toUpperCase(), statusColor],
@@ -261,39 +476,34 @@ export class PolicyPanel extends BasePanel {
       ]));
       lines.push(buildPanelLine(width, [
         ['  ', C.label],
-        [preflightReview.summary.slice(0, Math.max(0, width - 2)), C.dim],
+        [truncateDisplay(preflightReview.summary, Math.max(0, width - 2)), C.dim],
       ]));
       for (const issue of preflightReview.issues.slice(0, 4)) {
-        const issueColor = issue.severity === 'error' ? C.error : issue.severity === 'warn' ? C.warn : C.info;
+        const issueColor = issue.severity === 'error' ? C.bad : issue.severity === 'warn' ? C.warn : C.info;
         lines.push(buildPanelLine(width, [
           ['  ', C.label],
           [issue.severity.toUpperCase(), issueColor],
           ['  ', C.label],
-          [issue.message.slice(0, Math.max(0, width - 14)), issueColor],
+          [truncateDisplay(issue.message, Math.max(0, width - 14)), issueColor],
         ]));
       }
     }
 
-    if (!simulationSummary) {
-      if (!current && !candidate && !divergence && snapshot.history.length === 0 && permissionAudit.length === 0 && lintFindings.length === 0 && !preflightReview) {
-        lines.push(buildPanelLine(width, [[' Simulation Samples', C.label]]));
-        lines.push(buildPanelLine(width, [['  No concrete simulation samples recorded yet.', C.empty]]));
-      }
-    } else {
+    if (simulationSummary) {
       lines.push(buildPanelLine(width, [[' Simulation Samples', C.label]]));
       lines.push(buildPanelLine(width, [
         ['  Mode: ', C.label],
         [simulationSummary.mode, C.info],
         ['  Diverged: ', C.label],
-        [`${simulationSummary.divergentScenarios}/${simulationSummary.totalScenarios}`, simulationSummary.divergentScenarios > 0 ? C.warn : C.ok],
+        [`${simulationSummary.divergentScenarios}/${simulationSummary.totalScenarios}`, simulationSummary.divergentScenarios > 0 ? C.warn : C.good],
         ['  Allowed(actual/sim): ', C.label],
         [`${simulationSummary.allowedByActual}/${simulationSummary.allowedBySimulated}`, C.value],
       ]));
       for (const result of simulationSummary.results.slice(0, 4)) {
-        const color = result.diverged ? C.warn : (result.authoritativeDecision.allowed ? C.ok : C.error);
+        const color = result.diverged ? C.warn : (result.authoritativeDecision.allowed ? C.good : C.bad);
         lines.push(buildPanelLine(width, [
           ['  ', C.label],
-          [result.scenario.label.slice(0, Math.max(0, width - 40)), C.value],
+          [truncateDisplay(result.scenario.label, Math.max(0, width - 40)), C.value],
           ['  ', C.label],
           [(result.authoritativeDecision.allowed ? 'allow' : 'deny').toUpperCase(), color],
           ['  ', C.label],
@@ -302,7 +512,6 @@ export class PolicyPanel extends BasePanel {
       }
     }
 
-    lines.push(buildPanelLine(width, [['  /policy opens this panel. Press r to record a divergence trend snapshot.', C.dim]]));
     return lines;
   }
 }

package/src/panels/polish-core.ts

@@ -0,0 +1,162 @@
+import type { Line } from '../types/grid.ts';
+import { createEmptyLine, createStyledCell } from '../types/grid.ts';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import { resolveUiTones } from '../renderer/theme.ts';
+
+// DEFAULT_PANEL_PALETTE is built from the mode-resolved chrome tones
+// (resolveUiTones) rather than the static UI_TONES constant — WO-001 single
+// read path. Mode is fixed to 'dark' until the terminal-bg-probe lands.
+const UI_TONES = resolveUiTones('dark');
+
+// ---------------------------------------------------------------------------
+// Panel palette + core line primitives.
+//
+// The leaf foundation of the panel formatting toolkit: both `polish.ts` and
+// `polish-tables.ts` build on these. Kept dependency-free (only grid /
+// terminal-width / ui-primitives) so it never participates in an import cycle.
+// All symbols are re-exported from `polish.ts` — panels import from there.
+// ---------------------------------------------------------------------------
+
+export interface PanelPalette {
+  readonly label: string;
+  readonly value: string;
+  readonly dim: string;
+  readonly info: string;
+  readonly good?: string;
+  readonly warn?: string;
+  readonly bad?: string;
+  readonly empty: string;
+  readonly header?: string;
+  readonly headerBg?: string;
+  readonly surfaceBg?: string;
+  readonly sectionBg?: string;
+  readonly summaryBg?: string;
+  readonly inputBg?: string;
+  readonly accent?: string;
+  readonly selectBg?: string;
+}
+
+export const DEFAULT_PANEL_PALETTE: Readonly<Required<PanelPalette>> = {
+  header: UI_TONES.fg.primary,
+  headerBg: UI_TONES.bg.title,
+  label: UI_TONES.fg.muted,
+  value: UI_TONES.fg.primary,
+  dim: UI_TONES.fg.dim,
+  info: UI_TONES.state.info,
+  good: UI_TONES.state.good,
+  warn: UI_TONES.state.warn,
+  bad: UI_TONES.state.bad,
+  empty: UI_TONES.fg.empty,
+  surfaceBg: UI_TONES.bg.surface,
+  sectionBg: UI_TONES.bg.section,
+  summaryBg: UI_TONES.bg.summary,
+  inputBg: UI_TONES.bg.input,
+  accent: UI_TONES.fg.secondary,
+  selectBg: UI_TONES.bg.selected,
+} as const;
+
+/**
+ * Extend the base panel palette with domain-specific colors.
+ *
+ * Convention: raw hex colors may only live inside a palette constant declared
+ * at the top of a panel file, not inline in render calls.
+ *
+ * @example
+ * ```ts
+ * const C = extendPalette(DEFAULT_PANEL_PALETTE, {
+ *   decision: '#38bdf8',
+ *   incident: '#ef4444',
+ * });
+ * ```
+ */
+export function extendPalette<T extends Record<string, string>>(
+  base: typeof DEFAULT_PANEL_PALETTE,
+  extras: T,
+): typeof DEFAULT_PANEL_PALETTE & T {
+  return { ...base, ...extras };
+}
+
+export function buildPanelLine(
+  width: number,
+  segments: Array<StyledPanelSegment | [string, string, string?]>,
+): Line {
+  return buildStyledPanelLine(
+    width,
+    segments.map((seg) =>
+      Array.isArray(seg) ? { text: seg[0], fg: seg[1], bg: seg[2] } : seg,
+    ),
+  );
+}
+
+export interface StyledPanelSegment {
+  readonly text: string;
+  readonly fg: string;
+  readonly bg?: string;
+  readonly bold?: boolean;
+  readonly dim?: boolean;
+}
+
+export function buildSelectablePanelLine(
+  width: number,
+  segments: ReadonlyArray<StyledPanelSegment>,
+  options: { selected?: boolean; selectedBg?: string; fillFg?: string; fillBg?: string; leadingMarker?: string } = {},
+): Line {
+  const selected = options.selected ?? false;
+  const selectedBg = selected ? (options.selectedBg ?? DEFAULT_PANEL_PALETTE.selectBg) : '';
+  const fillBg = selectedBg || options.fillBg || '';
+  const fillFg = options.fillFg ?? '';
+  const cells = createEmptyLine(width);
+  if (fillBg) {
+    for (let col = 0; col < width; col++) {
+      cells[col] = createStyledCell(' ', { bg: fillBg, fg: fillFg });
+    }
+  }
+
+  let col = 0;
+  if (selected && options.leadingMarker) {
+    for (const ch of options.leadingMarker) {
+      const charWidth = getDisplayWidth(ch);
+      if (charWidth <= 0 || col + charWidth > width) break;
+      cells[col] = createStyledCell(ch, { fg: DEFAULT_PANEL_PALETTE.info, bg: selectedBg, bold: true });
+      if (charWidth > 1 && col + 1 < width) cells[col + 1] = createStyledCell(' ', { fg: DEFAULT_PANEL_PALETTE.info, bg: selectedBg, bold: true });
+      col += charWidth;
+    }
+  }
+  for (const segment of segments) {
+    const fg = segment.fg;
+    const bg = segment.bg ?? fillBg;
+    for (const ch of segment.text) {
+      const charWidth = getDisplayWidth(ch);
+      if (charWidth <= 0) continue;
+      if (col + charWidth > width) return cells;
+      cells[col] = createStyledCell(ch, {
+        fg,
+        bg,
+        bold: segment.bold ?? false,
+        dim: segment.dim ?? false,
+      });
+      if (charWidth > 1 && col + 1 < width) {
+        cells[col + 1] = createStyledCell(' ', {
+          fg,
+          bg,
+          bold: segment.bold ?? false,
+          dim: segment.dim ?? false,
+        });
+      }
+      col += charWidth;
+    }
+  }
+
+  while (col < width) {
+    cells[col++] = createStyledCell(' ', { bg: fillBg, fg: fillFg });
+  }
+  return cells;
+}
+
+export function buildStyledPanelLine(
+  width: number,
+  segments: ReadonlyArray<StyledPanelSegment>,
+  options: { fillBg?: string; fillFg?: string } = {},
+): Line {
+  return buildSelectablePanelLine(width, segments, options);
+}