From 104cac5dca42dc505e4f6a4c01d83a5fe10bd74c Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 00:56:47 -0400
Subject: [PATCH 01/18] =?UTF-8?q?fix(ui):=20tooltip=20readability=20?=
 =?UTF-8?q?=E2=80=94=20dark=20bg=20+=20parchment=20text=20(was=20light-on-?=
 =?UTF-8?q?light)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operator-flagged 2026-05-28: tooltips (e.g. the action buttons in
Subscriptions → Subscriptions) render near-white-on-near-white,
unreadable.

Cause: Vuetify's default v-tooltip pairs `on-surface-variant` text with
an `surface-variant` background. FC's theme deliberately maps
`on-surface-variant` to vellum (#C2BFB4 — a light cream, the correct
muted-text token for captions/hints on the dark page) but never defines
`surface-variant`, so Vuetify auto-generates a light-ish tooltip
background. Light text on light bg.

Fix is tooltip-specific so it doesn't disturb the (correctly light)
muted-text token elsewhere. New app-global stylesheet
frontend/src/styles/app.css, imported in main.js AFTER vuetify/styles
(equal-specificity rule wins by source order), overrides
`.v-tooltip > .v-overlay__content` to a dark elevated panel
(surface-bright = slate #2C313A) with high-contrast parchment text
(#E8E4D8) + a subtle border + shadow. Applies to every tooltip in the
app, so the fix is consistent rather than per-component.
---
 frontend/src/main.js        |  3 +++
 frontend/src/styles/app.css | 21 +++++++++++++++++++++
 2 files changed, 24 insertions(+)
 create mode 100644 frontend/src/styles/app.css

diff --git a/frontend/src/main.js b/frontend/src/main.js
index 0882de9..d4ce856 100644
--- a/frontend/src/main.js
+++ b/frontend/src/main.js
@@ -3,6 +3,9 @@ import { createPinia } from 'pinia'
 import { createVuetify } from 'vuetify'
 import 'vuetify/styles'
 import '@mdi/font/css/materialdesignicons.css'
+// App-global CSS overrides — imported AFTER vuetify/styles so equal-
+// specificity rules (e.g. the tooltip readability fix) win by source order.
+import './styles/app.css'
 
 import App from './App.vue'
 import router from './router.js'
diff --git a/frontend/src/styles/app.css b/frontend/src/styles/app.css
new file mode 100644
index 0000000..55b13a4
--- /dev/null
+++ b/frontend/src/styles/app.css
@@ -0,0 +1,21 @@
+/* App-global overrides. Imported in main.js AFTER 'vuetify/styles' so
+   these win on equal selector specificity by source order. */
+
+/* Tooltip readability fix (operator-flagged 2026-05-28).
+   Vuetify's default v-tooltip pairs `on-surface-variant` TEXT with an
+   `surface-variant` BACKGROUND. FC's theme deliberately maps
+   `on-surface-variant` to vellum (#C2BFB4 — a light cream, correct for
+   muted captions/hints on the dark page) but never defines
+   `surface-variant`, so Vuetify auto-generates a light-ish background:
+   light text on light bg → near-white-on-near-white, unreadable.
+
+   Tooltips want the inverse of muted body text — a dark, slightly
+   elevated panel with the HIGH-contrast parchment text. Fixing it here
+   (not by changing on-surface-variant) keeps captions/empty-states
+   correct while making every tooltip in the app legible. */
+.v-tooltip > .v-overlay__content {
+  background: rgb(var(--v-theme-surface-bright));   /* slate #2C313A */
+  color: rgb(var(--v-theme-on-surface));            /* parchment #E8E4D8 */
+  border: 1px solid rgb(var(--v-theme-on-surface-variant) / 0.25);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.4);
+}

From e1fc65bd1bdbcb84fdb48716097cc1048bdf81ff Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 01:12:20 -0400
Subject: [PATCH 02/18] feat(provenance+tags): collapse provenance
 descriptions; purge retired-kind tags
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operator-flagged 2026-05-28, two asks.

**1. Provenance posts ate the panel.** Each post card rendered its full
description (180px scroll box) inline, so a few posts pushed everything
else off-screen. ProvenancePanel now collapses the description by
default behind a per-post "Show description ▾ / Hide ▴" toggle (state
keyed by provenance_id, reset when the viewed image changes). Cards stay
compact — platform/date/title/meta/actions — and the operator expands
only the descriptions they want.

**2. Purge tags of retired/system kinds.** The IR migration left
`archive`/`post`/`artist`-kind tags (e.g. `BlenderKnight:Hannah_BJ_Loops`)
that FC no longer creates — the tag input only makes
character/fandom/series/general, and provenance + artists are their own
systems now. (meta/rating were already hard-deleted by alembic 0023.)

- cleanup_service.purge_tags_by_kind(kinds=PURGEABLE_TAG_KINDS) — counts
  (dry_run) or deletes tags whose kind ∈ (archive, post, artist).
  CASCADE clears the image_tag / alias / allowlist / etc. rows.
- POST /api/admin/tags/purge-retired-kinds (Tier-A, dry-run preview
  returns per-kind counts + sample names — the preview IS the
  verification of exactly what'll be deleted before committing).
- Tag Maintenance card gets a second section: "Preview retired-kind
  tags" → per-kind breakdown + sample → "Delete N retired-kind tag(s)".

Tests: dry-run counts by kind (general survives), commit deletes only
the retired kinds (general + character survive, retired count → 0).

NOTE: a dry-run preview will show exactly which kinds/counts are
present. If the operator's noisy tags turn out to be `general` (e.g. an
IR `source:patreon` that fell back to general during migration), they
won't be caught by the kind purge — the preview makes that visible so
we can decide on a name-based pass separately.
---
 backend/app/api/admin.py                      | 19 ++++++
 backend/app/services/cleanup_service.py       | 42 +++++++++++++
 .../src/components/modal/ProvenancePanel.vue  | 18 +++++-
 .../settings/TagMaintenanceCard.vue           | 62 +++++++++++++++++++
 frontend/src/stores/admin.js                  | 14 +++++
 tests/test_api_admin.py                       | 50 +++++++++++++++
 6 files changed, 203 insertions(+), 2 deletions(-)

diff --git a/backend/app/api/admin.py b/backend/app/api/admin.py
index fd3c5ce..e6011b3 100644
--- a/backend/app/api/admin.py
+++ b/backend/app/api/admin.py
@@ -206,3 +206,22 @@ async def tags_prune_unused():
             )
         )
     return jsonify(result)
+
+
+@admin_bp.route("/tags/purge-retired-kinds", methods=["POST"])
+async def tags_purge_retired_kinds():
+    """Tier-A: delete tags whose kind is a system/legacy kind FC no
+    longer creates (archive / post / artist — the IR-migration leftovers
+    like `BlenderKnight:Hannah_BJ_Loops`). dry-run preview returns
+    per-kind counts + a sample so the UI can show exactly what'll go
+    before the operator confirms with dry_run=false."""
+    from ..services.cleanup_service import purge_tags_by_kind
+
+    body = await request.get_json(silent=True) or {}
+    dry_run = bool(body.get("dry_run", False))
+
+    async with get_session() as session:
+        result = await session.run_sync(
+            lambda sync_sess: purge_tags_by_kind(sync_sess, dry_run=dry_run)
+        )
+    return jsonify(result)
diff --git a/backend/app/services/cleanup_service.py b/backend/app/services/cleanup_service.py
index 7025b8b..4470d3f 100644
--- a/backend/app/services/cleanup_service.py
+++ b/backend/app/services/cleanup_service.py
@@ -369,6 +369,48 @@ def prune_unused_tags(session: Session, *, dry_run: bool = False) -> dict:
     return {"deleted": len(ids), "sample_names": sample}
 
 
+# System/legacy tag kinds that FC no longer creates: the tag input only
+# makes character/fandom/series/general; provenance (post grouping) and
+# archive membership are their own systems now, and artists are
+# first-class Artist/Source rows. These linger only on IR-migrated rows.
+# meta/rating were hard-deleted by alembic 0023, so they're not listed.
+PURGEABLE_TAG_KINDS = ("archive", "post", "artist")
+
+
+def purge_tags_by_kind(
+    session: Session, *, kinds: tuple[str, ...] = PURGEABLE_TAG_KINDS,
+    dry_run: bool = False,
+) -> dict:
+    """Count (dry_run) or delete all tags whose kind is in `kinds`.
+
+    CASCADE on image_tag / tag_alias / tag_allowlist /
+    tag_reference_embedding / tag_suggestion_rejection / series_page
+    clears the related rows on the parent DELETE.
+
+    Returns:
+      {"by_kind": {kind: count, ...}, "count": total,
+       "sample_names": [first 50], and on live runs "deleted": total}
+    """
+    rows = session.execute(
+        select(Tag.id, Tag.name, Tag.kind).where(Tag.kind.in_(kinds))
+    ).all()
+    by_kind: dict[str, int] = {}
+    for _id, _name, kind in rows:
+        key = kind.value if hasattr(kind, "value") else str(kind)
+        by_kind[key] = by_kind.get(key, 0) + 1
+    sample = [name for _id, name, _kind in rows[:50]]
+    total = len(rows)
+    if dry_run:
+        return {"by_kind": by_kind, "count": total, "sample_names": sample}
+    if total:
+        session.execute(Tag.__table__.delete().where(Tag.kind.in_(kinds)))
+        session.commit()
+    return {
+        "by_kind": by_kind, "count": total, "deleted": total,
+        "sample_names": sample,
+    }
+
+
 # ---------------------------------------------------------------------------
 # FC-Cleanup additions (2026-05-26): retroactive audit of import-filter rules.
 # ---------------------------------------------------------------------------
diff --git a/frontend/src/components/modal/ProvenancePanel.vue b/frontend/src/components/modal/ProvenancePanel.vue
index 178c6af..507a9e6 100644
--- a/frontend/src/components/modal/ProvenancePanel.vue
+++ b/frontend/src/components/modal/ProvenancePanel.vue
@@ -37,9 +37,13 @@
           <a href="#" @click.prevent="openPost(e.post.id)">
             View images from this post
           </a>
+          <a
+            v-if="e.post.description_html"
+            href="#" @click.prevent="toggleDesc(e.provenance_id)"
+          >{{ expanded[e.provenance_id] ? 'Hide description ▴' : 'Show description ▾' }}</a>
         </div>
         <div
-          v-if="e.post.description_html"
+          v-if="e.post.description_html && expanded[e.provenance_id]"
           class="fc-prov__desc" v-html="e.post.description_html"
         />
       </article>
@@ -74,7 +78,7 @@
 </template>
 
 <script setup>
-import { computed, watch } from 'vue'
+import { computed, reactive, watch } from 'vue'
 import { useRouter } from 'vue-router'
 import { useModalStore } from '../../stores/modal.js'
 import { useProvenanceStore } from '../../stores/provenance.js'
@@ -84,6 +88,16 @@ const modal = useModalStore()
 const prov = useProvenanceStore()
 const router = useRouter()
 
+// Per-post description collapse state (keyed by provenance_id). Default
+// collapsed so multiple posts don't each eat ~180px of the panel — the
+// operator flagged the descriptions consuming a lot of real estate
+// 2026-05-28. Reset when the viewed image changes.
+const expanded = reactive({})
+function toggleDesc(id) { expanded[id] = !expanded[id] }
+watch(() => modal.currentImageId, () => {
+  for (const k of Object.keys(expanded)) delete expanded[k]
+})
+
 watch(
   () => modal.currentImageId,
   (id) => { if (id != null) prov.loadForImage(id) },
diff --git a/frontend/src/components/settings/TagMaintenanceCard.vue b/frontend/src/components/settings/TagMaintenanceCard.vue
index 7d82f0b..c19fef7 100644
--- a/frontend/src/components/settings/TagMaintenanceCard.vue
+++ b/frontend/src/components/settings/TagMaintenanceCard.vue
@@ -44,6 +44,46 @@
           @click="onCommit"
         >Delete {{ preview.count }} unused tag(s)</v-btn>
       </div>
+
+      <v-divider class="my-5" />
+
+      <p class="fc-muted text-body-2 mb-4">
+        Purge tags with retired/system kinds FC no longer uses
+        (<code>archive</code>, <code>post</code>, <code>artist</code>) —
+        IR-migration leftovers like
+        <code>BlenderKnight:Hannah_BJ_Loops</code>. Provenance and
+        artists are their own systems now, so these tag rows are pure
+        noise. Removes them from every image.
+      </p>
+
+      <v-btn
+        color="accent" variant="flat" rounded="pill"
+        prepend-icon="mdi-magnify"
+        :loading="loadingKindPreview"
+        class="mb-3"
+        @click="onKindPreview"
+      >Preview retired-kind tags</v-btn>
+
+      <div v-if="kindPreview">
+        <p class="text-body-2 mb-2">
+          <strong>{{ kindPreview.count }}</strong> tag(s) of retired kinds.
+          <span v-for="(n, k) in kindPreview.by_kind" :key="k" class="fc-muted">
+            {{ k }}: {{ n }}&nbsp;&nbsp;
+          </span>
+        </p>
+        <div v-if="kindPreview.sample_names?.length" class="fc-name-grid mb-3">
+          <span v-for="n in kindPreview.sample_names" :key="n" class="fc-name">
+            {{ n }}
+          </span>
+        </div>
+        <v-btn
+          color="error" variant="flat" rounded="pill"
+          prepend-icon="mdi-delete-sweep"
+          :disabled="!kindPreview.count"
+          :loading="kindCommitting"
+          @click="onKindCommit"
+        >Delete {{ kindPreview.count }} retired-kind tag(s)</v-btn>
+      </div>
     </v-card-text>
   </v-card>
 </template>
@@ -57,6 +97,9 @@ const store = useAdminStore()
 const preview = ref(null)
 const loadingPreview = ref(false)
 const committing = ref(false)
+const kindPreview = ref(null)
+const loadingKindPreview = ref(false)
+const kindCommitting = ref(false)
 
 async function onPreview() {
   loadingPreview.value = true
@@ -76,6 +119,25 @@ async function onCommit() {
     committing.value = false
   }
 }
+
+async function onKindPreview() {
+  loadingKindPreview.value = true
+  try {
+    kindPreview.value = await store.purgeRetiredKindTags({ dryRun: true })
+  } finally {
+    loadingKindPreview.value = false
+  }
+}
+
+async function onKindCommit() {
+  kindCommitting.value = true
+  try {
+    await store.purgeRetiredKindTags({ dryRun: false })
+    kindPreview.value = { count: 0, by_kind: {}, sample_names: [] }
+  } finally {
+    kindCommitting.value = false
+  }
+}
 </script>
 
 <style scoped>
diff --git a/frontend/src/stores/admin.js b/frontend/src/stores/admin.js
index 37eaf8c..2e915b3 100644
--- a/frontend/src/stores/admin.js
+++ b/frontend/src/stores/admin.js
@@ -114,6 +114,19 @@ export const useAdminStore = defineStore('admin', () => {
     }
   }
 
+  async function purgeRetiredKindTags({ dryRun = true } = {}) {
+    lastError.value = null
+    try {
+      return await api.post(
+        '/api/admin/tags/purge-retired-kinds',
+        { body: { dry_run: dryRun } },
+      )
+    } catch (e) {
+      lastError.value = e.message
+      throw e
+    }
+  }
+
   // --- Task progress polling (taps FC-3i activity dashboard) --------
 
   /**
@@ -148,6 +161,7 @@ export const useAdminStore = defineStore('admin', () => {
     mergeTags,
     tagUsageCount,
     pruneUnusedTags,
+    purgeRetiredKindTags,
     pollTaskUntilDone,
   }
 })
diff --git a/tests/test_api_admin.py b/tests/test_api_admin.py
index f1ed79c..dd74436 100644
--- a/tests/test_api_admin.py
+++ b/tests/test_api_admin.py
@@ -364,3 +364,53 @@ async def test_prune_unused_commit_deletes_and_returns_count(client, db):
     body = await resp.get_json()
     assert body["deleted"] >= 1
     assert "byebye" in body["sample_names"]
+
+
+@pytest.mark.asyncio
+async def test_purge_retired_kinds_dry_run_counts_by_kind(client, db):
+    db.add_all([
+        Tag(name="BlenderKnight:Hannah_BJ_Loops", kind=TagKind.archive),
+        Tag(name="BlenderKnight:May Animation", kind=TagKind.post),
+        Tag(name="SomeArtist", kind=TagKind.artist),
+        Tag(name="blonde hair", kind=TagKind.general),  # must survive
+    ])
+    await db.commit()
+
+    resp = await client.post(
+        "/api/admin/tags/purge-retired-kinds", json={"dry_run": True},
+    )
+    body = await resp.get_json()
+    assert body["count"] == 3
+    assert body["by_kind"] == {"archive": 1, "post": 1, "artist": 1}
+    assert "blonde hair" not in body["sample_names"]
+
+
+@pytest.mark.asyncio
+async def test_purge_retired_kinds_commit_deletes_only_retired(client, db):
+    from sqlalchemy import func, select
+
+    db.add_all([
+        Tag(name="arch1", kind=TagKind.archive),
+        Tag(name="post1", kind=TagKind.post),
+        Tag(name="keepme", kind=TagKind.general),
+        Tag(name="char1", kind=TagKind.character),
+    ])
+    await db.commit()
+
+    resp = await client.post(
+        "/api/admin/tags/purge-retired-kinds", json={"dry_run": False},
+    )
+    body = await resp.get_json()
+    assert body["deleted"] == 2
+
+    # general + character tags survive.
+    surviving = (await db.execute(
+        select(func.count()).select_from(Tag)
+        .where(Tag.kind.in_([TagKind.general, TagKind.character]))
+    )).scalar_one()
+    assert surviving >= 2
+    retired_left = (await db.execute(
+        select(func.count()).select_from(Tag)
+        .where(Tag.kind.in_([TagKind.archive, TagKind.post, TagKind.artist]))
+    )).scalar_one()
+    assert retired_left == 0

From bf8eb4468fd6bba1e5acb573c921290718d6f2f0 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 01:20:41 -0400
Subject: [PATCH 03/18] feat(tags): legacy-tag purge also catches source:*
 general tags
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operator-confirmed 2026-05-28: the BlenderKnight:* tags are `archive`
kind (caught by the kind purge), but the `source:patreon`-style tags
are IR's old `source` kind that fell back to `general` during migration
(FC's enum has no `source` kind) — so they can't be matched by kind.

Broadened the purge to a two-rule match and renamed it for accuracy
(all dev-only, unreleased):
- cleanup_service.purge_tags_by_kind → purge_legacy_tags. Predicate is
  now `kind IN (archive, post, artist) OR name LIKE 'source:%'`
  (LEGACY_NAME_PREFIXES). Preview classifies each row into by_kind OR
  by_prefix (source:* counts once under the prefix bucket regardless of
  its general kind).
- endpoint /tags/purge-retired-kinds → /tags/purge-legacy. dry-run
  returns by_kind + by_prefix + count + sample.
- store purgeRetiredKindTags → purgeLegacyTags.
- Tag Maintenance card copy + breakdown updated to show both buckets;
  button reads "Preview/Delete legacy tags".

Tests updated + extended: dry-run reports by_kind {archive,post,artist}
AND by_prefix {source:*}, plain general/character tags survive; commit
deletes both the kind-matched and source:*-matched rows and leaves the
rest.
---
 backend/app/api/admin.py                      | 20 ++---
 backend/app/services/cleanup_service.py       | 74 ++++++++++++-------
 .../settings/TagMaintenanceCard.vue           | 29 +++++---
 frontend/src/stores/admin.js                  |  6 +-
 tests/test_api_admin.py                       | 41 +++++-----
 5 files changed, 104 insertions(+), 66 deletions(-)

diff --git a/backend/app/api/admin.py b/backend/app/api/admin.py
index e6011b3..29820e8 100644
--- a/backend/app/api/admin.py
+++ b/backend/app/api/admin.py
@@ -6,6 +6,7 @@ Five action surfaces:
   DELETE /api/admin/tags/<int:tag_id>              (Tier B)
   POST   /api/admin/tags/<int:dest_id>/merge       (Tier B)
   POST   /api/admin/tags/prune-unused              (Tier A)
+  POST   /api/admin/tags/purge-legacy              (Tier A)
   GET    /api/admin/tags/<int:tag_id>/usage-count  (helper)
 
 Tier-C ops take a dry_run body flag (returns projection inline,
@@ -208,20 +209,21 @@ async def tags_prune_unused():
     return jsonify(result)
 
 
-@admin_bp.route("/tags/purge-retired-kinds", methods=["POST"])
-async def tags_purge_retired_kinds():
-    """Tier-A: delete tags whose kind is a system/legacy kind FC no
-    longer creates (archive / post / artist — the IR-migration leftovers
-    like `BlenderKnight:Hannah_BJ_Loops`). dry-run preview returns
-    per-kind counts + a sample so the UI can show exactly what'll go
-    before the operator confirms with dry_run=false."""
-    from ..services.cleanup_service import purge_tags_by_kind
+@admin_bp.route("/tags/purge-legacy", methods=["POST"])
+async def tags_purge_legacy():
+    """Tier-A: delete legacy IR-migration tags — archive/post/artist
+    kinds (e.g. `BlenderKnight:Hannah_BJ_Loops`) PLUS general tags with
+    a legacy name prefix (`source:*`, from IR's source kind that fell
+    back to general). dry-run preview returns per-kind + per-prefix
+    counts + a sample so the UI shows exactly what'll go before the
+    operator confirms with dry_run=false."""
+    from ..services.cleanup_service import purge_legacy_tags
 
     body = await request.get_json(silent=True) or {}
     dry_run = bool(body.get("dry_run", False))
 
     async with get_session() as session:
         result = await session.run_sync(
-            lambda sync_sess: purge_tags_by_kind(sync_sess, dry_run=dry_run)
+            lambda sync_sess: purge_legacy_tags(sync_sess, dry_run=dry_run)
         )
     return jsonify(result)
diff --git a/backend/app/services/cleanup_service.py b/backend/app/services/cleanup_service.py
index 4470d3f..dba9323 100644
--- a/backend/app/services/cleanup_service.py
+++ b/backend/app/services/cleanup_service.py
@@ -16,7 +16,7 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
-from sqlalchemy import func, select, update
+from sqlalchemy import func, or_, select, update
 from sqlalchemy.orm import Session
 
 from ..models import Artist, ImageRecord, LibraryAuditRun, Tag
@@ -369,46 +369,70 @@ def prune_unused_tags(session: Session, *, dry_run: bool = False) -> dict:
     return {"deleted": len(ids), "sample_names": sample}
 
 
-# System/legacy tag kinds that FC no longer creates: the tag input only
-# makes character/fandom/series/general; provenance (post grouping) and
-# archive membership are their own systems now, and artists are
-# first-class Artist/Source rows. These linger only on IR-migrated rows.
-# meta/rating were hard-deleted by alembic 0023, so they're not listed.
+# Legacy tags FC no longer uses, in two shapes:
+#   (1) kinds the tag input never produces — archive/post/artist.
+#       provenance (post grouping) + archive membership are their own
+#       systems now, and artists are first-class Artist/Source rows.
+#       meta/rating were already hard-deleted by alembic 0023.
+#   (2) name prefixes from IR kinds FC never adopted — `source:*`.
+#       ImageRepo had a `source` kind; FC's enum doesn't, so ir_ingest
+#       fell those back to `general` (kind=general, name="source:patreon"
+#       etc.). They can't be caught by kind, so we match the name prefix.
 PURGEABLE_TAG_KINDS = ("archive", "post", "artist")
+LEGACY_NAME_PREFIXES = ("source:",)
 
 
-def purge_tags_by_kind(
-    session: Session, *, kinds: tuple[str, ...] = PURGEABLE_TAG_KINDS,
-    dry_run: bool = False,
-) -> dict:
-    """Count (dry_run) or delete all tags whose kind is in `kinds`.
+def _legacy_tag_predicate():
+    name_clauses = [Tag.name.like(f"{p}%") for p in LEGACY_NAME_PREFIXES]
+    return or_(Tag.kind.in_(PURGEABLE_TAG_KINDS), *name_clauses)
+
+
+def purge_legacy_tags(session: Session, *, dry_run: bool = False) -> dict:
+    """Count (dry_run) or delete legacy IR-migration tags: archive/post/
+    artist-kind tags PLUS general tags whose name matches a legacy
+    prefix (source:*).
 
     CASCADE on image_tag / tag_alias / tag_allowlist /
     tag_reference_embedding / tag_suggestion_rejection / series_page
     clears the related rows on the parent DELETE.
 
     Returns:
-      {"by_kind": {kind: count, ...}, "count": total,
-       "sample_names": [first 50], and on live runs "deleted": total}
+      {"by_kind": {kind: count, ...},        # kind-matched rows
+       "by_prefix": {"source:*": count},     # name-prefix-matched rows
+       "count": total, "sample_names": [first 50],
+       and on live runs "deleted": total}
     """
+    predicate = _legacy_tag_predicate()
     rows = session.execute(
-        select(Tag.id, Tag.name, Tag.kind).where(Tag.kind.in_(kinds))
+        select(Tag.id, Tag.name, Tag.kind).where(predicate)
     ).all()
     by_kind: dict[str, int] = {}
-    for _id, _name, kind in rows:
-        key = kind.value if hasattr(kind, "value") else str(kind)
-        by_kind[key] = by_kind.get(key, 0) + 1
+    by_prefix: dict[str, int] = {}
+    for _id, name, kind in rows:
+        # Classify by name-prefix first so a source:* row counts once,
+        # under the prefix bucket, regardless of its (general) kind.
+        matched_prefix = next(
+            (p for p in LEGACY_NAME_PREFIXES if name.startswith(p)), None,
+        )
+        if matched_prefix is not None:
+            label = f"{matched_prefix}*"
+            by_prefix[label] = by_prefix.get(label, 0) + 1
+        else:
+            key = kind.value if hasattr(kind, "value") else str(kind)
+            by_kind[key] = by_kind.get(key, 0) + 1
     sample = [name for _id, name, _kind in rows[:50]]
     total = len(rows)
-    if dry_run:
-        return {"by_kind": by_kind, "count": total, "sample_names": sample}
-    if total:
-        session.execute(Tag.__table__.delete().where(Tag.kind.in_(kinds)))
-        session.commit()
-    return {
-        "by_kind": by_kind, "count": total, "deleted": total,
-        "sample_names": sample,
+    result = {
+        "by_kind": by_kind, "by_prefix": by_prefix,
+        "count": total, "sample_names": sample,
     }
+    if dry_run:
+        return result
+    if total:
+        session.execute(Tag.__table__.delete().where(predicate))
+        session.commit()
+    result["deleted"] = total
+    return result
 
 
 # ---------------------------------------------------------------------------
diff --git a/frontend/src/components/settings/TagMaintenanceCard.vue b/frontend/src/components/settings/TagMaintenanceCard.vue
index c19fef7..6ea69c8 100644
--- a/frontend/src/components/settings/TagMaintenanceCard.vue
+++ b/frontend/src/components/settings/TagMaintenanceCard.vue
@@ -48,12 +48,14 @@
       <v-divider class="my-5" />
 
       <p class="fc-muted text-body-2 mb-4">
-        Purge tags with retired/system kinds FC no longer uses
-        (<code>archive</code>, <code>post</code>, <code>artist</code>) —
-        IR-migration leftovers like
-        <code>BlenderKnight:Hannah_BJ_Loops</code>. Provenance and
-        artists are their own systems now, so these tag rows are pure
-        noise. Removes them from every image.
+        Purge legacy IR-migration tags FC no longer uses: retired/system
+        kinds (<code>archive</code>, <code>post</code>,
+        <code>artist</code> — e.g.
+        <code>BlenderKnight:Hannah_BJ_Loops</code>) plus
+        <code>source:*</code> tags (ImageRepo's old <code>source</code>
+        kind, which migrated to <code>general</code>). Provenance and
+        artists are their own systems now, so these are pure noise.
+        Removes them from every image.
       </p>
 
       <v-btn
@@ -62,14 +64,17 @@
         :loading="loadingKindPreview"
         class="mb-3"
         @click="onKindPreview"
-      >Preview retired-kind tags</v-btn>
+      >Preview legacy tags</v-btn>
 
       <div v-if="kindPreview">
         <p class="text-body-2 mb-2">
-          <strong>{{ kindPreview.count }}</strong> tag(s) of retired kinds.
+          <strong>{{ kindPreview.count }}</strong> legacy tag(s).
           <span v-for="(n, k) in kindPreview.by_kind" :key="k" class="fc-muted">
             {{ k }}: {{ n }}&nbsp;&nbsp;
           </span>
+          <span v-for="(n, p) in kindPreview.by_prefix" :key="p" class="fc-muted">
+            {{ p }}: {{ n }}&nbsp;&nbsp;
+          </span>
         </p>
         <div v-if="kindPreview.sample_names?.length" class="fc-name-grid mb-3">
           <span v-for="n in kindPreview.sample_names" :key="n" class="fc-name">
@@ -82,7 +87,7 @@
           :disabled="!kindPreview.count"
           :loading="kindCommitting"
           @click="onKindCommit"
-        >Delete {{ kindPreview.count }} retired-kind tag(s)</v-btn>
+        >Delete {{ kindPreview.count }} legacy tag(s)</v-btn>
       </div>
     </v-card-text>
   </v-card>
@@ -123,7 +128,7 @@ async function onCommit() {
 async function onKindPreview() {
   loadingKindPreview.value = true
   try {
-    kindPreview.value = await store.purgeRetiredKindTags({ dryRun: true })
+    kindPreview.value = await store.purgeLegacyTags({ dryRun: true })
   } finally {
     loadingKindPreview.value = false
   }
@@ -132,8 +137,8 @@ async function onKindPreview() {
 async function onKindCommit() {
   kindCommitting.value = true
   try {
-    await store.purgeRetiredKindTags({ dryRun: false })
-    kindPreview.value = { count: 0, by_kind: {}, sample_names: [] }
+    await store.purgeLegacyTags({ dryRun: false })
+    kindPreview.value = { count: 0, by_kind: {}, by_prefix: {}, sample_names: [] }
   } finally {
     kindCommitting.value = false
   }
diff --git a/frontend/src/stores/admin.js b/frontend/src/stores/admin.js
index 2e915b3..eb51ec9 100644
--- a/frontend/src/stores/admin.js
+++ b/frontend/src/stores/admin.js
@@ -114,11 +114,11 @@ export const useAdminStore = defineStore('admin', () => {
     }
   }
 
-  async function purgeRetiredKindTags({ dryRun = true } = {}) {
+  async function purgeLegacyTags({ dryRun = true } = {}) {
     lastError.value = null
     try {
       return await api.post(
-        '/api/admin/tags/purge-retired-kinds',
+        '/api/admin/tags/purge-legacy',
         { body: { dry_run: dryRun } },
       )
     } catch (e) {
@@ -161,7 +161,7 @@ export const useAdminStore = defineStore('admin', () => {
     mergeTags,
     tagUsageCount,
     pruneUnusedTags,
-    purgeRetiredKindTags,
+    purgeLegacyTags,
     pollTaskUntilDone,
   }
 })
diff --git a/tests/test_api_admin.py b/tests/test_api_admin.py
index dd74436..d778007 100644
--- a/tests/test_api_admin.py
+++ b/tests/test_api_admin.py
@@ -367,50 +367,57 @@ async def test_prune_unused_commit_deletes_and_returns_count(client, db):
 
 
 @pytest.mark.asyncio
-async def test_purge_retired_kinds_dry_run_counts_by_kind(client, db):
+async def test_purge_legacy_dry_run_counts_by_kind_and_prefix(client, db):
     db.add_all([
         Tag(name="BlenderKnight:Hannah_BJ_Loops", kind=TagKind.archive),
         Tag(name="BlenderKnight:May Animation", kind=TagKind.post),
         Tag(name="SomeArtist", kind=TagKind.artist),
+        # IR `source` kind fell back to general during migration —
+        # caught by the source:* name prefix, not by kind.
+        Tag(name="source:patreon", kind=TagKind.general),
         Tag(name="blonde hair", kind=TagKind.general),  # must survive
     ])
     await db.commit()
 
     resp = await client.post(
-        "/api/admin/tags/purge-retired-kinds", json={"dry_run": True},
+        "/api/admin/tags/purge-legacy", json={"dry_run": True},
     )
     body = await resp.get_json()
-    assert body["count"] == 3
+    assert body["count"] == 4
     assert body["by_kind"] == {"archive": 1, "post": 1, "artist": 1}
+    assert body["by_prefix"] == {"source:*": 1}
     assert "blonde hair" not in body["sample_names"]
+    assert "source:patreon" in body["sample_names"]
 
 
 @pytest.mark.asyncio
-async def test_purge_retired_kinds_commit_deletes_only_retired(client, db):
+async def test_purge_legacy_commit_deletes_only_legacy(client, db):
     from sqlalchemy import func, select
 
     db.add_all([
         Tag(name="arch1", kind=TagKind.archive),
-        Tag(name="post1", kind=TagKind.post),
+        Tag(name="source:fanbox", kind=TagKind.general),
         Tag(name="keepme", kind=TagKind.general),
         Tag(name="char1", kind=TagKind.character),
     ])
     await db.commit()
 
     resp = await client.post(
-        "/api/admin/tags/purge-retired-kinds", json={"dry_run": False},
+        "/api/admin/tags/purge-legacy", json={"dry_run": False},
     )
     body = await resp.get_json()
-    assert body["deleted"] == 2
+    assert body["deleted"] == 2  # arch1 + source:fanbox
 
-    # general + character tags survive.
-    surviving = (await db.execute(
-        select(func.count()).select_from(Tag)
-        .where(Tag.kind.in_([TagKind.general, TagKind.character]))
+    # The plain general + character tags survive.
+    keep = (await db.execute(
+        select(Tag.name).where(Tag.name.in_(["keepme", "char1"]))
+    )).scalars().all()
+    assert set(keep) == {"keepme", "char1"}
+    # No archive/post/artist or source:* left.
+    gone = (await db.execute(
+        select(func.count()).select_from(Tag).where(
+            (Tag.kind.in_([TagKind.archive, TagKind.post, TagKind.artist]))
+            | (Tag.name.like("source:%"))
+        )
     )).scalar_one()
-    assert surviving >= 2
-    retired_left = (await db.execute(
-        select(func.count()).select_from(Tag)
-        .where(Tag.kind.in_([TagKind.archive, TagKind.post, TagKind.artist]))
-    )).scalar_one()
-    assert retired_left == 0
+    assert gone == 0

From 56970fb66d24fd514c5e39e8a93a3c1a98e24a07 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 07:52:20 -0400
Subject: [PATCH 04/18] feat(credentials+downloads): real credential Verify
 button + live download-activity polling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operator-flagged 2026-05-28, two asks.

**1. Credential Verify (was missing vs GS — and now actually verifies).**
GS's Verify was a stub (`TODO: implement actual verification` — just
stamped last_verified). FC does a real check, which matters given the
recent auth pain (subscribestar age cookie, HF host-only PHPSESSID):

- GalleryDLService.verify(url, platform, cookies_path, auth_token) runs
  gallery-dl in `--simulate --range 1-1` mode (no download) against the
  URL with the materialized credentials, then reuses _categorize_error:
  returncode 0 / NO_NEW_CONTENT → valid; AUTH_ERROR → invalid; other →
  inconclusive (reason surfaced). 45s timeout.
- POST /api/credentials/<platform>/verify picks an enabled Source for
  the platform to probe, runs verify, and on success stamps
  credential.last_verified (new CredentialService.mark_verified).
  Returns {valid: bool|null, reason, last_verified?}. valid=null means
  untestable (no credential, or no enabled source to point at).
- CredentialCard gains a Verify button (on credentialed cards) + a
  result chip (Verified ✓ / Failed / Untestable) and a toast with the
  reason. SettingsTab reloads on @verified so last_verified refreshes.

**2. Live download-activity feedback.** The Downloads tab was static —
no way to tell if downloads were succeeding without manually hitting
Refresh. It now auto-polls: stats every 4s, and the event list too
while anything is queued/running. Polling pauses when the tab is
backgrounded (document.hidden) and the list reload is skipped on idle
ticks to stay light. A pulsing "● live" indicator next to the stat
chips shows when auto-refresh is active (queued+running > 0); honors
prefers-reduced-motion.

Tests: verify endpoint — untestable with no credential, untestable with
no enabled source, valid+stamped on success (gallery-dl mocked), and
auth-failure reported without stamping.
---
 backend/app/api/credentials.py                | 53 ++++++++++++
 backend/app/services/credential_service.py    | 15 +++-
 backend/app/services/gallery_dl.py            | 61 ++++++++++++++
 .../subscriptions/CredentialCard.vue          | 49 ++++++++++-
 .../components/subscriptions/DownloadsTab.vue | 50 +++++++++++-
 .../components/subscriptions/SettingsTab.vue  |  1 +
 frontend/src/stores/credentials.js            |  8 +-
 tests/test_api_credentials.py                 | 81 +++++++++++++++++++
 8 files changed, 312 insertions(+), 6 deletions(-)

diff --git a/backend/app/api/credentials.py b/backend/app/api/credentials.py
index 182792a..395846a 100644
--- a/backend/app/api/credentials.py
+++ b/backend/app/api/credentials.py
@@ -124,3 +124,56 @@ async def delete_credential(platform: str):
         except LookupError:
             return _bad("not_found", status=404)
     return "", 204
+
+
+@credentials_bp.route("/<platform>/verify", methods=["POST"])
+async def verify_credential(platform: str):
+    """Test the stored credential by running gallery-dl --simulate
+    against one of the platform's enabled sources. On success stamps
+    last_verified. Returns {valid: bool|null, reason, last_verified?}.
+    valid=null means "couldn't test" (no credential, or no enabled
+    source to point at)."""
+    from ..models import Artist, Source
+    from ..services.gallery_dl import GalleryDLService, SourceConfig
+
+    async with get_session() as session:
+        if not await _ext_key_ok(session):
+            return _bad("unauthorized", status=401)
+        svc = CredentialService(session, _get_crypto())
+        record = await svc.get(platform)
+        if record is None:
+            return jsonify({"valid": None, "reason": "No credential stored for this platform."})
+
+        # Pick an enabled source for this platform to point the probe at.
+        row = (await session.execute(
+            select(Source, Artist)
+            .join(Artist, Artist.id == Source.artist_id)
+            .where(Source.platform == platform, Source.enabled.is_(True))
+            .order_by(Source.id.asc())
+        )).first()
+        if row is None:
+            return jsonify({
+                "valid": None,
+                "reason": "No enabled source for this platform to verify against — add a subscription first.",
+            })
+        source, artist = row
+
+        cookies_path = await svc.get_cookies_path(platform)
+        auth_token = await svc.get_token(platform)
+
+    gdl = GalleryDLService(images_root=Path("/images"))
+    ok, message = await gdl.verify(
+        url=source.url,
+        artist_slug=artist.slug,
+        platform=platform,
+        source_config=SourceConfig.from_dict(source.config_overrides or {}),
+        cookies_path=str(cookies_path) if cookies_path else None,
+        auth_token=auth_token,
+    )
+
+    last_verified = None
+    if ok:
+        async with get_session() as session:
+            ts = await CredentialService(session, _get_crypto()).mark_verified(platform)
+            last_verified = ts.isoformat() if ts else None
+    return jsonify({"valid": ok, "reason": message, "last_verified": last_verified})
diff --git a/backend/app/services/credential_service.py b/backend/app/services/credential_service.py
index f467eb0..a8f6d8c 100644
--- a/backend/app/services/credential_service.py
+++ b/backend/app/services/credential_service.py
@@ -7,7 +7,7 @@ from __future__ import annotations
 import json
 import os
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import UTC, datetime
 from pathlib import Path
 
 from sqlalchemy import select
@@ -163,6 +163,19 @@ class CredentialService:
             return None
         return self.crypto.decrypt(row.encrypted_blob)
 
+    async def mark_verified(self, platform: str) -> datetime | None:
+        """Stamp last_verified=now after a successful verify. Returns the
+        timestamp, or None if the credential is gone."""
+        row = (await self.session.execute(
+            select(Credential).where(Credential.platform == platform)
+        )).scalar_one_or_none()
+        if row is None:
+            return None
+        ts = datetime.now(UTC)
+        row.last_verified = ts
+        await self.session.commit()
+        return ts
+
 
 def _augment_cookies(platform: str, netscape: str) -> str:
     """Delegate to the platform's `augment_cookies` hook if one is
diff --git a/backend/app/services/gallery_dl.py b/backend/app/services/gallery_dl.py
index 5e9b17f..497bcb4 100644
--- a/backend/app/services/gallery_dl.py
+++ b/backend/app/services/gallery_dl.py
@@ -658,3 +658,64 @@ class GalleryDLService:
                 Path(temp_config_path).unlink()  # noqa: ASYNC240
             except Exception:
                 pass
+
+    async def verify(
+        self,
+        url: str,
+        artist_slug: str,
+        platform: str,
+        source_config: SourceConfig | None = None,
+        cookies_path: str | None = None,
+        auth_token: str | None = None,
+        timeout: float = 45.0,
+    ) -> tuple[bool, str]:
+        """Test that credentials authenticate against `url` WITHOUT
+        downloading anything. Runs gallery-dl in --simulate mode limited
+        to the first item; if auth is bad the extractor errors before it
+        can list, which _categorize_error flags as AUTH_ERROR. Returns
+        (ok, message). Used by the credential Verify button."""
+        if source_config is None:
+            source_config = SourceConfig()
+        config = self._build_config_for_source(platform, source_config, artist_slug)
+        if cookies_path:
+            config["extractor"]["cookies"] = cookies_path
+        if auth_token and platform == "discord":
+            config["extractor"].setdefault("discord", {})["token"] = auth_token
+        if auth_token and platform == "pixiv":
+            config["extractor"].setdefault("pixiv", {})["refresh-token"] = auth_token
+
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".json", delete=False, dir=str(self._config_dir),
+        ) as fh:
+            json.dump(config, fh, indent=2)
+            temp_config_path = fh.name
+        try:
+            cmd = [
+                sys.executable, "-m", "gallery_dl",
+                "--config", temp_config_path,
+                "--simulate", "--range", "1-1", "--verbose", url,
+            ]
+            loop = asyncio.get_running_loop()
+            proc = await loop.run_in_executor(
+                None,
+                lambda: subprocess.run(
+                    cmd, capture_output=True, text=True, timeout=timeout,
+                ),
+            )
+            etype, msg = self._categorize_error(proc.returncode, proc.stdout, proc.stderr)
+            if proc.returncode == 0 or etype == ErrorType.NO_NEW_CONTENT:
+                return True, "Credentials valid — the feed authenticated."
+            if etype == ErrorType.AUTH_ERROR:
+                return False, msg
+            # Network / not-found / rate-limit / unknown: inconclusive,
+            # not a definitive credential failure. Surface the reason.
+            return False, f"Could not confirm ({etype.value}): {msg}"
+        except subprocess.TimeoutExpired:
+            return False, f"Verification timed out after {timeout:.0f}s"
+        except Exception as exc:  # noqa: BLE001
+            return False, f"Verification error: {exc}"
+        finally:
+            try:
+                Path(temp_config_path).unlink()  # noqa: ASYNC240
+            except Exception:
+                pass
diff --git a/frontend/src/components/subscriptions/CredentialCard.vue b/frontend/src/components/subscriptions/CredentialCard.vue
index 300b95e..0a1d834 100644
--- a/frontend/src/components/subscriptions/CredentialCard.vue
+++ b/frontend/src/components/subscriptions/CredentialCard.vue
@@ -55,7 +55,21 @@
     </v-card-text>
 
     <v-card-actions class="px-3 pb-3 pt-0">
-      <v-spacer />
+      <v-chip
+        v-if="verifyResult"
+        :color="verifyResult.valid === true ? 'success' : (verifyResult.valid === false ? 'error' : 'grey')"
+        size="x-small" variant="tonal" class="me-auto"
+        :title="verifyResult.reason"
+      >{{ verifyChipLabel }}</v-chip>
+      <v-spacer v-else />
+      <v-btn
+        v-if="hasCredential"
+        size="small" variant="text"
+        :loading="verifying"
+        @click="onVerify"
+      >
+        Verify
+      </v-btn>
       <v-btn
         v-if="hasCredential"
         size="small" variant="text" color="error"
@@ -76,14 +90,43 @@
 </template>
 
 <script setup>
-import { computed } from 'vue'
+import { computed, ref } from 'vue'
 import PlatformChip from './PlatformChip.vue'
+import { useCredentialsStore } from '../../stores/credentials.js'
 
 const props = defineProps({
   platform: { type: Object, required: true },
   credential: { type: Object, default: null },
 })
-defineEmits(['replace', 'remove'])
+const emit = defineEmits(['replace', 'remove', 'verified'])
+
+const credsStore = useCredentialsStore()
+const verifying = ref(false)
+const verifyResult = ref(null)
+
+const verifyChipLabel = computed(() => {
+  if (!verifyResult.value) return ''
+  if (verifyResult.value.valid === true) return 'Verified ✓'
+  if (verifyResult.value.valid === false) return 'Failed'
+  return 'Untestable'
+})
+
+async function onVerify() {
+  verifying.value = true
+  verifyResult.value = null
+  try {
+    const res = await credsStore.verify(props.platform.key)
+    verifyResult.value = res
+    const type = res.valid === true ? 'success' : (res.valid === false ? 'error' : 'info')
+    window.__fcToast?.({ text: `${props.platform.name}: ${res.reason}`, type })
+    if (res.valid === true) emit('verified')
+  } catch (e) {
+    verifyResult.value = { valid: false, reason: e.message }
+    window.__fcToast?.({ text: `Verify failed: ${e.message}`, type: 'error' })
+  } finally {
+    verifying.value = false
+  }
+}
 
 const hasCredential = computed(() => !!props.credential)
 
diff --git a/frontend/src/components/subscriptions/DownloadsTab.vue b/frontend/src/components/subscriptions/DownloadsTab.vue
index ecaa92b..750f9f6 100644
--- a/frontend/src/components/subscriptions/DownloadsTab.vue
+++ b/frontend/src/components/subscriptions/DownloadsTab.vue
@@ -2,6 +2,10 @@
   <div>
     <div class="fc-dl__top">
       <DownloadStatChips :stats="store.stats" />
+      <span v-if="liveActive" class="fc-dl__live" title="Auto-refreshing while downloads are active">
+        <span class="fc-dl__live-dot" />
+        live
+      </span>
       <v-spacer />
       <v-btn variant="text" icon @click="refresh">
         <v-icon>mdi-refresh</v-icon>
@@ -74,7 +78,7 @@
 </template>
 
 <script setup>
-import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { computed, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
 import { useRoute } from 'vue-router'
 
 import { useDownloadsStore } from '../../stores/downloads.js'
@@ -105,12 +109,39 @@ async function refresh() {
   ])
 }
 
+// Live auto-refresh: while any download is queued or running, poll the
+// stats + first page every 4s so the operator can watch events succeed/
+// fail in real time without hitting Refresh. Polling stops automatically
+// when the queue drains (nothing pending/running), and is paused while
+// the tab is backgrounded. Operator-flagged 2026-05-28: couldn't tell if
+// downloads were succeeding because the view was static.
+const POLL_MS = 4000
+const liveActive = computed(
+  () => (store.stats.pending || 0) + (store.stats.running || 0) > 0,
+)
+let pollId = null
+function startPolling() {
+  if (pollId) return
+  pollId = setInterval(async () => {
+    if (document.hidden) return
+    // Refresh stats cheaply every tick; only reload the event list when
+    // there's active work to reflect (keeps idle ticks light).
+    await store.loadStats(24)
+    if (liveActive.value) await store.loadFirst()
+  }, POLL_MS)
+}
+function stopPolling() {
+  if (pollId) { clearInterval(pollId); pollId = null }
+}
+
 onMounted(() => {
   if (route.query.source_id) {
     filterModel.value = { ...filterModel.value, source_id: Number(route.query.source_id) }
   }
   refresh()
+  startPolling()
 })
+onUnmounted(stopPolling)
 
 // Client-side date filter on the loaded page (avoids a backend round-trip
 // for the date pickers; the existing /api/downloads endpoint can grow
@@ -194,6 +225,23 @@ async function openDetail(id) {
   flex-wrap: wrap;
 }
 .fc-dl__filter { margin-bottom: 12px; }
+.fc-dl__live {
+  display: inline-flex; align-items: center; gap: 5px;
+  font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.06em;
+  color: rgb(var(--v-theme-info));
+}
+.fc-dl__live-dot {
+  width: 7px; height: 7px; border-radius: 50%;
+  background: rgb(var(--v-theme-info));
+  animation: fc-dl-pulse 1.4s ease-in-out infinite;
+}
+@keyframes fc-dl-pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50% { opacity: 0.35; transform: scale(0.7); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .fc-dl__live-dot { animation: none; }
+}
 .fc-dl__loading, .fc-dl__empty {
   display: flex; justify-content: center; padding: 3rem 0;
   color: rgb(var(--v-theme-on-surface-variant));
diff --git a/frontend/src/components/subscriptions/SettingsTab.vue b/frontend/src/components/subscriptions/SettingsTab.vue
index cc1be56..5b6c3b2 100644
--- a/frontend/src/components/subscriptions/SettingsTab.vue
+++ b/frontend/src/components/subscriptions/SettingsTab.vue
@@ -18,6 +18,7 @@
           :credential="credentialsStore.byPlatform.get(p.key) || null"
           @replace="openUpload"
           @remove="confirmRemove"
+          @verified="onSaved"
         />
       </v-col>
     </v-row>
diff --git a/frontend/src/stores/credentials.js b/frontend/src/stores/credentials.js
index 33f9274..8fbf4ae 100644
--- a/frontend/src/stores/credentials.js
+++ b/frontend/src/stores/credentials.js
@@ -38,6 +38,12 @@ export const useCredentialsStore = defineStore('credentials', () => {
     byPlatform.value.delete(platform)
   }
 
+  // Runs gallery-dl --simulate against an enabled source for the
+  // platform. Returns {valid: bool|null, reason, last_verified?}.
+  async function verify(platform) {
+    return await api.post(`/api/credentials/${platform}/verify`)
+  }
+
   async function loadKey() {
     const body = await api.get('/api/settings/extension_api_key')
     extensionKey.value = body.key
@@ -50,6 +56,6 @@ export const useCredentialsStore = defineStore('credentials', () => {
 
   return {
     byPlatform, extensionKey, loading, error,
-    loadAll, upload, remove, loadKey, rotateKey,
+    loadAll, upload, remove, verify, loadKey, rotateKey,
   }
 })
diff --git a/tests/test_api_credentials.py b/tests/test_api_credentials.py
index 7c5b5a0..cd4651b 100644
--- a/tests/test_api_credentials.py
+++ b/tests/test_api_credentials.py
@@ -143,3 +143,84 @@ async def test_extension_key_wrong_rejects(client, ext_key):
         headers={"X-Extension-Key": "WRONG"},
     )
     assert resp.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_verify_no_credential_is_untestable(client):
+    resp = await client.post("/api/credentials/patreon/verify")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body["valid"] is None
+    assert "No credential" in body["reason"]
+
+
+@pytest.mark.asyncio
+async def test_verify_no_enabled_source_is_untestable(client):
+    await client.post("/api/credentials", json={
+        "platform": "patreon", "credential_type": "cookies", "data": _NETSCAPE,
+    })
+    resp = await client.post("/api/credentials/patreon/verify")
+    body = await resp.get_json()
+    assert body["valid"] is None
+    assert "no enabled source" in body["reason"].lower()
+
+
+@pytest.mark.asyncio
+async def test_verify_runs_gallery_dl_and_stamps_on_success(client, db, monkeypatch):
+    from backend.app.models import Artist, Source
+    from backend.app.services import gallery_dl as gdl_mod
+
+    # Stub the gallery-dl probe so the test doesn't shell out / hit network.
+    async def _fake_verify(self, *args, **kwargs):
+        return (True, "Credentials valid — the feed authenticated.")
+    monkeypatch.setattr(gdl_mod.GalleryDLService, "verify", _fake_verify)
+
+    await client.post("/api/credentials", json={
+        "platform": "patreon", "credential_type": "cookies", "data": _NETSCAPE,
+    })
+    artist = Artist(name="Maewix", slug="maewix")
+    db.add(artist)
+    await db.flush()
+    db.add(Source(
+        artist_id=artist.id, platform="patreon",
+        url="https://www.patreon.com/maewix", enabled=True, config_overrides={},
+    ))
+    await db.commit()
+
+    resp = await client.post("/api/credentials/patreon/verify")
+    body = await resp.get_json()
+    assert body["valid"] is True
+    assert body["last_verified"] is not None
+
+    # The stamp is persisted on the credential record.
+    rec = await (await client.get("/api/credentials/patreon")).get_json()
+    assert rec["last_verified"] is not None
+
+
+@pytest.mark.asyncio
+async def test_verify_reports_auth_failure(client, db, monkeypatch):
+    from backend.app.models import Artist, Source
+    from backend.app.services import gallery_dl as gdl_mod
+
+    async def _fake_verify(self, *args, **kwargs):
+        return (False, "Authentication failed — cookies may be expired or invalid")
+    monkeypatch.setattr(gdl_mod.GalleryDLService, "verify", _fake_verify)
+
+    await client.post("/api/credentials", json={
+        "platform": "hentaifoundry", "credential_type": "cookies", "data": _NETSCAPE,
+    })
+    artist = Artist(name="HolyMeh", slug="holymeh")
+    db.add(artist)
+    await db.flush()
+    db.add(Source(
+        artist_id=artist.id, platform="hentaifoundry",
+        url="https://www.hentai-foundry.com/user/HolyMeh", enabled=True,
+        config_overrides={},
+    ))
+    await db.commit()
+
+    resp = await client.post("/api/credentials/hentaifoundry/verify")
+    body = await resp.get_json()
+    assert body["valid"] is False
+    assert "auth" in body["reason"].lower()
+    assert body["last_verified"] is None

From 73520b7cc3dd626a809192a23d967f450088e162 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 07:54:40 -0400
Subject: [PATCH 05/18] feat(downloads): copy buttons in the download detail
 modal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operator-flagged 2026-05-28: the download event detail modal had no way
to copy the error / stdout / stderr text for researching a failure
(parity with the ErrorDetailModal Copy button shipped in v26.05.26.0).

Added per-block Copy buttons (Error, Errors & warnings, Raw stdout, Raw
stderr — the stdout/stderr ones sit in the expansion-panel title with
@click.stop so they don't toggle the panel) plus a "Copy all
diagnostics" button in the footer that assembles a single block: header
line (event id / platform / artist / status / timestamps) + error +
errors&warnings + full stdout + stderr, ready to paste into an issue.

All routed through utils/clipboard.js copyText() — the navigator.clipboard
→ execCommand fallback that works on the plain-HTTP homelab origin
(per feedback_no_secure_context_apis). Each copy shows a confirmation
toast.
---
 .../downloads/DownloadDetailModal.vue         | 75 ++++++++++++++++++-
 1 file changed, 72 insertions(+), 3 deletions(-)

diff --git a/frontend/src/components/downloads/DownloadDetailModal.vue b/frontend/src/components/downloads/DownloadDetailModal.vue
index 5ee4823..35bb921 100644
--- a/frontend/src/components/downloads/DownloadDetailModal.vue
+++ b/frontend/src/components/downloads/DownloadDetailModal.vue
@@ -35,20 +35,53 @@
           </ul>
         </template>
 
+        <template v-if="event.error">
+          <div class="fc-dl-blockhead mt-4">
+            <h3 class="text-subtitle-2">Error</h3>
+            <v-btn
+              size="x-small" variant="text" prepend-icon="mdi-content-copy"
+              @click="onCopy('Error', event.error)"
+            >Copy</v-btn>
+          </div>
+          <pre class="fc-dl-pre">{{ event.error }}</pre>
+        </template>
+
         <template v-if="errorsWarnings">
-          <h3 class="text-subtitle-2 mt-4">Errors &amp; warnings</h3>
+          <div class="fc-dl-blockhead mt-4">
+            <h3 class="text-subtitle-2">Errors &amp; warnings</h3>
+            <v-btn
+              size="x-small" variant="text" prepend-icon="mdi-content-copy"
+              @click="onCopy('Errors & warnings', errorsWarnings)"
+            >Copy</v-btn>
+          </div>
           <pre class="fc-dl-pre">{{ errorsWarnings }}</pre>
         </template>
 
         <v-expansion-panels class="mt-4">
           <v-expansion-panel>
-            <v-expansion-panel-title>Raw stdout</v-expansion-panel-title>
+            <v-expansion-panel-title>
+              <span>Raw stdout</span>
+              <v-spacer />
+              <v-btn
+                size="x-small" variant="text" prepend-icon="mdi-content-copy"
+                class="me-2"
+                @click.stop="onCopy('stdout', event.metadata?.stdout || '')"
+              >Copy</v-btn>
+            </v-expansion-panel-title>
             <v-expansion-panel-text>
               <pre class="fc-dl-pre">{{ event.metadata?.stdout || '(empty)' }}</pre>
             </v-expansion-panel-text>
           </v-expansion-panel>
           <v-expansion-panel>
-            <v-expansion-panel-title>Raw stderr</v-expansion-panel-title>
+            <v-expansion-panel-title>
+              <span>Raw stderr</span>
+              <v-spacer />
+              <v-btn
+                size="x-small" variant="text" prepend-icon="mdi-content-copy"
+                class="me-2"
+                @click.stop="onCopy('stderr', event.metadata?.stderr || '')"
+              >Copy</v-btn>
+            </v-expansion-panel-title>
             <v-expansion-panel-text>
               <pre class="fc-dl-pre">{{ event.metadata?.stderr || '(empty)' }}</pre>
             </v-expansion-panel-text>
@@ -56,6 +89,10 @@
         </v-expansion-panels>
       </v-card-text>
       <v-card-actions>
+        <v-btn
+          variant="text" prepend-icon="mdi-content-copy"
+          @click="onCopy('All diagnostics', allDiagnostics)"
+        >Copy all diagnostics</v-btn>
         <v-spacer />
         <v-btn variant="text" @click="onClose(false)">Close</v-btn>
       </v-card-actions>
@@ -66,6 +103,8 @@
 <script setup>
 import { computed } from 'vue'
 
+import { copyText } from '../../utils/clipboard.js'
+
 const props = defineProps({ event: { type: Object, default: null } })
 const emit = defineEmits(['close'])
 
@@ -74,6 +113,32 @@ const summary = computed(() => props.event?.metadata?.import_summary || {})
 const quarantinedPaths = computed(() => props.event?.metadata?.quarantined_paths || [])
 const errorsWarnings = computed(() => props.event?.metadata?.stderr_errors_warnings || '')
 
+// One combined block for "research the issue elsewhere" — header line +
+// error + full stdout/stderr. Built lazily from the current event.
+const allDiagnostics = computed(() => {
+  const e = props.event
+  if (!e) return ''
+  const md = e.metadata || {}
+  return [
+    `event #${e.id} · ${e.platform || '—'} · ${e.artist_name || '—'}`,
+    `status: ${e.status}`,
+    `started: ${e.started_at}  finished: ${e.finished_at || '(running)'}`,
+    e.error ? `\n--- error ---\n${e.error}` : '',
+    errorsWarnings.value ? `\n--- errors & warnings ---\n${errorsWarnings.value}` : '',
+    `\n--- stdout ---\n${md.stdout || '(empty)'}`,
+    `\n--- stderr ---\n${md.stderr || '(empty)'}`,
+  ].filter(Boolean).join('\n')
+})
+
+async function onCopy(label, text) {
+  try {
+    await copyText(text || '')
+    window.__fcToast?.({ text: `${label} copied`, type: 'success' })
+  } catch (e) {
+    window.__fcToast?.({ text: `Copy failed: ${e.message}`, type: 'error' })
+  }
+}
+
 const statusColor = computed(() => ({
   ok: 'success', error: 'error', running: 'info',
   pending: 'secondary', skipped: 'warning',
@@ -114,4 +179,8 @@ function onClose() {
   word-break: break-all;
 }
 .fc-dl-quar { padding-left: 1.5rem; font-size: 0.85rem; }
+.fc-dl-blockhead {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 0.5rem;
+}
 </style>

From a459d21a6510ba0c91fd9598ea576d846bc52686 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 08:10:04 -0400
Subject: [PATCH 06/18] feat(dashboards): 1600px max-width, richer Downloads
 filters, needs-attention + sticky headers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operator-flagged 2026-05-28: the Subscriptions/Downloads dashboards were
full-bleed and thin on filtering. Chosen via AskUserQuestion.

**Layout**
- SubscriptionsView capped at a centered max-width 1600px (covers all
  three subtabs) so rows aren't a mile wide on ultrawide monitors.
- Sticky control headers on both tabs (top: 48px, below the top nav,
  opaque bg) so filters/stat-chips stay reachable while scrolling a
  long list.

**Downloads filters (all four requested)**
- Stat chips are now clickable filters: click Queued/Running/Completed/
  Failed/Skipped to filter the list to that status; the active chip is
  outlined + elevated; re-click clears.
- Free-text search box over the loaded events (artist / platform /
  error substring).
- Artist filter: the filter popover's numeric "Source ID" field is
  replaced with an artist autocomplete (sources.autocompleteArtist →
  artist_id, which /api/downloads already supports). Pill shows the
  artist name.
- "Show no-change scans" toggle (default OFF): hides status=ok/skipped
  rows with 0 files (the scheduled scans that found nothing) so real
  downloads + failures stand out.

**Subscriptions**
- "Needs attention" quick-filter chip: one click to show only artists
  with sources that have errors OR have never been checked; chip shows
  the count and disables the status dropdown while active.

Frontend-only — backend filter params (status/artist_id/date) and the
/api/downloads endpoint already supported everything.
---
 .../subscriptions/DownloadStatChips.vue       | 13 ++-
 .../subscriptions/DownloadsFilterPopover.vue  | 64 ++++++++++---
 .../components/subscriptions/DownloadsTab.vue | 95 +++++++++++++++----
 .../subscriptions/SubscriptionsTab.vue        | 36 ++++++-
 frontend/src/views/SubscriptionsView.vue      |  8 +-
 5 files changed, 184 insertions(+), 32 deletions(-)

diff --git a/frontend/src/components/subscriptions/DownloadStatChips.vue b/frontend/src/components/subscriptions/DownloadStatChips.vue
index ce5c975..e2e3ab1 100644
--- a/frontend/src/components/subscriptions/DownloadStatChips.vue
+++ b/frontend/src/components/subscriptions/DownloadStatChips.vue
@@ -3,9 +3,11 @@
     <v-chip
       v-for="s in STAT_DEFS" :key="s.key"
       :color="s.color"
-      variant="tonal"
+      :variant="activeStatus === s.key ? 'elevated' : 'tonal'"
       :prepend-icon="s.icon"
       size="default"
+      :class="{ 'fc-dl-stats__active': activeStatus === s.key }"
+      @click="$emit('select', activeStatus === s.key ? null : s.key)"
     >
       {{ s.label }}
       <strong class="ms-1">{{ stats[s.key] ?? 0 }}</strong>
@@ -16,7 +18,11 @@
 <script setup>
 defineProps({
   stats: { type: Object, required: true },
+  // The currently-active status filter key (pending|running|ok|error|
+  // skipped) or null. Highlights the matching chip.
+  activeStatus: { type: String, default: null },
 })
+defineEmits(['select'])
 
 // status keys come straight from the backend ENUM
 // (pending|running|ok|error|skipped); display order + icons are UI-only.
@@ -33,4 +39,9 @@ const STAT_DEFS = [
 .fc-dl-stats {
   display: flex; gap: 8px; flex-wrap: wrap;
 }
+.fc-dl-stats .v-chip { cursor: pointer; }
+.fc-dl-stats__active {
+  outline: 2px solid rgb(var(--v-theme-on-surface) / 0.5);
+  outline-offset: 1px;
+}
 </style>
diff --git a/frontend/src/components/subscriptions/DownloadsFilterPopover.vue b/frontend/src/components/subscriptions/DownloadsFilterPopover.vue
index 57b8253..4ba8e24 100644
--- a/frontend/src/components/subscriptions/DownloadsFilterPopover.vue
+++ b/frontend/src/components/subscriptions/DownloadsFilterPopover.vue
@@ -9,7 +9,7 @@
           </v-chip>
         </v-btn>
       </template>
-      <v-card min-width="320" class="pa-3">
+      <v-card min-width="340" class="pa-3">
         <v-select
           v-model="local.status"
           :items="STATUS_OPTIONS"
@@ -17,12 +17,17 @@
           density="compact" variant="outlined" hide-details clearable
           class="mb-2"
         />
-        <v-text-field
-          v-model.number="local.source_id"
-          label="Source ID"
+        <v-autocomplete
+          v-model="local.artist_id"
+          :items="artistItems"
+          :loading="artistLoading"
+          label="Artist"
+          item-title="name" item-value="id"
           density="compact" variant="outlined" hide-details clearable
-          type="number" min="1"
+          no-filter
           class="mb-2"
+          @update:search="onArtistSearch"
+          @update:model-value="onArtistPick"
         />
         <v-text-field
           v-model="local.from_date"
@@ -62,11 +67,15 @@
 <script setup>
 import { computed, reactive, ref, watch } from 'vue'
 
+import { useSourcesStore } from '../../stores/sources.js'
+
 const props = defineProps({
   modelValue: { type: Object, required: true },
 })
 const emit = defineEmits(['update:modelValue'])
 
+const sourcesStore = useSourcesStore()
+
 const STATUS_OPTIONS = [
   { title: 'Queued',    value: 'pending' },
   { title: 'Running',   value: 'running' },
@@ -78,18 +87,43 @@ const STATUS_LABEL = Object.fromEntries(STATUS_OPTIONS.map((o) => [o.value, o.ti
 
 const open = ref(false)
 const local = reactive({
-  status:    props.modelValue.status ?? null,
-  source_id: props.modelValue.source_id ?? null,
-  from_date: props.modelValue.from_date ?? null,
-  to_date:   props.modelValue.to_date ?? null,
+  status:      props.modelValue.status ?? null,
+  artist_id:   props.modelValue.artist_id ?? null,
+  artist_name: props.modelValue.artist_name ?? null,
+  from_date:   props.modelValue.from_date ?? null,
+  to_date:     props.modelValue.to_date ?? null,
 })
 
 watch(() => props.modelValue, (v) => Object.assign(local, v), { deep: true })
 
+// Artist autocomplete for the filter (replaces the old numeric Source-ID
+// field — operator-flagged 2026-05-28). Keeps the currently-selected
+// artist in the items list so the chip label resolves even before a
+// search runs.
+const artistItems = ref([])
+const artistLoading = ref(false)
+let artistDebounce = null
+function onArtistSearch(q) {
+  if (artistDebounce) clearTimeout(artistDebounce)
+  if (!q || !q.trim()) { return }
+  artistDebounce = setTimeout(async () => {
+    artistLoading.value = true
+    try {
+      artistItems.value = await sourcesStore.autocompleteArtist(q.trim(), 20)
+    } finally {
+      artistLoading.value = false
+    }
+  }, 250)
+}
+function onArtistPick(id) {
+  const hit = artistItems.value.find((a) => a.id === id)
+  local.artist_name = hit ? hit.name : null
+}
+
 const activePills = computed(() => {
   const out = []
   if (local.status)    out.push({ key: 'status',    label: `Status: ${STATUS_LABEL[local.status] || local.status}` })
-  if (local.source_id) out.push({ key: 'source_id', label: `Source #${local.source_id}` })
+  if (local.artist_id) out.push({ key: 'artist_id', label: `Artist: ${local.artist_name || `#${local.artist_id}`}` })
   if (local.from_date) out.push({ key: 'from_date', label: `From ${local.from_date}` })
   if (local.to_date)   out.push({ key: 'to_date',   label: `To ${local.to_date}` })
   return out
@@ -102,13 +136,19 @@ function apply() {
 }
 function reset() {
   local.status = null
-  local.source_id = null
+  local.artist_id = null
+  local.artist_name = null
   local.from_date = null
   local.to_date = null
   emit('update:modelValue', { ...local })
 }
 function clearOne(key) {
-  local[key] = null
+  if (key === 'artist_id') {
+    local.artist_id = null
+    local.artist_name = null
+  } else {
+    local[key] = null
+  }
   emit('update:modelValue', { ...local })
 }
 </script>
diff --git a/frontend/src/components/subscriptions/DownloadsTab.vue b/frontend/src/components/subscriptions/DownloadsTab.vue
index 750f9f6..98dce0d 100644
--- a/frontend/src/components/subscriptions/DownloadsTab.vue
+++ b/frontend/src/components/subscriptions/DownloadsTab.vue
@@ -1,20 +1,41 @@
 <template>
   <div>
-    <div class="fc-dl__top">
-      <DownloadStatChips :stats="store.stats" />
-      <span v-if="liveActive" class="fc-dl__live" title="Auto-refreshing while downloads are active">
-        <span class="fc-dl__live-dot" />
-        live
-      </span>
-      <v-spacer />
-      <v-btn variant="text" icon @click="refresh">
-        <v-icon>mdi-refresh</v-icon>
-        <v-tooltip activator="parent" location="top">Refresh</v-tooltip>
-      </v-btn>
-      <MaintenanceMenu @refresh="refresh" />
-    </div>
+    <div class="fc-dl__sticky">
+      <div class="fc-dl__top">
+        <DownloadStatChips
+          :stats="store.stats"
+          :active-status="filterModel.status"
+          @select="onStatusChipSelect"
+        />
+        <span v-if="liveActive" class="fc-dl__live" title="Auto-refreshing while downloads are active">
+          <span class="fc-dl__live-dot" />
+          live
+        </span>
+        <v-spacer />
+        <v-btn variant="text" icon @click="refresh">
+          <v-icon>mdi-refresh</v-icon>
+          <v-tooltip activator="parent" location="top">Refresh</v-tooltip>
+        </v-btn>
+        <MaintenanceMenu @refresh="refresh" />
+      </div>
 
-    <DownloadsFilterPopover v-model="filterModel" class="fc-dl__filter" />
+      <div class="fc-dl__controls">
+        <v-text-field
+          v-model="search"
+          density="compact" variant="outlined" hide-details clearable
+          prepend-inner-icon="mdi-magnify"
+          placeholder="Search artist / platform / error"
+          style="max-width: 340px"
+        />
+        <DownloadsFilterPopover v-model="filterModel" />
+        <v-switch
+          v-model="showNoChange"
+          label="Show no-change scans"
+          density="compact" hide-details color="accent"
+          class="fc-dl__nochange"
+        />
+      </div>
+    </div>
 
     <v-alert v-if="store.error" type="error" variant="tonal" closable class="my-4">
       {{ String(store.error) }}
@@ -92,6 +113,17 @@ const route = useRoute()
 const store = useDownloadsStore()
 const filterModel = ref({ ...store.filter })
 
+// Free-text search (client-side over the loaded events) + a toggle to
+// hide "no-change" scheduled scans (status=ok/skipped with 0 files) so
+// real downloads + failures stand out. Operator-flagged 2026-05-28.
+const search = ref('')
+const showNoChange = ref(false)
+
+// Clicking a stat chip toggles a status filter (re-click clears it).
+function onStatusChipSelect(statusKey) {
+  filterModel.value = { ...filterModel.value, status: statusKey }
+}
+
 // Each group's collapsed state persists across refreshes for the
 // lifetime of the SubscriptionsView (operator-friendly default: all
 // expanded; collapse what you don't care about right now).
@@ -158,6 +190,21 @@ const filteredEvents = computed(() => {
     const toTs = new Date(to).getTime() + 24 * 3600 * 1000 - 1
     arr = arr.filter((e) => new Date(e.started_at).getTime() <= toTs)
   }
+  // Hide no-change scheduled scans (succeeded/skipped, downloaded
+  // nothing) unless the operator opts to show them.
+  if (!showNoChange.value) {
+    arr = arr.filter(
+      (e) => !((e.status === 'ok' || e.status === 'skipped') && !(e.files_count > 0)),
+    )
+  }
+  const q = search.value?.trim().toLowerCase()
+  if (q) {
+    arr = arr.filter((e) =>
+      (e.artist_name || '').toLowerCase().includes(q)
+      || (e.platform || '').toLowerCase().includes(q)
+      || (e.error || '').toLowerCase().includes(q),
+    )
+  }
   return arr
 })
 
@@ -207,6 +254,7 @@ watch(filterModel, async (m) => {
   await store.applyFilter({
     status: m.status,
     source_id: m.source_id || null,
+    artist_id: m.artist_id || null,
     from_date: m.from_date,
     to_date: m.to_date,
   })
@@ -219,12 +267,27 @@ async function openDetail(id) {
 </script>
 
 <style scoped>
+/* Sticky control header: stat chips + search + filter + toggle stay
+   pinned below the top nav while the event feed scrolls. Opaque
+   background so rows don't bleed through. */
+.fc-dl__sticky {
+  position: sticky;
+  top: 48px;
+  z-index: 3;
+  background: rgb(var(--v-theme-background));
+  padding: 8px 0 10px;
+  margin-bottom: 4px;
+  border-bottom: 1px solid rgb(var(--v-theme-on-surface-variant) / 0.12);
+}
 .fc-dl__top {
   display: flex; gap: 8px; align-items: center;
-  margin-bottom: 12px;
+  margin-bottom: 10px;
   flex-wrap: wrap;
 }
-.fc-dl__filter { margin-bottom: 12px; }
+.fc-dl__controls {
+  display: flex; gap: 12px; align-items: center; flex-wrap: wrap;
+}
+.fc-dl__nochange { flex: 0 0 auto; }
 .fc-dl__live {
   display: inline-flex; align-items: center; gap: 5px;
   font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.06em;
diff --git a/frontend/src/components/subscriptions/SubscriptionsTab.vue b/frontend/src/components/subscriptions/SubscriptionsTab.vue
index 96ac883..5d3b04e 100644
--- a/frontend/src/components/subscriptions/SubscriptionsTab.vue
+++ b/frontend/src/components/subscriptions/SubscriptionsTab.vue
@@ -7,10 +7,22 @@
       <v-btn variant="outlined" prepend-icon="mdi-account-plus" @click="showArtistDialog = true">
         New artist
       </v-btn>
+      <v-chip
+        :color="needsAttention ? 'error' : undefined"
+        :variant="needsAttention ? 'flat' : 'outlined'"
+        prepend-icon="mdi-alert-circle-outline"
+        @click="needsAttention = !needsAttention"
+      >
+        Needs attention
+        <v-chip v-if="attentionCount" size="x-small" class="ms-2" variant="tonal">
+          {{ attentionCount }}
+        </v-chip>
+      </v-chip>
       <v-spacer />
       <v-select
         v-model="statusFilter"
         :items="STATUS_OPTIONS"
+        :disabled="needsAttention"
         density="compact" variant="outlined" hide-details
         style="max-width: 180px"
       />
@@ -218,6 +230,7 @@ const importStore = useImportStore()
 
 const search = ref('')
 const statusFilter = ref('all')
+const needsAttention = ref(false)
 const expanded = ref([])
 const selected = ref([])
 const showSourceDialog = ref(false)
@@ -277,12 +290,23 @@ const groups = computed(() => {
   })
 })
 
+// A group "needs attention" if any of its sources has accumulated
+// failures OR has never been checked — the ones worth acting on.
+function groupNeedsAttention(g) {
+  return groupMatchesStatus(g, 'errors') || groupMatchesStatus(g, 'stale')
+}
+const attentionCount = computed(
+  () => groups.value.filter(groupNeedsAttention).length,
+)
+
 const filteredGroups = computed(() => {
   let arr = groups.value
   if (artistFilter.value != null) {
     arr = arr.filter((g) => g.artist.id === artistFilter.value)
   }
-  if (statusFilter.value !== 'all') {
+  if (needsAttention.value) {
+    arr = arr.filter(groupNeedsAttention)
+  } else if (statusFilter.value !== 'all') {
     arr = arr.filter((g) => groupMatchesStatus(g, statusFilter.value))
   }
   const q = search.value?.trim().toLowerCase()
@@ -478,9 +502,17 @@ async function bulkDelete() {
 <style scoped>
 .fc-subs__bar {
   display: flex; gap: 0.75rem; align-items: center;
-  padding-bottom: 1rem;
   flex-wrap: wrap;
+  /* Sticky below the top nav so the filter/search controls stay
+     reachable while scrolling a long subscription list. Opaque bg so
+     table rows don't bleed through. Operator-flagged 2026-05-28. */
+  position: sticky;
+  top: 48px;
+  z-index: 3;
+  background: rgb(var(--v-theme-background));
+  padding: 8px 0 1rem;
 }
+.fc-subs__bar .v-chip { cursor: pointer; }
 .fc-subs__loading, .fc-subs__empty {
   display: flex; justify-content: center; padding: 2rem;
   color: rgb(var(--v-theme-on-surface-variant));
diff --git a/frontend/src/views/SubscriptionsView.vue b/frontend/src/views/SubscriptionsView.vue
index 67df3ab..7b1105c 100644
--- a/frontend/src/views/SubscriptionsView.vue
+++ b/frontend/src/views/SubscriptionsView.vue
@@ -1,5 +1,5 @@
 <template>
-  <v-container fluid class="pt-2 pb-6">
+  <v-container fluid class="pt-2 pb-6 fc-subs-shell">
     <v-tabs
       v-model="tab"
       align-tabs="start"
@@ -65,6 +65,12 @@ watch(() => route.query.tab, (q) => {
 </script>
 
 <style scoped>
+/* Cap the dashboards at a centered 1600px so rows aren't a mile wide on
+   wide/ultrawide monitors (operator-flagged 2026-05-28). */
+.fc-subs-shell {
+  max-width: 1600px;
+  margin-inline: auto;
+}
 .fc-subs-tabs {
   border-bottom: 1px solid rgb(var(--v-theme-on-surface-variant) / 0.18);
 }

From 215a8993a151d4543ef04bbf0b5010ae54148a92 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 08:18:33 -0400
Subject: [PATCH 07/18] fix(lint): noqa ASYNC109 on gallery_dl.verify timeout
 (subprocess.run deadline, not coroutine)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 backend/app/services/gallery_dl.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/backend/app/services/gallery_dl.py b/backend/app/services/gallery_dl.py
index 497bcb4..e149477 100644
--- a/backend/app/services/gallery_dl.py
+++ b/backend/app/services/gallery_dl.py
@@ -667,7 +667,7 @@ class GalleryDLService:
         source_config: SourceConfig | None = None,
         cookies_path: str | None = None,
         auth_token: str | None = None,
-        timeout: float = 45.0,
+        timeout: float = 45.0,  # noqa: ASYNC109 — subprocess.run timeout, not a coroutine deadline
     ) -> tuple[bool, str]:
         """Test that credentials authenticate against `url` WITHOUT
         downloading anything. Runs gallery-dl in --simulate mode limited

From 2358cedf3e61e4bf0010fd7a65a081f6148cf05d Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 08:30:14 -0400
Subject: [PATCH 08/18] feat(dashboards): scheduler health strip,
 failing-source rollup, 24h activity sparkline, credential staleness nudge

D1 scheduler visibility: AppSetting last-tick stamp on every Beat tick +
GET /api/sources/schedule-status (last_tick_at/next_due_at/due_now/auto_sources)
+ SchedulerStatusBar on the Subscriptions tab (re-polled every 30s).

D2 failing-source rollup: ?failing=true on the sources list + FailingSourcesCard
on Downloads with per-source and bulk "retry" (re-runs the feed via /check).

D3 activity sparkline: GET /api/downloads/activity hourly buckets + CSS bar
chart by the stat chips (failures stacked in error color); refreshes on live poll.

D4 credential staleness: surface last_verified age + "re-verify recommended"
warning past 30d; also fixes the dead last_verified_at field-name mismatch so
the verification row renders at all.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 backend/app/api/downloads.py                  |  48 ++++++++
 backend/app/api/sources.py                    |  11 +-
 backend/app/services/scheduler_service.py     |  68 ++++++++++-
 backend/app/services/source_service.py        |  17 ++-
 backend/app/tasks/scan.py                     |   4 +-
 .../subscriptions/CredentialCard.vue          |  44 ++++++-
 .../DownloadActivitySparkline.vue             |  92 +++++++++++++++
 .../components/subscriptions/DownloadsTab.vue |  70 ++++++++++-
 .../subscriptions/FailingSourcesCard.vue      |  87 ++++++++++++++
 .../subscriptions/SchedulerStatusBar.vue      | 110 ++++++++++++++++++
 .../subscriptions/SubscriptionsTab.vue        |  16 ++-
 frontend/src/stores/downloads.js              |  14 +++
 frontend/src/stores/sources.js                |   9 +-
 tests/test_api_downloads.py                   |  20 ++++
 tests/test_api_sources.py                     |  33 +++++-
 15 files changed, 623 insertions(+), 20 deletions(-)
 create mode 100644 frontend/src/components/subscriptions/DownloadActivitySparkline.vue
 create mode 100644 frontend/src/components/subscriptions/FailingSourcesCard.vue
 create mode 100644 frontend/src/components/subscriptions/SchedulerStatusBar.vue

diff --git a/backend/app/api/downloads.py b/backend/app/api/downloads.py
index e7a86c9..ee648ef 100644
--- a/backend/app/api/downloads.py
+++ b/backend/app/api/downloads.py
@@ -126,6 +126,54 @@ async def downloads_stats():
     return jsonify(out)
 
 
+@downloads_bp.route("/activity", methods=["GET"])
+async def downloads_activity():
+    """Hourly download-event counts over the last `?hours=` (default 24).
+
+    Returns a fixed-length, oldest-first bucket array so the UI can render
+    a sparkline directly. Bucketing is done in Python against UTC to dodge
+    session-timezone ambiguity in SQL date_trunc.
+    """
+    try:
+        hours = int(request.args.get("hours", "24"))
+    except ValueError:
+        return jsonify({"error": "invalid_hours"}), 400
+    hours = max(1, min(168, hours))
+
+    now = datetime.now(UTC)
+    end = now.replace(minute=0, second=0, microsecond=0)
+    start = end - timedelta(hours=hours - 1)
+    buckets = [
+        {"hour": (start + timedelta(hours=i)).isoformat(),
+         "ok": 0, "error": 0, "other": 0, "total": 0}
+        for i in range(hours)
+    ]
+
+    async with get_session() as session:
+        rows = (await session.execute(
+            select(DownloadEvent.started_at, DownloadEvent.status)
+            .where(DownloadEvent.started_at >= start)
+        )).all()
+
+    for started_at, status in rows:
+        if started_at is None:
+            continue
+        sa = started_at if started_at.tzinfo else started_at.replace(tzinfo=UTC)
+        idx = int((sa - start).total_seconds() // 3600)
+        if not (0 <= idx < hours):
+            continue
+        b = buckets[idx]
+        if status == "ok":
+            b["ok"] += 1
+        elif status == "error":
+            b["error"] += 1
+        else:
+            b["other"] += 1
+        b["total"] += 1
+
+    return jsonify({"hours": hours, "buckets": buckets})
+
+
 @downloads_bp.route("/<int:event_id>", methods=["GET"])
 async def get_download(event_id: int):
     async with get_session() as session:
diff --git a/backend/app/api/sources.py b/backend/app/api/sources.py
index fd2b109..71d5d9d 100644
--- a/backend/app/api/sources.py
+++ b/backend/app/api/sources.py
@@ -5,6 +5,7 @@ from sqlalchemy import select
 
 from ..extensions import get_session
 from ..models import DownloadEvent, Source
+from ..services.scheduler_service import scheduler_status
 from ..services.source_service import (
     KNOWN_PLATFORMS,
     ArtistNotFoundError,
@@ -35,11 +36,19 @@ async def list_sources():
             artist_id = int(artist_id_raw)
         except ValueError:
             return _bad("invalid_artist_id", detail="artist_id must be an integer")
+    failing = request.args.get("failing", "").lower() in ("1", "true", "yes")
     async with get_session() as session:
-        records = await SourceService(session).list(artist_id=artist_id)
+        records = await SourceService(session).list(artist_id=artist_id, failing=failing)
     return jsonify([r.to_dict() for r in records])
 
 
+@sources_bp.route("/schedule-status", methods=["GET"])
+async def schedule_status():
+    """FC-dashboards: scheduler health for the Subscriptions hub."""
+    async with get_session() as session:
+        return jsonify(await scheduler_status(session))
+
+
 @sources_bp.route("/<int:source_id>", methods=["GET"])
 async def get_source(source_id: int):
     async with get_session() as session:
diff --git a/backend/app/services/scheduler_service.py b/backend/app/services/scheduler_service.py
index 58071d0..2008eba 100644
--- a/backend/app/services/scheduler_service.py
+++ b/backend/app/services/scheduler_service.py
@@ -12,12 +12,17 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
-from ..models import Artist, ImportSettings, Source
+from ..models import AppSetting, Artist, ImportSettings, Source
 
 MIN_INTERVAL_SECONDS = 60
 MAX_INTERVAL_SECONDS = 86400
 MAX_BACKOFF_EXPONENT = 6
 
+# AppSetting key stamped every time the Beat tick fires (see scan.py). The
+# tick runs every 60s; the UI flags the scheduler as stalled if the last
+# stamp is older than a few minutes.
+SCHEDULER_LAST_TICK_KEY = "scheduler_last_tick_at"
+
 
 def compute_effective_interval(
     source: Source, artist: Artist, settings: ImportSettings,
@@ -78,3 +83,64 @@ def compute_next_check_at(
         return None
     interval = compute_effective_interval(source, artist, settings)
     return source.last_checked_at + timedelta(seconds=interval)
+
+
+async def record_tick(session: AsyncSession) -> None:
+    """Stamp the current time on the SCHEDULER_LAST_TICK_KEY AppSetting.
+
+    Called once per Beat tick so the UI can prove the scheduler is alive.
+    Commits its own write so the stamp survives even if the rest of the
+    tick errors out.
+    """
+    now_iso = datetime.now(UTC).isoformat()
+    row = (await session.execute(
+        select(AppSetting).where(AppSetting.key == SCHEDULER_LAST_TICK_KEY)
+    )).scalar_one_or_none()
+    if row is None:
+        session.add(AppSetting(key=SCHEDULER_LAST_TICK_KEY, value=now_iso))
+    else:
+        row.value = now_iso
+    await session.commit()
+
+
+async def scheduler_status(session: AsyncSession) -> dict:
+    """Summarise scheduler health for the dashboard.
+
+    Returns last_tick_at (when Beat last fired), next_due_at (earliest
+    upcoming scheduled check across enabled auto-check sources), due_now
+    (how many are due right now), and auto_sources (total under schedule).
+    """
+    last_tick_at = (await session.execute(
+        select(AppSetting.value).where(AppSetting.key == SCHEDULER_LAST_TICK_KEY)
+    )).scalar_one_or_none()
+
+    rows = (await session.execute(
+        select(Source)
+        .options(selectinload(Source.artist))
+        .join(Artist, Source.artist_id == Artist.id)
+        .where(Source.enabled.is_(True))
+        .where(Artist.auto_check.is_(True))
+    )).scalars().all()
+    settings = (await session.execute(
+        select(ImportSettings).where(ImportSettings.id == 1)
+    )).scalar_one()
+
+    now = datetime.now(UTC)
+    due_now = 0
+    next_due_at: datetime | None = None
+    for s in rows:
+        if s.last_checked_at is None:
+            due_now += 1
+            continue
+        nca = compute_next_check_at(s, s.artist, settings)
+        if nca is None or nca <= now:
+            due_now += 1
+        elif next_due_at is None or nca < next_due_at:
+            next_due_at = nca
+
+    return {
+        "last_tick_at": last_tick_at,
+        "next_due_at": next_due_at.isoformat() if next_due_at else None,
+        "due_now": due_now,
+        "auto_sources": len(rows),
+    }
diff --git a/backend/app/services/source_service.py b/backend/app/services/source_service.py
index df75e3e..ec17bed 100644
--- a/backend/app/services/source_service.py
+++ b/backend/app/services/source_service.py
@@ -151,14 +151,19 @@ class SourceService:
         settings = await self._load_settings()
         return self._build_record(source, artist, settings)
 
-    async def list(self, artist_id: int | None = None) -> list[SourceRecord]:
-        stmt = (
-            select(Source, Artist)
-            .join(Artist, Artist.id == Source.artist_id)
-            .order_by(Artist.name.asc(), Source.id.asc())
-        )
+    async def list(
+        self, artist_id: int | None = None, failing: bool = False,
+    ) -> list[SourceRecord]:
+        stmt = select(Source, Artist).join(Artist, Artist.id == Source.artist_id)
         if artist_id is not None:
             stmt = stmt.where(Source.artist_id == artist_id)
+        if failing:
+            # Worst-first so the rollup card surfaces the loudest failures.
+            stmt = stmt.where(Source.consecutive_failures > 0).order_by(
+                Source.consecutive_failures.desc(), Artist.name.asc(),
+            )
+        else:
+            stmt = stmt.order_by(Artist.name.asc(), Source.id.asc())
         rows = (await self.session.execute(stmt)).all()
         settings = await self._load_settings()
         return [self._build_record(s, a, settings) for s, a in rows]
diff --git a/backend/app/tasks/scan.py b/backend/app/tasks/scan.py
index 0451e49..60cbfe0 100644
--- a/backend/app/tasks/scan.py
+++ b/backend/app/tasks/scan.py
@@ -18,7 +18,7 @@ from ..celery_app import celery
 from ..config import get_config
 from ..models import DownloadEvent, ImportBatch, ImportSettings, ImportTask
 from ..services.archive_extractor import is_archive
-from ..services.scheduler_service import select_due_sources
+from ..services.scheduler_service import record_tick, select_due_sources
 from ._sync_engine import sync_session_factory as _sync_session_factory
 
 
@@ -151,6 +151,8 @@ async def _tick_due_sources_async() -> dict:
     factory, engine = _async_session_factory()
     try:
         async with factory() as session:
+            # Prove the scheduler is alive even on empty ticks (UI reads this).
+            await record_tick(session)
             due = await select_due_sources(session)
             if not due:
                 return {
diff --git a/frontend/src/components/subscriptions/CredentialCard.vue b/frontend/src/components/subscriptions/CredentialCard.vue
index 0a1d834..8427a48 100644
--- a/frontend/src/components/subscriptions/CredentialCard.vue
+++ b/frontend/src/components/subscriptions/CredentialCard.vue
@@ -24,9 +24,17 @@
           </v-icon>
           <span>Expires {{ fmtDate(credential.expires_at) }}</span>
         </div>
-        <div v-if="credential.last_verified_at" class="fc-cred-card__row">
-          <v-icon size="small" color="on-surface-variant">mdi-shield-check</v-icon>
-          <span>Last verified {{ fmtDate(credential.last_verified_at) }}</span>
+        <div v-if="credential.last_verified" class="fc-cred-card__row">
+          <v-icon size="small" :color="verifyStale ? 'warning' : 'success'">
+            {{ verifyStale ? 'mdi-shield-alert' : 'mdi-shield-check' }}
+          </v-icon>
+          <span :class="verifyStale ? 'text-warning' : undefined">
+            Last verified {{ verifiedRelative }}<template v-if="verifyStale"> — re-verify recommended</template>
+          </span>
+        </div>
+        <div v-else-if="!freshlyVerified" class="fc-cred-card__row">
+          <v-icon size="small" color="warning">mdi-shield-alert</v-icon>
+          <span class="text-warning">Never verified — click Verify to confirm</span>
         </div>
       </template>
       <template v-else>
@@ -139,14 +147,42 @@ const expiringSoon = computed(() => {
   return diff > 0 && diff < 7
 })
 
+// Verification staleness: a stored cookie/token that hasn't been confirmed
+// in a month is the silent-failure trap (subscribestar/HF). Nudge the
+// operator to re-verify before a scheduled download dies on bad auth.
+const STALE_DAYS = 30
+// A successful Verify in this session clears the warning even before the
+// parent reloads the credential list (last_verified prop is still old).
+const freshlyVerified = computed(() => verifyResult.value?.valid === true)
+const verifiedAgeDays = computed(() => {
+  const v = props.credential?.last_verified
+  if (!v) return null
+  return (Date.now() - new Date(v).getTime()) / 86400_000
+})
+const verifyStale = computed(() => {
+  if (!hasCredential.value || freshlyVerified.value) return false
+  const age = verifiedAgeDays.value
+  return age == null || age > STALE_DAYS
+})
+const verifiedRelative = computed(() => {
+  const age = verifiedAgeDays.value
+  if (age == null) return '—'
+  if (age < 1) return 'today'
+  if (age < 2) return 'yesterday'
+  if (age < 30) return `${Math.floor(age)}d ago`
+  if (age < 365) return `${Math.floor(age / 30)}mo ago`
+  return `${Math.floor(age / 365)}y ago`
+})
+
 const statusLabel = computed(() => {
   if (!hasCredential.value) return 'Not configured'
   if (expiringSoon.value) return 'Expiring soon'
+  if (verifyStale.value) return 'Verify due'
   return 'Active'
 })
 const statusColor = computed(() => {
   if (!hasCredential.value) return 'grey'
-  if (expiringSoon.value) return 'warning'
+  if (expiringSoon.value || verifyStale.value) return 'warning'
   return 'success'
 })
 
diff --git a/frontend/src/components/subscriptions/DownloadActivitySparkline.vue b/frontend/src/components/subscriptions/DownloadActivitySparkline.vue
new file mode 100644
index 0000000..b2d909e
--- /dev/null
+++ b/frontend/src/components/subscriptions/DownloadActivitySparkline.vue
@@ -0,0 +1,92 @@
+<template>
+  <div class="fc-spark" :title="summaryTip">
+    <div class="fc-spark__bars">
+      <div
+        v-for="(b, i) in buckets" :key="i"
+        class="fc-spark__bar"
+        :title="barTip(b)"
+      >
+        <div class="fc-spark__fill" :style="{ height: fillPct(b) + '%' }">
+          <div
+            v-if="b.error > 0"
+            class="fc-spark__err"
+            :style="{ height: errPct(b) + '%' }"
+          />
+        </div>
+      </div>
+    </div>
+    <div class="fc-spark__caption">
+      {{ hours }}h · {{ totalEvents }} events
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps({
+  // [{ hour, ok, error, other, total }] oldest-first
+  buckets: { type: Array, default: () => [] },
+  hours: { type: Number, default: 24 },
+})
+
+const maxTotal = computed(() =>
+  Math.max(1, ...props.buckets.map((b) => b.total || 0)),
+)
+const totalEvents = computed(() =>
+  props.buckets.reduce((n, b) => n + (b.total || 0), 0),
+)
+
+function fillPct(b) {
+  return Math.round(((b.total || 0) / maxTotal.value) * 100)
+}
+function errPct(b) {
+  if (!b.total) return 0
+  return Math.round((b.error / b.total) * 100)
+}
+function barTip(b) {
+  const t = new Date(b.hour)
+  const label = t.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+  return `${label} — ${b.total} events (${b.ok} ok, ${b.error} failed)`
+}
+const summaryTip = computed(
+  () => `Download activity, last ${props.hours}h (red = failures)`,
+)
+</script>
+
+<style scoped>
+.fc-spark {
+  display: flex; flex-direction: column; gap: 2px;
+  min-width: 160px;
+}
+.fc-spark__bars {
+  display: flex; align-items: flex-end; gap: 2px;
+  height: 36px;
+}
+.fc-spark__bar {
+  flex: 1 1 0;
+  height: 100%;
+  display: flex; align-items: flex-end;
+  min-width: 2px;
+}
+.fc-spark__fill {
+  width: 100%;
+  min-height: 1px;
+  position: relative;
+  border-radius: 2px 2px 0 0;
+  background: rgb(var(--v-theme-accent) / 0.7);
+}
+.fc-spark__err {
+  position: absolute; bottom: 0; left: 0;
+  width: 100%;
+  border-radius: 0 0 2px 2px;
+  background: rgb(var(--v-theme-error));
+}
+.fc-spark__caption {
+  font-size: 0.68rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: rgb(var(--v-theme-on-surface-variant));
+  text-align: center;
+}
+</style>
diff --git a/frontend/src/components/subscriptions/DownloadsTab.vue b/frontend/src/components/subscriptions/DownloadsTab.vue
index 98dce0d..e1cd3e0 100644
--- a/frontend/src/components/subscriptions/DownloadsTab.vue
+++ b/frontend/src/components/subscriptions/DownloadsTab.vue
@@ -12,6 +12,12 @@
           live
         </span>
         <v-spacer />
+        <DownloadActivitySparkline
+          v-if="store.activity.buckets.length"
+          :buckets="store.activity.buckets"
+          :hours="store.activity.hours"
+          class="fc-dl__spark"
+        />
         <v-btn variant="text" icon @click="refresh">
           <v-icon>mdi-refresh</v-icon>
           <v-tooltip activator="parent" location="top">Refresh</v-tooltip>
@@ -41,6 +47,14 @@
       {{ String(store.error) }}
     </v-alert>
 
+    <FailingSourcesCard
+      :sources="store.failing"
+      :retrying-ids="sourcesStore.checkingIds"
+      :retrying-all="retryingAll"
+      @retry="onRetrySource"
+      @retry-all="onRetryAll"
+    />
+
     <div v-if="store.loading && store.events.length === 0" class="fc-dl__loading">
       <v-progress-circular indeterminate color="accent" size="36" />
     </div>
@@ -103,15 +117,20 @@ import { computed, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
 import { useRoute } from 'vue-router'
 
 import { useDownloadsStore } from '../../stores/downloads.js'
+import { useSourcesStore } from '../../stores/sources.js'
 import DownloadEventRow from '../downloads/DownloadEventRow.vue'
 import DownloadDetailModal from '../downloads/DownloadDetailModal.vue'
 import DownloadStatChips from './DownloadStatChips.vue'
+import DownloadActivitySparkline from './DownloadActivitySparkline.vue'
+import FailingSourcesCard from './FailingSourcesCard.vue'
 import MaintenanceMenu from './MaintenanceMenu.vue'
 import DownloadsFilterPopover from './DownloadsFilterPopover.vue'
 
 const route = useRoute()
 const store = useDownloadsStore()
+const sourcesStore = useSourcesStore()
 const filterModel = ref({ ...store.filter })
+const retryingAll = ref(false)
 
 // Free-text search (client-side over the loaded events) + a toggle to
 // hide "no-change" scheduled scans (status=ok/skipped with 0 files) so
@@ -138,9 +157,51 @@ async function refresh() {
   await Promise.all([
     store.loadFirst(),
     store.loadStats(24),
+    store.loadActivity(24),
+    store.loadFailing(),
   ])
 }
 
+// Retry a single failing source (re-runs its whole feed) then refresh the
+// rollup + stats so the operator sees it move.
+async function onRetrySource(source) {
+  try {
+    await sourcesStore.checkNow(source.id)
+    globalThis.window?.__fcToast?.({ text: `Retry queued for ${source.artist_name || source.platform}`, type: 'success' })
+  } catch (e) {
+    if (e?.body?.download_event_id) {
+      globalThis.window?.__fcToast?.({ text: 'Already running — see below', type: 'info' })
+    } else {
+      globalThis.window?.__fcToast?.({ text: `Retry failed: ${e?.detail || e?.message || e}`, type: 'error' })
+    }
+  } finally {
+    await Promise.all([store.loadFailing(), store.loadStats(24), store.loadFirst()])
+  }
+}
+
+async function onRetryAll(sources) {
+  retryingAll.value = true
+  let ok = 0
+  let conflict = 0
+  try {
+    for (const s of sources) {
+      try {
+        await sourcesStore.checkNow(s.id)
+        ok += 1
+      } catch (e) {
+        if (e?.body?.download_event_id) conflict += 1
+      }
+    }
+  } finally {
+    retryingAll.value = false
+    await Promise.all([store.loadFailing(), store.loadStats(24), store.loadFirst()])
+  }
+  const parts = []
+  if (ok) parts.push(`${ok} queued`)
+  if (conflict) parts.push(`${conflict} already running`)
+  globalThis.window?.__fcToast?.({ text: parts.join(', ') || 'Nothing to retry', type: 'info' })
+}
+
 // Live auto-refresh: while any download is queued or running, poll the
 // stats + first page every 4s so the operator can watch events succeed/
 // fail in real time without hitting Refresh. Polling stops automatically
@@ -156,10 +217,10 @@ function startPolling() {
   if (pollId) return
   pollId = setInterval(async () => {
     if (document.hidden) return
-    // Refresh stats cheaply every tick; only reload the event list when
-    // there's active work to reflect (keeps idle ticks light).
-    await store.loadStats(24)
-    if (liveActive.value) await store.loadFirst()
+    // Refresh stats + sparkline cheaply every tick; only reload the event
+    // list + failing rollup when there's active work (keeps idle ticks light).
+    await Promise.all([store.loadStats(24), store.loadActivity(24)])
+    if (liveActive.value) await Promise.all([store.loadFirst(), store.loadFailing()])
   }, POLL_MS)
 }
 function stopPolling() {
@@ -288,6 +349,7 @@ async function openDetail(id) {
   display: flex; gap: 12px; align-items: center; flex-wrap: wrap;
 }
 .fc-dl__nochange { flex: 0 0 auto; }
+.fc-dl__spark { flex: 0 0 auto; margin-right: 4px; max-width: 240px; }
 .fc-dl__live {
   display: inline-flex; align-items: center; gap: 5px;
   font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.06em;
diff --git a/frontend/src/components/subscriptions/FailingSourcesCard.vue b/frontend/src/components/subscriptions/FailingSourcesCard.vue
new file mode 100644
index 0000000..496c8bc
--- /dev/null
+++ b/frontend/src/components/subscriptions/FailingSourcesCard.vue
@@ -0,0 +1,87 @@
+<template>
+  <v-card v-if="sources.length" variant="tonal" color="error" class="fc-fail mb-4">
+    <div class="fc-fail__head" @click="open = !open">
+      <v-icon size="small">mdi-alert-circle</v-icon>
+      <span class="fc-fail__title">
+        {{ sources.length }}
+        {{ sources.length === 1 ? 'source is' : 'sources are' }} failing
+      </span>
+      <v-spacer />
+      <v-btn
+        size="small" variant="text" prepend-icon="mdi-refresh"
+        :loading="retryingAll"
+        @click.stop="$emit('retry-all', sources)"
+      >
+        Retry all
+      </v-btn>
+      <v-icon size="small">{{ open ? 'mdi-chevron-up' : 'mdi-chevron-down' }}</v-icon>
+    </div>
+
+    <v-expand-transition>
+      <div v-if="open" class="fc-fail__body">
+        <div v-for="s in sources" :key="s.id" class="fc-fail__row">
+          <PlatformChip :platform="s.platform" size="x-small" />
+          <span class="fc-fail__artist">{{ s.artist_name || `#${s.artist_id}` }}</span>
+          <v-chip size="x-small" color="error" variant="flat" label class="fc-fail__count">
+            {{ s.consecutive_failures }}× failed
+          </v-chip>
+          <span class="fc-fail__err" :title="s.last_error || ''">
+            {{ s.last_error || 'no error message recorded' }}
+          </span>
+          <v-spacer />
+          <v-btn
+            size="x-small" variant="text" prepend-icon="mdi-refresh"
+            :loading="retryingIds.has(s.id)"
+            @click="$emit('retry', s)"
+          >
+            Retry
+          </v-btn>
+        </div>
+      </div>
+    </v-expand-transition>
+  </v-card>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import PlatformChip from './PlatformChip.vue'
+
+defineProps({
+  // source records from /api/sources?failing=true
+  sources: { type: Array, default: () => [] },
+  retryingIds: { type: Set, default: () => new Set() },
+  retryingAll: { type: Boolean, default: false },
+})
+defineEmits(['retry', 'retry-all'])
+
+const open = ref(true)
+</script>
+
+<style scoped>
+.fc-fail { border-radius: 8px; }
+.fc-fail__head {
+  display: flex; align-items: center; gap: 8px;
+  padding: 10px 14px;
+  cursor: pointer;
+  user-select: none;
+}
+.fc-fail__title { font-weight: 600; }
+.fc-fail__body {
+  padding: 0 14px 10px;
+  display: flex; flex-direction: column; gap: 2px;
+}
+.fc-fail__row {
+  display: flex; align-items: center; gap: 10px;
+  padding: 6px 8px;
+  border-radius: 4px;
+  background: rgb(var(--v-theme-surface) / 0.4);
+}
+.fc-fail__artist { font-weight: 600; white-space: nowrap; }
+.fc-fail__count { flex: 0 0 auto; }
+.fc-fail__err {
+  color: rgb(var(--v-theme-on-surface-variant));
+  font-size: 0.8rem;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  max-width: 46ch;
+}
+</style>
diff --git a/frontend/src/components/subscriptions/SchedulerStatusBar.vue b/frontend/src/components/subscriptions/SchedulerStatusBar.vue
new file mode 100644
index 0000000..46ec14c
--- /dev/null
+++ b/frontend/src/components/subscriptions/SchedulerStatusBar.vue
@@ -0,0 +1,110 @@
+<template>
+  <div v-if="status" class="fc-sched" :class="`fc-sched--${health}`">
+    <span class="fc-sched__dot" />
+    <span class="fc-sched__label">Scheduler</span>
+    <span class="fc-sched__sep">·</span>
+    <span class="fc-sched__item">
+      <v-icon size="x-small">mdi-clock-outline</v-icon>
+      last ran {{ lastRanLabel }}
+    </span>
+    <span class="fc-sched__sep">·</span>
+    <span class="fc-sched__item">
+      <v-icon size="x-small">mdi-calendar-clock</v-icon>
+      {{ nextLabel }}
+    </span>
+    <span class="fc-sched__sep">·</span>
+    <span class="fc-sched__item">
+      {{ status.auto_sources }} on schedule
+    </span>
+    <v-tooltip activator="parent" location="bottom">
+      {{ tooltip }}
+    </v-tooltip>
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps({
+  // { last_tick_at, next_due_at, due_now, auto_sources } | null
+  status: { type: Object, default: null },
+})
+
+// The Beat tick fires every 60s; if the last stamp is older than ~3
+// minutes the scheduler (Beat) is almost certainly down.
+const STALE_MS = 180_000
+
+const tickAgeMs = computed(() => {
+  const t = props.status?.last_tick_at
+  if (!t) return null
+  return Date.now() - new Date(t).getTime()
+})
+
+const health = computed(() => {
+  if (tickAgeMs.value == null) return 'unknown'
+  return tickAgeMs.value <= STALE_MS ? 'ok' : 'stale'
+})
+
+function rel(ms) {
+  const s = Math.max(0, Math.floor(ms / 1000))
+  if (s < 60) return `${s}s ago`
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`
+  return `${Math.floor(s / 86400)}d ago`
+}
+
+const lastRanLabel = computed(() =>
+  tickAgeMs.value == null ? 'never' : rel(tickAgeMs.value),
+)
+
+const nextLabel = computed(() => {
+  const due = props.status?.due_now || 0
+  if (due > 0) return `${due} due now`
+  const n = props.status?.next_due_at
+  if (!n) return 'nothing scheduled'
+  const diff = new Date(n).getTime() - Date.now()
+  if (diff <= 0) return 'check due'
+  const s = Math.floor(diff / 1000)
+  if (s < 60) return `next in ${s}s`
+  if (s < 3600) return `next in ${Math.floor(s / 60)}m`
+  if (s < 86400) return `next in ${Math.floor(s / 3600)}h`
+  return `next in ${Math.floor(s / 86400)}d`
+})
+
+const tooltip = computed(() => {
+  if (health.value === 'unknown') return 'The scheduler has not ticked yet (or the worker just started).'
+  if (health.value === 'stale') return 'The scheduler tick is overdue — check that Celery Beat is running.'
+  return 'Celery Beat is firing the periodic source-check tick on schedule.'
+})
+</script>
+
+<style scoped>
+.fc-sched {
+  display: inline-flex; align-items: center; gap: 8px;
+  flex-wrap: wrap;
+  font-size: 0.78rem;
+  color: rgb(var(--v-theme-on-surface-variant));
+  padding: 4px 10px;
+  border-radius: 6px;
+  background: rgb(var(--v-theme-on-surface) / 0.04);
+}
+.fc-sched__dot {
+  width: 8px; height: 8px; border-radius: 50%;
+  flex: 0 0 auto;
+  background: rgb(var(--v-theme-on-surface-variant));
+}
+.fc-sched--ok .fc-sched__dot { background: rgb(var(--v-theme-success)); }
+.fc-sched--stale .fc-sched__dot { background: rgb(var(--v-theme-error)); }
+.fc-sched--unknown .fc-sched__dot { background: rgb(var(--v-theme-on-surface-variant)); }
+.fc-sched--stale { color: rgb(var(--v-theme-error)); }
+.fc-sched__label {
+  font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em;
+  color: rgb(var(--v-theme-on-surface));
+}
+.fc-sched--stale .fc-sched__label { color: rgb(var(--v-theme-error)); }
+.fc-sched__sep { opacity: 0.4; }
+.fc-sched__item {
+  display: inline-flex; align-items: center; gap: 3px;
+  white-space: nowrap;
+}
+</style>
diff --git a/frontend/src/components/subscriptions/SubscriptionsTab.vue b/frontend/src/components/subscriptions/SubscriptionsTab.vue
index 5d3b04e..7c07ffb 100644
--- a/frontend/src/components/subscriptions/SubscriptionsTab.vue
+++ b/frontend/src/components/subscriptions/SubscriptionsTab.vue
@@ -1,5 +1,7 @@
 <template>
   <div>
+    <SchedulerStatusBar :status="store.scheduleStatus" class="fc-subs__sched" />
+
     <div class="fc-subs__bar">
       <v-btn color="accent" prepend-icon="mdi-plus" @click="openAddSource(null)">
         Add subscription
@@ -197,7 +199,7 @@
 </template>
 
 <script setup>
-import { computed, onMounted, ref, watch } from 'vue'
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useSourcesStore } from '../../stores/sources.js'
 import { usePlatformsStore } from '../../stores/platforms.js'
@@ -207,6 +209,7 @@ import SourceHealthDot from './SourceHealthDot.vue'
 import SourceFormDialog from './SourceFormDialog.vue'
 import ArtistCreateDialog from './ArtistCreateDialog.vue'
 import PlatformChip from './PlatformChip.vue'
+import SchedulerStatusBar from './SchedulerStatusBar.vue'
 
 const ITEMS_PER_PAGE_OPTIONS = [
   { value: 25, title: '25' },
@@ -250,14 +253,24 @@ const failureThreshold = computed(() =>
 async function refresh() {
   await store.loadAll()
   await platformsStore.loadAll()
+  store.loadScheduleStatus()
   if (!importStore.settings) await importStore.loadSettings()
 }
 
+// Re-poll scheduler status every 30s so the "last ran" reading + health
+// dot stay honest (the Beat tick fires every 60s).
+let schedId = null
 onMounted(() => {
   refresh()
   if (artistFilter.value != null) {
     expanded.value = [`artist-${artistFilter.value}`]
   }
+  schedId = setInterval(() => {
+    if (!document.hidden) store.loadScheduleStatus()
+  }, 30000)
+})
+onUnmounted(() => {
+  if (schedId) { clearInterval(schedId); schedId = null }
 })
 watch(() => route.query.artist_id, refresh)
 
@@ -500,6 +513,7 @@ async function bulkDelete() {
 </script>
 
 <style scoped>
+.fc-subs__sched { margin-bottom: 10px; }
 .fc-subs__bar {
   display: flex; gap: 0.75rem; align-items: center;
   flex-wrap: wrap;
diff --git a/frontend/src/stores/downloads.js b/frontend/src/stores/downloads.js
index 5dd76df..cc72e7b 100644
--- a/frontend/src/stores/downloads.js
+++ b/frontend/src/stores/downloads.js
@@ -16,6 +16,8 @@ export const useDownloadsStore = defineStore('downloads', () => {
   const loading = ref(false)
   const error = ref(null)
   const stats = ref({ pending: 0, running: 0, ok: 0, error: 0, skipped: 0 })
+  const activity = ref({ hours: 24, buckets: [] })
+  const failing = ref([])
 
   function _params(extra = {}) {
     const out = { limit: 50, ...extra }
@@ -74,8 +76,20 @@ export const useDownloadsStore = defineStore('downloads', () => {
     return stats.value
   }
 
+  async function loadActivity(hours = 24) {
+    activity.value = await api.get('/api/downloads/activity', { params: { hours } })
+    return activity.value
+  }
+
+  async function loadFailing() {
+    failing.value = await api.get('/api/sources', { params: { failing: true } })
+    return failing.value
+  }
+
   return {
     events, cursor, hasMore, filter, selected, loading, error, stats,
+    activity, failing,
     loadFirst, loadMore, loadOne, applyFilter, closeDetail, loadStats,
+    loadActivity, loadFailing,
   }
 })
diff --git a/frontend/src/stores/sources.js b/frontend/src/stores/sources.js
index 1032edb..d3955b1 100644
--- a/frontend/src/stores/sources.js
+++ b/frontend/src/stores/sources.js
@@ -9,6 +9,7 @@ export const useSourcesStore = defineStore('sources', () => {
   const byArtist = ref(new Map())
   const loading = ref(false)
   const error = ref(null)
+  const scheduleStatus = ref(null)
 
   const allSources = computed(() => byArtist.value.get(null) ?? [])
 
@@ -70,6 +71,11 @@ export const useSourcesStore = defineStore('sources', () => {
     return await api.get('/api/artists/autocomplete', { params: { q: query, limit } })
   }
 
+  async function loadScheduleStatus() {
+    scheduleStatus.value = await api.get('/api/sources/schedule-status')
+    return scheduleStatus.value
+  }
+
   // FC-3c: trigger a download for one source. Returns {download_event_id,status}.
   const checkingIds = ref(new Set())
 
@@ -104,13 +110,14 @@ export const useSourcesStore = defineStore('sources', () => {
   }
 
   return {
-    byArtist, loading, error,
+    byArtist, loading, error, scheduleStatus,
     allSources,
     checkingIds,
     loadAll, loadForArtist,
     create, update, remove,
     checkNow,
     findOrCreateArtist, autocompleteArtist,
+    loadScheduleStatus,
     sourcesByArtistGrouped,
   }
 })
diff --git a/tests/test_api_downloads.py b/tests/test_api_downloads.py
index 253f1c5..9d164b8 100644
--- a/tests/test_api_downloads.py
+++ b/tests/test_api_downloads.py
@@ -126,3 +126,23 @@ async def test_stats_window_hours_rejects_out_of_range(client):
     assert resp.status_code == 400
     resp = await client.get("/api/downloads/stats?window_hours=bogus")
     assert resp.status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_activity_returns_fixed_bucket_array(client, seed):
+    resp = await client.get("/api/downloads/activity")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert body["hours"] == 24
+    assert len(body["buckets"]) == 24
+    assert sum(b["total"] for b in body["buckets"]) == 2
+    # Both seed events were created "now" → land in the newest bucket.
+    newest = body["buckets"][-1]
+    assert newest["ok"] == 1
+    assert newest["error"] == 1
+
+
+@pytest.mark.asyncio
+async def test_activity_rejects_bogus_hours(client):
+    resp = await client.get("/api/downloads/activity?hours=bogus")
+    assert resp.status_code == 400
diff --git a/tests/test_api_sources.py b/tests/test_api_sources.py
index 9c58430..da8b05c 100644
--- a/tests/test_api_sources.py
+++ b/tests/test_api_sources.py
@@ -1,7 +1,7 @@
 import pytest
 
 from backend.app import create_app
-from backend.app.models import Artist
+from backend.app.models import Artist, Source
 
 pytestmark = pytest.mark.integration
 
@@ -25,6 +25,37 @@ async def artist(db):
     return a
 
 
+@pytest.mark.asyncio
+async def test_list_failing_filter_returns_only_failing(client, artist, db):
+    healthy = Source(
+        artist_id=artist.id, platform="patreon", url="https://p/ok",
+        enabled=True, consecutive_failures=0,
+    )
+    broken = Source(
+        artist_id=artist.id, platform="pixiv", url="https://p/bad",
+        enabled=True, consecutive_failures=3, last_error="boom",
+    )
+    db.add_all([healthy, broken])
+    await db.commit()
+
+    resp = await client.get("/api/sources?failing=true")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert len(body) == 1
+    assert body[0]["consecutive_failures"] == 3
+    assert body[0]["last_error"] == "boom"
+
+
+@pytest.mark.asyncio
+async def test_schedule_status_shape(client):
+    resp = await client.get("/api/sources/schedule-status")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert set(body) == {"last_tick_at", "next_due_at", "due_now", "auto_sources"}
+    assert isinstance(body["due_now"], int)
+    assert isinstance(body["auto_sources"], int)
+
+
 @pytest.mark.asyncio
 async def test_create_list_get_delete(client, artist):
     create = await client.post("/api/sources", json={

From eebc8e241330cf37a1fb44cb98de7ae250356e5b Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 11:20:07 -0400
Subject: [PATCH 09/18] refactor(dry-F2): centralize shared UI primitives
 (relative-time, toast, download-status)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- utils/date.js: add formatRelative(iso, {future,nullText}); migrate 6 sites
  (SourceRow, SubscriptionsTab, SourceHealthDot, SchedulerStatusBar +
  thin adapters in BackupRunsTable/SystemActivityTab for their '—' null text).
  PostCard (30d->absolute) and CredentialCard (mo/y buckets) intentionally
  keep bespoke formatters.
- utils/toast.js: toast(opts) wraps the globalThis.window?.__fcToast?.(...)
  incantation; migrate 63 call sites across 24 files.
- utils/downloadStatus.js: single source for the download-event status enum
  -> label/color/icon; collapse the 3 duplicate maps (DownloadStatChips,
  DownloadsFilterPopover, DownloadEventRow).

Net -33 lines. Platform metadata was already centralized in platformColor.js.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/cleanup/MinDimensionCard.vue   |  7 +++--
 .../cleanup/SingleColorAuditCard.vue          | 11 ++++----
 .../cleanup/TransparencyAuditCard.vue         | 11 ++++----
 .../components/common/ErrorDetailModal.vue    |  3 +-
 .../credentials/ExtensionKeyBar.vue           |  7 +++--
 .../downloads/DownloadDetailModal.vue         |  5 ++--
 .../components/downloads/DownloadEventRow.vue | 19 +++++--------
 .../src/components/modal/SuggestionsPanel.vue |  5 ++--
 .../components/settings/BackupRunsTable.vue   | 10 ++-----
 .../settings/BrowserExtensionCard.vue         | 11 ++++----
 .../settings/CentroidRecomputeCard.vue        |  3 +-
 .../components/settings/ImportTaskList.vue    |  5 ++--
 .../components/settings/MLBackfillCard.vue    |  3 +-
 .../settings/MLThresholdSliders.vue           |  3 +-
 .../components/settings/SystemActivityTab.vue | 10 ++-----
 .../settings/ThumbnailBackfillCard.vue        |  3 +-
 .../subscriptions/ArtistCreateDialog.vue      |  3 +-
 .../subscriptions/CredentialCard.vue          |  5 ++--
 .../subscriptions/DownloadStatChips.vue       | 24 ++++++----------
 .../subscriptions/DownloadsFilterPopover.vue  | 12 ++------
 .../components/subscriptions/DownloadsTab.vue |  9 +++---
 .../subscriptions/MaintenanceMenu.vue         |  9 +++---
 .../subscriptions/SchedulerStatusBar.vue      | 11 ++------
 .../subscriptions/SourceHealthDot.vue         | 28 +++++--------------
 .../components/subscriptions/SourceRow.vue    | 18 +-----------
 .../subscriptions/SubscriptionsTab.vue        | 24 ++++++----------
 frontend/src/stores/gallerySelection.js       |  5 ++--
 frontend/src/stores/import.js                 | 13 +++++----
 frontend/src/stores/modal.js                  |  3 +-
 frontend/src/stores/seriesManage.js           |  3 +-
 frontend/src/stores/suggestions.js            |  5 ++--
 frontend/src/utils/date.js                    | 19 +++++++++++++
 frontend/src/utils/downloadStatus.js          | 21 ++++++++++++++
 frontend/src/utils/toast.js                   |  8 ++++++
 34 files changed, 166 insertions(+), 170 deletions(-)
 create mode 100644 frontend/src/utils/downloadStatus.js
 create mode 100644 frontend/src/utils/toast.js

diff --git a/frontend/src/components/cleanup/MinDimensionCard.vue b/frontend/src/components/cleanup/MinDimensionCard.vue
index 140d549..b018c6b 100644
--- a/frontend/src/components/cleanup/MinDimensionCard.vue
+++ b/frontend/src/components/cleanup/MinDimensionCard.vue
@@ -62,6 +62,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { onMounted, ref } from 'vue'
 
 import DestructiveConfirmModal from '../modal/DestructiveConfirmModal.vue'
@@ -94,7 +95,7 @@ async function onPreview() {
   try {
     preview.value = await store.previewMinDim(minW.value, minH.value)
   } catch (e) {
-    window.__fcToast?.({ text: `Preview failed: ${e.message}`, type: 'error' })
+    toast({ text: `Preview failed: ${e.message}`, type: 'error' })
   } finally {
     busy.value = false
   }
@@ -108,12 +109,12 @@ function onDeleteClick() {
 async function onConfirmedDelete(token) {
   try {
     const res = await store.deleteMinDim(minW.value, minH.value, token)
-    window.__fcToast?.({
+    toast({
       text: `Deleted ${res.deleted} image(s)`, type: 'success',
     })
     preview.value = null
   } catch (e) {
-    window.__fcToast?.({ text: `Delete failed: ${e.message}`, type: 'error' })
+    toast({ text: `Delete failed: ${e.message}`, type: 'error' })
   }
 }
 </script>
diff --git a/frontend/src/components/cleanup/SingleColorAuditCard.vue b/frontend/src/components/cleanup/SingleColorAuditCard.vue
index ff2ecbe..08c6476 100644
--- a/frontend/src/components/cleanup/SingleColorAuditCard.vue
+++ b/frontend/src/components/cleanup/SingleColorAuditCard.vue
@@ -93,6 +93,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { onMounted, onUnmounted, ref } from 'vue'
 
 import DestructiveConfirmModal from '../modal/DestructiveConfirmModal.vue'
@@ -124,7 +125,7 @@ function startPoll(id) {
       if (fresh.status !== 'running') stopPoll()
     } catch (e) {
       stopPoll()
-      window.__fcToast?.({ text: `Audit poll failed: ${e.message}`, type: 'error' })
+      toast({ text: `Audit poll failed: ${e.message}`, type: 'error' })
     }
   }, 5000)
 }
@@ -142,7 +143,7 @@ async function onStart() {
     audit.value = await store.getAudit(res.audit_id)
     startPoll(res.audit_id)
   } catch (e) {
-    window.__fcToast?.({ text: `Scan start failed: ${e.message}`, type: 'error' })
+    toast({ text: `Scan start failed: ${e.message}`, type: 'error' })
   } finally {
     busy.value = false
   }
@@ -155,7 +156,7 @@ async function onCancel() {
     audit.value = await store.getAudit(audit.value.id)
     stopPoll()
   } catch (e) {
-    window.__fcToast?.({ text: `Cancel failed: ${e.message}`, type: 'error' })
+    toast({ text: `Cancel failed: ${e.message}`, type: 'error' })
   }
 }
 
@@ -167,12 +168,12 @@ function onApplyClick() {
 async function onConfirmedApply(token) {
   try {
     const res = await store.applyAudit(audit.value.id, token)
-    window.__fcToast?.({
+    toast({
       text: `Deleted ${res.deleted} image(s)`, type: 'success',
     })
     audit.value = await store.getAudit(audit.value.id)
   } catch (e) {
-    window.__fcToast?.({ text: `Apply failed: ${e.message}`, type: 'error' })
+    toast({ text: `Apply failed: ${e.message}`, type: 'error' })
   }
 }
 </script>
diff --git a/frontend/src/components/cleanup/TransparencyAuditCard.vue b/frontend/src/components/cleanup/TransparencyAuditCard.vue
index 4e91ac0..6e26f99 100644
--- a/frontend/src/components/cleanup/TransparencyAuditCard.vue
+++ b/frontend/src/components/cleanup/TransparencyAuditCard.vue
@@ -80,6 +80,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { onMounted, onUnmounted, ref } from 'vue'
 
 import DestructiveConfirmModal from '../modal/DestructiveConfirmModal.vue'
@@ -109,7 +110,7 @@ function startPoll(id) {
       if (fresh.status !== 'running') stopPoll()
     } catch (e) {
       stopPoll()
-      window.__fcToast?.({ text: `Audit poll failed: ${e.message}`, type: 'error' })
+      toast({ text: `Audit poll failed: ${e.message}`, type: 'error' })
     }
   }, 5000)
 }
@@ -125,7 +126,7 @@ async function onStart() {
     audit.value = await store.getAudit(res.audit_id)
     startPoll(res.audit_id)
   } catch (e) {
-    window.__fcToast?.({ text: `Scan start failed: ${e.message}`, type: 'error' })
+    toast({ text: `Scan start failed: ${e.message}`, type: 'error' })
   } finally {
     busy.value = false
   }
@@ -138,7 +139,7 @@ async function onCancel() {
     audit.value = await store.getAudit(audit.value.id)
     stopPoll()
   } catch (e) {
-    window.__fcToast?.({ text: `Cancel failed: ${e.message}`, type: 'error' })
+    toast({ text: `Cancel failed: ${e.message}`, type: 'error' })
   }
 }
 
@@ -150,12 +151,12 @@ function onApplyClick() {
 async function onConfirmedApply(token) {
   try {
     const res = await store.applyAudit(audit.value.id, token)
-    window.__fcToast?.({
+    toast({
       text: `Deleted ${res.deleted} image(s)`, type: 'success',
     })
     audit.value = await store.getAudit(audit.value.id)
   } catch (e) {
-    window.__fcToast?.({ text: `Apply failed: ${e.message}`, type: 'error' })
+    toast({ text: `Apply failed: ${e.message}`, type: 'error' })
   }
 }
 </script>
diff --git a/frontend/src/components/common/ErrorDetailModal.vue b/frontend/src/components/common/ErrorDetailModal.vue
index 021f3da..6c378b3 100644
--- a/frontend/src/components/common/ErrorDetailModal.vue
+++ b/frontend/src/components/common/ErrorDetailModal.vue
@@ -33,6 +33,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, ref, watch } from 'vue'
 
 import { copyText } from '../../utils/clipboard.js'
@@ -119,7 +120,7 @@ async function onCopy () {
     if (copiedTimer) clearTimeout(copiedTimer)
     copiedTimer = setTimeout(() => { copied.value = false }, 1500)
   } catch (e) {
-    window.__fcToast?.({ text: `Copy failed: ${e.message}`, type: 'error' })
+    toast({ text: `Copy failed: ${e.message}`, type: 'error' })
   }
 }
 </script>
diff --git a/frontend/src/components/credentials/ExtensionKeyBar.vue b/frontend/src/components/credentials/ExtensionKeyBar.vue
index 2563ec6..3453aec 100644
--- a/frontend/src/components/credentials/ExtensionKeyBar.vue
+++ b/frontend/src/components/credentials/ExtensionKeyBar.vue
@@ -26,6 +26,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { onMounted, ref } from 'vue'
 import { useCredentialsStore } from '../../stores/credentials.js'
 import { copyText } from '../../utils/clipboard.js'
@@ -39,9 +40,9 @@ async function copyKey() {
   if (!store.extensionKey) return
   try {
     await copyText(store.extensionKey)
-    globalThis.window?.__fcToast?.({ text: 'Copied', type: 'success' })
+    toast({ text: 'Copied', type: 'success' })
   } catch {
-    globalThis.window?.__fcToast?.({ text: 'Copy failed', type: 'error' })
+    toast({ text: 'Copy failed', type: 'error' })
   }
 }
 
@@ -50,7 +51,7 @@ function confirmRotate() { showRotateConfirm.value = true }
 async function doRotate() {
   showRotateConfirm.value = false
   await store.rotateKey()
-  globalThis.window?.__fcToast?.({ text: 'Key rotated', type: 'success' })
+  toast({ text: 'Key rotated', type: 'success' })
 }
 </script>
 
diff --git a/frontend/src/components/downloads/DownloadDetailModal.vue b/frontend/src/components/downloads/DownloadDetailModal.vue
index 35bb921..e8c4697 100644
--- a/frontend/src/components/downloads/DownloadDetailModal.vue
+++ b/frontend/src/components/downloads/DownloadDetailModal.vue
@@ -101,6 +101,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed } from 'vue'
 
 import { copyText } from '../../utils/clipboard.js'
@@ -133,9 +134,9 @@ const allDiagnostics = computed(() => {
 async function onCopy(label, text) {
   try {
     await copyText(text || '')
-    window.__fcToast?.({ text: `${label} copied`, type: 'success' })
+    toast({ text: `${label} copied`, type: 'success' })
   } catch (e) {
-    window.__fcToast?.({ text: `Copy failed: ${e.message}`, type: 'error' })
+    toast({ text: `Copy failed: ${e.message}`, type: 'error' })
   }
 }
 
diff --git a/frontend/src/components/downloads/DownloadEventRow.vue b/frontend/src/components/downloads/DownloadEventRow.vue
index fb2999b..c18b873 100644
--- a/frontend/src/components/downloads/DownloadEventRow.vue
+++ b/frontend/src/components/downloads/DownloadEventRow.vue
@@ -86,11 +86,13 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, ref } from 'vue'
 import { RouterLink } from 'vue-router'
 
 import PlatformChip from '../subscriptions/PlatformChip.vue'
 import { useSourcesStore } from '../../stores/sources.js'
+import { downloadStatusColor, downloadStatusIcon, downloadStatusLabel } from '../../utils/downloadStatus.js'
 
 const props = defineProps({ event: { type: Object, required: true } })
 defineEmits(['open'])
@@ -98,16 +100,9 @@ defineEmits(['open'])
 const sourcesStore = useSourcesStore()
 const retrying = ref(false)
 
-const _STATUS = {
-  ok:      { color: 'success', icon: 'mdi-check-circle',    label: 'Completed' },
-  error:   { color: 'error',   icon: 'mdi-alert-circle',    label: 'Failed' },
-  running: { color: 'info',    icon: 'mdi-progress-clock',  label: 'Running' },
-  pending: { color: 'grey',    icon: 'mdi-clock-outline',   label: 'Queued' },
-  skipped: { color: 'warning', icon: 'mdi-skip-next',       label: 'Skipped' },
-}
-const statusColor = computed(() => _STATUS[props.event.status]?.color || 'grey')
-const statusIcon = computed(() => _STATUS[props.event.status]?.icon || 'mdi-help-circle')
-const statusLabel = computed(() => _STATUS[props.event.status]?.label || props.event.status)
+const statusColor = computed(() => downloadStatusColor(props.event.status))
+const statusIcon = computed(() => downloadStatusIcon(props.event.status))
+const statusLabel = computed(() => downloadStatusLabel(props.event.status))
 
 function fmtTime(iso) {
   if (!iso) return '—'
@@ -131,12 +126,12 @@ async function onRetry() {
   retrying.value = true
   try {
     await sourcesStore.checkNow(props.event.source_id)
-    globalThis.window?.__fcToast?.({
+    toast({
       text: `Source check re-queued`, type: 'success',
     })
   } catch (e) {
     const isInFlight = !!e?.body?.download_event_id
-    globalThis.window?.__fcToast?.({
+    toast({
       text: isInFlight ? 'Already running' : `Retry failed: ${e?.detail || e?.message || e}`,
       type: isInFlight ? 'info' : 'error',
     })
diff --git a/frontend/src/components/modal/SuggestionsPanel.vue b/frontend/src/components/modal/SuggestionsPanel.vue
index a5f8353..0ca5cea 100644
--- a/frontend/src/components/modal/SuggestionsPanel.vue
+++ b/frontend/src/components/modal/SuggestionsPanel.vue
@@ -38,6 +38,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, ref, watch } from 'vue'
 import { useSuggestionsStore, CATEGORY_LABELS } from '../../stores/suggestions.js'
 import SuggestionsCategoryGroup from './SuggestionsCategoryGroup.vue'
@@ -57,7 +58,7 @@ watch(() => props.imageId, (id) => { if (id != null) store.load(id) }, { immedia
 
 async function onAccept(s) {
   try { await store.accept(s) }
-  catch (e) { window.__fcToast?.({ text: `Accept failed: ${e.message}`, type: 'error' }) }
+  catch (e) { toast({ text: `Accept failed: ${e.message}`, type: 'error' }) }
 }
 
 const aliasDialog = ref(false)
@@ -68,7 +69,7 @@ async function onAliasConfirm(canonicalTagId) {
     await store.aliasAccept(aliasTarget.value, canonicalTagId)
     aliasDialog.value = false
   } catch (e) {
-    window.__fcToast?.({ text: `Alias failed: ${e.message}`, type: 'error' })
+    toast({ text: `Alias failed: ${e.message}`, type: 'error' })
   }
 }
 </script>
diff --git a/frontend/src/components/settings/BackupRunsTable.vue b/frontend/src/components/settings/BackupRunsTable.vue
index dc15d24..0d12676 100644
--- a/frontend/src/components/settings/BackupRunsTable.vue
+++ b/frontend/src/components/settings/BackupRunsTable.vue
@@ -59,6 +59,8 @@
 </template>
 
 <script setup>
+import { formatRelative as fmtRelative } from '../../utils/date.js'
+
 defineProps({ runs: { type: Array, default: () => [] } })
 defineEmits(['restore', 'delete', 'tag'])
 
@@ -92,13 +94,7 @@ function formatBytes(b) {
   return `${v.toFixed(i === 0 ? 0 : 1)} ${units[i]}`
 }
 function formatRelative(iso) {
-  if (!iso) return '—'
-  const then = new Date(iso).getTime()
-  const diff = Math.max(0, (Date.now() - then) / 1000)
-  if (diff < 60) return `${Math.floor(diff)}s ago`
-  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`
-  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`
-  return `${Math.floor(diff / 86400)}d ago`
+  return fmtRelative(iso, { nullText: '—' })
 }
 </script>
 
diff --git a/frontend/src/components/settings/BrowserExtensionCard.vue b/frontend/src/components/settings/BrowserExtensionCard.vue
index 2a0bedb..b3d7a41 100644
--- a/frontend/src/components/settings/BrowserExtensionCard.vue
+++ b/frontend/src/components/settings/BrowserExtensionCard.vue
@@ -108,6 +108,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, onMounted, ref } from 'vue'
 import { useApi } from '../../composables/useApi.js'
 import { copyText } from '../../utils/clipboard.js'
@@ -147,7 +148,7 @@ async function loadKey() {
     apiKey.value = key
   } catch (e) {
     apiKey.value = ''
-    window.__fcToast?.({
+    toast({
       text: `Failed to load extension API key: ${e.message}`,
       type: 'error',
     })
@@ -160,9 +161,9 @@ async function rotateKey() {
     const { key } = await api.post('/api/settings/extension_api_key/rotate')
     apiKey.value = key
     keyShown.value = true
-    window.__fcToast?.({ text: 'Extension API key rotated.', type: 'success' })
+    toast({ text: 'Extension API key rotated.', type: 'success' })
   } catch (e) {
-    window.__fcToast?.({
+    toast({
       text: `Rotate failed: ${e.message}`,
       type: 'error',
     })
@@ -174,9 +175,9 @@ async function rotateKey() {
 async function copy(text, label) {
   try {
     await copyText(text)
-    window.__fcToast?.({ text: `${label} copied.`, type: 'success' })
+    toast({ text: `${label} copied.`, type: 'success' })
   } catch (e) {
-    window.__fcToast?.({ text: `Copy failed: ${e.message}`, type: 'error' })
+    toast({ text: `Copy failed: ${e.message}`, type: 'error' })
   }
 }
 </script>
diff --git a/frontend/src/components/settings/CentroidRecomputeCard.vue b/frontend/src/components/settings/CentroidRecomputeCard.vue
index 22bf4bd..1f49210 100644
--- a/frontend/src/components/settings/CentroidRecomputeCard.vue
+++ b/frontend/src/components/settings/CentroidRecomputeCard.vue
@@ -16,6 +16,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { ref } from 'vue'
 import { useMLStore } from '../../stores/ml.js'
 const store = useMLStore()
@@ -24,7 +25,7 @@ const done = ref(false)
 async function run() {
   busy.value = true
   try { await store.triggerRecomputeCentroids(); done.value = true }
-  catch (e) { window.__fcToast?.({ text: e.message, type: 'error' }) }
+  catch (e) { toast({ text: e.message, type: 'error' }) }
   finally { busy.value = false }
 }
 </script>
diff --git a/frontend/src/components/settings/ImportTaskList.vue b/frontend/src/components/settings/ImportTaskList.vue
index 4eadf3c..a3c78e2 100644
--- a/frontend/src/components/settings/ImportTaskList.vue
+++ b/frontend/src/components/settings/ImportTaskList.vue
@@ -125,6 +125,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, ref } from 'vue'
 import { useImportStore } from '../../stores/import.js'
 import ErrorDetailModal from '../common/ErrorDetailModal.vue'
@@ -177,9 +178,9 @@ async function onRefetch(item) {
   try {
     const res = await store.refetchTask(item.id)
     const msg = _REFETCH_MSG[res.status] || { text: `Re-fetch: ${res.status}`, type: 'info' }
-    window.__fcToast?.(msg)
+    toast(msg)
   } catch (e) {
-    window.__fcToast?.({ text: `Re-fetch failed: ${e.message}`, type: 'error' })
+    toast({ text: `Re-fetch failed: ${e.message}`, type: 'error' })
   } finally {
     refetching.value = null
   }
diff --git a/frontend/src/components/settings/MLBackfillCard.vue b/frontend/src/components/settings/MLBackfillCard.vue
index 4380971..1023811 100644
--- a/frontend/src/components/settings/MLBackfillCard.vue
+++ b/frontend/src/components/settings/MLBackfillCard.vue
@@ -15,6 +15,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { ref } from 'vue'
 import { useMLStore } from '../../stores/ml.js'
 const store = useMLStore()
@@ -23,7 +24,7 @@ const done = ref(false)
 async function run() {
   busy.value = true
   try { await store.triggerBackfill(); done.value = true }
-  catch (e) { window.__fcToast?.({ text: e.message, type: 'error' }) }
+  catch (e) { toast({ text: e.message, type: 'error' }) }
   finally { busy.value = false }
 }
 </script>
diff --git a/frontend/src/components/settings/MLThresholdSliders.vue b/frontend/src/components/settings/MLThresholdSliders.vue
index 34304d3..8919e3b 100644
--- a/frontend/src/components/settings/MLThresholdSliders.vue
+++ b/frontend/src/components/settings/MLThresholdSliders.vue
@@ -17,6 +17,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { reactive, watch } from 'vue'
 import { useMLStore } from '../../stores/ml.js'
 
@@ -35,6 +36,6 @@ async function save() {
   const patch = {}
   for (const f of fields) patch[f.key] = local[f.key]
   try { await store.patchSettings(patch) }
-  catch (e) { window.__fcToast?.({ text: e.message, type: 'error' }) }
+  catch (e) { toast({ text: e.message, type: 'error' }) }
 }
 </script>
diff --git a/frontend/src/components/settings/SystemActivityTab.vue b/frontend/src/components/settings/SystemActivityTab.vue
index 0d6485c..fe9db71 100644
--- a/frontend/src/components/settings/SystemActivityTab.vue
+++ b/frontend/src/components/settings/SystemActivityTab.vue
@@ -154,6 +154,7 @@
 import { computed, onMounted, onUnmounted, ref } from 'vue'
 
 import { useSystemActivityStore } from '../../stores/systemActivity.js'
+import { formatRelative as fmtRelative } from '../../utils/date.js'
 import ErrorDetailModal from '../common/ErrorDetailModal.vue'
 import QueuesTable from './QueuesTable.vue'
 
@@ -277,14 +278,7 @@ function formatDuration(ms) {
   return `${(ms / 60_000).toFixed(1)} min`
 }
 function formatRelative(iso) {
-  if (!iso) return '—'
-  const then = new Date(iso).getTime()
-  const now = Date.now()
-  const diff = Math.max(0, (now - then) / 1000)
-  if (diff < 60) return `${Math.floor(diff)}s ago`
-  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`
-  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`
-  return `${Math.floor(diff / 86400)}d ago`
+  return fmtRelative(iso, { nullText: '—' })
 }
 </script>
 
diff --git a/frontend/src/components/settings/ThumbnailBackfillCard.vue b/frontend/src/components/settings/ThumbnailBackfillCard.vue
index 489c45f..37aab2a 100644
--- a/frontend/src/components/settings/ThumbnailBackfillCard.vue
+++ b/frontend/src/components/settings/ThumbnailBackfillCard.vue
@@ -16,6 +16,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { ref } from 'vue'
 import { useThumbnailsStore } from '../../stores/thumbnails.js'
 const store = useThumbnailsStore()
@@ -24,7 +25,7 @@ const done = ref(false)
 async function run () {
   busy.value = true
   try { await store.triggerBackfill(); done.value = true }
-  catch (e) { window.__fcToast?.({ text: e.message, type: 'error' }) }
+  catch (e) { toast({ text: e.message, type: 'error' }) }
   finally { busy.value = false }
 }
 </script>
diff --git a/frontend/src/components/subscriptions/ArtistCreateDialog.vue b/frontend/src/components/subscriptions/ArtistCreateDialog.vue
index 8efde7d..c60afa5 100644
--- a/frontend/src/components/subscriptions/ArtistCreateDialog.vue
+++ b/frontend/src/components/subscriptions/ArtistCreateDialog.vue
@@ -20,6 +20,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { ref, watch } from 'vue'
 import { useSourcesStore } from '../../stores/sources.js'
 
@@ -44,7 +45,7 @@ async function submit() {
   busy.value = true
   try {
     const { artist, created } = await store.findOrCreateArtist(name.value.trim())
-    globalThis.window?.__fcToast?.({
+    toast({
       text: created ? 'Artist created' : 'Artist already exists',
       type: 'success',
     })
diff --git a/frontend/src/components/subscriptions/CredentialCard.vue b/frontend/src/components/subscriptions/CredentialCard.vue
index 8427a48..182b09e 100644
--- a/frontend/src/components/subscriptions/CredentialCard.vue
+++ b/frontend/src/components/subscriptions/CredentialCard.vue
@@ -98,6 +98,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, ref } from 'vue'
 import PlatformChip from './PlatformChip.vue'
 import { useCredentialsStore } from '../../stores/credentials.js'
@@ -126,11 +127,11 @@ async function onVerify() {
     const res = await credsStore.verify(props.platform.key)
     verifyResult.value = res
     const type = res.valid === true ? 'success' : (res.valid === false ? 'error' : 'info')
-    window.__fcToast?.({ text: `${props.platform.name}: ${res.reason}`, type })
+    toast({ text: `${props.platform.name}: ${res.reason}`, type })
     if (res.valid === true) emit('verified')
   } catch (e) {
     verifyResult.value = { valid: false, reason: e.message }
-    window.__fcToast?.({ text: `Verify failed: ${e.message}`, type: 'error' })
+    toast({ text: `Verify failed: ${e.message}`, type: 'error' })
   } finally {
     verifying.value = false
   }
diff --git a/frontend/src/components/subscriptions/DownloadStatChips.vue b/frontend/src/components/subscriptions/DownloadStatChips.vue
index e2e3ab1..d04387e 100644
--- a/frontend/src/components/subscriptions/DownloadStatChips.vue
+++ b/frontend/src/components/subscriptions/DownloadStatChips.vue
@@ -1,38 +1,30 @@
 <template>
   <div class="fc-dl-stats">
     <v-chip
-      v-for="s in STAT_DEFS" :key="s.key"
+      v-for="s in STAT_DEFS" :key="s.value"
       :color="s.color"
-      :variant="activeStatus === s.key ? 'elevated' : 'tonal'"
+      :variant="activeStatus === s.value ? 'elevated' : 'tonal'"
       :prepend-icon="s.icon"
       size="default"
-      :class="{ 'fc-dl-stats__active': activeStatus === s.key }"
-      @click="$emit('select', activeStatus === s.key ? null : s.key)"
+      :class="{ 'fc-dl-stats__active': activeStatus === s.value }"
+      @click="$emit('select', activeStatus === s.value ? null : s.value)"
     >
       {{ s.label }}
-      <strong class="ms-1">{{ stats[s.key] ?? 0 }}</strong>
+      <strong class="ms-1">{{ stats[s.value] ?? 0 }}</strong>
     </v-chip>
   </div>
 </template>
 
 <script setup>
+import { DOWNLOAD_STATUSES as STAT_DEFS } from '../../utils/downloadStatus.js'
+
 defineProps({
   stats: { type: Object, required: true },
-  // The currently-active status filter key (pending|running|ok|error|
+  // The currently-active status filter value (pending|running|ok|error|
   // skipped) or null. Highlights the matching chip.
   activeStatus: { type: String, default: null },
 })
 defineEmits(['select'])
-
-// status keys come straight from the backend ENUM
-// (pending|running|ok|error|skipped); display order + icons are UI-only.
-const STAT_DEFS = [
-  { key: 'pending',  label: 'Queued',    color: 'grey',    icon: 'mdi-clock-outline' },
-  { key: 'running',  label: 'Running',   color: 'info',    icon: 'mdi-progress-clock' },
-  { key: 'ok',       label: 'Completed', color: 'success', icon: 'mdi-check-circle' },
-  { key: 'error',    label: 'Failed',    color: 'error',   icon: 'mdi-alert-circle' },
-  { key: 'skipped',  label: 'Skipped',   color: 'warning', icon: 'mdi-skip-next' },
-]
 </script>
 
 <style scoped>
diff --git a/frontend/src/components/subscriptions/DownloadsFilterPopover.vue b/frontend/src/components/subscriptions/DownloadsFilterPopover.vue
index 4ba8e24..0bef8d0 100644
--- a/frontend/src/components/subscriptions/DownloadsFilterPopover.vue
+++ b/frontend/src/components/subscriptions/DownloadsFilterPopover.vue
@@ -68,6 +68,7 @@
 import { computed, reactive, ref, watch } from 'vue'
 
 import { useSourcesStore } from '../../stores/sources.js'
+import { DOWNLOAD_STATUSES, downloadStatusLabel } from '../../utils/downloadStatus.js'
 
 const props = defineProps({
   modelValue: { type: Object, required: true },
@@ -76,14 +77,7 @@ const emit = defineEmits(['update:modelValue'])
 
 const sourcesStore = useSourcesStore()
 
-const STATUS_OPTIONS = [
-  { title: 'Queued',    value: 'pending' },
-  { title: 'Running',   value: 'running' },
-  { title: 'Completed', value: 'ok' },
-  { title: 'Failed',    value: 'error' },
-  { title: 'Skipped',   value: 'skipped' },
-]
-const STATUS_LABEL = Object.fromEntries(STATUS_OPTIONS.map((o) => [o.value, o.title]))
+const STATUS_OPTIONS = DOWNLOAD_STATUSES.map((s) => ({ title: s.label, value: s.value }))
 
 const open = ref(false)
 const local = reactive({
@@ -122,7 +116,7 @@ function onArtistPick(id) {
 
 const activePills = computed(() => {
   const out = []
-  if (local.status)    out.push({ key: 'status',    label: `Status: ${STATUS_LABEL[local.status] || local.status}` })
+  if (local.status)    out.push({ key: 'status',    label: `Status: ${downloadStatusLabel(local.status)}` })
   if (local.artist_id) out.push({ key: 'artist_id', label: `Artist: ${local.artist_name || `#${local.artist_id}`}` })
   if (local.from_date) out.push({ key: 'from_date', label: `From ${local.from_date}` })
   if (local.to_date)   out.push({ key: 'to_date',   label: `To ${local.to_date}` })
diff --git a/frontend/src/components/subscriptions/DownloadsTab.vue b/frontend/src/components/subscriptions/DownloadsTab.vue
index e1cd3e0..36c2718 100644
--- a/frontend/src/components/subscriptions/DownloadsTab.vue
+++ b/frontend/src/components/subscriptions/DownloadsTab.vue
@@ -113,6 +113,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
 import { useRoute } from 'vue-router'
 
@@ -167,12 +168,12 @@ async function refresh() {
 async function onRetrySource(source) {
   try {
     await sourcesStore.checkNow(source.id)
-    globalThis.window?.__fcToast?.({ text: `Retry queued for ${source.artist_name || source.platform}`, type: 'success' })
+    toast({ text: `Retry queued for ${source.artist_name || source.platform}`, type: 'success' })
   } catch (e) {
     if (e?.body?.download_event_id) {
-      globalThis.window?.__fcToast?.({ text: 'Already running — see below', type: 'info' })
+      toast({ text: 'Already running — see below', type: 'info' })
     } else {
-      globalThis.window?.__fcToast?.({ text: `Retry failed: ${e?.detail || e?.message || e}`, type: 'error' })
+      toast({ text: `Retry failed: ${e?.detail || e?.message || e}`, type: 'error' })
     }
   } finally {
     await Promise.all([store.loadFailing(), store.loadStats(24), store.loadFirst()])
@@ -199,7 +200,7 @@ async function onRetryAll(sources) {
   const parts = []
   if (ok) parts.push(`${ok} queued`)
   if (conflict) parts.push(`${conflict} already running`)
-  globalThis.window?.__fcToast?.({ text: parts.join(', ') || 'Nothing to retry', type: 'info' })
+  toast({ text: parts.join(', ') || 'Nothing to retry', type: 'info' })
 }
 
 // Live auto-refresh: while any download is queued or running, poll the
diff --git a/frontend/src/components/subscriptions/MaintenanceMenu.vue b/frontend/src/components/subscriptions/MaintenanceMenu.vue
index dc2d57e..b89d045 100644
--- a/frontend/src/components/subscriptions/MaintenanceMenu.vue
+++ b/frontend/src/components/subscriptions/MaintenanceMenu.vue
@@ -31,6 +31,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { useImportStore } from '../../stores/import.js'
 
 const emit = defineEmits(['refresh'])
@@ -39,10 +40,10 @@ const importStore = useImportStore()
 async function onRetry() {
   try {
     await importStore.retryFailed()
-    globalThis.window?.__fcToast?.({ text: 'Retry queued', type: 'success' })
+    toast({ text: 'Retry queued', type: 'success' })
     emit('refresh')
   } catch (e) {
-    globalThis.window?.__fcToast?.({ text: `Retry failed: ${e?.detail || e?.message || e}`, type: 'error' })
+    toast({ text: `Retry failed: ${e?.detail || e?.message || e}`, type: 'error' })
   }
 }
 
@@ -50,13 +51,13 @@ async function onClear() {
   try {
     const body = await importStore.clearStuck()
     const n = body?.cleared ?? 0
-    globalThis.window?.__fcToast?.({
+    toast({
       text: n ? `Cleared ${n} stuck task${n === 1 ? '' : 's'}` : 'Nothing stuck',
       type: 'success',
     })
     emit('refresh')
   } catch (e) {
-    globalThis.window?.__fcToast?.({ text: `Clear failed: ${e?.detail || e?.message || e}`, type: 'error' })
+    toast({ text: `Clear failed: ${e?.detail || e?.message || e}`, type: 'error' })
   }
 }
 </script>
diff --git a/frontend/src/components/subscriptions/SchedulerStatusBar.vue b/frontend/src/components/subscriptions/SchedulerStatusBar.vue
index 46ec14c..59f8bb2 100644
--- a/frontend/src/components/subscriptions/SchedulerStatusBar.vue
+++ b/frontend/src/components/subscriptions/SchedulerStatusBar.vue
@@ -24,6 +24,7 @@
 
 <script setup>
 import { computed } from 'vue'
+import { formatRelative } from '../../utils/date.js'
 
 const props = defineProps({
   // { last_tick_at, next_due_at, due_now, auto_sources } | null
@@ -45,16 +46,8 @@ const health = computed(() => {
   return tickAgeMs.value <= STALE_MS ? 'ok' : 'stale'
 })
 
-function rel(ms) {
-  const s = Math.max(0, Math.floor(ms / 1000))
-  if (s < 60) return `${s}s ago`
-  if (s < 3600) return `${Math.floor(s / 60)}m ago`
-  if (s < 86400) return `${Math.floor(s / 3600)}h ago`
-  return `${Math.floor(s / 86400)}d ago`
-}
-
 const lastRanLabel = computed(() =>
-  tickAgeMs.value == null ? 'never' : rel(tickAgeMs.value),
+  formatRelative(props.status?.last_tick_at, { nullText: 'never' }),
 )
 
 const nextLabel = computed(() => {
diff --git a/frontend/src/components/subscriptions/SourceHealthDot.vue b/frontend/src/components/subscriptions/SourceHealthDot.vue
index 44333ef..145044d 100644
--- a/frontend/src/components/subscriptions/SourceHealthDot.vue
+++ b/frontend/src/components/subscriptions/SourceHealthDot.vue
@@ -22,6 +22,7 @@
 
 <script setup>
 import { computed } from 'vue'
+import { formatRelative } from '../../utils/date.js'
 
 const props = defineProps({
   source: { type: Object, required: true },
@@ -38,28 +39,13 @@ const level = computed(() => {
 
 const ariaLabel = computed(() => `source health: ${level.value}`)
 
-function relativeTime(iso) {
-  if (!iso) return 'Never'
-  const then = new Date(iso).getTime()
-  const now = Date.now()
-  const diff = Math.abs(now - then) / 1000
-  if (diff < 60) return `${Math.floor(diff)}s`
-  if (diff < 3600) return `${Math.floor(diff / 60)}m`
-  if (diff < 86400) return `${Math.floor(diff / 3600)}h`
-  return `${Math.floor(diff / 86400)}d`
-}
+const lastCheckedText = computed(() => formatRelative(props.source.last_checked_at))
 
-const lastCheckedText = computed(() => {
-  if (!props.source.last_checked_at) return 'Never'
-  return `${relativeTime(props.source.last_checked_at)} ago`
-})
-
-const nextCheckText = computed(() => {
-  if (!props.source.next_check_at) return null
-  const due = new Date(props.source.next_check_at).getTime()
-  if (due <= Date.now()) return 'imminent'
-  return `in ~${relativeTime(props.source.next_check_at)}`
-})
+const nextCheckText = computed(() =>
+  props.source.next_check_at
+    ? formatRelative(props.source.next_check_at, { future: true })
+    : null,
+)
 
 const truncatedError = computed(() => {
   const e = props.source.last_error || ''
diff --git a/frontend/src/components/subscriptions/SourceRow.vue b/frontend/src/components/subscriptions/SourceRow.vue
index 63f3bf4..c30a45c 100644
--- a/frontend/src/components/subscriptions/SourceRow.vue
+++ b/frontend/src/components/subscriptions/SourceRow.vue
@@ -62,6 +62,7 @@
 
 <script setup>
 import SourceHealthDot from './SourceHealthDot.vue'
+import { formatRelative } from '../../utils/date.js'
 
 const props = defineProps({
   source: { type: Object, required: true },
@@ -73,23 +74,6 @@ const emit = defineEmits(['edit', 'remove', 'toggle', 'check'])
 function onToggleEnabled(value) {
   emit('toggle', { source: props.source, enabled: value })
 }
-
-function formatRelative(iso, opts = {}) {
-  if (!iso) return opts.future ? '—' : 'Never'
-  const then = new Date(iso).getTime()
-  const now = Date.now()
-  const diff = (then - now) / 1000  // seconds; positive = future, negative = past
-  const abs = Math.abs(diff)
-
-  let body
-  if (abs < 60) body = `${Math.floor(abs)}s`
-  else if (abs < 3600) body = `${Math.floor(abs / 60)}m`
-  else if (abs < 86400) body = `${Math.floor(abs / 3600)}h`
-  else body = `${Math.floor(abs / 86400)}d`
-
-  if (opts.future) return diff <= 0 ? 'imminent' : `in ${body}`
-  return `${body} ago`
-}
 </script>
 
 <style scoped>
diff --git a/frontend/src/components/subscriptions/SubscriptionsTab.vue b/frontend/src/components/subscriptions/SubscriptionsTab.vue
index 7c07ffb..2fe5cc8 100644
--- a/frontend/src/components/subscriptions/SubscriptionsTab.vue
+++ b/frontend/src/components/subscriptions/SubscriptionsTab.vue
@@ -199,6 +199,7 @@
 </template>
 
 <script setup>
+import { toast } from '../../utils/toast.js'
 import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useSourcesStore } from '../../stores/sources.js'
@@ -210,6 +211,7 @@ import SourceFormDialog from './SourceFormDialog.vue'
 import ArtistCreateDialog from './ArtistCreateDialog.vue'
 import PlatformChip from './PlatformChip.vue'
 import SchedulerStatusBar from './SchedulerStatusBar.vue'
+import { formatRelative } from '../../utils/date.js'
 
 const ITEMS_PER_PAGE_OPTIONS = [
   { value: 25, title: '25' },
@@ -365,16 +367,6 @@ function pickWorstSource(sources, threshold) {
   return sources.reduce((worst, s) => (level(s) > level(worst) ? s : worst), sources[0])
 }
 
-function formatRelative(iso) {
-  if (!iso) return 'Never'
-  const then = new Date(iso).getTime()
-  const diff = (Date.now() - then) / 1000
-  if (diff < 60) return `${Math.floor(diff)}s ago`
-  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`
-  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`
-  return `${Math.floor(diff / 86400)}d ago`
-}
-
 function onRowClick(_evt, { item }) {
   const key = item.key
   const idx = expanded.value.indexOf(key)
@@ -419,19 +411,19 @@ function onArtistCreated(artist) {
 async function onCheck(source) {
   try {
     const body = await store.checkNow(source.id)
-    globalThis.window?.__fcToast?.({
+    toast({
       text: `Check enqueued (event #${body.download_event_id})`,
       type: 'success',
     })
   } catch (e) {
     if (e?.body?.download_event_id) {
-      globalThis.window?.__fcToast?.({
+      toast({
         text: 'Already running — see Downloads',
         type: 'info',
       })
       router.push({ path: '/subscriptions', query: { tab: 'downloads', source_id: source.id } })
     } else {
-      globalThis.window?.__fcToast?.({
+      toast({
         text: `Check failed: ${e?.detail || e?.message || e}`,
         type: 'error',
       })
@@ -454,7 +446,7 @@ async function checkAll(group) {
   const parts = []
   if (ok) parts.push(`${ok} queued`)
   if (conflict) parts.push(`${conflict} already running`)
-  globalThis.window?.__fcToast?.({
+  toast({
     text: parts.join(', ') || 'Nothing to check (no enabled sources)',
     type: 'info',
   })
@@ -481,7 +473,7 @@ async function bulkSetEnabled(enabled) {
     }
   }
   await refresh()
-  globalThis.window?.__fcToast?.({
+  toast({
     text: `${changed} source${changed === 1 ? '' : 's'} ${enabled ? 'enabled' : 'disabled'}`,
     type: 'success',
   })
@@ -504,7 +496,7 @@ async function bulkDelete() {
     }
   }
   await refresh()
-  globalThis.window?.__fcToast?.({
+  toast({
     text: `${deleted} source${deleted === 1 ? '' : 's'} deleted`,
     type: 'success',
   })
diff --git a/frontend/src/stores/gallerySelection.js b/frontend/src/stores/gallerySelection.js
index daf31a0..2eaa4e6 100644
--- a/frontend/src/stores/gallerySelection.js
+++ b/frontend/src/stores/gallerySelection.js
@@ -1,4 +1,5 @@
 import { defineStore } from 'pinia'
+import { toast } from '../utils/toast.js'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
 
@@ -51,7 +52,7 @@ export const useGallerySelectionStore = defineStore('gallerySelection', () => {
       body: { image_ids: order.value, tag_id: tagId, source }
     })
     await refresh()
-    globalThis.window?.__fcToast?.({
+    toast({
       text: `Added to ${body.added_count} image(s)`, type: 'success'
     })
     return body
@@ -62,7 +63,7 @@ export const useGallerySelectionStore = defineStore('gallerySelection', () => {
       body: { image_ids: order.value, tag_id: tagId }
     })
     await refresh()
-    globalThis.window?.__fcToast?.({
+    toast({
       text: `Removed from ${body.removed_count} image(s)`, type: 'success'
     })
     return body
diff --git a/frontend/src/stores/import.js b/frontend/src/stores/import.js
index 98d4d56..f52c436 100644
--- a/frontend/src/stores/import.js
+++ b/frontend/src/stores/import.js
@@ -1,4 +1,5 @@
 import { defineStore } from 'pinia'
+import { toast } from '../utils/toast.js'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
 
@@ -37,7 +38,7 @@ export const useImportStore = defineStore('import', () => {
       settings.value = await api.patch('/api/settings/import', { body: patch })
     } catch (e) {
       settingsError.value = e.message
-      window.__fcToast?.({ text: `Settings save failed: ${e.message}`, type: 'error' })
+      toast({ text: `Settings save failed: ${e.message}`, type: 'error' })
       throw e
     }
   }
@@ -68,7 +69,7 @@ export const useImportStore = defineStore('import', () => {
       const label = mode === 'deep'
         ? 'Deep scan triggered (re-applying sidecar metadata + filling NULL phash/artist on existing rows)'
         : mode === 'verify' ? 'Library verify triggered' : 'Quick scan triggered'
-      window.__fcToast?.({ text: label, type: 'success' })
+      toast({ text: label, type: 'success' })
       await refreshStatus()
       // Re-poll twice over ~5s and produce an HONEST follow-up toast.
       // Operator-flagged 2026-05-25: the prior "no new files" message was
@@ -91,22 +92,22 @@ export const useImportStore = defineStore('import', () => {
         const refreshedCount = sameBatch.filter(t => t.status === 'complete' && t.result_image_id).length
         const newImported = sameBatch.filter(t => t.status === 'complete' && t.result_image_id && !t.error).length
         if (mode === 'deep' && sameBatch.length > 0) {
-          window.__fcToast?.({
+          toast({
             text: `Deep scan finished — ${sameBatch.length} file(s) processed`,
             type: 'info',
           })
         } else if (mode === 'quick' && sameBatch.length > 0) {
-          window.__fcToast?.({
+          toast({
             text: `Quick scan finished — ${newImported} new file(s) queued`,
             type: 'info',
           })
         } else {
-          window.__fcToast?.({ text: 'Library is up to date', type: 'info' })
+          toast({ text: 'Library is up to date', type: 'info' })
         }
       }, 2000)
     } catch (e) {
       triggerError.value = e.message
-      window.__fcToast?.({ text: `Scan failed: ${e.message}`, type: 'error' })
+      toast({ text: `Scan failed: ${e.message}`, type: 'error' })
       throw e
     }
   }
diff --git a/frontend/src/stores/modal.js b/frontend/src/stores/modal.js
index feffb15..2efbe42 100644
--- a/frontend/src/stores/modal.js
+++ b/frontend/src/stores/modal.js
@@ -1,4 +1,5 @@
 import { defineStore } from 'pinia'
+import { toast } from '../utils/toast.js'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
 
@@ -96,7 +97,7 @@ export const useModalStore = defineStore('modal', () => {
       })
     } catch (e) {
       current.value.tags = prev
-      window.__fcToast?.({ text: `Failed to remove tag: ${e.message}`, type: 'error' })
+      toast({ text: `Failed to remove tag: ${e.message}`, type: 'error' })
       throw e
     }
   }
diff --git a/frontend/src/stores/seriesManage.js b/frontend/src/stores/seriesManage.js
index 17f84ee..3967b68 100644
--- a/frontend/src/stores/seriesManage.js
+++ b/frontend/src/stores/seriesManage.js
@@ -1,4 +1,5 @@
 import { defineStore } from 'pinia'
+import { toast } from '../utils/toast.js'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
 
@@ -59,7 +60,7 @@ export const useSeriesManageStore = defineStore('seriesManage', () => {
     })
     pickerSelection.value = []
     await refresh()
-    globalThis.window?.__fcToast?.({ text: 'Added to series', type: 'success' })
+    toast({ text: 'Added to series', type: 'success' })
   }
 
   async function remove(imageId) {
diff --git a/frontend/src/stores/suggestions.js b/frontend/src/stores/suggestions.js
index d9914e4..0e4447c 100644
--- a/frontend/src/stores/suggestions.js
+++ b/frontend/src/stores/suggestions.js
@@ -1,4 +1,5 @@
 import { defineStore } from 'pinia'
+import { toast } from '../utils/toast.js'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
 
@@ -54,7 +55,7 @@ export const useSuggestionsStore = defineStore('suggestions', () => {
       body: { tag_id: tagId }
     })
     _drop(suggestion.category, s => s === suggestion)
-    window.__fcToast?.({
+    toast({
       text: `Tagged: ${suggestion.display_name}`,
       type: 'success'
     })
@@ -69,7 +70,7 @@ export const useSuggestionsStore = defineStore('suggestions', () => {
       }
     })
     _drop(suggestion.category, s => s === suggestion)
-    window.__fcToast?.({
+    toast({
       text: `Aliased & tagged: ${suggestion.display_name}`,
       type: 'success'
     })
diff --git a/frontend/src/utils/date.js b/frontend/src/utils/date.js
index f0ade54..16f6fd3 100644
--- a/frontend/src/utils/date.js
+++ b/frontend/src/utils/date.js
@@ -13,3 +13,22 @@ export function formatPostDate(iso) {
   if (isNaN(d.getTime())) return null
   return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`
 }
+
+// Compact relative formatter: "5m ago" (past) or "in 3h" (future). Null /
+// invalid input returns `nullText`. Pass { future: true } for upcoming
+// timestamps; a future time already elapsed reads as "imminent".
+export function formatRelative(iso, opts = {}) {
+  const { future = false, nullText = future ? '—' : 'Never' } = opts
+  if (!iso) return nullText
+  const then = new Date(iso).getTime()
+  if (isNaN(then)) return nullText
+  const diff = (then - Date.now()) / 1000  // +ve = future
+  const abs = Math.abs(diff)
+  let body
+  if (abs < 60) body = `${Math.floor(abs)}s`
+  else if (abs < 3600) body = `${Math.floor(abs / 60)}m`
+  else if (abs < 86400) body = `${Math.floor(abs / 3600)}h`
+  else body = `${Math.floor(abs / 86400)}d`
+  if (future) return diff <= 0 ? 'imminent' : `in ${body}`
+  return `${body} ago`
+}
diff --git a/frontend/src/utils/downloadStatus.js b/frontend/src/utils/downloadStatus.js
new file mode 100644
index 0000000..62821f5
--- /dev/null
+++ b/frontend/src/utils/downloadStatus.js
@@ -0,0 +1,21 @@
+// Single source of truth for the download-event status enum -> display
+// metadata (label/color/icon). Mirrors the backend ENUM
+// (pending|running|ok|error|skipped). Used by the stat chips, the filter
+// dropdown, and the event rows so they never drift apart.
+
+export const DOWNLOAD_STATUSES = [
+  { value: 'pending', label: 'Queued',    color: 'grey',    icon: 'mdi-clock-outline' },
+  { value: 'running', label: 'Running',   color: 'info',    icon: 'mdi-progress-clock' },
+  { value: 'ok',      label: 'Completed', color: 'success', icon: 'mdi-check-circle' },
+  { value: 'error',   label: 'Failed',    color: 'error',   icon: 'mdi-alert-circle' },
+  { value: 'skipped', label: 'Skipped',   color: 'warning', icon: 'mdi-skip-next' },
+]
+
+const _BY_VALUE = Object.fromEntries(DOWNLOAD_STATUSES.map((s) => [s.value, s]))
+
+export function downloadStatusMeta(value) {
+  return _BY_VALUE[value] || { value, label: value, color: 'grey', icon: 'mdi-help-circle' }
+}
+export const downloadStatusLabel = (v) => downloadStatusMeta(v).label
+export const downloadStatusColor = (v) => downloadStatusMeta(v).color
+export const downloadStatusIcon = (v) => downloadStatusMeta(v).icon
diff --git a/frontend/src/utils/toast.js b/frontend/src/utils/toast.js
new file mode 100644
index 0000000..114e017
--- /dev/null
+++ b/frontend/src/utils/toast.js
@@ -0,0 +1,8 @@
+// Centralized toast trigger. App.vue registers the actual snackbar on
+// window.__fcToast; this wraps the optional-chaining lookup so call sites
+// don't repeat `globalThis.window?.__fcToast?.(...)` everywhere.
+//
+// opts: { text: string, type?: 'success' | 'error' | 'info' | 'warning' }
+export function toast(opts) {
+  globalThis.window?.__fcToast?.(opts)
+}

From def967a1a8114bb96ce67f14202bb6eb6961423a Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 11:33:05 -0400
Subject: [PATCH 10/18] refactor(dry-S1): hoist app/client test fixtures into
 conftest

Removed the app/client fixtures duplicated across 36 test files (two
variants: separate app + client(app), and a self-contained client() that
called create_app inline) and the now-unused create_app imports. Both
fixtures now live once in conftest.py. test_suggestions_bulk keeps its
import (builds the app inline in two tests); test_health drops its local
client + unused pytest_asyncio.

Net -415 lines.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 tests/conftest.py                       | 12 ++++++++++++
 tests/test_api_admin.py                 | 12 ------------
 tests/test_api_aliases.py               | 12 ------------
 tests/test_api_allowlist.py             | 12 ------------
 tests/test_api_artist.py                |  8 --------
 tests/test_api_artists_create.py        | 12 ------------
 tests/test_api_artists_directory.py     | 12 ------------
 tests/test_api_attachments.py           | 12 ------------
 tests/test_api_bulk_tags.py             | 12 ------------
 tests/test_api_cleanup.py               | 12 ------------
 tests/test_api_credentials.py           | 12 ------------
 tests/test_api_downloads.py             | 12 ------------
 tests/test_api_extension.py             | 12 ------------
 tests/test_api_extension_api_key.py     | 12 ------------
 tests/test_api_gallery.py               | 12 ------------
 tests/test_api_import_admin.py          | 12 ------------
 tests/test_api_migrate.py               | 12 ------------
 tests/test_api_ml_admin.py              | 12 ------------
 tests/test_api_platforms.py             | 12 ------------
 tests/test_api_posts.py                 | 12 ------------
 tests/test_api_provenance.py            | 12 ------------
 tests/test_api_series.py                | 12 ------------
 tests/test_api_settings.py              | 12 ------------
 tests/test_api_settings_downloader.py   | 12 ------------
 tests/test_api_showcase.py              |  8 --------
 tests/test_api_sources.py               | 12 ------------
 tests/test_api_sources_check.py         | 12 ------------
 tests/test_api_suggestions.py           | 12 ------------
 tests/test_api_system_activity.py       | 12 ------------
 tests/test_api_system_backup.py         | 12 ------------
 tests/test_api_tag_merge.py             | 12 ------------
 tests/test_api_tags.py                  | 12 ------------
 tests/test_api_tags_directory.py        |  8 --------
 tests/test_api_thumbnails.py            | 12 ------------
 tests/test_extension_cors.py            |  8 --------
 tests/test_gallery_artist_payload.py    | 12 ------------
 tests/test_gallery_provenance_filter.py | 12 ------------
 tests/test_health.py                    | 10 ----------
 tests/test_suggestions_bulk.py          |  7 +++----
 39 files changed, 15 insertions(+), 430 deletions(-)

diff --git a/tests/conftest.py b/tests/conftest.py
index 00a8127..0afacb0 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -18,6 +18,7 @@ from sqlalchemy.ext.asyncio import (
 )
 from sqlalchemy.orm import sessionmaker
 
+from backend.app import create_app
 from backend.app.models import Base
 
 
@@ -77,6 +78,17 @@ def db_sync(sync_engine):
             session.rollback()
 
 
+@pytest_asyncio.fixture
+async def app():
+    return create_app()
+
+
+@pytest_asyncio.fixture
+async def client(app):
+    async with app.test_client() as c:
+        yield c
+
+
 # Migration-seeded baseline (singleton config like import_settings /
 # ml_settings), captured lazily at the FIRST integration test's setup —
 # when the CI integration job has just run `alembic upgrade head` so the DB
diff --git a/tests/test_api_admin.py b/tests/test_api_admin.py
index d778007..ec8edfe 100644
--- a/tests/test_api_admin.py
+++ b/tests/test_api_admin.py
@@ -8,24 +8,12 @@ import hashlib
 
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, ImageRecord, Tag, TagKind
 from backend.app.models.tag import image_tag
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 # --- Tier-C: POST /artists/<slug>/cascade-delete --------------------
 
 
diff --git a/tests/test_api_aliases.py b/tests/test_api_aliases.py
index 123f8ef..103b75e 100644
--- a/tests/test_api_aliases.py
+++ b/tests/test_api_aliases.py
@@ -1,23 +1,11 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import TagKind
 from backend.app.services.tag_service import TagService
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_create_list_delete(client, db):
     tag = await TagService(db).find_or_create("Canon", TagKind.character)
diff --git a/tests/test_api_allowlist.py b/tests/test_api_allowlist.py
index 4505b7d..3b4f45b 100644
--- a/tests/test_api_allowlist.py
+++ b/tests/test_api_allowlist.py
@@ -1,23 +1,11 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import TagAllowlist, TagKind
 from backend.app.services.tag_service import TagService
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_list_and_patch_and_delete(client, db):
     tag = await TagService(db).find_or_create("AL", TagKind.character)
diff --git a/tests/test_api_artist.py b/tests/test_api_artist.py
index 0a61d3b..f2b6587 100644
--- a/tests/test_api_artist.py
+++ b/tests/test_api_artist.py
@@ -1,18 +1,10 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def client():
-    app = create_app()
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_artist_404(client):
     resp = await client.get("/api/artist/nope")
diff --git a/tests/test_api_artists_create.py b/tests/test_api_artists_create.py
index ccf1030..64fcb6e 100644
--- a/tests/test_api_artists_create.py
+++ b/tests/test_api_artists_create.py
@@ -1,21 +1,9 @@
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_create_artist_returns_201(client):
     resp = await client.post("/api/artists", json={"name": "Alice"})
diff --git a/tests/test_api_artists_directory.py b/tests/test_api_artists_directory.py
index 37459fc..64b3dda 100644
--- a/tests/test_api_artists_directory.py
+++ b/tests/test_api_artists_directory.py
@@ -2,23 +2,11 @@
 
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, ImageRecord, Source
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.fixture
 async def seeded(db):
     alice = Artist(name="alice-api", slug="alice-api", is_subscription=True)
diff --git a/tests/test_api_attachments.py b/tests/test_api_attachments.py
index 5516438..95e31f2 100644
--- a/tests/test_api_attachments.py
+++ b/tests/test_api_attachments.py
@@ -1,22 +1,10 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, PostAttachment
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_download_streams_with_disposition(client, db, tmp_path):
     blob = tmp_path / "pack.zip"
diff --git a/tests/test_api_bulk_tags.py b/tests/test_api_bulk_tags.py
index 1917734..91e4a17 100644
--- a/tests/test_api_bulk_tags.py
+++ b/tests/test_api_bulk_tags.py
@@ -1,21 +1,9 @@
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _mk_tag(client, name, kind="general"):
     r = await client.post("/api/tags", json={"name": name, "kind": kind})
     return (await r.get_json())["id"]
diff --git a/tests/test_api_cleanup.py b/tests/test_api_cleanup.py
index 35478a4..eaccba5 100644
--- a/tests/test_api_cleanup.py
+++ b/tests/test_api_cleanup.py
@@ -11,7 +11,6 @@ import pytest
 from PIL import Image
 from sqlalchemy import func, select
 
-from backend.app import create_app
 from backend.app.celery_app import celery
 from backend.app.models import ImageRecord, LibraryAuditRun
 
@@ -23,17 +22,6 @@ def disable_celery_eager(monkeypatch):
     monkeypatch.setattr(celery.conf, "task_always_eager", False)
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 def _sha256_min_dim_token(min_w: int, min_h: int) -> str:
     canon = f"{min_w}x{min_h}"
     return f"delete-min-dim-{hashlib.sha256(canon.encode()).hexdigest()[:8]}"
diff --git a/tests/test_api_credentials.py b/tests/test_api_credentials.py
index cd4651b..fa042b4 100644
--- a/tests/test_api_credentials.py
+++ b/tests/test_api_credentials.py
@@ -1,6 +1,5 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import AppSetting
 
 pytestmark = pytest.mark.integration
@@ -12,17 +11,6 @@ _NETSCAPE = (
 )
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.fixture
 async def ext_key(db):
     # Seed an extension API key for tests that want to assert the
diff --git a/tests/test_api_downloads.py b/tests/test_api_downloads.py
index 9d164b8..b20f53b 100644
--- a/tests/test_api_downloads.py
+++ b/tests/test_api_downloads.py
@@ -1,22 +1,10 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, DownloadEvent, Source
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.fixture
 async def seed(db):
     artist = Artist(name="Alice", slug="alice")
diff --git a/tests/test_api_extension.py b/tests/test_api_extension.py
index ca3671f..9f79c0e 100644
--- a/tests/test_api_extension.py
+++ b/tests/test_api_extension.py
@@ -6,7 +6,6 @@ import pytest
 import pytest_asyncio
 from sqlalchemy import func, select
 
-from backend.app import create_app
 from backend.app import frontend as frontend_module
 from backend.app.api import extension as extension_module
 from backend.app.models import AppSetting, Artist, Source
@@ -14,17 +13,6 @@ from backend.app.models import AppSetting, Artist, Source
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest_asyncio.fixture
 async def ext_key(db):
     db.add(AppSetting(key="extension_api_key", value="test-ext-key"))
diff --git a/tests/test_api_extension_api_key.py b/tests/test_api_extension_api_key.py
index 222afc5..7995613 100644
--- a/tests/test_api_extension_api_key.py
+++ b/tests/test_api_extension_api_key.py
@@ -1,23 +1,11 @@
 import pytest
 from sqlalchemy import select
 
-from backend.app import create_app
 from backend.app.models import AppSetting
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_get_seeds_a_value(client, db):
     # First call seeds the row (idempotent on repeat calls).
diff --git a/tests/test_api_gallery.py b/tests/test_api_gallery.py
index 6dadd45..f64066e 100644
--- a/tests/test_api_gallery.py
+++ b/tests/test_api_gallery.py
@@ -2,23 +2,11 @@ from datetime import UTC, datetime, timedelta
 
 import pytest
 
-from backend.app import create_app
 from backend.app.models import ImageRecord
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _seed(db, count: int = 3):
     base = datetime.now(UTC)
     for i in range(count):
diff --git a/tests/test_api_import_admin.py b/tests/test_api_import_admin.py
index f033fd5..0f1a700 100644
--- a/tests/test_api_import_admin.py
+++ b/tests/test_api_import_admin.py
@@ -2,7 +2,6 @@ from datetime import UTC, datetime, timedelta
 
 import pytest
 
-from backend.app import create_app
 from backend.app.celery_app import celery
 from backend.app.models import ImportBatch, ImportTask
 
@@ -16,17 +15,6 @@ def eager():
     celery.conf.task_always_eager = False
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_status_when_idle(client):
     resp = await client.get("/api/import/status")
diff --git a/tests/test_api_migrate.py b/tests/test_api_migrate.py
index be2e782..9febf96 100644
--- a/tests/test_api_migrate.py
+++ b/tests/test_api_migrate.py
@@ -6,7 +6,6 @@ import pytest
 from werkzeug.datastructures import FileStorage
 
 import backend.app.tasks.migration  # noqa: F401 — register celery task
-from backend.app import create_app
 from backend.app.celery_app import celery
 
 pytestmark = pytest.mark.integration
@@ -20,17 +19,6 @@ def _file_storage(payload: dict, filename: str = "export.json") -> FileStorage:
     )
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 # Retired 2026-05-24 (FC-3h): `test_post_backup_returns_202_and_id`
 # asserted the /api/migrate/backup endpoint, which was retired in FC-3h.
 # Backup is now a first-class feature at /api/system/backup/*;
diff --git a/tests/test_api_ml_admin.py b/tests/test_api_ml_admin.py
index cb99630..d026e5e 100644
--- a/tests/test_api_ml_admin.py
+++ b/tests/test_api_ml_admin.py
@@ -1,6 +1,5 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.celery_app import celery
 from backend.app.models import TagKind
 from backend.app.services.tag_service import TagService
@@ -15,17 +14,6 @@ def eager():
     celery.conf.task_always_eager = False
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_get_and_patch_settings(client):
     resp = await client.get("/api/ml/settings")
diff --git a/tests/test_api_platforms.py b/tests/test_api_platforms.py
index 3f6c624..6bf0d82 100644
--- a/tests/test_api_platforms.py
+++ b/tests/test_api_platforms.py
@@ -2,22 +2,10 @@ import re
 
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_platforms_returns_gs_six(client):
     resp = await client.get("/api/platforms")
diff --git a/tests/test_api_posts.py b/tests/test_api_posts.py
index 997bfa7..1aa1ef0 100644
--- a/tests/test_api_posts.py
+++ b/tests/test_api_posts.py
@@ -8,23 +8,11 @@ from datetime import UTC, datetime
 
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, Post, Source
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.fixture
 async def seeded_post(db):
     artist = Artist(name="alice-api", slug="alice-api")
diff --git a/tests/test_api_provenance.py b/tests/test_api_provenance.py
index 328739e..df0a2b7 100644
--- a/tests/test_api_provenance.py
+++ b/tests/test_api_provenance.py
@@ -2,7 +2,6 @@ from datetime import UTC, datetime
 
 import pytest
 
-from backend.app import create_app
 from backend.app.models import (
     Artist,
     ImageProvenance,
@@ -14,17 +13,6 @@ from backend.app.models import (
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _seed_full(db):
     rec = ImageRecord(
         path="/images/p/1.jpg", sha256="p" + "0" * 63,
diff --git a/tests/test_api_series.py b/tests/test_api_series.py
index 5f70f6b..5a7e020 100644
--- a/tests/test_api_series.py
+++ b/tests/test_api_series.py
@@ -1,21 +1,9 @@
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _series(client, name="Vol"):
     r = await client.post("/api/tags", json={"name": name, "kind": "series"})
     return (await r.get_json())["id"]
diff --git a/tests/test_api_settings.py b/tests/test_api_settings.py
index a406f4c..3fb9aa2 100644
--- a/tests/test_api_settings.py
+++ b/tests/test_api_settings.py
@@ -1,21 +1,9 @@
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_get_import_settings_defaults(client):
     resp = await client.get("/api/settings/import")
diff --git a/tests/test_api_settings_downloader.py b/tests/test_api_settings_downloader.py
index 814dec8..6556d76 100644
--- a/tests/test_api_settings_downloader.py
+++ b/tests/test_api_settings_downloader.py
@@ -1,21 +1,9 @@
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_get_includes_downloader_fields(client):
     resp = await client.get("/api/settings/import")
diff --git a/tests/test_api_showcase.py b/tests/test_api_showcase.py
index d61e793..b6d512b 100644
--- a/tests/test_api_showcase.py
+++ b/tests/test_api_showcase.py
@@ -1,18 +1,10 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import ImageRecord
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def client():
-    app = create_app()
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_showcase_returns_images(client, db):
     for i in range(8):
diff --git a/tests/test_api_sources.py b/tests/test_api_sources.py
index da8b05c..c48ed65 100644
--- a/tests/test_api_sources.py
+++ b/tests/test_api_sources.py
@@ -1,22 +1,10 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, Source
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.fixture
 async def artist(db):
     a = Artist(name="Alice", slug="alice")
diff --git a/tests/test_api_sources_check.py b/tests/test_api_sources_check.py
index c532738..8b2cfa6 100644
--- a/tests/test_api_sources_check.py
+++ b/tests/test_api_sources_check.py
@@ -1,22 +1,10 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, DownloadEvent, Source
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.fixture
 async def seed(db):
     artist = Artist(name="Alice", slug="alice")
diff --git a/tests/test_api_suggestions.py b/tests/test_api_suggestions.py
index 50c7704..f8bd49c 100644
--- a/tests/test_api_suggestions.py
+++ b/tests/test_api_suggestions.py
@@ -1,6 +1,5 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.celery_app import celery
 from backend.app.models import ImageRecord, TagKind
 from backend.app.services.tag_service import TagService
@@ -15,17 +14,6 @@ def eager():
     celery.conf.task_always_eager = False
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _img(db, preds):
     img = ImageRecord(
         path="/images/s.jpg", sha256="s" * 64, size_bytes=1,
diff --git a/tests/test_api_system_activity.py b/tests/test_api_system_activity.py
index bc16c52..0a493ab 100644
--- a/tests/test_api_system_activity.py
+++ b/tests/test_api_system_activity.py
@@ -10,24 +10,12 @@ from datetime import UTC, datetime, timedelta
 import pytest
 import pytest_asyncio
 
-from backend.app import create_app
 from backend.app.api import system_activity as activity_module
 from backend.app.models import TaskRun
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.fixture(autouse=True)
 def _reset_caches(monkeypatch):
     """Clear the module-level caches between tests so cache state from
diff --git a/tests/test_api_system_backup.py b/tests/test_api_system_backup.py
index 7ee81a7..0759011 100644
--- a/tests/test_api_system_backup.py
+++ b/tests/test_api_system_backup.py
@@ -5,23 +5,11 @@ import pytest
 import pytest_asyncio
 from sqlalchemy import select
 
-from backend.app import create_app
 from backend.app.models import BackupRun
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest_asyncio.fixture
 async def _seed_runs(db):
     """Insert 4 BackupRun rows for paging/filter tests."""
diff --git a/tests/test_api_tag_merge.py b/tests/test_api_tag_merge.py
index 8b8dd15..656e319 100644
--- a/tests/test_api_tag_merge.py
+++ b/tests/test_api_tag_merge.py
@@ -1,21 +1,9 @@
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _mk(client, name, kind):
     r = await client.post("/api/tags", json={"name": name, "kind": kind})
     return (await r.get_json())["id"]
diff --git a/tests/test_api_tags.py b/tests/test_api_tags.py
index 3322556..bce749b 100644
--- a/tests/test_api_tags.py
+++ b/tests/test_api_tags.py
@@ -1,21 +1,9 @@
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_autocomplete_empty(client):
     resp = await client.get("/api/tags/autocomplete?q=")
diff --git a/tests/test_api_tags_directory.py b/tests/test_api_tags_directory.py
index 1865482..7089abc 100644
--- a/tests/test_api_tags_directory.py
+++ b/tests/test_api_tags_directory.py
@@ -1,18 +1,10 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Tag, TagKind
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def client():
-    app = create_app()
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_directory_endpoint(client, db):
     db.add(Tag(name="api_tag", kind=TagKind.general))
diff --git a/tests/test_api_thumbnails.py b/tests/test_api_thumbnails.py
index b9d07a4..9a9c729 100644
--- a/tests/test_api_thumbnails.py
+++ b/tests/test_api_thumbnails.py
@@ -1,6 +1,5 @@
 import pytest
 
-from backend.app import create_app
 from backend.app.celery_app import celery
 
 pytestmark = pytest.mark.integration
@@ -13,17 +12,6 @@ def eager():
     celery.conf.task_always_eager = False
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_trigger_thumbnail_backfill(client):
     r = await client.post("/api/thumbnails/backfill")
diff --git a/tests/test_extension_cors.py b/tests/test_extension_cors.py
index da5c336..9729793 100644
--- a/tests/test_extension_cors.py
+++ b/tests/test_extension_cors.py
@@ -13,18 +13,10 @@ requests (no Origin header, or a regular https:// Origin) get nothing
 
 import pytest
 
-from backend.app import create_app
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def client():
-    app = create_app()
-    async with app.test_client() as c:
-        yield c
-
-
 @pytest.mark.asyncio
 async def test_extension_preflight_returns_204_with_acl_headers(client):
     resp = await client.options(
diff --git a/tests/test_gallery_artist_payload.py b/tests/test_gallery_artist_payload.py
index c3c3bbe..46c7099 100644
--- a/tests/test_gallery_artist_payload.py
+++ b/tests/test_gallery_artist_payload.py
@@ -2,23 +2,11 @@ from datetime import UTC, datetime, timedelta
 
 import pytest
 
-from backend.app import create_app
 from backend.app.models import Artist, ImageRecord, Source
 
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _img(db, n):
     rec = ImageRecord(
         path=f"/images/ap/{n}.jpg", sha256=f"ap{n:062d}",
diff --git a/tests/test_gallery_provenance_filter.py b/tests/test_gallery_provenance_filter.py
index 2eb93aa..e2fc95b 100644
--- a/tests/test_gallery_provenance_filter.py
+++ b/tests/test_gallery_provenance_filter.py
@@ -2,7 +2,6 @@ from datetime import UTC, datetime, timedelta
 
 import pytest
 
-from backend.app import create_app
 from backend.app.models import (
     Artist,
     ImageProvenance,
@@ -15,17 +14,6 @@ from backend.app.services.gallery_service import GalleryService
 pytestmark = pytest.mark.integration
 
 
-@pytest.fixture
-async def app():
-    return create_app()
-
-
-@pytest.fixture
-async def client(app):
-    async with app.test_client() as c:
-        yield c
-
-
 async def _img(db, n):
     base = datetime.now(UTC)
     rec = ImageRecord(
diff --git a/tests/test_health.py b/tests/test_health.py
index b8f9b2a..2a2069d 100644
--- a/tests/test_health.py
+++ b/tests/test_health.py
@@ -1,16 +1,6 @@
 """Health endpoint smoke test."""
 
 import pytest
-import pytest_asyncio
-
-from backend.app import create_app
-
-
-@pytest_asyncio.fixture
-async def client():
-    app = create_app()
-    async with app.test_client() as c:
-        yield c
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_suggestions_bulk.py b/tests/test_suggestions_bulk.py
index 2b00649..f3e0a78 100644
--- a/tests/test_suggestions_bulk.py
+++ b/tests/test_suggestions_bulk.py
@@ -1,5 +1,6 @@
 import pytest
 
+from backend.app import create_app
 from backend.app.models import ImageRecord, TagKind
 from backend.app.models.tag import image_tag
 from backend.app.services.ml.suggestions import SuggestionService
@@ -86,8 +87,7 @@ async def test_consensus_threshold_clamped_and_empty_for_no_ids(db):
 
 @pytest.mark.asyncio
 async def test_bulk_suggestions_route(db):
-    from backend.app import create_app
-
+    
     tags = TagService(db)
     await tags.find_or_create("sword", TagKind.general)
     a = _img("i" * 64, {"sword": {"category": "general", "confidence": 0.97}})
@@ -107,8 +107,7 @@ async def test_bulk_suggestions_route(db):
 
 @pytest.mark.asyncio
 async def test_bulk_suggestions_requires_ids(db):
-    from backend.app import create_app
-
+    
     app = create_app()
     async with app.test_client() as c:
         resp = await c.post("/api/suggestions/bulk", json={})

From cabd73287a75982c6862af623c1e7beaf780096c Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 12:43:08 -0400
Subject: [PATCH 11/18] =?UTF-8?q?fix(lint):=20S1=20ruff=20fallout=20?=
 =?UTF-8?q?=E2=80=94=20collapse=20double=20blank=20after=20import=20block?=
 =?UTF-8?q?=20(I001)=20+=20strip=20W293=20in=20test=5Fsuggestions=5Fbulk?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removing the create_app import left 2 blank lines before pytestmark in 9
files where ruff isort wants 1. Also stripped two pre-existing
whitespace-only blank lines surfaced by the file change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 tests/test_api_artists_create.py      | 1 -
 tests/test_api_bulk_tags.py           | 1 -
 tests/test_api_platforms.py           | 1 -
 tests/test_api_series.py              | 1 -
 tests/test_api_settings.py            | 1 -
 tests/test_api_settings_downloader.py | 1 -
 tests/test_api_tag_merge.py           | 1 -
 tests/test_api_tags.py                | 1 -
 tests/test_extension_cors.py          | 1 -
 tests/test_suggestions_bulk.py        | 4 ++--
 10 files changed, 2 insertions(+), 11 deletions(-)

diff --git a/tests/test_api_artists_create.py b/tests/test_api_artists_create.py
index 64fcb6e..5e44b16 100644
--- a/tests/test_api_artists_create.py
+++ b/tests/test_api_artists_create.py
@@ -1,6 +1,5 @@
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_api_bulk_tags.py b/tests/test_api_bulk_tags.py
index 91e4a17..5c3c6c7 100644
--- a/tests/test_api_bulk_tags.py
+++ b/tests/test_api_bulk_tags.py
@@ -1,6 +1,5 @@
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_api_platforms.py b/tests/test_api_platforms.py
index 6bf0d82..1c76b90 100644
--- a/tests/test_api_platforms.py
+++ b/tests/test_api_platforms.py
@@ -2,7 +2,6 @@ import re
 
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_api_series.py b/tests/test_api_series.py
index 5a7e020..0ac39fa 100644
--- a/tests/test_api_series.py
+++ b/tests/test_api_series.py
@@ -1,6 +1,5 @@
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_api_settings.py b/tests/test_api_settings.py
index 3fb9aa2..8067c19 100644
--- a/tests/test_api_settings.py
+++ b/tests/test_api_settings.py
@@ -1,6 +1,5 @@
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_api_settings_downloader.py b/tests/test_api_settings_downloader.py
index 6556d76..4a1235c 100644
--- a/tests/test_api_settings_downloader.py
+++ b/tests/test_api_settings_downloader.py
@@ -1,6 +1,5 @@
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_api_tag_merge.py b/tests/test_api_tag_merge.py
index 656e319..b731e6b 100644
--- a/tests/test_api_tag_merge.py
+++ b/tests/test_api_tag_merge.py
@@ -1,6 +1,5 @@
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_api_tags.py b/tests/test_api_tags.py
index bce749b..c4ead6e 100644
--- a/tests/test_api_tags.py
+++ b/tests/test_api_tags.py
@@ -1,6 +1,5 @@
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_extension_cors.py b/tests/test_extension_cors.py
index 9729793..ec61be3 100644
--- a/tests/test_extension_cors.py
+++ b/tests/test_extension_cors.py
@@ -13,7 +13,6 @@ requests (no Origin header, or a regular https:// Origin) get nothing
 
 import pytest
 
-
 pytestmark = pytest.mark.integration
 
 
diff --git a/tests/test_suggestions_bulk.py b/tests/test_suggestions_bulk.py
index f3e0a78..1bfe40d 100644
--- a/tests/test_suggestions_bulk.py
+++ b/tests/test_suggestions_bulk.py
@@ -87,7 +87,7 @@ async def test_consensus_threshold_clamped_and_empty_for_no_ids(db):
 
 @pytest.mark.asyncio
 async def test_bulk_suggestions_route(db):
-    
+
     tags = TagService(db)
     await tags.find_or_create("sword", TagKind.general)
     a = _img("i" * 64, {"sword": {"category": "general", "confidence": 0.97}})
@@ -107,7 +107,7 @@ async def test_bulk_suggestions_route(db):
 
 @pytest.mark.asyncio
 async def test_bulk_suggestions_requires_ids(db):
-    
+
     app = create_app()
     async with app.test_client() as c:
         resp = await c.post("/api/suggestions/bulk", json={})

From a37dad33c7740b9eb444eb9525d574d65916cf39 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 12:53:57 -0400
Subject: [PATCH 12/18] refactor(dry-F1): shared useAsyncAction lifecycle
 helper for stores

New composables/useAsyncAction.js owns the loading/error/try-finally
lifecycle. Migrated 11 stores: credentials, downloads, sources, posts
(error=raw) + ml, artistDirectory, tagDirectory, showcase, suggestions,
seriesReader, modal (error=message). The errorAs option preserves each
store's existing error shape so store.error keeps the same type for
components (~50 consumption sites unchanged). Stores whose catch also
reset data (suggestions/seriesReader/modal) clear it upfront instead.

Deliberately NOT migrated (special control flow, would change behavior):
artist (conditional 404 catch + dual loading states), migration (rethrows),
gallery (inflight-id stale-response guard), and the Shape-B no-catch /
loaded-guard / keyed-cache stores.

Net -77 lines.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend/src/composables/useAsyncAction.js | 28 ++++++++++++++++++++++
 frontend/src/stores/artistDirectory.js     | 14 ++++-------
 frontend/src/stores/credentials.js         | 14 ++++-------
 frontend/src/stores/downloads.js           | 23 +++++-------------
 frontend/src/stores/ml.js                  | 14 ++++-------
 frontend/src/stores/modal.js               | 16 ++++---------
 frontend/src/stores/posts.js               | 14 ++++-------
 frontend/src/stores/seriesReader.js        | 18 +++++---------
 frontend/src/stores/showcase.js            | 14 ++++-------
 frontend/src/stores/sources.js             | 24 +++++--------------
 frontend/src/stores/suggestions.js         | 16 ++++---------
 frontend/src/stores/tagDirectory.js        | 14 ++++-------
 12 files changed, 80 insertions(+), 129 deletions(-)
 create mode 100644 frontend/src/composables/useAsyncAction.js

diff --git a/frontend/src/composables/useAsyncAction.js b/frontend/src/composables/useAsyncAction.js
new file mode 100644
index 0000000..a391625
--- /dev/null
+++ b/frontend/src/composables/useAsyncAction.js
@@ -0,0 +1,28 @@
+import { ref } from 'vue'
+
+// Owns the loading/error lifecycle shared by most Pinia stores. `run`
+// flips loading on, clears error, runs `fn`, captures any throw into error
+// (swallowed so callers can read `store.error`), and always resets loading.
+// Returns fn's resolved value on success, or undefined if it threw.
+//
+// `errorAs` matches each store's existing convention so migrations don't
+// change what `store.error` holds: 'raw' keeps the thrown object (the
+// ApiError, with .status/.body), 'message' keeps just the string.
+export function useAsyncAction({ errorAs = 'raw' } = {}) {
+  const loading = ref(false)
+  const error = ref(null)
+
+  async function run(fn) {
+    loading.value = true
+    error.value = null
+    try {
+      return await fn()
+    } catch (e) {
+      error.value = errorAs === 'message' ? (e?.message ?? String(e)) : e
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { loading, error, run }
+}
diff --git a/frontend/src/stores/artistDirectory.js b/frontend/src/stores/artistDirectory.js
index 7550c36..111ff9f 100644
--- a/frontend/src/stores/artistDirectory.js
+++ b/frontend/src/stores/artistDirectory.js
@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 const PAGE = 60
 
@@ -8,8 +9,7 @@ export const useArtistDirectoryStore = defineStore('artistDirectory', () => {
   const api = useApi()
   const cards = ref([])
   const nextCursor = ref(null)
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction({ errorAs: 'message' })
   const q = ref('')
   const platform = ref(null)
   let started = false
@@ -17,9 +17,7 @@ export const useArtistDirectoryStore = defineStore('artistDirectory', () => {
   async function loadMore() {
     if (loading.value) return
     if (started && nextCursor.value === null) return
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const params = { limit: PAGE }
       if (q.value) params.q = q.value
       if (platform.value) params.platform = platform.value
@@ -28,11 +26,7 @@ export const useArtistDirectoryStore = defineStore('artistDirectory', () => {
       cards.value.push(...body.cards)
       nextCursor.value = body.next_cursor
       started = true
-    } catch (e) {
-      error.value = e.message
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function reset() {
diff --git a/frontend/src/stores/credentials.js b/frontend/src/stores/credentials.js
index 8fbf4ae..c3558e3 100644
--- a/frontend/src/stores/credentials.js
+++ b/frontend/src/stores/credentials.js
@@ -1,28 +1,22 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 export const useCredentialsStore = defineStore('credentials', () => {
   const api = useApi()
 
   const byPlatform = ref(new Map())
   const extensionKey = ref(null)
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction()
 
   async function loadAll() {
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const arr = await api.get('/api/credentials')
       const m = new Map()
       for (const c of arr) m.set(c.platform, c)
       byPlatform.value = m
-    } catch (e) {
-      error.value = e
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function upload(platform, credential_type, data) {
diff --git a/frontend/src/stores/downloads.js b/frontend/src/stores/downloads.js
index cc72e7b..564cb68 100644
--- a/frontend/src/stores/downloads.js
+++ b/frontend/src/stores/downloads.js
@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 export const useDownloadsStore = defineStore('downloads', () => {
   const api = useApi()
@@ -13,8 +14,7 @@ export const useDownloadsStore = defineStore('downloads', () => {
     from_date: null, to_date: null,
   })
   const selected = ref(null)
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction()
   const stats = ref({ pending: 0, running: 0, ok: 0, error: 0, skipped: 0 })
   const activity = ref({ hours: 24, buckets: [] })
   const failing = ref([])
@@ -28,33 +28,22 @@ export const useDownloadsStore = defineStore('downloads', () => {
   }
 
   async function loadFirst() {
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const body = await api.get('/api/downloads', { params: _params() })
       events.value = body
       cursor.value = body.length ? body[body.length - 1].id : null
       hasMore.value = body.length === 50
-    } catch (e) {
-      error.value = e
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function loadMore() {
     if (!hasMore.value || cursor.value == null) return
-    loading.value = true
-    try {
+    await run(async () => {
       const body = await api.get('/api/downloads', { params: _params({ before: cursor.value }) })
       events.value.push(...body)
       cursor.value = body.length ? body[body.length - 1].id : cursor.value
       hasMore.value = body.length === 50
-    } catch (e) {
-      error.value = e
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function loadOne(id) {
diff --git a/frontend/src/stores/ml.js b/frontend/src/stores/ml.js
index 1323268..5c55982 100644
--- a/frontend/src/stores/ml.js
+++ b/frontend/src/stores/ml.js
@@ -1,23 +1,17 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 export const useMLStore = defineStore('ml', () => {
   const api = useApi()
   const settings = ref(null)
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction({ errorAs: 'message' })
 
   async function loadSettings() {
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       settings.value = await api.get('/api/ml/settings')
-    } catch (e) {
-      error.value = e.message
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function patchSettings(patch) {
diff --git a/frontend/src/stores/modal.js b/frontend/src/stores/modal.js
index 2efbe42..83f60be 100644
--- a/frontend/src/stores/modal.js
+++ b/frontend/src/stores/modal.js
@@ -2,14 +2,14 @@ import { defineStore } from 'pinia'
 import { toast } from '../utils/toast.js'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 export const useModalStore = defineStore('modal', () => {
   const api = useApi()
 
   const currentImageId = ref(null)
   const current = ref(null)
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction({ errorAs: 'message' })
 
   // Post-scoped cycle. When set, prev/next cycles within this array
   // (used by PostCard's expanded-mosaic PostImageGrid clicks). When
@@ -20,8 +20,7 @@ export const useModalStore = defineStore('modal', () => {
 
   async function open (id, opts = {}) {
     currentImageId.value = id
-    loading.value = true
-    error.value = null
+    current.value = null  // cleared upfront so it stays null on error
     // Update post-scoped state if caller passed it; otherwise clear so
     // the next open() from gallery context uses neighbors mode.
     if (opts.postImageIds != null) {
@@ -32,14 +31,9 @@ export const useModalStore = defineStore('modal', () => {
       postImageIds.value = null
       postImageIndex.value = 0
     }
-    try {
+    await run(async () => {
       current.value = await api.get(`/api/gallery/image/${id}`)
-    } catch (e) {
-      error.value = e.message
-      current.value = null
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function close () {
diff --git a/frontend/src/stores/posts.js b/frontend/src/stores/posts.js
index d5b18c7..926bb63 100644
--- a/frontend/src/stores/posts.js
+++ b/frontend/src/stores/posts.js
@@ -1,15 +1,15 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 export const usePostsStore = defineStore('posts', () => {
   const api = useApi()
 
   const items = ref([])
   const cursor = ref(null)
-  const loading = ref(false)
+  const { loading, error, run } = useAsyncAction()
   const done = ref(false)
-  const error = ref(null)
   const filters = ref({ artist_id: null, platform: null })
 
   function _qs() {
@@ -38,18 +38,12 @@ export const usePostsStore = defineStore('posts', () => {
 
   async function loadMore() {
     if (loading.value || done.value) return
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const body = await api.get('/api/posts', { params: _qs() })
       items.value.push(...body.items)
       cursor.value = body.next_cursor
       if (body.next_cursor == null) done.value = true
-    } catch (e) {
-      error.value = e
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function getPostFull(id) {
diff --git a/frontend/src/stores/seriesReader.js b/frontend/src/stores/seriesReader.js
index f79b8d6..beac66d 100644
--- a/frontend/src/stores/seriesReader.js
+++ b/frontend/src/stores/seriesReader.js
@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 // IR reader.js "viewport-center-in-third" rule, pure for unit tests.
 // metrics: [{page_number, top, height}] in page order.
@@ -33,23 +34,16 @@ export const useSeriesReaderStore = defineStore('seriesReader', () => {
 
   const series = ref(null)
   const pages = ref([])
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction({ errorAs: 'message' })
 
   async function load(tagId) {
-    loading.value = true
-    error.value = null
-    try {
+    series.value = null  // cleared upfront so they stay reset on error
+    pages.value = []
+    await run(async () => {
       const body = await api.get(`/api/series/${tagId}/pages`)
       series.value = body.series
       pages.value = body.pages
-    } catch (e) {
-      error.value = e.message
-      series.value = null
-      pages.value = []
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   return { series, pages, loading, error, load }
diff --git a/frontend/src/stores/showcase.js b/frontend/src/stores/showcase.js
index 7e72488..2b93d3d 100644
--- a/frontend/src/stores/showcase.js
+++ b/frontend/src/stores/showcase.js
@@ -1,32 +1,26 @@
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 const PAGE = 60
 
 export const useShowcaseStore = defineStore('showcase', () => {
   const api = useApi()
   const images = ref([])
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction({ errorAs: 'message' })
   const exhausted = ref(false)
   const seen = new Set()
 
   async function fetchPage() {
     if (loading.value) return
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const body = await api.get('/api/showcase', { params: { limit: PAGE } })
       const fresh = body.images.filter(i => !seen.has(i.id))
       if (fresh.length === 0) { exhausted.value = true; return }
       for (const i of fresh) seen.add(i.id)
       images.value.push(...fresh)
-    } catch (e) {
-      error.value = e.message
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function shuffle() {
diff --git a/frontend/src/stores/sources.js b/frontend/src/stores/sources.js
index d3955b1..77ece67 100644
--- a/frontend/src/stores/sources.js
+++ b/frontend/src/stores/sources.js
@@ -1,42 +1,30 @@
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 export const useSourcesStore = defineStore('sources', () => {
   const api = useApi()
 
   // keyed cache: null => all sources, number => artist_id filtered
   const byArtist = ref(new Map())
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction()
   const scheduleStatus = ref(null)
 
   const allSources = computed(() => byArtist.value.get(null) ?? [])
 
   async function loadAll() {
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const body = await api.get('/api/sources')
       byArtist.value.set(null, body)
-    } catch (e) {
-      error.value = e
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function loadForArtist(artistId) {
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const body = await api.get('/api/sources', { params: { artist_id: artistId } })
       byArtist.value.set(artistId, body)
-    } catch (e) {
-      error.value = e
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   function _invalidate(artistId) {
diff --git a/frontend/src/stores/suggestions.js b/frontend/src/stores/suggestions.js
index 0e4447c..124bee3 100644
--- a/frontend/src/stores/suggestions.js
+++ b/frontend/src/stores/suggestions.js
@@ -2,6 +2,7 @@ import { defineStore } from 'pinia'
 import { toast } from '../utils/toast.js'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 // Category display order: people/sources first, general last.
 export const CATEGORY_ORDER = ['artist', 'character', 'copyright', 'general']
@@ -15,23 +16,16 @@ export const CATEGORY_LABELS = {
 export const useSuggestionsStore = defineStore('suggestions', () => {
   const api = useApi()
   const byCategory = ref({})       // { category: [suggestion, ...] }
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction({ errorAs: 'message' })
   let currentImageId = null
 
   async function load(imageId) {
     currentImageId = imageId
-    loading.value = true
-    error.value = null
-    try {
+    byCategory.value = {}  // cleared upfront so it stays empty on error
+    await run(async () => {
       const body = await api.get(`/api/images/${imageId}/suggestions`)
       byCategory.value = body.by_category || {}
-    } catch (e) {
-      error.value = e.message
-      byCategory.value = {}
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   function _drop(category, predicate) {
diff --git a/frontend/src/stores/tagDirectory.js b/frontend/src/stores/tagDirectory.js
index 4528a17..fc1b838 100644
--- a/frontend/src/stores/tagDirectory.js
+++ b/frontend/src/stores/tagDirectory.js
@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
 import { useApi } from '../composables/useApi.js'
+import { useAsyncAction } from '../composables/useAsyncAction.js'
 
 const PAGE = 60
 
@@ -8,8 +9,7 @@ export const useTagDirectoryStore = defineStore('tagDirectory', () => {
   const api = useApi()
   const cards = ref([])
   const nextCursor = ref(null)
-  const loading = ref(false)
-  const error = ref(null)
+  const { loading, error, run } = useAsyncAction({ errorAs: 'message' })
   const kind = ref(null)
   const q = ref('')
   let started = false
@@ -17,9 +17,7 @@ export const useTagDirectoryStore = defineStore('tagDirectory', () => {
   async function loadMore() {
     if (loading.value) return
     if (started && nextCursor.value === null) return
-    loading.value = true
-    error.value = null
-    try {
+    await run(async () => {
       const params = { limit: PAGE }
       if (kind.value) params.kind = kind.value
       if (q.value) params.q = q.value
@@ -28,11 +26,7 @@ export const useTagDirectoryStore = defineStore('tagDirectory', () => {
       cards.value.push(...body.cards)
       nextCursor.value = body.next_cursor
       started = true
-    } catch (e) {
-      error.value = e.message
-    } finally {
-      loading.value = false
-    }
+    })
   }
 
   async function reset() {

From 597c6d48d3458132a99943894f9d8d7e493381cc Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 13:10:04 -0400
Subject: [PATCH 13/18] refactor(dry-B1): consolidate duplicated _bad error
 helper into api/_responses.py

8 blueprints each defined an identical _bad() (two variants: with/without
detail). Extracted error_response() into api/_responses.py; each blueprint
now imports it `as _bad` so call sites are unchanged. The detail-aware
canonical subsumes both variants. Left settings.py's distinct _bad_int and
the inline jsonify error sites (not duplicated helpers).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 backend/app/api/_responses.py    | 16 ++++++++++++++++
 backend/app/api/admin.py         |  7 +------
 backend/app/api/cleanup.py       |  7 +------
 backend/app/api/credentials.py   |  9 +--------
 backend/app/api/extension.py     |  7 +------
 backend/app/api/migrate.py       |  7 +------
 backend/app/api/posts.py         |  9 +--------
 backend/app/api/sources.py       |  9 +--------
 backend/app/api/system_backup.py |  7 +------
 9 files changed, 24 insertions(+), 54 deletions(-)
 create mode 100644 backend/app/api/_responses.py

diff --git a/backend/app/api/_responses.py b/backend/app/api/_responses.py
new file mode 100644
index 0000000..e935321
--- /dev/null
+++ b/backend/app/api/_responses.py
@@ -0,0 +1,16 @@
+"""Shared API response helpers."""
+
+from quart import jsonify
+
+
+def error_response(
+    error: str, *, status: int = 400, detail: str | None = None, **extra,
+):
+    """JSON error body + HTTP status. `detail` is included only when given;
+    `extra` keys are merged into the body. Returns the (response, status)
+    tuple Quart expects. Imported as `_bad` by the blueprints."""
+    body = {"error": error}
+    if detail is not None:
+        body["detail"] = detail
+    body.update(extra)
+    return jsonify(body), status
diff --git a/backend/app/api/admin.py b/backend/app/api/admin.py
index 29820e8..b82aacf 100644
--- a/backend/app/api/admin.py
+++ b/backend/app/api/admin.py
@@ -24,16 +24,11 @@ from sqlalchemy import select
 from ..extensions import get_session
 from ..models import Artist
 from ..services.cleanup_service import project_artist_cascade, project_bulk_image_delete
+from ._responses import error_response as _bad
 
 admin_bp = Blueprint("admin", __name__, url_prefix="/api/admin")
 
 
-def _bad(error: str, *, status: int = 400, **extra):
-    body = {"error": error}
-    body.update(extra)
-    return jsonify(body), status
-
-
 def _bulk_image_confirm_token(image_ids: list[int]) -> str:
     """Stable 8-hex token derived from the sorted id list. Mutates
     when the selection changes; stays the same across modal opens of
diff --git a/backend/app/api/cleanup.py b/backend/app/api/cleanup.py
index 7149525..24853fe 100644
--- a/backend/app/api/cleanup.py
+++ b/backend/app/api/cleanup.py
@@ -31,18 +31,13 @@ from sqlalchemy import select
 from ..extensions import get_session
 from ..models import LibraryAuditRun
 from ..services import cleanup_service
+from ._responses import error_response as _bad
 
 cleanup_bp = Blueprint("cleanup", __name__, url_prefix="/api/cleanup")
 
 IMAGES_ROOT = Path("/images")
 
 
-def _bad(error: str, *, status: int = 400, **extra):
-    body = {"error": error}
-    body.update(extra)
-    return jsonify(body), status
-
-
 def _min_dim_token(min_w: int, min_h: int) -> str:
     # SHA-256 (not MD5) — Web Crypto's subtle.digest rejects MD5; both
     # sides use SHA-256 truncated to 8 hex chars.
diff --git a/backend/app/api/credentials.py b/backend/app/api/credentials.py
index 395846a..f719b51 100644
--- a/backend/app/api/credentials.py
+++ b/backend/app/api/credentials.py
@@ -20,6 +20,7 @@ from ..services.credential_service import (
     UnknownPlatformError,
     WrongAuthTypeError,
 )
+from ._responses import error_response as _bad
 
 credentials_bp = Blueprint("credentials", __name__, url_prefix="/api/credentials")
 
@@ -38,14 +39,6 @@ def _get_crypto() -> CredentialCrypto:
     return _crypto
 
 
-def _bad(error: str, *, status: int = 400, detail: str | None = None, **extra):
-    body = {"error": error}
-    if detail is not None:
-        body["detail"] = detail
-    body.update(extra)
-    return jsonify(body), status
-
-
 async def _ext_key_ok(session) -> bool:
     """If X-Extension-Key is supplied, it must match the stored value.
     Missing header → True (browser path; accepted per homelab posture).
diff --git a/backend/app/api/extension.py b/backend/app/api/extension.py
index 4f4766f..5266d46 100644
--- a/backend/app/api/extension.py
+++ b/backend/app/api/extension.py
@@ -20,6 +20,7 @@ from ..services.extension_service import (
     UnknownPlatformError,
 )
 from ..services.source_service import KNOWN_PLATFORMS
+from ._responses import error_response as _bad
 
 extension_bp = Blueprint("extension", __name__, url_prefix="/api/extension")
 
@@ -30,12 +31,6 @@ XPI_DIR = Path("/app/frontend/dist/extension")
 _XPI_VERSION_RE = re.compile(r"fabledcurator-(?P<version>[\w.-]+)\.xpi$")
 
 
-def _bad(error: str, *, status: int = 400, **extra):
-    body = {"error": error}
-    body.update(extra)
-    return jsonify(body), status
-
-
 async def _ext_key_required(session) -> bool:
     """Unlike /api/credentials (which accepts the browser path with no
     header), quick-add-source writes server state and must be explicitly
diff --git a/backend/app/api/migrate.py b/backend/app/api/migrate.py
index 8a67fc6..d48e9f4 100644
--- a/backend/app/api/migrate.py
+++ b/backend/app/api/migrate.py
@@ -13,6 +13,7 @@ from sqlalchemy import select
 from ..extensions import get_session
 from ..models import MigrationRun
 from ..tasks.migration import run_migration
+from ._responses import error_response as _bad
 
 migrate_bp = Blueprint("migrate", __name__, url_prefix="/api/migrate")
 
@@ -24,12 +25,6 @@ _VALID_KINDS = frozenset({
 _INGEST_KINDS = frozenset({"gs_ingest", "ir_ingest"})
 
 
-def _bad(error: str, *, status: int = 400, **extra):
-    body = {"error": error}
-    body.update(extra)
-    return jsonify(body), status
-
-
 def _run_to_dict(run: MigrationRun) -> dict:
     return {
         "id": run.id,
diff --git a/backend/app/api/posts.py b/backend/app/api/posts.py
index 1f9dd3e..d96e523 100644
--- a/backend/app/api/posts.py
+++ b/backend/app/api/posts.py
@@ -5,18 +5,11 @@ from quart import Blueprint, jsonify, request
 from ..extensions import get_session
 from ..services.post_feed_service import PostFeedService
 from ..services.source_service import KNOWN_PLATFORMS
+from ._responses import error_response as _bad
 
 posts_bp = Blueprint("posts", __name__, url_prefix="/api/posts")
 
 
-def _bad(error: str, *, status: int = 400, detail: str | None = None, **extra):
-    body = {"error": error}
-    if detail is not None:
-        body["detail"] = detail
-    body.update(extra)
-    return jsonify(body), status
-
-
 @posts_bp.route("", methods=["GET"])
 async def list_posts():
     args = request.args
diff --git a/backend/app/api/sources.py b/backend/app/api/sources.py
index 71d5d9d..9d7c9b1 100644
--- a/backend/app/api/sources.py
+++ b/backend/app/api/sources.py
@@ -15,18 +15,11 @@ from ..services.source_service import (
     SourceService,
     UnknownPlatformError,
 )
+from ._responses import error_response as _bad
 
 sources_bp = Blueprint("sources", __name__, url_prefix="/api/sources")
 
 
-def _bad(error: str, *, status: int = 400, detail: str | None = None, **extra):
-    body = {"error": error}
-    if detail is not None:
-        body["detail"] = detail
-    body.update(extra)
-    return jsonify(body), status
-
-
 @sources_bp.route("", methods=["GET"])
 async def list_sources():
     artist_id_raw = request.args.get("artist_id")
diff --git a/backend/app/api/system_backup.py b/backend/app/api/system_backup.py
index 24fa94e..fcf57c7 100644
--- a/backend/app/api/system_backup.py
+++ b/backend/app/api/system_backup.py
@@ -14,6 +14,7 @@ from sqlalchemy import desc, select
 
 from ..extensions import get_session
 from ..models import BackupRun, ImportSettings
+from ._responses import error_response as _bad
 
 system_backup_bp = Blueprint(
     "system_backup", __name__, url_prefix="/api/system/backup",
@@ -29,12 +30,6 @@ _BACKUP_SETTINGS_FIELDS = (
 )
 
 
-def _bad(error: str, *, status: int = 400, **extra):
-    body = {"error": error}
-    body.update(extra)
-    return jsonify(body), status
-
-
 def _row_to_dict(r: BackupRun) -> dict:
     return {
         "id": r.id,

From 21c1b0a81c24f2b85dd48166fc14879c490514cb Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 13:15:04 -0400
Subject: [PATCH 14/18] refactor(dry-B4): extract shared async_session_factory
 for Celery tasks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

download/migration/scan each defined an identical _async_session_factory()
(fresh per-invocation async engine — async connections are event-loop-bound
so each asyncio.run() task needs its own engine, unlike the process-wide
_sync_engine). Moved it to tasks/_async_session.py; the 3 files import it
and drop their now-orphaned sqlalchemy.ext.asyncio / get_config imports
(migration keeps AsyncSession for a type hint). Call-site try/finally
dispose left as-is to avoid re-indenting the critical task bodies.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 backend/app/tasks/_async_session.py | 21 +++++++++++++++++++++
 backend/app/tasks/download.py       | 11 ++---------
 backend/app/tasks/migration.py      | 12 +++---------
 backend/app/tasks/scan.py           | 11 ++---------
 4 files changed, 28 insertions(+), 27 deletions(-)
 create mode 100644 backend/app/tasks/_async_session.py

diff --git a/backend/app/tasks/_async_session.py b/backend/app/tasks/_async_session.py
new file mode 100644
index 0000000..ea7a796
--- /dev/null
+++ b/backend/app/tasks/_async_session.py
@@ -0,0 +1,21 @@
+"""Per-invocation async session factory for Celery task modules.
+
+Async engine connections are bound to the event loop. Each Celery task
+runs its async body under a fresh ``asyncio.run()`` loop, so it needs its
+own engine created (and disposed) within that loop — a process-wide async
+engine would reuse loop-bound connections across tasks and raise "attached
+to a different loop". So unlike the process-wide sync engine in
+``_sync_engine.py``, this returns a fresh engine per call; the caller
+disposes it (``await engine.dispose()``) when its loop ends.
+"""
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from ..config import get_config
+
+
+def async_session_factory():
+    """Return ``(sessionmaker, engine)`` bound to a fresh async engine."""
+    cfg = get_config()
+    engine = create_async_engine(cfg.database_url, future=True, pool_pre_ping=True)
+    return async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False), engine
diff --git a/backend/app/tasks/download.py b/backend/app/tasks/download.py
index 8801a56..fa82212 100644
--- a/backend/app/tasks/download.py
+++ b/backend/app/tasks/download.py
@@ -5,10 +5,8 @@ from pathlib import Path
 
 from sqlalchemy import select
 from sqlalchemy.exc import DBAPIError, OperationalError
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
 from ..celery_app import celery
-from ..config import get_config
 from ..models import ImportSettings
 from ..services.credential_crypto import CredentialCrypto
 from ..services.credential_service import CredentialService
@@ -16,18 +14,13 @@ from ..services.download_service import DownloadService
 from ..services.gallery_dl import GalleryDLService
 from ..services.importer import Importer
 from ..services.thumbnailer import Thumbnailer
+from ._async_session import async_session_factory
 from .import_file import _sync_session_factory
 
 IMAGES_ROOT = Path("/images")
 _KEY_PATH = IMAGES_ROOT / "secrets" / "credential_key.b64"
 
 
-def _async_session_factory():
-    cfg = get_config()
-    engine = create_async_engine(cfg.database_url, future=True, pool_pre_ping=True)
-    return async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False), engine
-
-
 @celery.task(
     name="backend.app.tasks.download.download_source",
     bind=True,
@@ -44,7 +37,7 @@ def download_source(self, source_id: int) -> int:
     """Returns the DownloadEvent.id."""
 
     async def _run():
-        async_factory, async_engine = _async_session_factory()
+        async_factory, async_engine = async_session_factory()
         SyncFactory = _sync_session_factory()
         try:
             with SyncFactory() as sync_session:
diff --git a/backend/app/tasks/migration.py b/backend/app/tasks/migration.py
index a59c8b2..aec5102 100644
--- a/backend/app/tasks/migration.py
+++ b/backend/app/tasks/migration.py
@@ -15,14 +15,14 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from ..celery_app import celery
-from ..config import get_config
 from ..models import MigrationRun
 from ..services.credential_crypto import CredentialCrypto
 from ..services.migrators import cleanup as cleanup_mod
 from ..services.migrators import gs_ingest, ir_ingest, ml_queue, tag_apply, verify
+from ._async_session import async_session_factory
 
 log = logging.getLogger(__name__)
 
@@ -30,12 +30,6 @@ IMAGES_ROOT = Path("/images")
 _KEY_PATH = IMAGES_ROOT / "secrets" / "credential_key.b64"
 
 
-def _async_session_factory():
-    cfg = get_config()
-    engine = create_async_engine(cfg.database_url, future=True, pool_pre_ping=True)
-    return async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False), engine
-
-
 async def _update_run(
     db: AsyncSession, run_id: int, *,
     status: str | None = None, counts: dict | None = None,
@@ -59,7 +53,7 @@ async def _update_run(
 
 
 async def _run_async(run_id: int, kind: str, params: dict) -> dict:
-    factory, engine = _async_session_factory()
+    factory, engine = async_session_factory()
     try:
         async with factory() as db:
             await _update_run(db, run_id, status="running")
diff --git a/backend/app/tasks/scan.py b/backend/app/tasks/scan.py
index 60cbfe0..c5f3dff 100644
--- a/backend/app/tasks/scan.py
+++ b/backend/app/tasks/scan.py
@@ -12,13 +12,12 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
 from ..celery_app import celery
-from ..config import get_config
 from ..models import DownloadEvent, ImportBatch, ImportSettings, ImportTask
 from ..services.archive_extractor import is_archive
 from ..services.scheduler_service import record_tick, select_due_sources
+from ._async_session import async_session_factory
 from ._sync_engine import sync_session_factory as _sync_session_factory
 
 
@@ -141,14 +140,8 @@ def scan_directory(self, triggered_by: str = "manual",
 # --- FC-3d: periodic source-check tick ------------------------------------
 
 
-def _async_session_factory():
-    cfg = get_config()
-    engine = create_async_engine(cfg.database_url, future=True, pool_pre_ping=True)
-    return async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False), engine
-
-
 async def _tick_due_sources_async() -> dict:
-    factory, engine = _async_session_factory()
+    factory, engine = async_session_factory()
     try:
         async with factory() as session:
             # Prove the scheduler is alive even on empty ticks (UI reads this).

From 171c4869394f9a31e45524673f3d284160940be1 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 14:03:26 -0400
Subject: [PATCH 15/18] refactor(dry-B2): ImportSettings.load()/load_sync()
 classmethods for the singleton row
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `select(ImportSettings).where(id == 1)).scalar_one()` singleton load was
repeated 15× across services, API, and 5 task modules. Added async load() +
sync load_sync() classmethods on the model and migrated all 15 full-row sites
(callers already imported ImportSettings, so no new imports; dropped download's
now-orphaned select import). Left maintenance.py's deliberate column-select
(import_scan_path only) as-is.

Rest of the service layer was already adequately DRY — the Record/to_dict
pattern is only 2 instances and the savepoint find-or-create recovery is
correctly per-entity, so neither was forced into a shared abstraction.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 backend/app/api/import_admin.py           |  4 +---
 backend/app/api/settings.py               |  8 ++------
 backend/app/api/system_backup.py          |  8 ++------
 backend/app/models/import_settings.py     | 12 +++++++++++-
 backend/app/services/scheduler_service.py |  8 ++------
 backend/app/services/source_service.py    |  4 +---
 backend/app/tasks/backup.py               |  8 ++------
 backend/app/tasks/download.py             |  9 ++-------
 backend/app/tasks/import_file.py          |  4 +---
 backend/app/tasks/maintenance.py          |  4 +---
 backend/app/tasks/scan.py                 |  4 +---
 11 files changed, 26 insertions(+), 47 deletions(-)

diff --git a/backend/app/api/import_admin.py b/backend/app/api/import_admin.py
index 7ad3fa7..36575c3 100644
--- a/backend/app/api/import_admin.py
+++ b/backend/app/api/import_admin.py
@@ -159,9 +159,7 @@ def _refetch_task_sync(session, task_id: int) -> dict:
         return {"status": "not_found"}
     if task.status != "failed":
         return {"status": "not_failed"}
-    settings = session.execute(
-        select(ImportSettings).where(ImportSettings.id == 1)
-    ).scalar_one()
+    settings = ImportSettings.load_sync(session)
     return attempt_refetch(session, task, Path(settings.import_scan_path))
 
 
diff --git a/backend/app/api/settings.py b/backend/app/api/settings.py
index 145890e..fa97bda 100644
--- a/backend/app/api/settings.py
+++ b/backend/app/api/settings.py
@@ -31,9 +31,7 @@ _EDITABLE_FIELDS = (
 @settings_bp.route("/settings/import", methods=["GET"])
 async def get_import_settings():
     async with get_session() as session:
-        row = (
-            await session.execute(select(ImportSettings).where(ImportSettings.id == 1))
-        ).scalar_one()
+        row = await ImportSettings.load(session)
     return jsonify({
         "min_width": row.min_width,
         "min_height": row.min_height,
@@ -99,9 +97,7 @@ async def update_import_settings():
             return _bad_int("download_failure_warning_threshold", 1, 100)
 
     async with get_session() as session:
-        row = (
-            await session.execute(select(ImportSettings).where(ImportSettings.id == 1))
-        ).scalar_one()
+        row = await ImportSettings.load(session)
         for field in _EDITABLE_FIELDS:
             if field in body:
                 setattr(row, field, body[field])
diff --git a/backend/app/api/system_backup.py b/backend/app/api/system_backup.py
index fcf57c7..a0f9ef2 100644
--- a/backend/app/api/system_backup.py
+++ b/backend/app/api/system_backup.py
@@ -227,9 +227,7 @@ async def delete_run(run_id: int):
 @system_backup_bp.route("/settings", methods=["GET"])
 async def get_settings():
     async with get_session() as session:
-        row = (await session.execute(
-            select(ImportSettings).where(ImportSettings.id == 1)
-        )).scalar_one()
+        row = await ImportSettings.load(session)
     return jsonify({
         "backup_db_nightly_enabled": row.backup_db_nightly_enabled,
         "backup_db_nightly_hour_utc": row.backup_db_nightly_hour_utc,
@@ -249,9 +247,7 @@ async def patch_settings():
         return err
 
     async with get_session() as session:
-        row = (await session.execute(
-            select(ImportSettings).where(ImportSettings.id == 1)
-        )).scalar_one()
+        row = await ImportSettings.load(session)
         for field in _BACKUP_SETTINGS_FIELDS:
             if field in body:
                 setattr(row, field, body[field])
diff --git a/backend/app/models/import_settings.py b/backend/app/models/import_settings.py
index 323fbf6..aa874ea 100644
--- a/backend/app/models/import_settings.py
+++ b/backend/app/models/import_settings.py
@@ -4,7 +4,7 @@ Enforced as a single row via a CHECK (id = 1) constraint. The application
 always SELECTs id=1 and never inserts/deletes after the initial migration.
 """
 
-from sqlalchemy import Boolean, CheckConstraint, Float, Integer, Text
+from sqlalchemy import Boolean, CheckConstraint, Float, Integer, Text, select
 from sqlalchemy.orm import Mapped, mapped_column
 
 from .base import Base
@@ -63,3 +63,13 @@ class ImportSettings(Base):
     backup_images_keep_last_n: Mapped[int] = mapped_column(
         Integer, nullable=False, default=3,
     )
+
+    @classmethod
+    async def load(cls, session) -> "ImportSettings":
+        """The singleton settings row (id=1), via an async session."""
+        return (await session.execute(select(cls).where(cls.id == 1))).scalar_one()
+
+    @classmethod
+    def load_sync(cls, session) -> "ImportSettings":
+        """The singleton settings row (id=1), via a sync session."""
+        return session.execute(select(cls).where(cls.id == 1)).scalar_one()
diff --git a/backend/app/services/scheduler_service.py b/backend/app/services/scheduler_service.py
index 2008eba..e70c87f 100644
--- a/backend/app/services/scheduler_service.py
+++ b/backend/app/services/scheduler_service.py
@@ -58,9 +58,7 @@ async def select_due_sources(session: AsyncSession) -> list[Source]:
         .where(Artist.auto_check.is_(True))
     )).scalars().all()
 
-    settings = (await session.execute(
-        select(ImportSettings).where(ImportSettings.id == 1)
-    )).scalar_one()
+    settings = await ImportSettings.load(session)
 
     now = datetime.now(UTC)
     due: list[Source] = []
@@ -121,9 +119,7 @@ async def scheduler_status(session: AsyncSession) -> dict:
         .where(Source.enabled.is_(True))
         .where(Artist.auto_check.is_(True))
     )).scalars().all()
-    settings = (await session.execute(
-        select(ImportSettings).where(ImportSettings.id == 1)
-    )).scalar_one()
+    settings = await ImportSettings.load(session)
 
     now = datetime.now(UTC)
     due_now = 0
diff --git a/backend/app/services/source_service.py b/backend/app/services/source_service.py
index ec17bed..85a6564 100644
--- a/backend/app/services/source_service.py
+++ b/backend/app/services/source_service.py
@@ -120,9 +120,7 @@ class SourceService:
         return config
 
     async def _load_settings(self) -> ImportSettings:
-        return (await self.session.execute(
-            select(ImportSettings).where(ImportSettings.id == 1)
-        )).scalar_one()
+        return await ImportSettings.load(self.session)
 
     def _build_record(
         self, source: Source, artist: Artist, settings: ImportSettings,
diff --git a/backend/app/tasks/backup.py b/backend/app/tasks/backup.py
index 9d2fefb..da7c841 100644
--- a/backend/app/tasks/backup.py
+++ b/backend/app/tasks/backup.py
@@ -246,9 +246,7 @@ def prune_backups() -> dict:
     SessionLocal = _sync_session_factory()
     counts = {"db_deleted": 0, "images_deleted": 0, "files_unlinked": 0}
     with SessionLocal() as session:
-        s = session.execute(
-            select(ImportSettings).where(ImportSettings.id == 1)
-        ).scalar_one()
+        s = ImportSettings.load_sync(session)
         for kind, keep in (
             ("db", s.backup_db_keep_last_n),
             ("images", s.backup_images_keep_last_n),
@@ -286,9 +284,7 @@ def backup_db_nightly() -> dict:
     either {'skipped': '<reason>'} or {'dispatched': '<task_id>'}."""
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
-        s = session.execute(
-            select(ImportSettings).where(ImportSettings.id == 1)
-        ).scalar_one()
+        s = ImportSettings.load_sync(session)
         nightly_enabled = s.backup_db_nightly_enabled
         configured_hour = s.backup_db_nightly_hour_utc
     if not nightly_enabled:
diff --git a/backend/app/tasks/download.py b/backend/app/tasks/download.py
index fa82212..7cd7c13 100644
--- a/backend/app/tasks/download.py
+++ b/backend/app/tasks/download.py
@@ -3,7 +3,6 @@
 import asyncio
 from pathlib import Path
 
-from sqlalchemy import select
 from sqlalchemy.exc import DBAPIError, OperationalError
 
 from ..celery_app import celery
@@ -41,9 +40,7 @@ def download_source(self, source_id: int) -> int:
         SyncFactory = _sync_session_factory()
         try:
             with SyncFactory() as sync_session:
-                settings = sync_session.execute(
-                    select(ImportSettings).where(ImportSettings.id == 1)
-                ).scalar_one()
+                settings = ImportSettings.load_sync(sync_session)
                 rate_limit = settings.download_rate_limit_seconds
                 validate_files = settings.download_validate_files
 
@@ -57,9 +54,7 @@ def download_source(self, source_id: int) -> int:
             async with async_factory() as async_session:
                 cred_service = CredentialService(async_session, crypto)
                 with SyncFactory() as sync_session:
-                    sync_settings = sync_session.execute(
-                        select(ImportSettings).where(ImportSettings.id == 1)
-                    ).scalar_one()
+                    sync_settings = ImportSettings.load_sync(sync_session)
                     importer = Importer(
                         session=sync_session,
                         images_root=IMAGES_ROOT,
diff --git a/backend/app/tasks/import_file.py b/backend/app/tasks/import_file.py
index 4a124d1..49c798d 100644
--- a/backend/app/tasks/import_file.py
+++ b/backend/app/tasks/import_file.py
@@ -167,9 +167,7 @@ def enqueue_import(task_id: int, task_type: str) -> None:
 
 def _do_import(session, task, import_task_id: int) -> dict:
     """Actual work, called from inside the resilience wrapper."""
-    settings = session.execute(
-        select(ImportSettings).where(ImportSettings.id == 1)
-    ).scalar_one()
+    settings = ImportSettings.load_sync(session)
     import_root = Path(settings.import_scan_path)
     batch = session.get(ImportBatch, task.batch_id)
     deep = bool(batch and batch.scan_mode == "deep")
diff --git a/backend/app/tasks/maintenance.py b/backend/app/tasks/maintenance.py
index 4584d01..8bd321b 100644
--- a/backend/app/tasks/maintenance.py
+++ b/backend/app/tasks/maintenance.py
@@ -460,9 +460,7 @@ def cleanup_old_download_events() -> int:
     """
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
-        settings = session.execute(
-            select(ImportSettings).where(ImportSettings.id == 1)
-        ).scalar_one()
+        settings = ImportSettings.load_sync(session)
         retention_days = settings.download_event_retention_days
         cutoff = datetime.now(UTC) - timedelta(days=retention_days)
         result = session.execute(
diff --git a/backend/app/tasks/scan.py b/backend/app/tasks/scan.py
index c5f3dff..90398fa 100644
--- a/backend/app/tasks/scan.py
+++ b/backend/app/tasks/scan.py
@@ -44,9 +44,7 @@ def scan_directory(self, triggered_by: str = "manual",
     batch id."""
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
-        settings = session.execute(
-            select(ImportSettings).where(ImportSettings.id == 1)
-        ).scalar_one()
+        settings = ImportSettings.load_sync(session)
         import_root = Path(settings.import_scan_path)
 
         batch = ImportBatch(

From 9d18dacbe80092b8cc3f1ca398cd77b45973baef Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 14:08:24 -0400
Subject: [PATCH 16/18] =?UTF-8?q?fix(lint):=20UP037=20=E2=80=94=20drop=20q?=
 =?UTF-8?q?uotes=20from=20ImportSettings.load=20return=20annotations=20(py?=
 =?UTF-8?q?3.14=20deferred=20annotations)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 backend/app/models/import_settings.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend/app/models/import_settings.py b/backend/app/models/import_settings.py
index aa874ea..e5142ca 100644
--- a/backend/app/models/import_settings.py
+++ b/backend/app/models/import_settings.py
@@ -65,11 +65,11 @@ class ImportSettings(Base):
     )
 
     @classmethod
-    async def load(cls, session) -> "ImportSettings":
+    async def load(cls, session) -> ImportSettings:
         """The singleton settings row (id=1), via an async session."""
         return (await session.execute(select(cls).where(cls.id == 1))).scalar_one()
 
     @classmethod
-    def load_sync(cls, session) -> "ImportSettings":
+    def load_sync(cls, session) -> ImportSettings:
         """The singleton settings row (id=1), via a sync session."""
         return session.execute(select(cls).where(cls.id == 1)).scalar_one()

From 32bdde049f0048e95e8f3fa1a98394279ac28800 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 15:02:55 -0400
Subject: [PATCH 17/18] refactor(dry-B3): extract _get_or_create race-safe
 find-or-create in Importer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_find_or_create_source, _source_for_sidecar, and _find_or_create_post each
repeated the SELECT → savepoint-INSERT → on-IntegrityError rollback+re-SELECT
pattern. Extracted _get_or_create(stmt, factory): the statement is reused for
the scalar_one_or_none lookup and the scalar_one post-conflict re-fetch, so
all three are reproduced exactly. Centralizing the race-safe pattern in one
place also reduces the risk of the copies drifting (the bug class banked
2026-05-26).

Left _upsert_artist (no savepoint by design) and the ImageProvenance void
ensure-exists block (no return / no re-select) alone — they don't fit.

The rest of the ingest pipeline was already DRY: sidecar parsing lives in
utils/sidecar.py, per-platform quirks in the platforms package, and
_safe_ext/_categorize_error/_build_config are each single-instance.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 backend/app/services/importer.py | 124 +++++++++++++------------------
 1 file changed, 51 insertions(+), 73 deletions(-)

diff --git a/backend/app/services/importer.py b/backend/app/services/importer.py
index 0e366d9..b722f67 100644
--- a/backend/app/services/importer.py
+++ b/backend/app/services/importer.py
@@ -204,6 +204,32 @@ class Importer:
                 (phash, width or 0, height or 0, image_id)
             )
 
+    def _get_or_create(self, stmt, factory):
+        """Race-safe find-or-create. Run `stmt` (scalar_one_or_none); if a
+        row exists, return it. Otherwise open a savepoint and INSERT
+        ``factory()``; on IntegrityError (a concurrent worker inserted the
+        same row first) roll the savepoint back — NOT the outer transaction,
+        which would lose the surrounding scan's progress — and re-run `stmt`
+        (scalar_one) to return the row the other worker created.
+
+        Centralizes the pattern shared by _find_or_create_source,
+        _source_for_sidecar, and _find_or_create_post. The plain
+        SELECT-then-INSERT version lost races under the 5-min recovery sweep
+        (operator-flagged 2026-05-26)."""
+        existing = self.session.execute(stmt).scalar_one_or_none()
+        if existing is not None:
+            return existing
+        sp = self.session.begin_nested()
+        try:
+            row = factory()
+            self.session.add(row)
+            self.session.flush()
+            sp.commit()
+            return row
+        except IntegrityError:
+            sp.rollback()
+            return self.session.execute(stmt).scalar_one()
+
     def _find_or_create_source(
         self, *, artist_id: int, platform: str, url: str,
     ) -> Source:
@@ -222,31 +248,15 @@ class Importer:
         and re-select — the concurrent op just created the row we
         wanted, so the second select will find it.
         """
-        existing = self.session.execute(
-            select(Source).where(
-                Source.artist_id == artist_id,
-                Source.platform == platform,
-                Source.url == url,
-            )
-        ).scalar_one_or_none()
-        if existing is not None:
-            return existing
-        sp = self.session.begin_nested()
-        try:
-            row = Source(artist_id=artist_id, platform=platform, url=url)
-            self.session.add(row)
-            self.session.flush()
-            sp.commit()
-            return row
-        except IntegrityError:
-            sp.rollback()
-            return self.session.execute(
-                select(Source).where(
-                    Source.artist_id == artist_id,
-                    Source.platform == platform,
-                    Source.url == url,
-                )
-            ).scalar_one()
+        stmt = select(Source).where(
+            Source.artist_id == artist_id,
+            Source.platform == platform,
+            Source.url == url,
+        )
+        return self._get_or_create(
+            stmt,
+            lambda: Source(artist_id=artist_id, platform=platform, url=url),
+        )
 
     def _source_for_sidecar(
         self, *, artist_id: int, platform: str, artist_slug: str,
@@ -268,7 +278,7 @@ class Importer:
         ONE synthetic anchor with url='sidecar:<platform>:<artist_slug>' and
         enabled=False (so the subscription checker doesn't poll it).
         """
-        existing = self.session.execute(
+        stmt = (
             select(Source)
             .where(
                 Source.artist_id == artist_id,
@@ -276,33 +286,16 @@ class Importer:
             )
             .order_by(Source.id.asc())
             .limit(1)
-        ).scalar_one_or_none()
-        if existing is not None:
-            return existing
-        synthetic_url = f"sidecar:{platform}:{artist_slug}"
-        sp = self.session.begin_nested()
-        try:
-            row = Source(
+        )
+        return self._get_or_create(
+            stmt,
+            lambda: Source(
                 artist_id=artist_id,
                 platform=platform,
-                url=synthetic_url,
+                url=f"sidecar:{platform}:{artist_slug}",
                 enabled=False,
-            )
-            self.session.add(row)
-            self.session.flush()
-            sp.commit()
-            return row
-        except IntegrityError:
-            sp.rollback()
-            return self.session.execute(
-                select(Source)
-                .where(
-                    Source.artist_id == artist_id,
-                    Source.platform == platform,
-                )
-                .order_by(Source.id.asc())
-                .limit(1)
-            ).scalar_one()
+            ),
+        )
 
     def _find_or_create_post(
         self, *, source_id: int, external_post_id: str,
@@ -310,29 +303,14 @@ class Importer:
         """Race-safe find-or-create on `post` keyed by
         (source_id, external_post_id). Mirrors `_find_or_create_source`
         — same savepoint + IntegrityError-recovery pattern."""
-        existing = self.session.execute(
-            select(Post).where(
-                Post.source_id == source_id,
-                Post.external_post_id == external_post_id,
-            )
-        ).scalar_one_or_none()
-        if existing is not None:
-            return existing
-        sp = self.session.begin_nested()
-        try:
-            row = Post(source_id=source_id, external_post_id=external_post_id)
-            self.session.add(row)
-            self.session.flush()
-            sp.commit()
-            return row
-        except IntegrityError:
-            sp.rollback()
-            return self.session.execute(
-                select(Post).where(
-                    Post.source_id == source_id,
-                    Post.external_post_id == external_post_id,
-                )
-            ).scalar_one()
+        stmt = select(Post).where(
+            Post.source_id == source_id,
+            Post.external_post_id == external_post_id,
+        )
+        return self._get_or_create(
+            stmt,
+            lambda: Post(source_id=source_id, external_post_id=external_post_id),
+        )
 
     def import_one(self, source: Path) -> ImportResult:
         """Dispatch by kind. Media → normal pipeline. Archive → extract

From 1322056b220393b03c5a0d06dc571546ff4858bc Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Thu, 28 May 2026 15:20:30 -0400
Subject: [PATCH 18/18] refactor(dry-F5): useTabQuery composable for ?tab=
 query-param routing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ArtistView and SubscriptionsView both two-way-bound a tab ref with the
?tab= query param via identical tab->URL and URL->tab watchers. Extracted
useTabQuery(validTabs, defaultTab) — defaultTab accepts a string or a
function (ArtistView's default is postCount-dependent), and resolve() is
exposed so ArtistView can re-apply it after the artist loads. Both views
drop their now-orphaned ref/useRouter imports.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend/src/composables/useTabQuery.js  | 30 ++++++++++++++++++++
 frontend/src/views/ArtistView.vue        | 35 ++++++------------------
 frontend/src/views/SubscriptionsView.vue | 22 ++-------------
 3 files changed, 40 insertions(+), 47 deletions(-)
 create mode 100644 frontend/src/composables/useTabQuery.js

diff --git a/frontend/src/composables/useTabQuery.js b/frontend/src/composables/useTabQuery.js
new file mode 100644
index 0000000..57b39ae
--- /dev/null
+++ b/frontend/src/composables/useTabQuery.js
@@ -0,0 +1,30 @@
+import { ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+// Two-way bind a tab ref with the ?tab= query param: the initial value comes
+// from the URL (when it names a valid tab) else `defaultTab` — a string, or a
+// function for a state-dependent default. Tab changes push to the URL via
+// router.replace (no history spam); URL changes (back/forward) flow back into
+// the ref. Returns { tab, resolve } where resolve() re-applies the URL-or-
+// default rule (callers re-run it when their default inputs change).
+export function useTabQuery(validTabs, defaultTab) {
+  const route = useRoute()
+  const router = useRouter()
+
+  const resolveDefault = () =>
+    (typeof defaultTab === 'function' ? defaultTab() : defaultTab)
+  const resolve = () =>
+    (validTabs.includes(route.query.tab) ? route.query.tab : resolveDefault())
+
+  const tab = ref(resolve())
+
+  watch(tab, (t) => {
+    if (route.query.tab === t) return
+    router.replace({ query: { ...route.query, tab: t } })
+  })
+  watch(() => route.query.tab, (q) => {
+    if (q && validTabs.includes(q) && tab.value !== q) tab.value = q
+  })
+
+  return { tab, resolve }
+}
diff --git a/frontend/src/views/ArtistView.vue b/frontend/src/views/ArtistView.vue
index 876b9d8..0dcf90f 100644
--- a/frontend/src/views/ArtistView.vue
+++ b/frontend/src/views/ArtistView.vue
@@ -39,30 +39,26 @@
 </template>
 
 <script setup>
-import { computed, ref, watch } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
+import { computed, watch } from 'vue'
+import { useRoute } from 'vue-router'
 
 import { useArtistStore } from '../stores/artist.js'
 import ArtistHeader from '../components/artist/ArtistHeader.vue'
 import ArtistPostsTab from '../components/artist/ArtistPostsTab.vue'
 import ArtistGalleryTab from '../components/artist/ArtistGalleryTab.vue'
 import ArtistManagementTab from '../components/artist/ArtistManagementTab.vue'
+import { useTabQuery } from '../composables/useTabQuery.js'
 
 const VALID_TABS = ['posts', 'gallery', 'management']
 
 const route = useRoute()
-const router = useRouter()
 const store = useArtistStore()
 
 const slug = computed(() => route.params.slug)
-const tab = ref('posts')
-
-function resolveDefaultTab () {
-  const fromUrl = route.query.tab
-  if (VALID_TABS.includes(fromUrl)) return fromUrl
-  if ((store.postCount ?? 0) > 0) return 'posts'
-  return 'gallery'
-}
+const { tab, resolve } = useTabQuery(
+  VALID_TABS,
+  () => ((store.postCount ?? 0) > 0 ? 'posts' : 'gallery'),
+)
 
 watch(slug, async (s) => {
   if (!s) return
@@ -70,23 +66,8 @@ watch(slug, async (s) => {
   document.title = store.overview
     ? `${store.overview.name} — FabledCurator`
     : 'FabledCurator'
-  tab.value = resolveDefaultTab()
+  tab.value = resolve()
 }, { immediate: true })
-
-// Reflect tab changes back into the URL so refresh/back/forward work.
-watch(tab, (newTab) => {
-  if (route.query.tab === newTab) return
-  router.replace({
-    query: { ...route.query, tab: newTab },
-  })
-})
-
-// React to URL-tab changes (e.g., back/forward).
-watch(() => route.query.tab, (q) => {
-  if (q && VALID_TABS.includes(q) && tab.value !== q) {
-    tab.value = q
-  }
-})
 </script>
 
 <style scoped>
diff --git a/frontend/src/views/SubscriptionsView.vue b/frontend/src/views/SubscriptionsView.vue
index 7b1105c..0f2098b 100644
--- a/frontend/src/views/SubscriptionsView.vue
+++ b/frontend/src/views/SubscriptionsView.vue
@@ -36,32 +36,14 @@
 </template>
 
 <script setup>
-import { ref, watch } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-
 import SubscriptionsTab from '../components/subscriptions/SubscriptionsTab.vue'
 import DownloadsTab from '../components/subscriptions/DownloadsTab.vue'
 import SettingsTab from '../components/subscriptions/SettingsTab.vue'
+import { useTabQuery } from '../composables/useTabQuery.js'
 
 const VALID_TABS = ['subscriptions', 'downloads', 'settings']
 
-const route = useRoute()
-const router = useRouter()
-
-const tab = ref(
-  VALID_TABS.includes(route.query.tab) ? route.query.tab : 'subscriptions',
-)
-
-watch(tab, (t) => {
-  if (route.query.tab === t) return
-  router.replace({ query: { ...route.query, tab: t } })
-})
-
-watch(() => route.query.tab, (q) => {
-  if (q && VALID_TABS.includes(q) && tab.value !== q) {
-    tab.value = q
-  }
-})
+const { tab } = useTabQuery(VALID_TABS, 'subscriptions')
 </script>
 
 <style scoped>