From 1b496e74d46a30ca7e0659a0fbf87dbefae6aa3a Mon Sep 17 00:00:00 2001
From: Darrell van Swinderen <darrell260802@gmail.com>
Date: Wed, 23 Sep 2026 15:38:02 +0200
Subject: [PATCH] feat(library): show view count on published clips' cards

The counts were already mirrored onto every clip row, so no per-page
fetch: the card reads publisherViews off the row it already has. What
was missing was freshness, since the sync only ran at boot and on the
Publisher screen. The library now asks on open and on window focus,
throttled in main to one request per ten minutes shared with every
other caller, and patches the rows on screen rather than refetching.

Null and zero both show nothing on a card: a card cannot tell "never
opened" from "nothing was counting yet".

Closes #63

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/main/actions/SyncPublisherStatsAction.ts  | 74 +++++++++++++++----
 src/main/routes/stats.ts                      | 11 ++-
 src/main/services/publisherStatsFreshness.ts  | 20 +++++
 .../src/components/Library/ClipCard.vue       |  2 +
 .../src/components/Library/ClipMetadata.vue   | 22 +++++-
 .../library/useLibraryViewCounts.ts           | 73 ++++++++++++++++++
 src/renderer/src/services/clips.ts            | 16 ++--
 src/renderer/src/stores/clips.ts              | 18 +++++
 src/renderer/src/utils/viewCount.ts           | 20 +++++
 src/renderer/src/views/ClipsPage.vue          |  3 +
 .../unit/main/publisherStatsFreshness.spec.ts | 28 +++++++
 tests/unit/renderer/viewCount.spec.ts         | 33 +++++++++
 12 files changed, 299 insertions(+), 21 deletions(-)
 create mode 100644 src/main/services/publisherStatsFreshness.ts
 create mode 100644 src/renderer/src/composables/library/useLibraryViewCounts.ts
 create mode 100644 src/renderer/src/utils/viewCount.ts
 create mode 100644 tests/unit/main/publisherStatsFreshness.spec.ts
 create mode 100644 tests/unit/renderer/viewCount.spec.ts

diff --git a/src/main/actions/SyncPublisherStatsAction.ts b/src/main/actions/SyncPublisherStatsAction.ts
index 1f149af6..9d5231e6 100644
--- a/src/main/actions/SyncPublisherStatsAction.ts
+++ b/src/main/actions/SyncPublisherStatsAction.ts
@@ -5,6 +5,7 @@ import { AppDataSource } from '../data-source.js';
 import { Clip } from '../entity/Clip.js';
 import { publisherAuthHeaders, publisherBaseUrl } from '../services/publisherConfig.js';
 import { ClipDTO } from '@shared/index.js';
+import { statsAreStale } from '../services/publisherStatsFreshness.js';
 
 export interface PublisherClipStat {
   filename: string;
@@ -45,16 +46,38 @@ export interface SyncPublisherStatsOutput {
    * state never appeared. Null when the publisher answered.
    */
   problem: PublisherStatsProblem | null;
+  /**
+   * True when nothing was asked because the last attempt is recent enough.
+   *
+   * The rest of the answer is then empty and means nothing; a caller patching
+   * rows on screen must leave them alone rather than read "no clips".
+   */
+  skipped: boolean;
 }
 
+export interface SyncPublisherStatsInput {
+  /**
+   * Ask only if the last attempt is older than this. Omitted means ask now,
+   * which is what boot and the Publisher screen want.
+   */
+  maxAgeMs?: number;
+}
+
+/** When the publisher was last asked, by anyone. See `statsAreStale`. */
+let lastAttemptAt: number | null = null;
+/** One request at a time: a second caller waits for the one already out. */
+let inFlight: Promise<SyncPublisherStatsOutput> | null = null;
+
 
 /**
  * Bring the publisher's view counts back onto the rows.
  *
- * **Pulled, not polled.** On app start and when the Publisher screen opens. A
- * background timer refreshing a number that only matters while somebody is
- * looking at it is cost with no reader, and every refresh is a request over
- * somebody's home uplink to their own server.
+ * **Pulled, not polled.** On app start, when the Publisher screen opens, and
+ * when the library is looked at, throttled by `maxAgeMs` so the library's
+ * cards stay current without asking on every alt-tab. A background timer
+ * refreshing a number that only matters while somebody is looking at it is
+ * cost with no reader, and every refresh is a request over somebody's home
+ * uplink to their own server.
  *
  * Mirrored onto `clip` rather than fetched per tile for the same reason
  * `suggestedCount` is: the library is one query per page, and a remote lookup
@@ -65,15 +88,27 @@ export interface SyncPublisherStatsOutput {
  * are "no numbers today" rather than an error, because nothing the user asked
  * for has failed.
  */
-export class SyncPublisherStatsAction extends BaseAction<void, SyncPublisherStatsOutput> {
-  async execute(): Promise<SyncPublisherStatsOutput> {
-    const empty: SyncPublisherStatsOutput = {
-      clips: [],
-      updated: 0,
-      totals: { clips: 0, bytes: 0, views: 0 },
-      countingSince: null,
-      problem: null,
-    };
+export class SyncPublisherStatsAction extends BaseAction<
+  SyncPublisherStatsInput | void,
+  SyncPublisherStatsOutput
+> {
+  async execute(input: SyncPublisherStatsInput | void): Promise<SyncPublisherStatsOutput> {
+    if (inFlight) return inFlight;
+
+    const maxAgeMs = input?.maxAgeMs;
+    if (maxAgeMs != null && !statsAreStale(lastAttemptAt, Date.now(), maxAgeMs)) {
+      return { ...emptyOutput(), skipped: true };
+    }
+
+    lastAttemptAt = Date.now();
+    inFlight = this.sync().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  }
+
+  private async sync(): Promise<SyncPublisherStatsOutput> {
+    const empty = emptyOutput();
 
     const baseUrl = publisherBaseUrl();
     if (!baseUrl) return empty;
@@ -122,6 +157,7 @@ export class SyncPublisherStatsAction extends BaseAction<void, SyncPublisherStat
         totals: payload.totals ?? empty.totals,
         countingSince: payload.countingSince ?? null,
         problem: null,
+        skipped: false,
       };
     }
 
@@ -149,6 +185,18 @@ export class SyncPublisherStatsAction extends BaseAction<void, SyncPublisherStat
       totals: payload.totals ?? empty.totals,
       countingSince: payload.countingSince ?? null,
       problem: null,
+      skipped: false,
     };
   }
 }
+
+function emptyOutput(): SyncPublisherStatsOutput {
+  return {
+    clips: [],
+    updated: 0,
+    totals: { clips: 0, bytes: 0, views: 0 },
+    countingSince: null,
+    problem: null,
+    skipped: false,
+  };
+}
diff --git a/src/main/routes/stats.ts b/src/main/routes/stats.ts
index b9312ddf..e1b4d43a 100644
--- a/src/main/routes/stats.ts
+++ b/src/main/routes/stats.ts
@@ -10,13 +10,20 @@ export const statsRouter = express.Router();
 /**
  * Bring the publisher's view counts back, and say what it reported.
  *
+ * Also asked by the library, throttled, so the counts on its cards follow the
+ * publisher while the app sits in the tray for days.
+ *
  * A POST rather than a GET: it writes to `clip` rows. Pulled by the Publisher
  * screen when it opens and once at boot, rather than polled, because a number
  * only matters while somebody is looking at it and every refresh is a request
  * over a home uplink to somebody's own server.
  */
-statsRouter.post('/publisher/sync', asyncHandler(async (_req, res) => {
-  const result = await new SyncPublisherStatsAction().execute();
+statsRouter.post('/publisher/sync', asyncHandler(async (req, res) => {
+  // The library passes `maxAgeMs` and is answered from the last sync when it
+  // is recent; the Publisher screen passes nothing and always asks.
+  const raw = Number(req.body?.maxAgeMs);
+  const maxAgeMs = Number.isFinite(raw) && raw > 0 ? raw : undefined;
+  const result = await new SyncPublisherStatsAction().execute({ maxAgeMs });
   res.json(result);
 }));
 
diff --git a/src/main/services/publisherStatsFreshness.ts b/src/main/services/publisherStatsFreshness.ts
new file mode 100644
index 00000000..32bc18f0
--- /dev/null
+++ b/src/main/services/publisherStatsFreshness.ts
@@ -0,0 +1,20 @@
+/**
+ * Whether the mirrored view counts are old enough to ask the publisher again.
+ *
+ * The library asks every time it is opened and every time the window comes
+ * back into focus, which is often. One clock in main, shared by boot, the
+ * Publisher screen and the library, turns that into at most one request per
+ * window, and a burst of navigation into none at all.
+ *
+ * An attempt counts, not only a success: a publisher that is switched off is
+ * asked once per window rather than on every alt-tab.
+ *
+ * Pure so `tests/unit` owns it; the clock lives in the action.
+ */
+export function statsAreStale(lastAttemptAt: number | null, now: number, maxAgeMs: number): boolean {
+  if (lastAttemptAt == null) return true;
+  // A clock that went backwards (a sleep, a manual change) is not "fresh for
+  // ever": treat it as stale rather than trusting a negative age.
+  const age = now - lastAttemptAt;
+  return age < 0 || age >= maxAgeMs;
+}
diff --git a/src/renderer/src/components/Library/ClipCard.vue b/src/renderer/src/components/Library/ClipCard.vue
index 5c8192cd..75ae18f5 100644
--- a/src/renderer/src/components/Library/ClipCard.vue
+++ b/src/renderer/src/components/Library/ClipCard.vue
@@ -443,6 +443,8 @@ function handleCardClick(event: MouseEvent) {
         :duration-sec="clip.durationSec"
         :game="gameDisplayName"
         :recorded-at="clip.recordedAt ?? clip.fileModifiedAt ?? clip.createdAt"
+        :views="clip.published ? clip.publisherViews : null"
+        :last-viewed-at="clip.publisherLastViewedAt"
       />
 
       <ClipTags :clip="clip" @updated="emit('updated', $event)" />
diff --git a/src/renderer/src/components/Library/ClipMetadata.vue b/src/renderer/src/components/Library/ClipMetadata.vue
index 70b3a286..222ba537 100644
--- a/src/renderer/src/components/Library/ClipMetadata.vue
+++ b/src/renderer/src/components/Library/ClipMetadata.vue
@@ -3,6 +3,7 @@ import { ref, computed } from 'vue';
 import { useConfiguration } from '@renderer/composables/app/useConfiguration';
 import { formatRelativeTime, formatExactDate } from '@renderer/helpers/dateFormat';
 import { useFormat } from '@renderer/composables/ui/useFormat';
+import { viewCountLabel } from '@renderer/utils/viewCount';
 
 /**
  * When the clip was recorded, which is the file's own date.
@@ -29,6 +30,12 @@ interface Props {
    */
   durationSec?: number | null;
   recordedAt?: string;
+  /**
+   * How often the published copy has been opened. Null for a clip that is not
+   * published or has not been counted; `viewCountLabel` decides what is said.
+   */
+  views?: number | null;
+  lastViewedAt?: string | null;
 }
 
 const props = defineProps<Props>();
@@ -47,6 +54,11 @@ const length = computed(() => {
   return hours ? `${hours}:${two(mins)}:${two(secs)}` : `${mins}:${two(secs)}`;
 });
 
+const viewsLabel = computed(() => viewCountLabel(props.views));
+const viewsHint = computed(() =>
+  props.lastViewedAt ? `Last opened ${formatRelativeTime(props.lastViewedAt)}` : undefined,
+);
+
 const displayDate = computed(() => {
   // No date is no date. Falling back to now would put a confident, wrong
   // "just now" on a clip whose age is simply not known.
@@ -60,7 +72,8 @@ const displayDate = computed(() => {
 
 <template>
   <!--
-    One line: how long, which game, how long ago, how big.
+    One line: how long, which game, how long ago, how big, and for a
+    published clip how often it has been opened.
 
     It was the duration and the file size on the left with the date pushed to
     the right edge, so each card carried a two-column layout of its own and a
@@ -88,6 +101,13 @@ const displayDate = computed(() => {
     </time>
     <span v-if="displayDate && sizeBytes" aria-hidden="true" class="shrink-0">·</span>
     <span v-if="sizeBytes" class="shrink-0 tabular-nums">{{ formatBytes(sizeBytes) }}</span>
+    <span v-if="viewsLabel && (length || game || displayDate || sizeBytes)" aria-hidden="true" class="shrink-0">·</span>
+    <span
+      v-if="viewsLabel"
+      class="shrink-0 tabular-nums"
+      data-testid="clip-view-count"
+      :title="viewsHint"
+    >{{ viewsLabel }}</span>
   </div>
 </template>
 
diff --git a/src/renderer/src/composables/library/useLibraryViewCounts.ts b/src/renderer/src/composables/library/useLibraryViewCounts.ts
new file mode 100644
index 00000000..f388ceeb
--- /dev/null
+++ b/src/renderer/src/composables/library/useLibraryViewCounts.ts
@@ -0,0 +1,73 @@
+import { onBeforeUnmount, onMounted, watch } from 'vue';
+import { syncPublisherStats } from '@renderer/services/clips';
+import { useClipsStore } from '@renderer/stores/clips';
+import { useAppSettings } from '@renderer/composables/app/useAppSettings';
+
+/**
+ * How stale the counts on a card may get while somebody is looking at them.
+ *
+ * Main owns the clock (`statsAreStale`), so boot, the Publisher screen and
+ * this all share one window and a burst of navigation is one request.
+ */
+export const LIBRARY_VIEW_COUNT_MAX_AGE_MS = 10 * 60_000;
+
+/**
+ * Keep the view counts on the library's cards following the publisher.
+ *
+ * The counts are already on every row (`SyncPublisherStatsAction` mirrors
+ * them), so nothing is fetched per page or per tile. What was missing is
+ * freshness: the sync ran at boot and on the Publisher screen, and the app
+ * sits in the tray for days. So the library asks when it opens and when the
+ * window comes back into focus, and main answers from the last sync when it
+ * is recent.
+ *
+ * **Quiet on failure.** A publisher that is off leaves yesterday's numbers on
+ * the cards. The Publisher screen is where "could not reach" is explained; an
+ * optional feature does not get an error banner over the library.
+ */
+export function useLibraryViewCounts(): void {
+  const clipsStore = useClipsStore();
+  const { settings } = useAppSettings();
+
+  async function refresh(): Promise<void> {
+    if (!settings.value.publisherBaseUrl) return;
+    try {
+      const answer = await syncPublisherStats(LIBRARY_VIEW_COUNT_MAX_AGE_MS);
+      if (answer.skipped || answer.problem) return;
+      /*
+       * After the list lands, not over it. The page's own first fetch runs
+       * beside this one, and a patch applied before its rows arrive is
+       * replaced by rows that may have been read before the sync wrote.
+       */
+      await untilListIdle();
+      clipsStore.applyPublisherViews(answer.clips ?? []);
+    } catch (error) {
+      console.warn('[library] could not refresh view counts:', error);
+    }
+  }
+
+  function untilListIdle(): Promise<void> {
+    if (!clipsStore.loading) return Promise.resolve();
+    return new Promise((resolve) => {
+      const stop = watch(
+        () => clipsStore.loading,
+        (loading) => {
+          if (loading) return;
+          stop();
+          resolve();
+        },
+      );
+    });
+  }
+
+  const onFocus = (): void => void refresh();
+
+  onMounted(() => {
+    void refresh();
+    window.addEventListener('focus', onFocus);
+  });
+
+  onBeforeUnmount(() => {
+    window.removeEventListener('focus', onFocus);
+  });
+}
diff --git a/src/renderer/src/services/clips.ts b/src/renderer/src/services/clips.ts
index db2cc08a..f9befc6a 100644
--- a/src/renderer/src/services/clips.ts
+++ b/src/renderer/src/services/clips.ts
@@ -275,17 +275,23 @@ export interface PublisherStats {
   countingSince: string | null;
   /** Why there are no numbers, when the publisher did not answer. */
   problem: { kind: 'unreachable' | 'unauthorized' | 'outdated'; message: string } | null;
+  /** Nothing was asked: the last sync is inside `maxAgeMs`. The rest is empty. */
+  skipped: boolean;
 }
 
 /**
  * Ask the publisher what it has, and mirror the numbers onto the rows.
  *
- * A POST because it writes. Called when the Publisher screen opens, never on a
- * timer: this is the one screen in the app that reads a remote service, and a
- * number nobody is looking at is not worth a request over a home uplink.
+ * A POST because it writes. Called when the Publisher screen opens, and by the
+ * library with `maxAgeMs` so main answers from the last sync when it is
+ * recent. Never on a timer: a number nobody is looking at is not worth a
+ * request over a home uplink.
  */
-export async function syncPublisherStats(): Promise<PublisherStats> {
-  const { data } = await axios.post<PublisherStats>('/api/stats/publisher/sync');
+export async function syncPublisherStats(maxAgeMs?: number): Promise<PublisherStats> {
+  const { data } = await axios.post<PublisherStats>(
+    '/api/stats/publisher/sync',
+    maxAgeMs ? { maxAgeMs } : undefined,
+  );
   return data;
 }
 
diff --git a/src/renderer/src/stores/clips.ts b/src/renderer/src/stores/clips.ts
index e76e2ee5..5c3d91dd 100644
--- a/src/renderer/src/stores/clips.ts
+++ b/src/renderer/src/stores/clips.ts
@@ -214,6 +214,24 @@ export const useClipsStore = defineStore('clips', {
       if (clip) clip.suggestedCount = suggestedCount;
     },
 
+    /**
+     * Fresh view counts onto the rows already on screen.
+     *
+     * Two fields assigned rather than whole rows replaced, and never a
+     * refetch: the grid would jump, and a list load here would race the
+     * abort-and-requestId pattern above. A clip not on screen gets the count
+     * when it is next fetched, because the sync wrote it to the row.
+     */
+    applyPublisherViews(published: ReadonlyArray<Pick<Clip, 'id' | 'publisherViews' | 'publisherLastViewedAt'>>): void {
+      const byId = new Map(published.map((row) => [row.id, row]));
+      for (const clip of this.items) {
+        const fresh = byId.get(clip.id);
+        if (!fresh) continue;
+        clip.publisherViews = fresh.publisherViews ?? null;
+        clip.publisherLastViewedAt = fresh.publisherLastViewedAt ?? null;
+      }
+    },
+
     updateClip(updatedClip: Clip): void {
       const index = this.items.findIndex(clip => clip.id === updatedClip.id);
       if (index !== -1) {
diff --git a/src/renderer/src/utils/viewCount.ts b/src/renderer/src/utils/viewCount.ts
new file mode 100644
index 00000000..75dbe20a
--- /dev/null
+++ b/src/renderer/src/utils/viewCount.ts
@@ -0,0 +1,20 @@
+import { pluralize } from './pluralize';
+
+/**
+ * What a library card says about how often a published clip has been watched.
+ *
+ * **Null says nothing.** It means nobody has counted: a publisher older than
+ * the counter, or no sync yet. A number there would be invented.
+ *
+ * **Zero says nothing either, on a card.** The counter started at zero for
+ * every clip on the day it shipped, so a card cannot tell "nobody opened it"
+ * from "nothing was counting then", and a tile is no place to explain the
+ * difference. The Publisher screen knows `countingSince` and says both.
+ *
+ * Grouped digits because a clip that went round a Discord can reach four.
+ */
+export function viewCountLabel(views: number | null | undefined): string {
+  if (views == null || !Number.isFinite(views) || views <= 0) return '';
+  const whole = Math.floor(views);
+  return `${whole.toLocaleString('en-US')} ${pluralize(whole, 'view')}`;
+}
diff --git a/src/renderer/src/views/ClipsPage.vue b/src/renderer/src/views/ClipsPage.vue
index 9be8ca2d..464ac7ca 100644
--- a/src/renderer/src/views/ClipsPage.vue
+++ b/src/renderer/src/views/ClipsPage.vue
@@ -11,6 +11,7 @@ import { useBatchOperations } from '@renderer/composables/library/useBatchOperat
 import { useClipListKeyboardShortcuts } from '@renderer/composables/library/useClipListKeyboardShortcuts';
 import { useClipListHandlers } from '@renderer/composables/library/useClipListHandlers';
 import { useLibraryRescan } from '@renderer/composables/library/useLibraryRescan';
+import { useLibraryViewCounts } from '@renderer/composables/library/useLibraryViewCounts';
 import { useSelectAllShortcut } from '@renderer/composables/ui/useSelectAllShortcut';
 import { useScrolledPage } from '@renderer/composables/ui/useScrolledPage';
 import type { Clip } from '@renderer/types/clip';
@@ -28,6 +29,8 @@ const gamesStore = useGamesStore();
 const config = useConfiguration();
 const { getVideoUrl, getThumbUrl } = useClipHandlers();
 const { rescan } = useLibraryRescan();
+// The view counts on published cards, refreshed while the library is looked at.
+useLibraryViewCounts();
 
 /** The shell follows the scroll; this row only reads it. */
 const { scrolled } = useScrolledPage();
diff --git a/tests/unit/main/publisherStatsFreshness.spec.ts b/tests/unit/main/publisherStatsFreshness.spec.ts
new file mode 100644
index 00000000..7117743f
--- /dev/null
+++ b/tests/unit/main/publisherStatsFreshness.spec.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { statsAreStale } from '../../../src/main/services/publisherStatsFreshness';
+
+/**
+ * When the library asks the publisher for new view counts.
+ *
+ * It asks on every open and every focus, so this is what keeps that from
+ * being a request over somebody's home uplink on every alt-tab.
+ */
+describe('statsAreStale', () => {
+  const minute = 60_000;
+
+  it('asks when nobody has asked yet', () => {
+    expect(statsAreStale(null, 1_000, 10 * minute)).toBe(true);
+  });
+
+  it('does not ask again inside the window', () => {
+    expect(statsAreStale(0, 10 * minute - 1, 10 * minute)).toBe(false);
+  });
+
+  it('asks again once the window has passed', () => {
+    expect(statsAreStale(0, 10 * minute, 10 * minute)).toBe(true);
+  });
+
+  it('asks when the clock went backwards rather than trusting it for ever', () => {
+    expect(statsAreStale(10 * minute, 0, 10 * minute)).toBe(true);
+  });
+});
diff --git a/tests/unit/renderer/viewCount.spec.ts b/tests/unit/renderer/viewCount.spec.ts
new file mode 100644
index 00000000..e9397668
--- /dev/null
+++ b/tests/unit/renderer/viewCount.spec.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { viewCountLabel } from '../../../src/renderer/src/utils/viewCount';
+
+/**
+ * The view count on a library card.
+ *
+ * Null and zero are the two that matter: both say nothing on a card, because
+ * a card cannot tell "never opened" from "nothing was counting yet".
+ */
+describe('viewCountLabel', () => {
+  it('says nothing when nobody has counted', () => {
+    expect(viewCountLabel(null)).toBe('');
+    expect(viewCountLabel(undefined)).toBe('');
+  });
+
+  it('says nothing for zero, which a card cannot tell from "not counted then"', () => {
+    expect(viewCountLabel(0)).toBe('');
+  });
+
+  it('says nothing for a number that is not one', () => {
+    expect(viewCountLabel(Number.NaN)).toBe('');
+    expect(viewCountLabel(-3)).toBe('');
+  });
+
+  it('is singular for one', () => {
+    expect(viewCountLabel(1)).toBe('1 view');
+  });
+
+  it('is plural and grouped above that', () => {
+    expect(viewCountLabel(37)).toBe('37 views');
+    expect(viewCountLabel(1234)).toBe('1,234 views');
+  });
+});