feat(facets): facet registry, Batch A server params, genre model v2, facets endpoint

Phase 1 + backend of Phase 2 of the faceted-navigation plan. One
declarative facet registry (services/facet_registry.go) drives the
bookshelf filter system; a drift-guard unit test reflects over the
generated SearchMediaItemsUnifiedParams so a registry entry and its
sqlc.narg block can never disagree silently.

- Nine new filter params on SearchMediaItemsUnified: story_arc,
  imprint, edition (scalar-fuzzy), age_rating, format_group,
  manga_type, reading_direction (exact), explicit, abridged
  (presence-bound bools). Comma = OR-within multi-select on every
  text facet; AND-across-facets unchanged.
- Genre model v2 (user rule: a subgenre is not a genre, it's a tag):
  genre_lexicon.go rebuilt as shelf set + subgenre->shelf map;
  pickSmartGenre picks direct shelf > mapped subgenre > Fiction floor
  > empty (unknown-only stays tags-only). Type-words (Manga, Comics,
  Graphic Novel) join the demote list. Both 'adventure' and 'action &
  adventure' are shelves — provider data uses both and the verified
  traces pin them.
- Language filter UX: comma elements normalize through the ingest
  language map, so display names ('English') match rows stored as ISO
  codes ('en'). The language autocomplete now serves display names.
- NEW GET /api/media-items/facets?facet=X&library_id=... — registry-
  driven value+count listing (14 static per-column queries, family-lens
  join); language values carry display names; bool/range facets 400.
- Family-lens gates: an explicit hidden-library library_id is now a
  403 on the search endpoints (was a silent empty set) — JSON branch
  and HTMX grid partial both.
- handlers.ParseMediaSearchParams is the SINGLE param parser for the
  search JSON endpoint and the HTMX grid partial; the HTML branch
  previously dropped publisher_filter and narrator_filter silently.

Pins: docs/contract_pins.md changelog entries (additive request
params; new facets endpoint). Tests: facet_registry_test.go (shape +
SQL drift guard + library-type union), series_parsing_test.go genre-v2
cases, facets_integration_test.go (param filtering e2e, counts,
language display, 403s) — container runner.

internal/router/search.go

@@ -3,15 +3,11 @@ package router
 import (
 	"bookhoard/internal/database"
 	"bookhoard/internal/handlers"
-	"bookhoard/internal/services"
 	"bookhoard/templates"
 	"bytes"
 	"log"
 	"net/http"
-	"strconv"
 
-	"github.com/google/uuid"
-	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/labstack/echo/v5"
 )
 
@@ -30,6 +26,9 @@ func registerSearchRoutes(cfg *Config) {
 		// Otherwise return JSON (API clients)
 		return cfg.MediaHandler.SearchMediaItems(c)
 	})
+	// Facet-value listings for the filter panel (faceted-navigation
+	// Batch C): /api/media-items/facets?facet=X&library_id=...
+	protected.GET("/media-items/facets", cfg.MediaHandler.GetFacets)
 	protected.POST("/sync/books/query", cfg.MatchingHandler.QueryBooks)
 }
 
@@ -39,60 +38,37 @@ func handleSearchHTML(c *echo.Context, cfg *Config) error {
 	if !ok {
 		return c.String(http.StatusUnauthorized, "Unauthorized")
 	}
-	// Extract query parameters
-	query := c.QueryParam("q")
+	// Extract filters via the SHARED parser (handlers.ParseMediaSearchParams)
+	// — the HTMX grid partial and the JSON endpoint can never disagree on
+	// which facet params exist or how they parse. (This branch previously
+	// dropped publisher_filter and narrator_filter entirely — the shared
+	// parser fixes that too.)
+	params := handlers.ParseMediaSearchParams(c)
+	params.UserID = user.ID
+	limit := params.Limit
+	offset := params.Offset
 	libraryID := c.QueryParam("library_id")
-	limit, _ := strconv.Atoi(c.QueryParam("limit"))
-	if limit == 0 {
-		limit = 50
-	}
-	offset, _ := strconv.Atoi(c.QueryParam("offset"))
-	// Validate library_id
-	var libUUID pgtype.UUID
-	if libraryID != "" {
-		lib, err := uuid.Parse(libraryID)
+
+	// Family-lens gate: an explicit library_id outside the requester's
+	// visible set is a 403 (same rule as the JSON branch).
+	if params.LibraryID.Valid {
+		_, ids, err := cfg.LibraryService.VisibleLibrarySet(c.Request().Context(), user.ID)
 		if err != nil {
-			return c.String(http.StatusBadRequest, "invalid library_id")
+			log.Printf("VisibleLibrarySet failed: %v", err)
+			return c.HTML(http.StatusInternalServerError, `<div style="color: red;">Search error</div>`)
+		}
+		visible := false
+		for _, id := range ids {
+			if id == params.LibraryID {
+				visible = true
+				break
+			}
+		}
+		if !visible {
+			return c.HTML(http.StatusForbidden, `<div style="color: red;">Library not visible</div>`)
 		}
-		libUUID = pgtype.UUID{Bytes: lib, Valid: true}
-	} else {
-		libUUID = pgtype.UUID{Valid: false}
-	}
-	// Extract filters
-	authorFilter := c.QueryParam("author_filter")
-	seriesFilter := c.QueryParam("series_filter")
-	genreFilter := c.QueryParam("genre_filter")
-	tagsFilter := c.QueryParam("tags_filter")
-	languageFilter := c.QueryParam("language_filter")
-	yearMin, _ := strconv.Atoi(c.QueryParam("year_min"))
-	yearMax, _ := strconv.Atoi(c.QueryParam("year_max"))
-	hasCover := false
-	hasCoverValid := false
-	if _, exists := c.QueryParams()["has_cover"]; exists {
-		hasCover = c.QueryParam("has_cover") == "true"
-		hasCoverValid = true
-	}
-	sortParam := c.QueryParam("sort")
-	if sortParam == "" {
-		sortParam = "title ASC"
-	}
-	// Build search params
-	params := services.SearchParams{
-		UserID:         user.ID,
-		LibraryID:      libUUID,
-		SearchQuery:    query,
-		AuthorFilter:   authorFilter,
-		SeriesFilter:   seriesFilter,
-		GenreFilter:    genreFilter,
-		TagsFilter:     tagsFilter,
-		LanguageFilter: languageFilter,
-		YearMin:        yearMin,
-		YearMax:        yearMax,
-		HasCover:       pgtype.Bool{Bool: hasCover, Valid: hasCoverValid},
-		Sort:           sortParam,
-		Limit:          limit,
-		Offset:         offset,
 	}
+
 	// Execute search using handler method
 	results, totalCount, err := cfg.MediaHandler.ExecuteSearch(c.Request().Context(), params)
 	if err != nil {