fix: persistent TV connection + eliminate concurrent socket races

[danmunz]

Summary

Fixes the critical TV connection failures reported by u/Feastweasel (524 artworks, Docker) where every TV operation failed with ConnectionFailure / socket closed, and the UI froze for 10–45 seconds during thumbnail loading. Also ships several related improvements accumulated during the investigation.

Root Cause

Six interconnected bugs in the TV communication layer, detailed in #67. The two critical ones:

1. Background thumbnail pre-fetch bypassed _tv_lock — opened an unguarded concurrent WebSocket that crashed the TV's socket server
2. Every _tv_op opened/closed a new WebSocket — 56+ connect/disconnect cycles per page load with 524 artworks

How Each Issue Is Resolved

Closes #67 — TV operations fail with ConnectionFailure / socket closed on large catalogs

The primary bug. Six root causes, all addressed:

Root Cause	Fix
_fetch_thumbnails_sync bypasses _tv_lock → concurrent WebSocket crashes TV	Removed entirely. No more background pre-fetch. Thumbnails are fetched on demand through the lock-protected /api/thumbnails endpoint.
Every _tv_op opens/closes a new WebSocket (56+ cycles)	Persistent connection. _ensure_tv_connection() reuses a single WebSocket across all operations. Auto-reconnects on failure via _close_tv_connection(). Reduced from 11 connections to 2 in testing.
Single _tv_lock serializes ALL ops → lock starvation	Lock released between retries. The retry loop now releases _tv_lock during the delay, so other operations can proceed instead of starving for 58+ seconds.
"TV is listening" indicator set once, never updated	Dynamic status updates. New updateTvStatus() function flips the indicator to "TV went to sleep" on any 502 error, and back to online when operations succeed.
Failed retries hold lock for up to 58 seconds	Same fix as lock starvation — lock released between attempts.
Frontend fires ~53 serial thumbnail requests for 524 artworks	Batch size 10 → 50. Reduces to ~11 requests. Timeout raised 12s → 30s to accommodate.

Closes #19 — Add /health endpoint for liveness checks

Added GET /health — a lightweight endpoint that checks data file integrity, directory writability, and uptime without attempting a TV connection. Returns structured JSON:

{"status": "ok", "version": "1.0.1", "tv_ip": "192.168.1.24", "data_dir": "/data", "data_files": {"collections": "ok", ...}, "uptime_seconds": 3600}

Also added a Docker HEALTHCHECK directive that polls /health every 30s (plus curl in the Dockerfile to support it).

Closes #57 — Corrupted JSON data files crash the server with no recovery

All five JSON data files (collections.json, artwork_meta.json, ai_config.json, api_usage.json, drive_sync.json) now use _safe_load_json():

• Corruption recovery: catches JSONDecodeError / ValueError, logs the error, backs up the corrupt file as filename.corrupt.TIMESTAMP, and returns sensible defaults so the server keeps running.
• Startup validation: all JSON files are loaded at startup in lifespan() so corruption is detected immediately, not on first user request.
• Atomic write backups: _atomic_write_json() now copies the existing file to .bak before overwriting, creating a one-deep recovery point.

Closes #63 — Jump-to-current-artwork button

Added a floating action button (FAB) in the bottom-right corner:

• Scrolls to the currently displayed artwork with smooth scroll, accounting for header and group nav height.
• Auto-shows/hides via _updateCurrentCardObserver() — visible when currentId is set, hidden when no artwork is displayed.
• Compact on scroll — shrinks when scrolled past 200px to stay unobtrusive.
• Filter-aware — if the current artwork is filtered out, shows a toast: "Current artwork is not visible — try clearing filters."

Closes #47 — AI settings UX: unclear relationship between Vision, Analysis, and API keys

Added inline .settings-hint help text throughout the AI Settings modal:

• Under Identification: explains it's optional, what Vision does (reverse-image search for hints), and that analysis works without it.
• Under Analysis: explains it's required for AI features, what it produces (title, artist, year, medium, etc.), and that Vision results are passed as context when enabled.
• Under each API key field: direct "Get a key →" links to the provider's console.
• Under model selectors: brief guidance ("Sonnet is best for most users. Haiku is cheapest." / "Pick whichever you already have a key for.").

What Changed

Backend (server.py)

• Persistent WebSocket connection — _ensure_tv_connection() / _close_tv_connection() reuse a single connection across all TV operations
• Removed _fetch_thumbnails_sync — eliminated the unguarded background pre-fetch
• Routed /api/art and /api/art/refresh through _tv_op — all TV access through the persistent connection
• Released _tv_lock between retries — no more 58-second lock starvation
• Added /health endpoint — lightweight status check without TV connection
• _safe_load_json() — corruption recovery with automatic backup
• _atomic_write_json() — backs up existing file before overwriting
• Startup validation — all JSON files loaded and checked in lifespan()

Frontend (index.html)

• Thumbnail batch size 10 → 50, timeout 12s → 30s
• updateTvStatus() — dynamic TV status indicator on 502 errors
• Jump-to-current FAB — scrollToCurrentCard(), _updateCurrentCardObserver(), compact-on-scroll
• AI settings hints — .settings-hint inline help text with provider links

Infrastructure

• Docker HEALTHCHECK — polls /health every 30s
• Dockerfile — added curl for healthcheck

Tests

• conftest.py — reset _tv_conn / _tv_art between tests
• New tests for health endpoint and file persistence (90 total, all passing)

Test Results

Reproduced on a local setup with 61 artworks. Same test (3 concurrent page-load requests + 6 concurrent thumbnail batches + 1 user select):

Metric	Before	After
WebSocket connections	11	2
Thumbnail batch failures	6/6	6/6 (TV API issue, not connection)
Background pre-fetch race	Present	Eliminated
Lock held during retries	Up to 58s	Released between attempts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8681b6ce09

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".