free-coding-models 0.5.1 → 0.5.4

package/web/src/hooks/useColumnSizing.js

@@ -0,0 +1,211 @@
+/**
+ * @file web/src/hooks/useColumnSizing.js
+ * @description React hook for resizable table columns with localStorage persistence.
+ *
+ * 📖 Wires TanStack Table's `columnSizing` state to a localStorage entry so the user's
+ * 📖 custom column widths survive page reloads and Dashboard/Desktop restarts.
+ *
+ * 📖 Storage strategy:
+ * 📖   - Key: `fcm.columnSizing.v1`
+ * 📖   - Value: JSON object { [columnId]: number } with the user's chosen widths in px
+ * 📖   - Read once on mount, written on every sizing change (debounced via React batching)
+ *
+ * 📖 Why a versioned key:
+ * 📖   - Future column additions or remodels can invalidate by bumping the suffix.
+ * 📖   - Old saved widths won't silently apply to a table whose columns have changed.
+ *
+ * 📖 Why not Zustand/Redux:
+ * 📖   - localStorage is the simplest possible cross-tab/cross-session persistence layer.
+ * 📖   - The data is 200 bytes max — no need for IndexedDB or a migration story.
+ * 📖   - SSR safety: every localStorage access is guarded with `typeof window !== 'undefined'`.
+ *
+ * @functions
+ *   → useColumnSizing(defaultSizing) — returns { columnSizing, setColumnSizing, resetColumnSizing, hasCustomSizing }
+ *   → sanitizeSizing / clampSizing / mergeSizing / hasCustomSizing — pure helpers (unit-tested)
+ *   → readSizingFromStorage / writeSizingToStorage / removeSizingFromStorage — storage adapters
+ * @exports useColumnSizing, sanitizeSizing, clampSizing, mergeSizing, hasCustomSizing,
+ *          readSizingFromStorage, writeSizingToStorage, removeSizingFromStorage,
+ *          COLUMN_SIZING_STORAGE_KEY, COLUMN_SIZING_MIN, COLUMN_SIZING_MAX
+ */
+
+import { useState, useCallback, useEffect, useRef } from 'react'
+
+export const COLUMN_SIZING_STORAGE_KEY = 'fcm.columnSizing.v1'
+
+// 📖 Bounds (px) for every column width. Mirrored in the model's CSS so the
+// 📖 rendering layer never has to ask the hook about min/max.
+export const COLUMN_SIZING_MIN = 24
+export const COLUMN_SIZING_MAX = 1200
+
+/**
+ * 📖 sanitizeSizing: Validate + clean an arbitrary object into a { id: number } map.
+ * 📖 Strips non-numbers, NaN, Infinity, zero, and negative widths.
+ * 📖 Exported for unit testing and for any future code path that ingests raw input.
+ */
+export function sanitizeSizing(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return {}
+  const out = {}
+  for (const [k, v] of Object.entries(input)) {
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0) out[k] = v
+  }
+  return out
+}
+
+/**
+ * 📖 clampSizing: Force every value into [min, max], rounded to an integer.
+ * 📖 Drops entries whose value is not a finite number so a typo in storage
+ * 📖 never crashes the dashboard.
+ */
+export function clampSizing(sizing, min = COLUMN_SIZING_MIN, max = COLUMN_SIZING_MAX) {
+  const out = {}
+  for (const [k, v] of Object.entries(sizing || {})) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) continue
+    out[k] = Math.max(min, Math.min(max, Math.round(v)))
+  }
+  return out
+}
+
+/**
+ * 📖 mergeSizing: Layer the stored widths on top of the defaults, with the
+ * 📖 runtime (in-memory) state winning on conflicts. This three-way merge is
+ * 📖 what keeps new columns (added in newer releases) from disappearing when
+ * 📖 a stale localStorage entry is loaded.
+ */
+export function mergeSizing(defaults, stored, runtime) {
+  return { ...(defaults || {}), ...(stored || {}), ...(runtime || {}) }
+}
+
+/**
+ * 📖 hasCustomSizing: True when at least one column differs from its default.
+ * 📖 Used by the UI to decide whether to show a "Reset" affordance.
+ */
+export function hasCustomSizing(current, defaults) {
+  if (!current || !defaults) return false
+  for (const k of Object.keys(current)) {
+    if (current[k] !== defaults[k]) return true
+  }
+  return false
+}
+
+/**
+ * 📖 readSizingFromStorage: Read JSON from a localStorage-like object, returns
+ * 📖 a sanitized empty object on any failure. Exported separately from the
+ * 📖 React hook so unit tests can drive it without a DOM.
+ *
+ * 📖 @param {Storage|null|undefined} storage  - the localStorage-like object
+ * 📖 @param {string} key                        - the storage key
+ * 📖 @param {Object} fallback                  - default if missing/empty
+ */
+export function readSizingFromStorage(storage, key, fallback = {}) {
+  if (!storage || typeof storage.getItem !== 'function') return fallback
+  let raw
+  try { raw = storage.getItem(key) } catch { return fallback }
+  if (!raw) return fallback
+  let parsed
+  try { parsed = JSON.parse(raw) } catch { return fallback }
+  return sanitizeSizing(parsed)
+}
+
+/**
+ * 📖 writeSizingToStorage: Persist a sizing object to a localStorage-like store.
+ * 📖 Returns true on success, false on any failure (quota, private mode, etc.).
+ */
+export function writeSizingToStorage(storage, key, sizing) {
+  if (!storage || typeof storage.setItem !== 'function') return false
+  try {
+    storage.setItem(key, JSON.stringify(sizing))
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 📖 removeSizingFromStorage: Best-effort delete; used when the runtime sizing
+ * 📖 returns to defaults so we don't keep stale entries around.
+ */
+export function removeSizingFromStorage(storage, key) {
+  if (!storage || typeof storage.removeItem !== 'function') return false
+  try { storage.removeItem(key); return true } catch { return false }
+}
+
+/**
+ * 📖 useColumnSizing: TanStack-compatible state for the table's columnSizing slot.
+ *
+ * 📖 Pass the default sizing object (e.g. `{ mood: 28, idx: 36, ... }`) used to seed
+ * 📖 new sessions; it also acts as the "reset to defaults" target.
+ *
+ * @param {Object} defaultSizing - { [columnId]: number } — defaults for the current column set
+ * @returns {{
+ *   columnSizing: Object,
+ *   setColumnSizing: (updater: Object | ((prev: Object) => Object)) => void,
+ *   resetColumnSizing: () => void,
+ *   hasCustomSizing: boolean,
+ * }}
+ */
+export function useColumnSizing(defaultSizing) {
+  const defaultRef = useRef(defaultSizing)
+  defaultRef.current = defaultSizing
+
+  const [columnSizing, setColumnSizingState] = useState(() => {
+    // 📖 SSR / unit-test safe: in Node, window is undefined and we fall back to defaults.
+    if (typeof window === 'undefined') return { ...defaultSizing }
+    const stored = readSizingFromStorage(window.localStorage, COLUMN_SIZING_STORAGE_KEY, {})
+    // 📖 Merge: defaults first, then stored overrides. New columns added in a
+    // 📖 future release still get their declared default width.
+    return mergeSizing(defaultSizing, stored, {})
+  })
+
+  // 📖 Keep a ref to the latest sizing for the cross-tab sync listener.
+  const sizingRef = useRef(columnSizing)
+  sizingRef.current = columnSizing
+
+  // 📖 Persist on every change. React batches updates, so this only fires once per real change.
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.localStorage) return
+    // 📖 When the runtime matches the defaults, drop the stored entry so a "reset"
+    // 📖 is also persisted (no orphan entry, no waste of quota).
+    if (!hasCustomSizing(columnSizing, defaultRef.current)) {
+      removeSizingFromStorage(window.localStorage, COLUMN_SIZING_STORAGE_KEY)
+      return
+    }
+    writeSizingToStorage(window.localStorage, COLUMN_SIZING_STORAGE_KEY, columnSizing)
+  }, [columnSizing])
+
+  // 📖 Cross-tab sync: if the user resizes columns in another tab/window, apply it live here.
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.addEventListener) return
+    const onStorage = (e) => {
+      if (e.key !== COLUMN_SIZING_STORAGE_KEY) return
+      const next = readSizingFromStorage(window.localStorage, COLUMN_SIZING_STORAGE_KEY, {})
+      // 📖 Merge incoming changes into the current default-sourced state so removed
+      // 📖 columns in the incoming payload don't drop widths for columns we still show.
+      setColumnSizingState((prev) => mergeSizing(defaultRef.current, next, prev))
+    }
+    window.addEventListener('storage', onStorage)
+    return () => window.removeEventListener('storage', onStorage)
+  }, [])
+
+  const setColumnSizing = useCallback((updater) => {
+    setColumnSizingState((prev) => {
+      const next = typeof updater === 'function' ? updater(prev) : updater
+      // 📖 Clamp every value: TanStack can momentarily receive 0-width from a drag,
+      // 📖 but rendering a 0-width column breaks layout.
+      return { ...prev, ...clampSizing(next) }
+    })
+  }, [])
+
+  const resetColumnSizing = useCallback(() => {
+    setColumnSizingState({ ...defaultRef.current })
+  }, [])
+
+  // 📖 hasCustomSizing is memoized cheaply — one pass over the current keys is enough.
+  const isCustom = hasCustomSizing(columnSizing, defaultRef.current)
+
+  return {
+    columnSizing,
+    setColumnSizing,
+    resetColumnSizing,
+    hasCustomSizing: isCustom,
+  }
+}

package/web/src/hooks/useFavorites.js

@@ -0,0 +1,150 @@
+/**
+ * @file web/src/hooks/useFavorites.js
+ * @description Favorites management hook for the Web Dashboard — M1 parity with TUI `F` / `Y` / `Shift+↑↓`.
+ * 📖 Persists through the existing ~/.free-coding-models.json config file (same source as the TUI),
+ * 📖 via the /api/favorites endpoint. Both surfaces share the same favorites list.
+ *
+ * 📖 Storage shape (mirrors src/core/favorites.js):
+ * 📖   config.favorites              — string[] of "providerKey/modelId", insertion-ordered
+ * 📖   config.settings.favoritesPinnedAndSticky — boolean (TUI `Y` key behavior)
+ *
+ * 📖 Returns a stable shape the rest of the Web UI can consume:
+ * 📖   {
+ * 📖     favorites: string[],                — current favorites in priority order
+ * 📖     pinnedAndSticky: boolean,           — true = favorites bypass filters
+ * 📖     isFavorite(model): boolean,         — predicate
+ * 📖     favoriteRank(model): number,        — 0-based index, Number.MAX_SAFE_INTEGER if not favorited
+ * 📖     toggle(model): Promise<void>,       — add/remove
+ * 📖     reorder(model, dir): Promise<void>, — 'up' or 'down'
+ * 📖     setPinnedAndSticky(bool): Promise<void>,
+ * 📖     refresh(): Promise<void>,           — manual reload from server
+ * 📖     loading: boolean,                   — initial load
+ * 📖   }
+ *
+ * @functions
+ *   → useFavorites({ models }) — hook
+ *
+ * @see src/core/favorites.js — TUI engine (same storage format)
+ * @see web/server.js — /api/favorites endpoint
+ */
+import { useCallback, useEffect, useState, useMemo } from 'react'
+
+const EMPTY_FAVORITES = Object.freeze([])
+
+export function useFavorites({ models } = {}) {
+  const [favorites, setFavorites] = useState(EMPTY_FAVORITES)
+  const [pinnedAndSticky, setPinnedAndStickyState] = useState(false)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState(null)
+
+  // 📖 Initial load: fetch the current favorites + pinnedAndSticky from the server.
+  const refresh = useCallback(async () => {
+    try {
+      const resp = await fetch('/api/favorites')
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
+      const data = await resp.json()
+      setFavorites(Array.isArray(data.favorites) ? data.favorites : [])
+      setPinnedAndStickyState(Boolean(data.pinnedAndSticky))
+      setError(null)
+    } catch (err) {
+      setError(err.message || 'Failed to load favorites')
+      // 📖 On error, fall back to empty state — the UI stays usable.
+      setFavorites(EMPTY_FAVORITES)
+      setPinnedAndStickyState(false)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => { refresh() }, [refresh])
+
+  // 📖 Build a map "providerKey/modelId" → index for O(1) lookup.
+  const favoriteIndex = useMemo(() => {
+    const map = new Map()
+    favorites.forEach((key, idx) => map.set(key, idx))
+    return map
+  }, [favorites])
+
+  const isFavorite = useCallback((model) => {
+    if (!model) return false
+    const key = `${model.providerKey}/${model.modelId}`
+    return favoriteIndex.has(key)
+  }, [favoriteIndex])
+
+  const favoriteRank = useCallback((model) => {
+    if (!model) return Number.MAX_SAFE_INTEGER
+    const key = `${model.providerKey}/${model.modelId}`
+    const idx = favoriteIndex.get(key)
+    return idx === undefined ? Number.MAX_SAFE_INTEGER : idx
+  }, [favoriteIndex])
+
+  // 📖 Build a key for the API — same shape the TUI uses (providerKey/modelId).
+  const keyOf = useCallback((model) => {
+    if (!model) return null
+    return `${model.providerKey}/${model.modelId}`
+  }, [])
+
+  // 📖 Send the updated favorites list to the server.
+  const persistFavorites = useCallback(async (next) => {
+    try {
+      const resp = await fetch('/api/favorites', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ favorites: next }),
+      })
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
+      setFavorites(next)
+    } catch (err) {
+      setError(err.message || 'Failed to save favorites')
+    }
+  }, [])
+
+  const toggle = useCallback(async (model) => {
+    const key = keyOf(model)
+    if (!key) return
+    const exists = favoriteIndex.has(key)
+    const next = exists
+      ? favorites.filter((k) => k !== key)
+      : [...favorites, key]
+    await persistFavorites(next)
+  }, [favorites, favoriteIndex, keyOf, persistFavorites])
+
+  const reorder = useCallback(async (model, direction) => {
+    const key = keyOf(model)
+    if (!key) return
+    const idx = favorites.indexOf(key)
+    if (idx < 0) return
+    const swapIdx = direction === 'up' ? idx - 1 : idx + 1
+    if (swapIdx < 0 || swapIdx >= favorites.length) return
+    const next = [...favorites]
+    ;[next[idx], next[swapIdx]] = [next[swapIdx], next[idx]]
+    await persistFavorites(next)
+  }, [favorites, keyOf, persistFavorites])
+
+  const setPinnedAndSticky = useCallback(async (value) => {
+    setPinnedAndStickyState(Boolean(value))
+    try {
+      await fetch('/api/favorites', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ pinnedAndSticky: Boolean(value) }),
+      })
+    } catch (err) {
+      setError(err.message || 'Failed to save display mode')
+    }
+  }, [])
+
+  // 📖 Return a stable object — callers can destructure safely across renders.
+  return {
+    favorites,
+    pinnedAndSticky,
+    isFavorite,
+    favoriteRank,
+    toggle,
+    reorder,
+    setPinnedAndSticky,
+    refresh,
+    loading,
+    error,
+  }
+}

package/web/src/hooks/useFilter.js

@@ -2,13 +2,16 @@
  * @file web/src/hooks/useFilter.js
  * @description React hook for model filtering and tri-state sorting state.
  *
- * 📖 Manages tier/status/provider/text filters plus table sorting. Every visible
- * dashboard column can cycle through: ascending → descending → reset. Reset
- * returns the filtered list to catalog/rank order, which is the least surprising
- * neutral state after users have explored a sorted column.
+ * 📖 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
  *
- * Supports all CLI/Web columns: mood, idx, tier, sweScore, ctx, label, origin,
- * latestPing, avg, condition, verdict, stability, uptime, aiLatency, tps, trend.
+ * 📖 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
@@ -18,6 +21,17 @@ 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
 }
@@ -64,35 +78,75 @@ function compareNullableString(aValue, bValue, direction) {
   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) => {
     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'
@@ -101,17 +155,43 @@ 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) => {
@@ -141,8 +221,7 @@ export function useFilter(models) {
         const bAvg = b.avg == null || b.avg === Infinity || b.avg > 99000 ? null : b.avg
         cmp = compareNullableNumber(aAvg, bAvg, direction)
       } else if (sortColumn === 'condition') {
-        const healthOrder = { up: 0, timeout: 1, down: 2, pending: 3, noauth: 4, auth_error: 5 }
-        cmp = compareNullableNumber(healthOrder[a.status] ?? 9, healthOrder[b.status] ?? 9, direction)
+        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') {
@@ -154,7 +233,6 @@ export function useFilter(models) {
       } 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') {
-        // 📖 Negative delta means latency improved over the visible sparkline; positive means it got slower.
         cmp = compareNullableNumber(trendDelta(a), trendDelta(b), direction)
       }
 
@@ -162,14 +240,69 @@ export function useFilter(models) {
     })
 
     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
 }