feat: add v2 stack (backend, runner, ui-v2) with release workflow

- backend/: Go API server and runner binaries with PocketBase + MinIO storage
- ui-v2/: SvelteKit frontend rewrite
- docker-compose-new.yml: compose file for the v2 stack
- .gitea/workflows/release-v2.yaml: CI/CD for backend, runner, and ui-v2 Docker Hub images
- scripts/pb-init.sh: migrate from wget to curl, add superuser bootstrap for fresh installs
- .env.example: document DOCKER_BUILDKIT=1 for Colima users

backend/internal/backend/handlers.go

@@ -0,0 +1,937 @@
+package backend
+
+// handlers.go — all HTTP request handlers for the backend server.
+//
+// Handler naming mirrors the route table in server.go:
+//   handleScrapeCatalogue, handleScrapeBook, handleScrapeBookRange
+//   handleScrapeStatus, handleScrapeTasks
+//   handleBrowse, handleSearch
+//   handleGetRanking, handleGetCover
+//   handleBookPreview, handleChapterText, handleReindex
+//   handleChapterText, handleReindex
+//   handleAudioGenerate, handleAudioStatus, handleAudioProxy
+//   handleVoices
+//   handlePresignChapter, handlePresignAudio, handlePresignVoiceSample
+//   handlePresignAvatarUpload, handlePresignAvatar
+//   handleGetProgress, handleSetProgress, handleDeleteProgress
+//
+// Key design choices vs. old scraper:
+//   - POST /scrape* creates a PocketBase task record and returns 202 with the
+//     task_id — it does NOT run the orchestrator inline.
+//   - POST /api/audio creates a PocketBase audio task and returns 202 — the
+//     runner binary executes TTS generation asynchronously.
+//   - GET /api/audio/status polls PocketBase for the task record status.
+//   - GET /api/audio-proxy reads the completed audio object from MinIO via a
+//     presigned URL redirect (the runner has already uploaded the bytes).
+//   - GET /api/browse and /api/search fetch novelfire.net live (no MinIO cache).
+//   - GET /api/cover redirects to the source cover URL live.
+//   - GET /api/ranking reads from the PocketBase ranking collection (populated
+//     by the runner after each catalogue scrape).
+//   - GET /api/book-preview returns stored data when in library, or enqueues a
+//     scrape task and returns 202 when not. The backend never scrapes directly.
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/libnovel/backend/internal/domain"
+	"github.com/libnovel/backend/internal/kokoro"
+)
+
+const (
+	novelFireBase   = "https://novelfire.net"
+	novelFireDomain = "novelfire.net"
+)
+
+// ── Scrape task creation ───────────────────────────────────────────────────────
+
+// handleScrapeCatalogue handles POST /scrape.
+// Creates a "catalogue" scrape task in PocketBase and returns 202 with the task ID.
+func (s *Server) handleScrapeCatalogue(w http.ResponseWriter, r *http.Request) {
+	taskID, err := s.deps.Producer.CreateScrapeTask(r.Context(), "catalogue", "", 0, 0)
+	if err != nil {
+		s.deps.Log.Error("handleScrapeCatalogue: CreateScrapeTask failed", "err", err)
+		jsonError(w, http.StatusInternalServerError, "failed to create task")
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]string{"task_id": taskID, "status": "accepted"})
+}
+
+// handleScrapeBook handles POST /scrape/book.
+// Body: {"url": "https://novelfire.net/book/..."}
+func (s *Server) handleScrapeBook(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		URL string `json:"url"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.URL == "" {
+		jsonError(w, http.StatusBadRequest, `request body must be JSON with "url" field`)
+		return
+	}
+	taskID, err := s.deps.Producer.CreateScrapeTask(r.Context(), "book", body.URL, 0, 0)
+	if err != nil {
+		s.deps.Log.Error("handleScrapeBook: CreateScrapeTask failed", "err", err)
+		jsonError(w, http.StatusInternalServerError, "failed to create task")
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]string{"task_id": taskID, "status": "accepted"})
+}
+
+// handleScrapeBookRange handles POST /scrape/book/range.
+// Body: {"url": "...", "from": N, "to": M}
+func (s *Server) handleScrapeBookRange(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		URL  string `json:"url"`
+		From int    `json:"from"`
+		To   int    `json:"to"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.URL == "" {
+		jsonError(w, http.StatusBadRequest, `request body must be JSON with "url" field`)
+		return
+	}
+	taskID, err := s.deps.Producer.CreateScrapeTask(r.Context(), "book_range", body.URL, body.From, body.To)
+	if err != nil {
+		s.deps.Log.Error("handleScrapeBookRange: CreateScrapeTask failed", "err", err)
+		jsonError(w, http.StatusInternalServerError, "failed to create task")
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]string{"task_id": taskID, "status": "accepted"})
+}
+
+// handleCancelTask handles POST /api/cancel-task/{id}.
+// Transitions a pending task (scrape or audio) to status=cancelled.
+// Returns 404 if the task does not exist, 409 if it cannot be cancelled
+// (e.g. already running/done).
+func (s *Server) handleCancelTask(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	if id == "" {
+		jsonError(w, http.StatusBadRequest, "missing task id")
+		return
+	}
+	if err := s.deps.Producer.CancelTask(r.Context(), id); err != nil {
+		s.deps.Log.Warn("handleCancelTask: CancelTask failed", "id", id, "err", err)
+		jsonError(w, http.StatusConflict, "could not cancel task: "+err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "cancelled", "id": id})
+}
+
+// ── Scrape task status / history ───────────────────────────────────────────────
+
+// handleScrapeStatus handles GET /api/scrape/status.
+// Returns the most recent scrape task status (or {"running":false} if none).
+func (s *Server) handleScrapeStatus(w http.ResponseWriter, r *http.Request) {
+	tasks, err := s.deps.TaskReader.ListScrapeTasks(r.Context())
+	if err != nil {
+		s.deps.Log.Error("handleScrapeStatus: ListScrapeTasks failed", "err", err)
+		writeJSON(w, 0, map[string]bool{"running": false})
+		return
+	}
+	running := false
+	for _, t := range tasks {
+		if t.Status == domain.TaskStatusRunning || t.Status == domain.TaskStatusPending {
+			running = true
+			break
+		}
+	}
+	writeJSON(w, 0, map[string]bool{"running": running})
+}
+
+// handleScrapeTasks handles GET /api/scrape/tasks.
+// Returns all scrape task records from PocketBase, newest first.
+func (s *Server) handleScrapeTasks(w http.ResponseWriter, r *http.Request) {
+	tasks, err := s.deps.TaskReader.ListScrapeTasks(r.Context())
+	if err != nil {
+		s.deps.Log.Error("handleScrapeTasks: ListScrapeTasks failed", "err", err)
+		jsonError(w, http.StatusInternalServerError, "failed to list tasks")
+		return
+	}
+	if tasks == nil {
+		tasks = []domain.ScrapeTask{}
+	}
+	writeJSON(w, 0, tasks)
+}
+
+// ── Browse & search ────────────────────────────────────────────────────────────
+
+// NovelListing represents a single novel entry from the novelfire browse/search page.
+type NovelListing struct {
+	Slug     string `json:"slug"`
+	Title    string `json:"title"`
+	Cover    string `json:"cover"`
+	Rank     string `json:"rank"`
+	Rating   string `json:"rating"`
+	Chapters string `json:"chapters"`
+	URL      string `json:"url"`
+}
+
+// handleBrowse handles GET /api/browse.
+// Fetches novelfire.net live (no MinIO cache in the new backend).
+// Query params: page (default 1), genre (default "all"), sort (default "popular"),
+// status (default "all"), type (default "all-novel")
+func (s *Server) handleBrowse(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query()
+	page := q.Get("page")
+	if page == "" {
+		page = "1"
+	}
+	genre := q.Get("genre")
+	if genre == "" {
+		genre = "all"
+	}
+	sortBy := q.Get("sort")
+	if sortBy == "" {
+		sortBy = "popular"
+	}
+	status := q.Get("status")
+	if status == "" {
+		status = "all"
+	}
+	novelType := q.Get("type")
+	if novelType == "" {
+		novelType = "all-novel"
+	}
+
+	pageNum, _ := strconv.Atoi(page)
+	if pageNum <= 0 {
+		pageNum = 1
+	}
+
+	targetURL := fmt.Sprintf("%s/genre-%s/sort-%s/status-%s/%s?page=%d",
+		novelFireBase, genre, sortBy, status, novelType, pageNum)
+
+	ctx, cancel := context.WithTimeout(r.Context(), 45*time.Second)
+	defer cancel()
+
+	novels, hasNext, err := s.fetchBrowsePage(ctx, targetURL)
+	if err != nil {
+		s.deps.Log.Error("handleBrowse: fetch failed", "url", targetURL, "err", err)
+		jsonError(w, http.StatusBadGateway, err.Error())
+		return
+	}
+
+	w.Header().Set("Cache-Control", "public, max-age=300")
+	writeJSON(w, 0, map[string]any{
+		"novels":  novels,
+		"page":    pageNum,
+		"hasNext": hasNext,
+	})
+}
+
+// handleSearch handles GET /api/search.
+// Query params: q (min 2 chars), source ("local"|"remote"|"all", default "all")
+func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query().Get("q")
+	if len([]rune(q)) < 2 {
+		jsonError(w, http.StatusBadRequest, "query must be at least 2 characters")
+		return
+	}
+
+	source := r.URL.Query().Get("source")
+	if source == "" {
+		source = "all"
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 20*time.Second)
+	defer cancel()
+
+	var localResults, remoteResults []NovelListing
+
+	// Local search (PocketBase books)
+	if source == "local" || source == "all" {
+		books, err := s.deps.BookReader.ListBooks(ctx)
+		if err != nil {
+			s.deps.Log.Warn("search: ListBooks failed", "err", err)
+		} else {
+			qLower := strings.ToLower(q)
+			for _, b := range books {
+				if strings.Contains(strings.ToLower(b.Title), qLower) ||
+					strings.Contains(strings.ToLower(b.Author), qLower) {
+					localResults = append(localResults, NovelListing{
+						Slug:  b.Slug,
+						Title: b.Title,
+						Cover: b.Cover,
+						URL:   b.SourceURL,
+					})
+				}
+			}
+		}
+	}
+
+	// Remote search (novelfire.net)
+	if source == "remote" || source == "all" {
+		searchURL := novelFireBase + "/search?keyword=" + url.QueryEscape(q)
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, searchURL, nil)
+		if err == nil {
+			req.Header.Set("User-Agent", "Mozilla/5.0 (compatible; libnovel-backend/2)")
+			req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
+			if resp, fetchErr := http.DefaultClient.Do(req); fetchErr == nil {
+				defer resp.Body.Close()
+				if resp.StatusCode == http.StatusOK {
+					parsed, _ := parseBrowsePage(resp.Body)
+					remoteResults = parsed
+				}
+			}
+		}
+	}
+
+	// Merge: local first, de-duplicate remote
+	localSlugs := make(map[string]bool, len(localResults))
+	for _, item := range localResults {
+		localSlugs[item.Slug] = true
+	}
+	combined := make([]NovelListing, 0, len(localResults)+len(remoteResults))
+	combined = append(combined, localResults...)
+	for _, item := range remoteResults {
+		if !localSlugs[item.Slug] {
+			combined = append(combined, item)
+		}
+	}
+
+	writeJSON(w, 0, map[string]any{
+		"results":      combined,
+		"local_count":  len(localResults),
+		"remote_count": len(remoteResults),
+	})
+}
+
+// ── Ranking ────────────────────────────────────────────────────────────────────
+
+// handleGetRanking handles GET /api/ranking.
+// Returns all ranking items sorted by rank ascending.
+func (s *Server) handleGetRanking(w http.ResponseWriter, r *http.Request) {
+	items, err := s.deps.RankingStore.ReadRankingItems(r.Context())
+	if err != nil {
+		s.deps.Log.Error("handleGetRanking: ReadRankingItems failed", "err", err)
+		jsonError(w, http.StatusInternalServerError, "failed to read ranking")
+		return
+	}
+	if items == nil {
+		items = []domain.RankingItem{}
+	}
+	writeJSON(w, 0, items)
+}
+
+// handleGetCover handles GET /api/cover/{domain}/{slug}.
+// The new backend does not cache covers in MinIO. Instead it redirects the
+// client to the novelfire.net source URL. The domain path segment is kept for
+// API compatibility with the old scraper.
+func (s *Server) handleGetCover(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	if slug == "" {
+		http.Error(w, "missing slug", http.StatusBadRequest)
+		return
+	}
+	// Redirect to the standard novelfire cover CDN URL. If the caller has the
+	// actual cover URL stored in metadata they should use it directly; this
+	// endpoint is a best-effort fallback.
+	coverURL := fmt.Sprintf("https://cdn.novelfire.net/covers/%s.jpg", slug)
+	http.Redirect(w, r, coverURL, http.StatusFound)
+}
+
+// ── Preview (live scrape, no store writes) ─────────────────────────────────────
+
+// handleBookPreview handles GET /api/book-preview/{slug}.
+//
+// If the book is already in the library (PocketBase), returns its metadata and
+// chapter index immediately (200).
+//
+// If the book is not yet in the library, enqueues a "book" scrape task and
+// returns 202 Accepted with the task_id. The runner will scrape the book
+// asynchronously; the client should poll GET /api/scrape/status or
+// GET /api/scrape/tasks to detect completion, then re-request this endpoint.
+//
+// The backend never scrapes directly — all scraping is the runner's job.
+func (s *Server) handleBookPreview(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	if slug == "" {
+		jsonError(w, http.StatusBadRequest, "missing slug")
+		return
+	}
+
+	ctx := r.Context()
+
+	meta, inLib, err := s.deps.BookReader.ReadMetadata(ctx, slug)
+	if err != nil {
+		s.deps.Log.Warn("book-preview: ReadMetadata failed", "slug", slug, "err", err)
+		inLib = false
+	}
+
+	if inLib {
+		// Fast path: book is already scraped — return stored data.
+		chapters, cerr := s.deps.BookReader.ListChapters(ctx, slug)
+		if cerr != nil {
+			s.deps.Log.Warn("book-preview: ListChapters failed", "slug", slug, "err", cerr)
+		}
+		writeJSON(w, 0, map[string]any{
+			"in_lib":   true,
+			"meta":     meta,
+			"chapters": chapters,
+		})
+		return
+	}
+
+	// Book not in library — enqueue a range scrape task for the first 20 chapters
+	// so the user can start reading quickly. Remaining chapters can be scraped
+	// later via the book detail page or the admin scrape panel.
+	bookURL := r.URL.Query().Get("source_url")
+	if bookURL == "" {
+		bookURL = fmt.Sprintf("%s/book/%s", novelFireBase, slug)
+	}
+
+	const previewFrom, previewTo = 1, 20
+	taskID, err := s.deps.Producer.CreateScrapeTask(ctx, "book_range", bookURL, previewFrom, previewTo)
+	if err != nil {
+		s.deps.Log.Error("book-preview: CreateScrapeTask failed", "slug", slug, "err", err)
+		jsonError(w, http.StatusInternalServerError, "failed to enqueue scrape task")
+		return
+	}
+
+	s.deps.Log.Info("book-preview: enqueued range scrape task", "slug", slug, "task_id", taskID,
+		"from", previewFrom, "to", previewTo)
+	writeJSON(w, http.StatusAccepted, map[string]any{
+		"in_lib":  false,
+		"task_id": taskID,
+		"message": fmt.Sprintf("scraping first %d chapters; poll /api/scrape/tasks for completion", previewTo),
+	})
+}
+
+// ── Chapter text ───────────────────────────────────────────────────────────────
+
+// handleChapterText handles GET /api/chapter-text/{slug}/{n}.
+// Returns plain text (markdown stripped) of a stored chapter.
+func (s *Server) handleChapterText(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	n, err := strconv.Atoi(r.PathValue("n"))
+	if err != nil || n < 1 {
+		http.NotFound(w, r)
+		return
+	}
+	raw, err := s.deps.BookReader.ReadChapter(r.Context(), slug, n)
+	if err != nil {
+		http.NotFound(w, r)
+		return
+	}
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	fmt.Fprint(w, stripMarkdown(raw))
+}
+
+// handleChapterMarkdown handles GET /api/chapter-markdown/{slug}/{n}.
+//
+// Returns the raw markdown content of a stored chapter directly from MinIO.
+// This is used by the SvelteKit UI as a simpler alternative to presign+fetch:
+// it avoids the need for the SvelteKit server to reach MinIO directly, and
+// gives a clean 404 when the chapter has not been scraped yet.
+func (s *Server) handleChapterMarkdown(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	n, err := strconv.Atoi(r.PathValue("n"))
+	if err != nil || n < 1 || slug == "" {
+		http.Error(w, `{"error":"invalid params"}`, http.StatusBadRequest)
+		return
+	}
+	raw, err := s.deps.BookReader.ReadChapter(r.Context(), slug, n)
+	if err != nil {
+		s.deps.Log.Warn("chapter-markdown: not found in MinIO", "slug", slug, "n", n, "err", err)
+		http.Error(w, `{"error":"chapter not found"}`, http.StatusNotFound)
+		return
+	}
+	w.Header().Set("Content-Type", "text/markdown; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	fmt.Fprint(w, raw)
+}
+
+// handleReindex handles POST /api/reindex/{slug}.
+// Rebuilds the chapters_idx PocketBase collection for a book from MinIO objects.
+func (s *Server) handleReindex(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	if slug == "" {
+		jsonError(w, http.StatusBadRequest, "missing slug")
+		return
+	}
+
+	count, err := s.deps.BookReader.ReindexChapters(r.Context(), slug)
+	if err != nil {
+		s.deps.Log.Error("reindex failed", "slug", slug, "indexed", count, "err", err)
+		writeJSON(w, http.StatusInternalServerError, map[string]any{
+			"error":   err.Error(),
+			"indexed": count,
+		})
+		return
+	}
+
+	s.deps.Log.Info("reindex complete", "slug", slug, "indexed", count)
+	writeJSON(w, 0, map[string]any{"slug": slug, "indexed": count})
+}
+
+// ── Audio ──────────────────────────────────────────────────────────────────────
+
+// handleAudioGenerate handles POST /api/audio/{slug}/{n}.
+// Creates an audio_jobs task in PocketBase (runner executes asynchronously).
+// Returns 200 immediately if audio already exists in MinIO.
+// Returns 202 with the task_id if a new task was created.
+func (s *Server) handleAudioGenerate(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	n, err := strconv.Atoi(r.PathValue("n"))
+	if err != nil || n < 1 {
+		jsonError(w, http.StatusBadRequest, "invalid chapter")
+		return
+	}
+
+	voice := s.cfg.DefaultVoice
+	var body struct {
+		Voice string `json:"voice"`
+	}
+	if r.Body != nil {
+		_ = json.NewDecoder(r.Body).Decode(&body)
+	}
+	if body.Voice != "" {
+		voice = body.Voice
+	}
+
+	cacheKey := fmt.Sprintf("%s/%d/%s", slug, n, voice)
+
+	// Fast path: audio already in MinIO
+	audioKey := s.deps.AudioStore.AudioObjectKey(slug, n, voice)
+	if s.deps.AudioStore.AudioExists(r.Context(), audioKey) {
+		proxyURL := fmt.Sprintf("/api/audio-proxy/%s/%d?voice=%s", slug, n, voice)
+		writeJSON(w, 0, map[string]string{"url": proxyURL, "status": "done"})
+		return
+	}
+
+	// Check if a task is already pending/running
+	task, found, _ := s.deps.TaskReader.GetAudioTask(r.Context(), cacheKey)
+	if found && (task.Status == domain.TaskStatusPending || task.Status == domain.TaskStatusRunning) {
+		writeJSON(w, http.StatusAccepted, map[string]string{
+			"task_id": task.ID,
+			"status":  string(task.Status),
+		})
+		return
+	}
+
+	// Create a new audio task
+	taskID, err := s.deps.Producer.CreateAudioTask(r.Context(), slug, n, voice)
+	if err != nil {
+		s.deps.Log.Error("handleAudioGenerate: CreateAudioTask failed", "err", err)
+		jsonError(w, http.StatusInternalServerError, "failed to create audio task")
+		return
+	}
+
+	writeJSON(w, http.StatusAccepted, map[string]string{
+		"task_id": taskID,
+		"status":  "pending",
+	})
+}
+
+// handleAudioStatus handles GET /api/audio/status/{slug}/{n}.
+// Polls PocketBase for the audio task status.
+// Query params: voice (optional, defaults to DefaultVoice)
+func (s *Server) handleAudioStatus(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	n, err := strconv.Atoi(r.PathValue("n"))
+	if err != nil || n < 1 || slug == "" {
+		jsonError(w, http.StatusBadRequest, "invalid params")
+		return
+	}
+
+	voice := r.URL.Query().Get("voice")
+	if voice == "" {
+		voice = s.cfg.DefaultVoice
+	}
+
+	// Fast path: audio exists in MinIO
+	audioKey := s.deps.AudioStore.AudioObjectKey(slug, n, voice)
+	if s.deps.AudioStore.AudioExists(r.Context(), audioKey) {
+		proxyURL := fmt.Sprintf("/api/audio-proxy/%s/%d?voice=%s", slug, n, voice)
+		writeJSON(w, 0, map[string]string{
+			"status": "done",
+			"url":    proxyURL,
+		})
+		return
+	}
+
+	cacheKey := fmt.Sprintf("%s/%d/%s", slug, n, voice)
+	task, found, _ := s.deps.TaskReader.GetAudioTask(r.Context(), cacheKey)
+	if !found {
+		writeJSON(w, 0, map[string]string{"status": "idle"})
+		return
+	}
+
+	resp := map[string]string{
+		"status":  string(task.Status),
+		"task_id": task.ID,
+	}
+	if task.Status == domain.TaskStatusFailed && task.ErrorMessage != "" {
+		resp["error"] = task.ErrorMessage
+	}
+	writeJSON(w, 0, resp)
+}
+
+// handleAudioProxy handles GET /api/audio-proxy/{slug}/{n}.
+// Redirects to a presigned MinIO URL for the generated audio object.
+// Query params: voice (optional, defaults to DefaultVoice)
+func (s *Server) handleAudioProxy(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	n, err := strconv.Atoi(r.PathValue("n"))
+	if err != nil || n < 1 {
+		http.NotFound(w, r)
+		return
+	}
+
+	voice := r.URL.Query().Get("voice")
+	if voice == "" {
+		voice = s.cfg.DefaultVoice
+	}
+
+	audioKey := s.deps.AudioStore.AudioObjectKey(slug, n, voice)
+	if !s.deps.AudioStore.AudioExists(r.Context(), audioKey) {
+		http.Error(w, "audio not generated yet", http.StatusNotFound)
+		return
+	}
+
+	presignURL, err := s.deps.PresignStore.PresignAudio(r.Context(), audioKey, 1*time.Hour)
+	if err != nil {
+		s.deps.Log.Error("handleAudioProxy: PresignAudio failed", "slug", slug, "n", n, "err", err)
+		http.Error(w, "presign failed", http.StatusInternalServerError)
+		return
+	}
+
+	http.Redirect(w, r, presignURL, http.StatusFound)
+}
+
+// ── Voices ─────────────────────────────────────────────────────────────────────
+
+// handleVoices handles GET /api/voices.
+// Returns {"voices": [...]} — fetched from Kokoro with built-in fallback.
+func (s *Server) handleVoices(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, 0, map[string]any{"voices": s.voices(r.Context())})
+}
+
+// ── Presigned URLs ─────────────────────────────────────────────────────────────
+
+// handlePresignChapter handles GET /api/presign/chapter/{slug}/{n}.
+func (s *Server) handlePresignChapter(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	n, err := strconv.Atoi(r.PathValue("n"))
+	if err != nil || n < 1 || slug == "" {
+		jsonError(w, http.StatusBadRequest, "invalid params")
+		return
+	}
+
+	u, err := s.deps.PresignStore.PresignChapter(r.Context(), slug, n, 15*time.Minute)
+	if err != nil {
+		s.deps.Log.Error("presign chapter failed", "slug", slug, "n", n, "err", err)
+		jsonError(w, http.StatusInternalServerError, "presign failed")
+		return
+	}
+	writeJSON(w, 0, map[string]string{"url": u})
+}
+
+// handlePresignAudio handles GET /api/presign/audio/{slug}/{n}.
+// Query params: voice (optional)
+func (s *Server) handlePresignAudio(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	n, err := strconv.Atoi(r.PathValue("n"))
+	if err != nil || n < 1 || slug == "" {
+		jsonError(w, http.StatusBadRequest, "invalid params")
+		return
+	}
+
+	voice := r.URL.Query().Get("voice")
+	if voice == "" {
+		voice = s.cfg.DefaultVoice
+	}
+
+	key := s.deps.AudioStore.AudioObjectKey(slug, n, voice)
+	if !s.deps.AudioStore.AudioExists(r.Context(), key) {
+		http.NotFound(w, r)
+		return
+	}
+
+	u, err := s.deps.PresignStore.PresignAudio(r.Context(), key, 1*time.Hour)
+	if err != nil {
+		s.deps.Log.Error("presign audio failed", "slug", slug, "n", n, "err", err)
+		jsonError(w, http.StatusInternalServerError, "presign failed")
+		return
+	}
+	writeJSON(w, 0, map[string]string{"url": u})
+}
+
+// handlePresignVoiceSample handles GET /api/presign/voice-sample/{voice}.
+func (s *Server) handlePresignVoiceSample(w http.ResponseWriter, r *http.Request) {
+	voice := r.PathValue("voice")
+	if voice == "" {
+		jsonError(w, http.StatusBadRequest, "missing voice")
+		return
+	}
+
+	key := kokoro.VoiceSampleKey(voice)
+	if !s.deps.AudioStore.AudioExists(r.Context(), key) {
+		http.NotFound(w, r)
+		return
+	}
+
+	u, err := s.deps.PresignStore.PresignAudio(r.Context(), key, 1*time.Hour)
+	if err != nil {
+		s.deps.Log.Error("presign voice sample failed", "voice", voice, "err", err)
+		jsonError(w, http.StatusInternalServerError, "presign failed")
+		return
+	}
+	writeJSON(w, 0, map[string]string{"url": u})
+}
+
+// handlePresignAvatarUpload handles GET /api/presign/avatar-upload/{userId}.
+// Query params: ext (jpg|png|webp, defaults to jpg)
+func (s *Server) handlePresignAvatarUpload(w http.ResponseWriter, r *http.Request) {
+	userID := r.PathValue("userId")
+	if userID == "" {
+		jsonError(w, http.StatusBadRequest, "missing userId")
+		return
+	}
+
+	ext := r.URL.Query().Get("ext")
+	switch ext {
+	case "jpg", "jpeg":
+		ext = "jpg"
+	case "png":
+		ext = "png"
+	case "webp":
+		ext = "webp"
+	default:
+		ext = "jpg"
+	}
+
+	uploadURL, key, err := s.deps.PresignStore.PresignAvatarUpload(r.Context(), userID, ext)
+	if err != nil {
+		s.deps.Log.Error("presign avatar upload failed", "userId", userID, "err", err)
+		jsonError(w, http.StatusInternalServerError, "presign failed")
+		return
+	}
+	writeJSON(w, 0, map[string]string{"upload_url": uploadURL, "key": key})
+}
+
+// handlePresignAvatar handles GET /api/presign/avatar/{userId}.
+func (s *Server) handlePresignAvatar(w http.ResponseWriter, r *http.Request) {
+	userID := r.PathValue("userId")
+	if userID == "" {
+		jsonError(w, http.StatusBadRequest, "missing userId")
+		return
+	}
+
+	u, found, err := s.deps.PresignStore.PresignAvatarURL(r.Context(), userID)
+	if err != nil {
+		s.deps.Log.Error("presign avatar failed", "userId", userID, "err", err)
+		jsonError(w, http.StatusInternalServerError, "presign failed")
+		return
+	}
+	if !found {
+		http.NotFound(w, r)
+		return
+	}
+	writeJSON(w, 0, map[string]string{"url": u})
+}
+
+// ── Progress ───────────────────────────────────────────────────────────────────
+
+// handleGetProgress handles GET /api/progress.
+// Returns {"slug": chapterNum, "slug_ts": timestampMs, ...}
+func (s *Server) handleGetProgress(w http.ResponseWriter, r *http.Request) {
+	sid := ensureSession(w, r)
+	entries, err := s.deps.ProgressStore.AllProgress(r.Context(), sid)
+	if err != nil {
+		s.deps.Log.Error("AllProgress failed", "err", err)
+		entries = nil
+	}
+
+	progress := make(map[string]any, len(entries)*2)
+	for _, p := range entries {
+		progress[p.Slug] = p.Chapter
+		progress[p.Slug+"_ts"] = p.UpdatedAt.UnixMilli()
+	}
+	writeJSON(w, 0, progress)
+}
+
+// handleSetProgress handles POST /api/progress/{slug}.
+// Body: {"chapter": N}
+func (s *Server) handleSetProgress(w http.ResponseWriter, r *http.Request) {
+	sid := ensureSession(w, r)
+	slug := r.PathValue("slug")
+	if slug == "" {
+		jsonError(w, http.StatusBadRequest, "missing slug")
+		return
+	}
+
+	var body struct {
+		Chapter int `json:"chapter"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.Chapter < 1 {
+		jsonError(w, http.StatusBadRequest, "invalid body")
+		return
+	}
+
+	p := domain.ReadingProgress{
+		Slug:      slug,
+		Chapter:   body.Chapter,
+		UpdatedAt: time.Now(),
+	}
+	if err := s.deps.ProgressStore.SetProgress(r.Context(), sid, p); err != nil {
+		s.deps.Log.Error("SetProgress failed", "slug", slug, "err", err)
+		jsonError(w, http.StatusInternalServerError, "store error")
+		return
+	}
+	writeJSON(w, 0, map[string]string{})
+}
+
+// handleDeleteProgress handles DELETE /api/progress/{slug}.
+func (s *Server) handleDeleteProgress(w http.ResponseWriter, r *http.Request) {
+	sid := ensureSession(w, r)
+	slug := r.PathValue("slug")
+	if slug == "" {
+		jsonError(w, http.StatusBadRequest, "missing slug")
+		return
+	}
+
+	if err := s.deps.ProgressStore.DeleteProgress(r.Context(), sid, slug); err != nil {
+		s.deps.Log.Error("DeleteProgress failed", "slug", slug, "err", err)
+		// non-fatal
+	}
+	writeJSON(w, 0, map[string]string{})
+}
+
+// ── Browse page parsing helpers ────────────────────────────────────────────────
+
+// fetchBrowsePage fetches pageURL and parses NovelListings from the HTML.
+func (s *Server) fetchBrowsePage(ctx context.Context, pageURL string) ([]NovelListing, bool, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, pageURL, nil)
+	if err != nil {
+		return nil, false, fmt.Errorf("build request: %w", err)
+	}
+	req.Header.Set("User-Agent", "Mozilla/5.0 (compatible; libnovel-backend/2)")
+	req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
+	req.Header.Set("Accept-Language", "en-US,en;q=0.9")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, false, fmt.Errorf("fetch %s: %w", pageURL, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		_, _ = io.Copy(io.Discard, resp.Body)
+		return nil, false, fmt.Errorf("upstream returned %d", resp.StatusCode)
+	}
+
+	novels, hasNext := parseBrowsePage(resp.Body)
+	return novels, hasNext, nil
+}
+
+// parseBrowsePage parses a novelfire HTML body and returns novel listings.
+// It uses a simple string-scanning approach to avoid importing golang.org/x/net/html
+// in this package (that dependency is only in internal/novelfire).
+func parseBrowsePage(r io.Reader) ([]NovelListing, bool) {
+	data, err := io.ReadAll(r)
+	if err != nil {
+		return nil, false
+	}
+	body := string(data)
+
+	var novels []NovelListing
+	hasNext := false
+
+	// Detect "next page" link
+	if strings.Contains(body, `rel="next"`) ||
+		strings.Contains(body, `aria-label="Next"`) ||
+		strings.Contains(body, `class="next"`) {
+		hasNext = true
+	}
+
+	// Extract novel slugs and titles using simple regex patterns.
+	// novelfire.net novel items: <li class="novel-item">...</li>
+	// Each contains an anchor like <a href="/book/{slug}">
+	slugRe := regexp.MustCompile(`href="/book/([^/"]+)"`)
+	titleRe := regexp.MustCompile(`class="novel-title[^"]*"[^>]*>([^<]+)<`)
+	coverRe := regexp.MustCompile(`data-src="(https?://[^"]+)"`)
+
+	slugMatches := slugRe.FindAllStringSubmatch(body, -1)
+	titleMatches := titleRe.FindAllStringSubmatch(body, -1)
+	coverMatches := coverRe.FindAllStringSubmatch(body, -1)
+
+	seen := make(map[string]bool)
+	for i, sm := range slugMatches {
+		slug := sm[1]
+		if seen[slug] {
+			continue
+		}
+		seen[slug] = true
+
+		novel := NovelListing{
+			Slug: slug,
+			URL:  novelFireBase + "/book/" + slug,
+		}
+		if i < len(titleMatches) {
+			novel.Title = strings.TrimSpace(titleMatches[i][1])
+		}
+		if i < len(coverMatches) {
+			novel.Cover = coverMatches[i][1]
+		}
+		if novel.Title != "" {
+			novels = append(novels, novel)
+		}
+	}
+
+	return novels, hasNext
+}
+
+// ── Markdown stripping ─────────────────────────────────────────────────────────
+
+// stripMarkdown removes common markdown syntax from src, returning plain text.
+func stripMarkdown(src string) string {
+	src = regexp.MustCompile(`(?m)^#{1,6}\s+`).ReplaceAllString(src, "")
+	src = regexp.MustCompile(`\*{1,3}|_{1,3}`).ReplaceAllString(src, "")
+	src = regexp.MustCompile("(?s)```.*?```").ReplaceAllString(src, "")
+	src = regexp.MustCompile("`[^`]*`").ReplaceAllString(src, "")
+	src = regexp.MustCompile(`\[([^\]]+)\]\([^)]+\)`).ReplaceAllString(src, "$1")
+	src = regexp.MustCompile(`!\[[^\]]*\]\([^)]+\)`).ReplaceAllString(src, "")
+	src = regexp.MustCompile(`(?m)^>\s?`).ReplaceAllString(src, "")
+	src = regexp.MustCompile(`(?m)^[-*_]{3,}\s*$`).ReplaceAllString(src, "")
+	src = regexp.MustCompile(`\n{3,}`).ReplaceAllString(src, "\n\n")
+	return strings.TrimSpace(src)
+}
+
+// ── Hardcoded Kokoro voice fallback ───────────────────────────────────────────
+
+// kokoroVoices is the built-in fallback list used when the Kokoro service is
+// unavailable. Matches the list in the old scraper helpers.go.
+var kokoroVoices = []string{
+	// American English
+	"af_alloy", "af_aoede", "af_bella", "af_heart", "af_jadzia",
+	"af_jessica", "af_kore", "af_nicole", "af_nova", "af_river",
+	"af_sarah", "af_sky",
+	"am_adam", "am_echo", "am_eric", "am_fenrir", "am_liam",
+	"am_michael", "am_onyx", "am_puck",
+	// British English
+	"bf_alice", "bf_emma", "bf_lily",
+	"bm_daniel", "bm_fable", "bm_george", "bm_lewis",
+	// Spanish
+	"ef_dora", "em_alex",
+	// French
+	"ff_siwis",
+	// Hindi
+	"hf_alpha", "hf_beta", "hm_omega", "hm_psi",
+	// Italian
+	"if_sara", "im_nicola",
+	// Japanese
+	"jf_alpha", "jf_gongitsune", "jf_nezumi", "jf_tebukuro", "jm_kumo",
+	// Portuguese
+	"pf_dora", "pm_alex",
+	// Chinese
+	"zf_xiaobei", "zf_xiaoni", "zf_xiaoxiao", "zf_xiaoyi",
+	"zm_yunjian", "zm_yunxi", "zm_yunxia", "zm_yunyang",
+}

backend/internal/backend/server.go

@@ -0,0 +1,285 @@
+// Package backend implements the HTTP API server for the LibNovel backend.
+//
+// The server exposes all endpoints consumed by the SvelteKit UI:
+//   - Book/chapter reads from PocketBase/MinIO via bookstore interfaces
+//   - Task creation (scrape + audio) via taskqueue.Producer — the runner binary
+//     picks up and executes those tasks asynchronously
+//   - Presigned MinIO URLs for media playback/upload
+//   - Session-scoped reading progress
+//   - Live novelfire.net browse/search (no scraper interface needed; direct HTTP)
+//   - Kokoro voice list
+//
+// The backend never scrapes directly. All scraping (metadata, chapter list,
+// chapter text, audio TTS) is delegated to the runner binary via PocketBase
+// task records. GET /api/book-preview enqueues a task when the book is absent.
+//
+// All external dependencies are injected as interfaces; concrete types live in
+// internal/storage and are wired by cmd/backend/main.go.
+package backend
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/libnovel/backend/internal/bookstore"
+	"github.com/libnovel/backend/internal/kokoro"
+	"github.com/libnovel/backend/internal/taskqueue"
+)
+
+// Dependencies holds all external services the backend server depends on.
+// Every field is an interface so test doubles can be injected freely.
+type Dependencies struct {
+	// BookReader reads book metadata and chapter text from PocketBase/MinIO.
+	BookReader bookstore.BookReader
+	// RankingStore reads ranking data from PocketBase.
+	RankingStore bookstore.RankingStore
+	// AudioStore checks audio object existence and computes MinIO keys.
+	AudioStore bookstore.AudioStore
+	// PresignStore generates short-lived MinIO URLs.
+	PresignStore bookstore.PresignStore
+	// ProgressStore reads/writes per-session reading progress.
+	ProgressStore bookstore.ProgressStore
+	// Producer creates scrape/audio tasks in PocketBase.
+	Producer taskqueue.Producer
+	// TaskReader reads scrape/audio task records from PocketBase.
+	TaskReader taskqueue.Reader
+	// Kokoro is the TTS client (used for voice list only in the backend;
+	// audio generation is done by the runner).
+	Kokoro kokoro.Client
+	// Log is the structured logger.
+	Log *slog.Logger
+}
+
+// Config holds HTTP server tuning parameters.
+type Config struct {
+	// Addr is the listen address, e.g. ":8080".
+	Addr string
+	// DefaultVoice is used when no voice is specified in audio requests.
+	DefaultVoice string
+	// Version and Commit are embedded in /health and /api/version responses.
+	Version string
+	Commit  string
+}
+
+// Server is the HTTP API server.
+type Server struct {
+	cfg  Config
+	deps Dependencies
+
+	// voiceMu guards cachedVoices. Populated lazily on first GET /api/voices.
+	voiceMu      sync.RWMutex
+	cachedVoices []string
+}
+
+// New creates a Server from cfg and deps.
+func New(cfg Config, deps Dependencies) *Server {
+	if cfg.DefaultVoice == "" {
+		cfg.DefaultVoice = "af_bella"
+	}
+	if deps.Log == nil {
+		deps.Log = slog.Default()
+	}
+	return &Server{cfg: cfg, deps: deps}
+}
+
+// ListenAndServe registers all routes and starts the HTTP server.
+// It blocks until ctx is cancelled, then performs a graceful shutdown.
+func (s *Server) ListenAndServe(ctx context.Context) error {
+	mux := http.NewServeMux()
+
+	// Health / version
+	mux.HandleFunc("GET /health", s.handleHealth)
+	mux.HandleFunc("GET /api/version", s.handleVersion)
+
+	// Scrape task creation (202 Accepted — runner executes asynchronously)
+	mux.HandleFunc("POST /scrape", s.handleScrapeCatalogue)
+	mux.HandleFunc("POST /scrape/book", s.handleScrapeBook)
+	mux.HandleFunc("POST /scrape/book/range", s.handleScrapeBookRange)
+
+	// Scrape task status / history
+	mux.HandleFunc("GET /api/scrape/status", s.handleScrapeStatus)
+	mux.HandleFunc("GET /api/scrape/tasks", s.handleScrapeTasks)
+
+	// Cancel a pending task (scrape or audio)
+	mux.HandleFunc("POST /api/cancel-task/{id}", s.handleCancelTask)
+
+	// Browse & search (live novelfire.net)
+	mux.HandleFunc("GET /api/browse", s.handleBrowse)
+	mux.HandleFunc("GET /api/search", s.handleSearch)
+
+	// Ranking (from PocketBase)
+	mux.HandleFunc("GET /api/ranking", s.handleGetRanking)
+
+	// Cover proxy (live URL redirect)
+	mux.HandleFunc("GET /api/cover/{domain}/{slug}", s.handleGetCover)
+
+	// Book preview (enqueues scrape task if not in library; returns stored data if already scraped)
+	mux.HandleFunc("GET /api/book-preview/{slug}", s.handleBookPreview)
+
+	// Chapter text (served from MinIO via PocketBase index)
+	mux.HandleFunc("GET /api/chapter-text/{slug}/{n}", s.handleChapterText)
+	// Raw markdown chapter content — served directly from MinIO by the backend.
+	// Use this instead of presign+fetch to avoid SvelteKit→MinIO network path.
+	mux.HandleFunc("GET /api/chapter-markdown/{slug}/{n}", s.handleChapterMarkdown)
+
+	// Reindex chapters_idx from MinIO
+	mux.HandleFunc("POST /api/reindex/{slug}", s.handleReindex)
+
+	// Audio task creation (backend creates task; runner executes)
+	mux.HandleFunc("POST /api/audio/{slug}/{n}", s.handleAudioGenerate)
+	mux.HandleFunc("GET /api/audio/status/{slug}/{n}", s.handleAudioStatus)
+	mux.HandleFunc("GET /api/audio-proxy/{slug}/{n}", s.handleAudioProxy)
+
+	// Voices list
+	mux.HandleFunc("GET /api/voices", s.handleVoices)
+
+	// Presigned URLs
+	mux.HandleFunc("GET /api/presign/chapter/{slug}/{n}", s.handlePresignChapter)
+	mux.HandleFunc("GET /api/presign/audio/{slug}/{n}", s.handlePresignAudio)
+	mux.HandleFunc("GET /api/presign/voice-sample/{voice}", s.handlePresignVoiceSample)
+	mux.HandleFunc("GET /api/presign/avatar-upload/{userId}", s.handlePresignAvatarUpload)
+	mux.HandleFunc("GET /api/presign/avatar/{userId}", s.handlePresignAvatar)
+
+	// Reading progress
+	mux.HandleFunc("GET /api/progress", s.handleGetProgress)
+	mux.HandleFunc("POST /api/progress/{slug}", s.handleSetProgress)
+	mux.HandleFunc("DELETE /api/progress/{slug}", s.handleDeleteProgress)
+
+	srv := &http.Server{
+		Addr:         s.cfg.Addr,
+		Handler:      mux,
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 60 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	errCh := make(chan error, 1)
+	go func() { errCh <- srv.ListenAndServe() }()
+	s.deps.Log.Info("backend: HTTP server listening", "addr", s.cfg.Addr)
+
+	select {
+	case <-ctx.Done():
+		s.deps.Log.Info("backend: context cancelled, starting graceful shutdown")
+		shutCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		if err := srv.Shutdown(shutCtx); err != nil {
+			s.deps.Log.Error("backend: graceful shutdown failed", "err", err)
+			return err
+		}
+		s.deps.Log.Info("backend: shutdown complete")
+		return nil
+	case err := <-errCh:
+		return err
+	}
+}
+
+// ── Session cookie helpers ─────────────────────────────────────────────────────
+
+const sessionCookieName = "libnovel_session"
+
+func sessionID(r *http.Request) string {
+	c, err := r.Cookie(sessionCookieName)
+	if err != nil {
+		return ""
+	}
+	return c.Value
+}
+
+func newSessionID() (string, error) {
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}
+
+func ensureSession(w http.ResponseWriter, r *http.Request) string {
+	if id := sessionID(r); id != "" {
+		return id
+	}
+	id, err := newSessionID()
+	if err != nil {
+		id = fmt.Sprintf("fallback-%d", time.Now().UnixNano())
+	}
+	http.SetCookie(w, &http.Cookie{
+		Name:     sessionCookieName,
+		Value:    id,
+		Path:     "/",
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		MaxAge:   365 * 24 * 60 * 60,
+	})
+	return id
+}
+
+// ── Utility helpers ────────────────────────────────────────────────────────────
+
+// writeJSON writes v as a JSON response with status code. Status 0 → 200.
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	if status != 0 {
+		w.WriteHeader(status)
+	}
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+// jsonError writes a JSON error body and the given status code.
+func jsonError(w http.ResponseWriter, status int, msg string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(map[string]string{"error": msg})
+}
+
+// voices returns the list of available Kokoro voices. On the first call it
+// fetches from the Kokoro service and caches the result. Falls back to the
+// hardcoded list on error.
+func (s *Server) voices(ctx context.Context) []string {
+	s.voiceMu.RLock()
+	cached := s.cachedVoices
+	s.voiceMu.RUnlock()
+	if len(cached) > 0 {
+		return cached
+	}
+
+	if s.deps.Kokoro == nil {
+		return kokoroVoices
+	}
+
+	fetchCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	list, err := s.deps.Kokoro.ListVoices(fetchCtx)
+	if err != nil || len(list) == 0 {
+		s.deps.Log.Warn("backend: could not fetch kokoro voices, using built-in list", "err", err)
+		return kokoroVoices
+	}
+
+	s.voiceMu.Lock()
+	s.cachedVoices = list
+	s.voiceMu.Unlock()
+	s.deps.Log.Info("backend: fetched kokoro voices", "count", len(list))
+	return list
+}
+
+// handleHealth handles GET /health.
+func (s *Server) handleHealth(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, 0, map[string]string{
+		"status":  "ok",
+		"version": s.cfg.Version,
+		"commit":  s.cfg.Commit,
+	})
+}
+
+// handleVersion handles GET /api/version.
+func (s *Server) handleVersion(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, 0, map[string]string{
+		"version": s.cfg.Version,
+		"commit":  s.cfg.Commit,
+	})
+}