free-coding-models 0.2.12 → 0.2.14

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ---
 
+## 0.2.14
+
+### Fixed
+- **Changelog scrolling viewport**: Scrolling in changelog details (N key) now respects viewport boundaries — content no longer scrolls beyond visible area. Down/PageDown/End keys now properly clamp to max scroll offset so you can view all content without it disappearing off screen.
+
+---
+
+## 0.2.13
+
+### Added
+- **Persist UI view settings**: Tier filter (T key), provider filter (D key), and sort order now persist across session restarts — settings are saved to `~/.free-coding-models.json` under `config.settings` and automatically restored on next startup. Settings also mirror into active profiles so profile switching captures live view preferences.
+  - When T cycles tier: S+ tier is now remembered for next session
+  - When D cycles provider: Filtered provider is now remembered
+  - When sort keys (R/O/M/L/A/S/C/H/V/B/U) change order: Sort column and direction are now remembered
+  - Profile loading has priority over global `config.settings` so saved profiles override global defaults
+- **Reset view settings (Shift+R)**: New keyboard shortcut to instantly reset tier filter, provider filter, and sort order to defaults (All tier, no provider filter, avg sort ascending). Also clears persisted settings from `config.settings` so next restart returns to factory defaults.
+  - Useful when you've customized your view but want a fresh start
+  - Does not affect favorites, API keys, or other settings — only view state
+
+### Changed
+- **Help overlay (K key)**: Updated to document new Shift+R keybinding for resetting view settings
+
+---
+
 ## 0.2.12
 
 ### Added

package/README.md

@@ -80,6 +80,7 @@ By Vanessa Depraute
 - **📐 Stability score** — Composite 0–100 score measuring consistency (p95, jitter, spikes, uptime)
 - **📊 Usage tracking** — Monitor remaining quota for each exact provider/model pair when the provider exposes it; otherwise the TUI shows a green dot instead of a misleading percentage.
 - **📜 Request Log Overlay** — Press `X` to inspect recent proxied requests and token usage for exact provider/model pairs.
+- **📋 Changelog Overlay** — Press `N` to browse all versions in an index, then `Enter` to view details for any version with full scroll support
 - **🛠 MODEL_NOT_FOUND Rotation** — If a specific provider returns a 404 for a model, the TUI intelligently rotates through other available providers for the same model.
 - **🔄 Auto-retry** — Timeout models keep getting retried, nothing is ever "given up on"
 - **🎮 Interactive selection** — Navigate with arrow keys directly in the table, press Enter to act
@@ -931,6 +932,7 @@ This script:
 - **Shift+P** — Cycle through saved profiles (switches live TUI settings)
 - **Shift+S** — Save current TUI settings as a named profile (inline prompt)
 - **Q** — Open Smart Recommend overlay (find the best model for your task)
+- **N** — Open Changelog overlay (browse index of all versions, `Enter` to view details, `B` to go back)
 - **W** — Cycle ping mode (`FAST` 2s → `NORMAL` 10s → `SLOW` 30s → `FORCED` 4s)
 - **J / I** — Request feature / Report bug
 - **K / Esc** — Show help overlay / Close overlay

package/bin/free-coding-models.js

@@ -362,8 +362,8 @@ async function main() {
     frame: 0,
     cursor: 0,
     selectedModel: null,
-    sortColumn: startupProfileSettings?.sortColumn || 'avg',
-    sortDirection: startupProfileSettings?.sortAsc === false ? 'desc' : 'asc',
+    sortColumn: startupProfileSettings?.sortColumn ?? config.settings?.sortColumn ?? 'avg',
+    sortDirection: (startupProfileSettings?.sortAsc ?? config.settings?.sortAsc ?? true) ? 'asc' : 'desc',
     pingInterval: PING_MODE_INTERVALS.speed, // 📖 Effective live interval derived from the active ping mode.
     pingMode: 'speed',            // 📖 Current ping mode: speed | normal | slow | forced.
     pingModeSource: 'startup',    // 📖 Why this mode is active: startup | manual | auto | idle | activity.
@@ -444,6 +444,12 @@ async function main() {
     logVisible: false,            // 📖 Whether the log page overlay is active
     logScrollOffset: 0,           // 📖 Vertical scroll offset for log overlay viewport
     logShowAll: false,             // 📖 Show all logs (true) or limited to 500 (false)
+    // 📖 Changelog overlay state (N key opens it)
+    changelogOpen: false,         // 📖 Whether the changelog overlay is active
+    changelogScrollOffset: 0,     // 📖 Vertical scroll offset for changelog overlay viewport
+    changelogPhase: 'index',      // 📖 'index' (all versions) | 'details' (specific version)
+    changelogCursor: 0,           // 📖 Selected row in index phase
+    changelogSelectedVersion: null, // 📖 Which version to show details for
     // 📖 Proxy startup status — set by autoStartProxyIfSynced, consumed by Task 3 indicator
     // 📖 null = not configured/not attempted
     // 📖 { phase: 'starting' } — proxy start in progress
@@ -606,8 +612,10 @@ async function main() {
 
   // 📖 originFilterMode: index into ORIGIN_CYCLE, 0=All, then each provider key in order
   const ORIGIN_CYCLE = [null, ...Object.keys(sources)]
-  state.tierFilterMode = startupProfileSettings?.tierFilter ? Math.max(0, TIER_CYCLE.indexOf(startupProfileSettings.tierFilter)) : 0
-  state.originFilterMode = 0
+  const resolvedTierFilter = startupProfileSettings?.tierFilter ?? config.settings?.tierFilter
+  state.tierFilterMode = resolvedTierFilter ? Math.max(0, TIER_CYCLE.indexOf(resolvedTierFilter)) : 0
+  const resolvedOriginFilter = config.settings?.originFilter
+  state.originFilterMode = resolvedOriginFilter ? Math.max(0, ORIGIN_CYCLE.indexOf(resolvedOriginFilter)) : 0
 
   function applyTierFilter() {
     const activeTier = TIER_CYCLE[state.tierFilterMode]
@@ -771,12 +779,12 @@ async function main() {
   process.stdin.on('keypress', onKeyPress)
   process.on('SIGCONT', noteUserActivity)
 
-  // 📖 Animation loop: render settings overlay, recommend overlay, help overlay, feature request overlay, bug report overlay, OR main table
+  // 📖 Animation loop: render settings overlay, recommend overlay, help overlay, feature request overlay, bug report overlay, changelog overlay, OR main table
   ticker = setInterval(() => {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen && !state.changelogOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
@@ -794,6 +802,8 @@ async function main() {
                 ? overlays.renderHelp()
               : state.logVisible
                 ? overlays.renderLog()
+              : state.changelogOpen
+                ? overlays.renderChangelog()
                 : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",

package/src/key-handler.js

@@ -25,6 +25,8 @@
  * @exports { buildProviderModelsUrl, parseProviderModelIds, listProviderTestModels, classifyProviderTestOutcome, buildProviderTestDetail, createKeyHandler }
  */
 
+import { loadChangelog } from './changelog-loader.js'
+
 // 📖 Some providers need an explicit probe model because the first catalog entry
 // 📖 is not guaranteed to be accepted by their chat endpoint.
 const PROVIDER_TEST_MODEL_OVERRIDES = {
@@ -766,6 +768,102 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Changelog overlay: two-phase (index + details) with keyboard navigation
+    if (state.changelogOpen) {
+      const pageStep = Math.max(1, (state.terminalRows || 1) - 2)
+      const changelogData = loadChangelog()
+      const { versions } = changelogData
+      const versionList = Object.keys(versions).sort((a, b) => {
+        const aParts = a.split('.').map(Number)
+        const bParts = b.split('.').map(Number)
+        for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+          const aVal = aParts[i] || 0
+          const bVal = bParts[i] || 0
+          if (bVal !== aVal) return bVal - aVal
+        }
+        return 0
+      })
+
+      // 📖 Close changelog overlay
+      if (key.name === 'escape' || key.name === 'n') {
+        state.changelogOpen = false
+        state.changelogPhase = 'index'
+        state.changelogCursor = 0
+        state.changelogSelectedVersion = null
+        return
+      }
+
+      if (state.changelogPhase === 'index') {
+        // 📖 INDEX PHASE: Navigate through versions
+        if (key.name === 'up') {
+          state.changelogCursor = Math.max(0, state.changelogCursor - 1)
+          return
+        }
+        if (key.name === 'down') {
+          state.changelogCursor = Math.min(versionList.length - 1, state.changelogCursor + 1)
+          return
+        }
+        if (key.name === 'home') { state.changelogCursor = 0; return }
+        if (key.name === 'end') { state.changelogCursor = versionList.length - 1; return }
+        if (key.name === 'return') {
+          // 📖 Enter details phase for selected version
+          state.changelogPhase = 'details'
+          state.changelogSelectedVersion = versionList[state.changelogCursor]
+          state.changelogScrollOffset = 0
+          return
+        }
+      } else if (state.changelogPhase === 'details') {
+        // 📖 DETAILS PHASE: Scroll through selected version details
+        if (key.name === 'b') {
+          // 📖 B = back to index
+          state.changelogPhase = 'index'
+          state.changelogScrollOffset = 0
+          return
+        }
+
+        // 📖 Calculate total content lines for proper scroll boundary clamping
+        const calcChangelogLines = () => {
+          const lines = []
+          lines.push(`  🚀 free-coding-models`)
+          lines.push(`  📋 v${state.changelogSelectedVersion}`)
+          lines.push(`  — ↑↓ / PgUp / PgDn scroll • B back • Esc close`)
+          lines.push('')
+          const changes = versions[state.changelogSelectedVersion]
+          if (changes) {
+            const sections = { added: '✨ Added', fixed: '🐛 Fixed', changed: '🔄 Changed', updated: '📝 Updated' }
+            for (const [key, label] of Object.entries(sections)) {
+              if (changes[key] && changes[key].length > 0) {
+                lines.push(`  ${label}`)
+                for (const item of changes[key]) {
+                  let displayText = item.replace(/\*\*([^*]+)\*\*/g, '$1').replace(/`([^`]+)`/g, '$1')
+                  const maxWidth = state.terminalCols - 16
+                  if (displayText.length > maxWidth) {
+                    displayText = displayText.substring(0, maxWidth - 3) + '…'
+                  }
+                  lines.push(`    • ${displayText}`)
+                }
+                lines.push('')
+              }
+            }
+          }
+          return lines.length
+        }
+        const totalChangelogLines = calcChangelogLines()
+        const viewportRows = Math.max(1, state.terminalRows || 1)
+        const maxScrollOffset = Math.max(0, totalChangelogLines - viewportRows)
+
+        if (key.name === 'up') { state.changelogScrollOffset = Math.max(0, state.changelogScrollOffset - 1); return }
+        if (key.name === 'down') { state.changelogScrollOffset = Math.min(maxScrollOffset, state.changelogScrollOffset + 1); return }
+        if (key.name === 'pageup') { state.changelogScrollOffset = Math.max(0, state.changelogScrollOffset - pageStep); return }
+        if (key.name === 'pagedown') { state.changelogScrollOffset = Math.min(maxScrollOffset, state.changelogScrollOffset + pageStep); return }
+        if (key.name === 'home') { state.changelogScrollOffset = 0; return }
+        if (key.name === 'end') { state.changelogScrollOffset = maxScrollOffset; return }
+      }
+
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+      return
+    }
+
     // 📖 Smart Recommend overlay: full keyboard handling while overlay is open.
     if (state.recommendOpen) {
       if (key.ctrl && key.name === 'c') { exit(0); return }
@@ -882,10 +980,11 @@ export function createKeyHandler(ctx) {
       const proxySyncRowIdx = updateRowIdx + 2
       const proxyPortRowIdx = updateRowIdx + 3
       const proxyCleanupRowIdx = updateRowIdx + 4
-      // 📖 Profile rows start after maintenance + proxy rows — one row per saved profile
+      const changelogViewRowIdx = updateRowIdx + 5
+      // 📖 Profile rows start after maintenance + proxy rows + changelog row — one row per saved profile
       const savedProfiles = listProfiles(state.config)
-      const profileStartIdx = updateRowIdx + 5
-      const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : proxyCleanupRowIdx
+      const profileStartIdx = updateRowIdx + 6
+      const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : changelogViewRowIdx
 
       // 📖 Edit/Add-key mode: capture typed characters for the API key
       if (state.settingsEditMode || state.settingsAddKeyMode) {
@@ -1059,6 +1158,17 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        // 📖 Changelog row: Enter → open changelog overlay
+        if (state.settingsCursor === changelogViewRowIdx) {
+          state.settingsOpen = false
+          state.changelogOpen = true
+          state.changelogPhase = 'index'
+          state.changelogCursor = 0
+          state.changelogSelectedVersion = null
+          state.changelogScrollOffset = 0
+          return
+        }
+
         // 📖 Profile row: Enter → load the selected profile (apply its settings live)
         if (state.settingsCursor >= profileStartIdx && savedProfiles.length > 0) {
           const profileIdx = state.settingsCursor - profileStartIdx
@@ -1094,7 +1204,7 @@ export function createKeyHandler(ctx) {
       }
 
       if (key.name === 'space') {
-        if (state.settingsCursor === updateRowIdx || state.settingsCursor === proxyPortRowIdx || state.settingsCursor === proxyCleanupRowIdx) return
+        if (state.settingsCursor === updateRowIdx || state.settingsCursor === proxyPortRowIdx || state.settingsCursor === proxyCleanupRowIdx || state.settingsCursor === changelogViewRowIdx) return
         // 📖 Profile rows don't respond to Space
         if (state.settingsCursor >= profileStartIdx) return
 
@@ -1125,7 +1235,7 @@ export function createKeyHandler(ctx) {
       }
 
       if (key.name === 't') {
-        if (state.settingsCursor === updateRowIdx) return
+        if (state.settingsCursor === updateRowIdx || state.settingsCursor === proxyPortRowIdx || state.settingsCursor === proxyCleanupRowIdx || state.settingsCursor === changelogViewRowIdx) return
         // 📖 Profile rows don't respond to T (test key)
         if (state.settingsCursor >= profileStartIdx) return
 
@@ -1333,9 +1443,60 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Helper: persist current UI view settings (tier, provider, sort) to config.settings
+    // 📖 Called after every T / D / sort key so preferences survive session restarts.
+    function persistUiSettings() {
+      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+      state.config.settings.tierFilter = TIER_CYCLE[state.tierFilterMode]
+      state.config.settings.originFilter = ORIGIN_CYCLE[state.originFilterMode] ?? null
+      state.config.settings.sortColumn = state.sortColumn
+      state.config.settings.sortAsc = state.sortDirection === 'asc'
+      // 📖 Mirror into active profile too so profile captures live preferences
+      if (state.activeProfile && state.config.profiles?.[state.activeProfile]) {
+        const profile = state.config.profiles[state.activeProfile]
+        if (!profile.settings || typeof profile.settings !== 'object') profile.settings = {}
+        profile.settings.tierFilter = state.config.settings.tierFilter
+        profile.settings.originFilter = state.config.settings.originFilter
+        profile.settings.sortColumn = state.config.settings.sortColumn
+        profile.settings.sortAsc = state.config.settings.sortAsc
+      }
+      saveConfig(state.config)
+    }
+
+    // 📖 Shift+R: reset all UI view settings to defaults (tier, sort, provider) and clear persisted config
+    if (key.name === 'r' && key.shift) {
+      state.tierFilterMode = 0
+      state.originFilterMode = 0
+      state.sortColumn = 'avg'
+      state.sortDirection = 'asc'
+      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
+      delete state.config.settings.tierFilter
+      delete state.config.settings.originFilter
+      delete state.config.settings.sortColumn
+      delete state.config.settings.sortAsc
+      // 📖 Also clear in active profile if loaded
+      if (state.activeProfile && state.config.profiles?.[state.activeProfile]) {
+        const profile = state.config.profiles[state.activeProfile]
+        if (profile.settings) {
+          delete profile.settings.tierFilter
+          delete profile.settings.originFilter
+          delete profile.settings.sortColumn
+          delete profile.settings.sortAsc
+        }
+      }
+      saveConfig(state.config)
+      applyTierFilter()
+      const visible = state.results.filter(r => !r.hidden)
+      state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
+      state.cursor = 0
+      state.scrollOffset = 0
+      return
+    }
+
     // 📖 Sorting keys: R=rank, O=origin, M=model, L=latest ping, A=avg ping, S=SWE-bench, C=context, H=health, V=verdict, B=stability, U=uptime, G=usage
     // 📖 T is reserved for tier filter cycling. Y now opens the install-endpoints flow.
     // 📖 D is now reserved for provider filter cycling
+    // 📖 Shift+R is reserved for reset view settings
     const sortKeys = {
       'r': 'rank', 'o': 'origin', 'm': 'model',
       'l': 'ping', 'a': 'avg', 's': 'swe', 'c': 'ctx', 'h': 'condition', 'v': 'verdict', 'b': 'stability', 'u': 'uptime', 'g': 'usage'
@@ -1355,6 +1516,7 @@ export function createKeyHandler(ctx) {
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
+      persistUiSettings()
       return
     }
 
@@ -1440,6 +1602,7 @@ export function createKeyHandler(ctx) {
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
+      persistUiSettings()
       return
     }
 
@@ -1452,6 +1615,7 @@ export function createKeyHandler(ctx) {
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
       state.cursor = 0
       state.scrollOffset = 0
+      persistUiSettings()
       return
     }
 
@@ -1462,6 +1626,18 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Changelog overlay key: N = toggle changelog overlay
+    if (key.name === 'n') {
+      state.changelogOpen = !state.changelogOpen
+      if (state.changelogOpen) {
+        state.changelogScrollOffset = 0
+        state.changelogPhase = 'index'
+        state.changelogCursor = 0
+        state.changelogSelectedVersion = null
+      }
+      return
+    }
+
     // 📖 Mode toggle key: Z cycles through the supported tool targets.
     if (key.name === 'z') {
       const modeOrder = getToolModeOrder()

package/src/overlays.js

@@ -4,7 +4,7 @@
  *
  * @details
  *   This module centralizes all overlay rendering in one place:
- *   - Settings, Install Endpoints, Help, Log, Smart Recommend, Feature Request, Bug Report
+ *   - Settings, Install Endpoints, Help, Log, Smart Recommend, Feature Request, Bug Report, Changelog
  *   - Settings diagnostics for provider key tests, including wrapped retry/error details
  *   - Recommend analysis timer orchestration and progress updates
  *
@@ -17,6 +17,8 @@
  * @exports { createOverlayRenderers }
  */
 
+import { loadChangelog } from './changelog-loader.js'
+
 export function createOverlayRenderers(state, deps) {
   const {
     chalk,
@@ -138,6 +140,7 @@ export function createOverlayRenderers(state, deps) {
     const proxySyncRowIdx = updateRowIdx + 2
     const proxyPortRowIdx = updateRowIdx + 3
     const proxyCleanupRowIdx = updateRowIdx + 4
+    const changelogViewRowIdx = updateRowIdx + 5
     const proxySettings = getProxySettings(state.config)
     const EL = '\x1b[K'
     const lines = []
@@ -296,9 +299,15 @@ export function createOverlayRenderers(state, deps) {
     cursorLineByRow[proxyCleanupRowIdx] = lines.length
     lines.push(state.settingsCursor === proxyCleanupRowIdx ? chalk.bgRgb(45, 30, 30)(proxyCleanupRow) : proxyCleanupRow)
 
+    // 📖 Changelog viewer row
+    const changelogViewBullet = state.settingsCursor === changelogViewRowIdx ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+    const changelogViewRow = `${changelogViewBullet}${chalk.bold('View Changelog').padEnd(44)} ${chalk.dim('Enter browse version history')}`
+    cursorLineByRow[changelogViewRowIdx] = lines.length
+    lines.push(state.settingsCursor === changelogViewRowIdx ? chalk.bgRgb(30, 45, 30)(changelogViewRow) : changelogViewRow)
+
     // 📖 Profiles section — list saved profiles with active indicator + delete support
     const savedProfiles = listProfiles(state.config)
-    const profileStartIdx = updateRowIdx + 5
+    const profileStartIdx = updateRowIdx + 6
     const maxRowIdx = savedProfiles.length > 0 ? profileStartIdx + savedProfiles.length - 1 : updateRowIdx
 
     lines.push('')
@@ -610,6 +619,8 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${chalk.yellow('Shift+S')}  Save current config as a named profile  ${chalk.dim('(inline prompt — type name + Enter)')}`)
     lines.push(`             ${chalk.dim('Profiles store: favorites, sort, tier filter, ping interval, configured-only filter, API keys.')}`)
     lines.push(`             ${chalk.dim('Use --profile <name> to load a profile on startup.')}`)
+    lines.push(`  ${chalk.yellow('Shift+R')}  Reset view settings  ${chalk.dim('(tier filter, sort, provider filter → defaults)')}`)
+    lines.push(`  ${chalk.yellow('N')}  Changelog  ${chalk.dim('(📋 browse all versions, Enter to view details)')}`)
     lines.push(`  ${chalk.yellow('K')} / ${chalk.yellow('Esc')}  Show/hide this help`)
     lines.push(`  ${chalk.yellow('Ctrl+C')}  Exit`)
     lines.push('')
@@ -1239,6 +1250,97 @@ export function createOverlayRenderers(state, deps) {
     return cleared.join('\n')
   }
 
+  // ─── Changelog overlay renderer ───────────────────────────────────────────
+  // 📖 renderChangelog: Two-phase overlay — index of all versions or details of one version
+  function renderChangelog() {
+    const EL = '\x1b[K'
+    const lines = []
+    const changelogData = loadChangelog()
+    const { versions } = changelogData
+    const versionList = Object.keys(versions).sort((a, b) => {
+      const aParts = a.split('.').map(Number)
+      const bParts = b.split('.').map(Number)
+      for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aVal = aParts[i] || 0
+        const bVal = bParts[i] || 0
+        if (bVal !== aVal) return bVal - aVal
+      }
+      return 0
+    })
+
+    // 📖 Branding header
+    lines.push(`  ${chalk.cyanBright('🚀')} ${chalk.bold.cyanBright('free-coding-models')} ${chalk.dim(`v${LOCAL_VERSION}`)}`)
+
+    if (state.changelogPhase === 'index') {
+      // ═══════════════════════════════════════════════════════════════════════
+      // 📖 INDEX PHASE: Show all versions with selection
+      // ═══════════════════════════════════════════════════════════════════════
+      lines.push(`  ${chalk.bold('📋 Changelog - All Versions')}`)
+      lines.push(`  ${chalk.dim('— ↑↓ navigate • Enter select • Esc close')}`)
+      lines.push('')
+
+      for (let i = 0; i < versionList.length; i++) {
+        const version = versionList[i]
+        const changes = versions[version]
+        const isSelected = i === state.changelogCursor
+
+        // 📖 Count items in this version
+        let itemCount = 0
+        for (const key of ['added', 'fixed', 'changed', 'updated']) {
+          if (changes[key]) itemCount += changes[key].length
+        }
+
+        // 📖 Format version line with selection highlight
+        const versionStr = `  v${version.padEnd(8)} — ${itemCount} ${itemCount === 1 ? 'change' : 'changes'}`
+        if (isSelected) {
+          lines.push(chalk.inverse(versionStr))
+        } else {
+          lines.push(versionStr)
+        }
+      }
+
+      lines.push('')
+      lines.push(`  ${chalk.dim(`Total: ${versionList.length} versions`)}`)
+
+    } else if (state.changelogPhase === 'details') {
+      // ═══════════════════════════════════════════════════════════════════════
+      // 📖 DETAILS PHASE: Show detailed changes for selected version
+      // ═══════════════════════════════════════════════════════════════════════
+      lines.push(`  ${chalk.bold(`📋 v${state.changelogSelectedVersion}`)}`)
+      lines.push(`  ${chalk.dim('— ↑↓ / PgUp / PgDn scroll • B back • Esc close')}`)
+      lines.push('')
+
+      const changes = versions[state.changelogSelectedVersion]
+      if (changes) {
+        const sections = { added: '✨ Added', fixed: '🐛 Fixed', changed: '🔄 Changed', updated: '📝 Updated' }
+        for (const [key, label] of Object.entries(sections)) {
+          if (changes[key] && changes[key].length > 0) {
+            lines.push(`  ${chalk.yellow(label)}`)
+            for (const item of changes[key]) {
+              // 📖 Unwrap markdown bold/code markers for display
+              let displayText = item.replace(/\*\*([^*]+)\*\*/g, '$1').replace(/`([^`]+)`/g, '$1')
+              // 📖 Wrap long lines
+              const maxWidth = state.terminalCols - 16
+              if (displayText.length > maxWidth) {
+                displayText = displayText.substring(0, maxWidth - 3) + '…'
+              }
+              lines.push(`    • ${displayText}`)
+            }
+            lines.push('')
+          }
+        }
+      }
+    }
+
+    // 📖 Use scrolling with overlay handler
+    const CHANGELOG_OVERLAY_BG = chalk.bgRgb(10, 40, 80)  // Dark blue background
+    const { visible, offset } = sliceOverlayLines(lines, state.changelogScrollOffset, state.terminalRows)
+    state.changelogScrollOffset = offset
+    const tintedLines = tintOverlayLines(visible, CHANGELOG_OVERLAY_BG, state.terminalCols)
+    const cleared = tintedLines.map(l => l + EL)
+    return cleared.join('\n')
+  }
+
   // 📖 stopRecommendAnalysis: cleanup timers if user cancels during analysis
   function stopRecommendAnalysis() {
     if (state.recommendAnalysisTimer) { clearInterval(state.recommendAnalysisTimer); state.recommendAnalysisTimer = null }
@@ -1253,6 +1355,7 @@ export function createOverlayRenderers(state, deps) {
     renderRecommend,
     renderFeatureRequest,
     renderBugReport,
+    renderChangelog,
     startRecommendAnalysis,
     stopRecommendAnalysis,
   }

package/src/render-table.js

@@ -672,6 +672,8 @@ export function renderTable(results, pendingPings, frame, cursor = null, sortCol
       chalk.dim(' → ') +
       chalk.rgb(200, 150, 255)('https://discord.gg/ZTNFHvvCkU') +
       chalk.dim('  •  ') +
+      chalk.yellow('N') + chalk.dim(' Changelog') +
+      chalk.dim('  •  ') +
       chalk.dim('Ctrl+C Exit')
   }
   lines.push(footerLine)