Code-review follow-ups: httputil, validation caps, a11y

Backend:
- Extract shared internal/httputil (WriteJSON/ErrorJSON/BadRequest/
  ServerError); drop the triple-duplicated helpers in docs, suggestions,
  vocab. ServerError now logs the real error and returns a generic 500 so
  raw DB/internal errors never reach the client.
- vocab capture: validate doc_id ownership (blank -> none, unknown -> 400
  instead of a leaked FK 500); rune-safe clamp word/gloss/definition/
  phonetic/example.
- vocab review(): wrap the read-modify-write in a transaction (TOCTOU).
- /api request-size cap via MaxBytesReader middleware (2 MiB), exempting
  /api/images (own 10 MiB limit).

Frontend:
- StatusBar: drive the checking/voicing/collocating indicators from one
  array; llmDown uses !anyBusy.
- Slide-overs: new useFocusTrap hook (focus-in, Tab trap, focus-restore)
  on GardenPanel + HistoryPanel, both role=dialog/aria-modal/aria-label.
- speech.ts: export stopSpeech(); GardenPanel cancels audio on unmount.

Tests: add doc_id-validation and field-clamp coverage; full suite green.

Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd

internal/docs/handlers.go

@@ -13,6 +13,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 )
 
 // Handler holds the dependencies shared by every document route.
@@ -62,7 +63,7 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 		db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	defer rows.Close()
@@ -72,20 +73,20 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 	for rows.Next() {
 		var d docSummary
 		if err := rows.Scan(&d.ID, &d.Title, &d.WordCount, &d.UpdatedAt); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		out = append(out, d)
 		ids = append(ids, d.ID)
 	}
 	if err := rows.Err(); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	byDoc, err := h.tagsByDoc(ids)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	for i := range out {
@@ -94,7 +95,7 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 			out[i].Tags = []db.Tag{}
 		}
 	}
-	writeJSON(w, http.StatusOK, out)
+	httputil.WriteJSON(w, http.StatusOK, out)
 }
 
 // create inserts a fresh blank document and returns it in full.
@@ -109,10 +110,10 @@ func (h *Handler) create(w http.ResponseWriter, r *http.Request) {
 		&doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusCreated, doc)
+	httputil.WriteJSON(w, http.StatusCreated, doc)
 }
 
 // get returns a single full document by id.
@@ -123,10 +124,10 @@ func (h *Handler) get(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, doc)
+	httputil.WriteJSON(w, http.StatusOK, doc)
 }
 
 // updateRequest is the auto-save payload. Every field is optional (a pointer) so
@@ -163,7 +164,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
 		req.Title, req.Content, req.ContentText, req.Tone, req.WordCount, id, db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
@@ -173,7 +174,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
 
 	doc, err := h.fetch(id)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
@@ -186,7 +187,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	writeJSON(w, http.StatusOK, doc)
+	httputil.WriteJSON(w, http.StatusOK, doc)
 }
 
 // delete removes a document (suggestions cascade via the FK).
@@ -196,7 +197,7 @@ func (h *Handler) delete(w http.ResponseWriter, r *http.Request) {
 		chi.URLParam(r, "id"), db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
@@ -222,21 +223,12 @@ func (h *Handler) fetch(id string) (db.Document, error) {
 }
 
 // --- small response helpers -------------------------------------------------
+//
+// The generic JSON/error helpers live in internal/httputil; these are the
+// document-specific shorthands that carry domain wording.
 
-func writeJSON(w http.ResponseWriter, status int, v any) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(v)
+func badRequest(w http.ResponseWriter, msg string) { httputil.BadRequest(w, msg) }
+func notFound(w http.ResponseWriter) {
+	httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
 }
-
-func errorJSON(w http.ResponseWriter, status int, msg string) {
-	writeJSON(w, status, map[string]string{"error": msg})
-}
-
-func serverError(w http.ResponseWriter, err error) {
-	errorJSON(w, http.StatusInternalServerError, err.Error())
-}
-
-func badRequest(w http.ResponseWriter, msg string) { errorJSON(w, http.StatusBadRequest, msg) }
-func notFound(w http.ResponseWriter)               { errorJSON(w, http.StatusNotFound, "document not found") }
-func notFoundMsg(w http.ResponseWriter, msg string) { errorJSON(w, http.StatusNotFound, msg) }
+func notFoundMsg(w http.ResponseWriter, msg string) { httputil.ErrorJSON(w, http.StatusNotFound, msg) }