free-coding-models 0.5.0 → 0.5.4

package/web/src/global.css

@@ -8,23 +8,24 @@
 
 /* ─── CSS Custom Properties (Design Tokens) ─── */
 :root {
-  --color-bg:           #0a0a0f;
-  --color-bg-elevated:  #12121a;
-  --color-bg-card:      rgba(18, 18, 30, 0.7);
-  --color-bg-hover:     rgba(30, 30, 50, 0.8);
-  --color-bg-active:    rgba(40, 40, 65, 0.9);
-  --color-surface:      #1a1a2e;
-  --color-border:       rgba(255, 255, 255, 0.06);
-  --color-border-hover: rgba(255, 255, 255, 0.12);
-
-  --color-text:         #e8e8f0;
-  --color-text-muted:   #8888a8;
-  --color-text-dim:     #555570;
-
-  --color-accent:       #76b900;
-  --color-accent-hover: #8ad100;
-  --color-accent-glow:  rgba(118, 185, 0, 0.25);
-  --color-accent-dim:   rgba(118, 185, 0, 0.08);
+  --color-brand:        #76b900;
+  --color-bg:           #000000;
+  --color-bg-elevated:  #0a0a0a;
+  --color-bg-card:      #0a0a0a;
+  --color-bg-hover:     #161616;
+  --color-bg-active:    #222222;
+  --color-surface:      #111111;
+  --color-border:       #262626;
+  --color-border-hover: #404040;
+
+  --color-text:         #ffffff;
+  --color-text-muted:   #888888;
+  --color-text-dim:     #444444;
+
+  --color-accent:       #ffffff;
+  --color-accent-hover: #eaeaea;
+  --color-accent-glow:  rgba(255, 255, 255, 0.1);
+  --color-accent-dim:   rgba(255, 255, 255, 0.05);
 
   --color-danger:       #ff4444;
   --color-danger-dim:   rgba(255, 68, 68, 0.1);
@@ -58,17 +59,15 @@
   --font-mono:  'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;
 
   --header-h: 60px;
-  --sidebar-w: 64px;
-  --sidebar-w-expanded: 200px;
-  --radius-sm: 6px;
-  --radius-md: 10px;
-  --radius-lg: 16px;
-  --radius-xl: 20px;
-
-  --shadow-sm:   0 1px 3px rgba(0,0,0,0.3);
-  --shadow-md:   0 4px 12px rgba(0,0,0,0.4);
-  --shadow-lg:   0 8px 32px rgba(0,0,0,0.5);
-  --shadow-glow: 0 0 30px var(--color-accent-glow);
+  --radius-sm: 4px;
+  --radius-md: 6px;
+  --radius-lg: 8px;
+  --radius-xl: 8px;
+
+  --shadow-sm:   none;
+  --shadow-md:   none;
+  --shadow-lg:   none;
+  --shadow-glow: none;
 
   --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
   --transition-fast: 150ms var(--ease-out);
@@ -78,26 +77,60 @@
 
 /* ─── Light Theme ─── */
 [data-theme="light"] {
-  --color-bg:           #f5f5fa;
+  --color-bg:           #ffffff;
   --color-bg-elevated:  #ffffff;
-  --color-bg-card:      rgba(255, 255, 255, 0.85);
-  --color-bg-hover:     rgba(240, 240, 248, 0.9);
-  --color-bg-active:    rgba(230, 230, 242, 0.95);
-  --color-surface:      #eeeef4;
-  --color-border:       rgba(0, 0, 0, 0.08);
-  --color-border-hover: rgba(0, 0, 0, 0.15);
-  --color-text:         #1a1a2e;
-  --color-text-muted:   #666688;
-  --color-text-dim:     #9999aa;
-  --color-accent-glow:  rgba(118, 185, 0, 0.15);
-  --color-accent-dim:   rgba(118, 185, 0, 0.05);
-  --color-danger-dim:   rgba(255, 68, 68, 0.08);
-  --color-warning-dim:  rgba(255, 170, 0, 0.08);
-  --color-success-dim:  rgba(0, 255, 136, 0.08);
-  --color-info-dim:     rgba(6, 182, 212, 0.08);
-  --shadow-sm:   0 1px 3px rgba(0,0,0,0.08);
-  --shadow-md:   0 4px 12px rgba(0,0,0,0.1);
-  --shadow-lg:   0 8px 32px rgba(0,0,0,0.12);
+  --color-bg-card:      #ffffff;
+  --color-bg-hover:     #fafafa;
+  --color-bg-active:    #f0f0f0;
+  --color-surface:      #fafafa;
+  --color-border:       #eaeaea;
+  --color-border-hover: #d5d5d5;
+  --color-text:         #000000;
+  --color-text-muted:   #666666;
+  --color-text-dim:     #999999;
+  --color-accent:       #000000;
+  --color-accent-hover: #333333;
+  --color-accent-glow:  rgba(0, 0, 0, 0.05);
+  --color-accent-dim:   rgba(0, 0, 0, 0.02);
+
+  /* 📖 Bright neon colors that look great on black become unreadable on white.
+     📖 We swap them for darker, AA-contrast equivalents in light mode. The
+     📖 hex values are picked to stay visually similar to the dark variant
+     📖 (still "green" / "cyan" / "gold") while passing WCAG AA on #fff. */
+  --color-success:      #008f4d;     /* was #00ff88 (neon) */
+  --color-warning:      #b86b00;     /* was #ffaa00 (neon amber) */
+  --color-danger:       #c8143a;     /* was #ff4444 (neon red) */
+  --color-info:         #0e7490;     /* was #06b6d4 (neon cyan) */
+  --color-danger-dim:   rgba(200, 20, 58, 0.08);
+  --color-warning-dim:  rgba(184, 107, 0, 0.08);
+  --color-success-dim:  rgba(0, 143, 77, 0.08);
+  --color-info-dim:     rgba(14, 116, 144, 0.08);
+
+  /* 📖 Tier + verdict palette: shift toward darker, more saturated variants
+     📖 so badges stay legible on white. The original "neon" feel is dropped
+     📖 in favor of "saturated-but-deep" colors that pass contrast. */
+  --tier-splus:  #b08800;     /* was #ffd700 (gold) */
+  --tier-s:      #c45a00;     /* was #ff8c00 (dark orange) */
+  --tier-aplus:  #0073a8;     /* was #00c8ff (neon cyan) */
+  --tier-a:      #1f7a3e;     /* was #3ddc84 (mid green) */
+  --tier-aminus: #2f7a2f;     /* was #7ecf7e (light green) */
+  --tier-bplus:  #5a5a8a;     /* was #a8a8c8 (lavender) */
+  --tier-b:      #555566;     /* was #808098 (gray-blue) */
+  --tier-c:      #6a6a7a;     /* was #606078 (slate) */
+
+  --verdict-perfect:    #008f4d;     /* was #00ff88 */
+  --verdict-normal:     #4a7a00;     /* was #76b900 */
+  --verdict-slow:       #b86b00;     /* was #ffaa00 */
+  --verdict-spiky:      #c45000;     /* was #ff6600 */
+  --verdict-veryslow:   #c8143a;     /* was #ff4444 */
+  --verdict-overloaded: #b8101f;     /* was #ff2222 */
+  --verdict-unstable:   #990000;     /* was #cc0000 */
+  --verdict-notactive:  #6a6a7a;     /* was #555570 */
+  --verdict-pending:    #6a6a8a;     /* was #444460 */
+
+  --shadow-sm:   none;
+  --shadow-md:   none;
+  --shadow-lg:   none;
 }
 
 /* ─── Reset & Base ─── */
@@ -118,6 +151,7 @@ body {
   overflow-x: hidden;
   position: relative;
   display: flex;
+  flex-direction: column;
 }
 
 a { color: var(--color-accent); text-decoration: none; }
@@ -126,41 +160,13 @@ code { font-family: var(--font-mono); font-size: 12px; background: var(--color-s
 
 /* ─── Background Effects ─── */
 .bg-grid {
-  position: fixed; inset: 0; z-index: 0; pointer-events: none;
-  background-image:
-    linear-gradient(rgba(255,255,255,0.02) 1px, transparent 1px),
-    linear-gradient(90deg, rgba(255,255,255,0.02) 1px, transparent 1px);
-  background-size: 60px 60px;
+  display: none;
 }
 
 .bg-glow {
-  position: fixed; z-index: 0; pointer-events: none;
-  border-radius: 50%;
-  filter: blur(120px);
-  opacity: 0.3;
-  animation: float 20s ease-in-out infinite;
-}
-.bg-glow--1 {
-  width: 600px; height: 600px;
-  background: radial-gradient(circle, var(--color-accent) 0%, transparent 70%);
-  top: -200px; left: -200px;
-}
-.bg-glow--2 {
-  width: 400px; height: 400px;
-  background: radial-gradient(circle, #6366f1 0%, transparent 70%);
-  top: 50%; right: -150px; animation-delay: -7s;
-}
-.bg-glow--3 {
-  width: 500px; height: 500px;
-  background: radial-gradient(circle, #06b6d4 0%, transparent 70%);
-  bottom: -200px; left: 30%; animation-delay: -14s;
+  display: none;
 }
 
-@keyframes float {
-  0%, 100% { transform: translate(0, 0) scale(1); }
-  33% { transform: translate(30px, -30px) scale(1.05); }
-  66% { transform: translate(-20px, 20px) scale(0.95); }
-}
 
 [data-theme="light"] .bg-glow { opacity: 0.12; }
 [data-theme="light"] .bg-grid {
@@ -170,30 +176,58 @@ code { font-family: var(--font-mono); font-size: 12px; background: var(--color-s
 }
 
 /* ─── App Layout ─── */
+.app-shell {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  width: 100%;
+  position: relative;
+  z-index: 1;
+}
+
 .app-content {
   flex: 1;
-  margin-left: var(--sidebar-w);
   position: relative;
   z-index: 1;
-  min-height: 100vh;
+  min-height: calc(100vh - var(--header-h));
   display: flex;
   flex-direction: column;
-  transition: margin-left var(--transition-medium);
 }
 
 .view {
   display: flex;
   flex-direction: column;
   flex: 1;
+  min-height: 0;
 }
 
 /* ─── Scrollbar ─── */
-::-webkit-scrollbar { width: 6px; }
-::-webkit-scrollbar-track { background: transparent; }
-::-webkit-scrollbar-thumb { background: var(--color-border); border-radius: 3px; }
+::-webkit-scrollbar { width: 8px; height: 8px; }
+::-webkit-scrollbar-track { background: var(--color-bg); }
+::-webkit-scrollbar-thumb { background: var(--color-border); border-radius: 4px; }
 ::-webkit-scrollbar-thumb:hover { background: var(--color-text-dim); }
+::-webkit-scrollbar-corner { background: var(--color-bg); }
 
 /* ─── Responsive ─── */
 @media (max-width: 768px) {
-  .app-content { margin-left: 0; }
+  /* 📖 No sidebar to collapse on small viewports — the header itself collapses
+     📖 (see Header.module.css). The model table keeps its 100% width. */
+}
+
+/* ─── Full-page horizontal/vertical scroll layout ─── */
+.app-content {
+  flex: 1;
+  position: relative;
+  z-index: 1;
+  min-height: calc(100vh - var(--header-h));
+  display: flex;
+  flex-direction: column;
+}
+
+.view {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
 }

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,
+  }
+}