github-search-cli 0.8.1 → 0.9.0

package/src/tui.ts

@@ -32,40 +32,105 @@ import {
   ScrollBoxRenderable,
 } from "@opentui/core";
 import type { Repo, SearchOptions, SortStrategy } from "./types";
-import { parseQuery, applyFlagFilters, validateQuery, suggestFor, rankRepos, createGitHubSearch, type Logger } from "./search";
-import { fetchTrendingRepos, tabSince, TAB_NAMES, fmtStars, type TrendingRepo } from "./trending";
+import {
+  parseQuery,
+  applyFlagFilters,
+  validateQuery,
+  suggestFor,
+  rankRepos,
+  createGitHubSearch,
+  SearchModule,
+  TrendingAdapter,
+  type Logger,
+} from "./search";
+import {
+  tabSince,
+  TAB_NAMES,
+  fmtStars,
+} from "./trending";
 import { loadConfig } from "./config";
 import { buildHelpSections, HELP_KEYS_COLUMN } from "./help";
-import { SearchCliError, NetworkError, RateLimitError, BadQueryError, NoResultsError } from "./errors";
-import { appendHistory, readHistory, deleteHistoryEntry, clearHistory, rotateHistory } from "./history";
-import { getBookmarks, isBookmarked, toggleBookmark, removeBookmark } from "./bookmarks";
-import { getSavedSearches, saveSearch, deleteSavedSearch, touchSavedSearch } from "./saved-searches";
+import {
+  SearchCliError,
+  NetworkError,
+  RateLimitError,
+  BadQueryError,
+  NoResultsError,
+} from "./errors";
+import {
+  appendHistory,
+  readHistory,
+  deleteHistoryEntry,
+  clearHistory,
+  rotateHistory,
+} from "./history";
+import {
+  getBookmarks,
+  isBookmarked,
+  toggleBookmark,
+  removeBookmark,
+} from "./bookmarks";
+import {
+  getSavedSearches,
+  saveSearch,
+  deleteSavedSearch,
+  touchSavedSearch,
+} from "./saved-searches";
 import { saveSession, restoreSession } from "./session";
 import { fetchDeepDive, buildDeepDiveText } from "./deepdive";
 import { buildComparisonTable } from "./compare";
 import { fetchTopics, type TopicItem } from "./explore";
-import { exportToFile, type ExportFormat } from "./export";
+import { exportToFile, type ExportFormat } from "./output";
 import { loadTheme } from "./themes";
 import { StatusManager } from "./status";
-import { addNotification, getNotifications, dismissNotification, dismissAll } from "./notifications";
+import {
+  addNotification,
+  getNotifications,
+  dismissNotification,
+  dismissAll,
+} from "./notifications";
 import { formatShare, copyToClipboard, type ShareFormat } from "./share";
 import { nextTip } from "./tips";
 import { openUrl } from "./open-url";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = join(__dirname, "..");
 
-// ─── Theme ────────────────────────────────────────────────────────────
+let cachedVersion: string | null = null;
+import {
+  checkForUpdate,
+  shouldCheckUpdate,
+  markUpdateChecked,
+  snoozeUpdateNotices,
+  suppressUpdateNotices,
+  performUpdate,
+} from "./update-check";
+import { debugLog } from "./storage";
 const colors = {
-  bg: "#1e1e2e",
-  surface: "#181825",
-  text: "#cdd6f4",
-  muted: "#6c7086",
+  bg: "#3D3B3B",
+  surface: "#4a4848",
+  surfaceAlt: "#525050",
+  text: "#e0e4f0",
+  muted: "#a8a6a6",
   blue: "#89b4fa",
   green: "#a6e3a1",
   yellow: "#f9e2af",
   red: "#f38ba8",
   teal: "#94e2d5",
-  border: "#45475a",
-  selectionBg: "#2d5bcf",
+  purple: "#cba6f7",
+  orange: "#fab387",
+  border: "#1C1C1C",
+  borderAlt: "#2a2a2a",
+  separator: "#1C1C1C",  // Dark thin colorblock - thicker than border, visible separation
+  selectionBg: "#2A2A9C",
   selectionText: "#ffffff",
+  // Premium accents for the command menu
+  accent: "#89b4fa",
+  accentDim: "#587cf5",
+  surfaceDim: "#1a1919",
+  borderAccent: "#1a1919",
 };
 
 // ─── Logger ───────────────────────────────────────────────────────────
@@ -90,11 +155,21 @@ export async function launchBrowser(): Promise<void> {
   try {
     renderer = await createCliRenderer();
   } catch (err) {
-    console.error(
-      "Failed to start the interactive browser. OpenTUI native backend unavailable.\n",
-      `Reason: ${err instanceof Error ? err.message : String(err)}\n`,
-      "Install Zig or use a platform with native OpenTUI support.",
-    );
+    const isNode = process.versions.bun === undefined;
+    if (isNode) {
+      console.error("\n❌  The interactive TUI requires Bun runtime.\n");
+      console.error("  Install Bun:  curl -fsSL https://bun.sh/install | bash");
+      console.error("  Then run:    bunx ghfind");
+      console.error("\n  Or use non-interactive mode (works on Node.js):");
+      console.error("  ghfind \"language:Rust\" --json | jq '.[].fullName'");
+      console.error("  ghfind --trending --count");
+    } else {
+      console.error(
+        "Failed to start the interactive browser. OpenTUI native backend unavailable.\n",
+        `Reason: ${err instanceof Error ? err.message : String(err)}\n`,
+        "Install Zig or use a platform with native OpenTUI support.",
+      );
+    }
     process.exit(1);
     return;
   }
@@ -121,33 +196,48 @@ export async function launchBrowser(): Promise<void> {
   let currentQueryInput = session?.query ?? "";
   let isLoading = false;
   let currentMode: "search" | "trending" = session?.mode ?? "search";
-  let trendingTab: typeof TAB_NAMES[number] = (session?.trendingTab as typeof TAB_NAMES[number]) ?? "This Week";
+  let trendingTab: (typeof TAB_NAMES)[number] =
+    (session?.trendingTab as (typeof TAB_NAMES)[number]) ?? "This Week";
   let trendingPeriod = "this week";
   let graphFullscreen = false;
   let chartCommitData: number[] = [];
-  let currentOverlay: "none" | "history" | "bookmarks" | "saved" | "help" | "topics" | "export" | "compare" | "notifications" | "share" | "leader" | "readme" = "none";
+  let currentOverlay:
+    | "none"
+    | "history"
+    | "bookmarks"
+    | "saved"
+    | "help"
+    | "topics"
+    | "export"
+    | "compare"
+    | "notifications"
+    | "share"
+    | "leader"
+    | "readme"
+    | "update" = "none";
   let currentPage = 1;
   let totalCount = 0;
   let deepDiveActive = false;
   let compareList: Repo[] = [];
   let quitArmed = false;
 
-
   // ── Header bar ──────────────────────────────────────────────────────
   const header = new TextRenderable(renderer, {
     content:
-      " ghfind — GitHub repo browser   [/]search  [Space]menu  [?]help  [q]uit",
+      " ghfind — GitHub repo browser   [/]search  [Space]menu  [\u2192]open  [?]help  [q]uit",
     backgroundColor: colors.bg,
     color: colors.muted,
     height: 1,
+    borderBottom: true,
+    borderBottomColor: colors.border,
   });
-  root.add(header);
 
   // ── Trending tab bar (hidden in search mode) ────────────────────────
   const trendingTabBox = new BoxRenderable(renderer, {
     flexDirection: "row",
     height: 1,
-    backgroundColor: colors.bg,
+    backgroundColor: colors.surface,
+    // No border — pure contract-edge separation via text contrast
     paddingX: 1,
     visible: false,
   });
@@ -180,30 +270,45 @@ export async function launchBrowser(): Promise<void> {
       }
     });
   }
+  root.add(header);
   root.add(trendingTabBox);
 
   // ── Search input row ────────────────────────────────────────────────
   const searchBox = new BoxRenderable(renderer, {
-    visible: true, // hidden in trending mode
-    border: true,
-    borderColor: colors.blue,
-    paddingX: 1,
-    height: 3,
+    visible: true,
+    borderBottom: true,
+    borderBottomColor: colors.border,
+    title: " SEARCH ",
+    titleColor: colors.blue,
+    width: "100%",
+    flexDirection: "row",
+    paddingTop: 0,
+    paddingBottom: 0,
+    backgroundColor: colors.surface,
   });
   const searchInput = new InputRenderable(renderer, {
-    placeholder: "Search GitHub repos (e.g. rust cli, or language:Rust stars:>100)",
+    placeholder:
+      "Search GitHub repos (e.g. rust cli, or language:Rust stars:>100)",
     value: "",
+    backgroundColor: colors.surface,
+    textColor: colors.text,
+    borderColor: colors.blue,
+    selectedBorderColor: colors.blue,
+    paddingX: 0,
+    flexGrow: 1,
   });
   searchBox.add(searchInput);
   root.add(searchBox);
 
   // ── Toolbar (sort + limit indicator) ────────────────────────────────
   const toolbarText = new TextRenderable(renderer, {
-    content: formatToolbar(currentSort, currentLimit),
+    content: formatToolbar(currentSort, currentLimit, totalCount),
     visible: true, // hidden in trending mode
-    backgroundColor: colors.bg,
+    backgroundColor: colors.surface,                  // Surface panel
     color: colors.muted,
     height: 1,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     paddingX: 1,
   });
   root.add(toolbarText);
@@ -219,8 +324,8 @@ export async function launchBrowser(): Promise<void> {
 
   // Results pane
   const resultsBox = new BoxRenderable(renderer, {
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Results ",
     titleColor: colors.blue,
     width: "50%",
@@ -229,11 +334,16 @@ export async function launchBrowser(): Promise<void> {
     focusable: false,
   });
   const resultsSelect = new SelectRenderable(renderer, {
-    options: [{ name: "", description: "Type a query and press Enter to search", value: null }],
+    options: [
+      {
+        name: "",
+        description: "Type a query and press Enter to search",
+        value: null,
+      },
+    ],
     showDescription: false,
     showSelectionIndicator: false,
     flexGrow: 1,
-    backgroundColor: colors.bg,
     textColor: colors.text,
     selectedBackgroundColor: colors.selectionBg,
     selectedTextColor: colors.selectionText,
@@ -245,8 +355,8 @@ export async function launchBrowser(): Promise<void> {
 
   // Detail / Graph pane
   const detailBox = new BoxRenderable(renderer, {
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Details ",
     titleColor: colors.green,
     width: "50%",
@@ -254,6 +364,7 @@ export async function launchBrowser(): Promise<void> {
     paddingX: 1,
     paddingY: 1,
     focusable: false,
+    backgroundColor: colors.surface,
   });
   const detailText = new TextRenderable(renderer, {
     content: "",
@@ -265,8 +376,6 @@ export async function launchBrowser(): Promise<void> {
   body.add(detailBox);
   root.add(body);
 
-
-
   // ── Overlay system ──────────────────────────────────────────────────
 
   // Hide main content so overlays can take 100% of the content area
@@ -298,7 +407,10 @@ export async function launchBrowser(): Promise<void> {
     notifsBox.visible = false;
     shareBox.visible = false;
     leaderBox.visible = false;
+    leaderDim.visible = false;
     readmeBox.visible = false;
+    updateBox.visible = false;
+    updateDim.visible = false;
 
     if (type === "none") {
       currentOverlay = "none";
@@ -307,18 +419,38 @@ export async function launchBrowser(): Promise<void> {
       return;
     }
     currentOverlay = type;
-    hideMainContent();
-    if (type === "help") { helpBox.visible = true; }
-    else if (type === "history") { historyBox.visible = true; }
-    else if (type === "bookmarks") { bookmarksBox.visible = true; }
-    else if (type === "saved") { savedBox.visible = true; }
-    else if (type === "topics") { topicsBox.visible = true; }
-    else if (type === "export") { exportBox.visible = true; }
-    else if (type === "compare") { compareBox.visible = true; }
-    else if (type === "notifications") { notifsBox.visible = true; }
-    else if (type === "share") { shareBox.visible = true; }
-    else if (type === "leader") { leaderBox.visible = true; }
-    else if (type === "readme") { readmeBox.visible = true; }
+    // Leader menu is a floating overlay — main content stays visible behind it
+    if (type !== "leader") {
+      hideMainContent();
+    }
+    if (type === "help") {
+      helpBox.visible = true;
+    } else if (type === "history") {
+      historyBox.visible = true;
+    } else if (type === "bookmarks") {
+      bookmarksBox.visible = true;
+    } else if (type === "saved") {
+      savedBox.visible = true;
+    } else if (type === "topics") {
+      topicsBox.visible = true;
+    } else if (type === "export") {
+      exportBox.visible = true;
+    } else if (type === "compare") {
+      compareBox.visible = true;
+    } else if (type === "notifications") {
+      notifsBox.visible = true;
+    } else if (type === "share") {
+      shareBox.visible = true;
+    } else if (type === "leader") {
+      leaderDim.visible = true;
+      leaderBox.visible = true;
+    } else if (type === "readme") {
+      readmeBox.visible = true;
+    } else if (type === "update") {
+      updateDim.visible = true;
+      updateBox.visible = true;
+      updateSelect.focus();
+    }
     renderer.requestRender();
   }
 
@@ -328,8 +460,8 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
   });
   const helpScroll = new ScrollBoxRenderable(renderer, {
     flexGrow: 1,
@@ -347,10 +479,12 @@ export async function launchBrowser(): Promise<void> {
   });
   for (const section of helpSections) {
     const sectionBox = new BoxRenderable(renderer, {
-      border: true,
-      borderColor: colors.border,
+      borderBottom: true,
+      borderBottomColor: colors.border,
       title: section.title,
-      titleColor: (colors as Record<string, string>)[section.titleColor] ?? section.titleColor,
+      titleColor:
+        (colors as Record<string, string>)[section.titleColor] ??
+        section.titleColor,
       flexDirection: "column",
       paddingY: 0,
       marginLeft: 1,
@@ -359,16 +493,20 @@ export async function launchBrowser(): Promise<void> {
     });
     for (const row of section.rows) {
       const keys = row.keys.padEnd(HELP_KEYS_COLUMN);
-      sectionBox.add(new TextRenderable(renderer, {
-        content: `  ${keys} ${row.action}`,
-        color: colors.text,
-      }));
+      sectionBox.add(
+        new TextRenderable(renderer, {
+          content: `  ${keys} ${row.action}`,
+          color: colors.text,
+        }),
+      );
     }
     if (section.note) {
-      sectionBox.add(new TextRenderable(renderer, {
-        content: `  ${section.note}`,
-        color: colors.muted,
-      }));
+      sectionBox.add(
+        new TextRenderable(renderer, {
+          content: `  ${section.note}`,
+          color: colors.muted,
+        }),
+      );
     }
     helpScroll.add(sectionBox);
   }
@@ -380,8 +518,8 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Search History ",
     titleColor: colors.blue,
   });
@@ -402,7 +540,9 @@ export async function launchBrowser(): Promise<void> {
   function refreshHistory() {
     const entries = readHistory();
     if (entries.length === 0) {
-      historySelect.options = [{ name: "(no history)", description: "", value: null }];
+      historySelect.options = [
+        { name: "(no history)", description: "", value: null },
+      ];
     } else {
       historySelect.options = entries.map((e, i) => ({
         name: `${e.query}  — ${e.mode}${e.tab ? ` (${e.tab})` : ""}`,
@@ -418,8 +558,8 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Bookmarks ",
     titleColor: colors.green,
   });
@@ -440,7 +580,9 @@ export async function launchBrowser(): Promise<void> {
   function refreshBookmarks() {
     const bookmarks = getBookmarks();
     if (bookmarks.length === 0) {
-      bookmarksSelect.options = [{ name: "(no bookmarks)", description: "", value: null }];
+      bookmarksSelect.options = [
+        { name: "(no bookmarks)", description: "", value: null },
+      ];
     } else {
       bookmarksSelect.options = bookmarks.map((b) => ({
         name: `${b.repo.fullName}  ★ ${b.repo.stars.toLocaleString()}`,
@@ -456,8 +598,8 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Saved Searches ",
     titleColor: colors.yellow,
   });
@@ -480,8 +622,8 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Topics ",
     titleColor: colors.purple ?? colors.blue,
   });
@@ -508,7 +650,9 @@ export async function launchBrowser(): Promise<void> {
         value: t,
       }));
     } catch {
-      topicsSelect.options = [{ name: "(failed to load topics)", description: "", value: null }];
+      topicsSelect.options = [
+        { name: "(failed to load topics)", description: "", value: null },
+      ];
     }
     topicsSelect.setSelectedIndex(0);
   }
@@ -518,16 +662,28 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Export ",
     titleColor: colors.green,
   });
   const exportSelect = new SelectRenderable(renderer, {
     options: [
-      { name: "  JSON", description: "Full repo data as JSON array", value: "json" },
-      { name: "  CSV", description: "Rank, name, stars, forks, language, URL", value: "csv" },
-      { name: "  Markdown", description: "Pretty table with links (paste into README)", value: "markdown" },
+      {
+        name: "  JSON",
+        description: "Full repo data as JSON array",
+        value: "json",
+      },
+      {
+        name: "  CSV",
+        description: "Rank, name, stars, forks, language, URL",
+        value: "csv",
+      },
+      {
+        name: "  Markdown",
+        description: "Pretty table with links (paste into README)",
+        value: "markdown",
+      },
       { name: "  Plain text", description: "One repo per line", value: "text" },
     ],
     showDescription: true,
@@ -547,8 +703,8 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Comparison ",
     titleColor: colors.yellow,
   });
@@ -565,8 +721,8 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Notifications ",
     titleColor: colors.yellow,
   });
@@ -594,16 +750,28 @@ export async function launchBrowser(): Promise<void> {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.border,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " Share Repo ",
     titleColor: colors.blue,
   });
   const shareSelect = new SelectRenderable(renderer, {
     options: [
-      { name: "  Markdown", description: "[owner/repo](url) — description", value: "markdown" },
-      { name: "  Plain", description: "owner/repo — description — url", value: "plain" },
-      { name: "  GitHub CLI", description: "gh repo view owner/repo", value: "gh-cli" },
+      {
+        name: "  Markdown",
+        description: "[owner/repo](url) — description",
+        value: "markdown",
+      },
+      {
+        name: "  Plain",
+        description: "owner/repo — description — url",
+        value: "plain",
+      },
+      {
+        name: "  GitHub CLI",
+        description: "gh repo view owner/repo",
+        value: "gh-cli",
+      },
       { name: "  Short", description: "owner/repo", value: "short" },
     ],
     showDescription: true,
@@ -620,7 +788,8 @@ export async function launchBrowser(): Promise<void> {
 
   function refreshCompare() {
     if (compareList.length < 2) {
-      compareText.content = "Select at least 2 repos to compare (press c to add).";
+      compareText.content =
+        "Select at least 2 repos to compare (press c to add).";
     } else {
       compareText.content = buildComparisonTable(compareList);
     }
@@ -629,7 +798,9 @@ export async function launchBrowser(): Promise<void> {
   function refreshSavedSearches() {
     const saved = getSavedSearches();
     if (saved.length === 0) {
-      savedSelect.options = [{ name: "(no saved searches)", description: "", value: null }];
+      savedSelect.options = [
+        { name: "(no saved searches)", description: "", value: null },
+      ];
     } else {
       savedSelect.options = saved.map((s) => ({
         name: `${s.name}`,
@@ -641,96 +812,547 @@ export async function launchBrowser(): Promise<void> {
   }
 
   // ── Leader menu overlay (Space key) ─────────────────────────────
+  // Dim overlay — sits behind the menu, above main content
+  const leaderDim = new BoxRenderable(renderer, {
+    visible: false,
+    position: "absolute",
+    top: 0,
+    left: 0,
+    width: "100%",
+    height: "100%",
+    backgroundColor: "#00000099", // 60% opacity black (hex alpha: 0x99 ≈ 153/255)
+  });
+  root.add(leaderDim);
+
   const leaderBox = new BoxRenderable(renderer, {
     visible: false,
-    flexGrow: 1,
-    backgroundColor: colors.bg,
+    position: "absolute",
+    width: "80%",
+    height: 18,
+    left: "10%",
+    top: "30%",
+    backgroundColor: colors.surfaceDim,
     border: true,
-    borderColor: colors.border,
-    title: " Menu ",
-    titleColor: colors.blue,
+    borderStyle: "rounded",
+    borderColor: colors.borderAccent,
+    title: " ⚙ Menu ",
+    titleColor: colors.accent,
+    titleAlignment: "left",
     flexDirection: "column",
+    paddingX: 1,
   });
   const leaderSelect = new SelectRenderable(renderer, {
     options: [{ name: "(empty)", description: "", value: null }],
     showDescription: true,
     showSelectionIndicator: true,
     flexGrow: 1,
-    backgroundColor: colors.bg,
+    backgroundColor: colors.surfaceDim,
     textColor: colors.text,
-    selectedBackgroundColor: colors.selectionBg,
+    focusedBackgroundColor: colors.surfaceDim,
+    focusedTextColor: colors.text,
+    selectedBackgroundColor: colors.accent,
     selectedTextColor: colors.selectionText,
+    descriptionColor: colors.muted,
+    selectedDescriptionColor: colors.selectionText,
     itemSpacing: 0,
   });
   const leaderFooter = new TextRenderable(renderer, {
-    content: "  ↑↓ select  Enter run  Esc/q close",
+    content: " ↑↓ select   Enter run   Esc/q close ",
     color: colors.muted,
-    backgroundColor: colors.bg,
+    backgroundColor: colors.surfaceDim,
     height: 1,
-    paddingX: 1,
+    borderTop: true,
+    borderTopColor: colors.border,
+    paddingX: 2,
   });
   leaderBox.add(leaderSelect);
   leaderBox.add(leaderFooter);
+  root.add(leaderDim);
   root.add(leaderBox);
 
-  interface LeaderItem { name: string; description: string; action: () => void; }
+  // ── Update panel overlay ────────────────────────────────────────
+  const updateDim = new BoxRenderable(renderer, {
+    visible: false,
+    position: "absolute",
+    top: 0,
+    left: 0,
+    width: "100%",
+    height: "100%",
+    backgroundColor: "#00000088",
+  });
 
-  function showLeaderMenu() {
-    const items: LeaderItem[] = [];
+  root.add(updateDim);
 
-    if (currentMode === "search") {
-      items.push(
-        { name: "  Sort", description: `Cycle sort (current: ${currentSort})`, action: () => changeSort() },
-        { name: "  Limit", description: `Cycle result limit (current: ${currentLimit})`, action: () => changeLimit() },
-        { name: "  Refresh", description: "Re-run current search", action: () => { if (currentQueryInput) doSearch(currentQueryInput); } },
-        { name: "  Toggle trending", description: "Browse GitHub trending repos", action: () => loadTrending() },
-        { name: "  Deep-dive", description: "Languages, contributors, README excerpt", action: () => { showOverlay("none"); triggerDeepDive(); } },
-        { name: "  Readme", description: "Full README viewer", action: () => { showReadme(); } },
-        { name: "  Activity graph", description: "Toggle commit chart fullscreen", action: () => toggleGraph() },
-        { name: "  Bookmark", description: "Save / unsave selected repo", action: () => toggleBookmarkOnSelected() },
-        { name: "  Compare", description: "Add/remove repo to comparison", action: () => toggleCompareOnSelected() },
-      );
-    }
+  const updateBox = new BoxRenderable(renderer, {
+    visible: false,
+    position: "absolute",
+    width: "55%",
+    height: 16,
+    left: "22.5%",
+    top: "25%",
+    backgroundColor: colors.surfaceDim,
+    border: true,
+    borderStyle: "rounded",
+    borderColor: colors.border,
+    title: " ghfind ",
+    titleColor: colors.accent,
+    titleAlignment: "left",
+    flexDirection: "column",
+    paddingX: 2,
+    paddingLeft: 2,
+    paddingRight: 2,
+  });
+  const updateText = new TextRenderable(renderer, {
+    content: "",
+    color: colors.accent,
+    backgroundColor: colors.surfaceDim,
+  });
 
-    if (currentMode === "trending") {
-      items.push(
-        { name: "  Refresh", description: "Reload trending repos", action: () => loadTrending() },
-        { name: "  Search mode", description: "Switch to query search", action: () => showSearchMode() },
-        { name: "  Readme", description: "Full README viewer", action: () => { showReadme(); } },
-        { name: "  Bookmark", description: "Save / unsave selected repo", action: () => toggleBookmarkOnSelected() },
-      );
-    }
+  // Horizontal option boxes
+  let updateSelectedOption = 0;
+
+  const updateOptionsRow = new BoxRenderable(renderer, {
+    flexDirection: "row",
+    gap: 1,
+    backgroundColor: colors.surfaceDim,
+    height: 3,
+    width: "100%",
+  });
+
+  const updateNowBox = new BoxRenderable(renderer, {
+    border: true,
+    borderColor: updateSelectedOption === 0 ? colors.yellow : colors.border,
+    backgroundColor: colors.surfaceDim,
+    height: 3,
+    width: "50%",
+    paddingLeft: 1,
+    paddingRight: 1,
+  });
+  const updateNowText = new TextRenderable(renderer, {
+    content: "   Update Now  ",
+    color: updateSelectedOption === 0 ? colors.yellow : colors.text,
+    backgroundColor: colors.surfaceDim,
+  });
+  updateNowBox.add(updateNowText);
+
+  const laterBox = new BoxRenderable(renderer, {
+    border: true,
+    borderColor: updateSelectedOption === 1 ? colors.yellow : colors.border,
+    backgroundColor: colors.surfaceDim,
+    height: 3,
+    width: "50%",
+    paddingLeft: 1,
+    paddingRight: 1,
+  });
+  const laterText = new TextRenderable(renderer, {
+    content: "  Later",
+    color: updateSelectedOption === 1 ? colors.yellow : colors.text,
+    backgroundColor: colors.surfaceDim,
+  });
+  laterBox.add(laterText);
+
+  const neverBox = new BoxRenderable(renderer, {
+    border: true,
+    borderColor: updateSelectedOption === 2 ? colors.yellow : colors.border,
+    backgroundColor: colors.surfaceDim,
+    height: 3,
+    width: "50%",
+    paddingLeft: 1,
+    paddingRight: 1,
+  });
+  const neverText = new TextRenderable(renderer, {
+    content: "  Don't show again",
+    color: updateSelectedOption === 2 ? colors.yellow : colors.text,
+    backgroundColor: colors.surfaceDim,
+  });
+  neverBox.add(neverText);
+
+  function renderUpdateOptions() {
+    updateNowBox.borderColor = updateSelectedOption === 0 ? colors.yellow : colors.border;
+    laterBox.borderColor = updateSelectedOption === 1 ? colors.yellow : colors.border;
+    neverBox.borderColor = updateSelectedOption === 2 ? colors.yellow : colors.border;
+    updateNowText.color = updateSelectedOption === 0 ? colors.yellow : colors.text;
+    laterText.color = updateSelectedOption === 1 ? colors.yellow : colors.text;
+    neverText.color = updateSelectedOption === 2 ? colors.yellow : colors.text;
+    renderer.requestRender();
+  }
+
+  updateOptionsRow.add(updateNowBox);
+  updateOptionsRow.add(laterBox);
+
+  const updateFooter = new TextRenderable(renderer, {
+    content: "  ←→ select  Enter  Esc/q close",
+    color: colors.muted,
+    backgroundColor: colors.surfaceDim,
+    height: 1,
+    paddingX: 1,
+  });
+  updateBox.add(updateText);
+  updateBox.add(updateOptionsRow);
+  updateBox.add(updateFooter);
+  root.add(updateDim);
+  root.add(updateBox);
+
+  // ── Hierarchical menu types ──────────────────────────────────────
+  interface MenuAction {
+    type: "action";
+    name: string;
+    description: string;
+    action: () => void;
+  }
+
+  interface MenuCategory {
+    type: "category";
+    name: string;
+    description: string;
+    icon: string;
+    children: MenuEntry[];
+  }
+
+  type MenuEntry = MenuAction | MenuCategory;
+
+  // ── Submenu navigation ──────────────────────────────────────────
+  interface MenuLevel {
+    title: string;
+    parentTitle: string;
+    entries: MenuEntry[];
+    selectedIndex: number;
+  }
+
+  const menuStack: MenuLevel[] = [];
+
+  function pushMenuLevel(
+    title: string,
+    parentTitle: string,
+    entries: MenuEntry[],
+    selectIndex = 0,
+  ) {
+    menuStack.push({
+      title,
+      parentTitle,
+      entries,
+      selectedIndex: leaderSelect.getSelectedIndex?.(),
+    });
+    leaderSelect.options = entries.map((e) => ({
+      name:
+        e.type === "category" ? `  ${e.icon} ${e.name} \u2192` : `  ${e.name}`,
+      description: e.description,
+      value: e,
+    }));
+    leaderSelect.setSelectedIndex(selectIndex);
+    leaderBox.title = title;
+    const isTop = menuStack.length === 1;
+    leaderFooter.content = isTop
+      ? "  \u2191\u2193 select  \u2192 open category  Enter run  Esc/q close"
+      : "  Esc back  \u2191\u2193 select  Enter run";
+  }
+
+  function popMenuLevel(): boolean {
+    if (menuStack.length <= 1) return false;
+    const prev = menuStack[menuStack.length - 2];
+    const current = menuStack.pop()!;
+    leaderSelect.options = prev.entries.map((e) => ({
+      name:
+        e.type === "category" ? `  ${e.icon} ${e.name} \u2192` : `  ${e.name}`,
+      description: e.description,
+      value: e,
+    }));
+    leaderSelect.setSelectedIndex(current.selectedIndex);
+    leaderBox.title = prev.title;
+    const isTop = menuStack.length === 1;
+    leaderFooter.content = isTop
+      ? "  \u2191\u2193 select  \u2192 open category  Enter run  Esc/q close"
+      : "  Esc back  \u2191\u2193 select  Enter run";
+    return true;
+  }
+
+  function resetMenu() {
+    menuStack.length = 0;
+  }
 
-    // Common items (always available when repos exist)
+  // ── Build hierarchical menu ─────────────────────────────────────
+  function buildMenuHierarchy(): MenuCategory[] {
     const hasRepo = (() => {
       const opt = resultsSelect.getSelectedOption();
       return opt?.value && typeof (opt.value as any)?.fullName === "string";
     })();
 
-    items.push(
-      { name: "  Open in browser", description: "Open selected repo in browser", action: () => openUrlIfSelected() },
-      { name: "  History", description: "Search history", action: () => { refreshHistory(); showOverlay("history"); } },
-      { name: "  Saved searches", description: "Load a saved search", action: () => { refreshSavedSearches(); showOverlay("saved"); } },
-      { name: "  Export", description: "Export results to JSON/CSV/Markdown", action: () => showOverlay("export") },
-      { name: "  Share repo", description: "Copy repo link to clipboard", action: () => showShareIfRepo() },
-      { name: "  Notifications", description: "View alerts", action: () => { refreshNotifications(); showOverlay("notifications"); } },
-      { name: "  Topics", description: "Browse popular GitHub topics", action: () => { refreshTopics(); showOverlay("topics"); } },
-      { name: "  Compare view", description: "Show side-by-side comparison", action: () => { refreshCompare(); showOverlay("compare"); } },
-      { name: "  Bookmarks panel", description: "Browse saved repos", action: () => { refreshBookmarks(); showOverlay("bookmarks"); } },
-      { name: "  Save search", description: "Save current query", action: () => saveCurrentSearch() },
-      { name: "  Help", description: "Keybindings reference", action: () => showOverlay("help") },
+    const groups: MenuCategory[] = [];
+
+    // Search group 
+    const searchItems: MenuEntry[] = [];
+    if (currentMode === "search") {
+      searchItems.push(
+        {
+          type: "action",
+          name: "Sort",
+          description: `Cycle sort (current: ${currentSort})`,
+          action: () => changeSort(),
+        },
+        {
+          type: "action",
+          name: "Limit",
+          description: `Cycle result limit (current: ${currentLimit})`,
+          action: () => changeLimit(),
+        },
+        {
+          type: "action",
+          name: "Refresh",
+          description: "Re-run current search",
+          action: () => {
+            if (currentQueryInput) doSearch(currentQueryInput);
+          },
+        },
+        {
+          type: "action",
+          name: "Save search",
+          description: "Save current query as a named search",
+          action: () => saveCurrentSearch(),
+        },
+        {
+          type: "action",
+          name: "Saved searches",
+          description: "Load a saved search",
+          action: () => {
+            refreshSavedSearches();
+            showOverlay("saved");
+          },
+        },
+      );
+    }
+    if (searchItems.length > 0) {
+      groups.push({
+        type: "category",
+        name: "Search",
+        description: "Sort, limit, refresh, save searches",
+        icon: "\uD83D\uDD0D",
+        children: searchItems,
+      });
+    }
+
+    //  Repo group 
+    const repoItems: MenuEntry[] = [];
+    if (hasRepo) {
+      repoItems.push(
+        {
+          type: "action",
+          name: "Open in browser",
+          description: "Open selected repo in browser",
+          action: () => openUrlIfSelected(),
+        },
+        {
+          type: "action",
+          name: "Readme",
+          description: "Full README viewer",
+          action: () => {
+            showReadme();
+          },
+        },
+        {
+          type: "action",
+          name: "Activity graph",
+          description: "Toggle commit chart fullscreen",
+          action: () => toggleGraph(),
+        },
+      );
+      if (currentMode === "search") {
+        repoItems.push({
+          type: "action",
+          name: "Deep-dive",
+          description: "Languages, contributors, README excerpt",
+          action: () => {
+            showOverlay("none");
+            triggerDeepDive();
+          },
+        });
+      }
+      repoItems.push(
+        {
+          type: "action",
+          name: "Bookmark",
+          description: "Save / unsave selected repo",
+          action: () => toggleBookmarkOnSelected(),
+        },
+        {
+          type: "action",
+          name: "Compare",
+          description: "Add/remove repo to comparison",
+          action: () => toggleCompareOnSelected(),
+        },
+        {
+          type: "action",
+          name: "Share",
+          description: "Copy repo link to clipboard",
+          action: () => showShareIfRepo(),
+        },
+      );
+    }
+    if (repoItems.length > 0) {
+      groups.push({
+        type: "category",
+        name: "Repo",
+        description: "Open, readme, bookmark, share, compare",
+        icon: "\uD83D\uDCCB",
+        children: repoItems,
+      });
+    }
+
+    //  Navigate group 
+    const navItems: MenuEntry[] = [];
+    if (currentMode === "search") {
+      navItems.push({
+        type: "action",
+        name: "Trending",
+        description: "Browse GitHub trending repos",
+        action: () => loadTrending(),
+      });
+    } else {
+      navItems.push({
+        type: "action",
+        name: "Search mode",
+        description: "Switch to query search",
+        action: () => showSearchMode(),
+      });
+    }
+    navItems.push(
+      {
+        type: "action",
+        name: "History",
+        description: "Search history",
+        action: () => {
+          refreshHistory();
+          showOverlay("history");
+        },
+      },
+      {
+        type: "action",
+        name: "Bookmarks",
+        description: "Browse saved repos",
+        action: () => {
+          refreshBookmarks();
+          showOverlay("bookmarks");
+        },
+      },
+      {
+        type: "action",
+        name: "Topics",
+        description: "Browse popular GitHub topics",
+        action: () => {
+          refreshTopics();
+          showOverlay("topics");
+        },
+      },
+      {
+        type: "action",
+        name: "Export",
+        description: "Export results to JSON/CSV/Markdown",
+        action: () => showOverlay("export"),
+      },
     );
+    groups.push({
+      type: "category",
+      name: "Navigate",
+      description: "Trending, history, bookmarks, topics, export",
+      icon: "\uD83E\uDDED",
+      children: navItems,
+    });
 
-    leaderSelect.options = items.map((it) => ({
-      name: it.name,
-      description: it.description,
-      value: it,
-    }));
-    leaderSelect.setSelectedIndex(0);
+    // ⚙️ System group
+    const sysItems: MenuEntry[] = [
+      {
+        type: "action",
+        name: "Check for updates",
+        description: "Check npm for a newer version (debug)",
+        action: () => {
+          showOverlay("none");
+          checkForUpdateAndShow(true);
+        },
+      },
+      {
+        type: "action",
+        name: "Help",
+        description: "Keybindings reference",
+        action: () => showOverlay("help"),
+      },
+      {
+        type: "action",
+        name: "Notifications",
+        description: "View alerts",
+        action: () => {
+          refreshNotifications();
+          showOverlay("notifications");
+        },
+      },
+      {
+        type: "action",
+        name: "Compare view",
+        description: "Show side-by-side comparison",
+        action: () => {
+          refreshCompare();
+          showOverlay("compare");
+        },
+      },
+      {
+        type: "action",
+        name: "Quit",
+        description: "Exit ghfind",
+        action: () => {
+          saveSession({
+            mode: currentMode,
+            query: currentQueryInput,
+            sort: currentSort,
+            limit: currentLimit,
+            trendingTab,
+          });
+          cleanup();
+        },
+      },
+    ];
+    groups.push({
+      type: "category",
+      name: "System",
+      description: "Help, notifications, compare, quit",
+      icon: "\u2699\uFE0F",
+      children: sysItems,
+    });
+
+    return groups;
+  }
+
+  function showLeaderMenu() {
+    resetMenu();
+    const topLevel = buildMenuHierarchy();
+    pushMenuLevel(" ⚙ Menu ", "", topLevel, 0);
     leaderSelect.focus();
     showOverlay("leader");
   }
 
+  async function checkForUpdateAndShow(force: boolean = false) {
+    if (!force && !shouldCheckUpdate()) return;
+    if (cachedVersion === null) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf-8"));
+        cachedVersion = pkg.version;
+      } catch {
+        debugLog("Failed to read package.json");
+        return;
+      }
+    }
+    const currentVersion = cachedVersion;
+    // ponytail: DEBUG_FORCE_UPDATE lets you test the panel without a real newer version
+    const latest = process.env.DEBUG_FORCE_UPDATE || await checkForUpdate(currentVersion);
+    markUpdateChecked(latest ?? undefined);
+    if (latest) {
+      updateSelectedOption = 0;
+      updateText.content = `  A new version is available\n\n  Current: ${currentVersion}\n  Latest:   ${latest}\n\n  Run "npm install -g ghfind"`;
+      renderUpdateOptions();
+      showOverlay("update");
+    } else {
+      // ponytail: debug to file so it's not swallowed by TUI renderer
+      debugLog(`No update available (current: ${currentVersion})`);
+    }
+  }
+
   function openUrlIfSelected() {
     const opt = resultsSelect.getSelectedOption();
     const repo = opt?.value as Repo | undefined;
@@ -743,7 +1365,9 @@ export async function launchBrowser(): Promise<void> {
     const repo = opt?.value as Repo | undefined;
     if (repo) {
       const added = toggleBookmark(repo);
-      setStatus(added ? `Bookmarked ${repo.fullName}` : `Unbookmarked ${repo.fullName}`);
+      setStatus(
+        added ? `Bookmarked ${repo.fullName}` : `Unbookmarked ${repo.fullName}`,
+      );
     }
   }
 
@@ -757,23 +1381,36 @@ export async function launchBrowser(): Promise<void> {
       setStatus(`Removed ${repo.fullName} from comparison`);
     } else {
       compareList.push(repo);
-      setStatus(`${repo.fullName} added to comparison (${compareList.length} selected)`);
+      setStatus(
+        `${repo.fullName} added to comparison (${compareList.length} selected)`,
+      );
     }
   }
 
   function showShareIfRepo() {
     const opt = resultsSelect.getSelectedOption();
     const repo = opt?.value as Repo | undefined;
-    if (!repo) { setStatus("No repo selected to share"); return; }
+    if (!repo) {
+      setStatus("No repo selected to share");
+      return;
+    }
     showOverlay("share");
   }
 
   function saveCurrentSearch() {
     if (currentQueryInput) {
-      const name = currentQueryInput.length > 40
-        ? currentQueryInput.slice(0, 37) + "..."
-        : currentQueryInput;
-      saveSearch(name, currentQueryInput, currentMode, currentSort, currentLimit, currentMode === "trending" ? trendingTab : undefined);
+      const name =
+        currentQueryInput.length > 40
+          ? currentQueryInput.slice(0, 37) + "..."
+          : currentQueryInput;
+      saveSearch(
+        name,
+        currentQueryInput,
+        currentMode,
+        currentSort,
+        currentLimit,
+        currentMode === "trending" ? trendingTab : undefined,
+      );
       setStatus(`Saved as "${name}"`);
     } else {
       setStatus("No search to save");
@@ -807,9 +1444,9 @@ export async function launchBrowser(): Promise<void> {
   const readmeBox = new BoxRenderable(renderer, {
     visible: false,
     flexGrow: 1,
-    backgroundColor: colors.bg,
-    border: true,
-    borderColor: colors.green,
+    backgroundColor: colors.surface,
+    borderBottom: true,
+    borderBottomColor: colors.border,
     title: " README ",
     titleColor: colors.green,
   });
@@ -862,8 +1499,13 @@ export async function launchBrowser(): Promise<void> {
         `${repo.owner}/${repo.name}/master/README.md`,
         `${repo.owner}/${repo.name}/main/README.rst`,
       ]) {
-        const r = await fetch(`https://raw.githubusercontent.com/${path}`, { headers });
-        if (r.ok) { text = await r.text(); break; }
+        const r = await fetch(`https://raw.githubusercontent.com/${path}`, {
+          headers,
+        });
+        if (r.ok) {
+          text = await r.text();
+          break;
+        }
       }
       if (!text) {
         readmeText.content = `  (no README found for ${repo.fullName})`;
@@ -889,10 +1531,12 @@ export async function launchBrowser(): Promise<void> {
   // ── Status bar ──────────────────────────────────────────────────────
   const statusBar = new TextRenderable(renderer, {
     content: " Ready. Press Enter to search.",
-    backgroundColor: colors.bg,
+    backgroundColor: colors.surface,
     color: colors.muted,
     height: 1,
     paddingX: 1,
+    borderTop: true,
+    borderTopColor: colors.border,
   });
   root.add(statusBar);
 
@@ -918,7 +1562,7 @@ export async function launchBrowser(): Promise<void> {
   }
 
   function setToolbar() {
-    toolbarText.content = formatToolbar(currentSort, currentLimit);
+    toolbarText.content = formatToolbar(currentSort, currentLimit, totalCount);
     renderer.requestRender();
   }
 
@@ -927,22 +1571,30 @@ export async function launchBrowser(): Promise<void> {
       detailText.content = "";
       return;
     }
-    const topics = repo.topics.length ? repo.topics.slice(0, 8).join(", ") : "—";
+    const topics = repo.topics.length
+      ? repo.topics.slice(0, 8).join(", ")
+      : "—";
     const desc = repo.description ?? "(no description)";
+    const stars = repo.stars.toLocaleString();
+    const forks = repo.forks.toLocaleString();
+    const lang = repo.language ?? "—";
+    const updated = repo.updatedAt.slice(0, 10);
+    const statusTags: string[] = [];
+    if (repo.archived) statusTags.push("archived");
+    if (repo.isFork) statusTags.push("fork");
+    const tagStr = statusTags.length ? `  [${statusTags.join(", ")}]` : "";
+    
     const lines = [
-      `Name     ${repo.fullName}`,
-      `Stars    ${repo.stars.toLocaleString()}`,
-      `Forks    ${repo.forks.toLocaleString()}`,
-      `Lang     ${repo.language ?? "—"}`,
-      `Updated  ${repo.updatedAt.slice(0, 10)}`,
-      repo.archived ? "Status   archived" : "",
-      repo.isFork ? "Status   fork" : "",
-      `Topics   ${topics}`,
-      "",
-      desc,
-      "",
-      repo.url,
-    ].filter((l) => l !== "");
+      `  ${repo.fullName}${tagStr}`,
+      ``,
+      `  ★  ${stars}    ♡  ${forks}    ${lang}`,
+      `  Updated  ${updated}`,
+      `  Topics   ${topics}`,
+      ``,
+      `  ${desc}`,
+      ``,
+      `  ${repo.url}`,
+    ];
     detailText.content = lines.join("\n");
   }
 
@@ -956,7 +1608,11 @@ export async function launchBrowser(): Promise<void> {
     return bits === 0 ? " " : String.fromCodePoint(0x2800 + bits);
   }
 
-  function buildChartString(values: number[], termW: number, termH: number): string[] {
+  function buildChartString(
+    values: number[],
+    termW: number,
+    termH: number,
+  ): string[] {
     if (values.length === 0) return ["(no data)"];
 
     // Braille resolution: 2 horizontal dots and 4 vertical dots per terminal cell.
@@ -970,10 +1626,12 @@ export async function launchBrowser(): Promise<void> {
     }
     const max = Math.max(...sampled, 1);
     // Map each sample to a dot row (0 = bottom, dotH-1 = top).
-    const dotRows = sampled.map(v => Math.round((v / max) * (dotH - 1)));
+    const dotRows = sampled.map((v) => Math.round((v / max) * (dotH - 1)));
 
     // Build a mask grid: dotGrid[row][col] = true if the silhouette passes through.
-    const dotGrid: boolean[][] = Array.from({ length: dotH }, () => Array(dotW).fill(false));
+    const dotGrid: boolean[][] = Array.from({ length: dotH }, () =>
+      Array(dotW).fill(false),
+    );
 
     // Draw the silhouette line: mark the dot at each column.
     for (let c = 0; c < dotW; c++) {
@@ -998,29 +1656,54 @@ export async function launchBrowser(): Promise<void> {
         const r0 = tr * 4;
         const c0 = tc * 2;
         let bits = 0;
-        if (r0 + 0 < dotH && c0 + 0 < dotW && dotGrid[r0 + 0][c0 + 0]) bits |= 0x01;
-        if (r0 + 1 < dotH && c0 + 0 < dotW && dotGrid[r0 + 1][c0 + 0]) bits |= 0x02;
-        if (r0 + 2 < dotH && c0 + 0 < dotW && dotGrid[r0 + 2][c0 + 0]) bits |= 0x04;
-        if (r0 + 0 < dotH && c0 + 1 < dotW && dotGrid[r0 + 0][c0 + 1]) bits |= 0x08;
-        if (r0 + 1 < dotH && c0 + 1 < dotW && dotGrid[r0 + 1][c0 + 1]) bits |= 0x10;
-        if (r0 + 2 < dotH && c0 + 1 < dotW && dotGrid[r0 + 2][c0 + 1]) bits |= 0x20;
-        if (r0 + 3 < dotH && c0 + 0 < dotW && dotGrid[r0 + 3][c0 + 0]) bits |= 0x40;
-        if (r0 + 3 < dotH && c0 + 1 < dotW && dotGrid[r0 + 3][c0 + 1]) bits |= 0x80;
+        if (r0 + 0 < dotH && c0 + 0 < dotW && dotGrid[r0 + 0][c0 + 0])
+          bits |= 0x01;
+        if (r0 + 1 < dotH && c0 + 0 < dotW && dotGrid[r0 + 1][c0 + 0])
+          bits |= 0x02;
+        if (r0 + 2 < dotH && c0 + 0 < dotW && dotGrid[r0 + 2][c0 + 0])
+          bits |= 0x04;
+        if (r0 + 0 < dotH && c0 + 1 < dotW && dotGrid[r0 + 0][c0 + 1])
+          bits |= 0x08;
+        if (r0 + 1 < dotH && c0 + 1 < dotW && dotGrid[r0 + 1][c0 + 1])
+          bits |= 0x10;
+        if (r0 + 2 < dotH && c0 + 1 < dotW && dotGrid[r0 + 2][c0 + 1])
+          bits |= 0x20;
+        if (r0 + 3 < dotH && c0 + 0 < dotW && dotGrid[r0 + 3][c0 + 0])
+          bits |= 0x40;
+        if (r0 + 3 < dotH && c0 + 1 < dotW && dotGrid[r0 + 3][c0 + 1])
+          bits |= 0x80;
         chars.push(brailleChar(bits));
       }
 
       // Y-axis labels
-      const labelRows = [0, Math.floor(termH / 4), Math.floor(termH / 2), Math.floor(3 * termH / 4), termH - 1];
-      const labelVals = [max, Math.round(max * 0.75), Math.round(max / 2), Math.round(max / 4), 0];
+      const labelRows = [
+        0,
+        Math.floor(termH / 4),
+        Math.floor(termH / 2),
+        Math.floor((3 * termH) / 4),
+        termH - 1,
+      ];
+      const labelVals = [
+        max,
+        Math.round(max * 0.75),
+        Math.round(max / 2),
+        Math.round(max / 4),
+        0,
+      ];
       const idx = labelRows.indexOf(tr);
       let label = "     ";
-      if (idx >= 0) label = String(labelVals[idx]).padStart(4) + " ";
-      lines.push(`${label}\u2524${chars.join("")}`);
+      if (idx >= 0) {
+        const val = labelVals[idx];
+        label = val >= 1000 ? `${(val/1000).toFixed(1).replace(/\.0$/, "")}k` : String(val);
+        label = label.padStart(5) + " ";
+      }
+      lines.push(`${label}┆${chars.join("")}`);
     }
 
-    // X-axis
-    lines.push(`     \u2514${String.fromCharCode(0x2500).repeat(termW)}`);
-    return lines;
+    // X-axis with week labels
+    const xAxis = `     ┆${"─".repeat(termW)}`;
+    const weekLabels = `     ┆ ${"1w".padEnd(Math.floor(termW/4))} ${"13w".padEnd(Math.floor(termW/4))} ${"26w".padEnd(Math.floor(termW/4))} ${"52w"}`;
+    return [xAxis, weekLabels];
   }
 
   async function loadChart(repo: Repo) {
@@ -1028,10 +1711,13 @@ export async function launchBrowser(): Promise<void> {
     renderer.requestRender();
     try {
       const [chartRes, repoRes] = await Promise.all([
-        fetch(`https://api.github.com/repos/${repo.owner}/${repo.name}/stats/participation`,
-          { headers: { "User-Agent": "ghfind/1.0" } }),
-        fetch(`https://api.github.com/repos/${repo.owner}/${repo.name}`,
-          { headers: { "User-Agent": "ghfind/1.0" } }).then(r => r.ok ? r.json() : null),
+        fetch(
+          `https://api.github.com/repos/${repo.owner}/${repo.name}/stats/participation`,
+          { headers: { "User-Agent": "ghfind/1.0" } },
+        ),
+        fetch(`https://api.github.com/repos/${repo.owner}/${repo.name}`, {
+          headers: { "User-Agent": "ghfind/1.0" },
+        }).then((r) => (r.ok ? r.json() : null)),
       ]);
 
       let chartSection = "";
@@ -1042,22 +1728,28 @@ export async function launchBrowser(): Promise<void> {
           const chartW = 60;
           const chartH = 10;
           const chartLines = buildChartString(chartCommitData, chartW, chartH);
-          chartSection = ["", "Weekly commits (52 weeks)", ...chartLines].join("\n");
+          chartSection = ["", "Weekly commits (52 weeks)", ...chartLines].join(
+            "\n",
+          );
         }
       }
 
       const desc = repo.description ?? "";
-      const lang = repo.language ?? "\u2014";
+      const lang = repo.language ?? "—";
       const updated = repo.updatedAt ? repo.updatedAt.slice(0, 10) : "";
-      const topics = repoRes?.topics?.length ? repoRes.topics.slice(0, 8).join(", ") : "";
-
-      const growthLine = currentMode === "trending" && repo.score > 0
-        ? ` Growth \u25b2 ${fmtStars(repo.score)} ${trendingPeriod}`
+      const topics = repoRes?.topics?.length
+        ? repoRes.topics.slice(0, 8).join(", ")
         : "";
 
+      const growthLine =
+        currentMode === "trending" && repo.score > 0
+          ? ` Growth \u25b2 ${fmtStars(repo.score)} ${trendingPeriod}`
+          : "";
+
       const detailLines = [
-        ` ${repo.fullName}`,
-        ` \u2606 ${repo.stars.toLocaleString()}  \u2666 ${repo.forks.toLocaleString()}  ${lang}`,
+        `  ${repo.fullName}`,
+        ``,
+        `  ★  ${repo.stars.toLocaleString()}    ♡  ${repo.forks.toLocaleString()}    ${lang}`,
         growthLine,
         updated ? ` Updated ${updated}` : "",
         topics ? ` Topics  ${topics}` : "",
@@ -1065,12 +1757,9 @@ export async function launchBrowser(): Promise<void> {
         desc,
         "",
         ` ${repo.url}`,
-      ].filter(l => l !== "");
+      ].filter((l) => l !== "");
 
-      detailText.content = [
-        ...detailLines,
-        chartSection,
-      ].join("\n");
+      detailText.content = [...detailLines, chartSection].join("\n");
     } catch {
       detailText.content = "  Failed to load chart";
     }
@@ -1100,37 +1789,14 @@ export async function launchBrowser(): Promise<void> {
 
   // ── Trending helpers ────────────────────────────────────────────────
 
-  function formatTrendingLine(r: { rank: number; owner: string; name: string; stars: number; starsToday: number; language: string }): string {
-    const rank = String(r.rank).padStart(2, "0");
+  function formatTrendingLine(r: Repo, rank: number): string {
+    const rankStr = String(rank).padStart(2, "0");
     const name = `${r.owner}/${r.name}`.padEnd(30).slice(0, 30);
     const lang = (r.language || "?").padEnd(12).slice(0, 12);
     const stars = `★ ${fmtStars(r.stars)}`.padEnd(9).slice(0, 9);
-    const arrow = r.starsToday > 0 ? "▲" : r.starsToday < 0 ? "▼" : "—";
-    const growth = `${arrow} ${fmtStars(r.starsToday)} ${trendingPeriod}`;
-    return `[${rank}] ${name} ${lang} ${stars} ${growth}`;
-  }
-
-  function trendingRepoToSelectValue(r: TrendingRepo): Repo {
-    return {
-      id: 0,
-      fullName: `${r.owner}/${r.name}`,
-      name: r.name,
-      owner: r.owner,
-      description: r.description,
-      url: `https://github.com/${r.owner}/${r.name}`,
-      stars: r.stars,
-      forks: 0,
-      watchers: 0,
-      language: r.language,
-      topics: [],
-      archived: false,
-      isFork: false,
-      private: false,
-      createdAt: "",
-      updatedAt: "",
-      pushedAt: "",
-      score: r.starsToday,
-    };
+    const arrow = r.score > 0 ? "▲" : r.score < 0 ? "▼" : "—";
+    const growth = `${arrow} ${fmtStars(r.score)} ${trendingPeriod}`;
+    return `[${rankStr}] ${name} ${lang} ${stars} ${growth}`;
   }
 
   async function loadTrending() {
@@ -1140,31 +1806,59 @@ export async function launchBrowser(): Promise<void> {
     toolbarText.visible = false;
     trendingTabBox.visible = true;
     renderTrendingTabs();
-    resultsSelect.options = [{ name: "  Loading trending...", description: "", value: null }];
+    resultsSelect.options = [
+      { name: "  Loading trending...", description: "", value: null },
+    ];
     detailText.content = "";
     statusMgr.set("loading", "Loading trending repos...");
     renderer.requestRender();
 
     try {
-      const fetched = await fetchTrendingRepos(tabSince(trendingTab));
+      const searchModule = new SearchModule(new TrendingAdapter());
+      const response = await searchModule.search(
+        { keywords: [], qualifiers: [], raw: "trending" },
+        { limit: 25, sort: "stars", json: false, verbose: false, trendingSince: tabSince(trendingTab) },
+      );
+      const fetched = response.repos;
       const since = tabSince(trendingTab);
-      trendingPeriod = since === "daily" ? "today" : since === "weekly" ? "this week" : "this month";
-      resultsSelect.options = fetched.map(r => ({
-        name: formatTrendingLine(r),
-        description: r.description,
-        value: trendingRepoToSelectValue(r),
+      trendingPeriod =
+        since === "daily"
+          ? "today"
+          : since === "weekly"
+            ? "this week"
+            : "this month";
+      resultsSelect.options = fetched.map((r, i) => ({
+        name: formatTrendingLine(r, i + 1),
+        description: r.description ?? "",
+        value: r,
       }));
       if (fetched.length > 0) {
         resultsSelect.setSelectedIndex(0);
-        updateDetail(trendingRepoToSelectValue(fetched[0]));
+        updateDetail(fetched[0]);
       } else {
         throw new NoResultsError(trendingTab);
       }
-      statusMgr.set("success", `${fetched.length} trending repos — ${trendingTab}`);
-      appendHistory({ query: `trending:${trendingTab}`, mode: "trending", tab: trendingTab, timestamp: Date.now(), resultCount: fetched.length });
+      statusMgr.set(
+        "success",
+        `${fetched.length} trending repos — ${trendingTab}`,
+      );
+      appendHistory({
+        query: `trending:${trendingTab}`,
+        mode: "trending",
+        tab: trendingTab,
+        timestamp: Date.now(),
+        resultCount: fetched.length,
+      });
     } catch (err) {
-      const msg = err instanceof SearchCliError ? err.userMessage : (err instanceof Error ? err.message : String(err));
-      resultsSelect.options = [{ name: " (error)", description: "", value: null }];
+      const msg =
+        err instanceof SearchCliError
+          ? err.userMessage
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      resultsSelect.options = [
+        { name: " (error)", description: "", value: null },
+      ];
       statusMgr.set("error", msg.slice(0, 60));
     }
     isLoading = false;
@@ -1176,7 +1870,8 @@ export async function launchBrowser(): Promise<void> {
     trendingTabBox.visible = false;
     searchBox.visible = true;
     toolbarText.visible = true;
-    searchInput.placeholder = "Search GitHub repos (e.g. rust cli, or language:Rust stars:>100)";
+    searchInput.placeholder =
+      "Search GitHub repos (e.g. rust cli, or language:Rust stars:>100)";
     searchInput.focus();
     renderer.requestRender();
   }
@@ -1191,7 +1886,9 @@ export async function launchBrowser(): Promise<void> {
     isLoading = true;
     currentQueryInput = q;
     if (!append) {
-      resultsSelect.options = [{ name: "  Searching...", description: "", value: null }];
+      resultsSelect.options = [
+        { name: "  Searching...", description: "", value: null },
+      ];
       detailText.content = "";
     }
     statusMgr.set("searching", `Searching for "${q}"`);
@@ -1229,15 +1926,30 @@ export async function launchBrowser(): Promise<void> {
         const idx = append ? resultsSelect.options.length - newRepos.length : 0;
         updateDetail(currentRepos[idx]);
         resultsSelect.setSelectedIndex(idx);
-        statusMgr.set("success", `Page ${currentPage} — ${currentRepos.length} of ${totalCount.toLocaleString()} results`);
+        statusMgr.set(
+          "success",
+          `Page ${currentPage} — ${currentRepos.length} of ${totalCount.toLocaleString()} results`,
+        );
         if (!append) {
-          appendHistory({ query: q, mode: "search", timestamp: Date.now(), resultCount: currentRepos.length });
+          appendHistory({
+            query: q,
+            mode: "search",
+            timestamp: Date.now(),
+            resultCount: currentRepos.length,
+          });
         }
       }
     } catch (err) {
       currentRepos = [];
-      resultsSelect.options = [{ name: " (error)", description: "", value: null }];
-      const msg = err instanceof SearchCliError ? err.userMessage : (err instanceof Error ? err.message : String(err));
+      resultsSelect.options = [
+        { name: " (error)", description: "", value: null },
+      ];
+      const msg =
+        err instanceof SearchCliError
+          ? err.userMessage
+          : err instanceof Error
+            ? err.message
+            : String(err);
       statusMgr.set("error", msg.slice(0, 60));
     }
 
@@ -1303,21 +2015,56 @@ export async function launchBrowser(): Promise<void> {
   renderer.keyInput.on("keypress", (key) => {
     // ── Overlay-mode handling ────────────────────────────────────────
     if (currentOverlay !== "none") {
-      // Escape or q closes any overlay
-      if (key.name === "escape" || key.name === "q") {
+      // Escape or q closes any overlay (except: leader uses Esc for back-nav, q to close)
+      if (key.name === "escape") {
+        if (currentOverlay === "leader") {
+          if (!popMenuLevel()) {
+            showOverlay("none");
+          }
+          setToolbar();
+          renderer.requestRender();
+        } else {
+          showOverlay("none");
+          renderer.requestRender();
+        }
+        return;
+      }
+      if (key.name === "q") {
         showOverlay("none");
         renderer.requestRender();
         return;
       }
 
-      // Leader menu: Enter dispatches action, up/down navigates
+      // Leader menu: hierarchical submenu navigation
       if (currentOverlay === "leader") {
-        if (key.name === "enter" || key.name === "return") {
+        if (
+          key.name === "enter" ||
+          key.name === "return" ||
+          key.name === "right" ||
+          key.name === "l"
+        ) {
           const sel = leaderSelect.getSelectedOption();
-          const item = sel?.value as LeaderItem | undefined;
-          if (item) {
+          const entry = sel?.value as MenuEntry | undefined;
+          if (!entry) return;
+          if (entry.type === "category") {
+            pushMenuLevel(
+              `  Menu > ${entry.name}`,
+              entry.name,
+              entry.children,
+              0,
+            );
+            renderer.requestRender();
+          } else {
+            resetMenu();
             showOverlay("none");
-            item.action();
+            entry.action();
+            renderer.requestRender();
+          }
+          return;
+        }
+        if (key.name === "left" || key.name === "h") {
+          if (popMenuLevel()) {
+            setToolbar();
             renderer.requestRender();
           }
           return;
@@ -1355,7 +2102,8 @@ export async function launchBrowser(): Promise<void> {
             const entry = (sel.value as any).entry;
             showOverlay("none");
             if (entry.mode === "trending") {
-              if (entry.tab) trendingTab = entry.tab as typeof TAB_NAMES[number];
+              if (entry.tab)
+                trendingTab = entry.tab as (typeof TAB_NAMES)[number];
               loadTrending();
             } else {
               searchInput.value = entry.query;
@@ -1407,7 +2155,7 @@ export async function launchBrowser(): Promise<void> {
             showOverlay("none");
             touchSavedSearch(s.name);
             if (s.mode === "trending") {
-              if (s.tab) trendingTab = s.tab as typeof TAB_NAMES[number];
+              if (s.tab) trendingTab = s.tab as (typeof TAB_NAMES)[number];
               loadTrending();
             } else {
               searchInput.value = s.query;
@@ -1512,6 +2260,51 @@ export async function launchBrowser(): Promise<void> {
         return;
       }
 
+      // Update panel
+      if (currentOverlay === "update") {
+        if (key.name === "escape" || key.name === "q") {
+          showOverlay("none");
+          renderer.requestRender();
+          return;
+        }
+        if (key.name === "left" || key.name === "h") {
+          updateSelectedOption = Math.max(0, updateSelectedOption - 1);
+          renderUpdateOptions();
+          return;
+        }
+        if (key.name === "right" || key.name === "l") {
+          updateSelectedOption = Math.min(2, updateSelectedOption + 1);
+          renderUpdateOptions();
+          return;
+        }
+        if (key.name === "enter" || key.name === "return") {
+          const action = ["now", "later", "never"][updateSelectedOption] as "now" | "later" | "never" | undefined;
+          if (action === "now") {
+            showOverlay("none");
+            performUpdate().then((ok) => {
+              if (ok) {
+                setStatus("✓ Update complete — restart ghfind");
+              } else {
+                setStatus("✗ Update failed — check terminal output");
+              }
+            }).catch(() => {
+              setStatus("✗ Update failed — check terminal output");
+            });
+          } else if (action === "never") {
+            suppressUpdateNotices();
+            showOverlay("none");
+            setStatus("Update notices suppressed");
+          } else {
+            snoozeUpdateNotices(3);
+            showOverlay("none");
+            setStatus("Update reminder snoozed for 3 days");
+          }
+          renderer.requestRender();
+          return;
+        }
+        return;
+      }
+
       return;
     }
 
@@ -1523,7 +2316,13 @@ export async function launchBrowser(): Promise<void> {
         toggleGraph();
         return;
       }
-      saveSession({ mode: currentMode, query: currentQueryInput, sort: currentSort, limit: currentLimit, trendingTab });
+      saveSession({
+        mode: currentMode,
+        query: currentQueryInput,
+        sort: currentSort,
+        limit: currentLimit,
+        trendingTab,
+      });
       cleanup();
       return;
     }
@@ -1534,9 +2333,14 @@ export async function launchBrowser(): Promise<void> {
       return;
     }
 
-    // Space opens leader menu
-    if (key.name === "space") {
-      showLeaderMenu();
+    // Space toggles leader menu (open if closed, close if open)
+    // Skip when the search input is focused so spaces can be typed in queries
+    if (key.name === "space" && !searchInput.focused) {
+      if (currentOverlay === "leader") {
+        showOverlay("none");
+      } else {
+        showLeaderMenu();
+      }
       return;
     }
 
@@ -1554,9 +2358,10 @@ export async function launchBrowser(): Promise<void> {
         const currentWord = lastSpace >= 0 ? val.slice(lastSpace + 1) : val;
         const suggestions = suggestFor(currentWord);
         if (suggestions.length > 0) {
-          const newVal = lastSpace >= 0
-            ? val.slice(0, lastSpace + 1) + suggestions[0]
-            : suggestions[0];
+          const newVal =
+            lastSpace >= 0
+              ? val.slice(0, lastSpace + 1) + suggestions[0]
+              : suggestions[0];
           searchInput.value = newVal;
           renderer.requestRender();
         }
@@ -1588,14 +2393,20 @@ export async function launchBrowser(): Promise<void> {
     if (key.name === "left" || key.name === "h") {
       if (currentMode === "trending") {
         const idx = TAB_NAMES.indexOf(trendingTab);
-        if (idx > 0) { trendingTab = TAB_NAMES[idx - 1]; loadTrending(); }
+        if (idx > 0) {
+          trendingTab = TAB_NAMES[idx - 1];
+          loadTrending();
+        }
       }
       return;
     }
     if (key.name === "right" || key.name === "l") {
       if (currentMode === "trending") {
         const idx = TAB_NAMES.indexOf(trendingTab);
-        if (idx < TAB_NAMES.length - 1) { trendingTab = TAB_NAMES[idx + 1]; loadTrending(); }
+        if (idx < TAB_NAMES.length - 1) {
+          trendingTab = TAB_NAMES[idx + 1];
+          loadTrending();
+        }
       }
       return;
     }
@@ -1620,7 +2431,22 @@ export async function launchBrowser(): Promise<void> {
     }
   });
 
+  // ── Update check (before start) ──────────────────────────────────────
+  const pkgPath = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "package.json",
+  );
+  let currentVersion = "0.0.0";
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    currentVersion = pkg.version;
+  } catch {
+    // non-critical
+  }
   // ── Start ──────────────────────────────────────────────────────────
+  // Check for updates (non-blocking — doesn't delay TUI startup)
+  checkForUpdateAndShow();
   renderer.start();
   if (currentMode === "trending") {
     loadTrending();
@@ -1641,21 +2467,27 @@ export async function launchBrowser(): Promise<void> {
 function formatResultLine(repo: Repo): string {
   const stars = formatStars(repo.stars);
   const lang = (repo.language ?? "?").padEnd(12).slice(0, 12);
-  return `${repo.fullName}  ${stars}`;
+  const name = repo.fullName.padEnd(40).slice(0, 40);
+  return `${name}  ${lang}  ${stars}`;
 }
 
 function formatStars(n: number): string {
+  if (n >= 1000000) return `★ ${(n / 1000000).toFixed(1).replace(/\.0$/, "")}M`;
   if (n >= 1000) return `★ ${(n / 1000).toFixed(1).replace(/\.0$/, "")}k`;
   return `★ ${n}`;
 }
 
-function formatToolbar(sort: SortStrategy, limit: number): string {
+function formatToolbar(sort: SortStrategy, limit: number, totalCount: number): string {
   const sortLabel = SORT_MODES.find((m) => m.key === sort)?.label ?? sort;
-  return ` sort: ${sortLabel}   limit: ${limit}`;
+  return ` sort: ${sortLabel}   limit: ${limit}   results: ${totalCount.toLocaleString()}`;
 }
 
 function cleanup(): void {
-  try { rotateHistory(); } catch { /* non-critical */ }
+  try {
+    rotateHistory();
+  } catch {
+    /* non-critical */
+  }
   process.exit(0);
 }