free-coding-models 0.3.56 → 0.3.58

package/src/key-handler.js

@@ -8,7 +8,7 @@
  *   tool launch actions. It also keeps the live key bindings aligned with the
  *   highlighted letters shown in the table headers.
  *
- *   📖 Key I opens the unified "Feedback, bugs & requests" overlay.
+ *   📖 Key I opens the changelog overlay.
  *
  *   It also owns the "test key" model selection used by the Settings overlay.
  *   Anonymous telemetry hooks for model launches and a few high-signal settings
@@ -291,7 +291,6 @@ export function createKeyHandler(ctx) {
     sendUsageTelemetry,
     startRecommendAnalysis,
     stopRecommendAnalysis,
-    sendBugReport,
     stopUi,
     ping,
     getPingModel,
@@ -950,12 +949,7 @@ export function createKeyHandler(ctx) {
     state.installEndpointsResult = null
   }
 
-  function openFeedbackOverlay() {
-    state.feedbackOpen = true
-    state.bugReportBuffer = ''
-    state.bugReportStatus = 'idle'
-    state.bugReportError = null
-  }
+
 
   function openChangelogOverlay() {
     state.changelogOpen = true
@@ -1115,7 +1109,7 @@ export function createKeyHandler(ctx) {
       || state.installedModelsOpen
       || state.routerDashboardOpen
       || state.recommendOpen
-      || state.feedbackOpen
+
       || state.helpVisible
       || state.changelogOpen
   }
@@ -1303,7 +1297,7 @@ export function createKeyHandler(ctx) {
         state.helpScrollOffset = 0
         return
       case 'open-changelog': return openChangelogOverlay()
-      case 'open-feedback': return openFeedbackOverlay()
+
       case 'open-recommend': return openRecommendOverlay()
       case 'open-router-dashboard': return openRouterDashboardOverlay(state)
       case 'open-token-usage': return openTokenUsageOverlay()
@@ -1433,7 +1427,7 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    if (!state.feedbackOpen && !state.settingsEditMode && !state.settingsAddKeyMode && key.name === 'g' && !key.ctrl && !key.meta) {
+    if (!state.settingsEditMode && !state.settingsAddKeyMode && key.name === 'g' && !key.ctrl && !key.meta) {
       cycleGlobalTheme()
       return
     }
@@ -1889,72 +1883,7 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 Feedback overlay: intercept ALL keys while overlay is active.
-    // 📖 Enter → send to Discord, Esc → cancel, Backspace → delete char, printable → append to buffer.
-    if (state.feedbackOpen) {
-      if (key.ctrl && key.name === 'c') { exit(0); return }
-
-      if (key.name === 'escape') {
-        // 📖 Cancel feedback — close overlay
-        state.feedbackOpen = false
-        state.bugReportBuffer = ''
-        state.bugReportStatus = 'idle'
-        state.bugReportError = null
-        return
-      }
-
-      if (key.name === 'return') {
-        // 📖 Send feedback to Discord webhook
-        const message = state.bugReportBuffer.trim()
-        if (message.length > 0 && state.bugReportStatus !== 'sending') {
-          state.bugReportStatus = 'sending'
-          const result = await sendBugReport(message)
-          if (result.success) {
-            // 📖 Success — show confirmation briefly, then close overlay after 3 seconds
-            state.bugReportStatus = 'success'
-            setTimeout(() => {
-              state.feedbackOpen = false
-              state.bugReportBuffer = ''
-              state.bugReportStatus = 'idle'
-              state.bugReportError = null
-            }, 3000)
-          } else {
-            // 📖 Error — show error message, keep overlay open
-            state.bugReportStatus = 'error'
-            state.bugReportError = result.error || 'Unknown error'
-          }
-        }
-        return
-      }
 
-      if (key.name === 'backspace') {
-        // 📖 Don't allow editing while sending or after success
-        if (state.bugReportStatus === 'sending' || state.bugReportStatus === 'success') return
-        state.bugReportBuffer = state.bugReportBuffer.slice(0, -1)
-        // 📖 Clear error status when user starts editing again
-        if (state.bugReportStatus === 'error') {
-          state.bugReportStatus = 'idle'
-          state.bugReportError = null
-        }
-        return
-      }
-
-      // 📖 Append printable characters (str is the raw character typed)
-      // 📖 Limit to 500 characters (Discord embed description limit)
-      if (str && str.length === 1 && !key.ctrl && !key.meta) {
-        // 📖 Don't allow editing while sending or after success
-        if (state.bugReportStatus === 'sending' || state.bugReportStatus === 'success') return
-        if (state.bugReportBuffer.length < 500) {
-          state.bugReportBuffer += str
-          // 📖 Clear error status when user starts editing again
-          if (state.bugReportStatus === 'error') {
-            state.bugReportStatus = 'idle'
-            state.bugReportError = null
-          }
-        }
-      }
-      return
-    }
 
     // 📖 Help overlay: full keyboard navigation + key swallowing while overlay is open.
     if (state.helpVisible) {
@@ -2629,7 +2558,8 @@ export function createKeyHandler(ctx) {
 
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
-    // 📖 Shift+R: open the Smart Model Router dashboard from the main table.
+    // 📖 Shift+R intentionally stays unadvertised in the main UI, but remains
+    // 📖 available as a tester entry point for the Router Dashboard.
     if (key.name === 'r' && key.shift && !key.ctrl && !key.meta) {
       openRouterDashboardOverlay(state)
       return
@@ -2670,11 +2600,7 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 I key: open Feedback overlay (anonymous Discord feedback)
-    if (key.name === 'i') {
-      openFeedbackOverlay()
-      return
-    }
+
 
     // 📖 W cycles the supported ping modes:
     // 📖 speed (2s) → normal (10s) → slow (30s) → forced (4s) → speed.
@@ -2686,17 +2612,7 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 Ctrl+O: toggle footer visibility (collapse to single hint when hidden)
-    if (key.ctrl && key.name === 'o' && !key.meta) {
-      state.footerHidden = !state.footerHidden
-      if (!state.config.settings || typeof state.config.settings !== 'object') state.config.settings = {}
-      state.config.settings.footerHidden = state.footerHidden
-      saveConfig(state.config)
-      state.frame++ // 📖 Force immediate re-render
-      return
-    }
-
-    // 📖 E toggles hiding models whose provider has no configured API key.
+    // 📖 E toggles "Show only configured & working models": hides models whose provider has no configured API key, or whose health status is noauth/auth_error (but keeps timeout and 429).
     // 📖 The preference is saved globally.
     if (key.name === 'e') {
       state.hideUnconfiguredModels = !state.hideUnconfiguredModels
@@ -2746,8 +2662,8 @@ export function createKeyHandler(ctx) {
       return
     }
 
-    // 📖 Help overlay key: Ctrl+H = toggle help overlay
-    if (key.ctrl && key.name === 'h') {
+    // 📖 Help overlay key: I = toggle help overlay
+    if (key.name === 'i') {
       state.helpVisible = !state.helpVisible
       if (state.helpVisible) state.helpScrollOffset = 0
       return
@@ -3002,10 +2918,7 @@ export function createMouseEventHandler(ctx) {
         }
         return
       }
-      if (state.feedbackOpen) {
-        // 📖 Feedback overlay doesn't scroll — ignore
-        return
-      }
+
       if (state.commandPaletteOpen) {
         // 📖 Command palette: scroll the results list
         const count = state.commandPaletteResults?.length || 0
@@ -3147,12 +3060,7 @@ export function createMouseEventHandler(ctx) {
       return
     }
 
-    if (state.feedbackOpen) {
-      // 📖 Feedback overlay: click anywhere closes (no scroll, no cursor)
-      state.feedbackOpen = false
-      state.feedbackInput = ''
-      return
-    }
+
 
     if (state.helpVisible) {
       // 📖 Help overlay: click anywhere closes (same as K or Escape)

package/src/overlays.js

@@ -4,15 +4,13 @@
  *
  * @details
  *   This module centralizes all overlay rendering in one place:
- *   - Settings, Install Endpoints, Command Palette, Help, Smart Recommend, Feedback, Changelog, Router Dashboard
+ *   - Settings, Install Endpoints, Command Palette, Help, Smart Recommend, Changelog, Router Dashboard
  *   - Settings diagnostics for provider key tests, including wrapped retry/error details
  *   - Recommend analysis timer orchestration and progress updates
  *
  *   The factory pattern keeps stateful UI logic isolated while still
  *   allowing the main CLI to control shared state and dependencies.
  *
- *   📖 Feedback overlay (I key) combines feature requests + bug reports in one left-aligned input
- *
  *   → Functions:
  *   - `createOverlayRenderers` — returns renderer + analysis helpers + overlayLayout
  *   - `renderRouterDashboard` — mounts the Smart Model Router dashboard renderer
@@ -299,12 +297,16 @@ export function createOverlayRenderers(state, deps) {
     }
     lines.push('')
 
-    // 📖 Footer with credits
+    // 📖 Footer with credits + community links — Discord and Buy me a coffee
+    // 📖 live here (and in the onboarding) instead of the main TUI footer to
+    // 📖 keep the table chrome lean.
     lines.push('')
     lines.push(
       themeColors.dim('  ') +
       themeColors.footerLove('Made with 💖 & ☕ by ') +
       themeColors.link('\x1b]8;;https://github.com/vava-nessa\x1b\\vava-nessa\x1b]8;;\x1b\\') +
+      themeColors.dim('  •  💬 ') +
+      themeColors.footerDiscord('\x1b]8;;https://discord.gg/ZTNFHvvCkU\x1b\\Join the Discord\x1b]8;;\x1b\\') +
       themeColors.dim('  •  ☕ ') +
       themeColors.footerCoffee('\x1b]8;;https://buymeacoffee.com/vavanessadev\x1b\\Buy me a coffee\x1b]8;;\x1b\\') +
       themeColors.dim('  •  ') +
@@ -868,8 +870,9 @@ export function createOverlayRenderers(state, deps) {
     // 📖 Branding header
     lines.push(`  ${themeColors.accent('🚀')} ${themeColors.accentBold('free-coding-models')} ${themeColors.dim(`v${LOCAL_VERSION}`)}`)
     lines.push(`  ${heading('❓ Help & Keyboard Shortcuts')}`)
+    lines.push(`  ${themeColors.successBold('🔑 Yellow = active key')}`)
     lines.push('')
-    lines.push(`  ${hint('— ↑↓ / PgUp / PgDn / Home / End scroll • K or Esc close')}`)
+    lines.push(`  ${hint('— ↑↓ / PgUp / PgDn / Home / End scroll • K or ')}${themeColors.successBold('Esc close')}`)
     lines.push(`  ${heading('Columns')}`)
     lines.push('')
     lines.push(`  ${label('Rank')}        SWE-bench rank (1 = best coding score)  ${hint('Sort:')} ${key('R')}`)
@@ -884,7 +887,7 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${label('CTX')}         Context window size (128k, 200k, 256k, 1m, etc.)  ${hint('Sort:')} ${key('C')}`)
     lines.push(`              ${hint('Bigger context = the model can read more of your codebase at once without forgetting.')}`)
     lines.push('')
-    lines.push(`  ${label('Model')}       Model name (①②③ = favorite order)  ${hint('Sort:')} ${key('M')}  ${hint('Favorite:')} ${key('F')}`)
+    lines.push(`  ${label('Model')}       Model name (1️⃣2️⃣3️⃣ = favorite order)  ${hint('Sort:')} ${key('M')}  ${hint('Favorite:')} ${key('F')}`)
     lines.push(`              ${hint('Star the ones you like. Press Y to switch between pinned mode and normal filter/sort mode.')}`)
     lines.push('')
     lines.push(`  ${label('Provider')}    Provider source (NIM, Groq, Cerebras, etc.)  ${hint('Sort:')} ${key('O')}  ${hint('Cycle:')} ${key('D')}`)
@@ -925,19 +928,18 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${key('Ctrl+P')}  Open ⚡️ command palette  ${hint('(search and run actions quickly)')}`)
     lines.push(`  ${key('E')}  Toggle configured models only  ${hint('(enabled by default)')}`)
     lines.push(`  ${key('Z')}  Cycle tool mode  ${hint('(📦 OpenCode → π Pi → 🪼 jcode → 📦 Desktop → 🦞 OpenClaw → 💘 Crush → 🪿 Goose → 🛠 Aider → 🐉 Qwen → 🤲 OpenHands → ⚡ Amp → 🦘 Rovo → ♊ Gemini)')}`)
-    lines.push(`  ${key('F')}  Toggle favorite on selected row  ${hint('(①②③ = router fallback order)')}`)
+    lines.push(`  ${key('F')}  Toggle favorite on selected row  ${hint('(1️⃣2️⃣3️⃣ = router fallback order, capped at 🔟)')}`)
     lines.push(`  ${key('⇧↑/⇧↓')}  Reorder selected favorite up/down  ${hint('(changes router priority)')}`)
     lines.push(`  ${key('Y')}  Toggle favorites mode  ${hint('(Pinned + always visible ↔ Normal filter/sort behavior)')}`)
     lines.push(`  ${key('X')}  Clear active text filter  ${hint('(remove custom query applied from ⚡️ Command Palette)')}`)
     lines.push(`  ${key('Q')}  Smart Recommend  ${hint('(🎯 find the best model for your task — questionnaire + live analysis)')}`)
-    lines.push(`  ${key('Shift+R')}  Router Dashboard  ${hint('(🔀 daemon health, circuit breakers, tokens, request log)')}`)
     lines.push(`  ${key('G')}  Cycle theme  ${hint('(auto → dark → light)')}`)
-    lines.push(`  ${themeColors.errorBold('I')}  Feedback, bugs & requests  ${hint('(📝 send anonymous feedback, bug reports, or feature requests)')}`)
+
     lines.push(`  ${key('P')}  Open settings  ${hint('(manage API keys, provider toggles, updates, legacy cleanup)')}`)
       // 📖 Profile system removed - API keys now persist permanently across all sessions
     lines.push(`  ${key('Ctrl+P')}  Reset view settings  ${hint('(search "Reset view" in the command palette)')}`)
     lines.push(`  ${key('N')}  Changelog  ${hint('(📋 browse all versions, Enter to view details)')}`)
-    lines.push(`  ${key('Ctrl+H')} / ${key('Esc')}  Show/hide this help`)
+    lines.push(`  ${key('I')} / ${key('Esc')}  Show/hide this help`)
     lines.push(`  ${key('Ctrl+C')}  Exit`)
     lines.push('')
     lines.push(`  ${heading('Settings (P)')}`)
@@ -1170,92 +1172,6 @@ export function createOverlayRenderers(state, deps) {
     }, PING_RATE)
   }
 
-  // ─── Feedback overlay renderer ────────────────────────────────────────────
-  // 📖 renderFeedback: Draw the overlay for anonymous Discord feedback.
-  // 📖 Shows an input field where users can type feedback, bug reports, or any comments.
-  function renderFeedback() {
-    const EL = '\x1b[K'
-    const lines = []
-
-    // 📖 Calculate available space for multi-line input (dynamic based on terminal width)
-    const maxInputWidth = state.terminalCols - 8 // 8 = padding (4 spaces each side)
-    const maxInputLines = 10 // Show up to 10 lines of input
-    
-    // 📖 Split buffer into lines for display (with wrapping)
-    const wrapText = (text, width) => {
-      const words = text.split(' ')
-      const lines = []
-      let currentLine = ''
-      
-      for (const word of words) {
-        const testLine = currentLine ? currentLine + ' ' + word : word
-        if (testLine.length <= width) {
-          currentLine = testLine
-        } else {
-          if (currentLine) lines.push(currentLine)
-          currentLine = word
-        }
-      }
-      if (currentLine) lines.push(currentLine)
-      return lines
-    }
-
-    const inputLines = wrapText(state.bugReportBuffer, maxInputWidth)
-    const displayLines = inputLines.slice(0, maxInputLines)
-
-    // 📖 Branding header
-    lines.push('')
-    lines.push(`  ${themeColors.accent('🚀')} ${themeColors.accentBold('free-coding-models')} ${themeColors.dim(`v${LOCAL_VERSION}`)}`)
-    lines.push(`  ${themeColors.successBold('📝 Feedback, bugs & requests')}`)
-    lines.push('')
-    lines.push(themeColors.dim("  — don't hesitate to send us feedback, bug reports, or just your feeling about the app"))
-    lines.push('')
-    
-    // 📖 Status messages (if any)
-    if (state.bugReportStatus === 'sending') {
-      lines.push(`  ${themeColors.warning('⏳ Sending...')}`)
-      lines.push('')
-    } else if (state.bugReportStatus === 'success') {
-      lines.push(`  ${themeColors.successBold('✅ Successfully sent!')} ${themeColors.dim('Closing overlay in 3 seconds...')}`)
-      lines.push('')
-      lines.push(`  ${themeColors.dim('Thank you for your feedback! It has been sent to the project team.')}`)
-      lines.push('')
-    } else if (state.bugReportStatus === 'error') {
-      lines.push(`  ${themeColors.error('❌ Error:')} ${themeColors.warning(state.bugReportError || 'Failed to send')}`)
-      lines.push(`  ${themeColors.dim('Press Backspace to edit, or Esc to close')}`)
-      lines.push('')
-    } else {
-      lines.push(`  ${themeColors.dim('Type your feedback below. Press Enter to send, Esc to cancel.')}`)
-      lines.push(`  ${themeColors.dim('Your message will be sent anonymously to the project team.')}`)
-      lines.push('')
-    }
-
-    // 📖 Simple input area – left-aligned, framed by horizontal lines
-    lines.push(`  ${themeColors.info('Message')} (${state.bugReportBuffer.length}/500 chars)`)
-    lines.push(`  ${themeColors.dim('─'.repeat(maxInputWidth))}`)
-    // 📖 Input lines — left-aligned, or placeholder when empty
-    if (displayLines.length > 0) {
-      for (const line of displayLines) {
-        lines.push(`    ${line}`)
-      }
-      // 📖 Show cursor on last line
-      if (state.bugReportStatus === 'idle' || state.bugReportStatus === 'error') {
-        lines[lines.length - 1] += themeColors.accentBold('▏')
-      }
-    } else {
-      const placeholderBR = state.bugReportStatus === 'idle' ? chalk.italic.rgb(...getProviderRgb('googleai'))('Type your message here...') : ''
-      lines.push(`    ${placeholderBR}${themeColors.accentBold('▏')}`)
-    }
-    lines.push(`  ${themeColors.dim('─'.repeat(maxInputWidth))}`)
-    lines.push('')
-    lines.push(themeColors.dim('  Enter Send  •  Esc Cancel  •  Backspace Delete'))
-
-    // 📖 Apply overlay tint and return
-    const tintedLines = tintOverlayLines(lines, themeColors.overlayBgFeedback, state.terminalCols)
-    const cleared = tintedLines.map(l => l + EL)
-    return cleared.join('\n')
-  }
-
   // ─── Changelog overlay renderer ───────────────────────────────────────────
   // 📖 renderChangelog: Two-phase overlay — index of all versions or details of one version
   function renderChangelog() {
@@ -1606,7 +1522,7 @@ export function createOverlayRenderers(state, deps) {
     lines.push(`  ${totalRow.join(' ')}`)
 
     lines.push('')
-    lines.push(themeColors.dim('  Esc Back to main table  •  Shift+R Router Dashboard'))
+    lines.push(themeColors.dim('  Esc Back to main table'))
 
     const { visible, offset } = sliceOverlayLines(lines, state.tokenUsageScrollOffset, state.terminalRows)
     state.tokenUsageScrollOffset = offset
@@ -1641,7 +1557,7 @@ export function createOverlayRenderers(state, deps) {
       lines.push(themeColors.info('  Enabling router, please wait...'))
     } else if (state.routerOnboardingPhase === 'success') {
       lines.push(themeColors.success('  ✅ Router enabled! Dashboard opening...'))
-      lines.push(themeColors.dim('  Shift+R to reopen the dashboard anytime'))
+      lines.push(themeColors.dim('  Setup complete. Return to the main table to continue.'))
     } else if (state.routerOnboardingPhase === 'error') {
       lines.push(themeColors.error(`  ❌ ${state.routerOnboardingError || 'Failed to enable router'}`))
       lines.push(themeColors.dim('  Press Esc or Enter to continue to the main table'))
@@ -1657,6 +1573,12 @@ export function createOverlayRenderers(state, deps) {
         lines.push('')
       }
       lines.push(themeColors.dim('  ↑↓ Navigate  •  Enter Select  •  Esc Skip for now'))
+      lines.push('')
+      lines.push(
+        themeColors.dim('  💬 ') +
+        themeColors.footerDiscord('\x1b]8;;https://discord.gg/ZTNFHvvCkU\x1b\\Join the Discord community\x1b]8;;\x1b\\') +
+        themeColors.dim('  •  Get help, share feedback, follow updates')
+      )
     }
 
     const targetLine = cursorLineByRow[state.routerOnboardingCursor] ?? 0
@@ -1667,26 +1589,6 @@ export function createOverlayRenderers(state, deps) {
     return tintedLines.map((l) => l + EL).join('\n')
   }
 
-  // ─── Router upgrade banner (inline in main table, not an overlay) ─────────────
-  // 📖 renderRouterUpgradeBanner: non-blocking notification at top of the table
-  // 📖 shown once to existing users who haven't seen router yet. Auto-dismisses after 10s.
-  function renderRouterUpgradeBanner() {
-    const EL = '\x1b[K'
-    const now = Date.now()
-    const BANNER_TTL_MS = 10_000
-    // Dismissed or already seen in this session?
-    if (state.routerUpgradeBannerDismissedAt > 0) return ''
-    if (state.routerUpgradeBannerShownAt === 0) state.routerUpgradeBannerShownAt = now
-    if (now - state.routerUpgradeBannerShownAt > BANNER_TTL_MS) {
-      state.routerUpgradeBannerDismissedAt = now
-      return ''
-    }
-    const remaining = Math.ceil((BANNER_TTL_MS - (now - state.routerUpgradeBannerShownAt)) / 1000)
-    const msg = `  ${themeColors.accentBold('🆕')}  ${themeColors.textBold('Smart Router is now available!')}  ${themeColors.dim('Press')}  ${themeColors.hotkey('Shift+R')}  ${themeColors.dim('to set it up.')}  ${themeColors.dim(`(dismisses in ${remaining}s)`)}`
-    const pad = state.terminalCols > displayWidth(msg) ? ' '.repeat(Math.max(0, state.terminalCols - displayWidth(msg))) : ''
-    return themeColors.warningBold(msg + pad)
-  }
-
   return {
     renderSettings,
     renderInstallEndpoints,
@@ -1694,14 +1596,12 @@ export function createOverlayRenderers(state, deps) {
     renderCommandPalette,
     renderHelp,
     renderRecommend,
-    renderFeedback,
     renderChangelog,
     renderInstalledModels,
     renderRouterDashboard,
     renderIncompatibleFallback,
     renderTokenUsage,
     renderRouterOnboarding,
-    renderRouterUpgradeBanner,
     startRecommendAnalysis,
     stopRecommendAnalysis,
     overlayLayout,

package/src/provider-metadata.js

@@ -116,7 +116,7 @@ export const PROVIDER_METADATA = {
     rateLimits: 'Quota depends on GitHub/Copilot tier; no separate provider billing',
   },
   mistral: {
-    label: 'Mistral La Plateforme',
+    label: 'Mistral LP',
     color: chalk.rgb(255, 196, 120),
     signupUrl: 'https://console.mistral.ai/api-keys',
     signupHint: 'La Plateforme → API keys (MISTRAL_API_KEY)',

package/src/render-helpers.js

@@ -47,7 +47,7 @@
  */
 
 import chalk from 'chalk'
-import { OVERLAY_PANEL_WIDTH, TABLE_FIXED_LINES } from './constants.js'
+import { OVERLAY_PANEL_WIDTH, TABLE_FIXED_LINES, TABLE_HEADER_LINES, TABLE_FOOTER_LINES } from './constants.js'
 import { sortResults } from './utils.js'
 
 // 📖 stripAnsi: Remove ANSI color/control sequences to estimate visible text width before padding.
@@ -65,13 +65,32 @@ export function maskApiKey(key) {
 
 // 📖 displayWidth: Calculate display width of a string in terminal columns.
 // 📖 Emojis and other wide characters occupy 2 columns, variation selectors (U+FE0F) are zero-width.
+// 📖 Keycap sequences (digit/# + FE0F + 20E3, e.g. 1️⃣) render as a single 2-cell glyph.
 // 📖 This avoids pulling in a full `string-width` dependency for a lightweight CLI tool.
 export function displayWidth(str) {
   const plain = stripAnsi(String(str))
+  const codepoints = [...plain]
   let w = 0
-  for (const ch of plain) {
+  for (let i = 0; i < codepoints.length; i++) {
+    const ch = codepoints[i]
     const cp = ch.codePointAt(0)
-    // Zero-width: variation selectors (FE00-FE0F), zero-width joiner/non-joiner, combining marks
+
+    // Keycap sequence detection: ASCII digit / # / * followed by optional FE0F then 20E3 → +2 (single emoji glyph)
+    const isKeycapBase = (cp >= 0x30 && cp <= 0x39) || cp === 0x23 || cp === 0x2A
+    if (isKeycapBase) {
+      let j = i + 1
+      let sawFe0f = false
+      if (j < codepoints.length && codepoints[j].codePointAt(0) === 0xFE0F) { sawFe0f = true; j++ }
+      if (j < codepoints.length && codepoints[j].codePointAt(0) === 0x20E3) {
+        w += 2
+        i = j // 📖 skip the consumed FE0F (if any) and the 20E3
+        continue
+      }
+      // 📖 Not a keycap, fall through to normal handling
+      void sawFe0f
+    }
+
+    // Zero-width: variation selectors (FE00-FE0F), zero-width joiner/non-joiner, lone combining keycap
     if ((cp >= 0xFE00 && cp <= 0xFE0F) || cp === 0x200D || cp === 0x200C || cp === 0x20E3) continue
     // Wide: CJK, emoji (most above U+1F000), fullwidth forms
     if (
@@ -146,14 +165,24 @@ export function sliceOverlayLines(lines, offset, terminalRows) {
 
 // ─── Table viewport calculation ────────────────────────────────────────────────
 
+// 📖 getTableFixedLines: Resolve the non-model line budget for the main table.
+// 📖 Header and full footer are always visible in the main table, with optional
+// 📖 extra fixed rows for temporary banners.
+export function getTableFixedLines({ extraFixedLines = 0 } = {}) {
+  return TABLE_HEADER_LINES + TABLE_FOOTER_LINES + Math.max(0, extraFixedLines)
+}
+
 // 📖 calculateViewport: Computes the visible slice of model rows that fits in the terminal.
 // 📖 When scroll indicators are needed, they each consume 1 line from the model budget.
-// 📖 `extraFixedLines` lets callers reserve temporary footer rows without shrinking the
-// 📖 viewport permanently for the normal case.
+// 📖 `lineBudget` lets callers reserve temporary footer/header rows without shrinking
+// 📖 the viewport permanently for the normal case.
 // 📖 Returns { startIdx, endIdx, hasAbove, hasBelow } for rendering.
-export function calculateViewport(terminalRows, scrollOffset, totalModels, extraFixedLines = 0) {
+export function calculateViewport(terminalRows, scrollOffset, totalModels, lineBudget = 0) {
   if (terminalRows <= 0) return { startIdx: 0, endIdx: totalModels, hasAbove: false, hasBelow: false }
-  let maxSlots = terminalRows - TABLE_FIXED_LINES - extraFixedLines
+  const fixedLines = typeof lineBudget === 'number'
+    ? TABLE_FIXED_LINES + Math.max(0, lineBudget)
+    : getTableFixedLines(lineBudget)
+  let maxSlots = terminalRows - fixedLines
   if (maxSlots < 1) maxSlots = 1
   if (totalModels <= maxSlots) return { startIdx: 0, endIdx: totalModels, hasAbove: false, hasBelow: false }
 
@@ -206,7 +235,8 @@ export function sortResultsWithPinnedFavorites(results, sortColumn, sortDirectio
 // 📖 Modifies st.scrollOffset in-place, returns undefined.
 export function adjustScrollOffset(st) {
   const total = st.visibleSorted ? st.visibleSorted.length : st.results.filter(r => !r.hidden).length
-  let maxSlots = st.terminalRows - TABLE_FIXED_LINES
+  const fixedLines = getTableFixedLines()
+  let maxSlots = st.terminalRows - fixedLines
   if (maxSlots < 1) maxSlots = 1
   if (total <= maxSlots) { st.scrollOffset = 0; return }
   // Ensure cursor is not above the visible window