feat(collections): smart (dynamic) collections — rules evaluated live at render

Type is DERIVED, not stored: a saved ruleset makes a collection SMART,
no rules = STATIC (stored collection_items links, unchanged behavior).
No schema change — collections.auto_assign_rules JSONB already carried
the config; user's decision 2026-10-14 (handoff: live-at-render, not
refresh-on-scan; create-time Static/Smart toggle; v1 NO hybrid).

- Rule gains an enabled flag (absent = enabled, legacy rules unaffected).
- Rule CRUD: POST/PUT(DELETE) /api/collections/:id/rules[/:ruleId] — the
  survivor dead effort of the rules-builder UI finally has real
  endpoints (rules were never editable after creation; nothing ever
  re-evaluated them). First rule converts a user collection to smart;
  removing the last reverts it to static. UpdateCollectionRulesJSON
  edits ONLY the rules doc so rule CRUD cannot clobber metadata.
- Live evaluation: candidates from GetVisibleLiveMediaForRules —
  visible-library set (family lens enforced at source) + archived IS
  NULL AND missing_scan_count = 0 — any enabled rule matches, title
  order. Zero refresh hooks by design: always current by construction.
- Membership mutations (add/remove/bulk-add) are 400 on smart — v1 no
  hybrid; collection_items.excluded stays the reserved future hook.
- Rules builder page (/collections/:id/rules) first time ever routable;
  templ whole-attribute interpolation ("{ expr }" inside a quoted attr
  value is literal text, as theme-{ user.Theme } silently proved).
- UI: create modal Static/⚡Smart cards (smart create redirects into the
  rules builder), ⚡ badge + real per-card counts on the grid (smart =
  live matches, static = stored-link count), smart detail renders
  matched books with no hand-pick actions + an Edit Rules button.
- API: GET /:id gains is_smart + live books; GET /: keeps the Android
  app's default exclusion, include_auto=true surfaces smart rows with
  live counts; TestRules previews against the SAME candidates the live
  render uses (visible + live, was raw first-1000).
- FIXED pre-existing regression from 7ce7321: static collection detail
  with NO library_id returned zero books — QueryType != '' caught user
  rows ('filter' default) and routed them to dashboard sections that
  never contain them; now only real system query types go there
  (handlers + SSR). App-visible symptom: /api/collections/:id without
  library_id came back books:[] for every static collection.

Tests: collections_smart_test.go (conversion, disabled rules, mutation
guards, revert-to-static, validation, system-collection prohibition,
include_auto semantics). Full offline integration suite PASS.

internal/handlers/collections.go

@@ -40,6 +40,7 @@ type CreateCollectionRequest struct {
 	Description     string                 `form:"description" json:"description"`
 	Color           string                 `form:"color" json:"color"`
 	Icon            string                 `form:"icon" json:"icon"`
+	CollectionType  string                 `form:"collection_type" json:"collection_type"` // "static" (default) or "smart" (rule-based)
 	AutoAssignRules []services.Rule        `form:"auto_assign_rules" json:"auto_assign_rules"`
 	ViewSettings    map[string]interface{} `form:"view_settings" json:"view_settings"`
 }
@@ -118,6 +119,7 @@ func (h *CollectionHandler) CreateCollection(c *echo.Context) error {
 	}
 
 	bookCount := int32(0)
+	isSmart := req.CollectionType == "smart" || len(req.AutoAssignRules) > 0
 	response := map[string]interface{}{
 		"id":                uuid.UUID(collection.ID.Bytes).String(),
 		"user_id":           uuid.UUID(collection.UserID.Bytes).String(),
@@ -125,6 +127,7 @@ func (h *CollectionHandler) CreateCollection(c *echo.Context) error {
 		"description":       textToString(collection.Description),
 		"color":             textToString(collection.Color),
 		"icon":              textToString(collection.Icon),
+		"collection_type":   map[bool]string{true: "smart", false: "static"}[isSmart],
 		"auto_assign_rules": collection.AutoAssignRules,
 		"view_settings":     collection.ViewSettings,
 		"book_count":        bookCount,
@@ -133,7 +136,13 @@ func (h *CollectionHandler) CreateCollection(c *echo.Context) error {
 
 	// Add redirect header for HTMX requests
 	if c.Request().Header.Get("HX-Request") == "true" {
-		c.Response().Header().Set("HX-Redirect", "/collections")
+		// A smart collection starts with an empty ruleset; the builder is
+		// where it becomes real. Static collections head back to the grid.
+		if isSmart {
+			c.Response().Header().Set("HX-Redirect", "/collections/"+uuid.UUID(collection.ID.Bytes).String()+"/rules")
+		} else {
+			c.Response().Header().Set("HX-Redirect", "/collections")
+		}
 	}
 
 	return c.JSON(http.StatusCreated, response)
@@ -158,31 +167,46 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
 		AutoAssignRules json.RawMessage `json:"auto_assign_rules"`
 		CreatedAt       string          `json:"created_at"`
 		BookCount       int             `json:"book_count"`
+		IsSmart         bool            `json:"is_smart"`
 	}
 
 	response := make([]CollectionResponse, 0, len(collections))
 	for _, col := range collections {
-		if !includeAuto && len(col.AutoAssignRules) > 0 {
+		isSmart := h.collectionService.IsSmartCollection(col.AutoAssignRules)
+		if !includeAuto && isSmart {
+			// Legacy default for API clients (the Android app pre-dates
+			// smart collections): rule-driven collections stay opt-in so
+			// their membership could never be stale for old readers.
 			continue
 		}
 
 		bookCount := 0
+		var libUUID pgtype.UUID
 		if libraryID != "" {
-			libUUID, libErr := uuid.Parse(libraryID)
-			if libErr == nil {
-				items, countErr := h.db.GetCollectionItemsForDashboard(c.Request().Context(), database.GetCollectionItemsForDashboardParams{
-					CollectionID: pgtype.UUID{Bytes: col.ID.Bytes, Valid: true},
-					LibraryID:    pgtype.UUID{Bytes: libUUID, Valid: true},
-					Limit:        pgtype.Int4{Int32: 10000, Valid: true},
+			if libParsed, libErr := uuid.Parse(libraryID); libErr == nil {
+				libUUID = pgtype.UUID{Bytes: libParsed, Valid: true}
+			}
+		}
+		if isSmart {
+			rules := h.collectionService.ParseRules(col.AutoAssignRules)
+			visibleIDs, visErr := h.userVisibleLibraryIDs(c)
+			if visErr == nil {
+				matches, evalErr := h.collectionService.EvaluateSmartCollection(c.Request().Context(), rules, services.SmartEvalOptions{
+					LibraryID:  libUUID,
+					VisibleIDs: visibleIDs,
 				})
-				if countErr == nil {
-					for _, item := range items {
-						if !item.Excluded.Valid || !item.Excluded.Bool {
-							bookCount++
-						}
-					}
+				if evalErr == nil {
+					bookCount = len(matches)
 				}
 			}
+		} else {
+			count, countErr := h.db.CountCollectionLiveItems(c.Request().Context(), database.CountCollectionLiveItemsParams{
+				CollectionID: pgtype.UUID{Bytes: col.ID.Bytes, Valid: true},
+				LibraryID:    libUUID,
+			})
+			if countErr == nil {
+				bookCount = int(count)
+			}
 		}
 
 		response = append(response, CollectionResponse{
@@ -194,6 +218,7 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
 			AutoAssignRules: col.AutoAssignRules,
 			CreatedAt:       col.CreatedAt.Time.String(),
 			BookCount:       bookCount,
+			IsSmart:         isSmart,
 		})
 	}
 
@@ -236,7 +261,31 @@ func (h *CollectionHandler) GetCollection(c *echo.Context) error {
 		libUUID = pgtype.UUID{Bytes: parsed, Valid: true}
 	}
 
-	if collection.QueryType.Valid && collection.QueryType.String != "" {
+	isSmart := h.collectionService.IsSmartCollection(collection.AutoAssignRules)
+	if isSmart {
+		rules := h.collectionService.ParseRules(collection.AutoAssignRules)
+		visibleIDs, err := h.userVisibleLibraryIDs(c)
+		if err != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		}
+		matches, evalErr := h.collectionService.EvaluateSmartCollection(c.Request().Context(), rules, services.SmartEvalOptions{
+			LibraryID:  libUUID,
+			VisibleIDs: visibleIDs,
+		})
+		if evalErr != nil {
+			return c.JSON(http.StatusInternalServerError, map[string]string{"error": evalErr.Error()})
+		}
+		bookList = make([]BookInfo, 0, len(matches))
+		for _, item := range matches {
+			itemUUID, _ := uuid.FromBytes(item.ID.Bytes[0:16])
+			bookList = append(bookList, BookInfo{
+				MediaItemID:    itemUUID.String(),
+				Title:          item.Title,
+				Author:         textToString(item.Author),
+				CoverImagePath: utils.ResolveMediaURL(item.LibraryID, item.CoverImagePath),
+			})
+		}
+	} else if collection.IsSystemCollection.Bool && collection.QueryType.Valid && collection.QueryType.String != "" && collection.QueryType.String != "filter" {
 		user := c.Get("user").(database.Users)
 		userUUID := uuid.UUID(user.ID.Bytes)
 		dashboardSvc := services.NewDashboardService(h.db)
@@ -323,6 +372,7 @@ func (h *CollectionHandler) GetCollection(c *echo.Context) error {
 		"view_settings":     viewSettings,
 		"books":             bookList,
 		"book_count":        len(bookList),
+		"is_smart":          isSmart,
 		"created_at":        collection.CreatedAt.Time.String(),
 	})
 }
@@ -400,6 +450,10 @@ func (h *CollectionHandler) AddBooks(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
 	}
 
+	if guardErr := h.rejectSmartMutation(c, collectionID); guardErr != nil {
+		return guardErr
+	}
+
 	user := c.Get("user").(database.Users)
 	userUUID := uuid.UUID(user.ID.Bytes)
 
@@ -447,6 +501,10 @@ func (h *CollectionHandler) RemoveBook(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
 	}
 
+	if guardErr := h.rejectSmartMutation(c, collectionID); guardErr != nil {
+		return guardErr
+	}
+
 	bookID, err := uuid.Parse(c.Param("bookId"))
 	if err != nil {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid book id"})
@@ -487,6 +545,10 @@ func (h *CollectionHandler) BulkRemoveBooks(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
 	}
 
+	if guardErr := h.rejectSmartMutation(c, collectionID); guardErr != nil {
+		return guardErr
+	}
+
 	user := c.Get("user").(database.Users)
 	userUUID := uuid.UUID(user.ID.Bytes)
 
@@ -727,6 +789,170 @@ func (h *CollectionHandler) GetUserCollectionsList(c *echo.Context) ([]database.
 	return h.collectionService.GetUserCollections(c.Request().Context(), userUUID)
 }
 
+// userVisibleLibraryIDs loads the requester's visible-library set (the
+// family lens). Smart-collection evaluation funnels every book candidate
+// through it so hidden libraries contribute nothing.
+func (h *CollectionHandler) userVisibleLibraryIDs(c *echo.Context) ([]pgtype.UUID, error) {
+	user, ok := c.Get("user").(database.Users)
+	if !ok {
+		return nil, echo.NewHTTPError(http.StatusUnauthorized, "invalid user")
+	}
+	rows, err := h.libraryService.GetUserVisibleLibraries(c.Request().Context(), user.ID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check library access: %w", err)
+	}
+	ids := make([]pgtype.UUID, 0, len(rows))
+	for _, lib := range rows {
+		if lib.ID.Valid {
+			ids = append(ids, lib.ID)
+		}
+	}
+	return ids, nil
+}
+
+// UserVisibleLibraryIDs is the exported entry point for the router's
+// frontend page handlers, which resolve the visible-library set before
+// evaluating smart-collection rule matches.
+func (h *CollectionHandler) UserVisibleLibraryIDs(c *echo.Context) ([]pgtype.UUID, error) {
+	return h.userVisibleLibraryIDs(c)
+}
+
+// CollectionService returns the underlying service so the router's
+// frontend handlers can share the exact same evaluation the API uses.
+func (h *CollectionHandler) CollectionService() *services.CollectionService {
+	return h.collectionService
+}
+
+// rejectSmartMutation returns a 400 for smart collections: membership is
+// derived live from rules, so stored link mutations have nothing to act
+// on. v1 has no hybrid mode — add/remove with both rules and hand-picked
+// books is deliberately unsupported (collection_items.excluded awaits it).
+func (h *CollectionHandler) rejectSmartMutation(c *echo.Context, collectionID uuid.UUID) *echo.HTTPError {
+	collection, err := h.GetCollectionData(c, collectionID)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusNotFound, "collection not found")
+	}
+	if h.collectionService.IsSmartCollection(collection.AutoAssignRules) {
+		return echo.NewHTTPError(http.StatusBadRequest, "smart collections are rule-based — membership is managed by the collection's rules, not by hand")
+	}
+	return nil
+}
+
+type AddRuleRequest struct {
+	Field    string `json:"field" validate:"required"`
+	Operator string `json:"operator" validate:"required"`
+	Value    string `json:"value" validate:"required"`
+	Enabled  *bool  `json:"enabled"`
+	Priority int    `json:"priority"`
+}
+
+// AddRule handles POST /api/collections/:id/rules — appends one rule to
+// the ruleset. The first rule converts a static collection to smart.
+func (h *CollectionHandler) AddRule(c *echo.Context) error {
+	collectionID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
+	}
+
+	collection, err := h.GetCollectionData(c, collectionID)
+	if err != nil {
+		return c.JSON(http.StatusNotFound, map[string]string{"error": "collection not found"})
+	}
+	if collection.IsSystemCollection.Bool {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "system collections cannot have rules"})
+	}
+
+	var req AddRuleRequest
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	updated, rule, err := h.collectionService.AddRule(c.Request().Context(), collectionID, services.Rule{
+		Field:    req.Field,
+		Operator: req.Operator,
+		Value:    req.Value,
+		Enabled:  req.Enabled,
+		Priority: req.Priority,
+	})
+	if err != nil {
+		var ruleErr *services.RuleValidationError
+		if errors.As(err, &ruleErr) {
+			return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusCreated, map[string]interface{}{
+		"collection_id": uuid.UUID(updated.ID.Bytes).String(),
+		"rule":          rule,
+		"is_smart":      h.collectionService.IsSmartCollection(updated.AutoAssignRules),
+	})
+}
+
+// UpdateRule handles PUT /api/collections/:id/rules/:ruleId — currently
+// the enabled toggle; the payload may only carry {"enabled": bool}.
+func (h *CollectionHandler) UpdateRule(c *echo.Context) error {
+	collectionID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
+	}
+	ruleID := c.Param("ruleId")
+	if ruleID == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "rule id required"})
+	}
+
+	var req struct {
+		Enabled *bool `json:"enabled" validate:"required"`
+	}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid request"})
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	updated, err := h.collectionService.SetRuleEnabled(c.Request().Context(), collectionID, ruleID, *req.Enabled)
+	if err != nil {
+		if strings.Contains(err.Error(), "rule not found") {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"collection_id": uuid.UUID(updated.ID.Bytes).String(),
+		"is_smart":      h.collectionService.IsSmartCollection(updated.AutoAssignRules),
+	})
+}
+
+// RemoveRule handles DELETE /api/collections/:id/rules/:ruleId.
+func (h *CollectionHandler) RemoveRule(c *echo.Context) error {
+	collectionID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "invalid collection id"})
+	}
+	ruleID := c.Param("ruleId")
+	if ruleID == "" {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": "rule id required"})
+	}
+
+	updated, err := h.collectionService.RemoveRule(c.Request().Context(), collectionID, ruleID)
+	if err != nil {
+		if strings.Contains(err.Error(), "rule not found") {
+			return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()})
+		}
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+
+	return c.JSON(http.StatusOK, map[string]interface{}{
+		"collection_id": uuid.UUID(updated.ID.Bytes).String(),
+		"is_smart":      h.collectionService.IsSmartCollection(updated.AutoAssignRules),
+	})
+}
+
 type TestRulesRequest struct {
 	Rules []map[string]interface{} `json:"rules" validate:"required"`
 }
@@ -748,16 +974,32 @@ func (h *CollectionHandler) TestRules(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
 	}
 
-	mediaItems, err := h.db.ListMediaItems(c.Request().Context(), database.ListMediaItemsParams{
-		Limit:  1000,
-		Offset: 0,
+	// Candidates mirror what smart collections actually evaluate against:
+	// the requester's visible libraries and live items only — the preview
+	// must not promise matches the live render will never produce.
+	visibleIDs, err := h.userVisibleLibraryIDs(c)
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
+	}
+	var visibleArg []pgtype.UUID
+	if len(visibleIDs) > 0 {
+		visibleArg = visibleIDs
+	}
+	mediaItems, err := h.db.GetVisibleLiveMediaForRules(c.Request().Context(), database.GetVisibleLiveMediaForRulesParams{
+		LibraryID:         pgtype.UUID{},
+		VisibleLibraryIds: visibleArg,
 	})
 	if err != nil {
 		return c.JSON(http.StatusInternalServerError, map[string]string{"error": "failed to load media items"})
 	}
 
+	listRows := make([]database.ListMediaItemsRow, len(mediaItems))
+	for i, item := range mediaItems {
+		listRows[i] = mediaItemsToListMediaItemsRow(item)
+	}
+
 	var matches []BookMatch
-	for _, item := range mediaItems {
+	for _, item := range listRows {
 		matchReason := h.checkRulesAgainstBook(item, req.Rules)
 		if matchReason != "" {
 			author := ""
@@ -886,6 +1128,16 @@ func (h *CollectionHandler) HandleBulkAddBooks(c *echo.Context) error {
 		return c.JSON(http.StatusBadRequest, map[string]string{"error": "operations required"})
 	}
 
+	// Smart collections are rejected up front per operation so the
+	// caller sees a clean, actionable error instead of silent no-ops.
+	for _, op := range req.Operations {
+		if colUUID, err := uuid.Parse(op.CollectionID); err == nil {
+			if guardErr := h.rejectSmartMutation(c, colUUID); guardErr != nil {
+				return guardErr
+			}
+		}
+	}
+
 	results := make([]map[string]interface{}, 0)
 	successCount := 0
 	failedCount := 0