free-coding-models 0.5.0 → 0.5.4

package/web/src/hooks/useFilter.js

@@ -1,36 +1,152 @@
 /**
  * @file web/src/hooks/useFilter.js
- * @description React hook for model filtering and sorting state.
- * 📖 Manages tier/status/provider/text filters + sort column/direction.
- * → useFilter
+ * @description React hook for model filtering and tri-state sorting state.
+ *
+ * 📖 M1 parity additions (vs the previous version):
+ * 📖   - verdict filter cycle   (`V` in TUI)
+ * 📖   - health filter cycle    (`H` in TUI)
+ * 📖   - visibility mode cycle  (`E` in TUI: Normal / Configured-only / Usable-only)
+ * 📖   - custom text filter     (Ctrl+P → "Apply text filter" in TUI)
+ * 📖   - resetView()            (`N` in TUI) — clears every filter back to defaults
+ *
+ * 📖 All TUI filter values (tier / status / provider / verdict / health)
+ * 📖 are read in a single sorted pass so the visible list always matches the
+ * 📖 header chip bar one-to-one.
+ *
+ * @functions
+ *   → useFilter(models) — filter + sort state for the dashboard table
+ * @exports useFilter
  */
 import { useState, useMemo, useCallback } from 'react'
 import { tierRank, verdictRank, parseSwe } from '../utils/ranks.js'
 import { formatCtx } from '../utils/format.js'
 
+// 📖 TUI constants mirrored in JS so the Web chips use the same labels/cycle as the TUI.
+export const TIER_CYCLE = ['all', 'S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
+export const STATUS_CYCLE = ['all', 'up', 'down', 'pending']
+// 📖 Verdict filter: full set of verdict states the TUI cycles through.
+// 📖 `all` = no verdict filter (the TUI's null position in VERDICT_CYCLE).
+export const VERDICT_CYCLE = ['all', 'Perfect', 'Normal', 'Spiky', 'Slow', 'Overloaded', 'Down', 'Unstable', 'Pending']
+// 📖 Health filter: matches the TUI's HEALTH_CYCLE exactly.
+export const HEALTH_CYCLE = ['all', 'up', 'timeout', 'down', 'pending', 'noauth', 'auth_error']
+// 📖 Visibility mode: TUI's E key cycle — Normal / Configured-only / Usable-only.
+export const VISIBILITY_CYCLE = ['normal', 'configured', 'usable']
+
+function rankOrder(model) {
+  return model.idx ?? 9999
+}
+
+function pingHistory(model) {
+  return model.pingHistory || model.pings || []
+}
+
+function latestPingMs(model) {
+  const hist = pingHistory(model)
+  const latest = hist.length > 0 ? hist[hist.length - 1] : null
+  return latest?.ms ?? null
+}
+
+function trendDelta(model) {
+  const points = pingHistory(model)
+    .map((point) => point?.ms)
+    .filter((ms) => typeof ms === 'number' && Number.isFinite(ms))
+  if (points.length < 2) return null
+  return points[points.length - 1] - points[0]
+}
+
+function numericOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function compareNullableNumber(aValue, bValue, direction) {
+  const aMissing = aValue == null
+  const bMissing = bValue == null
+  if (aMissing && bMissing) return 0
+  if (aMissing) return 1
+  if (bMissing) return -1
+  return (aValue - bValue) * direction
+}
+
+function compareNullableString(aValue, bValue, direction) {
+  const aText = typeof aValue === 'string' ? aValue : ''
+  const bText = typeof bValue === 'string' ? bValue : ''
+  const aMissing = aText.length === 0
+  const bMissing = bText.length === 0
+  if (aMissing && bMissing) return 0
+  if (aMissing) return 1
+  if (bMissing) return -1
+  return aText.localeCompare(bText) * direction
+}
+
+// 📖 Health order: same precedence as the TUI's HEALTH_CYCLE.
+// 📖 "up" is best, noauth/auth_error are worst.
+const HEALTH_ORDER = {
+  up: 0, pending: 1, timeout: 2, down: 3, noauth: 4, auth_error: 5,
+}
+
 export function useFilter(models) {
+  // 📖 Initial values match the TUI defaults (everything off, "all" everywhere).
   const [filterTier, setFilterTier] = useState('all')
   const [filterStatus, setFilterStatus] = useState('all')
   const [filterProvider, setFilterProvider] = useState('all')
+  const [filterVerdict, setFilterVerdict] = useState('all')
+  const [filterHealth, setFilterHealth] = useState('all')
+  const [visibilityMode, setVisibilityMode] = useState('normal')
   const [searchQuery, setSearchQuery] = useState('')
+  const [customTextFilter, setCustomTextFilter] = useState(null)
   const [sortColumn, setSortColumn] = useState('avg')
   const [sortDirection, setSortDirection] = useState('asc')
 
+  // 📖 Cycle helpers: clicking the same chip advances to the next value in its
+  // 📖 cycle, matching the TUI's single-key cycling (T / D / V / H / E).
+  const cycleFilter = useCallback((current, cycle, setter) => {
+    const idx = cycle.indexOf(current)
+    setter(cycle[(idx + 1) % cycle.length])
+  }, [])
+
+  const cycleTier = useCallback(() => cycleFilter(filterTier, TIER_CYCLE, setFilterTier), [filterTier, cycleFilter])
+  const cycleStatus = useCallback(() => cycleFilter(filterStatus, STATUS_CYCLE, setFilterStatus), [filterStatus, cycleFilter])
+  const cycleVerdict = useCallback(() => cycleFilter(filterVerdict, VERDICT_CYCLE, setFilterVerdict), [filterVerdict, cycleFilter])
+  const cycleHealth = useCallback(() => cycleFilter(filterHealth, HEALTH_CYCLE, setFilterHealth), [filterHealth, cycleFilter])
+  const cycleVisibility = useCallback(() => cycleFilter(visibilityMode, VISIBILITY_CYCLE, setVisibilityMode), [visibilityMode, cycleFilter])
+
   const toggleSort = useCallback((col) => {
-    setSortColumn((prevCol) => {
-      if (prevCol === col) {
-        setSortDirection((prevDir) => (prevDir === 'asc' ? 'desc' : 'asc'))
-      } else {
-        setSortDirection('asc')
-      }
-      return col
-    })
+    if (sortColumn !== col) {
+      setSortColumn(col)
+      setSortDirection('asc')
+      return
+    }
+    if (sortDirection === 'asc') {
+      setSortDirection('desc')
+      return
+    }
+    // 📖 Third click resets the column: no active sort, catalog/rank order.
+    setSortColumn(null)
+    setSortDirection('asc')
+  }, [sortColumn, sortDirection])
+
+  // 📖 Reset view — TUI's `N` key. Wipes every filter + sort back to default
+  // 📖 and clears the search box. The custom text filter is part of the view
+  // 📖 state and gets cleared too.
+  const resetView = useCallback(() => {
+    setFilterTier('all')
+    setFilterStatus('all')
+    setFilterProvider('all')
+    setFilterVerdict('all')
+    setFilterHealth('all')
+    setVisibilityMode('normal')
+    setSearchQuery('')
+    setCustomTextFilter(null)
+    setSortColumn('avg')
+    setSortDirection('asc')
   }, [])
 
   const filtered = useMemo(() => {
     let result = [...models]
 
+    // ── Tier ──
     if (filterTier !== 'all') result = result.filter((m) => m.tier === filterTier)
+    // ── Status (coarser cycle that maps onto the TUI's "health" semantics) ──
     if (filterStatus !== 'all') {
       result = result.filter((m) => {
         if (filterStatus === 'up') return m.status === 'up'
@@ -39,45 +155,154 @@ export function useFilter(models) {
         return true
       })
     }
+    // ── Provider ──
     if (filterProvider !== 'all') result = result.filter((m) => m.providerKey === filterProvider)
-    if (searchQuery) {
-      const q = searchQuery.toLowerCase()
-      result = result.filter(
-        (m) =>
-          m.label.toLowerCase().includes(q) ||
-          m.modelId.toLowerCase().includes(q) ||
-          m.origin.toLowerCase().includes(q) ||
-          m.tier.toLowerCase().includes(q) ||
-          (m.verdict || '').toLowerCase().includes(q)
-      )
+    // ── Verdict (TUI's `V` cycle) ──
+    if (filterVerdict !== 'all') result = result.filter((m) => m.verdict === filterVerdict)
+    // ── Health (TUI's `H` cycle — full granularity) ──
+    if (filterHealth !== 'all') result = result.filter((m) => m.status === filterHealth)
+    // ── Visibility mode (TUI's `E` cycle) ──
+    if (visibilityMode === 'configured') {
+      // 📖 Hide models with no API key OR auth/noauth errors. Keep timeout/429.
+      result = result.filter((m) => m.hasApiKey && m.status !== 'noauth' && m.status !== 'auth_error')
+    } else if (visibilityMode === 'usable') {
+      // 📖 Only Health UP with verdict in the good set (Perfect / Normal / Slow).
+      result = result.filter((m) => {
+        if (m.status !== 'up') return false
+        return ['Perfect', 'Normal', 'Slow'].includes(m.verdict)
+      })
+    }
+    // ── Search + custom text filter (TUI's Ctrl+P "Apply text filter") ──
+    const searchLower = searchQuery.trim().toLowerCase()
+    const customLower = (customTextFilter || '').trim().toLowerCase()
+    if (searchLower) {
+      result = result.filter((m) => (
+        m.label.toLowerCase().includes(searchLower) ||
+        m.modelId.toLowerCase().includes(searchLower) ||
+        m.origin.toLowerCase().includes(searchLower) ||
+        m.tier.toLowerCase().includes(searchLower) ||
+        (m.verdict || '').toLowerCase().includes(searchLower)
+      ))
+    }
+    if (customLower) {
+      result = result.filter((m) => (
+        m.label.toLowerCase().includes(customLower) ||
+        m.modelId.toLowerCase().includes(customLower) ||
+        m.origin.toLowerCase().includes(customLower) ||
+        (m.ctx || '').toLowerCase().includes(customLower) ||
+        (m.providerKey || '').toLowerCase().includes(customLower)
+      ))
     }
 
     result.sort((a, b) => {
+      if (!sortColumn) return rankOrder(a) - rankOrder(b)
+
+      const direction = sortDirection === 'desc' ? -1 : 1
       let cmp = 0
-      const col = sortColumn
-      if (col === 'idx') cmp = a.idx - b.idx
-      else if (col === 'tier') cmp = tierRank(a.tier) - tierRank(b.tier)
-      else if (col === 'label') cmp = a.label.localeCompare(b.label)
-      else if (col === 'origin') cmp = a.origin.localeCompare(b.origin)
-      else if (col === 'sweScore') cmp = parseSwe(a.sweScore) - parseSwe(b.sweScore)
-      else if (col === 'ctx') cmp = formatCtx(a.ctx) - formatCtx(b.ctx)
-      else if (col === 'latestPing') cmp = (a.latestPing ?? Infinity) - (b.latestPing ?? Infinity)
-      else if (col === 'avg') cmp = (a.avg === Infinity ? 99999 : a.avg) - (b.avg === Infinity ? 99999 : b.avg)
-      else if (col === 'stability') cmp = (a.stability ?? -1) - (b.stability ?? -1)
-      else if (col === 'verdict') cmp = verdictRank(a.verdict) - verdictRank(b.verdict)
-      else if (col === 'uptime') cmp = (a.uptime ?? 0) - (b.uptime ?? 0)
-      return sortDirection === 'asc' ? cmp : -cmp
+
+      if (sortColumn === 'mood') {
+        cmp = compareNullableNumber(verdictRank(a.verdict), verdictRank(b.verdict), direction)
+      } else if (sortColumn === 'idx') {
+        cmp = compareNullableNumber(rankOrder(a), rankOrder(b), direction)
+      } else if (sortColumn === 'tier') {
+        cmp = compareNullableNumber(tierRank(a.tier), tierRank(b.tier), direction)
+      } else if (sortColumn === 'label') {
+        cmp = compareNullableString(a.label, b.label, direction)
+      } else if (sortColumn === 'origin') {
+        cmp = compareNullableString(a.origin, b.origin, direction)
+      } else if (sortColumn === 'sweScore') {
+        cmp = compareNullableNumber(parseSwe(a.sweScore), parseSwe(b.sweScore), direction)
+      } else if (sortColumn === 'ctx') {
+        cmp = compareNullableNumber(formatCtx(a.ctx), formatCtx(b.ctx), direction)
+      } else if (sortColumn === 'latestPing') {
+        cmp = compareNullableNumber(latestPingMs(a), latestPingMs(b), direction)
+      } else if (sortColumn === 'avg') {
+        const aAvg = a.avg == null || a.avg === Infinity || a.avg > 99000 ? null : a.avg
+        const bAvg = b.avg == null || b.avg === Infinity || b.avg > 99000 ? null : b.avg
+        cmp = compareNullableNumber(aAvg, bAvg, direction)
+      } else if (sortColumn === 'condition') {
+        cmp = compareNullableNumber(HEALTH_ORDER[a.status] ?? 9, HEALTH_ORDER[b.status] ?? 9, direction)
+      } else if (sortColumn === 'verdict') {
+        cmp = compareNullableNumber(verdictRank(a.verdict), verdictRank(b.verdict), direction)
+      } else if (sortColumn === 'stability') {
+        cmp = compareNullableNumber(numericOrNull(a.stability), numericOrNull(b.stability), direction)
+      } else if (sortColumn === 'uptime') {
+        cmp = compareNullableNumber(numericOrNull(a.uptime), numericOrNull(b.uptime), direction)
+      } else if (sortColumn === 'aiLatency') {
+        cmp = compareNullableNumber(a.benchmark?.ok ? a.benchmark.totalMs : null, b.benchmark?.ok ? b.benchmark.totalMs : null, direction)
+      } else if (sortColumn === 'tps') {
+        cmp = compareNullableNumber(a.benchmark?.ok ? a.benchmark.tokensPerSecond ?? 0 : null, b.benchmark?.ok ? b.benchmark.tokensPerSecond ?? 0 : null, direction)
+      } else if (sortColumn === 'trend') {
+        cmp = compareNullableNumber(trendDelta(a), trendDelta(b), direction)
+      }
+
+      return cmp || (rankOrder(a) - rankOrder(b))
     })
 
     return result
-  }, [models, filterTier, filterStatus, filterProvider, searchQuery, sortColumn, sortDirection])
+  }, [models, filterTier, filterStatus, filterProvider, filterVerdict, filterHealth, visibilityMode, searchQuery, customTextFilter, sortColumn, sortDirection])
 
   return {
     filtered,
-    filterTier, setFilterTier,
-    filterStatus, setFilterStatus,
+    filterTier, setFilterTier, cycleTier,
+    filterStatus, setFilterStatus, cycleStatus,
     filterProvider, setFilterProvider,
+    filterVerdict, setFilterVerdict, cycleVerdict,
+    filterHealth, setFilterHealth, cycleHealth,
+    visibilityMode, setVisibilityMode, cycleVisibility,
     searchQuery, setSearchQuery,
+    customTextFilter, setCustomTextFilter,
     sortColumn, sortDirection, toggleSort,
+    resetView,
+  }
+}
+
+// ─── 3-bucket sort helpers (extracted for unit testing) ────────────────
+// 📖 The AI Latency + TPS columns sort rows by a "bucket" then by value:
+// 📖   bucket 0 = completed benchmark (has a real result)
+// 📖   bucket 1 = benchmark currently running (no result yet, but isBenchmarking)
+// 📖   bucket 2 = never tested (no benchmark object, not running)
+// 📖 Rows in buckets 1 and 2 are NOT sorted by their numeric value (they don't
+// 📖 have one) — the comparator returns 0 inside each bucket so the rank-based
+// 📖 tie-breaker takes over.
+
+/**
+ * 📖 Classify a model into one of the 3 benchmark buckets.
+ * @param {{benchmark?: {ok?: boolean}|null, isBenchmarking?: boolean}} model
+ * @returns {0|1|2}
+ */
+export function benchmarkBucket(model) {
+  if (!model) return 2
+  if (model.benchmark && model.benchmark.ok === true) return 0
+  if (model.isBenchmarking === true) return 1
+  return 2
+}
+
+/**
+ * 📖 Comparator for the AI Latency / TPS sort columns.
+ * 📖 Always agrees on bucket order (completed → running → never) regardless of
+ * 📖 direction. Within each bucket, returns 0 so the rank tie-breaker applies.
+ * 📖 `valueGetter` reads the numeric metric (totalMs for latency, tokensPerSecond for TPS).
+ * @param {object} a
+ * @param {object} b
+ * @param {1|-1} direction  — 1 = ascending, -1 = descending
+ * @param {(bench: object) => number} valueGetter
+ * @returns {number}
+ */
+export function compareBenchmark(a, b, direction, valueGetter) {
+  const ba = benchmarkBucket(a)
+  const bb = benchmarkBucket(b)
+  if (ba !== bb) {
+    // 📖 Completed always first, never-tested always last, regardless of direction.
+    if (ba < bb) return -1
+    return 1
   }
+  if (ba !== 0) return 0
+  // 📖 Both completed: sort by the actual metric.
+  const va = valueGetter ? valueGetter(a.benchmark) : null
+  const vb = valueGetter ? valueGetter(b.benchmark) : null
+  if (va == null && vb == null) return 0
+  if (va == null) return 1
+  if (vb == null) return -1
+  return (va - vb) * direction
 }

package/web/src/hooks/useSSE.js

@@ -6,44 +6,68 @@
  */
 import { useState, useEffect, useRef, useCallback } from 'react'
 
+const RECONNECT_DELAY = 2000
+
 export function useSSE(url = '/api/events') {
   const [models, setModels] = useState([])
   const [connected, setConnected] = useState(false)
   const [updateCount, setUpdateCount] = useState(0)
   const esRef = useRef(null)
-  const reconnectTimer = useRef(null)
+  const reconnectRef = useRef(null)
+  const mountedRef = useRef(true)
 
   const connect = useCallback(() => {
-    if (esRef.current) esRef.current.close()
+    if (!mountedRef.current) return
+
+    // Close existing connection
+    if (esRef.current) {
+      esRef.current.close()
+      esRef.current = null
+    }
+
+    clearTimeout(reconnectRef.current)
 
     const es = new EventSource(url)
     esRef.current = es
 
-    es.onopen = () => setConnected(true)
+    es.onopen = () => {
+      if (mountedRef.current) setConnected(true)
+    }
+
     es.onmessage = (event) => {
+      if (!mountedRef.current) return
       try {
         const data = JSON.parse(event.data)
         setModels(data)
-        setUpdateCount((c) => c + 1)
+        setUpdateCount(c => c + 1)
       } catch (e) {
-        console.error('SSE parse error:', e)
+        console.warn('[useSSE] parse error:', e)
       }
     }
+
     es.onerror = () => {
       setConnected(false)
       es.close()
-      clearTimeout(reconnectTimer.current)
-      reconnectTimer.current = setTimeout(connect, 3000)
+      esRef.current = null
+
+      if (mountedRef.current) {
+        reconnectRef.current = setTimeout(() => {
+          if (mountedRef.current) connect()
+        }, RECONNECT_DELAY)
+      }
     }
   }, [url])
 
   useEffect(() => {
+    mountedRef.current = true
     connect()
+
     return () => {
+      mountedRef.current = false
+      clearTimeout(reconnectRef.current)
       esRef.current?.close()
-      clearTimeout(reconnectTimer.current)
     }
   }, [connect])
 
   return { models, connected, updateCount }
-}
+}

package/web/src/hooks/useSocket.js

@@ -0,0 +1,200 @@
+/**
+ * @file web/src/hooks/useSocket.js
+ * @description Realtime model-data hook with Socket.IO primary, SSE fallback, and REST polling safety net.
+ *
+ * 📖 The dashboard runs locally, so freshness matters more than shaving every
+ * byte. Socket.IO gives the snappiest path in `pnpm dev:web`; SSE keeps Docker /
+ * daemon-style servers working without Socket.IO; REST polling guarantees the UI
+ * eventually recovers if both streaming transports are interrupted.
+ *
+ * @functions
+ *   → useSocket(serverUrl) — Subscribe to live dashboard state
+ * @exports useSocket
+ */
+import { useState, useEffect, useRef, useCallback } from 'react'
+import { io } from 'socket.io-client'
+
+const REST_FALLBACK_INTERVAL_MS = 2_000
+const STALE_UPDATE_MS = 4_000
+const ACTIVITY_THROTTLE_MS = 1_000
+
+function normalizePayload(data) {
+  if (!data) return null
+  if (Array.isArray(data)) return { models: data }
+  if (Array.isArray(data.models)) return data
+  return null
+}
+
+function sameOriginUrl(path, serverUrl) {
+  if (!serverUrl) return path
+  return `${serverUrl.replace(/\/$/, '')}${path}`
+}
+
+export function useSocket(serverUrl = '') {
+  const [models, setModels] = useState([])
+  const [connected, setConnected] = useState(false)
+  const [transport, setTransport] = useState('connecting')
+  const [updateCount, setUpdateCount] = useState(0)
+  const [nextPingAt, setNextPingAt] = useState(null)
+  const [serverIsPinging, setServerIsPinging] = useState(false)
+  const [pendingPings, setPendingPings] = useState(0)
+  const [pingMode, setPingMode] = useState('speed')
+  const [globalBenchmarkRunning, setGlobalBenchmarkRunning] = useState(false)
+  const [globalBenchmarkTotal, setGlobalBenchmarkTotal] = useState(0)
+  const [globalBenchmarkCompleted, setGlobalBenchmarkCompleted] = useState(0)
+
+  const socketRef = useRef(null)
+  const esRef = useRef(null)
+  const pollRef = useRef(null)
+  const lastUpdateRef = useRef(0)
+  const lastActivityRef = useRef(0)
+  const mountedRef = useRef(false)
+
+  const applyPayload = useCallback((raw, source = 'unknown') => {
+    const data = normalizePayload(raw)
+    if (!data || !mountedRef.current) return
+
+    setModels(data.models ?? [])
+    setPingMode(data.pingMode ?? 'speed')
+    setNextPingAt(data.nextPingAt ?? null)
+    setServerIsPinging(Boolean(data.isPinging))
+    setPendingPings(Number.isFinite(data.pendingPings) ? data.pendingPings : 0)
+    setGlobalBenchmarkRunning(Boolean(data.globalBenchmarkRunning))
+    setGlobalBenchmarkTotal(Number.isFinite(data.globalBenchmarkTotal) ? data.globalBenchmarkTotal : 0)
+    setGlobalBenchmarkCompleted(Number.isFinite(data.globalBenchmarkCompleted) ? data.globalBenchmarkCompleted : 0)
+    setUpdateCount((count) => count + 1)
+    lastUpdateRef.current = Date.now()
+    if (source !== 'poll') {
+      setConnected(true)
+      setTransport(source)
+    }
+  }, [])
+
+  const fetchSnapshot = useCallback(async () => {
+    try {
+      const stateResponse = await fetch(sameOriginUrl('/api/state', serverUrl), { headers: { Accept: 'application/json' } })
+      if (stateResponse.ok) {
+        applyPayload(await stateResponse.json(), 'poll')
+        setConnected(true)
+        setTransport((current) => current === 'socket' || current === 'sse' ? current : 'poll')
+        return
+      }
+    } catch {}
+
+    try {
+      const response = await fetch(sameOriginUrl('/api/models', serverUrl), { headers: { Accept: 'application/json' } })
+      if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      applyPayload(await response.json(), 'poll')
+      setConnected(true)
+      setTransport((current) => current === 'socket' || current === 'sse' ? current : 'poll')
+    } catch {
+      setConnected(false)
+      setTransport('offline')
+    }
+  }, [applyPayload, serverUrl])
+
+  const startSse = useCallback(() => {
+    if (esRef.current || !mountedRef.current) return
+    try {
+      const es = new EventSource(sameOriginUrl('/api/events', serverUrl))
+      esRef.current = es
+      es.onopen = () => {
+        if (!mountedRef.current) return
+        setConnected(true)
+        setTransport('sse')
+      }
+      const handleSsePayload = (event) => {
+        try { applyPayload(JSON.parse(event.data), 'sse') }
+        catch (err) { console.warn('[useSocket] SSE parse error:', err) }
+      }
+      es.onmessage = handleSsePayload
+      es.addEventListener('models', handleSsePayload)
+      es.onerror = () => {
+        es.close()
+        if (esRef.current === es) esRef.current = null
+        if (!socketRef.current?.connected) setConnected(false)
+      }
+    } catch {
+      esRef.current = null
+    }
+  }, [applyPayload, serverUrl])
+
+  const sendActivity = useCallback(() => {
+    const now = Date.now()
+    if (now - lastActivityRef.current < ACTIVITY_THROTTLE_MS) return
+    lastActivityRef.current = now
+
+    if (socketRef.current?.connected) {
+      socketRef.current.emit('client:activity')
+      return
+    }
+
+    fetch(sameOriginUrl('/api/activity', serverUrl), { method: 'POST' }).catch(() => {})
+  }, [serverUrl])
+
+  useEffect(() => {
+    mountedRef.current = true
+
+    const socket = io(serverUrl || undefined, {
+      transports: ['websocket', 'polling'],
+      reconnectionDelay: 500,
+      reconnectionDelayMax: 2500,
+      timeout: 1200,
+    })
+    socketRef.current = socket
+
+    socket.on('connect', () => {
+      setConnected(true)
+      setTransport('socket')
+      esRef.current?.close()
+      esRef.current = null
+      socket.emit('models:refresh')
+      socket.emit('client:activity')
+    })
+    socket.on('disconnect', () => {
+      if (!mountedRef.current) return
+      setConnected(false)
+      startSse()
+    })
+    socket.on('connect_error', () => {
+      if (!mountedRef.current) return
+      setConnected(false)
+      startSse()
+    })
+    socket.on('models:update', (data) => applyPayload(data, 'socket'))
+
+    pollRef.current = setInterval(() => {
+      const stale = Date.now() - lastUpdateRef.current > STALE_UPDATE_MS
+      if (!socket.connected || stale) void fetchSnapshot()
+    }, REST_FALLBACK_INTERVAL_MS)
+
+    void fetchSnapshot()
+
+    const activityEvents = ['keydown', 'pointerdown', 'mousemove', 'focus']
+    for (const eventName of activityEvents) window.addEventListener(eventName, sendActivity, { passive: true })
+
+    return () => {
+      mountedRef.current = false
+      for (const eventName of activityEvents) window.removeEventListener(eventName, sendActivity)
+      if (pollRef.current) clearInterval(pollRef.current)
+      socket.disconnect()
+      esRef.current?.close()
+      socketRef.current = null
+      esRef.current = null
+    }
+  }, [applyPayload, fetchSnapshot, sendActivity, serverUrl, startSse])
+
+  return {
+    models,
+    connected,
+    transport,
+    updateCount,
+    nextPingAt,
+    isPinging: serverIsPinging,
+    pendingPings,
+    pingMode,
+    globalBenchmarkRunning,
+    globalBenchmarkTotal,
+    globalBenchmarkCompleted,
+  }
+}