free-coding-models 0.5.14 → 0.5.15

package/changelog/v0.5.12.md

@@ -53,10 +53,68 @@
   is exact-string equality). Moved them above the switch so they
   actually run. This is why the original reorder/add/remove proxies
   returned 404 in the v0.5.11 web build.
+- **Auto-heal the active router set on startup.** When the daemon starts,
+  it waits for the first probe burst to populate health data, then runs
+  `autoHealActiveSet()` to swap any broken model in the active set
+  (`AUTH_ERROR` or `STALE` state) for a working alternative. The picker
+  prefers the same provider first, then falls through to cross-provider
+  candidates, and skips providers whose every probe has been broken.
+  Three passes run at 8s, 24s, and 40s after startup so a freshly-added
+  replacement that turns out to be broken gets replaced again. The result:
+  a new user with a half-broken key set lands on a usable default set
+  by the time the Web Dashboard renders, and the Playground's `fcm`
+  virtual model starts returning successful responses immediately.
+- **`router.userCustomized` + `router.autoHeal` config flags.** The first
+  manual edit to the active set (add / remove / reorder / sync /
+  activate / rename) flips `userCustomized` to `true` and `autoHeal`
+  to `false` so the user's manual choices are never undone on the next
+  daemon start. New users get `userCustomized: false` and `autoHeal:
+  true` by default, which is what powers the M6 "default to working
+  models" promise.
+- **`/api/router/status` exposes `autoHeal`, `userCustomized`, and
+  `brokenModelCount`.** The Web Router Dashboard reads these to surface
+  an amber banner when broken models remain in the active set, with a
+  one-click "Fix now" button that re-runs the same `sync-set` probe
+  pipeline the CLI uses.
+- **Amber "models not responding" banner in the Web Router Dashboard.**
+  Shown when the daemon reports `brokenModelCount > 0`, with a
+  dismissable X so the user can ignore it after acknowledging the
+  problem. The "Fix now" button re-runs the probe-based heal and reloads
+  the dashboard state.
+- **Unusable row fade (TUI + Web + Desktop).** Rows whose health is
+  `NO KEY` (`noauth`) or `AUTH FAIL` (`auth_error`) are now rendered at
+  80% opacity (20% less opaque) on every user-facing surface. The user
+  can scan the table and instantly see which models they cannot
+  actually use, even when the cursor is parked on a different model.
+  - **TUI:** the new `fadedRow()` helper in `src/tui/render-helpers.js`
+    multiplies every 24-bit RGB channel inside an ANSI-colored string by
+    `0.8`, so the whole line reads as uniformly faded. This works on
+    every terminal that supports truecolor and does not rely on the
+    SGR 2 "faint" code, which is ignored by some terminals. The fade
+    composes cleanly with the cursor highlight, the dark-red
+    `incompatible` background, the green `recommended` background, and
+    the gold `favorite` background, so no existing visual cue is lost
+    — the "unusable" signal just rides on top of them.
+  - **Web / Desktop (Tauri):** the `ModelTable` adds an
+    `.unusable { opacity: 0.8 }` CSS class to rows whose `m.status` is
+    `noauth` or `auth_error`. The class is held steady on hover so the
+    "you cannot use this" signal never disappears while the user is
+    inspecting the row.
+- **`fadedRow(input, factor = 0.8)` helper.** Pure function exported
+  from `src/tui/render-helpers.js`, documented and unit-tested in
+  isolation. Identity fast-path for `factor >= 1`, channels clamped to
+  0–255, bold/dim/reset SGR codes pass through unchanged. Reusable for
+  any future "fade a whole line" need (e.g. stale rows, soft-disabled
+  providers).
 - **6 new unit tests** for the granular set-management endpoints
   (add, duplicate, remove, reorder, reorder-with-missing-key,
-  catalog) and **2 new tests** for `buildDefaultRouterSet`'s probe
-  path (probe-preference + sync fallback). All 495 tests pass.
+  catalog), **2 new tests** for `buildDefaultRouterSet`'s probe path
+  (probe-preference + sync fallback), **4 new unit tests** for the
+  auto-heal path (no-op when user-customized, no-op when auto-heal is
+  disabled, no-op when no broken models, and the
+  user-edit-flags-customization round-trip), and **12 new tests** for
+  the unusable row fade (7 for `fadedRow` + 5 for the renderTable
+  integration). **All 515 tests pass.**
 
 ### Notes
 - The TUI's `--sync-set` flag is unchanged — the Web "Sync best" button
@@ -66,3 +124,29 @@
   automatically picks up the new working-models set, so the
   Playground will start returning successful responses as soon as the
   Web user clicks "Sync best" once.
+- The auto-heal is best-effort: if the user has only one working
+  provider, the healed set will shrink to that one provider's top
+  model. That's still better than the previous behavior of showing
+  three models that all 401.
+- The new broken-model banner is intentionally subtle (amber, not red)
+  because the auto-heal already does its best to recover. It's there
+  for the "user has 0 working keys" edge case so the user can click
+  through to "Fix now" / "Sync best" and either get a working set or
+  see the toast explaining the situation.
+- The cursor row is still faded if the model is unusable — the user's
+  request was "the WHOLE line at 80% opacity" and we honor that
+  literally. The cursor highlight (blue background) gets its colors
+  multiplied by 0.8 too, so it remains visible but reads as "dimmed",
+  consistent with the rest of the line.
+
+### How the auto-heal picker works (M6)
+```
+For each broken model in the active set:
+  1. Same provider — pick a working model of the same provider
+     (skipping models that the circuit breaker already knows are broken).
+  2. Cross-provider — fall through to any working model across all
+     providers, sorted by static tier + swe score.
+  3. If neither yields a working model, leave the broken entry in
+     place and log a warning (the Web UI surfaces this in the
+     "models not responding" banner).
+```

package/changelog/v0.5.13.md

@@ -1,57 +1,23 @@
-# Changelog v0.5.13 - 2026-06-02
+# Changelog v0.5.13 - 2026-06-04
 
 ### Added
-- **Auto-heal the active router set on startup.** When the daemon starts,
-  it waits for the first probe burst to populate health data, then runs
-  `autoHealActiveSet()` to swap any broken model in the active set
-  (`AUTH_ERROR` or `STALE` state) for a working alternative. The picker
-  prefers the same provider first, then falls through to cross-provider
-  candidates, and skips providers whose every probe has been broken.
-  Three passes run at 8s, 24s, and 40s after startup so a freshly-added
-  replacement that turns out to be broken gets replaced again. The result:
-  a new user with a half-broken key set lands on a usable default set
-  by the time the Web Dashboard renders, and the Playground's `fcm`
-  virtual model starts returning successful responses immediately.
-- **`router.userCustomized` + `router.autoHeal` config flags.** The first
-  manual edit to the active set (add / remove / reorder / sync /
-  activate / rename) flips `userCustomized` to `true` and `autoHeal`
-  to `false` so the user's manual choices are never undone on the next
-  daemon start. New users get `userCustomized: false` and `autoHeal:
-  true` by default, which is what powers the M6 "default to working
-  models" promise.
-- **`/api/router/status` exposes `autoHeal`, `userCustomized`, and
-  `brokenModelCount`.** The Web Router Dashboard reads these to surface
-  an amber banner when broken models remain in the active set, with a
-  one-click "Fix now" button that re-runs the same `sync-set` probe
-  pipeline the CLI uses.
-- **Amber "models not responding" banner in the Web Router Dashboard.**
-  Shown when the daemon reports `brokenModelCount > 0`, with a
-  dismissable X so the user can ignore it after acknowledging the
-  problem. The "Fix now" button re-runs the probe-based heal and reloads
-  the dashboard state.
-- **4 new unit tests** for the auto-heal path: no-op when user-customized,
-  no-op when auto-heal is disabled, no-op when no broken models, and
-  the user-edit-flags-customization round-trip. **All 515 tests pass.**
+- **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.
 
-### Notes
-- The auto-heal is best-effort: if the user has only one working
-  provider, the healed set will shrink to that one provider's top
-  model. That's still better than the previous behavior of showing
-  three models that all 401.
-- The new broken-model banner is intentionally subtle (amber, not red)
-  because the auto-heal already does its best to recover. It's there
-  for the "user has 0 working keys" edge case so the user can click
-  through to "Fix now" / "Sync best" and either get a working set or
-  see the toast explaining the situation.
+### 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.
 
-### How the picker works (M6)
-```
-For each broken model in the active set:
-  1. Same provider — pick a working model of the same provider
-     (skipping models that the circuit breaker already knows are broken).
-  2. Cross-provider — fall through to any working model across all
-     providers, sorted by static tier + swe score.
-  3. If neither yields a working model, leave the broken entry in
-     place and log a warning (the Web UI surfaces this in the
-     "models not responding" banner).
-```
+### 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.14",
+  "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')
 }