free-coding-models 0.5.57 → 0.5.58

package/src/core/router-daemon.js

@@ -54,6 +54,15 @@ import { sendUsageTelemetry } from './telemetry.js'
 import { TIER_ORDER } from './utils.js'
 import { atomicWriteJson, safeJsonParse, sleep, maskApiKey, isRouteableProvider } from './shared-helpers.js'
 import { normalizeRequestBody } from './schema-normalizer.js'
+import {
+  loadCache as loadProbeCache,
+  flushCache as flushProbeCache,
+  recordProbeResults as recordProbeCacheResults,
+  getCacheStats as getProbeCacheStats,
+  getModelsDueForProbe,
+  isCacheFresh as isProbeCacheFresh,
+  pruneStaleEntries as pruneProbeCacheStaleEntries,
+} from './probe-cache.js'
 
 export const ROUTER_DEFAULT_PORT = 19280
 export const ROUTER_MAX_PORT = 19289
@@ -870,6 +879,12 @@ class RouterRuntime {
     this.webGlobalBenchmarkRunning = false
     this.webGlobalBenchmarkTotal = 0
     this.webGlobalBenchmarkCompleted = 0
+    // 📖 Probe-cache (t1): load the persistent probe-cache on boot so the daemon
+    // 📖 can skip fresh healthy models during its health-probe loop and write
+    // 📖 results back to the same file the CLI TUI uses. See src/core/probe-cache.js.
+    this.probeCache = loadProbeCache()
+    this.probeCacheDirty = false
+    this.probeCacheFlushTimer = null
     this.refreshRouteState()
   }
 
@@ -1023,6 +1038,39 @@ class RouterRuntime {
       latency_ms: result.latencyMs ?? null,
       circuit_state: this.circuit.get(key)?.state || 'UNKNOWN',
     })
+
+    // 📖 Probe-cache (t1): mirror the result into the persistent cross-session
+    // 📖 cache so the CLI TUI can skip fresh healthy models and auto-hide broken
+    // 📖 ones. key is `provider/modelId` — split on the first slash.
+    const slashIdx = key.indexOf('/')
+    if (slashIdx > 0) {
+      const providerKey = key.slice(0, slashIdx)
+      const modelId = key.slice(slashIdx + 1)
+      recordProbeCacheResults(providerKey, [{
+        modelId,
+        status: result.ok ? 'ok' : 'broken',
+        latencyMs: result.latencyMs ?? null,
+        lastError: result.ok ? null : (result.code != null ? String(result.code) : 'error'),
+      }])
+      this.probeCacheDirty = true
+      this.scheduleProbeCacheFlush()
+    }
+  }
+
+  /**
+   * 📖 scheduleProbeCacheFlush — debounced write to disk so we don't thrash the
+   * 📖 filesystem when a probe burst records dozens of results at once.
+   */
+  scheduleProbeCacheFlush() {
+    if (this.probeCacheFlushTimer) return
+    this.probeCacheFlushTimer = setTimeout(() => {
+      this.probeCacheFlushTimer = null
+      if (this.probeCacheDirty) {
+        flushProbeCache()
+        this.probeCacheDirty = false
+      }
+    }, 2000)
+    if (typeof this.probeCacheFlushTimer.unref === 'function') this.probeCacheFlushTimer.unref()
   }
 
   markAuthError(key, detail = 'authentication failed') {
@@ -1435,6 +1483,10 @@ class RouterRuntime {
       configPath: CONFIG_PATH,
       tokenStatsPath: ROUTER_TOKENS_PATH,
       logPath: ROUTER_LOG_PATH,
+      // 📖 Probe-cache (t1): live aggregates from the persistent probe-cache.
+      // 📖 Surfaced so the Web Dashboard + CLI can show cache hit rate + how many
+      // 📖 broken models are currently hidden. Refreshed every /stats call.
+      probeCache: getProbeCacheStats(),
     }
   }
 
@@ -1529,7 +1581,14 @@ class RouterRuntime {
     if (!set) return
     const candidates = this.scoreCandidates(set)
       .filter((candidate) => candidate.catalog?.routeable && !candidate.circuit?.stale)
-    await Promise.allSettled(candidates.map((candidate) => this.probeCandidate(candidate, {
+    // 📖 Probe-cache (t1): skip models that are still fresh + ok in the persistent
+    // 📖 cache. Broken models naturally pass through (isProbeCacheFresh returns false
+    // 📖 for them), so recovery detection keeps working unchanged.
+    const filtered = candidates.filter((c) => {
+      if (!c.catalog) return true
+      return !isProbeCacheFresh(c.catalog.providerKey, c.catalog.modelId)
+    })
+    await Promise.allSettled(filtered.map((candidate) => this.probeCandidate(candidate, {
       eco: this.routerConfig().probeMode === 'eco',
     })))
   }
@@ -3101,12 +3160,14 @@ class RouterRuntime {
     if (this.probeTimer) clearInterval(this.probeTimer)
     if (this.configReloadTimer) clearInterval(this.configReloadTimer)
     if (this.tokenFlushTimer) clearInterval(this.tokenFlushTimer)
+    if (this.probeCacheFlushTimer) clearInterval(this.probeCacheFlushTimer)
     for (const timeout of this.probeTimeouts) clearTimeout(timeout)
     const started = Date.now()
     while (this.inFlight > 0 && Date.now() - started < 30000) {
       await sleep(100)
     }
     this.tokenTracker.flush({ force: true })
+    flushProbeCache()  // 📖 t1: persist any pending probe-cache deltas before exit
     try { this.server?.close() } catch {}
     try { unlinkSync(ROUTER_PID_PATH) } catch {}
     try { unlinkSync(ROUTER_PORT_PATH) } catch {}

package/src/core/utils.js

@@ -452,11 +452,16 @@ export function findBestModel(results) {
 //     --daemon-status, --no-telemetry, --json, --help/-h (case-insensitive)
 //     --playground / playground subcommand (open the in-TUI chat playground)
 //   - Value flag: --tier <letter> (the next non-flag arg is the tier value)
+//   - Probe-cache flags (t1):
+//     --reprobe / --no-cache (boolean) — force-rebuild the probe cache this run
+//     --probe-ttl <ms> (value)          — override the 24h default TTL
+//     --show-broken (boolean)           — don't auto-hide broken models (one-shot)
 //
 // Returns:
 //   { apiKey, bestMode, fiableMode, openCodeMode, openCodeDesktopMode, openCodeWebMode, openClawMode,
 //     aiderMode, crushMode, gooseMode, qwenMode, openHandsMode, ampMode,
-//     piMode, jcodeMode, copilotMode, forgecodeMode, zcodeMode, noTelemetry, jsonMode, helpMode, tierFilter }
+//     piMode, jcodeMode, copilotMode, forgecodeMode, zcodeMode, noTelemetry, jsonMode, helpMode, tierFilter,
+//     reprobeMode, probeTtlMs, showBrokenMode }
 //
 // 📖 Note: apiKey may be null here — the main CLI falls back to env vars and saved config.
 export function parseArgs(argv) {
@@ -486,6 +491,12 @@ export function parseArgs(argv) {
     ? pingIntervalIdx + 1
     : -1
 
+  // 📖 --probe-ttl <ms> — override the 24h probe-cache TTL (power users / debugging)
+  const probeTtlIdx = args.findIndex(a => a.toLowerCase() === '--probe-ttl')
+  const probeTtlValueIdx = (probeTtlIdx !== -1 && args[probeTtlIdx + 1] && !args[probeTtlIdx + 1].startsWith('--'))
+    ? probeTtlIdx + 1
+    : -1
+
   // 📖 --sync-set [name] — auto-discover and live-probe models into a named router set
   const syncSetIdx = args.findIndex(a => a.toLowerCase() === '--sync-set')
   const syncSetValueIdx = (syncSetIdx !== -1 && args[syncSetIdx + 1] && !args[syncSetIdx + 1].startsWith('--'))
@@ -499,6 +510,7 @@ export function parseArgs(argv) {
   if (originValueIdx !== -1) skipIndices.add(originValueIdx)
   if (pingIntervalValueIdx !== -1) skipIndices.add(pingIntervalValueIdx)
   if (syncSetValueIdx !== -1) skipIndices.add(syncSetValueIdx)
+  if (probeTtlValueIdx !== -1) skipIndices.add(probeTtlValueIdx)
 
   for (const [i, arg] of args.entries()) {
     if (arg.startsWith('--') || arg === '-h') {
@@ -574,6 +586,13 @@ export function parseArgs(argv) {
   // 📖 --recommend — launch directly into Smart Recommend mode (Q key equivalent)
   const recommendMode = flags.includes('--recommend')
 
+  // 📖 Probe-cache flags (t1): --reprobe / --no-cache force a fresh probe pass;
+  // 📖 --probe-ttl overrides the 24h default; --show-broken un-hides broken models for this run.
+  const reprobeMode = flags.includes('--reprobe') || flags.includes('--no-cache')
+  const showBrokenMode = flags.includes('--show-broken')
+  const probeTtlRaw = probeTtlValueIdx !== -1 ? args[probeTtlValueIdx] : null
+  const probeTtlMs = probeTtlRaw !== null ? parseInt(probeTtlRaw, 10) : null
+
   return {
     apiKey,
     bestMode,
@@ -621,6 +640,10 @@ export function parseArgs(argv) {
     devMode,
     syncSetMode,
     syncSetName,
+    // 📖 Probe-cache flags (t1) — see src/core/probe-cache.js
+    reprobeMode,
+    probeTtlMs: Number.isFinite(probeTtlMs) && probeTtlMs > 0 ? probeTtlMs : null,
+    showBrokenMode,
   }
 }
 

package/src/tui/app.js

@@ -128,6 +128,17 @@ import { startExternalTool } from '../core/tool-launchers.js'
 import { getToolInstallPlan, installToolWithPlan, isToolInstalled } from '../core/tool-bootstrap.js'
 import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../core/endpoint-installer.js'
 import { loadCache, saveCache, clearCache, getCacheAge } from '../core/cache.js'
+import {
+  loadCache as loadProbeCache,
+  flushCache as flushProbeCache,
+  clearCache as clearProbeCache,
+  getModelsDueForProbe,
+  isCacheFresh,
+  recordProbeResults,
+  getCacheStats as getProbeCacheStats,
+  pruneStaleEntries as pruneProbeCacheStaleEntries,
+  DEFAULT_PROBE_TTL_MS,
+} from '../core/probe-cache.js'
 import { checkConfigSecurity } from '../core/security.js'
 import { buildCliHelpText } from './cli-help.js'
 import { detectActiveTheme, THEME_BG_RGB, getTheme, patchThemeBg } from './theme.js'
@@ -424,6 +435,78 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
     }
   }
 
+  // 📖 Probe-cache (t1): persistent per-provider health cache with TTL + auto-hide broken.
+  // 📖 Lives at ~/.free-coding-models/probe-cache.json, shared with daemon + Tauri surfaces.
+  // 📖 Honors CLI flags: --reprobe (force clear), --probe-ttl <ms>, --show-broken (don't hide).
+  if (cliArgs.reprobeMode) {
+    // 📖 --reprobe / --no-cache: nuke the cache so this run pings everything fresh.
+    clearProbeCache()
+  }
+  const probeCacheTtlMs = cliArgs.probeTtlMs ?? DEFAULT_PROBE_TTL_MS
+  state.probeCacheTtlMs = probeCacheTtlMs
+  state.showBrokenMode = !!cliArgs.showBrokenMode
+  const probeCache = loadProbeCache()
+
+  // 📖 Prune entries whose modelId is no longer in the catalog (one-time per boot).
+  for (const providerKey of new Set(state.results.map(r => r.providerKey))) {
+    const liveIds = state.results.filter(r => r.providerKey === providerKey).map(r => r.modelId)
+    pruneProbeCacheStaleEntries(providerKey, liveIds)
+  }
+
+  // 📖 Apply probe-cache to results: auto-hide broken, pre-fill fresh ok stats.
+  let probeCacheHits = 0
+  let probeCacheMisses = 0
+  for (const r of state.results) {
+    const entry = probeCache?.providers?.[r.providerKey]?.models?.[r.modelId]
+    if (!entry) {
+      probeCacheMisses++
+      continue
+    }
+    if (entry.status === 'broken') {
+      probeCacheHits++
+      r.cachedBroken = true
+      r.lastProbedAt = entry.lastProbedAt
+      r.lastError = entry.lastError ?? null
+      // 📖 Auto-hide broken models (unless --show-broken or feature disabled).
+      const autoHideEnabled = config.settings?.autoHideBrokenModels !== false
+      if (!state.showBrokenMode && autoHideEnabled) {
+        r.hidden = true
+        r.status = 'down'
+      }
+      continue
+    }
+    if (entry.status !== 'ok') {
+      probeCacheMisses++
+      continue
+    }
+    if (entry.probeVersion !== 2) {
+      // 📖 Stale version — count as miss, force re-probe this run.
+      probeCacheMisses++
+      continue
+    }
+    if (Date.now() - entry.lastProbedAt < probeCacheTtlMs) {
+      // 📖 Fresh ok entry — pre-fill the row so the TUI has data on frame 1.
+      probeCacheHits++
+      r.fromProbeCache = true
+      r.lastProbedAt = entry.lastProbedAt
+      const cachedLatency = typeof entry.latencyMs === 'number' ? entry.latencyMs : 0
+      r.avg = cachedLatency
+      r.p95 = cachedLatency
+      r.jitter = 0
+      r.stability = 100
+      r.uptime = 100
+      r.verdict = 'Cached'
+      r.status = 'up'
+      r.httpCode = '200'
+      r.pings = [{ ms: cachedLatency, code: '200' }]
+    } else {
+      probeCacheMisses++
+    }
+  }
+  state.probeCacheHits = probeCacheHits
+  state.probeCacheMisses = probeCacheMisses
+  state.probeCacheBrokenHidden = state.results.filter(r => r.cachedBroken && r.hidden).length
+
   // 📖 Define pingModel before JSON mode so `--json` can reuse the same provider-aware
   // 📖 ping path as the interactive TUI without waiting for the PTY/render loop setup.
   pingModel = async (r) => {
@@ -445,6 +528,26 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
 
       r.pings.push({ ms, code })
 
+      // 📖 Probe-cache (t1): record the result so future runs can skip healthy models
+      // 📖 and auto-hide broken ones. Uses the module-level in-memory cache; flushed
+      // 📖 on exit (see exit()) and on graceful shutdown.
+      const probeStatus = code === '200' ? 'ok' : 'broken'
+      recordProbeResults(r.providerKey, [{
+        modelId: r.modelId,
+        status: probeStatus,
+        latencyMs: typeof ms === 'number' ? ms : null,
+        lastError: probeStatus === 'broken' ? String(code) : null,
+      }])
+      // 📖 If a previously-broken model comes back ok, un-hide it automatically so the
+      // 📖 user sees the recovery without a restart. (Skip when --show-broken keeps them visible.)
+      if (probeStatus === 'ok' && r.cachedBroken && !state.showBrokenMode) {
+        r.cachedBroken = false
+        r.hidden = false
+        r.lastError = null
+        // 📖 Re-evaluate the broken-hidden counter for the footer chip.
+        state.probeCacheBrokenHidden = state.results.filter(x => x.cachedBroken && x.hidden).length
+      }
+
       if (code === '200') {
         r.status = 'up'
       } else if (code === '000') {
@@ -541,6 +644,7 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
   // 📖 Ensure we always leave alt screen cleanly (Ctrl+C, crash, normal exit)
   const exit = (code = 0) => {
     saveCache(state.results, state.pingMode)
+    flushProbeCache()
     clearInterval(ticker)
     clearTimeout(state.pingIntervalObj)
     clearInterval(state.versionRecheckTimer)
@@ -845,6 +949,11 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
       probeTotal: state.probeTotal,
       probeCompleted: state.probeCompleted,
       probeHiddenCount: state.probeHiddenCount,
+      // 📖 Probe-cache (t1): footer chip stats
+      probeCacheHits: state.probeCacheHits || 0,
+      probeCacheMisses: state.probeCacheMisses || 0,
+      probeCacheBrokenHidden: state.probeCacheBrokenHidden || 0,
+      showBrokenMode: !!state.showBrokenMode,
     }
     if (state.commandPaletteOpen) {
       if (!state.commandPaletteFrozenTable) {
@@ -970,8 +1079,13 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
 
   // ── Continuous ping loop — ping all models every N seconds forever ──────────
 
-  // 📖 Initial ping of all models
-  const initialPing = Promise.all(state.results.map(r => pingModel(r)))
+  // 📖 Initial ping: skip models that are still fresh in the probe-cache (t1).
+  // 📖 They already have valid data pre-filled and will be re-probed when their TTL expires.
+  // 📖 Broken models are always re-probed so recovery is detected.
+  const initialDueModels = state.results.filter(r => !isCacheFresh(r.providerKey, r.modelId, {
+    ttlMs: state.probeCacheTtlMs,
+  }))
+  const initialPing = Promise.all(initialDueModels.map(r => pingModel(r)))
 
   // 📖 Continuous ping loop with mode-driven cadence.
   const runPingCycle = async () => {
@@ -1008,6 +1122,13 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
         if (!state.config.favorites.includes(favKey)) return
       }
 
+      // 📖 Probe-cache (t1): skip models that are still fresh + ok in the cache.
+      // 📖 Broken models always pass through isCacheFresh() (it returns false for them),
+      // 📖 which gives us automatic recovery detection for free.
+      if (isCacheFresh(r.providerKey, r.modelId, { ttlMs: state.probeCacheTtlMs })) {
+        return
+      }
+
       pingModel(r).catch(() => {
         // Individual ping failures don't crash the loop
       })
@@ -1031,8 +1152,11 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
   await initialPing
   scheduleAiSpeedScanOnStartup()
 
-  // 📖 Save cache after initial pings complete for faster next startup
+  // 📖 Save caches after initial pings complete for faster next startup.
+  // 📖 Both caches live side-by-side: the old per-session cache for instant frame-1
+  // 📖 data, and the new persistent probe-cache for cross-session skip + auto-hide.
   saveCache(state.results, state.pingMode)
+  flushProbeCache()
 
   // 📖 Background version re-check: poll npm registry every 5 minutes.
   // 📖 If a new version appears (wasn't there at startup), update the banner live.

package/src/tui/cli-help.js

@@ -33,6 +33,9 @@ const ANALYSIS_FLAGS = [
   { flag: '--ping-interval <ms>', description: 'Override ping interval in milliseconds' },
   { flag: '--hide-unconfigured', description: 'Hide models without configured API keys' },
   { flag: '--show-unconfigured', description: 'Show all models regardless of API key config' },
+  { flag: '--reprobe, --no-cache', description: 'Force-rebuild the persistent probe-cache this run (skip cached healthy models)' },
+  { flag: '--probe-ttl <ms>', description: 'Override probe-cache TTL (default 24h); healthy models within TTL are not re-pinged' },
+  { flag: '--show-broken', description: "Don't auto-hide models that the probe-cache marked broken (one-shot override)" },
 ]
 
 const CONFIG_FLAGS = [

package/src/tui/key-handler.js

@@ -2784,6 +2784,25 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Shift+B: Toggle visibility of probe-cache-broken models (t1).
+    // 📖 When toggled on, hidden broken rows become visible (greyed/dimmed via render-table).
+    // 📖 When toggled off, they go back to hidden. Persisted for the current session.
+    if (key.name === 'b' && key.shift && !key.ctrl && !key.meta) {
+      const nextShowBroken = !state.showBrokenMode
+      state.showBrokenMode = nextShowBroken
+      // 📖 If enabling, restore all broken rows to visible; if disabling, re-hide them.
+      for (const r of state.results) {
+        if (r.cachedBroken) {
+          r.hidden = !nextShowBroken
+        }
+      }
+      // 📖 Refresh the footer counter chip + cursor bounds.
+      state.probeCacheBrokenHidden = state.results.filter(x => x.cachedBroken && x.hidden).length
+      applyTierFilter()
+      refreshVisibleSorted({ resetCursor: false })
+      return
+    }
+
     // 📖 X clears the active free-text filter set from the command palette.
     if (key.name === 'x' && !key.ctrl && !key.meta) {
       if (!state.customTextFilter) return

package/src/tui/render-table.js

@@ -151,6 +151,10 @@ export const PROVIDER_COLOR = new Proxy({}, {
  *   routerFooterTodayTokens?: number,
  *   routerFooterAllTimeTokens?: number,
  *   routerFooterRequests?: number,
+ *   probeCacheHits?: number,         // t1: number of fresh ok entries served from probe-cache
+ *   probeCacheMisses?: number,       // t1: number of models that needed a live probe
+ *   probeCacheBrokenHidden?: number, // t1: number of broken models auto-hidden this session
+ *   showBrokenMode?: boolean,        // t1: true when Shift+B has un-hidden broken models
  * }} opts
  * @returns {string}
  */
@@ -197,6 +201,10 @@ export function renderTable({
   probeTotal = 0,
   probeCompleted = 0,
   probeHiddenCount = 0,
+  probeCacheHits = 0,
+  probeCacheMisses = 0,
+  probeCacheBrokenHidden = 0,
+  showBrokenMode = false,
 } = _) {
   // 📖 Filter out hidden models for display
   const visibleResults = results.filter(r => !r.hidden)
@@ -1199,8 +1207,20 @@ export function renderTable({
     probeLabel = chalk.bgRgb(120, 60, 60).rgb(255, 200, 200).bold(` 🔍 Probe done: ${probeHiddenCount} broken model${probeHiddenCount > 1 ? 's' : ''} hidden `)
   }
 
-  // 📖 Line 3: Speed Test + Global Benchmark + Probe + Last release
-  if (releaseLabel || speedTestLabel || globalBenchmarkLabel || probeLabel) {
+  // 📖 Probe-cache chip (t1): `⚡ N cached · 🔴 M broken (Shift+B)`
+  // 📖 Always shown once any probe-cache state exists — gives the user a hint that
+  // 📖 cache hits are happening (and that broken models are being hidden for them).
+  let probeCacheLabel = ''
+  if (probeCacheHits > 0 || probeCacheBrokenHidden > 0 || showBrokenMode) {
+    const cachedTxt = `⚡ ${probeCacheHits} cached`
+    const brokenTxt = probeCacheBrokenHidden > 0
+      ? ` 🔴 ${probeCacheBrokenHidden} broken${showBrokenMode ? ' (visible)' : ' (Shift+B)'}`
+      : ''
+    probeCacheLabel = chalk.bgRgb(40, 90, 140).rgb(220, 235, 255).bold(` ${cachedTxt}${brokenTxt} `)
+  }
+
+  // 📖 Line 3: Speed Test + Global Benchmark + Probe + Probe-cache + Last release
+  if (releaseLabel || speedTestLabel || globalBenchmarkLabel || probeLabel || probeCacheLabel) {
     const parts = [
       { text: '  ', key: null },
       { text: speedTestLabel, key: 'a' },
@@ -1208,6 +1228,8 @@ export function renderTable({
       { text: globalBenchmarkLabel, key: 'u' },
       { text: probeLabel ? '  ' : '', key: null },
       { text: probeLabel, key: null },
+      { text: probeCacheLabel ? '  ' : '', key: null },
+      { text: probeCacheLabel, key: null },
       { text: '  ', key: null },
       { text: releaseLabel, key: null },
     ]

package/src/tui/tui-state.js

@@ -286,6 +286,17 @@ export function createTuiState({
     probeCompleted: 0,
     probeHiddenCount: 0,
 
+    // 📖 Persistent probe-cache (t1): TTL'd cross-session health cache.
+    // 📖 - probeCacheHits / Misses: telemetry counters per session (footer chip).
+    // 📖 - probeCacheBrokenHidden: live count of broken rows currently hidden.
+    // 📖 - probeCacheTtlMs: TTL override from --probe-ttl CLI flag (default 24h).
+    // 📖 - showBrokenMode: Shift+B toggle; true = broken rows are visible (dimmed).
+    probeCacheHits: 0,
+    probeCacheMisses: 0,
+    probeCacheBrokenHidden: 0,
+    probeCacheTtlMs: null,        // 📖 Set in app.js from cliArgs.probeTtlMs || DEFAULT
+    showBrokenMode: false,
+
     // 📖 Header click flash animation: briefly highlights the clicked column header
     // 📖 with an inverse/bright style for ~250ms (3 frames at 12 FPS).
     headerFlashColumn: null,       // 📖 Column name being flashed (null = no flash active)