@pi-unipi/updater 2.6.1 → 2.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/updater",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "description": "Auto-updater, changelog browser, and readme browser for Unipi — checks npm registry, renders CHANGELOG.md and README.md files in TUI overlays",
   "type": "module",
   "main": "index.ts",
@@ -45,8 +45,12 @@
     "typescript": "^6.0.0"
   },
   "pi": {
-    "extensions": [],
-    "skills": [],
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
     "prompts": [],
     "themes": []
   }

package/src/changelog.ts

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { findPackageRoot } from "@pi-unipi/core";
+import { findPackageRoot, compareVersions } from "@pi-unipi/core";
 import { isNewerVersion } from "./version.js";
 import type { ChangelogEntry } from "../types.js";
 
@@ -155,18 +155,3 @@ export function getNewerVersions(
   }
   return result;
 }
-
-/**
- * Compare semver strings (simple lexicographic for x.y.z format).
- * Returns positive if a > b, negative if a < b, 0 if equal.
- */
-export function compareVersions(a: string, b: string): number {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const na = pa[i] ?? 0;
-    const nb = pb[i] ?? 0;
-    if (na !== nb) return na - nb;
-  }
-  return 0;
-}

package/src/index.ts

@@ -165,9 +165,4 @@ export default function updaterExtension(pi: ExtensionAPI): void {
       // Update check failure — silent, non-critical
     }
   });
-
-  // Cleanup on session shutdown
-  pi.on("session_shutdown", async () => {
-    // No cleanup needed
-  });
 }

package/src/installer.ts

@@ -2,12 +2,11 @@
  * @pi-unipi/updater — Update installer
  *
  * Wraps child_process.exec for installing updates via pi CLI.
- * Emits UPDATE_APPLIED or UPDATE_ERROR events.
  */
 
 import { exec } from "child_process";
 import { promisify } from "util";
-import { getInstalledPackageVersion, emitEvent, UNIPI_EVENTS } from "@pi-unipi/core";
+import { getInstalledPackageVersion } from "@pi-unipi/core";
 import type { InstallResult } from "../types.js";
 
 const execAsync = promisify(exec);
@@ -20,14 +19,11 @@ const INSTALL_TIMEOUT_MS = 60000;
  * Uses pi CLI: `pi install npm:@pi-unipi/unipi`
  * Returns structured result with success/failure info.
  */
-export async function installUpdate(
-  pi?: { events: { emit: (name: string, payload: unknown) => void } },
-): Promise<InstallResult> {
+export async function installUpdate(): Promise<InstallResult> {
   const thisDir = new URL("..", import.meta.url).pathname;
-  const installedBefore = getInstalledPackageVersion(thisDir, "@pi-unipi/unipi");
 
   try {
-    const { stdout, stderr } = await execAsync(
+    await execAsync(
       "pi install npm:@pi-unipi/unipi",
       {
         timeout: INSTALL_TIMEOUT_MS,
@@ -38,34 +34,16 @@ export async function installUpdate(
     // Get new version after install
     const installedAfter = getInstalledPackageVersion(thisDir, "@pi-unipi/unipi");
 
-    const result: InstallResult = {
+    return {
       success: true,
       version: installedAfter,
     };
-
-    // Emit success event
-    if (pi) {
-      emitEvent(pi, UNIPI_EVENTS.UPDATE_APPLIED, {
-        previousVersion: installedBefore,
-        newVersion: installedAfter,
-      });
-    }
-
-    return result;
   } catch (err: unknown) {
     const errorMessage = (err instanceof Error && 'stderr' in err ? String((err as Error & { stderr?: string }).stderr) : undefined)
       || (err instanceof Error ? err.message : undefined)
       || String(err)
       || "Unknown install error";
 
-    // Emit error event
-    if (pi) {
-      emitEvent(pi, UNIPI_EVENTS.UPDATE_ERROR, {
-        error: errorMessage,
-        phase: "install",
-      });
-    }
-
     return {
       success: false,
       error: errorMessage,

package/src/markdown.ts

@@ -1,173 +1,27 @@
 /**
  * @pi-unipi/updater — Markdown terminal renderer
  *
- * Renders markdown to terminal-formatted strings.
- * When a Theme is provided, uses the full Markdown component from pi-tui
- * with theme-aware styling. Falls back to simple ANSI rendering otherwise.
+ * Renders markdown to terminal-formatted strings using the full
+ * Markdown component from pi-tui with theme-aware styling.
  */
 
 import { Markdown } from "@earendil-works/pi-tui";
-import type { MarkdownTheme } from "@earendil-works/pi-tui";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
 /**
  * Render markdown text to terminal-formatted lines.
  *
- * When a Theme is provided, uses the full Markdown component from pi-tui
- * with syntax highlighting, proper list nesting, tables, etc.
+ * Uses pi-tui's Markdown component with syntax highlighting,
+ * proper list nesting, tables, etc.
  *
  * @param text - Markdown text to render
  * @param width - Available width for rendering
- * @param theme - Optional Theme for styled rendering
+ * @param theme - Theme for styled rendering
  * @returns Array of rendered terminal lines
  */
-export function renderMarkdown(text: string, width: number, theme?: Theme): string[] {
-  if (theme) {
-    return renderWithTheme(text, width, theme);
-  }
-  return renderSimple(text, width);
-}
-
-/**
- * Render using the full Markdown component with theme support.
- */
-function renderWithTheme(text: string, width: number, theme: Theme): string[] {
+export function renderMarkdown(text: string, width: number, theme: Theme): string[] {
   const mdTheme = getMarkdownTheme();
   const md = new Markdown(text, 1, 0, mdTheme);
   return md.render(width);
 }
-
-/**
- * Simple fallback renderer using basic ANSI codes.
- * Used when no Theme is available.
- */
-
-/** ANSI escape codes */
-const ESC = "\x1b";
-const BOLD = `${ESC}[1m`;
-const DIM = `${ESC}[2m`;
-const UNDERLINE = `${ESC}[4m`;
-const RESET = `${ESC}[0m`;
-
-/** Wrap text in ANSI formatting */
-function fmt(code: string, text: string): string {
-  return `${code}${text}${RESET}`;
-}
-
-/** Word-wrap a line to fit within width */
-function wordWrap(line: string, width: number): string[] {
-  // Strip ANSI for length calculation but preserve in output
-  const stripped = line.replace(/\x1b\[[0-9;]*m/g, "");
-  if (stripped.length <= width) return [line];
-
-  const words = line.split(/(\s+)/);
-  const result: string[] = [];
-  let currentLine = "";
-  let currentWidth = 0;
-
-  for (const word of words) {
-    const wordWidth = word.replace(/\x1b\[[0-9;]*m/g, "").length;
-    if (currentWidth + wordWidth > width && currentLine) {
-      result.push(currentLine);
-      currentLine = word.trimStart();
-      currentWidth = currentLine.replace(/\x1b\[[0-9;]*m/g, "").length;
-    } else {
-      currentLine += word;
-      currentWidth += wordWidth;
-    }
-  }
-  if (currentLine) result.push(currentLine);
-  return result.length > 0 ? result : [""];
-}
-
-/** Apply inline formatting: bold, italic, code, links */
-function formatInline(text: string): string {
-  // Inline code: `code`
-  text = text.replace(/`([^`]+)`/g, (_, code) => fmt(DIM, code));
-
-  // Bold: **text**
-  text = text.replace(/\*\*([^*]+)\*\*/g, (_, bold) => fmt(BOLD, bold));
-
-  // Italic: *text*
-  text = text.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, (_, italic) => fmt(UNDERLINE, italic));
-
-  // Links: [text](url) → underlined text
-  text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, (_, linkText) => fmt(UNDERLINE, linkText));
-
-  return text;
-}
-
-/**
- * Simple markdown renderer (fallback).
- */
-function renderSimple(text: string, width: number): string[] {
-  const lines = text.split("\n");
-  const result: string[] = [];
-  let inCodeBlock = false;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-
-    // Code fence toggle
-    if (trimmed.startsWith("```")) {
-      inCodeBlock = !inCodeBlock;
-      continue;
-    }
-
-    // Inside code block — dim, no formatting
-    if (inCodeBlock) {
-      const formatted = fmt(DIM, line);
-      result.push(...wordWrap(formatted, width));
-      continue;
-    }
-
-    // Heading: #, ##, ###
-    if (trimmed.startsWith("### ")) {
-      const heading = trimmed.slice(4);
-      const formatted = fmt(BOLD + UNDERLINE, heading);
-      result.push(...wordWrap(formatted, width));
-      continue;
-    }
-    if (trimmed.startsWith("## ")) {
-      const heading = trimmed.slice(3);
-      const formatted = fmt(BOLD, heading);
-      result.push(...wordWrap(formatted, width));
-      continue;
-    }
-    if (trimmed.startsWith("# ")) {
-      const heading = trimmed.slice(2);
-      const formatted = fmt(BOLD, heading);
-      result.push(...wordWrap(formatted, width));
-      continue;
-    }
-
-    // Bullet list: - or *
-    if (trimmed.startsWith("- ") || trimmed.startsWith("* ")) {
-      const content = trimmed.slice(2);
-      const formatted = "  • " + formatInline(content);
-      result.push(...wordWrap(formatted, width));
-      continue;
-    }
-
-    // Numbered list: 1. 2. etc.
-    const numberMatch = trimmed.match(/^(\d+)\.\s+(.+)$/);
-    if (numberMatch) {
-      const formatted = `  ${numberMatch[1]}. ${formatInline(numberMatch[2])}`;
-      result.push(...wordWrap(formatted, width));
-      continue;
-    }
-
-    // Empty line — preserve spacing
-    if (!trimmed) {
-      result.push("");
-      continue;
-    }
-
-    // Regular paragraph — apply inline formatting
-    const formatted = formatInline(trimmed);
-    result.push(...wordWrap(formatted, width));
-  }
-
-  return result;
-}

package/src/settings.ts

@@ -56,21 +56,6 @@ export function saveConfig(config: UpdaterConfig): void {
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
 
-/** Validate config, returning list of error messages */
-export function validateConfig(config: UpdaterConfig): string[] {
-  const errors: string[] = [];
-
-  if (!VALID_MODES.includes(config.autoUpdate)) {
-    errors.push(`autoUpdate must be one of: ${VALID_MODES.join(", ")}`);
-  }
-
-  if (config.checkIntervalMs < 60000) {
-    errors.push("checkIntervalMs must be at least 60000 (1 minute)");
-  }
-
-  return errors;
-}
-
 /** Get human-readable label for an interval */
 export function getIntervalLabel(ms: number): string {
   for (const [label, value] of Object.entries(VALID_INTERVALS)) {

package/src/tui/changelog-overlay.ts

@@ -1,257 +1,65 @@
 /**
  * @pi-unipi/updater — Changelog TUI Overlay
  *
- * Version list with Current/New labels, Enter opens detail view, Esc/q back.
- * Uses ctx.ui.custom() overlay API with component return pattern.
+ * Version list with Current/New labels, Enter opens detail view.
  */
 
 import { existsSync } from "fs";
-import { join } from "path";
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { parseChangelog, resolveChangelogPath } from "../changelog.js";
 import { renderMarkdown } from "../markdown.js";
-import { getInstalledPackageVersion, boxInnerWidth } from "@pi-unipi/core";
+import { getInstalledPackageVersion } from "@pi-unipi/core";
+import { createListDetailOverlay } from "./list-detail-overlay.js";
 import type { ChangelogEntry } from "../../types.js";
 
-type View = "list" | "detail";
-
-interface ChangelogState {
-  view: View;
-  entries: ChangelogEntry[];
-  listIndex: number;
-  listScroll: number;
-  detailScroll: number;
-  installedVersion: 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);
-}
-
 /**
  * Render the changelog overlay.
  */
 export function renderChangelogOverlay() {
-  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 installedVersion = getInstalledPackageVersion(
-      new URL("..", import.meta.url).pathname,
-      "@pi-unipi/unipi",
-    );
-
-    const state: ChangelogState = {
-      view: "list",
-      entries: [],
-      listIndex: 0,
-      listScroll: 0,
-      detailScroll: 0,
-      installedVersion,
-    };
-
-    // Load changelog
-    let loaded = false;
-    const ensureLoaded = () => {
-      if (loaded) return;
+  const installedVersion = getInstalledPackageVersion(
+    new URL("..", import.meta.url).pathname,
+    "@pi-unipi/unipi",
+  );
+
+  return createListDetailOverlay<ChangelogEntry>({
+    title: " 📋 Changelog ",
+    emptyMessage: "No changelog available.",
+    listFooter: " j/k navigate  Enter view details  q/Esc close",
+    detailFooter: " j/k scroll  q/Esc back to list",
+
+    loadEntries: () => {
       const changelogPath = resolveChangelogPath();
-      if (existsSync(changelogPath)) {
-        state.entries = parseChangelog(changelogPath);
-      }
-      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(" 📋 Changelog ")), innerWidth) +
-        theme.fg("accent", "│"),
-      );
-      lines.push(theme.fg("accent", `├${"─".repeat(innerWidth)}┤`));
-
-      // ── Content ─────────────────────────────────────────────────────
-      if (state.view === "list") {
-        renderListView(lines, innerWidth);
+      return existsSync(changelogPath) ? parseChangelog(changelogPath) : [];
+    },
+
+    renderItem: (entry, selected, theme) => {
+      let label: string;
+      if (entry.version === "Unreleased") {
+        label = theme.fg("muted", "Unreleased");
+      } else if (entry.version === installedVersion) {
+        label = theme.fg("success", "✓ Current");
       } else {
-        renderDetailView(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")} view details  ${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 changelog available."), innerWidth) +
-          theme.fg("accent", "│"),
-        );
-        return;
+        const pa = entry.version.split(".").map(Number);
+        const pb = installedVersion.split(".").map(Number);
+        const isNewer =
+          pa[0]! > pb[0]! ||
+          (pa[0] === pb[0] && pa[1]! > pb[1]!) ||
+          (pa[0] === pb[0] && pa[1] === pb[1] && pa[2]! > pb[2]!);
+        label = isNewer ? theme.fg("warning", "↑ New") : "";
       }
 
-      state.listIndex = Math.min(state.listIndex, state.entries.length - 1);
-      state.listIndex = Math.max(0, state.listIndex);
-
-      // Show visible entries
-      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 version = selected ? theme.bold(entry.version) : theme.fg("text", entry.version);
+      const date = entry.date ? ` — ${theme.fg("muted", entry.date)}` : "";
+      const prefix = selected ? theme.fg("accent", "▸ ") : "  ";
+      return ` ${prefix}${version}${date}  ${label}`;
+    },
 
-      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", "▸ ") : "  ";
-
-        let label: string;
-        if (entry.version === "Unreleased") {
-          label = theme.fg("muted", "Unreleased");
-        } else if (entry.version === state.installedVersion) {
-          label = theme.fg("success", "✓ Current");
-        } else {
-          const pa = entry.version.split(".").map(Number);
-          const pb = state.installedVersion.split(".").map(Number);
-          const isNewer =
-            pa[0]! > pb[0]! ||
-            (pa[0] === pb[0] && pa[1]! > pb[1]!) ||
-            (pa[0] === pb[0] && pa[1] === pb[1] && pa[2]! > pb[2]!);
-          label = isNewer ? theme.fg("warning", "↑ New") : "";
-        }
-
-        const version = selected ? theme.bold(entry.version) : theme.fg("text", entry.version);
-        const date = entry.date ? ` — ${theme.fg("muted", entry.date)}` : "";
-        const line = ` ${prefix}${version}${date}  ${label}`;
-        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 = entry.date
+    renderDetailTitle: (entry, theme) =>
+      entry.date
         ? `${theme.bold(entry.version)} — ${theme.fg("muted", entry.date)}`
-        : `${theme.bold(entry.version)} — ${theme.fg("muted", "Unreleased")}`;
-      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 = renderMarkdown(entry.body, innerWidth - 2, 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") {
-        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) {
-            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();
-    };
+        : `${theme.bold(entry.version)} — ${theme.fg("muted", "Unreleased")}`,
 
-    return { render, handleInput, invalidate: () => {}, focused: true };
-  };
+    renderDetailBody: (entry, innerWidth, theme) =>
+      renderMarkdown(entry.body, innerWidth - 2, theme),
+  });
 }

package/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/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/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,

package/src/version.ts

@@ -1,36 +1,7 @@
 /**
  * @pi-unipi/updater — version comparison helpers
- */
-
-/**
- * Compare two semver-ish version strings.
- * Returns 1 when a > b, -1 when a < b, 0 when equal.
  *
- * This intentionally handles the simple versions Unipi publishes (x.y.z)
- * without adding a runtime dependency. Non-numeric suffixes are ignored for
- * ordering, so `2.0.5` and `v2.0.5` compare equal.
+ * Re-exported from @pi-unipi/core for backward compatibility.
  */
-export function compareVersions(a: string, b: string): number {
-  const parse = (version: string): number[] => version
-    .replace(/^v/, "")
-    .split(/[.-]/)
-    .slice(0, 3)
-    .map((part) => {
-      const parsed = Number.parseInt(part, 10);
-      return Number.isNaN(parsed) ? 0 : parsed;
-    });
-
-  const left = parse(a);
-  const right = parse(b);
-  for (let i = 0; i < 3; i++) {
-    const diff = (left[i] ?? 0) - (right[i] ?? 0);
-    if (diff > 0) return 1;
-    if (diff < 0) return -1;
-  }
-  return 0;
-}
 
-/** Return true only when `latest` is newer than `current`. */
-export function isNewerVersion(latest: string, current: string): boolean {
-  return compareVersions(latest, current) > 0;
-}
+export { compareVersions, isNewerVersion } from "@pi-unipi/core";