feat(gallery): tag→gallery nav from modal chips (#5) + OR/exclude tag scope (#6a)

Cluster A, milestone #97. #5: clicking an image-modal tag chip's body now
closes the modal and opens the gallery filtered for that one tag (fresh
filter); ✕/kebab stay as the explicit remove/rename controls.

#6a (backend of OR/exclude filtering): gallery_service._apply_scope gains a
structured tag model — tag_or_groups (AND-of-OR: one EXISTS(tag_id IN group)
per group) + tag_exclude (NOT EXISTS(tag_id IN exclude)) — layered additively
on the existing tag_ids AND path so cursors/facets/deep-links are untouched.
Threaded through scroll/timeline/jump_cursor/facets/similar + facets common
dict; _require_single_filter rejects post_id combined with OR/exclude. API
parses tag_or (repeatable → one OR-group each) + tag_not (csv exclude).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XCUHUGQLrBrkgyk1t49kpX

backend/app/api/gallery.py

@@ -37,16 +37,30 @@ def _parse_filters():
     """Parse the composable gallery filters from query args, returning
     ``(filters_dict, sort)``. Raises ValueError (→ 400) on malformed ids/dates.
 
-    `tag_id` accepts a single id or a comma-separated list (AND); `media` is
-    image|video; `sort` is newest|oldest; `platform` selects one platform
-    (or the UNSOURCED_PLATFORM sentinel); `untagged`/`no_artist` are boolean
-    flags; `date_from`/`date_to` are inclusive calendar-day bounds (date_to is
-    widened by a day so the whole day is covered by the service's half-open
-    `< date_to`)."""
+    The structured tag filter (#6) is AND-of-OR plus exclusions:
+    - `tag_id` accepts a single id or a comma-separated list — all ANDed
+      (the include common case; back-compat).
+    - `tag_or` is REPEATABLE; each instance is a comma-separated OR-group, and
+      the image must match at least one tag from EACH group (groups ANDed).
+    - `tag_not` is a comma-separated exclude list (image must carry none).
+
+    `media` is image|video; `sort` is newest|oldest; `platform` selects one
+    platform (or the UNSOURCED_PLATFORM sentinel); `untagged`/`no_artist` are
+    boolean flags; `date_from`/`date_to` are inclusive calendar-day bounds
+    (date_to is widened by a day so the whole day is covered by the service's
+    half-open `< date_to`)."""
     tag_raw = request.args.get("tag_id")
     tag_ids = (
         [int(x) for x in tag_raw.split(",") if x.strip()] if tag_raw else None
     ) or None
+    tag_or_groups = [
+        grp for raw in request.args.getlist("tag_or")
+        if (grp := [int(x) for x in raw.split(",") if x.strip()])
+    ] or None
+    not_raw = request.args.get("tag_not")
+    tag_exclude = (
+        [int(x) for x in not_raw.split(",") if x.strip()] if not_raw else None
+    ) or None
     post_id_raw = request.args.get("post_id")
     post_id = int(post_id_raw) if post_id_raw else None
     artist_id_raw = request.args.get("artist_id")
@@ -64,7 +78,9 @@ def _parse_filters():
         date_to += timedelta(days=1)  # inclusive of the date_to calendar day
     filters = {
         "tag_ids": tag_ids, "post_id": post_id, "artist_id": artist_id,
-        "media_type": media_type, "platform": platform,
+        "media_type": media_type,
+        "tag_or_groups": tag_or_groups, "tag_exclude": tag_exclude,
+        "platform": platform,
         "untagged": untagged, "no_artist": no_artist,
         "date_from": date_from, "date_to": date_to,
     }

backend/app/services/gallery_service.py

@@ -136,11 +136,15 @@ def image_url(path: str) -> str:
     return f"/images/{quote(rel, safe='/')}"
 
 
-def _require_single_filter(tag_ids, post_id, artist_id) -> None:
+def _require_single_filter(
+    tag_ids, post_id, artist_id, tag_or_groups=None, tag_exclude=None,
+) -> None:
     """post_id is the post-detail view — it can't combine with the
-    composable filters. tag_ids + artist_id (+ media_type) compose freely
-    (AND)."""
-    if post_id is not None and (tag_ids or artist_id is not None):
+    composable filters. tag_ids / tag_or_groups / tag_exclude + artist_id
+    (+ media_type) compose freely (AND)."""
+    if post_id is not None and (
+        tag_ids or artist_id is not None or tag_or_groups or tag_exclude
+    ):
         raise ValueError(
             "post_id cannot be combined with tag or artist filters"
         )
@@ -148,6 +152,7 @@ def _require_single_filter(tag_ids, post_id, artist_id) -> None:
 
 def _apply_scope(
     stmt, *, tag_ids, post_id, artist_id, media_type,
+    tag_or_groups=None, tag_exclude=None,
     platform=None, untagged=False, no_artist=False,
     date_from=None, date_to=None,
 ):
@@ -158,7 +163,14 @@ def _apply_scope(
     be present on `stmt` (the artist/platform paths alias Post/Source inside
     their own EXISTS).
 
-    - tag_ids: image must carry ALL of them — one correlated EXISTS per tag.
+    Tag filtering is one structured model (#6): AND-of-OR plus exclusions.
+    - tag_ids: image must carry ALL of them — one correlated EXISTS per tag
+      (the AND-of-singletons "include" common case; light editor + back-compat).
+    - tag_or_groups: list of OR-groups; the image must carry AT LEAST ONE tag
+      from EACH group — one EXISTS(tag_id IN group) per group, AND'd across
+      groups. (advanced editor)
+    - tag_exclude: image must carry NONE of these — a single NOT EXISTS(tag_id
+      IN exclude). (light "exclude" chips + advanced NOT)
     - post_id / artist_id: provenance EXISTS (post_id is exclusive, guarded
       by _require_single_filter).
     - media_type: 'image' | 'video' narrows by mime prefix.
@@ -175,6 +187,22 @@ def _apply_scope(
                 image_tag.c.tag_id == tid,
             )
         )
+    for group in tag_or_groups or []:
+        if not group:
+            continue  # an empty OR-group would match nothing; treat as absent
+        stmt = stmt.where(
+            exists().where(
+                image_tag.c.image_record_id == ImageRecord.id,
+                image_tag.c.tag_id.in_(group),
+            )
+        )
+    if tag_exclude:
+        stmt = stmt.where(
+            ~exists().where(
+                image_tag.c.image_record_id == ImageRecord.id,
+                image_tag.c.tag_id.in_(tag_exclude),
+            )
+        )
     prov = _provenance_clause(post_id, artist_id)
     if prov is not None:
         stmt = stmt.where(prov)
@@ -296,6 +324,8 @@ class GalleryService:
         artist_id: int | None = None,
         media_type: str | None = None,
         sort: str = "newest",
+        tag_or_groups: list[list[int]] | None = None,
+        tag_exclude: list[int] | None = None,
         platform: str | None = None,
         untagged: bool = False,
         no_artist: bool = False,
@@ -304,7 +334,9 @@ class GalleryService:
     ) -> GalleryPage:
         if limit < 1 or limit > 200:
             raise ValueError("limit must be between 1 and 200")
-        _require_single_filter(tag_ids, post_id, artist_id)
+        _require_single_filter(
+            tag_ids, post_id, artist_id, tag_or_groups, tag_exclude,
+        )
 
         eff = _effective_date_col()
         stmt = select(ImageRecord, Post.post_date, eff.label("eff"))
@@ -312,6 +344,7 @@ class GalleryService:
         stmt = _apply_scope(
             stmt, tag_ids=tag_ids, post_id=post_id,
             artist_id=artist_id, media_type=media_type,
+            tag_or_groups=tag_or_groups, tag_exclude=tag_exclude,
             platform=platform, untagged=untagged, no_artist=no_artist,
             date_from=date_from, date_to=date_to,
         )
@@ -359,6 +392,8 @@ class GalleryService:
         post_id: int | None = None,
         artist_id: int | None = None,
         media_type: str | None = None,
+        tag_or_groups: list[list[int]] | None = None,
+        tag_exclude: list[int] | None = None,
         platform: str | None = None,
         untagged: bool = False,
         no_artist: bool = False,
@@ -372,10 +407,13 @@ class GalleryService:
             year_col, month_col, func.count(ImageRecord.id).label("cnt")
         )
         stmt = _outer_join_primary_post(stmt)
-        _require_single_filter(tag_ids, post_id, artist_id)
+        _require_single_filter(
+            tag_ids, post_id, artist_id, tag_or_groups, tag_exclude,
+        )
         stmt = _apply_scope(
             stmt, tag_ids=tag_ids, post_id=post_id,
             artist_id=artist_id, media_type=media_type,
+            tag_or_groups=tag_or_groups, tag_exclude=tag_exclude,
             platform=platform, untagged=untagged, no_artist=no_artist,
             date_from=date_from, date_to=date_to,
         )
@@ -387,6 +425,8 @@ class GalleryService:
         self, year: int, month: int, tag_ids: list[int] | None = None,
         post_id: int | None = None, artist_id: int | None = None,
         media_type: str | None = None, sort: str = "newest",
+        tag_or_groups: list[list[int]] | None = None,
+        tag_exclude: list[int] | None = None,
         platform: str | None = None, untagged: bool = False,
         no_artist: bool = False, date_from: datetime | None = None,
         date_to: datetime | None = None,
@@ -403,10 +443,13 @@ class GalleryService:
             extract("month", eff) == month,
         )
         stmt = _outer_join_primary_post(stmt)
-        _require_single_filter(tag_ids, post_id, artist_id)
+        _require_single_filter(
+            tag_ids, post_id, artist_id, tag_or_groups, tag_exclude,
+        )
         stmt = _apply_scope(
             stmt, tag_ids=tag_ids, post_id=post_id,
             artist_id=artist_id, media_type=media_type,
+            tag_or_groups=tag_or_groups, tag_exclude=tag_exclude,
             platform=platform, untagged=untagged, no_artist=no_artist,
             date_from=date_from, date_to=date_to,
         )
@@ -427,7 +470,10 @@ class GalleryService:
     async def facets(
         self, *, tag_ids: list[int] | None = None,
         post_id: int | None = None, artist_id: int | None = None,
-        media_type: str | None = None, platform: str | None = None,
+        media_type: str | None = None,
+        tag_or_groups: list[list[int]] | None = None,
+        tag_exclude: list[int] | None = None,
+        platform: str | None = None,
         untagged: bool = False, no_artist: bool = False,
         date_from: datetime | None = None, date_to: datetime | None = None,
     ) -> GalleryFacets:
@@ -437,10 +483,13 @@ class GalleryService:
         No outer join is needed — every clause is a correlated EXISTS or a
         column predicate on ImageRecord.
         """
-        _require_single_filter(tag_ids, post_id, artist_id)
+        _require_single_filter(
+            tag_ids, post_id, artist_id, tag_or_groups, tag_exclude,
+        )
         common = {
             "tag_ids": tag_ids, "post_id": post_id,
             "artist_id": artist_id, "media_type": media_type,
+            "tag_or_groups": tag_or_groups, "tag_exclude": tag_exclude,
         }
 
         # total — the full active filter (the headline result count).
@@ -515,7 +564,10 @@ class GalleryService:
     async def similar(
         self, image_id: int, limit: int = 100, *,
         tag_ids: list[int] | None = None, artist_id: int | None = None,
-        media_type: str | None = None, platform: str | None = None,
+        media_type: str | None = None,
+        tag_or_groups: list[list[int]] | None = None,
+        tag_exclude: list[int] | None = None,
+        platform: str | None = None,
         untagged: bool = False, no_artist: bool = False,
         date_from: datetime | None = None, date_to: datetime | None = None,
     ) -> list[GalleryImage] | None:
@@ -547,6 +599,7 @@ class GalleryService:
         stmt = _apply_scope(
             stmt, tag_ids=tag_ids, post_id=None,
             artist_id=artist_id, media_type=media_type,
+            tag_or_groups=tag_or_groups, tag_exclude=tag_exclude,
             platform=platform, untagged=untagged, no_artist=no_artist,
             date_from=date_from, date_to=date_to,
         )