@pi-unipi/unipi 2.6.0 → 2.6.2

package/packages/updater/src/tui/list-detail-overlay.ts

@@ -0,0 +1,260 @@
+/**
+ * @pi-unipi/updater — Shared List+Detail TUI Overlay
+ *
+ * Parameterized overlay for browse-a-list-then-view-detail patterns.
+ * Used by both the changelog and readme browsers.
+ */
+
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { boxInnerWidth } from "@pi-unipi/core";
+
+/** Pad content to exact visible width. */
+function padVisible(content: string, targetWidth: number): string {
+  const vw = visibleWidth(content);
+  const pad = Math.max(0, targetWidth - vw);
+  return content + " ".repeat(pad);
+}
+
+/** Configuration for a list+detail overlay. */
+export interface ListDetailConfig<T> {
+  /** Header title (e.g. " 📋 Changelog ") */
+  title: string;
+  /** Message when list is empty */
+  emptyMessage: string;
+  /** Footer text in list view */
+  listFooter: string;
+  /** Footer text in detail view */
+  detailFooter: string;
+  /** Load list entries lazily on first render */
+  loadEntries: () => T[];
+  /** Render a single list item line (without the │ borders) */
+  renderItem: (entry: T, selected: boolean, theme: Theme) => string;
+  /** Render the detail title line for an entry */
+  renderDetailTitle: (entry: T, theme: Theme) => string;
+  /** Render the detail body lines for an entry */
+  renderDetailBody: (entry: T, innerWidth: number, theme: Theme) => string[];
+  /** Optional: if set, Enter in list view calls this instead of default detail switch.
+   *  Return true to switch to detail view, false to stay. */
+  onEnter?: (entry: T, tui: import("@earendil-works/pi-tui").TUI, theme: Theme) => boolean;
+  /** Optional: if set, Esc from detail view closes the overlay instead of returning to list */
+  closeOnDetailBack?: boolean;
+  /** Optional: open directly to a specific entry's detail view */
+  openDirectIndex?: number;
+}
+
+type View = "list" | "detail";
+
+/**
+ * Create a list+detail overlay component.
+ * Returns the ctx.ui.custom() callback.
+ */
+export function createListDetailOverlay<T>(
+  config: ListDetailConfig<T>,
+): (
+  tui: import("@earendil-works/pi-tui").TUI,
+  theme: Theme,
+  _kb: import("@earendil-works/pi-coding-agent").KeybindingsManager,
+  done: (result: { viewed: boolean } | null) => void,
+) => { render: (width: number) => string[]; handleInput: (data: string) => void; invalidate: () => void; focused: boolean } {
+  return (tui, theme, _kb, done) => {
+    const state: {
+      view: View;
+      entries: T[];
+      listIndex: number;
+      listScroll: number;
+      detailScroll: number;
+    } = {
+      view: "list",
+      entries: [],
+      listIndex: 0,
+      listScroll: 0,
+      detailScroll: 0,
+    };
+
+    let loaded = false;
+    const ensureLoaded = () => {
+      if (loaded) return;
+      state.entries = config.loadEntries();
+      if (config.openDirectIndex !== undefined && config.openDirectIndex >= 0 && config.openDirectIndex < state.entries.length) {
+        state.listIndex = config.openDirectIndex;
+        state.view = "detail";
+        state.detailScroll = 0;
+      }
+      loaded = true;
+    };
+
+    const render = (width: number): string[] => {
+      ensureLoaded();
+
+      const innerWidth = boxInnerWidth(width);
+      const lines: string[] = [];
+
+      // ── Header ──────────────────────────────────────────────────────
+      lines.push(theme.fg("accent", `╭${"─".repeat(innerWidth)}╮`));
+      lines.push(
+        theme.fg("accent", "│") +
+        padVisible(theme.fg("accent", theme.bold(config.title)), innerWidth) +
+        theme.fg("accent", "│"),
+      );
+      lines.push(theme.fg("accent", `├${"─".repeat(innerWidth)}┤`));
+
+      // ── Content ─────────────────────────────────────────────────────
+      if (state.view === "list") {
+        renderListView(lines, innerWidth);
+      } else {
+        renderDetailView(lines, innerWidth);
+      }
+
+      // ── Footer ──────────────────────────────────────────────────────
+      lines.push(theme.fg("accent", `├${"─".repeat(innerWidth)}┤`));
+      const footer = state.view === "list" ? config.listFooter : config.detailFooter;
+      lines.push(
+        theme.fg("accent", "│") +
+        padVisible(truncateToWidth(footer, innerWidth), innerWidth) +
+        theme.fg("accent", "│"),
+      );
+      lines.push(theme.fg("accent", `╰${"─".repeat(innerWidth)}╯`));
+
+      return lines;
+    };
+
+    const renderListView = (lines: string[], innerWidth: number) => {
+      if (state.entries.length === 0) {
+        lines.push(
+          theme.fg("accent", "│") +
+          padVisible(theme.fg("muted", `  ${config.emptyMessage}`), innerWidth) +
+          theme.fg("accent", "│"),
+        );
+        return;
+      }
+
+      state.listIndex = Math.min(state.listIndex, state.entries.length - 1);
+      state.listIndex = Math.max(0, state.listIndex);
+
+      const maxLines = 20;
+      if (state.listIndex < state.listScroll) state.listScroll = state.listIndex;
+      if (state.listIndex >= state.listScroll + maxLines) {
+        state.listScroll = state.listIndex - maxLines + 1;
+      }
+
+      const visible = state.entries.slice(state.listScroll, state.listScroll + maxLines);
+
+      for (let i = 0; i < visible.length; i++) {
+        const entry = visible[i]!;
+        const globalIdx = state.listScroll + i;
+        const selected = globalIdx === state.listIndex;
+        const line = config.renderItem(entry, selected, theme);
+        lines.push(
+          theme.fg("accent", "│") +
+          padVisible(
+            selected ? theme.bg("selectedBg", truncateToWidth(line, innerWidth)) : truncateToWidth(line, innerWidth),
+            innerWidth,
+          ) +
+          theme.fg("accent", "│"),
+        );
+      }
+    };
+
+    const renderDetailView = (lines: string[], innerWidth: number) => {
+      const entry = state.entries[state.listIndex];
+      if (!entry) {
+        lines.push(
+          theme.fg("accent", "│") +
+          padVisible(theme.fg("muted", "  No entry selected."), innerWidth) +
+          theme.fg("accent", "│"),
+        );
+        return;
+      }
+
+      const title = config.renderDetailTitle(entry, theme);
+      lines.push(
+        theme.fg("accent", "│") +
+        padVisible(truncateToWidth(`  ${title}`, innerWidth), innerWidth) +
+        theme.fg("accent", "│"),
+      );
+      lines.push(
+        theme.fg("accent", "│") +
+        padVisible("", innerWidth) +
+        theme.fg("accent", "│"),
+      );
+
+      const bodyLines = config.renderDetailBody(entry, innerWidth, theme);
+      const maxScroll = Math.max(0, bodyLines.length - 15);
+      state.detailScroll = Math.min(state.detailScroll, maxScroll);
+      state.detailScroll = Math.max(0, state.detailScroll);
+
+      const visible = bodyLines.slice(state.detailScroll, state.detailScroll + 15);
+      for (const line of visible) {
+        lines.push(
+          theme.fg("accent", "│") +
+          padVisible(truncateToWidth(`  ${line}`, innerWidth), innerWidth) +
+          theme.fg("accent", "│"),
+        );
+      }
+    };
+
+    const handleInput = (data: string) => {
+      ensureLoaded();
+
+      // Close from list view
+      if ((matchesKey(data, Key.escape) || data === "q") && state.view === "list") {
+        done({ viewed: true });
+        return;
+      }
+
+      // Back from detail view
+      if ((matchesKey(data, Key.escape) || data === "q") && state.view === "detail") {
+        if (config.closeOnDetailBack) {
+          done({ viewed: true });
+          return;
+        }
+        state.view = "list";
+        state.detailScroll = 0;
+        tui.requestRender();
+        return;
+      }
+
+      // Navigation
+      if (state.view === "list") {
+        if (matchesKey(data, Key.down) || data === "j") {
+          state.listIndex = Math.min(state.listIndex + 1, state.entries.length - 1);
+        } else if (matchesKey(data, Key.up) || data === "k") {
+          state.listIndex = Math.max(state.listIndex - 1, 0);
+        } else if (matchesKey(data, Key.enter)) {
+          if (state.entries.length > 0) {
+            if (config.onEnter) {
+              const entry = state.entries[state.listIndex]!;
+              const shouldSwitch = config.onEnter(entry, tui, theme);
+              if (shouldSwitch) {
+                state.view = "detail";
+                state.detailScroll = 0;
+              }
+            } else {
+              state.view = "detail";
+              state.detailScroll = 0;
+            }
+          }
+        } else if (data === "g") {
+          state.listIndex = 0;
+        } else if (data === "G") {
+          state.listIndex = state.entries.length - 1;
+        }
+      } else {
+        if (matchesKey(data, Key.down) || data === "j") {
+          state.detailScroll++;
+        } else if (matchesKey(data, Key.up) || data === "k") {
+          state.detailScroll = Math.max(0, state.detailScroll - 1);
+        } else if (data === "g") {
+          state.detailScroll = 0;
+        } else if (data === "G") {
+          state.detailScroll = 999999;
+        }
+      }
+
+      tui.requestRender();
+    };
+
+    return { render, handleInput, invalidate: () => {}, focused: true };
+  };
+}

package/packages/updater/src/tui/readme-overlay.ts

@@ -7,231 +7,74 @@
  */
 
 import { readFileSync } from "fs";
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { discoverReadmes, resolveReadmePath } from "../readme.js";
 import { renderMarkdown } from "../markdown.js";
+import { createListDetailOverlay } from "./list-detail-overlay.js";
 import type { ReadmeEntry } from "../../types.js";
-import { boxInnerWidth } from "@pi-unipi/core";
 
-type View = "list" | "content";
-
-interface ReadmeState {
-  view: View;
-  entries: ReadmeEntry[];
-  listIndex: number;
-  listScroll: number;
-  contentScroll: number;
-  contentLines: string[];
-}
-
-/**
- * Pad content to exact visible width.
- */
-function padVisible(content: string, targetWidth: number): string {
-  const vw = visibleWidth(content);
-  const pad = Math.max(0, targetWidth - vw);
-  return content + " ".repeat(pad);
+interface ReadmeParams {
+  openDirect?: string;
 }
 
 /**
  * Render the readme overlay.
  */
-export function renderReadmeOverlay(params?: { openDirect?: string }) {
-  return (
-    tui: import("@earendil-works/pi-tui").TUI,
-    theme: Theme,
-    _kb: import("@earendil-works/pi-coding-agent").KeybindingsManager,
-    done: (result: { viewed: boolean } | null) => void,
-  ) => {
-    const state: ReadmeState = {
-      view: "list",
-      entries: [],
-      listIndex: 0,
-      listScroll: 0,
-      contentScroll: 0,
-      contentLines: [],
-    };
-
-    let loaded = false;
-    const ensureLoaded = () => {
-      if (loaded) return;
-      state.entries = discoverReadmes();
-
+export function renderReadmeOverlay(params?: ReadmeParams) {
+  // Cache for rendered markdown content (keyed by entry path)
+  const contentCache = new Map<string, string[]>();
+  let openDirectIndex: number | undefined;
+
+  return createListDetailOverlay<ReadmeEntry>({
+    title: " 📖 README Browser ",
+    emptyMessage: "No README files found.",
+    listFooter: " j/k navigate  Enter read  q/Esc close",
+    detailFooter: " j/k scroll  q/Esc back to list",
+
+    loadEntries: () => {
+      const entries = discoverReadmes();
       if (params?.openDirect) {
         const readmePath = resolveReadmePath(params.openDirect);
         if (readmePath) {
-          const content = readFileSync(readmePath, "utf-8");
-          state.contentLines = renderMarkdown(content, (tui.terminal?.columns ?? 80) - 4, theme);
-          state.view = "content";
+          const idx = entries.findIndex((e) => e.path === readmePath);
+          if (idx >= 0) {
+            openDirectIndex = idx;
+            // Pre-load the content
+            const content = readFileSync(readmePath, "utf-8");
+            const lines = renderMarkdown(content, (process.stdout.columns ?? 80) - 4, undefined as any);
+            contentCache.set(readmePath, lines);
+          }
         }
       }
-      loaded = true;
-    };
-
-    const render = (width: number): string[] => {
-      ensureLoaded();
-
-      const innerWidth = boxInnerWidth(width);
-      const lines: string[] = [];
-
-      // ── Header ──────────────────────────────────────────────────────
-      lines.push(theme.fg("accent", `╭${"─".repeat(innerWidth)}╮`));
-      lines.push(
-        theme.fg("accent", "│") +
-        padVisible(theme.fg("accent", theme.bold(" 📖 README Browser ")), innerWidth) +
-        theme.fg("accent", "│"),
-      );
-      lines.push(theme.fg("accent", `├${"─".repeat(innerWidth)}┤`));
-
-      // ── Content ─────────────────────────────────────────────────────
-      if (state.view === "list") {
-        renderListView(lines, innerWidth);
-      } else {
-        renderContentView(lines, innerWidth);
-      }
-
-      // ── Footer ──────────────────────────────────────────────────────
-      lines.push(theme.fg("accent", `├${"─".repeat(innerWidth)}┤`));
-      const footer =
-        state.view === "list"
-          ? ` ${theme.fg("accent", "j/k")} navigate  ${theme.fg("success", "Enter")} read  ${theme.fg("error", "q/Esc")} close`
-          : ` ${theme.fg("accent", "j/k")} scroll  ${theme.fg("error", "q/Esc")} back to list`;
-      lines.push(
-        theme.fg("accent", "│") +
-        padVisible(truncateToWidth(footer, innerWidth), innerWidth) +
-        theme.fg("accent", "│"),
-      );
-      lines.push(theme.fg("accent", `╰${"─".repeat(innerWidth)}╯`));
-
-      return lines;
-    };
-
-    const renderListView = (lines: string[], innerWidth: number) => {
-      if (state.entries.length === 0) {
-        lines.push(
-          theme.fg("accent", "│") +
-          padVisible(theme.fg("muted", "  No README files found."), innerWidth) +
-          theme.fg("accent", "│"),
-        );
-        return;
-      }
-
-      state.listIndex = Math.min(state.listIndex, state.entries.length - 1);
-      state.listIndex = Math.max(0, state.listIndex);
-
-      const maxLines = 20;
-      if (state.listIndex < state.listScroll) state.listScroll = state.listIndex;
-      if (state.listIndex >= state.listScroll + maxLines) {
-        state.listScroll = state.listIndex - maxLines + 1;
-      }
-
-      const visible = state.entries.slice(state.listScroll, state.listScroll + maxLines);
-
-      for (let i = 0; i < visible.length; i++) {
-        const entry = visible[i]!;
-        const globalIdx = state.listScroll + i;
-        const selected = globalIdx === state.listIndex;
-        const prefix = selected ? theme.fg("accent", "▸ ") : "  ";
-
-        const name = selected ? theme.bold(entry.name) : theme.fg("text", entry.name);
-        const version = theme.fg("muted", `v${entry.version}`);
-        const line = ` ${prefix}${name}  ${version}`;
-        lines.push(
-          theme.fg("accent", "│") +
-          padVisible(
-            selected ? theme.bg("selectedBg", truncateToWidth(line, innerWidth)) : truncateToWidth(line, innerWidth),
-            innerWidth,
-          ) +
-          theme.fg("accent", "│"),
-        );
-      }
-    };
-
-    const renderContentView = (lines: string[], innerWidth: number) => {
-      if (state.contentLines.length === 0) {
-        lines.push(
-          theme.fg("accent", "│") +
-          padVisible(theme.fg("muted", "  No content available."), innerWidth) +
-          theme.fg("accent", "│"),
-        );
-        return;
-      }
-
-      const maxLines = 20;
-      const maxScroll = Math.max(0, state.contentLines.length - maxLines);
-      state.contentScroll = Math.min(state.contentScroll, maxScroll);
-      state.contentScroll = Math.max(0, state.contentScroll);
-
-      const visible = state.contentLines.slice(state.contentScroll, state.contentScroll + maxLines);
-      for (const line of visible) {
-        lines.push(
-          theme.fg("accent", "│") +
-          padVisible(truncateToWidth(` ${line}`, innerWidth), innerWidth) +
-          theme.fg("accent", "│"),
-        );
-      }
-    };
-
-    const handleInput = (data: string) => {
-      ensureLoaded();
-
-      // Close from list view
-      if ((matchesKey(data, Key.escape) || data === "q") && state.view === "list") {
-        done({ viewed: true });
-        return;
+      return entries;
+    },
+
+    openDirectIndex,
+    closeOnDetailBack: !!params?.openDirect,
+
+    renderItem: (entry, selected, theme) => {
+      const name = selected ? theme.bold(entry.name) : theme.fg("text", entry.name);
+      const version = theme.fg("muted", `v${entry.version}`);
+      const prefix = selected ? theme.fg("accent", "▸ ") : "  ";
+      return ` ${prefix}${name}  ${version}`;
+    },
+
+    renderDetailTitle: (entry, theme) =>
+      `${theme.bold(entry.name)} — ${theme.fg("muted", `v${entry.version}`)}`,
+
+    renderDetailBody: (entry, _innerWidth, theme) => {
+      // Return cached content if available
+      if (contentCache.has(entry.path)) {
+        return contentCache.get(entry.path)!;
       }
-
-      // Back from content view
-      if ((matchesKey(data, Key.escape) || data === "q") && state.view === "content") {
-        if (params?.openDirect) {
-          done({ viewed: true });
-          return;
-        }
-        state.view = "list";
-        state.contentScroll = 0;
-        tui.requestRender();
-        return;
-      }
-
-      if (state.view === "list") {
-        if (matchesKey(data, Key.down) || data === "j") {
-          state.listIndex = Math.min(state.listIndex + 1, state.entries.length - 1);
-        } else if (matchesKey(data, Key.up) || data === "k") {
-          state.listIndex = Math.max(state.listIndex - 1, 0);
-        } else if (matchesKey(data, Key.enter)) {
-          if (state.entries.length > 0) {
-            const entry = state.entries[state.listIndex]!;
-            try {
-              const content = readFileSync(entry.path, "utf-8");
-              state.contentLines = renderMarkdown(content, (tui.terminal?.columns ?? 80) - 4, theme);
-              state.contentScroll = 0;
-              state.view = "content";
-            } catch {
-              state.contentLines = ["  Error reading README file."];
-              state.view = "content";
-            }
-          }
-        } else if (data === "g") {
-          state.listIndex = 0;
-        } else if (data === "G") {
-          state.listIndex = state.entries.length - 1;
-        }
-      } else {
-        if (matchesKey(data, Key.down) || data === "j") {
-          state.contentScroll++;
-        } else if (matchesKey(data, Key.up) || data === "k") {
-          state.contentScroll = Math.max(0, state.contentScroll - 1);
-        } else if (data === "g") {
-          state.contentScroll = 0;
-        } else if (data === "G") {
-          state.contentScroll = 999999;
-        }
+      try {
+        const content = readFileSync(entry.path, "utf-8");
+        const lines = renderMarkdown(content, (process.stdout.columns ?? 80) - 4, theme);
+        contentCache.set(entry.path, lines);
+        return lines;
+      } catch {
+        return ["  Error reading README file."];
       }
-
-      tui.requestRender();
-    };
-
-    return { render, handleInput, invalidate: () => {}, focused: true };
-  };
+    },
+  });
 }

package/packages/updater/src/tui/settings-overlay.ts

@@ -5,6 +5,7 @@
  * Space cycles options, Enter saves, Esc cancels.
  */
 
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import {
   loadConfig,
   saveConfig,
@@ -22,21 +23,6 @@ const TEAL = `${ESC}[36m`;
 const GREEN = `${ESC}[32m`;
 const RESET = `${ESC}[0m`;
 
-/** Truncate string to visible width */
-function trunc(text: string, width: number): string {
-  let vw = 0;
-  let result = "";
-  let inEsc = false;
-  for (const ch of text) {
-    if (ch === "\x1b") { inEsc = true; result += ch; continue; }
-    if (inEsc) { result += ch; if (ch === "m") inEsc = false; continue; }
-    if (vw >= width) break;
-    result += ch;
-    vw++;
-  }
-  return result;
-}
-
 /**
  * Render the settings overlay.
  */
@@ -58,7 +44,7 @@ export function renderSettingsOverlay() {
     const render = (width: number): string[] => {
       const lines: string[] = [];
 
-      lines.push(trunc(` ${BOLD}⚙ Updater Settings${RESET}`, width));
+      lines.push(truncateToWidth(` ${BOLD}⚙ Updater Settings${RESET}`, width));
       lines.push("─".repeat(width));
       lines.push("");
 
@@ -67,7 +53,7 @@ export function renderSettingsOverlay() {
       const row0Selected = state.row === 0;
       const row0Prefix = row0Selected ? `${TEAL}▸${RESET} ` : "  ";
       lines.push(
-        trunc(
+        truncateToWidth(
           `  ${row0Prefix}${BOLD}Check Interval${RESET}  ${DIM}${intervalLabel}${RESET}`,
           width,
         ),
@@ -81,7 +67,7 @@ export function renderSettingsOverlay() {
             : `${DIM}○ ${opt.label}${RESET}`;
         })
         .join("   ");
-      lines.push(trunc(`      ${intervalLine}`, width));
+      lines.push(truncateToWidth(`      ${intervalLine}`, width));
       lines.push("");
 
       // Row 1: Auto Update
@@ -89,7 +75,7 @@ export function renderSettingsOverlay() {
       const row1Selected = state.row === 1;
       const row1Prefix = row1Selected ? `${TEAL}▸${RESET} ` : "  ";
       lines.push(
-        trunc(
+        truncateToWidth(
           `  ${row1Prefix}${BOLD}Auto Update${RESET}  ${DIM}${modeLabel}${RESET}`,
           width,
         ),
@@ -103,12 +89,12 @@ export function renderSettingsOverlay() {
             : `${DIM}○ ${mode}${RESET}`;
         })
         .join("   ");
-      lines.push(trunc(`      ${modeLine}`, width));
+      lines.push(truncateToWidth(`      ${modeLine}`, width));
       lines.push("");
 
       lines.push("─".repeat(width));
       lines.push(
-        trunc(
+        truncateToWidth(
           `  j/k: navigate  Space: cycle  ${GREEN}Enter: save${RESET}  ${DIM}Esc: cancel${RESET}`,
           width,
         ),
@@ -119,9 +105,10 @@ export function renderSettingsOverlay() {
 
     const handleInput = (data: string) => {
       const key = data.toLowerCase();
+      const keyRaw = data;
 
       // Close without saving
-      if (key === "\x1b") {
+      if (matchesKey(keyRaw, Key.escape)) {
         done({ saved: false });
         return;
       }
@@ -134,9 +121,9 @@ export function renderSettingsOverlay() {
       }
 
       // Navigate rows
-      if (key === "j" || key === "\x1b[B") {
+      if (key === "j" || matchesKey(keyRaw, Key.down)) {
         state.row = Math.min(state.row + 1, 1);
-      } else if (key === "k" || key === "\x1b[A") {
+      } else if (key === "k" || matchesKey(keyRaw, Key.up)) {
         state.row = Math.max(state.row - 1, 0);
       }
 
@@ -156,7 +143,7 @@ export function renderSettingsOverlay() {
       }
 
       // Cycle with left/right
-      if (key === "h" || key === "\x1b[D") {
+      if (key === "h" || matchesKey(keyRaw, Key.left)) {
         if (state.row === 0) {
           const currentIdx = intervalOptions.findIndex(
             (opt) => opt.ms === state.config.checkIntervalMs,
@@ -169,7 +156,7 @@ export function renderSettingsOverlay() {
           state.config.autoUpdate = modeOptions[prevIdx];
         }
       }
-      if (key === "l" || key === "\x1b[C") {
+      if (key === "l" || matchesKey(keyRaw, Key.right)) {
         if (state.row === 0) {
           const currentIdx = intervalOptions.findIndex(
             (opt) => opt.ms === state.config.checkIntervalMs,