feat(ui): hover an applied tag chip → highlight its grounding crop (#133 step 4)

Applied tags aren't scored live, so compute the grounding on demand: run the
tag's head over the image's max-over-bag (whole-image + concept crops), argmax
→ the region that best explains the tag on this image, mirroring what
score_image records for live suggestions.

- heads.py: extract _image_bag (now shared by score_image) + ground_applied_tag.
  Returns (grounding, has_head): has_head False = no head to localize with →
  no overlay; grounding None = the whole-image vector won → whole-image frame.
- tags.py: GET /api/images/<id>/tags/<id>/grounding → {grounding, has_head}.
- TagChip/TagPanel: applied chips inject fcSuggestionHover and fetch grounding
  on hover (cached per image+tag, race-guarded), reusing Step 3's overlay in
  both the modal and Explore. No new frontend overlay code.

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

tests/test_api_tags.py

@@ -94,3 +94,73 @@ async def test_unknown_prefix_kept_literal(client):
     body = await resp.get_json()
     assert body["name"] == "Http://example.com"
     assert body["kind"] == "general"
+
+
+# --- #1206 Step 4: applied-tag grounding endpoint (hover on applied chips) ----
+
+
+@pytest.mark.asyncio
+async def test_applied_tag_grounding_returns_winning_region(client, db):
+    # Hovering an applied chip fetches the crop that best explains the tag. Here
+    # the whole-image vector is orthogonal to the head but a concept crop aligns,
+    # so the crop wins the max-over-bag → grounding is that region's box.
+    from sqlalchemy import select
+
+    from backend.app.models import (
+        ImageRecord, ImageRegion, MLSettings, TagHead, TagKind,
+    )
+    from backend.app.services.tag_service import TagService
+
+    ver = (await db.execute(
+        select(MLSettings).where(MLSettings.id == 1)
+    )).scalar_one().embedder_model_version
+    img = ImageRecord(
+        path="/images/grchip.jpg", sha256="gc" * 32, size_bytes=1,
+        mime="image/jpeg", width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown",
+        siglip_embedding=[0.0] * 5 + [3.0] + [0.0] * 1146,   # whole-image ⟂ head
+    )
+    db.add(img)
+    await db.flush()
+    tag = await TagService(db).find_or_create("glasses", TagKind.general)
+    db.add(TagHead(
+        tag_id=tag.id, embedding_version=ver,
+        weights=[1.0] + [0.0] * 1151, bias=0.0, suggest_threshold=0.5,
+        auto_apply_threshold=None, n_pos=10, n_neg=30,
+        ap=0.8, precision_cv=0.9, recall=0.6,
+    ))
+    db.add(ImageRegion(
+        image_record_id=img.id, kind="concept",
+        rx=0.4, ry=0.4, rw=0.3, rh=0.3,
+        siglip_embedding=[3.0] + [0.0] * 1151, embedding_version=ver,
+    ))
+    await db.commit()
+
+    resp = await client.get(f"/api/images/{img.id}/tags/{tag.id}/grounding")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body["has_head"] is True
+    assert body["grounding"]["bbox"] == pytest.approx([0.4, 0.4, 0.3, 0.3])
+    assert body["grounding"]["kind"] == "concept"
+
+
+@pytest.mark.asyncio
+async def test_applied_tag_grounding_no_head(client, db):
+    # A tag with no head can't be localized → has_head False, grounding null; the
+    # chip shows no overlay. Validates the response contract the frontend reads.
+    from backend.app.models import ImageRecord, TagKind
+    from backend.app.services.tag_service import TagService
+
+    img = ImageRecord(
+        path="/images/grchip2.jpg", sha256="gd" * 32, size_bytes=1,
+        mime="image/jpeg", width=1, height=1, origin="imported_filesystem",
+        integrity_status="unknown",
+    )
+    db.add(img)
+    await db.flush()
+    tag = await TagService(db).find_or_create("NoHeadHere", TagKind.general)
+    await db.commit()
+
+    resp = await client.get(f"/api/images/{img.id}/tags/{tag.id}/grounding")
+    assert resp.status_code == 200
+    assert await resp.get_json() == {"grounding": None, "has_head": False}

tests/test_ml_suggestions.py

@@ -7,6 +7,7 @@ from sqlalchemy import select
 from backend.app.models import ImageRecord, ImageRegion, MLSettings, TagHead, TagKind
 from backend.app.models.tag import image_tag
 from backend.app.services.ml.allowlist import AllowlistService
+from backend.app.services.ml.heads import ground_applied_tag
 from backend.app.services.ml.suggestions import SuggestionService
 from backend.app.services.tag_service import TagService
 
@@ -280,3 +281,63 @@ async def test_ccip_character_surfaces_in_rail(db):
         if c.canonical_tag_id == raven.id
     )
     assert m.source == "ccip"
+
+
+# --- #1206 Step 4: on-demand grounding for ALREADY-APPLIED tag chips ---------
+# Applied tags aren't scored live, so ground_applied_tag recomputes the winning
+# bag row for one tag's head on demand — the data behind hovering an applied chip.
+
+
+@pytest.mark.asyncio
+async def test_ground_applied_tag_returns_winning_region(db):
+    # Whole-image vector is orthogonal to the head; a concept crop aligns with it,
+    # so the crop is the max-over-bag winner → grounding is THAT region's box.
+    tag = await TagService(db).find_or_create("glasses", TagKind.general)
+    img = await _img(db, "g1" * 32, _emb(5))            # whole-image ⟂ head
+    await _head(db, tag.id, slot=0)
+    db.add(ImageRegion(
+        image_record_id=img.id, kind="concept",
+        rx=0.4, ry=0.4, rw=0.3, rh=0.3,
+        siglip_embedding=_emb(0), embedding_version=await _embver(db),
+    ))
+    await db.commit()
+
+    grounding, has_head = await ground_applied_tag(db, img.id, tag.id)
+    assert has_head is True
+    assert grounding is not None
+    assert grounding["bbox"] == pytest.approx([0.4, 0.4, 0.3, 0.3])
+    assert grounding["kind"] == "concept"
+
+
+@pytest.mark.asyncio
+async def test_ground_applied_tag_none_when_whole_image_wins(db):
+    # Whole-image vector aligns with the head and out-scores an orthogonal crop →
+    # grounding None (has_head True): the tag is best explained by the global
+    # vector, so the chip hover shows the subtle whole-image frame, not a box.
+    tag = await TagService(db).find_or_create("sky", TagKind.general)
+    img = await _img(db, "g2" * 32, _emb(0))            # whole-image ALIGNED
+    await _head(db, tag.id, slot=0)
+    db.add(ImageRegion(
+        image_record_id=img.id, kind="concept",
+        rx=0.1, ry=0.1, rw=0.2, rh=0.2,
+        siglip_embedding=_emb(5), embedding_version=await _embver(db),
+    ))
+    await db.commit()
+
+    grounding, has_head = await ground_applied_tag(db, img.id, tag.id)
+    assert has_head is True
+    assert grounding is None
+
+
+@pytest.mark.asyncio
+async def test_ground_applied_tag_no_head(db):
+    # A tag with no head in the current space (manual/artist/meta, or below the
+    # head floor) can't be localized → (None, has_head False); the UI draws no
+    # overlay at all, distinct from "the whole image won".
+    tag = await TagService(db).find_or_create("artist:someone", TagKind.general)
+    img = await _img(db, "g3" * 32, _emb(0))
+    await db.commit()
+
+    grounding, has_head = await ground_applied_tag(db, img.id, tag.id)
+    assert has_head is False
+    assert grounding is None