0.5.1 - ⚡ Realtime Web Dashboard

Author: vava-nessa

README.md

@@ -145,7 +145,15 @@ docker run -p 19280:19280 ghcr.io/vava-nessa/free-coding-models:latest
 docker run -p 19280:19280 -e OPENROUTER_API_KEY=your_key ghcr.io/vava-nessa/free-coding-models:latest
 ```
 
-Access the web dashboard at `http://localhost:19280/` and configure your coding tool to use `http://localhost:19280/v1` with model `fcm`.
+Access the daemon web dashboard at `http://localhost:19280/` and configure your coding tool to use `http://localhost:19280/v1` with model `fcm`.
+
+For the full TUI-style catalog dashboard from an npm install, run:
+
+```bash
+free-coding-models web
+```
+
+This starts the realtime Web Dashboard locally, opens it in your browser, and uses `http://localhost:3333/` by default. Override the port with `FCM_WEB_PORT=3334 free-coding-models web`.
 
 ### Available Image Tags
 

bin/free-coding-models.js

@@ -53,6 +53,16 @@ async function main() {
     process.exit(0);
   }
 
+  // 📖 Standalone web dashboard: same full-catalog ping UI as the TUI, served
+  // 📖 locally with Socket.IO/SSE/REST realtime updates.
+  if (cliArgs.webMode) {
+    const { startWebServer } = await import('../web/server.js');
+    const parsedPort = Number.parseInt(process.env.FCM_WEB_PORT || process.env.FCM_PORT || '3333', 10);
+    const port = Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : 3333;
+    await startWebServer(port, { open: true, startPingLoop: true });
+    return;
+  }
+
   // 📖 Router daemon lifecycle flags run before the TUI so automation and
   // 📖 editor integrations can manage the local OpenAI-compatible endpoint.
   if (cliArgs.daemonMode || cliArgs.daemonBackgroundMode || cliArgs.daemonStopMode || cliArgs.daemonStatusMode) {

changelog/v0.5.1.md

@@ -0,0 +1,24 @@
+# Changelog v0.5.1 - 2026-05-31
+
+### Added
+- Added `free-coding-models web` as the npm-friendly way to launch the full TUI-style realtime Web Dashboard from a global install.
+- Added Socket.IO as the primary dashboard realtime transport, with SSE and REST polling fallbacks so the UI keeps updating even when one transport is unavailable.
+- Added `/api/state` support for dashboard clients and daemon dashboard clients, including ping mode, countdown, per-model ping state, and benchmark progress metadata.
+- Added tests that lock every visible web table column as sortable, including display-only columns such as `❔`, Last Ping, AI Latency, TPS, and Trend.
+
+### Changed
+- Reworked the standalone web server to mirror the TUI ping cadence more closely: startup speed mode, normal cadence, idle slow mode, per-model `isPinging`, and frequent incremental updates.
+- Changed the Web Dashboard AI Latency global benchmark to benchmark only the models currently visible after filters and search, instead of always benchmarking the full catalog.
+- Made every dashboard table column cycle through ascending, descending, and reset sorting, with missing values consistently pushed to the bottom.
+- Removed the top stats card row from the dashboard for a cleaner, table-first layout.
+- Removed the `ms` suffix from Last Ping and Avg cells in the dashboard table to make dense latency columns easier to scan.
+- Improved dashboard table borders and added visible column separators, including stronger light-theme borders.
+- Updated npm and web documentation to distinguish the full catalog dashboard (`free-coding-models web`, default `localhost:3333`) from the router daemon dashboard (`free-coding-models --daemon`, default `localhost:19280`).
+
+### Fixed
+- Fixed `free-coding-models web` being parsed as an API key by treating `web` as a real subcommand.
+- Fixed dashboard benchmark spinners so only the actively benchmarked row shows running state instead of making unrelated rows spin during global scans.
+- Fixed benchmark result keys by using provider/model identifiers, avoiding collisions and invisible results when providers share model ids.
+- Fixed the Tier “All” filter mismatch in the Web Dashboard.
+- Fixed light-theme button contrast where accent buttons could render unreadable black-on-black text.
+- Fixed the web development readiness check so it waits for the correct local server response.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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",

scripts/dev-web.mjs

@@ -61,7 +61,7 @@ startWebServer(${API_PORT}, { open: false, startPingLoop: true }).then(() => {})
   let portReady = false
   for (let i = 0; i < 30; i++) {
     await new Promise(r => setTimeout(r, 300))
-    portReady = !(await isPortUsed(API_PORT))
+    portReady = await isPortUsed(API_PORT)
     if (portReady) break
   }
 

src/core/router-daemon.js

@@ -48,6 +48,7 @@ import {
   saveConfig,
 } from './config.js'
 import { buildChatCompletionPingBody, resolveCloudflareUrl, shouldUseDisabledThinkingForProvider } from './ping.js'
+import { benchmarkModel, BENCHMARK_TIMEOUT_MS } from './benchmark.js'
 import { sendUsageTelemetry } from './telemetry.js'
 
 export const ROUTER_DEFAULT_PORT = 19280
@@ -343,12 +344,32 @@ function getWebModelsPayload(runtime) {
         pingCount: pings.length,
         hasApiKey,
         inRouterSet: inSetIndex.has(`${providerKey}::${modelId}`),
+        benchmarkKey: key,
+        isBenchmarking: runtime.webBenchmarkRunning?.has(key) || false,
+        benchmark: runtime.webBenchmarkResults?.get(key) || null,
       })
     }
   }
   return payload
 }
 
+function getWebStatePayload(runtime) {
+  const router = runtime.routerConfig()
+  const probeInterval = router.probeIntervals?.[router.probeMode] || DEFAULT_ROUTER_SETTINGS.probeIntervals.balanced
+  return {
+    pingMode: router.probeMode === 'aggressive' ? 'speed' : router.probeMode === 'eco' ? 'slow' : 'normal',
+    pingModeSource: 'daemon-probe-mode',
+    pingInterval: probeInterval,
+    nextPingAt: runtime.lastProbeAt ? runtime.lastProbeAt + probeInterval : null,
+    pendingPings: runtime.probeTimeouts?.size || 0,
+    isPinging: (runtime.probeTimeouts?.size || 0) > 0,
+    globalBenchmarkRunning: runtime.webGlobalBenchmarkRunning || false,
+    globalBenchmarkTotal: runtime.webGlobalBenchmarkTotal || 0,
+    globalBenchmarkCompleted: runtime.webGlobalBenchmarkCompleted || 0,
+    models: getWebModelsPayload(runtime),
+  }
+}
+
 function getWebConfigPayload(runtime) {
   const providers = {}
   for (const [key, src] of Object.entries(sources)) {
@@ -786,6 +807,11 @@ class RouterRuntime {
     this.quotaExhausted = new Set()
     this.quotaDetails = new Map()
     this.staleNotifications = new Set()
+    this.webBenchmarkRunning = new Set()
+    this.webBenchmarkResults = new Map()
+    this.webGlobalBenchmarkRunning = false
+    this.webGlobalBenchmarkTotal = 0
+    this.webGlobalBenchmarkCompleted = 0
     this.refreshRouteState()
   }
 
@@ -1131,6 +1157,99 @@ class RouterRuntime {
     }
   }
 
+  broadcastWebState() {
+    this.broadcast('models', getWebStatePayload(this))
+  }
+
+  async runWebBenchmark(providerKey, modelId) {
+    const key = modelKey(providerKey, modelId)
+    if (this.webBenchmarkRunning.has(key)) return { skipped: true }
+    const source = sources[providerKey]
+    if (!source?.url) {
+      return { ok: false, code: 'UNSUPPORTED', totalMs: 0, error: 'Provider has no benchmark URL', retries: 0 }
+    }
+
+    this.webBenchmarkRunning.add(key)
+    this.broadcastWebState()
+    try {
+      const result = await benchmarkModel({
+        apiKey: this.getApiKeyForProvider(providerKey) ?? null,
+        modelId,
+        providerKey,
+        url: source.url,
+        timeoutMs: BENCHMARK_TIMEOUT_MS,
+      })
+      this.webBenchmarkResults.set(key, result)
+      return result
+    } catch (err) {
+      const fallback = { ok: false, code: 'ERR', totalMs: 0, error: err?.message || 'Benchmark failed', retries: 0 }
+      this.webBenchmarkResults.set(key, fallback)
+      return fallback
+    } finally {
+      this.webBenchmarkRunning.delete(key)
+      this.broadcastWebState()
+    }
+  }
+
+  async runWebGlobalBenchmark(models) {
+    if (this.webGlobalBenchmarkRunning) return { started: false, error: 'Global benchmark already running' }
+    const knownModels = []
+    const seen = new Set()
+    for (const item of Array.isArray(models) ? models : []) {
+      const providerKey = typeof item?.providerKey === 'string' ? item.providerKey : ''
+      const modelId = typeof item?.modelId === 'string' ? item.modelId : ''
+      const key = modelKey(providerKey, modelId)
+      if (!this.modelCatalog.has(key) || seen.has(key)) continue
+      seen.add(key)
+      knownModels.push({ providerKey, modelId, key })
+    }
+
+    const fallbackModels = knownModels.length > 0
+      ? knownModels
+      : [...this.modelCatalog.values()].filter((m) => sources[m.providerKey]?.url && !sources[m.providerKey]?.cliOnly)
+
+    this.webGlobalBenchmarkRunning = true
+    this.webGlobalBenchmarkTotal = fallbackModels.length
+    this.webGlobalBenchmarkCompleted = 0
+    this.broadcastWebState()
+
+    const healthPriority = { up: 0, pending: 1, timeout: 2, noauth: 3, auth_error: 4, down: 5 }
+    const sorted = [...fallbackModels].sort((a, b) => {
+      const aw = this.probeWindows.get(modelKey(a.providerKey, a.modelId)) || []
+      const bw = this.probeWindows.get(modelKey(b.providerKey, b.modelId)) || []
+      const aLast = aw.at(-1)
+      const bLast = bw.at(-1)
+      const aState = aLast?.ok ? 'up' : aw.length ? 'down' : 'pending'
+      const bState = bLast?.ok ? 'up' : bw.length ? 'down' : 'pending'
+      const hpA = healthPriority[aState] ?? 6
+      const hpB = healthPriority[bState] ?? 6
+      if (hpA !== hpB) return hpA - hpB
+      return (aLast?.latencyMs ?? 99999) - (bLast?.latencyMs ?? 99999)
+    })
+
+    const workers = new Array(Math.min(5, sorted.length)).fill(null).map(async () => {
+      while (sorted.length > 0) {
+        const next = sorted.shift()
+        if (!next) break
+        try {
+          await this.runWebBenchmark(next.providerKey, next.modelId)
+        } finally {
+          this.webGlobalBenchmarkCompleted += 1
+          this.broadcastWebState()
+        }
+      }
+    })
+
+    void Promise.all(workers).finally(() => {
+      this.webGlobalBenchmarkRunning = false
+      this.webGlobalBenchmarkTotal = 0
+      this.webGlobalBenchmarkCompleted = 0
+      this.broadcastWebState()
+    })
+
+    return { started: true, total: fallbackModels.length }
+  }
+
   statusPayload() {
     const router = this.routerConfig()
     const activeSet = this.getSet(router.activeSet)
@@ -1892,6 +2011,10 @@ class RouterRuntime {
         sendJson(res, 200, getWebModelsPayload(this), { 'x-request-id': requestId })
         return
       }
+      if (req.method === 'GET' && url.pathname === '/api/state') {
+        sendJson(res, 200, getWebStatePayload(this), { 'x-request-id': requestId })
+        return
+      }
       if (req.method === 'GET' && url.pathname === '/api/config') {
         sendJson(res, 200, getWebConfigPayload(this), { 'x-request-id': requestId })
         return
@@ -1907,11 +2030,53 @@ class RouterRuntime {
           'Connection': 'keep-alive',
           'x-request-id': requestId,
         })
-        res.write(`data: ${JSON.stringify(getWebModelsPayload(this))}\n\n`)
+        res.write(`data: ${JSON.stringify(getWebStatePayload(this))}\n\n`)
         this.sseClients.add(res)
         req.on('close', () => this.sseClients.delete(res))
         return
       }
+      if (req.method === 'POST' && url.pathname === '/api/activity') {
+        sendJson(res, 200, { ok: true }, { 'x-request-id': requestId })
+        return
+      }
+      if (req.method === 'POST' && url.pathname === '/api/benchmark') {
+        const body = await readJsonBody(req)
+        const providerKey = typeof body.providerKey === 'string' ? body.providerKey : ''
+        const modelId = typeof body.modelId === 'string' ? body.modelId : ''
+        if (!this.modelCatalog.has(modelKey(providerKey, modelId))) {
+          sendJson(res, 404, { error: 'Model not found' }, { 'x-request-id': requestId })
+          return
+        }
+        if (this.webBenchmarkRunning.has(modelKey(providerKey, modelId))) {
+          sendJson(res, 409, { error: 'Benchmark already in progress for this model' }, { 'x-request-id': requestId })
+          return
+        }
+        const result = await this.runWebBenchmark(providerKey, modelId)
+        sendJson(res, 200, result, { 'x-request-id': requestId })
+        return
+      }
+      if (url.pathname === '/api/global-benchmark') {
+        if (req.method === 'GET') {
+          sendJson(res, 200, {
+            running: this.webGlobalBenchmarkRunning,
+            total: this.webGlobalBenchmarkTotal,
+            completed: this.webGlobalBenchmarkCompleted,
+          }, { 'x-request-id': requestId })
+          return
+        }
+        if (req.method !== 'POST') {
+          sendError(res, 405, 'Method not allowed', 'invalid_request_error', 'method_not_allowed', requestId)
+          return
+        }
+        if (this.webGlobalBenchmarkRunning) {
+          sendJson(res, 409, { error: 'Global benchmark already running' }, { 'x-request-id': requestId })
+          return
+        }
+        const body = await readJsonBody(req)
+        const result = await this.runWebGlobalBenchmark(body.models)
+        sendJson(res, result.started ? 202 : 409, result, { 'x-request-id': requestId })
+        return
+      }
       if (req.method === 'GET' && url.pathname.startsWith('/api/key/')) {
         // 📖 Reveals raw API keys — same-origin only to prevent malicious sites
         // 📖 from exfiltrating provider credentials via XHR/fetch.

src/core/utils.js

@@ -471,6 +471,8 @@ export function parseArgs(argv) {
       flags.push(arg.toLowerCase())
     } else if (skipIndices.has(i)) {
       // 📖 Skip — this is a value for --tier, not an API key
+    } else if (i === 0 && arg.toLowerCase() === 'web') {
+      // 📖 `free-coding-models web` is a subcommand, not a provider API key.
     } else if (!apiKey) {
       apiKey = arg
     }

src/tui/cli-help.js

@@ -36,6 +36,7 @@ const ANALYSIS_FLAGS = [
 ]
 
 const CONFIG_FLAGS = [
+  { flag: 'web | --web | --gui', description: 'Start the full-catalog realtime Web Dashboard' },
   { flag: '--daemon', description: 'Start the FCM Router daemon + web dashboard (same port)' },
   { flag: '--daemon-bg', description: 'Start the FCM Router daemon in the background' },
   { flag: '--daemon-status', description: 'Print FCM Router daemon status JSON' },
@@ -47,6 +48,7 @@ const CONFIG_FLAGS = [
 
 const EXAMPLES = [
   'free-coding-models --help',
+  'free-coding-models web',
   'free-coding-models --daemon',
   'free-coding-models --daemon-bg',
   'free-coding-models --daemon-status',

test/test.js

@@ -1786,6 +1786,14 @@ describe('parseArgs', () => {
     assert.equal(parseArgs(argv()).daemonMode, false)
   })
 
+  it('detects web dashboard mode without treating subcommand as API key', () => {
+    const subcommand = parseArgs(argv('web'))
+    assert.equal(subcommand.webMode, true)
+    assert.equal(subcommand.apiKey, null)
+    assert.equal(parseArgs(argv('--web')).webMode, true)
+    assert.equal(parseArgs(argv('--gui')).webMode, true)
+  })
+
   it('detects --help and -h flags', () => {
     assert.equal(parseArgs(argv('--help')).helpMode, true)
     assert.equal(parseArgs(argv('-h')).helpMode, true)
@@ -1842,6 +1850,7 @@ describe('cli help text', () => {
       '--json',
       '--tier <S|A|B|C>',
       '--recommend',
+      'web | --web | --gui',
       '--daemon',
       '--daemon-bg',
       '--daemon-status',
@@ -4462,6 +4471,39 @@ describe('getManualInstallCmd', () => {
   })
 })
 
+describe('web dashboard table sorting', () => {
+  const sortableWebColumns = [
+    'mood', 'idx', 'tier', 'sweScore', 'ctx', 'label', 'origin', 'latestPing',
+    'avg', 'condition', 'verdict', 'stability', 'uptime', 'aiLatency', 'tps', 'trend',
+  ]
+
+  it('keeps every visible web table column explicitly sortable', () => {
+    const tableSource = readFileSync(join(ROOT, 'web/src/components/dashboard/ModelTable.jsx'), 'utf8')
+
+    assert.match(tableSource, /const SORTABLE_COLUMN_IDS = new Set/, 'header clickability must not depend on TanStack display-column accessors')
+    assert.match(tableSource, /SORTABLE_COLUMN_IDS\.has\(col\.id\)/, 'headers must use the explicit sortable allowlist')
+
+    for (const columnId of sortableWebColumns) {
+      assert.ok(tableSource.includes(`'${columnId}'`), `${columnId} must be present in the sortable allowlist`)
+      const idPattern = columnId === 'condition'
+        ? /id:\s*'condition',[\s\S]*?enableSorting:\s*true/
+        : new RegExp(`(?:id:\\s*'${columnId}'|accessor\\('${columnId}'|accessor\\("${columnId}")[\\s\\S]*?enableSorting:\\s*true`)
+      assert.match(tableSource, idPattern, `${columnId} column must opt into sorting`)
+    }
+  })
+
+  it('has comparator support for every sortable web table column', () => {
+    const filterSource = readFileSync(join(ROOT, 'web/src/hooks/useFilter.js'), 'utf8')
+
+    for (const columnId of sortableWebColumns) {
+      assert.ok(
+        filterSource.includes(`sortColumn === '${columnId}'`) || columnId === 'avg',
+        `${columnId} must be handled by useFilter sorting`
+      )
+    }
+  })
+})
+
 // 📖 Web server tests use real loopback ports so we can verify the startup
 // 📖 fallback behavior without depending on shell scripts or a browser.
 async function getFreePort() {