refactor: remove dead code across server, templ pages, and client modules

Deadcode-verified removals (RTA reachability from main, cross-checked
with -test and textual xrefs):

Go server:
- whole files: middleware/transaction.go, middleware/error_handler.go,
  middleware/password_validator.go (live registration machinery kept),
  handlers/sync.go, sync/offline.go
- unrouted endpoints: auth UpdateUsername/UpdateEmail, timezone
  settings handler, OPDS RegisterOPDS, Kobo LibrarySync handler,
  ReaderHandler.ShowReader, JSON-data twins on collections/library
- duplicate book-matching handlers (book_matching.go Handler twins,
  matching.go MatchingHandler twins), superseded helpers
  (router.parseUUID, handlers.ValidateDeviceToken, normalizePath,
  userExists, generateLockID)

Templ/client:
- never-routed pages: api_explorer.templ, queue.templ and their
  client modules api-explorer.ts, api-explorer-docs.ts, queue.ts
- fully orphaned wrapper modules events.ts, dom.ts
- broken clearSyncQueue (called a nonexistent endpoint) and the
  hidden, never-populated sync-queue section on the devices page
- 166+ unused exports demoted to private (knip-verified); ~85 truly
  dead declarations removed via tsc noUnusedLocals fixpoint
- stale 'interactive API Explorer' claims dropped from docs

The docs drift-gate package (internal/docs), templ-bound modules
(dashboard, stats, header, index, login, profile*, bookshelf,
collections, toast-error), sqlc-generated code, and web/static are
intentionally untouched.

internal/services/book_matching_test.go

@@ -343,24 +343,3 @@ func TestLinkBookRequest_Validation(t *testing.T) {
 		})
 	}
 }
-
-// Example usage
-func ExampleBookMatchingService_QueryBooks() {
-	service := NewBookMatchingService(nil) // Would need real DB
-
-	req := &BookQueryRequest{
-		Identifiers: []string{
-			"uuid:550e8400-e29b-41d4-a716-446655440000",
-			"isbn:9783161484100",
-		},
-		SHA256:   "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592",
-		Title:    "Test Book",
-		Author:   "Test Author",
-		FileSize: 1024000,
-	}
-
-	_ = service
-	_ = req
-	// response, err := service.QueryBooks(context.Background(), req)
-	// fmt.Printf("Matches: %d, Action: %s\n", len(response.Matches), response.Action)
-}

internal/services/collection_service.go

@@ -122,27 +122,6 @@ func (s *CollectionService) GetCollection(ctx context.Context, collectionID uuid
 	return collection, nil
 }
 
-// GetCollectionWithBookCount gets a collection with book count
-func (s *CollectionService) GetCollectionWithBookCount(ctx context.Context, collectionID uuid.UUID) (map[string]any, error) {
-	collection, err := s.db.GetCollectionWithBookCount(ctx, pgtype.UUID{Bytes: collectionID, Valid: true})
-	if err != nil {
-		return nil, fmt.Errorf("failed to get collection: %v", err)
-	}
-
-	return map[string]any{
-		"id":                uuid.UUID(collection.ID.Bytes).String(),
-		"user_id":           uuid.UUID(collection.UserID.Bytes).String(),
-		"name":              collection.Name,
-		"description":       collection.Description.String,
-		"color":             collection.Color.String,
-		"icon":              collection.Icon.String,
-		"auto_assign_rules": collection.AutoAssignRules,
-		"view_settings":     collection.ViewSettings,
-		"created_at":        collection.CreatedAt.Time.String(),
-		"book_count":        collection.BookCount,
-	}, nil
-}
-
 // GetUserCollections gets all collections for a user
 func (s *CollectionService) GetUserCollections(ctx context.Context, userID uuid.UUID) ([]database.Collections, error) {
 	collections, err := s.db.GetCollectionsByUser(ctx, pgtype.UUID{Bytes: userID, Valid: true})

internal/services/filter_query.go

@@ -202,7 +202,7 @@ func clauseBoolFactory(col string) func(FilterRule, *filterBuilder) string {
 }
 
 // clausePresenceFactory — has / missing over a text column
-// (IS NULL / = '' per the plan's empty semantics).
+// (IS NULL / = ” per the plan's empty semantics).
 func clausePresenceFactory(col string) func(FilterRule, *filterBuilder) string {
 	return func(r FilterRule, b *filterBuilder) string {
 		switch r.Op {
@@ -761,7 +761,7 @@ WHERE ` + whereSQL +
 	for rows.Next() {
 		var row database.SearchMediaItemsUnifiedRow
 		if err := rows.Scan(composedScanDest(&row)...); err != nil {
-					return nil, err
+			return nil, err
 		}
 		out = append(out, row)
 	}

internal/services/media_scanner.go

@@ -491,12 +491,6 @@ func (s *MediaScanner) SetTrigger(trigger string) {
 	s.scanTrigger = trigger
 }
 
-// GetChangedItems reports how many existing items re-processed this run
-// (size change, sidecar change, or force rescan).
-func (s *MediaScanner) GetChangedItems() int {
-	return s.changedItems
-}
-
 func (s *MediaScanner) GetStats() (int, int, int) {
 	return s.totalFiles, s.newItems, s.errors
 }
@@ -4272,16 +4266,6 @@ func (s *MediaScanner) scanStateUpsert(libraryID pgtype.UUID, entry *scanEntry)
 	s.scanState[scanStateKey(libraryID, entry.FilePath)] = entry
 }
 
-// scanStateRemove drops an entry (the row's file_path moved elsewhere).
-func (s *MediaScanner) scanStateRemove(libraryID pgtype.UUID, relPath string) {
-	s.scanStateMu.Lock()
-	defer s.scanStateMu.Unlock()
-	if s.scanState == nil {
-		return
-	}
-	delete(s.scanState, scanStateKey(libraryID, relPath))
-}
-
 func (s *MediaScanner) getMediaItemByFilePath(ctx context.Context, filePath string, libraryID pgtype.UUID) (database.MediaItems, error) {
 	return s.db.GetMediaItemByFilePath(ctx, database.GetMediaItemByFilePathParams{
 		FilePath:  s.getRelativePath(filePath),

internal/services/media_scanner_audio.go

@@ -476,20 +476,6 @@ func applyAudioTagFallbacks(metadata *MediaMetadata, report *ffprobeReport) {
 	}
 }
 
-// audioDurationLabel renders the duration for logs/detail surfaces.
-func audioDurationLabel(seconds float64) string {
-	if seconds <= 0 {
-		return "—"
-	}
-	d := time.Duration(seconds) * time.Second
-	h := int(d.Hours())
-	m := int(d.Minutes()) % 60
-	if h > 0 {
-		return fmt.Sprintf("%dh %dm", h, m)
-	}
-	return fmt.Sprintf("%dm", m)
-}
-
 // parseJSONInt reads a RawMessage that may hold a JSON number or a
 // number-string; 0 for anything else. Used for sidecar fields whose
 // type differs across producing tools (Libation vs Calibre/ABS).

internal/services/media_scanner_comic_test.go

@@ -6,7 +6,6 @@ import (
 	"bytes"
 	"compress/gzip"
 	"encoding/xml"
-	"fmt"
 	"image"
 	"image/color"
 	"image/png"
@@ -595,21 +594,6 @@ func createTestTarGz(path string) error {
 	return nil
 }
 
-// Example usage
-func Example_extractComicMetadata() {
-	// Extract metadata from a comic archive
-	comicInfo, coverImage, err := extractComicMetadata("/path/to/comic.cbz")
-	if err != nil {
-		fmt.Printf("Error: %v\n", err)
-		return
-	}
-
-	fmt.Printf("Title: %s\n", comicInfo.Title)
-	fmt.Printf("Series: %s\n", comicInfo.Series)
-	fmt.Printf("Issue: %d\n", comicInfo.Number)
-	fmt.Printf("Cover size: %d bytes\n", len(coverImage))
-}
-
 func TestNormalizeMangaType(t *testing.T) {
 	tests := []struct {
 		name     string

internal/services/media_scanner_hash_test.go

@@ -5,7 +5,6 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"errors"
-	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -421,17 +420,3 @@ func TestExtractHashInfoIntegration(t *testing.T) {
 		})
 	}
 }
-
-// Example usage
-func ExampleMediaScanner_calculateFileSHA256() {
-	scanner := &MediaScanner{}
-
-	// Calculate SHA-256 hash of a file
-	hash, err := scanner.calculateFileSHA256("/path/to/ebook.epub")
-	if err != nil {
-		fmt.Printf("Error: %v\n", err)
-		return
-	}
-
-	fmt.Printf("SHA-256: %s\n", hash)
-}

internal/services/search.go

@@ -167,14 +167,6 @@ func normalizeLanguageFilter(wireValue string) string {
 	return strings.Join(out, ",")
 }
 
-// NormalizeLanguageFilter is the exported form of the search-path
-// normalization for callers that must compare RAW filter values
-// against stored codes without issuing a query (the facet panel marks
-// a value Active by matching the bound filter set).
-func NormalizeLanguageFilter(wireValue string) string {
-	return normalizeLanguageFilter(wireValue)
-}
-
 // FacetValue is one facet value + count for the filter panel.
 type FacetValue struct {
 	Value string `json:"value"` // the raw value (rides the filter param)