From d5d23a92f2c96bb907ad4fc7a32ce48321394a8a Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 21:18:02 -0400
Subject: [PATCH 01/10] feat(nav): consolidate Posts/Artists/Tags into a Browse
 hub
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Posts, Artists, and Tags are the three 'browse the library by an axis'
surfaces; Subscriptions stays purely management (operator-asked 2026-06-09).
New BrowseView renders them as tabs (?tab=posts|artists|tags); only the active
tab mounts. The old standalone paths become redirects into the matching tab,
preserving deep-link query (/posts?post_id=N → /browse?tab=posts&post_id=N) and
keeping the route names so existing { name: 'posts'|'artists'|'tags' } links and
path pushes still resolve. Nav now reads Showcase · Gallery · Browse · Series ·
Subscriptions, with Settings pinned right.

Test: /browse resolves; /tags and /artists redirect into their tabs; a posts
deep link survives the redirect.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/router.js            | 35 ++++++++++++++---------
 frontend/src/views/BrowseView.vue | 47 +++++++++++++++++++++++++++++++
 frontend/test/router.spec.js      | 20 +++++++++++--
 3 files changed, 86 insertions(+), 16 deletions(-)
 create mode 100644 frontend/src/views/BrowseView.vue

diff --git a/frontend/src/router.js b/frontend/src/router.js
index 2073c84..fa86c0f 100644
--- a/frontend/src/router.js
+++ b/frontend/src/router.js
@@ -2,14 +2,12 @@ import { createRouter, createWebHistory, createMemoryHistory } from 'vue-router'
 import SettingsView from './views/SettingsView.vue'
 import GalleryView from './views/GalleryView.vue'
 import ShowcaseView from './views/ShowcaseView.vue'
-import TagsView from './views/TagsView.vue'
+import BrowseView from './views/BrowseView.vue'
 import ArtistView from './views/ArtistView.vue'
 import SeriesView from './views/SeriesView.vue'
 import SeriesManageView from './views/SeriesManageView.vue'
 import SeriesReaderView from './views/SeriesReaderView.vue'
 import SubscriptionsView from './views/SubscriptionsView.vue'
-import PostsView from './views/PostsView.vue'
-import ArtistsView from './views/ArtistsView.vue'
 
 // The application's front door. `/` redirects here. Changing the front door
 // is a one-line edit (e.g. '/gallery' or '/tags').
@@ -22,27 +20,36 @@ const routes = [
   // FC-2: image backbone
   { path: '/showcase', name: 'showcase', component: ShowcaseView, meta: { title: 'Showcase' } },
   { path: '/gallery',  name: 'gallery',  component: GalleryView,  meta: { title: 'Gallery'  } },
-  { path: '/artists',  name: 'artists',  component: ArtistsView,  meta: { title: 'Artists'  } },
-  { path: '/tags',     name: 'tags',     component: TagsView,     meta: { title: 'Tags'     } },
+  // Browse hub (operator-asked 2026-06-09): Posts / Artists / Tags as tabs —
+  // the three "browse the library by an axis" surfaces. One nav entry; the old
+  // standalone paths redirect into the matching tab (below).
+  { path: '/browse', name: 'browse', component: BrowseView, meta: { title: 'Browse' } },
   // Artist detail — no meta.title (reached by clicking an artist, not nav).
   { path: '/artist/:slug', name: 'artist', component: ArtistView },
-  // Series browse — a nav entry (meta.title). Peer of Posts.
+  // Series browse — a nav entry (meta.title).
   { path: '/series', name: 'series', component: SeriesView, meta: { title: 'Series' } },
   // Series management — no meta.title (reached from a series card/tag).
   { path: '/series/:tagId', name: 'series-manage', component: SeriesManageView },
   // Series reader — immersive (no top nav, no meta.title).
   { path: '/series/:tagId/read', name: 'series-read', component: SeriesReaderView, meta: { immersive: true } },
-  { path: '/settings', name: 'settings', component: SettingsView, meta: { title: 'Settings' } },
 
-  // FC-3: subscription backbone
-  // /credentials and /downloads were folded into /subscriptions as subtabs
-  // 2026-05-27 (?tab=settings and ?tab=downloads). The hub view owns the
-  // whole download pipeline domain.
-  { path: '/posts',         name: 'posts',         component: PostsView,         meta: { title: 'Posts'         } },
+  // FC-3: subscription backbone — purely management (sources/downloads),
+  // distinct from the Browse hub.
   { path: '/subscriptions', name: 'subscriptions', component: SubscriptionsView, meta: { title: 'Subscriptions' } },
 
-  // Bookmark/back-button safety net for the routes that got folded in
-  // (no meta.title — stay out of TopNav).
+  // Settings — config, pinned to the right of the nav (TopNav special-cases it).
+  { path: '/settings', name: 'settings', component: SettingsView, meta: { title: 'Settings' } },
+
+  // The old standalone paths now redirect into the Browse hub, preserving any
+  // deep-link query (e.g. /posts?post_id=N → /browse?tab=posts&post_id=N). The
+  // route NAMES stay so existing { name: 'posts' | 'artists' | 'tags' } links
+  // and path pushes keep resolving.
+  { path: '/posts',   name: 'posts',   redirect: (to) => ({ name: 'browse', query: { ...to.query, tab: 'posts' } }) },
+  { path: '/artists', name: 'artists', redirect: (to) => ({ name: 'browse', query: { ...to.query, tab: 'artists' } }) },
+  { path: '/tags',    name: 'tags',    redirect: (to) => ({ name: 'browse', query: { ...to.query, tab: 'tags' } }) },
+
+  // Bookmark/back-button safety net for the routes that got folded into
+  // /subscriptions (no meta.title — stay out of TopNav).
   { path: '/credentials', redirect: '/subscriptions?tab=settings' },
   { path: '/downloads',   redirect: '/subscriptions?tab=downloads' }
 ]
diff --git a/frontend/src/views/BrowseView.vue b/frontend/src/views/BrowseView.vue
new file mode 100644
index 0000000..76a8da4
--- /dev/null
+++ b/frontend/src/views/BrowseView.vue
@@ -0,0 +1,47 @@
+<template>
+  <div class="fc-browse">
+    <v-container fluid class="pt-2 pb-0">
+      <v-tabs v-model="tab" density="compact">
+        <v-tab value="posts">Posts</v-tab>
+        <v-tab value="artists">Artists</v-tab>
+        <v-tab value="tags">Tags</v-tab>
+      </v-tabs>
+    </v-container>
+
+    <!-- Each tab's view is self-contained (its own container + state). Only the
+         active one is mounted; switching tabs swaps it. The Posts tab still
+         reads its deep-link (post_id/artist_id/platform) from route.query, so
+         /browse?tab=posts&post_id=N works exactly like the old /posts deep link.
+         (FC nav consolidation, operator-asked 2026-06-09: Posts/Artists/Tags are
+         the three "browse the library by an axis" surfaces.) -->
+    <component :is="activeComponent" :key="tab" />
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+import ArtistsView from './ArtistsView.vue'
+import PostsView from './PostsView.vue'
+import TagsView from './TagsView.vue'
+
+const TABS = { posts: PostsView, artists: ArtistsView, tags: TagsView }
+
+const route = useRoute()
+const router = useRouter()
+
+const tab = computed({
+  get() {
+    const t = route.query.tab
+    return typeof t === 'string' && t in TABS ? t : 'posts'
+  },
+  set(value) {
+    // Switching tabs starts a clean tab — a posts deep link (post_id, etc.)
+    // belongs only to the Posts tab and shouldn't bleed into Artists/Tags.
+    router.replace({ name: 'browse', query: { tab: value } })
+  },
+})
+
+const activeComponent = computed(() => TABS[tab.value])
+</script>
diff --git a/frontend/test/router.spec.js b/frontend/test/router.spec.js
index c976fd3..338412f 100644
--- a/frontend/test/router.spec.js
+++ b/frontend/test/router.spec.js
@@ -17,13 +17,29 @@ describe('router', () => {
     expect(router.resolve('/gallery').name).toBe('gallery')
   })
 
-  it('showcase, tags, artist resolve to named routes', () => {
+  it('showcase, artist resolve to named routes', () => {
     expect(router.resolve('/showcase').name).toBe('showcase')
-    expect(router.resolve('/tags').name).toBe('tags')
     expect(router.resolve('/artist/some-slug').name).toBe('artist')
     expect(router.resolve('/artist/some-slug').params.slug).toBe('some-slug')
   })
 
+  it('browse hub is reachable and old axis paths redirect into its tabs', async () => {
+    expect(router.resolve('/browse').name).toBe('browse')
+
+    await router.push('/tags')
+    expect(router.currentRoute.value.name).toBe('browse')
+    expect(router.currentRoute.value.query.tab).toBe('tags')
+
+    await router.push('/artists')
+    expect(router.currentRoute.value.query.tab).toBe('artists')
+
+    // A posts deep link survives the redirect into the hub tab.
+    await router.push({ path: '/posts', query: { post_id: '7' } })
+    expect(router.currentRoute.value.name).toBe('browse')
+    expect(router.currentRoute.value.query.tab).toBe('posts')
+    expect(router.currentRoute.value.query.post_id).toBe('7')
+  })
+
   it('series-read is an immersive route', () => {
     const r = router.resolve('/series/5/read')
     expect(r.name).toBe('series-read')

From c774042a85f428881b9b216a405a436a147be9a8 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 22:25:11 -0400
Subject: [PATCH 02/10] refactor(ui): consolidate 7 hand-rolled kebabs into one
 KebabMenu (DRY pattern sweep)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First pattern-consistency DRY pass (process #594). The overflow kebab was
hand-rolled 7 ways in two divergent activator strategies — Pattern A
(#activator + v-bind) which silently breaks inside the teleported image modal
(#711), and Pattern B (manual v-model + activator=parent + open-on-click=false +
z-index 2400) the modal kebabs needed as a workaround.

New <KebabMenu> (components/common) bakes in the modal-safe strategy
UNIVERSALLY, so every kebab works in modal and non-modal contexts — folding the
latent #711-class bug fix into all five Pattern-A sites. Menu items go in the
default slot; variations (size/variant/location/label/min-width) are props.

Adopted across all 7: TagChip, SuggestionItem, TagCard, SeriesView card,
SeriesManageView, BackupRunsTable, SourceActions. Exhaustiveness (§8b):
mdi-dots-vertical now lives only in KebabMenu. Labeled dropdowns / nav menus /
filter popovers are a different concept and left alone. Seeded the pattern
catalog so new code reuses the primitive. Test: KebabMenu renders slot items +
trigger label/glyph + presentational props.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/components/common/KebabMenu.vue  | 50 +++++++++++++++++
 frontend/src/components/discovery/TagCard.vue | 48 +++++++---------
 .../src/components/modal/SuggestionItem.vue   | 52 +++++-------------
 frontend/src/components/modal/TagChip.vue     | 43 ++++-----------
 .../components/settings/BackupRunsTable.vue   | 34 +++++-------
 .../subscriptions/SourceActions.vue           | 51 ++++++++---------
 frontend/src/views/SeriesManageView.vue       | 55 ++++++++-----------
 frontend/src/views/SeriesView.vue             | 36 +++++-------
 frontend/test/components/kebabMenu.spec.js    | 38 +++++++++++++
 9 files changed, 211 insertions(+), 196 deletions(-)
 create mode 100644 frontend/src/components/common/KebabMenu.vue
 create mode 100644 frontend/test/components/kebabMenu.spec.js

diff --git a/frontend/src/components/common/KebabMenu.vue b/frontend/src/components/common/KebabMenu.vue
new file mode 100644
index 0000000..0052df7
--- /dev/null
+++ b/frontend/src/components/common/KebabMenu.vue
@@ -0,0 +1,50 @@
+<template>
+  <!-- Canonical kebab (overflow ⋮) menu — the single primitive every kebab in
+       the app uses (DRY pattern-consistency sweep 2026-06-09). It bakes in the
+       modal-safe activator strategy that the image-modal kebabs needed (#711):
+       a manual v-model toggled by @click.stop, `activator="parent"` for
+       positioning only, `:open-on-click="false"`, and a z-index above the modal
+       (2000) — so a kebab works identically inside a teleported modal and on a
+       plain page. Menu items go in the default slot; close-on-content-click
+       (Vuetify default) closes the menu when one is chosen. -->
+  <span class="fc-kebab">
+    <v-btn
+      :icon="icon"
+      :size="size"
+      :variant="variant"
+      :aria-label="label"
+      @click.stop="open = !open"
+    />
+    <v-menu
+      v-model="open"
+      activator="parent"
+      :open-on-click="false"
+      :location="location"
+      :z-index="2400"
+    >
+      <v-list density="compact" :min-width="minWidth">
+        <slot />
+      </v-list>
+    </v-menu>
+  </span>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+defineProps({
+  icon: { type: String, default: 'mdi-dots-vertical' },
+  size: { type: String, default: 'x-small' },
+  variant: { type: String, default: 'text' },
+  location: { type: String, default: 'bottom end' },
+  // aria-label for the trigger (every kebab should name what it acts on).
+  label: { type: String, default: 'More actions' },
+  minWidth: { type: [String, Number], default: undefined },
+})
+
+const open = ref(false)
+</script>
+
+<style scoped>
+.fc-kebab { display: inline-flex; align-items: center; }
+</style>
diff --git a/frontend/src/components/discovery/TagCard.vue b/frontend/src/components/discovery/TagCard.vue
index db7b3df..81e5376 100644
--- a/frontend/src/components/discovery/TagCard.vue
+++ b/frontend/src/components/discovery/TagCard.vue
@@ -46,34 +46,25 @@
         <v-chip size="x-small" label>{{ card.kind }}</v-chip>
         <div class="fc-tagcard__meta-right">
           <span class="fc-tagcard__count">{{ card.image_count }}</span>
-          <v-menu>
-            <template #activator="{ props: act }">
-              <v-btn
-                class="fc-tagcard__menu"
-                icon="mdi-dots-vertical" size="x-small" variant="text"
-                v-bind="act" @click.stop
-              />
-            </template>
-            <v-list density="compact">
-              <v-list-item
-                v-if="card.kind === 'character'"
-                title="Set fandom…"
-                prepend-icon="mdi-book-open-page-variant"
-                @click="$emit('set-fandom', card)"
-              />
-              <v-list-item
-                title="Merge with…"
-                prepend-icon="mdi-call-merge"
-                @click="$emit('merge-with', card)"
-              />
-              <v-list-item
-                title="Delete tag"
-                prepend-icon="mdi-delete"
-                base-color="error"
-                @click="$emit('delete', card)"
-              />
-            </v-list>
-          </v-menu>
+          <KebabMenu class="fc-tagcard__menu" :label="`Actions for ${card.name}`">
+            <v-list-item
+              v-if="card.kind === 'character'"
+              title="Set fandom…"
+              prepend-icon="mdi-book-open-page-variant"
+              @click="$emit('set-fandom', card)"
+            />
+            <v-list-item
+              title="Merge with…"
+              prepend-icon="mdi-call-merge"
+              @click="$emit('merge-with', card)"
+            />
+            <v-list-item
+              title="Delete tag"
+              prepend-icon="mdi-delete"
+              base-color="error"
+              @click="$emit('delete', card)"
+            />
+          </KebabMenu>
         </div>
       </div>
     </v-card-text>
@@ -82,6 +73,7 @@
 
 <script setup>
 import { ref } from 'vue'
+import KebabMenu from '../common/KebabMenu.vue'
 
 const props = defineProps({ card: { type: Object, required: true } })
 const emit = defineEmits([
diff --git a/frontend/src/components/modal/SuggestionItem.vue b/frontend/src/components/modal/SuggestionItem.vue
index 55464fd..ed0b972 100644
--- a/frontend/src/components/modal/SuggestionItem.vue
+++ b/frontend/src/components/modal/SuggestionItem.vue
@@ -19,46 +19,29 @@
     >
       Accept
     </v-btn>
-    <!-- Operator-flagged 2026-06-04: the kebab still wasn't opening. The
-         prior `#activator` + `v-bind="props"` path never toggled the menu
-         inside this teleported modal, while v-model-driven overlays (the
-         dialogs in this modal) work fine. So drive the menu explicitly:
-         the button toggles `menuOpen` with @click.stop (also shields any
-         parent), and `activator="parent"` anchors the menu for positioning
-         only — `:open-on-click="false"` keeps Vuetify's activator-click out
-         of it, so there's a single, reliable opener. -->
-    <span class="fc-suggestion__menu-wrap">
-      <v-btn
-        class="fc-suggestion__menu"
-        icon="mdi-dots-vertical" size="small"
-        variant="outlined" density="compact"
-        :aria-label="`More actions for ${suggestion.display_name}`"
-        @click.stop="menuOpen = !menuOpen"
-      />
-      <v-menu
-        v-model="menuOpen" activator="parent" :open-on-click="false"
-        :z-index="2400"
-      >
-        <v-list density="compact">
-          <v-list-item @click="$emit('alias', suggestion)">
-            <v-list-item-title>Treat as alias for…</v-list-item-title>
-          </v-list-item>
-          <v-list-item @click="$emit('dismiss', suggestion)">
-            <v-list-item-title>Dismiss for this image</v-list-item-title>
-          </v-list-item>
-        </v-list>
-      </v-menu>
-    </span>
+    <!-- Modal-safe kebab is baked into KebabMenu (this row lives in the
+         teleported image modal — #711). -->
+    <KebabMenu
+      class="fc-suggestion__menu" size="small" variant="outlined"
+      :label="`More actions for ${suggestion.display_name}`"
+    >
+      <v-list-item @click="$emit('alias', suggestion)">
+        <v-list-item-title>Treat as alias for…</v-list-item-title>
+      </v-list-item>
+      <v-list-item @click="$emit('dismiss', suggestion)">
+        <v-list-item-title>Dismiss for this image</v-list-item-title>
+      </v-list-item>
+    </KebabMenu>
   </div>
 </template>
 
 <script setup>
-import { computed, ref } from 'vue'
+import { computed } from 'vue'
+import KebabMenu from '../common/KebabMenu.vue'
 
 const props = defineProps({ suggestion: { type: Object, required: true } })
 defineEmits(['accept', 'alias', 'dismiss'])
 
-const menuOpen = ref(false)
 const scorePct = computed(() => `${Math.round(props.suggestion.score * 100)}%`)
 </script>
 
@@ -102,11 +85,6 @@ const scorePct = computed(() => `${Math.round(props.suggestion.score * 100)}%`)
 .fc-suggestion__accept :deep(.v-btn__content) {
   font-size: 12px; letter-spacing: 0.02em;
 }
-.fc-suggestion__menu-wrap {
-  flex: 0 0 auto;
-  display: inline-flex;
-  align-items: center;
-}
 .fc-suggestion__menu {
   flex: 0 0 auto;
 }
diff --git a/frontend/src/components/modal/TagChip.vue b/frontend/src/components/modal/TagChip.vue
index b6df29d..1dc5699 100644
--- a/frontend/src/components/modal/TagChip.vue
+++ b/frontend/src/components/modal/TagChip.vue
@@ -1,9 +1,4 @@
 <template>
-  <!-- One tag chip + its kebab. The kebab uses the SAME explicit-menu pattern
-       as SuggestionItem (activator="parent" + :open-on-click="false" + a manual
-       v-model), because the #activator / v-bind="props" pattern never toggles a
-       v-menu inside the teleported ImageViewer modal (#711, re-fixed 2026-06-07
-       after the first attempt used the broken pattern). -->
   <span class="fc-tag-chip">
     <v-chip
       size="small" closable
@@ -16,41 +11,28 @@
         :title="tag.fandom_name ? `Fandom: ${tag.fandom_name}` : 'Has a fandom'"
       >→<template v-if="fandomLabel">&nbsp;{{ fandomLabel }}</template></span>
     </v-chip>
-    <span class="fc-tag-chip__menu-wrap">
-      <v-btn
-        class="fc-tag-chip__kebab"
-        icon="mdi-dots-vertical" size="x-small"
-        variant="text" density="comfortable"
-        :aria-label="`More actions for ${tag.name}`"
-        @click.stop="menuOpen = !menuOpen"
-      />
-      <!-- :z-index above the modal's 2000 — the teleported menu otherwise lands
-           BEHIND .fc-viewer and gets blurred by its backdrop-filter (operator
-           saw it ghosted behind the sidebar, 2026-06-07). THIS is what made the
-           kebab look dead the whole time: it opened, just underneath. -->
-      <v-menu v-model="menuOpen" activator="parent" :open-on-click="false" :z-index="2400">
-        <v-list density="compact">
-          <v-list-item @click="$emit('rename', tag)">
-            <v-list-item-title>Rename…</v-list-item-title>
-          </v-list-item>
-          <v-list-item v-if="tag.kind === 'character'" @click="$emit('set-fandom', tag)">
-            <v-list-item-title>Set fandom…</v-list-item-title>
-          </v-list-item>
-        </v-list>
-      </v-menu>
-    </span>
+    <!-- Modal-safe kebab is baked into KebabMenu (this chip lives in the
+         teleported image modal — #711). -->
+    <KebabMenu class="fc-tag-chip__kebab" :label="`More actions for ${tag.name}`">
+      <v-list-item @click="$emit('rename', tag)">
+        <v-list-item-title>Rename…</v-list-item-title>
+      </v-list-item>
+      <v-list-item v-if="tag.kind === 'character'" @click="$emit('set-fandom', tag)">
+        <v-list-item-title>Set fandom…</v-list-item-title>
+      </v-list-item>
+    </KebabMenu>
   </span>
 </template>
 
 <script setup>
-import { computed, ref } from 'vue'
+import { computed } from 'vue'
 import { useTagStore } from '../../stores/tags.js'
+import KebabMenu from '../common/KebabMenu.vue'
 
 const props = defineProps({ tag: { type: Object, required: true } })
 defineEmits(['remove', 'rename', 'set-fandom'])
 
 const store = useTagStore()
-const menuOpen = ref(false)
 
 // Show a character's fandom inline (truncated). Falls back to a bare arrow when
 // only fandom_id is known but the name wasn't resolved (older payloads).
@@ -71,7 +53,6 @@ function iconFor (k) { return KIND_ICONS[k] || 'mdi-tag' }
 
 <style scoped>
 .fc-tag-chip { display: inline-flex; align-items: center; gap: 1px; }
-.fc-tag-chip__menu-wrap { display: inline-flex; align-items: center; }
 .fc-tag-chip__kebab { opacity: 0.7; }
 .fc-tag-chip:hover .fc-tag-chip__kebab { opacity: 1; }
 .fc-tag-chip__fandom { opacity: 0.7; font-size: 0.85em; }
diff --git a/frontend/src/components/settings/BackupRunsTable.vue b/frontend/src/components/settings/BackupRunsTable.vue
index 0d12676..a58447b 100644
--- a/frontend/src/components/settings/BackupRunsTable.vue
+++ b/frontend/src/components/settings/BackupRunsTable.vue
@@ -30,25 +30,20 @@
           <span v-else class="fc-muted">—</span>
         </td>
         <td class="text-right">
-          <v-menu>
-            <template #activator="{ props: act }">
-              <v-btn icon="mdi-dots-vertical" size="x-small" variant="text" v-bind="act" />
-            </template>
-            <v-list density="compact">
-              <v-list-item
-                :title="r.tag ? 'Untag' : 'Tag…'"
-                @click="$emit('tag', r)"
-              />
-              <v-list-item
-                title="Restore…" :disabled="r.status !== 'ok'"
-                @click="$emit('restore', r)"
-              />
-              <v-list-item
-                title="Delete…"
-                @click="$emit('delete', r)"
-              />
-            </v-list>
-          </v-menu>
+          <KebabMenu :label="`Actions for backup ${r.id}`">
+            <v-list-item
+              :title="r.tag ? 'Untag' : 'Tag…'"
+              @click="$emit('tag', r)"
+            />
+            <v-list-item
+              title="Restore…" :disabled="r.status !== 'ok'"
+              @click="$emit('restore', r)"
+            />
+            <v-list-item
+              title="Delete…"
+              @click="$emit('delete', r)"
+            />
+          </KebabMenu>
         </td>
       </tr>
       <tr v-if="!runs.length">
@@ -60,6 +55,7 @@
 
 <script setup>
 import { formatRelative as fmtRelative } from '../../utils/date.js'
+import KebabMenu from '../common/KebabMenu.vue'
 
 defineProps({ runs: { type: Array, default: () => [] } })
 defineEmits(['restore', 'delete', 'tag'])
diff --git a/frontend/src/components/subscriptions/SourceActions.vue b/frontend/src/components/subscriptions/SourceActions.vue
index ae4751c..bdf01df 100644
--- a/frontend/src/components/subscriptions/SourceActions.vue
+++ b/frontend/src/components/subscriptions/SourceActions.vue
@@ -26,40 +26,33 @@
       </v-tooltip>
     </v-btn>
 
-    <v-menu location="bottom end">
-      <template #activator="{ props: menuProps }">
-        <v-btn icon size="small" variant="text" v-bind="menuProps" @click.stop>
-          <v-icon>mdi-dots-vertical</v-icon>
-          <v-tooltip activator="parent" location="top">More actions</v-tooltip>
-        </v-btn>
-      </template>
-      <v-list density="compact" min-width="260">
-        <v-list-item
-          v-if="isPatreon && !running"
-          prepend-icon="mdi-backup-restore"
-          @click="emit('recover', source)"
-        >
-          <v-list-item-title>Recover dropped near-duplicates</v-list-item-title>
-          <v-list-item-subtitle>
-            Re-fetch images previously dropped as near-dups and re-judge them
-            under the current similarity threshold
-          </v-list-item-subtitle>
-        </v-list-item>
-        <v-divider v-if="isPatreon && !running" />
-        <v-list-item
-          base-color="error"
-          prepend-icon="mdi-delete-outline"
-          @click="emit('remove', source)"
-        >
-          <v-list-item-title>Remove source</v-list-item-title>
-        </v-list-item>
-      </v-list>
-    </v-menu>
+    <KebabMenu size="small" :min-width="260" label="More actions">
+      <v-list-item
+        v-if="isPatreon && !running"
+        prepend-icon="mdi-backup-restore"
+        @click="emit('recover', source)"
+      >
+        <v-list-item-title>Recover dropped near-duplicates</v-list-item-title>
+        <v-list-item-subtitle>
+          Re-fetch images previously dropped as near-dups and re-judge them
+          under the current similarity threshold
+        </v-list-item-subtitle>
+      </v-list-item>
+      <v-divider v-if="isPatreon && !running" />
+      <v-list-item
+        base-color="error"
+        prepend-icon="mdi-delete-outline"
+        @click="emit('remove', source)"
+      >
+        <v-list-item-title>Remove source</v-list-item-title>
+      </v-list-item>
+    </KebabMenu>
   </div>
 </template>
 
 <script setup>
 import { computed } from 'vue'
+import KebabMenu from '../common/KebabMenu.vue'
 
 const props = defineProps({
   source: { type: Object, required: true },
diff --git a/frontend/src/views/SeriesManageView.vue b/frontend/src/views/SeriesManageView.vue
index 6f9b36e..35cc619 100644
--- a/frontend/src/views/SeriesManageView.vue
+++ b/frontend/src/views/SeriesManageView.vue
@@ -67,37 +67,29 @@
               @click="openPicker(ch.id)"
             >Add pages</v-btn>
 
-            <v-menu location="bottom end">
-              <template #activator="{ props }">
-                <v-btn
-                  v-bind="props" size="small" variant="text"
-                  icon="mdi-dots-vertical" title="Part actions"
-                />
-              </template>
-              <v-list density="compact">
-                <v-list-item
-                  prepend-icon="mdi-chevron-up" title="Move up"
-                  :disabled="ci === 0"
-                  @click="store.moveChapter(ch.id, -1)"
-                />
-                <v-list-item
-                  prepend-icon="mdi-chevron-down" title="Move down"
-                  :disabled="ci === store.chapters.length - 1"
-                  @click="store.moveChapter(ch.id, 1)"
-                />
-                <v-list-item
-                  prepend-icon="mdi-arrow-collapse-up" title="Merge into previous"
-                  :disabled="ci === 0"
-                  @click="store.mergeChapter(ch.id, store.chapters[ci - 1].id)"
-                />
-                <v-divider />
-                <v-list-item
-                  prepend-icon="mdi-delete-outline" title="Delete part"
-                  base-color="error"
-                  @click="confirmDelete(ch)"
-                />
-              </v-list>
-            </v-menu>
+            <KebabMenu size="small" label="Part actions">
+              <v-list-item
+                prepend-icon="mdi-chevron-up" title="Move up"
+                :disabled="ci === 0"
+                @click="store.moveChapter(ch.id, -1)"
+              />
+              <v-list-item
+                prepend-icon="mdi-chevron-down" title="Move down"
+                :disabled="ci === store.chapters.length - 1"
+                @click="store.moveChapter(ch.id, 1)"
+              />
+              <v-list-item
+                prepend-icon="mdi-arrow-collapse-up" title="Merge into previous"
+                :disabled="ci === 0"
+                @click="store.mergeChapter(ch.id, store.chapters[ci - 1].id)"
+              />
+              <v-divider />
+              <v-list-item
+                prepend-icon="mdi-delete-outline" title="Delete part"
+                base-color="error"
+                @click="confirmDelete(ch)"
+              />
+            </KebabMenu>
           </header>
 
           <div class="fc-part__statedrow">
@@ -230,6 +222,7 @@ import { computed, onMounted, reactive, ref, watch } from 'vue'
 import { useRoute } from 'vue-router'
 import { useSeriesManageStore, moveItem } from '../stores/seriesManage.js'
 import { useInfiniteScroll } from '../composables/useInfiniteScroll.js'
+import KebabMenu from '../components/common/KebabMenu.vue'
 
 const route = useRoute()
 const store = useSeriesManageStore()
diff --git a/frontend/src/views/SeriesView.vue b/frontend/src/views/SeriesView.vue
index d726df3..4c25183 100644
--- a/frontend/src/views/SeriesView.vue
+++ b/frontend/src/views/SeriesView.vue
@@ -60,27 +60,20 @@
               <span v-if="s.has_gap" class="fc-sbcard__gap" title="Has a missing-page gap">
                 <v-icon size="x-small">mdi-alert-outline</v-icon> gap
               </span>
-              <v-menu>
-                <template #activator="{ props: menuProps }">
-                  <v-btn
-                    v-bind="menuProps"
-                    icon="mdi-dots-vertical" size="x-small" variant="flat"
-                    class="fc-sbcard__kebab" :aria-label="`Actions for ${s.name}`"
-                    @click.stop
-                  />
-                </template>
-                <v-list density="compact">
-                  <v-list-item prepend-icon="mdi-pencil" @click.stop="openRename(s)">
-                    <v-list-item-title>Rename</v-list-item-title>
-                  </v-list-item>
-                  <v-list-item
-                    prepend-icon="mdi-delete" base-color="error"
-                    @click.stop="openDelete(s)"
-                  >
-                    <v-list-item-title>Delete</v-list-item-title>
-                  </v-list-item>
-                </v-list>
-              </v-menu>
+              <KebabMenu
+                class="fc-sbcard__kebab" variant="flat"
+                :label="`Actions for ${s.name}`"
+              >
+                <v-list-item prepend-icon="mdi-pencil" @click.stop="openRename(s)">
+                  <v-list-item-title>Rename</v-list-item-title>
+                </v-list-item>
+                <v-list-item
+                  prepend-icon="mdi-delete" base-color="error"
+                  @click.stop="openDelete(s)"
+                >
+                  <v-list-item-title>Delete</v-list-item-title>
+                </v-list-item>
+              </KebabMenu>
             </div>
             <div class="fc-sbcard__body">
               <h3 class="fc-sbcard__name">{{ s.name }}</h3>
@@ -210,6 +203,7 @@ import { useRouter } from 'vue-router'
 import { useSeriesBrowseStore } from '../stores/seriesBrowse.js'
 import { useSeriesSuggestionsStore } from '../stores/seriesSuggestions.js'
 import TagRenameDialog from '../components/modal/TagRenameDialog.vue'
+import KebabMenu from '../components/common/KebabMenu.vue'
 
 const router = useRouter()
 const store = useSeriesBrowseStore()
diff --git a/frontend/test/components/kebabMenu.spec.js b/frontend/test/components/kebabMenu.spec.js
new file mode 100644
index 0000000..5bbd1f2
--- /dev/null
+++ b/frontend/test/components/kebabMenu.spec.js
@@ -0,0 +1,38 @@
+// @vitest-environment happy-dom
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+
+import KebabMenu from '../../src/components/common/KebabMenu.vue'
+
+// Canonical kebab primitive (DRY pattern-consistency sweep). Vuetify components
+// are left unresolved by the test harness, so we assert the wiring the consumers
+// rely on: the trigger's aria-label, the default kebab glyph, and that the
+// consumer's menu items (default slot) are rendered inside the menu.
+function mountKebab (props = {}) {
+  return mount(KebabMenu, {
+    props,
+    slots: {
+      default: '<v-list-item>Rename</v-list-item><v-list-item>Delete</v-list-item>',
+    },
+  })
+}
+
+describe('KebabMenu', () => {
+  it('renders the trigger with the provided aria-label and the slotted items', () => {
+    const w = mountKebab({ label: 'Actions for Foo' })
+    expect(w.text()).toContain('Rename')
+    expect(w.text()).toContain('Delete')
+    expect(w.html()).toContain('Actions for Foo')
+  })
+
+  it('defaults the trigger glyph to the kebab icon', () => {
+    expect(mountKebab().html()).toContain('mdi-dots-vertical')
+  })
+
+  it('passes presentational props through to the trigger/menu', () => {
+    const w = mountKebab({ size: 'small', variant: 'flat', location: 'bottom end' })
+    const html = w.html()
+    expect(html).toContain('small')
+    expect(html).toContain('flat')
+  })
+})

From 4e83b4225a42c95429d6c9ab8adfc94d02ffd1ff Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 22:42:26 -0400
Subject: [PATCH 03/10] refactor(ui): single global .fc-muted token (DRY
 pattern sweep)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The muted-text token was redefined identically in 12 component <style scoped>
blocks. Consolidate to one global utility in styles/app.css; remove the 12
copies. Keeps the explicit on-surface-variant (vellum) token, NOT Vuetify's
opacity-based text-medium-emphasis (per the muted-text-token rule). Behavior-
preserving: every class=fc-muted usage now resolves to the single source.

§8b exhaustiveness caught (and I fixed) my own sed clobbering the new app.css
rule — now exactly one .fc-muted definition exists, zero component-local.
Catalog updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/components/artist/ArtistDangerZone.vue       | 1 -
 frontend/src/components/cleanup/MinDimensionCard.vue      | 1 -
 frontend/src/components/cleanup/SingleColorAuditCard.vue  | 1 -
 frontend/src/components/cleanup/TransparencyAuditCard.vue | 1 -
 frontend/src/components/settings/BackupCard.vue           | 1 -
 frontend/src/components/settings/BackupRunsTable.vue      | 1 -
 frontend/src/components/settings/BrowserExtensionCard.vue | 3 ---
 frontend/src/components/settings/PostMaintenanceCard.vue  | 1 -
 frontend/src/components/settings/QueuesTable.vue          | 1 -
 frontend/src/components/settings/SystemActivityTab.vue    | 1 -
 frontend/src/components/settings/TagMaintenanceCard.vue   | 1 -
 frontend/src/styles/app.css                               | 8 ++++++++
 frontend/src/views/CleanupView.vue                        | 1 -
 13 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/frontend/src/components/artist/ArtistDangerZone.vue b/frontend/src/components/artist/ArtistDangerZone.vue
index 478d785..0de1ced 100644
--- a/frontend/src/components/artist/ArtistDangerZone.vue
+++ b/frontend/src/components/artist/ArtistDangerZone.vue
@@ -91,5 +91,4 @@ async function onConfirm(token) {
   border-color: rgb(var(--v-theme-error));
   border-radius: 8px;
 }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 </style>
diff --git a/frontend/src/components/cleanup/MinDimensionCard.vue b/frontend/src/components/cleanup/MinDimensionCard.vue
index b018c6b..0769fd9 100644
--- a/frontend/src/components/cleanup/MinDimensionCard.vue
+++ b/frontend/src/components/cleanup/MinDimensionCard.vue
@@ -121,5 +121,4 @@ async function onConfirmedDelete(token) {
 
 <style scoped>
 .fc-clean-card { border-radius: 8px; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 </style>
diff --git a/frontend/src/components/cleanup/SingleColorAuditCard.vue b/frontend/src/components/cleanup/SingleColorAuditCard.vue
index dc75e4c..98d10d4 100644
--- a/frontend/src/components/cleanup/SingleColorAuditCard.vue
+++ b/frontend/src/components/cleanup/SingleColorAuditCard.vue
@@ -190,5 +190,4 @@ async function onConfirmedApply(token) {
 
 <style scoped>
 .fc-clean-card { border-radius: 8px; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 </style>
diff --git a/frontend/src/components/cleanup/TransparencyAuditCard.vue b/frontend/src/components/cleanup/TransparencyAuditCard.vue
index 5fb7523..d42a655 100644
--- a/frontend/src/components/cleanup/TransparencyAuditCard.vue
+++ b/frontend/src/components/cleanup/TransparencyAuditCard.vue
@@ -173,5 +173,4 @@ async function onConfirmedApply(token) {
 
 <style scoped>
 .fc-clean-card { border-radius: 8px; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 </style>
diff --git a/frontend/src/components/settings/BackupCard.vue b/frontend/src/components/settings/BackupCard.vue
index d83fb51..f169fae 100644
--- a/frontend/src/components/settings/BackupCard.vue
+++ b/frontend/src/components/settings/BackupCard.vue
@@ -192,7 +192,6 @@ async function onConfirmSubmit(token) {
 
 <style scoped>
 .fc-backup-card { border-radius: 8px; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 .fc-section-title {
   font-family: 'Fraunces', Georgia, serif;
   font-size: 16px; font-weight: 500;
diff --git a/frontend/src/components/settings/BackupRunsTable.vue b/frontend/src/components/settings/BackupRunsTable.vue
index a58447b..14b4e5c 100644
--- a/frontend/src/components/settings/BackupRunsTable.vue
+++ b/frontend/src/components/settings/BackupRunsTable.vue
@@ -97,5 +97,4 @@ function formatRelative(iso) {
 <style scoped>
 .fc-backup-table { background: transparent; }
 .fc-tabular { font-variant-numeric: tabular-nums; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 </style>
diff --git a/frontend/src/components/settings/BrowserExtensionCard.vue b/frontend/src/components/settings/BrowserExtensionCard.vue
index b3d7a41..0fcfc52 100644
--- a/frontend/src/components/settings/BrowserExtensionCard.vue
+++ b/frontend/src/components/settings/BrowserExtensionCard.vue
@@ -187,7 +187,4 @@ async function copy(text, label) {
 .fc-ext-install {
   display: flex; flex-wrap: wrap; gap: 8px;
 }
-.fc-muted {
-  color: rgb(var(--v-theme-on-surface-variant));
-}
 </style>
diff --git a/frontend/src/components/settings/PostMaintenanceCard.vue b/frontend/src/components/settings/PostMaintenanceCard.vue
index c49a3d9..8c41f11 100644
--- a/frontend/src/components/settings/PostMaintenanceCard.vue
+++ b/frontend/src/components/settings/PostMaintenanceCard.vue
@@ -94,7 +94,6 @@ async function onCommit() {
 
 <style scoped>
 .fc-post-maint { border-radius: 8px; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 .fc-name-grid {
   display: flex; flex-wrap: wrap; gap: 4px 8px;
   max-height: 200px; overflow-y: auto;
diff --git a/frontend/src/components/settings/QueuesTable.vue b/frontend/src/components/settings/QueuesTable.vue
index b326101..6ccc372 100644
--- a/frontend/src/components/settings/QueuesTable.vue
+++ b/frontend/src/components/settings/QueuesTable.vue
@@ -101,7 +101,6 @@ function recentErr(name) { return recentByQueue.value[name]?.err || 0 }
 .fc-ok { color: rgb(var(--v-theme-success, 76 175 80)); }
 .fc-err { color: rgb(var(--v-theme-error, 220 80 80)); }
 .fc-warn { color: rgb(var(--v-theme-warning, 255 179 0)); font-weight: 500; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 .fc-sep {
   margin: 0 4px;
   color: rgb(var(--v-theme-on-surface-variant));
diff --git a/frontend/src/components/settings/SystemActivityTab.vue b/frontend/src/components/settings/SystemActivityTab.vue
index ff2f7a7..a4690f9 100644
--- a/frontend/src/components/settings/SystemActivityTab.vue
+++ b/frontend/src/components/settings/SystemActivityTab.vue
@@ -305,5 +305,4 @@ function formatRelative(iso) {
   cursor: pointer;
 }
 .fc-err-link:hover { text-decoration: underline; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 </style>
diff --git a/frontend/src/components/settings/TagMaintenanceCard.vue b/frontend/src/components/settings/TagMaintenanceCard.vue
index 2122c58..46e2f8f 100644
--- a/frontend/src/components/settings/TagMaintenanceCard.vue
+++ b/frontend/src/components/settings/TagMaintenanceCard.vue
@@ -304,7 +304,6 @@ async function onNormCommit() {
 
 <style scoped>
 .fc-tag-maint { border-radius: 8px; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 .fc-name-grid {
   display: flex; flex-wrap: wrap; gap: 4px 8px;
   max-height: 200px; overflow-y: auto;
diff --git a/frontend/src/styles/app.css b/frontend/src/styles/app.css
index fa32dd1..8162633 100644
--- a/frontend/src/styles/app.css
+++ b/frontend/src/styles/app.css
@@ -31,3 +31,11 @@
   border: 1px solid rgb(var(--v-theme-on-surface-variant) / 0.25);
   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.4);
 }
+
+/* Canonical muted/secondary text token (DRY pattern sweep 2026-06-09).
+   Was redefined identically in 12 component <style scoped> blocks; now one
+   global utility. Muted text uses the explicit on-surface-variant (vellum)
+   token, NOT opacity — Vuetify's text-medium-emphasis is opacity-based and is
+   deliberately not used here. `.fc-muted` is a custom class Vuetify never
+   emits, so no specificity/reorder fight — no !important needed. */
+.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
diff --git a/frontend/src/views/CleanupView.vue b/frontend/src/views/CleanupView.vue
index 9f56bda..f1badb6 100644
--- a/frontend/src/views/CleanupView.vue
+++ b/frontend/src/views/CleanupView.vue
@@ -29,5 +29,4 @@ import TagMaintenanceCard from '../components/settings/TagMaintenanceCard.vue'
 
 <style scoped>
 .fc-cleanup { max-width: 900px; }
-.fc-muted { color: rgb(var(--v-theme-on-surface-variant)); }
 </style>

From 409bbd43dbde6936b9fe4c32c1674b0368a6d930 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 23:05:01 -0400
Subject: [PATCH 04/10] feat(series): rename a series from the management view
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The management view showed the series name but had no way to change it post-
creation (rename was only on the browse-card kebab). Add a pencil next to the
title that opens TagRenameDialog (reuses the canonical rename → PATCH
/api/tags/<id> with its collision→merge flow, since a series IS a
Tag(kind=series)); the new name reflects in place. Operator-asked 2026-06-09.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/views/SeriesManageView.vue | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/frontend/src/views/SeriesManageView.vue b/frontend/src/views/SeriesManageView.vue
index 35cc619..ad9d4e2 100644
--- a/frontend/src/views/SeriesManageView.vue
+++ b/frontend/src/views/SeriesManageView.vue
@@ -2,6 +2,12 @@
   <v-container fluid class="pt-2 pb-10 fc-series">
     <div class="fc-series__head">
       <span class="fc-series__name">{{ store.series?.name || 'Series' }}</span>
+      <v-btn
+        v-if="store.series"
+        icon="mdi-pencil" size="x-small" variant="text"
+        :aria-label="`Rename ${store.series.name}`"
+        @click="renameOpen = true"
+      />
       <span class="fc-series__count">
         {{ store.chapters.length }} part(s) · {{ store.pageCount }} page(s)
       </span>
@@ -214,6 +220,14 @@
         <div ref="sentinel" class="fc-picker__sentinel" />
       </div>
     </v-navigation-drawer>
+
+    <v-dialog v-model="renameOpen" max-width="420">
+      <TagRenameDialog
+        v-if="store.series"
+        :tag="{ id: store.tagId, name: store.series.name, kind: 'series' }"
+        @renamed="onRenamed" @cancel="renameOpen = false"
+      />
+    </v-dialog>
   </v-container>
 </template>
 
@@ -223,6 +237,7 @@ import { useRoute } from 'vue-router'
 import { useSeriesManageStore, moveItem } from '../stores/seriesManage.js'
 import { useInfiniteScroll } from '../composables/useInfiniteScroll.js'
 import KebabMenu from '../components/common/KebabMenu.vue'
+import TagRenameDialog from '../components/modal/TagRenameDialog.vue'
 
 const route = useRoute()
 const store = useSeriesManageStore()
@@ -231,6 +246,14 @@ const drag = ref(null)            // { chapterId, idx }
 const titleDraft = reactive({})   // chapterId -> draft title
 const partDraft = reactive({})    // chapterId -> draft stated_part (string)
 const pickerOpen = ref(false)
+const renameOpen = ref(false)
+
+// A series IS a Tag(kind=series); TagRenameDialog PATCHes /api/tags/<id> and
+// handles the same-name collision→merge flow. Reflect the new name in place.
+function onRenamed(updated) {
+  renameOpen.value = false
+  if (store.series && updated?.name) store.series.name = updated.name
+}
 
 // Keep local drafts in sync with loaded chapters. Edits commit on blur/Enter,
 // which refreshes and resets the draft to the saved value.

From 4854d74c5acdf7ead3aae1d54c4ea92778696195 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 23:08:15 -0400
Subject: [PATCH 05/10] refactor(ui): SampleNameGrid primitive for
 maintenance-card previews (DRY pattern sweep)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The preview sample-name grid (scrollable monospace chip grid) was hand-rolled
5 times with verbatim-duplicated markup + CSS — TagMaintenanceCard (×4) and
PostMaintenanceCard. Consolidate to <SampleNameGrid> (components/common): pass
:names for the plain case, default slot for the normalize from→to chips
(styled via :slotted .fc-name). Removed the duplicated .fc-name-grid/.fc-name
CSS from both cards.

Over-DRY guard: only the verbatim-duplicated grid is merged — each card's
preview/commit logic and result-count lines genuinely differ and stay put;
MinDimensionCard's typed-token confirm is a separate variant, untouched.
§8b: fc-name-grid now lives only in SampleNameGrid. Catalog updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/common/SampleNameGrid.vue  | 32 ++++++++++++++
 .../settings/PostMaintenanceCard.vue          | 21 +++------
 .../settings/TagMaintenanceCard.vue           | 43 +++++++------------
 3 files changed, 52 insertions(+), 44 deletions(-)
 create mode 100644 frontend/src/components/common/SampleNameGrid.vue

diff --git a/frontend/src/components/common/SampleNameGrid.vue b/frontend/src/components/common/SampleNameGrid.vue
new file mode 100644
index 0000000..4488e55
--- /dev/null
+++ b/frontend/src/components/common/SampleNameGrid.vue
@@ -0,0 +1,32 @@
+<template>
+  <!-- Scrollable grid of monospace name chips — the preview "here's a sample of
+       what will change" surface shared by the maintenance cards (DRY pattern
+       sweep 2026-06-09). Pass `names` for the common case; use the default slot
+       to render custom chips (style them `.fc-name` and they inherit the look
+       via :slotted). The caller keeps its own v-if for the empty case. -->
+  <div class="fc-name-grid">
+    <slot>
+      <span v-for="(n, i) in names" :key="i" class="fc-name">{{ n }}</span>
+    </slot>
+  </div>
+</template>
+
+<script setup>
+defineProps({
+  names: { type: Array, default: () => [] },
+})
+</script>
+
+<style scoped>
+.fc-name-grid {
+  display: flex; flex-wrap: wrap; gap: 4px 8px;
+  max-height: 200px; overflow-y: auto;
+  padding: 8px; border-radius: 4px;
+  background: rgb(var(--v-theme-surface-light));
+}
+.fc-name, :slotted(.fc-name) {
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 12px;
+  color: rgb(var(--v-theme-on-surface-variant));
+}
+</style>
diff --git a/frontend/src/components/settings/PostMaintenanceCard.vue b/frontend/src/components/settings/PostMaintenanceCard.vue
index 8c41f11..7e2c348 100644
--- a/frontend/src/components/settings/PostMaintenanceCard.vue
+++ b/frontend/src/components/settings/PostMaintenanceCard.vue
@@ -36,11 +36,10 @@
             Nothing to clean up.
           </span>
         </p>
-        <div v-if="preview.sample_names?.length" class="fc-name-grid mb-3">
-          <span v-for="(n, i) in preview.sample_names" :key="i" class="fc-name">
-            {{ n }}
-          </span>
-        </div>
+        <SampleNameGrid
+          v-if="preview.sample_names?.length"
+          :names="preview.sample_names" class="mb-3"
+        />
         <v-btn
           color="error" variant="flat" rounded="pill"
           prepend-icon="mdi-delete-sweep"
@@ -61,6 +60,7 @@
 import { ref } from 'vue'
 
 import { useAdminStore } from '../../stores/admin.js'
+import SampleNameGrid from '../common/SampleNameGrid.vue'
 
 const store = useAdminStore()
 const preview = ref(null)
@@ -94,15 +94,4 @@ async function onCommit() {
 
 <style scoped>
 .fc-post-maint { border-radius: 8px; }
-.fc-name-grid {
-  display: flex; flex-wrap: wrap; gap: 4px 8px;
-  max-height: 200px; overflow-y: auto;
-  padding: 8px; border-radius: 4px;
-  background: rgb(var(--v-theme-surface-light));
-}
-.fc-name {
-  font-family: 'JetBrains Mono', monospace;
-  font-size: 12px;
-  color: rgb(var(--v-theme-on-surface-variant));
-}
 </style>
diff --git a/frontend/src/components/settings/TagMaintenanceCard.vue b/frontend/src/components/settings/TagMaintenanceCard.vue
index 46e2f8f..dca22a6 100644
--- a/frontend/src/components/settings/TagMaintenanceCard.vue
+++ b/frontend/src/components/settings/TagMaintenanceCard.vue
@@ -31,11 +31,10 @@
             Showing first 50 names.
           </span>
         </p>
-        <div v-if="preview.sample_names?.length" class="fc-name-grid mb-3">
-          <span v-for="n in preview.sample_names" :key="n" class="fc-name">
-            {{ n }}
-          </span>
-        </div>
+        <SampleNameGrid
+          v-if="preview.sample_names?.length"
+          :names="preview.sample_names" class="mb-3"
+        />
         <v-btn
           color="error" variant="flat" rounded="pill"
           prepend-icon="mdi-delete-sweep"
@@ -76,11 +75,10 @@
             {{ 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">
-            {{ n }}
-          </span>
-        </div>
+        <SampleNameGrid
+          v-if="kindPreview.sample_names?.length"
+          :names="kindPreview.sample_names" class="mb-3"
+        />
         <v-btn
           color="error" variant="flat" rounded="pill"
           prepend-icon="mdi-delete-sweep"
@@ -122,11 +120,10 @@
           across <strong>{{ resetPreview.applications }}</strong> image
           application(s).
         </p>
-        <div v-if="resetPreview.sample_names?.length" class="fc-name-grid mb-3">
-          <span v-for="n in resetPreview.sample_names" :key="n" class="fc-name">
-            {{ n }}
-          </span>
-        </div>
+        <SampleNameGrid
+          v-if="resetPreview.sample_names?.length"
+          :names="resetPreview.sample_names" class="mb-3"
+        />
         <v-btn
           color="error" variant="flat" rounded="pill"
           prepend-icon="mdi-delete-alert"
@@ -170,14 +167,14 @@
           <strong>{{ normPreview.collisions }}</strong> collision(s) merging
           <strong>{{ normPreview.tags_to_merge }}</strong> tag(s) away.
         </p>
-        <div v-if="normPreview.sample?.length" class="fc-name-grid mb-3">
+        <SampleNameGrid v-if="normPreview.sample?.length" class="mb-3">
           <span
             v-for="s in normPreview.sample" :key="s.to + s.kind"
             class="fc-name"
           >
             <template v-if="s.merge">{{ s.from.join(' + ') }} → </template>{{ s.to }}
           </span>
-        </div>
+        </SampleNameGrid>
         <v-btn
           color="error" variant="flat" rounded="pill"
           prepend-icon="mdi-format-letter-case"
@@ -198,6 +195,7 @@
 import { ref } from 'vue'
 
 import { useAdminStore } from '../../stores/admin.js'
+import SampleNameGrid from '../common/SampleNameGrid.vue'
 
 const store = useAdminStore()
 const preview = ref(null)
@@ -304,15 +302,4 @@ async function onNormCommit() {
 
 <style scoped>
 .fc-tag-maint { border-radius: 8px; }
-.fc-name-grid {
-  display: flex; flex-wrap: wrap; gap: 4px 8px;
-  max-height: 200px; overflow-y: auto;
-  padding: 8px; border-radius: 4px;
-  background: rgb(var(--v-theme-surface-light));
-}
-.fc-name {
-  font-family: 'JetBrains Mono', monospace;
-  font-size: 12px;
-  color: rgb(var(--v-theme-on-surface-variant));
-}
 </style>

From 9deebfa1339a864336e204adf9f5993fc2847f9c Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 23:22:01 -0400
Subject: [PATCH 06/10] refactor(ui): CardHeading primitive for icon+title
 card/dialog headings (DRY pattern sweep)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The icon+title v-card-title heading (d-flex align-center + gap + <v-icon size=small> +
<span>) was hand-rolled identically in 13 cards/dialogs (15 heading instances).
Consolidate to <CardHeading icon title> (components/common) with an iconColor
prop (error headings) and a default slot for trailing content (spacer+actions,
inline status chip). Adopted everywhere the pattern appears — all-or-nothing per
the hardened DRY process.

Over-DRY guard: plain text-only <v-card-title> one-liners are NOT this pattern
and stay; DownloadDetailModal leads with a status CHIP (not an icon), a different
concept, left alone. §8b: the only remaining d-flex align-center v-card-title is
that intentional variant. Catalog updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../components/artist/ArtistDangerZone.vue    |  6 ++---
 .../components/cleanup/MinDimensionCard.vue   |  6 ++---
 .../cleanup/SingleColorAuditCard.vue          |  6 ++---
 .../cleanup/TransparencyAuditCard.vue         |  6 ++---
 .../src/components/common/CardHeading.vue     | 25 +++++++++++++++++++
 .../components/common/ErrorDetailModal.vue    | 10 +++++---
 .../src/components/settings/BackupCard.vue    |  6 ++---
 .../settings/BrowserExtensionCard.vue         |  7 +++---
 .../components/settings/ImportTaskList.vue    |  6 ++---
 .../settings/PostMaintenanceCard.vue          |  6 ++---
 .../settings/SystemActivitySummary.vue        |  7 +++---
 .../components/settings/SystemActivityTab.vue | 19 ++++++--------
 .../settings/TagMaintenanceCard.vue           |  6 ++---
 .../subscriptions/PreviewDialog.vue           |  9 ++++---
 14 files changed, 66 insertions(+), 59 deletions(-)
 create mode 100644 frontend/src/components/common/CardHeading.vue

diff --git a/frontend/src/components/artist/ArtistDangerZone.vue b/frontend/src/components/artist/ArtistDangerZone.vue
index 0de1ced..275c4a4 100644
--- a/frontend/src/components/artist/ArtistDangerZone.vue
+++ b/frontend/src/components/artist/ArtistDangerZone.vue
@@ -1,9 +1,6 @@
 <template>
   <v-card class="fc-danger-zone mt-8" variant="outlined">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-alert-octagon" color="error" size="small" />
-      <span>Danger zone</span>
-    </v-card-title>
+    <CardHeading icon="mdi-alert-octagon" icon-color="error" title="Danger zone" />
     <v-card-text>
       <p class="text-body-2 fc-muted mb-4">
         Cascade-delete this artist and every image, source, post, and
@@ -37,6 +34,7 @@ import { useRouter } from 'vue-router'
 
 import DestructiveConfirmModal from '../modal/DestructiveConfirmModal.vue'
 import { useAdminStore } from '../../stores/admin.js'
+import CardHeading from '../common/CardHeading.vue'
 
 const props = defineProps({
   slug: { type: String, required: true },
diff --git a/frontend/src/components/cleanup/MinDimensionCard.vue b/frontend/src/components/cleanup/MinDimensionCard.vue
index 0769fd9..632a6e2 100644
--- a/frontend/src/components/cleanup/MinDimensionCard.vue
+++ b/frontend/src/components/cleanup/MinDimensionCard.vue
@@ -1,9 +1,6 @@
 <template>
   <v-card class="fc-clean-card">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-image-size-select-small" size="small" />
-      <span>Minimum dimensions</span>
-    </v-card-title>
+    <CardHeading icon="mdi-image-size-select-small" title="Minimum dimensions" />
     <v-card-text>
       <p class="fc-muted text-body-2 mb-3">
         Find and delete images smaller than the threshold. Mirrors the
@@ -67,6 +64,7 @@ import { onMounted, ref } from 'vue'
 
 import DestructiveConfirmModal from '../modal/DestructiveConfirmModal.vue'
 import { useCleanupStore } from '../../stores/cleanup.js'
+import CardHeading from '../common/CardHeading.vue'
 
 // Backend's preview response hands the full Tier-C confirm token back
 // as `confirm_token` (e.g. `delete-min-dim-1a2b3c4d`); passed straight
diff --git a/frontend/src/components/cleanup/SingleColorAuditCard.vue b/frontend/src/components/cleanup/SingleColorAuditCard.vue
index 98d10d4..31467cc 100644
--- a/frontend/src/components/cleanup/SingleColorAuditCard.vue
+++ b/frontend/src/components/cleanup/SingleColorAuditCard.vue
@@ -1,9 +1,6 @@
 <template>
   <v-card class="fc-clean-card">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-palette-swatch" size="small" />
-      <span>Single-color audit</span>
-    </v-card-title>
+    <CardHeading icon="mdi-palette-swatch" title="Single-color audit" />
     <v-card-text>
       <p class="fc-muted text-body-2 mb-3">
         Scan library for images dominated by one color within the
@@ -97,6 +94,7 @@ import { toast } from '../../utils/toast.js'
 import { onMounted, onUnmounted, ref } from 'vue'
 
 import DestructiveConfirmModal from '../modal/DestructiveConfirmModal.vue'
+import CardHeading from '../common/CardHeading.vue'
 import { useCleanupStore } from '../../stores/cleanup.js'
 
 const store = useCleanupStore()
diff --git a/frontend/src/components/cleanup/TransparencyAuditCard.vue b/frontend/src/components/cleanup/TransparencyAuditCard.vue
index d42a655..7ff5dd0 100644
--- a/frontend/src/components/cleanup/TransparencyAuditCard.vue
+++ b/frontend/src/components/cleanup/TransparencyAuditCard.vue
@@ -1,9 +1,6 @@
 <template>
   <v-card class="fc-clean-card">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-checkerboard" size="small" />
-      <span>Transparency audit</span>
-    </v-card-title>
+    <CardHeading icon="mdi-checkerboard" title="Transparency audit" />
     <v-card-text>
       <p class="fc-muted text-body-2 mb-3">
         Scan library for images whose transparent-pixel fraction exceeds
@@ -84,6 +81,7 @@ import { toast } from '../../utils/toast.js'
 import { onMounted, onUnmounted, ref } from 'vue'
 
 import DestructiveConfirmModal from '../modal/DestructiveConfirmModal.vue'
+import CardHeading from '../common/CardHeading.vue'
 import { useCleanupStore } from '../../stores/cleanup.js'
 
 const store = useCleanupStore()
diff --git a/frontend/src/components/common/CardHeading.vue b/frontend/src/components/common/CardHeading.vue
new file mode 100644
index 0000000..d574385
--- /dev/null
+++ b/frontend/src/components/common/CardHeading.vue
@@ -0,0 +1,25 @@
+<template>
+  <!-- Canonical card/dialog heading: an optional leading icon + the title, with
+       a default slot for trailing content (a v-spacer + actions, or an inline
+       status chip). The icon+title v-card-title row was hand-rolled identically
+       in 14 cards/dialogs (DRY pattern sweep 2026-06-09). Plain text-only
+       v-card-titles are NOT this pattern and keep using <v-card-title> directly. -->
+  <v-card-title class="d-flex align-center fc-card-heading">
+    <v-icon v-if="icon" :icon="icon" :color="iconColor || undefined" size="small" />
+    <span>{{ title }}</span>
+    <slot />
+  </v-card-title>
+</template>
+
+<script setup>
+defineProps({
+  icon: { type: String, default: '' },
+  title: { type: String, default: '' },
+  // e.g. 'error' for danger/error headings; '' keeps the default text color.
+  iconColor: { type: String, default: '' },
+})
+</script>
+
+<style scoped>
+.fc-card-heading { gap: 10px; }
+</style>
diff --git a/frontend/src/components/common/ErrorDetailModal.vue b/frontend/src/components/common/ErrorDetailModal.vue
index 6c378b3..1fd8151 100644
--- a/frontend/src/components/common/ErrorDetailModal.vue
+++ b/frontend/src/components/common/ErrorDetailModal.vue
@@ -2,14 +2,15 @@
   <v-dialog :model-value="modelValue" max-width="900"
             @update:model-value="$emit('update:modelValue', $event)">
     <v-card>
-      <v-card-title class="d-flex align-center" style="gap: 12px;">
-        <v-icon icon="mdi-alert-circle-outline" color="error" />
-        <span>{{ displayTitle }}</span>
+      <CardHeading
+        icon="mdi-alert-circle-outline" icon-color="error"
+        :title="displayTitle"
+      >
         <v-spacer />
         <v-btn icon variant="text" size="small" @click="close">
           <v-icon>mdi-close</v-icon>
         </v-btn>
-      </v-card-title>
+      </CardHeading>
       <v-card-text>
         <dl v-if="contextRows.length" class="fc-err-context">
           <template v-for="(row, idx) in contextRows" :key="idx">
@@ -37,6 +38,7 @@ import { toast } from '../../utils/toast.js'
 import { computed, ref, watch } from 'vue'
 
 import { copyText } from '../../utils/clipboard.js'
+import CardHeading from './CardHeading.vue'
 
 const props = defineProps({
   modelValue: { type: Boolean, default: false },
diff --git a/frontend/src/components/settings/BackupCard.vue b/frontend/src/components/settings/BackupCard.vue
index f169fae..079a243 100644
--- a/frontend/src/components/settings/BackupCard.vue
+++ b/frontend/src/components/settings/BackupCard.vue
@@ -1,9 +1,6 @@
 <template>
   <v-card class="fc-backup-card">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-database-export" size="small" />
-      <span>Backups</span>
-    </v-card-title>
+    <CardHeading icon="mdi-database-export" title="Backups" />
     <v-card-text>
       <p class="fc-muted text-body-2 mb-4">
         pg_dump for the database (fast, nightly-schedulable);
@@ -101,6 +98,7 @@ import { computed, onMounted, onUnmounted, ref } from 'vue'
 
 import { useBackupStore } from '../../stores/backup.js'
 import BackupConfirmModal from '../modal/DestructiveConfirmModal.vue'
+import CardHeading from '../common/CardHeading.vue'
 import BackupRunsTable from './BackupRunsTable.vue'
 
 const store = useBackupStore()
diff --git a/frontend/src/components/settings/BrowserExtensionCard.vue b/frontend/src/components/settings/BrowserExtensionCard.vue
index 0fcfc52..0424975 100644
--- a/frontend/src/components/settings/BrowserExtensionCard.vue
+++ b/frontend/src/components/settings/BrowserExtensionCard.vue
@@ -1,12 +1,10 @@
 <template>
   <v-card class="fc-ext-card">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-puzzle" size="small" />
-      <span>Browser extension</span>
+    <CardHeading icon="mdi-puzzle" title="Browser extension">
       <span v-if="manifest?.installed" class="text-caption fc-muted">
         · Firefox · v{{ manifest.version }}
       </span>
-    </v-card-title>
+    </CardHeading>
 
     <v-card-text>
       <p class="fc-muted text-body-2">
@@ -112,6 +110,7 @@ import { toast } from '../../utils/toast.js'
 import { computed, onMounted, ref } from 'vue'
 import { useApi } from '../../composables/useApi.js'
 import { copyText } from '../../utils/clipboard.js'
+import CardHeading from '../common/CardHeading.vue'
 
 const api = useApi()
 
diff --git a/frontend/src/components/settings/ImportTaskList.vue b/frontend/src/components/settings/ImportTaskList.vue
index a3c78e2..2ad717e 100644
--- a/frontend/src/components/settings/ImportTaskList.vue
+++ b/frontend/src/components/settings/ImportTaskList.vue
@@ -1,7 +1,6 @@
 <template>
   <v-card>
-    <v-card-title class="d-flex align-center" style="gap: 12px;">
-      <span>Recent import tasks</span>
+    <CardHeading title="Recent import tasks">
       <v-spacer />
       <v-select
         v-model="statusFilter" :items="statusOptions" density="compact"
@@ -29,7 +28,7 @@
       >
         Clear completed…
       </v-btn>
-    </v-card-title>
+    </CardHeading>
     <v-data-table-virtual
       :headers="headers" :items="store.tasks" :loading="store.tasksLoading"
       height="480" density="compact" no-data-text="No tasks yet — trigger a scan above."
@@ -129,6 +128,7 @@ import { toast } from '../../utils/toast.js'
 import { computed, ref } from 'vue'
 import { useImportStore } from '../../stores/import.js'
 import ErrorDetailModal from '../common/ErrorDetailModal.vue'
+import CardHeading from '../common/CardHeading.vue'
 
 const store = useImportStore()
 const statusFilter = ref(null)
diff --git a/frontend/src/components/settings/PostMaintenanceCard.vue b/frontend/src/components/settings/PostMaintenanceCard.vue
index 7e2c348..71b07cd 100644
--- a/frontend/src/components/settings/PostMaintenanceCard.vue
+++ b/frontend/src/components/settings/PostMaintenanceCard.vue
@@ -1,9 +1,6 @@
 <template>
   <v-card class="fc-post-maint">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-post-outline" size="small" />
-      <span>Post maintenance</span>
-    </v-card-title>
+    <CardHeading icon="mdi-post-outline" title="Post maintenance" />
     <v-card-text>
       <p class="fc-muted text-body-2 mb-4">
         Remove <strong>bare posts</strong> — post rows with no images (neither
@@ -61,6 +58,7 @@ import { ref } from 'vue'
 
 import { useAdminStore } from '../../stores/admin.js'
 import SampleNameGrid from '../common/SampleNameGrid.vue'
+import CardHeading from '../common/CardHeading.vue'
 
 const store = useAdminStore()
 const preview = ref(null)
diff --git a/frontend/src/components/settings/SystemActivitySummary.vue b/frontend/src/components/settings/SystemActivitySummary.vue
index 354f94f..baa62a5 100644
--- a/frontend/src/components/settings/SystemActivitySummary.vue
+++ b/frontend/src/components/settings/SystemActivitySummary.vue
@@ -1,8 +1,6 @@
 <template>
   <v-card class="fc-activity-summary">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-pulse" size="small" />
-      <span>System activity (last min)</span>
+    <CardHeading icon="mdi-pulse" title="System activity (last min)">
       <v-spacer />
       <v-btn
         variant="text" size="small" rounded="pill"
@@ -11,7 +9,7 @@
         View activity
         <v-icon end size="small">mdi-arrow-right</v-icon>
       </v-btn>
-    </v-card-title>
+    </CardHeading>
 
     <v-card-text>
       <v-alert
@@ -36,6 +34,7 @@ import { onMounted, onUnmounted } from 'vue'
 
 import { useSystemActivityStore } from '../../stores/systemActivity.js'
 import QueuesTable from './QueuesTable.vue'
+import CardHeading from '../common/CardHeading.vue'
 
 defineEmits(['open-activity'])
 
diff --git a/frontend/src/components/settings/SystemActivityTab.vue b/frontend/src/components/settings/SystemActivityTab.vue
index a4690f9..65fd7b7 100644
--- a/frontend/src/components/settings/SystemActivityTab.vue
+++ b/frontend/src/components/settings/SystemActivityTab.vue
@@ -2,14 +2,12 @@
   <div class="fc-activity">
     <!-- Queues + workers pane -->
     <v-card class="mb-4">
-      <v-card-title class="d-flex align-center" style="gap: 10px;">
-        <v-icon icon="mdi-pulse" size="small" />
-        <span>Queues + workers</span>
+      <CardHeading icon="mdi-pulse" title="Queues + workers">
         <v-spacer />
         <span class="text-caption fc-muted">
           updated {{ formatRelative(store.queues?.fetched_at) }}
         </span>
-      </v-card-title>
+      </CardHeading>
       <v-card-text>
         <QueuesTable
           :queues="store.queues"
@@ -21,14 +19,12 @@
 
     <!-- Recent failures pane -->
     <v-card class="mb-4">
-      <v-card-title class="d-flex align-center" style="gap: 10px;">
-        <v-icon icon="mdi-alert-circle-outline" size="small" />
-        <span>Recent failures (last 24h)</span>
+      <CardHeading icon="mdi-alert-circle-outline" title="Recent failures (last 24h)">
         <v-spacer />
         <span class="text-caption fc-muted">
           {{ failureCount }} failures
         </span>
-      </v-card-title>
+      </CardHeading>
       <v-card-text>
         <div v-if="errorTypes.length" class="mb-3 fc-pills">
           <v-chip
@@ -79,9 +75,7 @@
 
     <!-- All activity pane -->
     <v-card>
-      <v-card-title class="d-flex align-center" style="gap: 10px;">
-        <v-icon icon="mdi-format-list-bulleted" size="small" />
-        <span>All recent activity</span>
+      <CardHeading icon="mdi-format-list-bulleted" title="All recent activity">
         <v-spacer />
         <v-select
           v-model="filterQueue"
@@ -102,7 +96,7 @@
           <v-icon start size="small">mdi-refresh</v-icon>
           Refresh
         </v-btn>
-      </v-card-title>
+      </CardHeading>
       <v-card-text>
         <v-table density="compact">
           <thead>
@@ -157,6 +151,7 @@ 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'
+import CardHeading from '../common/CardHeading.vue'
 
 // Click-to-open modal for full error text. Replaces the unusable
 // :title="..." tooltip (operator-flagged 2026-05-26: SQLAlchemy
diff --git a/frontend/src/components/settings/TagMaintenanceCard.vue b/frontend/src/components/settings/TagMaintenanceCard.vue
index dca22a6..233c2d4 100644
--- a/frontend/src/components/settings/TagMaintenanceCard.vue
+++ b/frontend/src/components/settings/TagMaintenanceCard.vue
@@ -1,9 +1,6 @@
 <template>
   <v-card class="fc-tag-maint">
-    <v-card-title class="d-flex align-center" style="gap: 10px;">
-      <v-icon icon="mdi-tag-remove" size="small" />
-      <span>Tag maintenance</span>
-    </v-card-title>
+    <CardHeading icon="mdi-tag-remove" title="Tag maintenance" />
     <v-card-text>
       <p class="fc-muted text-body-2 mb-4">
         Remove tags with zero image associations and zero series-page
@@ -196,6 +193,7 @@ import { ref } from 'vue'
 
 import { useAdminStore } from '../../stores/admin.js'
 import SampleNameGrid from '../common/SampleNameGrid.vue'
+import CardHeading from '../common/CardHeading.vue'
 
 const store = useAdminStore()
 const preview = ref(null)
diff --git a/frontend/src/components/subscriptions/PreviewDialog.vue b/frontend/src/components/subscriptions/PreviewDialog.vue
index 7639526..0dac268 100644
--- a/frontend/src/components/subscriptions/PreviewDialog.vue
+++ b/frontend/src/components/subscriptions/PreviewDialog.vue
@@ -6,10 +6,10 @@
     @update:model-value="$emit('update:modelValue', $event)"
   >
     <v-card v-if="source">
-      <v-card-title class="d-flex align-center">
-        <v-icon class="mr-2">mdi-eye-outline</v-icon>
-        Preview · {{ source.artist_name }}
-      </v-card-title>
+      <CardHeading
+        icon="mdi-eye-outline"
+        :title="`Preview · ${source.artist_name}`"
+      />
       <v-card-subtitle class="fc-preview__url">{{ source.url }}</v-card-subtitle>
 
       <v-card-text>
@@ -70,6 +70,7 @@
 import { ref, watch } from 'vue'
 import { useSourcesStore } from '../../stores/sources.js'
 import { formatRelative } from '../../utils/date.js'
+import CardHeading from '../common/CardHeading.vue'
 
 const props = defineProps({
   modelValue: { type: Boolean, default: false },

From 7b2a2051e941391284ce77f7d8b06cb020481002 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 23:46:01 -0400
Subject: [PATCH 07/10] refactor(services): shared race-safe get_or_create
 helper (DRY backend sweep)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The find-or-create dance — SELECT, then a SAVEPOINT INSERT that recovers (not a
full rollback) on IntegrityError when a concurrent worker inserted first — was
hand-rolled identically in 4 async sites: ArtistService.find_or_create,
TagService.find_or_create, ExtensionService._find_or_create_artist and
._find_or_create_source. Divergent copies of exactly this pattern are how the
duplicate-row/race bugs in reference_scalar_one_or_none_duplicates crept in, so
it now lives once in services/db_helpers.get_or_create (returns (row, created);
factory adds+flushes+returns the row; caller owns the outer commit).

Over-DRY guard: SourceService's IntegrityError sites RAISE DuplicateSourceError
(reject-on-conflict, a different concept) — left alone. Importer._get_or_create
is the lone SYNC consumer (already shared by 2 callers) — stays separate, can't
cross the sync/async boundary. §8b: no hand-rolled async find-or-create remains.
Test: get_or_create creates then returns existing without re-invoking the factory.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 backend/app/services/artist_service.py    | 33 +++++-------
 backend/app/services/db_helpers.py        | 55 ++++++++++++++++++++
 backend/app/services/extension_service.py | 63 +++++++++--------------
 backend/app/services/tag_service.py       | 16 ++----
 tests/test_db_helpers.py                  | 34 ++++++++++++
 5 files changed, 131 insertions(+), 70 deletions(-)
 create mode 100644 backend/app/services/db_helpers.py
 create mode 100644 tests/test_db_helpers.py

diff --git a/backend/app/services/artist_service.py b/backend/app/services/artist_service.py
index e72e3c0..5be2dcb 100644
--- a/backend/app/services/artist_service.py
+++ b/backend/app/services/artist_service.py
@@ -10,7 +10,6 @@ from dataclasses import dataclass
 
 from sqlalchemy import and_, case, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
-from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from ..models import (
@@ -24,6 +23,7 @@ from ..models import (
 )
 from ..models.tag import image_tag
 from ..utils.slug import slugify
+from .db_helpers import get_or_create
 from .gallery_service import decode_cursor, encode_cursor, thumbnail_url
 
 
@@ -250,12 +250,10 @@ class ArtistService:
         )
 
     async def find_or_create(self, name: str) -> tuple[Artist, bool]:
-        """Return (artist, created). Slug-keyed; idempotent under races.
-
-        Audit 2026-06-02: switched from session.rollback() to a
-        begin_nested savepoint + IntegrityError recovery so a lost
-        race doesn't unwind the calling request's surrounding work.
-        Mirrors importer._get_or_create.
+        """Return (artist, created). Slug-keyed; idempotent under races via the
+        shared race-safe db_helpers.get_or_create (savepoint + IntegrityError
+        recovery). A new artist also seeds an ArtistVisit so the directory's
+        `+N new` badge starts at 0.
         """
         cleaned = (name or "").strip()
         if not cleaned:
@@ -263,12 +261,8 @@ class ArtistService:
         slug = slugify(cleaned)
 
         select_existing = select(Artist).where(Artist.slug == slug)
-        existing = (await self.session.execute(select_existing)).scalar_one_or_none()
-        if existing is not None:
-            return existing, False
 
-        sp = await self.session.begin_nested()
-        try:
+        async def _create() -> Artist:
             artist = Artist(name=cleaned, slug=slug)
             self.session.add(artist)
             await self.session.flush()
@@ -279,13 +273,14 @@ class ArtistService:
             # count every image imported in the same session.
             self.session.add(ArtistVisit(artist_id=artist.id))
             await self.session.flush()
-            await sp.commit()
-        except IntegrityError:
-            await sp.rollback()
-            existing = (await self.session.execute(select_existing)).scalar_one()
-            return existing, False
-        await self.session.commit()
-        return artist, True
+            return artist
+
+        artist, created = await get_or_create(
+            self.session, select_existing, _create
+        )
+        if created:
+            await self.session.commit()
+        return artist, created
 
     async def autocomplete(self, prefix: str, limit: int = 20) -> list[Artist]:
         cleaned = (prefix or "").strip()
diff --git a/backend/app/services/db_helpers.py b/backend/app/services/db_helpers.py
new file mode 100644
index 0000000..2b934c4
--- /dev/null
+++ b/backend/app/services/db_helpers.py
@@ -0,0 +1,55 @@
+"""Shared DB-access helpers for the async services.
+
+`get_or_create` centralizes the race-safe find-or-create dance — SELECT, then on
+a miss a savepoint INSERT that recovers (NOT a full rollback) when a concurrent
+worker inserted the same row first. It was hand-rolled identically in
+ArtistService, TagService and ExtensionService; divergent copies are exactly how
+the duplicate-row / race bugs in [[reference_scalar_one_or_none_duplicates]] crept
+in, so it lives in one place now (DRY pattern sweep 2026-06-09).
+
+Note: this is the ASYNC sibling of `Importer._get_or_create` (sync, used by the
+filesystem-import path). The two can't share an implementation across the
+sync/async boundary; the importer one stays as the lone sync consumer.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from sqlalchemy import Select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+T = TypeVar("T")
+
+
+async def get_or_create(
+    session: AsyncSession,
+    select_stmt: Select,
+    factory: Callable[[], Awaitable[T]],
+) -> tuple[T, bool]:
+    """Race-safe find-or-create. Returns ``(row, created)``.
+
+    Run ``select_stmt`` (scalar_one_or_none); if a row exists, return it with
+    ``created=False``. Otherwise open a SAVEPOINT and ``await factory()`` — which
+    must add its row(s), flush, and return the primary row. On ``IntegrityError``
+    (a concurrent worker inserted the same row first) roll back the SAVEPOINT —
+    NOT the outer transaction, which would lose the caller's surrounding work —
+    and re-run ``select_stmt`` (scalar_one) to return the row the other worker
+    created. The caller owns the outer commit.
+
+    A UNIQUE/partial-unique constraint matching ``select_stmt``'s predicate is
+    required for the recovery to trip; without it a duplicate slips through.
+    """
+    existing = (await session.execute(select_stmt)).scalar_one_or_none()
+    if existing is not None:
+        return existing, False
+    sp = await session.begin_nested()
+    try:
+        row = await factory()
+        await sp.commit()
+        return row, True
+    except IntegrityError:
+        await sp.rollback()
+        return (await session.execute(select_stmt)).scalar_one(), False
diff --git a/backend/app/services/extension_service.py b/backend/app/services/extension_service.py
index 25d02a8..a5a932f 100644
--- a/backend/app/services/extension_service.py
+++ b/backend/app/services/extension_service.py
@@ -11,11 +11,11 @@ from __future__ import annotations
 import re
 
 from sqlalchemy import select
-from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from ..models import Artist, Source
 from ..utils.slug import slugify
+from .db_helpers import get_or_create
 from .source_service import BACKFILL_MAX_CHUNKS
 
 
@@ -169,24 +169,16 @@ class ExtensionService:
         500 against uq_artist_slug.
         """
         slug = slugify(raw_name)
-        existing = (await self.session.execute(
-            select(Artist).where(Artist.slug == slug)
-        )).scalar_one_or_none()
-        if existing is not None:
-            return existing, False
-        sp = await self.session.begin_nested()
-        try:
+
+        async def _create() -> Artist:
             artist = Artist(name=raw_name, slug=slug, is_subscription=True)
             self.session.add(artist)
             await self.session.flush()
-            await sp.commit()
-            return artist, True
-        except IntegrityError:
-            await sp.rollback()
-            recovered = (await self.session.execute(
-                select(Artist).where(Artist.slug == slug)
-            )).scalar_one()
-            return recovered, False
+            return artist
+
+        return await get_or_create(
+            self.session, select(Artist).where(Artist.slug == slug), _create
+        )
 
     async def _find_or_create_source(
         self, *, artist_id: int, platform: str, url: str,
@@ -194,17 +186,13 @@ class ExtensionService:
         """Race-safe — same pattern as _find_or_create_artist above. The
         uq_source_artist_platform_url constraint catches the duplicate
         insert; we roll the savepoint back and re-select."""
-        existing = (await 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, False
-        sp = await self.session.begin_nested()
-        try:
+        select_existing = select(Source).where(
+            Source.artist_id == artist_id,
+            Source.platform == platform,
+            Source.url == url,
+        )
+
+        async def _create() -> Source:
             # New subscription sources arm run-until-done backfill (plan #693)
             # so the first ticks walk the full history (otherwise gallery-dl's
             # exit:20 short-circuits before the archive is built). Mirrors
@@ -219,16 +207,11 @@ class ExtensionService:
             )
             self.session.add(src)
             await self.session.flush()
-            await sp.commit()
-        except IntegrityError:
-            await sp.rollback()
-            recovered = (await self.session.execute(
-                select(Source).where(
-                    Source.artist_id == artist_id,
-                    Source.platform == platform,
-                    Source.url == url,
-                )
-            )).scalar_one()
-            return recovered, False
-        await self.session.commit()
-        return src, True
+            return src
+
+        src, created = await get_or_create(
+            self.session, select_existing, _create
+        )
+        if created:
+            await self.session.commit()
+        return src, created
diff --git a/backend/app/services/tag_service.py b/backend/app/services/tag_service.py
index 335afc3..91dd7cb 100644
--- a/backend/app/services/tag_service.py
+++ b/backend/app/services/tag_service.py
@@ -7,12 +7,12 @@ from dataclasses import dataclass
 
 from sqlalchemy import and_, case, exists, func, select, text, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
-from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from ..models import Tag, TagKind, image_tag
 from ..models.tag_allowlist import TagAllowlist
 from ..models.tag_reference_embedding import TagReferenceEmbedding
+from .db_helpers import get_or_create
 
 log = logging.getLogger(__name__)
 
@@ -130,20 +130,14 @@ class TagService:
             .order_by(Tag.id)
             .limit(1)
         )
-        existing = (await self.session.execute(stmt)).scalar_one_or_none()
-        if existing:
-            return existing
-
-        sp = await self.session.begin_nested()
-        try:
+        async def _create() -> Tag:
             new_tag = Tag(name=name, kind=kind, fandom_id=fandom_id)
             self.session.add(new_tag)
             await self.session.flush()
-            await sp.commit()
             return new_tag
-        except IntegrityError:
-            await sp.rollback()
-            return (await self.session.execute(stmt)).scalar_one()
+
+        tag, _created = await get_or_create(self.session, stmt, _create)
+        return tag
 
     async def autocomplete(
         self,
diff --git a/tests/test_db_helpers.py b/tests/test_db_helpers.py
new file mode 100644
index 0000000..e0073b0
--- /dev/null
+++ b/tests/test_db_helpers.py
@@ -0,0 +1,34 @@
+"""Race-safe get_or_create helper (shared by the async services)."""
+
+import pytest
+from sqlalchemy import select
+
+from backend.app.models import Artist
+from backend.app.services.db_helpers import get_or_create
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.mark.asyncio
+async def test_get_or_create_creates_then_returns_existing(db):
+    stmt = select(Artist).where(Artist.slug == "goc-test")
+
+    factory_calls = {"n": 0}
+
+    async def _make():
+        factory_calls["n"] += 1
+        a = Artist(name="GOC Test", slug="goc-test")
+        db.add(a)
+        await db.flush()
+        return a
+
+    row1, created1 = await get_or_create(db, stmt, _make)
+    assert created1 is True
+    assert row1.slug == "goc-test"
+    assert factory_calls["n"] == 1
+
+    # Second call finds the existing row and does NOT invoke the factory.
+    row2, created2 = await get_or_create(db, stmt, _make)
+    assert created2 is False
+    assert row2.id == row1.id
+    assert factory_calls["n"] == 1  # factory not called when the row exists

From f1a664e5a72a70c048b250a601931fcce87b036c Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 9 Jun 2026 23:50:59 -0400
Subject: [PATCH 08/10] fix(services): PEP 695 type params for get_or_create
 (ruff UP047)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI lint flagged UP047 — use the native generic syntax def get_or_create[T](...)
instead of typing.TypeVar on Python 3.14.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 backend/app/services/db_helpers.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/backend/app/services/db_helpers.py b/backend/app/services/db_helpers.py
index 2b934c4..992a76d 100644
--- a/backend/app/services/db_helpers.py
+++ b/backend/app/services/db_helpers.py
@@ -15,16 +15,13 @@ sync/async boundary; the importer one stays as the lone sync consumer.
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable
-from typing import TypeVar
 
 from sqlalchemy import Select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
-T = TypeVar("T")
 
-
-async def get_or_create(
+async def get_or_create[T](
     session: AsyncSession,
     select_stmt: Select,
     factory: Callable[[], Awaitable[T]],

From 074c5868fb364b0b48cf99b03c258db62ec7e6bf Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Wed, 10 Jun 2026 00:10:57 -0400
Subject: [PATCH 09/10] refactor(services): shared pagination cursor (DRY
 sweep)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

encode_cursor/decode_cursor (base64 <iso8601>|<id>) were defined identically in
gallery_service AND post_feed_service, with artist_service importing gallery's
copy. Two implementations of one cursor format silently break pagination in
whichever feed drifts. Extract to services/pagination.py; gallery/post_feed/
artist all import it. Dropped now-unused base64/datetime imports.

§8b: encode_cursor/decode_cursor now defined only in pagination.py. Existing
cursor round-trip tests still cover it via the re-export. Catalog updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 backend/app/services/artist_service.py    |  3 ++-
 backend/app/services/gallery_service.py   | 18 +------------
 backend/app/services/pagination.py        | 31 +++++++++++++++++++++++
 backend/app/services/post_feed_service.py | 26 +++----------------
 4 files changed, 38 insertions(+), 40 deletions(-)
 create mode 100644 backend/app/services/pagination.py

diff --git a/backend/app/services/artist_service.py b/backend/app/services/artist_service.py
index 5be2dcb..20acf06 100644
--- a/backend/app/services/artist_service.py
+++ b/backend/app/services/artist_service.py
@@ -24,7 +24,8 @@ from ..models import (
 from ..models.tag import image_tag
 from ..utils.slug import slugify
 from .db_helpers import get_or_create
-from .gallery_service import decode_cursor, encode_cursor, thumbnail_url
+from .gallery_service import thumbnail_url
+from .pagination import decode_cursor, encode_cursor
 
 
 @dataclass(frozen=True)
diff --git a/backend/app/services/gallery_service.py b/backend/app/services/gallery_service.py
index 44cbe66..cd5cc2e 100644
--- a/backend/app/services/gallery_service.py
+++ b/backend/app/services/gallery_service.py
@@ -14,7 +14,6 @@ Decoding rejects malformed cursors with a ValueError; the API layer
 translates that to HTTP 400.
 """
 
-import base64
 from dataclasses import dataclass
 from datetime import datetime
 
@@ -24,8 +23,7 @@ from sqlalchemy.orm import aliased
 
 from ..models import Artist, ImageProvenance, ImageRecord, Post, Source, Tag
 from ..models.tag import image_tag
-
-CURSOR_SEPARATOR = "|"
+from .pagination import decode_cursor, encode_cursor
 
 # Reserved `platform` filter value selecting images with NO platformed
 # provenance (filesystem imports). Returned by facets() as a null-valued
@@ -35,20 +33,6 @@ CURSOR_SEPARATOR = "|"
 UNSOURCED_PLATFORM = "__unsourced__"
 
 
-def encode_cursor(effective_date: datetime, image_id: int) -> str:
-    raw = f"{effective_date.isoformat()}{CURSOR_SEPARATOR}{image_id}"
-    return base64.urlsafe_b64encode(raw.encode()).decode()
-
-
-def decode_cursor(cursor: str) -> tuple[datetime, int]:
-    try:
-        raw = base64.urlsafe_b64decode(cursor.encode()).decode()
-        ts_part, id_part = raw.split(CURSOR_SEPARATOR, 1)
-        return datetime.fromisoformat(ts_part), int(id_part)
-    except Exception as exc:
-        raise ValueError(f"invalid cursor: {cursor!r}") from exc
-
-
 def _effective_date_col():
     """The materialized gallery sort key: image_record.effective_date
     (alembic 0035) = COALESCE(primary post's post_date, created_at),
diff --git a/backend/app/services/pagination.py b/backend/app/services/pagination.py
new file mode 100644
index 0000000..5f3d01d
--- /dev/null
+++ b/backend/app/services/pagination.py
@@ -0,0 +1,31 @@
+"""Shared opaque keyset-pagination cursor.
+
+A cursor is base64(``<iso8601_sort_key>|<row_id>``). The sort key is whatever
+DESC-ordered timestamp a feed paginates on (gallery: effective_date; posts:
+COALESCE(post_date, downloaded_at); artists: created_at). `decode_cursor` rejects
+a malformed cursor with ValueError, which the API layer maps to HTTP 400.
+
+This was hand-rolled identically in gallery_service and post_feed_service (with
+artist_service importing gallery's copy). Two divergent copies of a cursor format
+silently break pagination in whichever feed drifts, so it lives once here now
+(DRY pattern sweep 2026-06-10).
+"""
+
+import base64
+from datetime import datetime
+
+CURSOR_SEPARATOR = "|"
+
+
+def encode_cursor(sort_key: datetime, row_id: int) -> str:
+    raw = f"{sort_key.isoformat()}{CURSOR_SEPARATOR}{row_id}"
+    return base64.urlsafe_b64encode(raw.encode()).decode()
+
+
+def decode_cursor(cursor: str) -> tuple[datetime, int]:
+    try:
+        raw = base64.urlsafe_b64decode(cursor.encode()).decode()
+        ts_part, id_part = raw.split(CURSOR_SEPARATOR, 1)
+        return datetime.fromisoformat(ts_part), int(id_part)
+    except Exception as exc:
+        raise ValueError(f"invalid cursor: {cursor!r}") from exc
diff --git a/backend/app/services/post_feed_service.py b/backend/app/services/post_feed_service.py
index f98debc..a4e1f78 100644
--- a/backend/app/services/post_feed_service.py
+++ b/backend/app/services/post_feed_service.py
@@ -1,9 +1,8 @@
 """FC-3e: cursor-paginated read service for the Posts stream.
 
-Mirrors GalleryService.scroll's cursor encoding so the frontend pattern
-is identical: base64 of "<iso8601_sort_key>|<post_id>". Sort key is
-COALESCE(Post.post_date, Post.downloaded_at) so posts without a
-publish date sort by when we captured them.
+Uses the shared `pagination` cursor (base64 of "<iso8601_sort_key>|<id>") so
+every feed paginates identically. Sort key here is COALESCE(Post.post_date,
+Post.downloaded_at) so posts without a publish date sort by when we captured them.
 
 Pure read-surface; no writes. The service composes the post dict
 (thumbnails from every image linked to the post — its own primary images
@@ -12,9 +11,6 @@ attachments from PostAttachment) so the API layer can jsonify directly.
 """
 from __future__ import annotations
 
-import base64
-from datetime import datetime
-
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -28,26 +24,12 @@ from ..models import (
 )
 from ..utils.text import html_to_plain, truncate_at_word
 from .gallery_service import thumbnail_url
+from .pagination import decode_cursor, encode_cursor
 
-CURSOR_SEPARATOR = "|"
 DESCRIPTION_LIMIT = 280
 THUMBNAIL_LIMIT = 6
 
 
-def encode_cursor(sort_key: datetime, post_id: int) -> str:
-    raw = f"{sort_key.isoformat()}{CURSOR_SEPARATOR}{post_id}"
-    return base64.urlsafe_b64encode(raw.encode()).decode()
-
-
-def decode_cursor(cursor: str) -> tuple[datetime, int]:
-    try:
-        raw = base64.urlsafe_b64decode(cursor.encode()).decode()
-        ts_part, id_part = raw.split(CURSOR_SEPARATOR, 1)
-        return datetime.fromisoformat(ts_part), int(id_part)
-    except Exception as exc:
-        raise ValueError(f"invalid cursor: {cursor!r}") from exc
-
-
 def _sort_key():
     """Postgres COALESCE expression used in ORDER BY and WHERE clauses."""
     return func.coalesce(Post.post_date, Post.downloaded_at)

From 14c244bd3d92adf3d2f107708799d64bb23bdaf6 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Wed, 10 Jun 2026 00:19:17 -0400
Subject: [PATCH 10/10] refactor(tags): shared tag_query for fandom self-join +
 serialization (DRY sweep)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The fandom self-join (resolve a character's fandom NAME via Tag.fandom_id->Tag)
and the {id,name,kind,fandom_id,fandom_name} dict were hand-written in
TagService.autocomplete/.list_for_image, GalleryService.get_image_with_tags and
the api/tags handlers — the last few grown by this session's fandom-on-chip
feature. Consolidate to services/tag_query: fandom_join_alias() + tag_columns()
build the select; serialize_tag(row) builds the dict. Now a new tag field is
added in one place.

Over-DRY guard: TagDirectoryService selects the full Tag ORM + an image-count
aggregate (a different select shape) — left as its own variant. §8b: the
fandom_lookup alias lives only in tag_query; gallery + both api/tags handlers
serialize via serialize_tag. Test: serialize_tag handles enum + string kind.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 backend/app/api/tags.py                 | 26 ++-------------
 backend/app/services/gallery_service.py | 24 +++-----------
 backend/app/services/tag_query.py       | 44 +++++++++++++++++++++++++
 backend/app/services/tag_service.py     | 19 +++--------
 tests/test_tag_query.py                 | 29 ++++++++++++++++
 5 files changed, 86 insertions(+), 56 deletions(-)
 create mode 100644 backend/app/services/tag_query.py
 create mode 100644 tests/test_tag_query.py

diff --git a/backend/app/api/tags.py b/backend/app/api/tags.py
index b189c1f..4fbe0a0 100644
--- a/backend/app/api/tags.py
+++ b/backend/app/api/tags.py
@@ -11,6 +11,7 @@ from ..services.bulk_tag_service import BulkTagService
 from ..services.series_match_service import SeriesMatchService
 from ..services.series_service import SeriesError, SeriesService
 from ..services.tag_directory_service import TagDirectoryService
+from ..services.tag_query import serialize_tag
 from ..services.tag_service import (
     TagMergeConflict,
     TagService,
@@ -72,17 +73,7 @@ async def autocomplete():
         hits = await svc.autocomplete(q, kind=kind, limit=limit)
 
     return jsonify(
-        [
-            {
-                "id": h.id,
-                "name": h.name,
-                "kind": h.kind,
-                "fandom_id": h.fandom_id,
-                "fandom_name": h.fandom_name,
-                "image_count": h.image_count,
-            }
-            for h in hits
-        ]
+        [{**serialize_tag(h), "image_count": h.image_count} for h in hits]
     )
 
 
@@ -165,18 +156,7 @@ async def list_tags_for_image(image_id: int):
     async with get_session() as session:
         svc = TagService(session)
         tags = await svc.list_for_image(image_id)
-    return jsonify(
-        [
-            {
-                "id": t.id,
-                "name": t.name,
-                "kind": t.kind.value,
-                "fandom_id": t.fandom_id,
-                "fandom_name": t.fandom_name,
-            }
-            for t in tags
-        ]
-    )
+    return jsonify([serialize_tag(t) for t in tags])
 
 
 @tags_bp.route("/images/<int:image_id>/tags", methods=["POST"])
diff --git a/backend/app/services/gallery_service.py b/backend/app/services/gallery_service.py
index cd5cc2e..b8a0721 100644
--- a/backend/app/services/gallery_service.py
+++ b/backend/app/services/gallery_service.py
@@ -24,6 +24,7 @@ from sqlalchemy.orm import aliased
 from ..models import Artist, ImageProvenance, ImageRecord, Post, Source, Tag
 from ..models.tag import image_tag
 from .pagination import decode_cursor, encode_cursor
+from .tag_query import fandom_join_alias, serialize_tag, tag_columns
 
 # Reserved `platform` filter value selecting images with NO platformed
 # provenance (filesystem imports). Returned by facets() as a null-valued
@@ -543,16 +544,10 @@ class GalleryService:
         if record is None:
             return None
         # Self-join Tag to resolve a character's fandom NAME (not just id) so the
-        # modal chip can label it without an N+1 — mirrors list_for_image.
-        fandom_alias = Tag.__table__.alias("fandom_lookup")
+        # modal chip can label it without an N+1 (shared tag_query helpers).
+        fandom_alias = fandom_join_alias()
         tag_stmt = (
-            select(
-                Tag.id,
-                Tag.name,
-                Tag.kind,
-                Tag.fandom_id,
-                fandom_alias.c.name.label("fandom_name"),
-            )
+            select(*tag_columns(fandom_alias))
             .select_from(
                 Tag.__table__
                 .join(image_tag, image_tag.c.tag_id == Tag.id)
@@ -599,16 +594,7 @@ class GalleryService:
                 {"id": artist.id, "name": artist.name, "slug": artist.slug}
                 if artist is not None else None
             ),
-            "tags": [
-                {
-                    "id": t.id,
-                    "name": t.name,
-                    "kind": t.kind.value if hasattr(t.kind, "value") else t.kind,
-                    "fandom_id": t.fandom_id,
-                    "fandom_name": t.fandom_name,
-                }
-                for t in tags
-            ],
+            "tags": [serialize_tag(t) for t in tags],
             "neighbors": neighbors,
         }
 
diff --git a/backend/app/services/tag_query.py b/backend/app/services/tag_query.py
new file mode 100644
index 0000000..2dfbfbd
--- /dev/null
+++ b/backend/app/services/tag_query.py
@@ -0,0 +1,44 @@
+"""Shared tag-with-fandom query columns + serialization.
+
+Resolving a character tag's fandom NAME via a Tag self-join (Tag.fandom_id -> the
+fandom Tag) and serializing the canonical
+``{id, name, kind, fandom_id, fandom_name}`` dict were hand-written in
+TagService.autocomplete / .list_for_image and GalleryService.get_image_with_tags
+(the last two added by the fandom-on-chip feature, 978f49a). One source now
+(DRY pattern sweep 2026-06-10) so a new tag field is added in exactly one place.
+
+TagDirectoryService selects the FULL Tag ORM plus an image-count aggregate (a
+different select shape), so it keeps its own variant — not folded in here.
+"""
+
+from ..models import Tag
+
+
+def fandom_join_alias():
+    """A Tag self-join alias for resolving a tag's fandom name. Outerjoin it on
+    ``Tag.fandom_id == <alias>.c.id`` and select via `tag_columns(alias)`."""
+    return Tag.__table__.alias("fandom_lookup")
+
+
+def tag_columns(fandom_alias):
+    """The canonical (id, name, kind, fandom_id, fandom_name) column set for a
+    tag select that outerjoins `fandom_alias` (from `fandom_join_alias()`)."""
+    return [
+        Tag.id,
+        Tag.name,
+        Tag.kind,
+        Tag.fandom_id,
+        fandom_alias.c.name.label("fandom_name"),
+    ]
+
+
+def serialize_tag(row) -> dict:
+    """Serialize a row carrying .id/.name/.kind/.fandom_id/.fandom_name to the
+    canonical tag dict. `kind` may be a TagKind enum or a plain string."""
+    return {
+        "id": row.id,
+        "name": row.name,
+        "kind": row.kind.value if hasattr(row.kind, "value") else row.kind,
+        "fandom_id": row.fandom_id,
+        "fandom_name": row.fandom_name,
+    }
diff --git a/backend/app/services/tag_service.py b/backend/app/services/tag_service.py
index 91dd7cb..3de2115 100644
--- a/backend/app/services/tag_service.py
+++ b/backend/app/services/tag_service.py
@@ -13,6 +13,7 @@ from ..models import Tag, TagKind, image_tag
 from ..models.tag_allowlist import TagAllowlist
 from ..models.tag_reference_embedding import TagReferenceEmbedding
 from .db_helpers import get_or_create
+from .tag_query import fandom_join_alias, tag_columns
 
 log = logging.getLogger(__name__)
 
@@ -159,7 +160,7 @@ class TagService:
             else_=2,
         )
 
-        fandom_alias = Tag.__table__.alias("fandom_lookup")
+        fandom_alias = fandom_join_alias()
         image_count = (
             select(func.count(image_tag.c.image_record_id))
             .where(image_tag.c.tag_id == Tag.id)
@@ -169,11 +170,7 @@ class TagService:
 
         stmt = (
             select(
-                Tag.id,
-                Tag.name,
-                Tag.kind,
-                Tag.fandom_id,
-                fandom_alias.c.name.label("fandom_name"),
+                *tag_columns(fandom_alias),
                 image_count.label("image_count"),
             )
             .select_from(Tag.__table__.outerjoin(
@@ -224,15 +221,9 @@ class TagService:
         NAME (not just fandom_id) via a self-join on Tag, so the UI can label a
         character chip with its fandom without an N+1 (mirrors the
         autocomplete/directory resolution)."""
-        fandom_alias = Tag.__table__.alias("fandom_lookup")
+        fandom_alias = fandom_join_alias()
         stmt = (
-            select(
-                Tag.id,
-                Tag.name,
-                Tag.kind,
-                Tag.fandom_id,
-                fandom_alias.c.name.label("fandom_name"),
-            )
+            select(*tag_columns(fandom_alias))
             .select_from(
                 Tag.__table__
                 .join(image_tag, image_tag.c.tag_id == Tag.id)
diff --git a/tests/test_tag_query.py b/tests/test_tag_query.py
new file mode 100644
index 0000000..c5ed4f7
--- /dev/null
+++ b/tests/test_tag_query.py
@@ -0,0 +1,29 @@
+"""serialize_tag — the shared canonical tag-dict serializer."""
+
+from types import SimpleNamespace
+
+from backend.app.models import TagKind
+from backend.app.services.tag_query import serialize_tag
+
+
+def test_serialize_tag_with_enum_kind():
+    # ORM/column rows carry kind as a TagKind enum.
+    row = SimpleNamespace(
+        id=1, name="Sasuke Uchiha", kind=TagKind.character,
+        fandom_id=5, fandom_name="Naruto",
+    )
+    assert serialize_tag(row) == {
+        "id": 1, "name": "Sasuke Uchiha", "kind": "character",
+        "fandom_id": 5, "fandom_name": "Naruto",
+    }
+
+
+def test_serialize_tag_with_string_kind_and_no_fandom():
+    # autocomplete hits already store kind as a plain string.
+    row = SimpleNamespace(
+        id=2, name="solo", kind="general", fandom_id=None, fandom_name=None,
+    )
+    assert serialize_tag(row) == {
+        "id": 2, "name": "solo", "kind": "general",
+        "fandom_id": None, "fandom_name": None,
+    }