free-coding-models 0.5.12 → 0.5.15

package/changelog/v0.5.13.md

@@ -0,0 +1,23 @@
+# Changelog v0.5.13 - 2026-06-04
+
+### Added
+- **Provider dropdown with SVG logos + health indicators** — The native `<select>` for provider filtering has been replaced by a custom dropdown that renders each provider's SVG icon + text wordmark (same `ProviderLogo` component used in the model table) alongside a color-coded health indicator dot:
+  - 🟢 Green = API key configured and at least one model is UP
+  - 🔴 Red = API key set but models are DOWN or have auth errors
+  - ⚪ Gray = No API key configured
+  - Colors adapt for both dark and light themes for readability.
+  - Scrollable list with keyboard support (Escape to close, click-outside to dismiss).
+- **Collapsible filter groups** — Tier, Status, Verdict, and Health filter chips are now collapsible dropdown triggers (like the Ping selector). Shows `LABEL: value` as a compact button; click to expand the chip row. Reduces visual clutter while keeping full chip sets on demand.
+- **Playground direct provider routing** — The playground can now chat directly with any "UP" model (not just via the router daemon). Select a specific model → the request goes straight to the provider endpoint. Falls back to daemon for `fcm` auto-router. Clear error messages when no API key is configured for the selected provider.
+- **Playground daemon start/stop controls** — When the router daemon is offline, the Playground now shows a start button instead of a dead panel. One-click to launch the daemon and begin chatting.
+- **"How the FCM Router works" help section** — New section in the Help modal (and TUI help overlay) explaining the smart router, pre-prompt, probe mechanism, circuit breaker states, failover order, auto-heal, and rate limits in plain English.
+- **Router circuit breaker friendly labels** — Circuit state badges in the Router dashboard now show human-readable labels (`Healthy`, `Down`, `Recovering`, `Auth error`) instead of raw internal names (`CLOSED`, `OPEN`, `HALF_OPEN`).
+- **Next-ping countdown with millisecond precision** — The filter bar countdown now shows `3.58s` format instead of rounding to whole seconds, matching TUI parity.
+
+### Changed
+- **FilterBar refactor** — Replaced the inline `ChipRow` component with a reusable `FilterGroup` component that handles collapsible open/close state, click-outside detection, and keyboard dismiss. The Ping selector was already using this pattern; now all filter groups use it.
+- **Provider data aggregation** — The `providers` prop passed to FilterBar now includes `hasKey` and `anyUp` boolean flags computed from the live model data, enabling the health indicator in the provider dropdown.
+- **Provider dropdown replaces native `<select>`** — The `<select id="provider-select">` and its CSS (`.providerSelect`) are removed from FilterBar. The new `ProviderDropdown` component provides SVG logo rendering, health dots, and a scrollable menu that's consistent with the rest of the filter bar UX.
+
+### Fixed
+- **Playground no longer dead when router offline** — Previously the Playground showed a static "Router offline" message with no action. Now it offers a start button and can also chat directly with providers that have working API keys.

package/changelog/v0.5.15.md

@@ -0,0 +1,17 @@
+# Changelog v0.5.15 - 2026-06-04
+
+### Added
+- **G Theme** footer hotkey — `G` now appears in the bottom shortcut bar with a prominent info-bold style so users immediately see they can cycle `auto → dark → light` themes from the keyboard
+- **Forced background colours per theme** — light mode paints a pure white background (`#FFFFFF`) on every line, and dark mode paints a deep dark blue-black background (`#070D18`), completely ignoring the terminal's native colour scheme. Light mode now renders correctly even inside a macOS Dark-mode terminal, and vice-versa
+- **Full dark/light palette coverage** — every hardcoded foreground and background colour in the TUI now has proper dark and light variants:
+  - Context window size colours (gold/green/teal/cyan) now use muted, readable variants in light mode
+  - Column header flash & sort-active backgrounds use auto-contrast text (`getReadableTextRgb`) instead of hardcoded white
+  - Auth-fail row backgrounds are light red in light mode instead of dark red
+  - Update banner, speed test badge, benchmark badge, Ctrl+P palette label, Twitter link, and release date text all have dedicated light-mode palette entries
+  - Header logo bar keeps its black background in both modes (intentional contrast)
+- Initial alt-screen fill with the active theme background colour to prevent a flash of the terminal's native bg before the first TUI frame renders
+
+### Changed
+- `THEME_BG_RGB` export in `theme.js` provides a dynamic bg fill color for the active theme
+- `renderTable` now injects `\x1b[48;2;R;G;Bm` before every `\x1b[K` (erase-to-EOL) and `\x1b[J` (erase-below) so space clearing respects the theme's background
+- 19 hardcoded `chalk.rgb()` / `chalk.bgRgb()` calls replaced with `currentPalette()` lookups

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.12",
+  "version": "0.5.15",
   "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",
@@ -67,6 +67,7 @@
     "@tabler/icons-react": "^3.44.0",
     "@tanstack/react-table": "^8.21.3",
     "chalk": "^5.6.2",
+    "kandown": "^0.4.0",
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3"
   },
@@ -76,8 +77,8 @@
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^6.0.2",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "vite": "^8.0.16",
     "vite-plus": "^0.1.23"
   }

package/src/tui/app.js

@@ -130,7 +130,7 @@ import { getConfiguredInstallableProviders, installProviderEndpoints, refreshIns
 import { loadCache, saveCache, clearCache, getCacheAge } from '../core/cache.js'
 import { checkConfigSecurity } from '../core/security.js'
 import { buildCliHelpText } from './cli-help.js'
-import { detectActiveTheme } from './theme.js'
+import { detectActiveTheme, THEME_BG_RGB, getTheme, patchThemeBg } from './theme.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -510,6 +510,16 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
 
   // 📖 Enter alternate screen — animation runs here, zero scrollback pollution
   process.stdout.write(ALT_ENTER)
+
+  // 📖 Force the entire alt-screen background to match the active theme so
+  // 📖 light mode is pure-white and dark mode is deep-dark, regardless of the
+  // 📖 terminal's native colour scheme. We paint every row + erase below.
+  const initBg = THEME_BG_RGB[getTheme()] ?? THEME_BG_RGB.dark
+  const bgFill = `\x1b[48;2;${initBg[0]};${initBg[1]};${initBg[2]}m`
+  const row = bgFill + ' '.repeat(state.terminalCols || 80) + '\x1b[K'
+  const initScreen = Array.from({ length: state.terminalRows || 24 }, () => row).join('\n')
+  process.stdout.write('\x1b[H' + initScreen + bgFill + '\x1b[J' + '\x1b[H')
+
   if (process.stdout.isTTY) {
     process.stdout.flush && process.stdout.flush()
   }
@@ -857,7 +867,9 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
               : state.changelogOpen
                 ? overlays.renderChangelog()
                  : tableContent
-    process.stdout.write(ALT_HOME + content)
+    // 📖 Strip stale bg resets emitted by chalk across ALL renderers (table + overlays).
+    const patched = patchThemeBg(content)
+    process.stdout.write(ALT_HOME + patched)
     if (process.stdout.isTTY) {
       process.stdout.flush && process.stdout.flush()
     }
@@ -877,7 +889,7 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
     benchmarkResults: state.benchmarkResults,
   })
 
-  process.stdout.write(ALT_HOME + renderTable({
+  process.stdout.write(ALT_HOME + patchThemeBg(renderTable({
     results: state.results,
     pendingPings: state.pendingPings,
     frame: state.frame,
@@ -910,7 +922,7 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
     bestModeOnly: state.bestModeOnly,
     benchmarkResults: state.benchmarkResults,
     benchmarkRunning: state.benchmarkRunning,
-  }))
+  })))
   if (process.stdout.isTTY) {
     process.stdout.flush && process.stdout.flush()
   }

package/src/tui/cli-help.js

@@ -60,6 +60,86 @@ const EXAMPLES = [
   "free-coding-models --json | jq '.[0]'",
 ]
 
+/**
+ * 📖 buildHowTheRouterWorks — a single-source explanation of the router
+ * 📖 internals (circuit breaker, probe mechanism, pre-prompt) that the
+ * 📖 Web Help modal and the TUI in-app help overlay both render. Keeping
+ * 📖 it here prevents the two surfaces from drifting apart.
+ */
+export function buildHowTheRouterWorksLines({ chalk = null, indent = '' } = {}) {
+  const lines = []
+  const header = (text) => `${indent}${paint(chalk, chalk?.bold, text)}`
+  const body = (text) => `${indent}${paint(chalk, chalk?.dim, text)}`
+  const bullet = (text) => `${indent}  • ${text}`
+
+  lines.push(header('How the FCM Router Works'))
+  lines.push('')
+
+  lines.push(header('1. The smart router daemon'))
+  lines.push(body('Point any OpenAI-compatible client at http://localhost:19280/v1'))
+  lines.push(body('with model: "fcm". The daemon picks the healthiest model in'))
+  lines.push(body('your active set and forwards the request — with automatic'))
+  lines.push(body('failover if the first model 429s or 5xxs.'))
+  lines.push('')
+
+  lines.push(header('2. The pre-prompt (system message)'))
+  lines.push(body('A first-class system message is injected on every proxied'))
+  lines.push(body('request. The default text introduces the assistant as the FCM'))
+  lines.push(body('routing agent and points the user to the dashboard URL.'))
+  lines.push(body('You can edit it from Settings (Settings → Pre-prompt).'))
+  lines.push('')
+
+  lines.push(header('3. The probe mechanism (every 10s/30s/120s)'))
+  lines.push(body('The daemon sends a 1-token chat-completion ping to every model'))
+  lines.push(body('in the active set. The probe measures latency + status code, not'))
+  lines.push(body('just URL reachability — so a wrong API key is caught and the'))
+  lines.push(body('circuit-breaker is opened.'))
+  lines.push(bullet('eco: probe every 120s (saves quota)'))
+  lines.push(bullet('balanced: probe every 30s (default)'))
+  lines.push(bullet('aggressive: probe every 10s (uses more quota)'))
+  lines.push('')
+
+  lines.push(header('4. The circuit breaker (per-model state)'))
+  lines.push(body('Each model has a tiny disjoncteur that flips between 3 states.'))
+  lines.push(body('The raw jargon is hidden in the UI — here is what the colors mean:'))
+  lines.push(bullet('Healthy (green)  — last probe returned 2xx, route here freely'))
+  lines.push(bullet('Down (red)      — last 3 probes failed, skip until cooldown'))
+  lines.push(bullet('Recovering (yellow) — cooldown expired, retrying with 1 request'))
+  lines.push(bullet('Auth error (orange) — 401/403, your API key is wrong for this model'))
+  lines.push(bullet('Deprecated (gray) — removed from the catalog, will be replaced'))
+  lines.push(body('When a model flips to Auth error, the auto-heal on next start'))
+  lines.push(body('replaces it with a working alternative from the same provider first,'))
+  lines.push(body('then falls through to any provider.'))
+  lines.push('')
+
+  lines.push(header('5. Failover order'))
+  lines.push(body('Models in the active set are tried in priority order. A model'))
+  lines.push(body('in Recovering/Down/Auth error is skipped — the request goes to'))
+  lines.push(body('the next healthy one. If ALL models fail, you get a 503 with the'))
+  lines.push(body('"models_tried" list in the error body — useful for debugging.'))
+  lines.push('')
+
+  lines.push(header('6. Auto-heal (default behavior)'))
+  lines.push(body('On daemon start, the active set is checked. Any model in Auth'))
+  lines.push(body('error or Deprecated is swapped for a working alternative. The'))
+  lines.push(body('first time you add/remove/reorder a model, auto-heal switches off'))
+  lines.push(body('and your manual choices are preserved.'))
+  lines.push('')
+
+  lines.push(header('7. Rate limits (RPD / RPM / TPM)'))
+  lines.push(body('Each provider has its own quota. Common free-tier limits:'))
+  lines.push(bullet('Groq on-demand: 14 400 RPD, 30 RPM per model'))
+  lines.push(bullet('Mistral La Plateforme: 1 RPS, 1B TPM (experiment plan)'))
+  lines.push(bullet('NVIDIA NIM: ~40 RPM (no credit card)'))
+  lines.push(bullet('OpenRouter free routes: 50 RPD'))
+  lines.push(body('When a provider returns 429, the router fails over. When the'))
+  lines.push(body('daily quota is fully exhausted, the model goes Auth error and'))
+  lines.push(body('auto-heal swaps it out next start.'))
+  lines.push('')
+
+  return lines
+}
+
 function paint(chalk, formatter, text) {
   if (!chalk || !formatter) return text
   return formatter(text)
@@ -103,6 +183,13 @@ export function buildCliHelpLines({ chalk = null, indent = '', title = 'CLI Help
   for (const example of EXAMPLES) {
     lines.push(`${indent}${paint(chalk, chalk?.cyan, example)}`)
   }
+  lines.push('')
+  lines.push('')
+  // 📖 Append the "How the router works" deep-dive so a single `--help`
+  // 📖 or in-app Help overlay covers everything the user needs.
+  for (const line of buildHowTheRouterWorksLines({ chalk, indent })) {
+    lines.push(line)
+  }
 
   return lines
 }

package/src/tui/key-handler.js

@@ -2877,26 +2877,14 @@ export function createKeyHandler(ctx) {
 
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
-    // 📖 Shift+R: Open Router Dashboard AND launch OpenCode with the selected model.
-    // 📖 If the dashboard is already open, just bring it to front.
+    // 📖 Shift+R: Open / close the Router Dashboard.
     if (key.name === 'r' && key.shift && !key.ctrl && !key.meta) {
       if (state.routerDashboardOpen) {
+        state.routerDashboardOpen = false
         state.routerDashboardScrollOffset = 0
         return
       }
       openRouterDashboardOverlay(state)
-      // 📖 If a model is selected in the main table, launch OpenCode with it after opening dashboard
-      const selected = state.visibleSorted?.[state.cursor]
-      if (selected && selected.providerKey && selected.modelId) {
-        const launchModel = {
-          modelId: selected.modelId,
-          label: selected.label,
-          tier: selected.tier,
-          providerKey: selected.providerKey,
-        }
-        // 📖 Launch asynchronously — don't await, dashboard renders while OpenCode starts
-        void startOpenCode(launchModel, state.config)
-      }
       return
     }
 

package/src/tui/render-table.js

@@ -47,7 +47,7 @@ import {
   TABLE_FOOTER_LINES,
   FRAMES
 } from '../core/constants.js'
-import { themeColors, currentPalette, getProviderRgb, getTierRgb, getReadableTextRgb, getTheme } from './theme.js'
+import { themeColors, currentPalette, getProviderRgb, getTierRgb, getReadableTextRgb, getTheme, THEME_BG_RGB } from './theme.js'
 import { TIER_COLOR } from './tier-colors.js'
 import { getAvg, getVerdict, getUptime, getStabilityScore, getVersionStatusInfo } from '../core/utils.js'
 import { usagePlaceholderForProvider } from '../core/ping.js'
@@ -207,7 +207,7 @@ export function renderTable({
   const timeSinceLastPing = Date.now() - lastPingTime
   const timeUntilNextPing = Math.max(0, pingInterval - timeSinceLastPing)
   const secondsUntilNext = timeUntilNextPing / 1000
-  const secondsUntilNextLabel = secondsUntilNext.toFixed(1)
+  const secondsUntilNextLabel = secondsUntilNext.toFixed(2)
 
   const intervalSec = Math.round(pingInterval / 1000)
   const pingModeMeta = {
@@ -415,8 +415,14 @@ export function renderTable({
     benchmarkResults,
   })
 
+  // 📖 Header logo colours — theme-aware bg/green/white
+  const hB = currentPalette().headerLogoBg
+  const hG = currentPalette().headerLogoGreen
+  const hW = currentPalette().headerLogoWhite
+  const hBold = (color, text) => chalk.rgb(...color).bgRgb(...hB).bold(text)
+
   const lines = [
-    `  ${chalk.rgb(118, 185, 0).bgRgb(0, 0, 0).bold(' > ')}${chalk.rgb(118, 185, 0).bgRgb(0, 0, 0).bold('free')}${chalk.rgb(255, 255, 255).bgRgb(0, 0, 0).bold('-coding-models')}${chalk.rgb(118, 185, 0).bgRgb(0, 0, 0).bold('_ ')} ${themeColors.dim(`v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${chalk.reset('')}   ` +
+    `  ${hBold(hG, ' > ')}${hBold(hG, 'free')}${hBold(hW, '-coding-models')}${hBold(hG, '_ ')} ${themeColors.dim(`v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${chalk.reset('')}   ` +
       themeColors.dim('📦 ') + themeColors.accentBold(`${completedPings}/${totalVisible}`) + themeColors.dim('  ') +
       themeColors.success(`✅ ${up}`) + themeColors.dim(' up  ') +
       themeColors.warning(`⏳ ${timeout}`) + themeColors.dim(' timeout  ') +
@@ -459,8 +465,9 @@ export function renderTable({
   // 📖 This gives satisfying visual feedback that the click was registered.
   const flashHeader = (plainText, width) => {
     const padded = plainText.length <= width ? plainText.padEnd(width) : plainText.slice(0, width)
-    const [r, g, b] = currentPalette().accentStrong
-    return chalk.bold.rgb(255, 255, 255).bgRgb(r, g, b)(padded)
+    const bg = currentPalette().accentStrong
+    const fg = getReadableTextRgb(bg)
+    return chalk.bold.rgb(...fg).bgRgb(...bg)(padded)
   }
 
   // 📖 Sort-active header: renders the column header with a subtle background color
@@ -474,7 +481,8 @@ export function renderTable({
     const padded = text.padEnd(width).slice(0, width)
     // 📖 Subtle dark accent background — visible but not overwhelming.
     const bg = currentPalette().cursor.defaultBg
-    return chalk.bold.rgb(255, 255, 255).bgRgb(...bg)(padded)
+    const fg = getReadableTextRgb(bg)
+    return chalk.bold.rgb(...fg).bgRgb(...bg)(padded)
   }
 
   // 📖 Now colorize each column header.
@@ -496,8 +504,8 @@ export function renderTable({
   const moodH_c    = (() => {
     // 📖 Tiny verdict indicator column: keep it emoji-only, no arrow, so it stays 2 cells wide.
     const padded = padEndDisplay(moodLabel, W_MOOD)
-    if (headerFlashColumn === 'verdict') return chalk.bold.rgb(255, 255, 255).bgRgb(...currentPalette().accentStrong)(padded)
-    if (sortColumn === 'verdict') return chalk.bold.rgb(255, 255, 255).bgRgb(...currentPalette().cursor.defaultBg)(padded)
+    if (headerFlashColumn === 'verdict') return chalk.bold.rgb(...getReadableTextRgb(currentPalette().accentStrong)).bgRgb(...currentPalette().accentStrong)(padded)
+    if (sortColumn === 'verdict') return chalk.bold.rgb(...getReadableTextRgb(currentPalette().cursor.defaultBg)).bgRgb(...currentPalette().cursor.defaultBg)(padded)
     return themeColors.hotkey(padded)
   })()
   const rankH_c    = headerStyle('rank', rankLabel, W_RANK)
@@ -681,12 +689,12 @@ export function renderTable({
           : numK <= 64
           ? themeColors.metricWarn(ctxRaw.padEnd(W_CTX))
           : numK <= 128
-          ? chalk.rgb(200, 180, 50).bold(ctxRaw.padEnd(W_CTX))
+          ? chalk.rgb(...currentPalette().ctxGold).bold(ctxRaw.padEnd(W_CTX))
           : numK <= 256
-          ? chalk.rgb(100, 200, 80).bold(ctxRaw.padEnd(W_CTX))
+          ? chalk.rgb(...currentPalette().ctxGreen).bold(ctxRaw.padEnd(W_CTX))
           : numK <= 400
-          ? chalk.rgb(0, 255, 200).bold(ctxRaw.padEnd(W_CTX))
-          : chalk.rgb(0, 255, 255).bold.underline(ctxRaw.padEnd(W_CTX))
+          ? chalk.rgb(...currentPalette().ctxTeal).bold(ctxRaw.padEnd(W_CTX))
+          : chalk.rgb(...currentPalette().ctxCyan).bold.underline(ctxRaw.padEnd(W_CTX))
       } else {
         ctxCell = themeColors.dim(ctxRaw.padEnd(W_CTX))
       }
@@ -965,7 +973,7 @@ export function renderTable({
     } else if (isIncompatible) {
       // 📖 Dark red background for models incompatible with the active tool mode.
       // 📖 This visually warns the user that selecting this model won't work with their current tool.
-      renderedRow = chalk.bgRgb(60, 15, 15).rgb(180, 130, 130)(row)
+      renderedRow = chalk.bgRgb(...currentPalette().rowDimBg).rgb(...currentPalette().rowDimFg)(row)
     } else if (r.isRecommended) {
       // 📖 Medium green background for recommended models (distinguishable from favorites)
       renderedRow = themeColors.bgModelRecommended(row)
@@ -1030,6 +1038,8 @@ export function renderTable({
       { text: 'I Help', key: 'i' },
       { text: '  •  ', key: null },
       { text: 'N Reset', key: 'n' },
+      { text: '  •  ', key: null },
+      { text: 'G Theme', key: 'g' },
     ]
     const footerRow1 = lines.length + 1 // 📖 1-based terminal row (line hasn't been pushed yet)
     let xPos = 1
@@ -1061,7 +1071,9 @@ export function renderTable({
     themeColors.dim(`  •  `) +
     hotkey('I', ' Help') +
     themeColors.dim(`  •  `) +
-    hotkey('N', ' Reset')
+    hotkey('N', ' Reset') +
+    themeColors.dim(`  •  `) +
+    themeColors.hotkey('G') + themeColors.infoBold(' Theme')
   )
 
   // 📖 Line 2: command palette + GitHub
@@ -1082,11 +1094,11 @@ export function renderTable({
   }
 
   // 📖 Line 2: command palette (simple color, no background) + GitHub link.
-  const paletteLabel = chalk.rgb(57, 255, 20).bold('Ctrl+P Cmd Palette')
+  const paletteLabel = chalk.rgb(...currentPalette().cmdPalette).bold('Ctrl+P Cmd Palette')
   const starLink = '⭐ ' + themeColors.link('\x1b]8;;https://github.com/vava-nessa/free-coding-models\x1b\\GitHub\x1b]8;;\x1b\\')
   lines.push(
     '  ' + paletteLabel + themeColors.dim(`  •  `) + starLink + themeColors.dim(`  •  `) +
-    chalk.rgb(255, 168, 209).bold('\x1b]8;;https://x.com/vavanessadev\x1b\\Follow @vavanessadev on X for updates and support\x1b]8;;\x1b\\')
+    chalk.rgb(...currentPalette().twitterLink).bold('\x1b]8;;https://x.com/vavanessadev\x1b\\Follow @vavanessadev on X for updates and support\x1b]8;;\x1b\\')
   )
 
   if (versionStatus.isOutdated) {
@@ -1097,8 +1109,8 @@ export function renderTable({
       ? updateMsg + ' '.repeat(Math.max(0, terminalCols - displayWidth(updateMsg)))
       : updateMsg
     const updateBanner = updateWarningMessage
-      ? chalk.bgRed.white.bold(paddedBanner)
-      : chalk.bgRgb(57, 255, 20).rgb(0, 0, 0).bold(paddedBanner)
+      ? chalk.bgRgb(...currentPalette().updateBannerErrorBg).rgb(...currentPalette().updateBannerErrorFg).bold(paddedBanner)
+      : chalk.bgRgb(...currentPalette().updateBannerBg).rgb(...currentPalette().updateBannerFg).bold(paddedBanner)
     const updateBannerRow = lines.length + 1
     _lastLayout.updateBannerRow = updateBannerRow
     footerHotkeys.push({ key: 'update-click', row: updateBannerRow, xStart: 1, xEnd: Math.max(terminalCols, displayWidth(updateMsg)) })
@@ -1138,10 +1150,10 @@ export function renderTable({
   }
 
   const releaseLabel = lastReleaseDate
-    ? chalk.rgb(255, 182, 193)(`Last release: ${lastReleaseDate}`)
+    ? chalk.rgb(...currentPalette().releaseDate)(`Last release: ${lastReleaseDate}`)
     : ''
-  const speedTestLabel = chalk.bgRgb(0, 60, 0).rgb(57, 255, 20).bold(' NEW ⭐️ Ctrl+A 🤖 AI Speed Test ')
-  const globalBenchmarkLabel = chalk.bgRgb(180, 0, 255).white.bold(' NEW Ctrl+U : Global AI Speed Test (Uses a lot of requests!) ')
+  const speedTestLabel = chalk.bgRgb(...currentPalette().badgeSpeedTestBg).rgb(...currentPalette().badgeSpeedTestFg).bold(' NEW ⭐️ Ctrl+A 🤖 AI Speed Test ')
+  const globalBenchmarkLabel = chalk.bgRgb(...currentPalette().badgeBenchmarkBg).rgb(...currentPalette().badgeBenchmarkFg).bold(' NEW Ctrl+U : Global AI Speed Test (Uses a lot of requests!) ')
 
   // 📖 Line 3: Speed Test (Ctrl+A) + Global Benchmark (Ctrl+U) + Last release
   if (releaseLabel || speedTestLabel || globalBenchmarkLabel) {
@@ -1165,11 +1177,19 @@ export function renderTable({
   }
   _lastLayout.footerHotkeys = footerHotkeys
 
-  // 📖 Append \x1b[K (erase to EOL) to each line so leftover chars from previous
-  // 📖 frames are cleared. \x1b[J clears stale content below without adding a
-  // 📖 newline that could scroll the alternate screen.
-  const EL = '\x1b[K'
-  const cleared = lines.map(l => l + EL)
+  // 📖 Force the theme's background colour on every line so light/dark mode
+  // 📖 is respected even when the terminal's native theme doesn't match.
+  // 📖 
+  // 📖 Each line is prefixed with \x1b[48;2;R;G;Bm so the content always renders
+  // 📖 on the correct background, then \x1b[K fills to end-of-line.
+  // 📖 No \x1b[49m (bg reset) is ever emitted — the theme bg persists across frames.
+  const bgRgb = THEME_BG_RGB[getTheme()] ?? THEME_BG_RGB.dark
+  const BG_SET = `\x1b[48;2;${bgRgb[0]};${bgRgb[1]};${bgRgb[2]}m`
+  // 📖 Each line: set bg → render content → erase to EOL (fills with theme bg)
+  const cleared = lines.map(l => BG_SET + l + '\x1b[K')
   if (cleared.length > 0) cleared[cleared.length - 1] += '\x1b[J'
+  // 📖 Every line is prefixed with the theme bg so content always renders on
+  // 📖 the correct background. \x1b[K fills to end-of-line. The app-level render
+  // 📖 loop applies patchThemeBg() to undo chalk's \x1b[49m resets globally.
   return cleared.join('\n')
 }

package/src/tui/theme.js

@@ -71,6 +71,27 @@ const PALETTES = {
       favoriteBg: [76, 55, 17],
       favoriteFg: [255, 244, 220],
     },
+    // 📖 Extra semantic tokens for elements that need distinct dark/light variants
+    headerLogoBg: [0, 0, 0],
+    headerLogoGreen: [118, 185, 0],
+    headerLogoWhite: [255, 255, 255],
+    cmdPalette: [57, 255, 20],
+    twitterLink: [255, 168, 209],
+    releaseDate: [255, 182, 193],
+    ctxGold: [200, 180, 50],
+    ctxGreen: [100, 200, 80],
+    ctxTeal: [0, 255, 200],
+    ctxCyan: [0, 255, 255],
+    rowDimBg: [60, 15, 15],
+    rowDimFg: [180, 130, 130],
+    badgeSpeedTestBg: [0, 60, 0],
+    badgeSpeedTestFg: [57, 255, 20],
+    badgeBenchmarkBg: [180, 0, 255],
+    badgeBenchmarkFg: [255, 255, 255],
+    updateBannerBg: [57, 255, 20],
+    updateBannerFg: [0, 0, 0],
+    updateBannerErrorBg: [196, 30, 30],
+    updateBannerErrorFg: [255, 255, 255],
   },
   light: {
     text: [28, 36, 51],
@@ -118,6 +139,27 @@ const PALETTES = {
       favoriteBg: [255, 241, 208],
       favoriteFg: [79, 53, 0],
     },
+    // 📖 Light-mode variants — more muted, higher contrast on white bg
+    headerLogoBg: [255, 255, 255],
+    headerLogoGreen: [0, 120, 40],
+    headerLogoWhite: [20, 30, 45],
+    cmdPalette: [0, 130, 35],
+    twitterLink: [185, 45, 110],
+    releaseDate: [185, 45, 85],
+    ctxGold: [140, 120, 0],
+    ctxGreen: [35, 120, 25],
+    ctxTeal: [0, 135, 110],
+    ctxCyan: [0, 125, 125],
+    rowDimBg: [255, 230, 230],
+    rowDimFg: [185, 55, 55],
+    badgeSpeedTestBg: [200, 235, 200],
+    badgeSpeedTestFg: [0, 95, 0],
+    badgeBenchmarkBg: [230, 205, 250],
+    badgeBenchmarkFg: [80, 0, 130],
+    updateBannerBg: [30, 180, 30],
+    updateBannerFg: [0, 0, 0],
+    updateBannerErrorBg: [196, 30, 30],
+    updateBannerErrorFg: [255, 255, 255],
   },
 }
 
@@ -287,6 +329,13 @@ function paintBg(bgRgb, text, fgRgb = null, options = {}) {
   return buildStyle({ bgRgb, fgRgb: fgRgb ?? getReadableTextRgb(bgRgb), ...options })(text)
 }
 
+// 📖 Background fill colours — used to force the terminal background to match
+// 📖 the active theme. Light mode → solid white, dark mode → solid dark.
+export const THEME_BG_RGB = {
+  dark: [7, 13, 24],
+  light: [255, 255, 255],
+}
+
 export const themeColors = {
   text: (text) => paintRgb(currentPalette().text, text),
   textBold: (text) => paintRgb(currentPalette().textStrong, text, { bold: true }),
@@ -330,4 +379,25 @@ export const themeColors = {
   overlayBgChangelog: (text) => paintBg(currentPalette().overlayBg.changelog, text, currentPalette().overlayFg),
   overlayBgPlayground: (text) => paintBg(currentPalette().overlayBg.playground, text, currentPalette().overlayFg),
   overlayBgCommandPalette: (text) => paintBg(currentPalette().overlayBg.commandPalette, text, currentPalette().overlayFg),
+  /**
+   * 📖 Returns the active theme's background RGB array.
+   * 📖 Use this to paint lines with a forced background so the TUI looks correct
+   * 📖 regardless of the terminal's native dark/light mode.
+   */
+  bgFill: () => THEME_BG_RGB[activeTheme] ?? THEME_BG_RGB.dark,
+}
+
+/**
+ * 📖 Patch every \x1b[49m (bg reset) in an ANSI string by immediately
+ * 📖 re-applying the current theme's background colour. Chalk emits
+ * 📖 \x1b[49m after every bgRgb() call, which undoes our forced theme bg.
+ *
+ * 📖 Also handles \x1b[0m (full reset) which includes a bg reset.
+ */
+export function patchThemeBg(raw, bgRgb = null) {
+  const color = bgRgb ?? THEME_BG_RGB[activeTheme] ?? THEME_BG_RGB.dark
+  const BG_SET = `\x1b[48;2;${color[0]};${color[1]};${color[2]}m`
+  return raw
+    .replace(/\x1b\[0m/g, `\x1b[0m${BG_SET}`)
+    .replace(/\x1b\[49m/g, `\x1b[49m${BG_SET}`)
 }

package/web/README.md

@@ -36,7 +36,7 @@ To start the React frontend with Vite HMR (Hot Module Replacement):
 cd web
 pnpm dev
 ```
-By default, the dev server runs on `http://localhost:5173/`. Ensure a background daemon is running on port `19280` so the API requests proxy correctly.
+By default, the dev server runs on `http://localhost:5179/`. Ensure a background daemon is running on port `19280` so the API requests proxy correctly.
 
 ### 2. Production Build
 To compile the production-ready SPA: