From 2818083583740a9d4ecfa7f7a4d175765a8e61ac Mon Sep 17 00:00:00 2001
From: Bryon Lewis <Bryon.Lewis@kitware.com>
Date: Tue, 29 Sep 2026 11:26:22 -0400
Subject: [PATCH 1/4] add review settings

---
 .../components/UserSettingsDialog.vue         | 37 +++++++++++++-
 client/dive-common/review/reviewItems.ts      | 13 +++++
 client/dive-common/review/reviewSettings.ts   | 51 +++++++++++++++++++
 client/dive-common/review/types.ts            | 23 +++++++++
 4 files changed, 123 insertions(+), 1 deletion(-)
 create mode 100644 client/dive-common/review/reviewSettings.ts

diff --git a/client/dive-common/components/UserSettingsDialog.vue b/client/dive-common/components/UserSettingsDialog.vue
index 93ca3e37e..a7aa037b5 100644
--- a/client/dive-common/components/UserSettingsDialog.vue
+++ b/client/dive-common/components/UserSettingsDialog.vue
@@ -1,8 +1,9 @@
 <script lang="ts">
-import { defineComponent } from 'vue';
+import { defineComponent, PropType } from 'vue';
 import { clientSettings } from 'dive-common/store/settings';
 import isDesktopRuntime from 'dive-common/isDesktopRuntime';
 import type { GlobalStyleSettings } from 'dive-common/apispec';
+import type { ReviewSettings } from 'dive-common/review/types';
 import SavedStylesEditor from './Types/SavedStylesEditor.vue';
 
 export default defineComponent({
@@ -13,6 +14,11 @@ export default defineComponent({
       type: Boolean,
       required: true,
     },
+    /** When set, shows review chip-grid options at the top of the dialog. */
+    reviewSettings: {
+      type: Object as PropType<ReviewSettings | null>,
+      default: null,
+    },
   },
   setup(_, { emit }) {
     const colorScopeItems = [
@@ -41,6 +47,35 @@ export default defineComponent({
     <v-card>
       <v-card-title>User Settings</v-card-title>
       <v-card-text>
+        <template v-if="reviewSettings">
+          <div class="text-subtitle-2 mb-2">
+            Review
+          </div>
+          <v-switch
+            v-model="reviewSettings.activateOnHover"
+            color="primary"
+            class="my-0"
+            label="Load and animate extra frames on hover"
+            hint="When on, the first frame of every chip still loads; additional track frames download and cycle only while the pointer is over the entry."
+            persistent-hint
+          />
+          <v-text-field
+            v-model.number="reviewSettings.playbackFps"
+            color="primary"
+            class="my-0 mt-3"
+            type="number"
+            min="0"
+            max="60"
+            step="1"
+            label="Chip playback (frames per second)"
+            hint="0 = real-time from each dataset's frame rate and the spacing between sampled keyframes."
+            persistent-hint
+            dense
+            outlined
+          />
+          <v-divider class="my-4" />
+        </template>
+
         <v-select
           v-model="clientSettings.typeSettings.colorScope"
           :items="colorScopeItems"
diff --git a/client/dive-common/review/reviewItems.ts b/client/dive-common/review/reviewItems.ts
index 6d4ec805e..1b6f5da5f 100644
--- a/client/dive-common/review/reviewItems.ts
+++ b/client/dive-common/review/reviewItems.ts
@@ -87,6 +87,19 @@ export function cycleIntervalFor(frames: readonly ReviewFrameRef[], fps: number,
   return Math.min(2000, Math.max(33, Math.round((stride / fps) * 1000)));
 }
 
+/** Milliseconds between cycled chip frames from review playback settings. */
+export function chipCycleIntervalMs(
+  frames: readonly ReviewFrameRef[],
+  datasetFps: number,
+  playbackFps: number,
+  fallbackMs: number,
+): number {
+  if (playbackFps > 0) {
+    return Math.min(2000, Math.max(33, Math.round(1000 / playbackFps)));
+  }
+  return cycleIntervalFor(frames, datasetFps, fallbackMs);
+}
+
 /** The pair a type query matches on, or null when the track does not qualify. */
 export function matchTypePair(
   pairs: readonly (readonly [string, number])[],
diff --git a/client/dive-common/review/reviewSettings.ts b/client/dive-common/review/reviewSettings.ts
new file mode 100644
index 000000000..faea80038
--- /dev/null
+++ b/client/dive-common/review/reviewSettings.ts
@@ -0,0 +1,51 @@
+/**
+ * Review behaviour settings shared by every chip grid and remembered per browser.
+ */
+import { reactive, watch } from 'vue';
+import {
+  DEFAULT_REVIEW_SETTINGS, REVIEW_PLAYBACK_FPS_LIMITS, ReviewSettings,
+} from './types';
+
+const SETTINGS_STORAGE_KEY = 'dive.review.settings';
+
+export function loadReviewSettings(): ReviewSettings {
+  try {
+    const raw = window.localStorage.getItem(SETTINGS_STORAGE_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object') {
+        return { ...DEFAULT_REVIEW_SETTINGS, ...parsed };
+      }
+    }
+  } catch {
+    // Storage may be unavailable; defaults are fine.
+  }
+  return { ...DEFAULT_REVIEW_SETTINGS };
+}
+
+export function storeReviewSettings(settings: ReviewSettings) {
+  try {
+    window.localStorage.setItem(SETTINGS_STORAGE_KEY, JSON.stringify(settings));
+  } catch {
+    // Ignore storage failures.
+  }
+}
+
+export function normalizeReviewSettings(settings: ReviewSettings): ReviewSettings {
+  const [minFps, maxFps] = REVIEW_PLAYBACK_FPS_LIMITS.fps;
+  const rawFps = Number(settings.playbackFps);
+  const playbackFps = Number.isFinite(rawFps)
+    ? Math.min(maxFps, Math.max(minFps, Math.round(rawFps)))
+    : DEFAULT_REVIEW_SETTINGS.playbackFps;
+  return {
+    activateOnHover: settings.activateOnHover !== false,
+    playbackFps,
+  };
+}
+
+/** A reactive settings object seeded from storage and written back on change. */
+export function usePersistentReviewSettings(): ReviewSettings {
+  const settings = reactive<ReviewSettings>(normalizeReviewSettings(loadReviewSettings()));
+  watch(settings, () => storeReviewSettings({ ...settings }), { deep: true });
+  return settings;
+}
diff --git a/client/dive-common/review/types.ts b/client/dive-common/review/types.ts
index 890c1fbd2..fac24a33b 100644
--- a/client/dive-common/review/types.ts
+++ b/client/dive-common/review/types.ts
@@ -124,6 +124,29 @@ export const DEFAULT_REVIEW_GRID: ReviewGridSettings = {
   maxSequenceFrames: 8,
 };
 
+/** Behaviour settings for chip grids (Review, search results, and similar). */
+export interface ReviewSettings {
+  /**
+   * When true, extra sequence frames load and cycle only while the pointer
+   * is over the entry; the primary chip still loads for every visible entry.
+   */
+  activateOnHover: boolean;
+  /**
+   * Fixed cycling rate in frames per second. 0 keeps real-time playback from
+   * each dataset's frame rate and the spacing of sampled keyframes.
+   */
+  playbackFps: number;
+}
+
+export const DEFAULT_REVIEW_SETTINGS: ReviewSettings = {
+  activateOnHover: true,
+  playbackFps: 1,
+};
+
+export const REVIEW_PLAYBACK_FPS_LIMITS = {
+  fps: [0, 60] as const,
+};
+
 export const REVIEW_GRID_LIMITS = {
   columns: [1, 12] as const,
   rows: [1, 10] as const,

From 57330480eca2c5c822e5456ea815ea5737ae1149 Mon Sep 17 00:00:00 2001
From: Bryon Lewis <Bryon.Lewis@kitware.com>
Date: Tue, 29 Sep 2026 11:26:51 -0400
Subject: [PATCH 2/4] connect review settings to the viewer

---
 .../components/Review/ReviewCell.vue          | 20 ++++++++-
 .../components/Review/ReviewChip.vue          | 26 ++++++++---
 .../components/Review/ReviewPage.vue          | 25 ++++++++++-
 client/dive-common/review/useReviewGrid.ts    | 45 ++++++++++++++++---
 client/dive-common/use/useReview.ts           |  5 +++
 .../desktop/frontend/components/QueryPage.vue | 17 +++++++
 6 files changed, 121 insertions(+), 17 deletions(-)

diff --git a/client/dive-common/components/Review/ReviewCell.vue b/client/dive-common/components/Review/ReviewCell.vue
index 5b968c70b..cf99063f4 100644
--- a/client/dive-common/components/Review/ReviewCell.vue
+++ b/client/dive-common/components/Review/ReviewCell.vue
@@ -81,6 +81,10 @@ export default defineComponent({
       type: Boolean,
       default: true,
     },
+    activateOnHover: {
+      type: Boolean,
+      default: false,
+    },
     cycleIntervalMs: {
       type: Number,
       default: 400,
@@ -152,6 +156,8 @@ export default defineComponent({
   setup(props, { emit }) {
     /** Chips currently in edit mode, to outline the whole entry. */
     const editingCount = ref(0);
+    const hovered = ref(false);
+    const cycling = computed(() => props.animate && (!props.activateOnHover || hovered.value));
 
     const viewList = computed<ReviewCellView[]>(() => props.views ?? [{
       key: 'single',
@@ -196,7 +202,7 @@ export default defineComponent({
     }
 
     function syncSharedTimer() {
-      const shouldRun = shared.value && props.animate && sequenceLength.value > 1
+      const shouldRun = shared.value && cycling.value && sequenceLength.value > 1
         && !sharedPaused.value && editingCount.value === 0;
       if (shouldRun && timer === null) {
         timer = window.setInterval(() => advanceShared(1), props.cycleIntervalMs);
@@ -206,7 +212,7 @@ export default defineComponent({
       }
     }
     watch(
-      [shared, () => props.animate, sequenceLength, sharedPaused, editingCount, () => props.cycleIntervalMs],
+      [shared, cycling, sequenceLength, sharedPaused, editingCount, () => props.cycleIntervalMs],
       () => {
         if (timer !== null) {
           window.clearInterval(timer);
@@ -233,9 +239,16 @@ export default defineComponent({
       if (next !== props.type) emit('assign', next);
     }
 
+    function onHoverChange(active: boolean) {
+      hovered.value = active;
+      emit('hover-change', active);
+    }
+
     return {
       viewList,
       editingCount,
+      hovered,
+      onHoverChange,
       commitType,
       shared,
       sharedSlot,
@@ -258,6 +271,8 @@ export default defineComponent({
       'cell-negative': highlight === 'negative',
     }"
     :style="{ '--cell-scale': scale }"
+    @mouseenter="onHoverChange(true)"
+    @mouseleave="onHoverChange(false)"
   >
     <div class="cell-views">
       <ReviewChip
@@ -272,6 +287,7 @@ export default defineComponent({
         :frame-count="view.frameCount"
         :label="view.label"
         :animate="animate"
+        :activate-on-hover="activateOnHover"
         :cycle-interval-ms="cycleIntervalMs"
         :type="type"
         :confidence="index === 0 ? confidence : null"
diff --git a/client/dive-common/components/Review/ReviewChip.vue b/client/dive-common/components/Review/ReviewChip.vue
index 65c0adf9d..a8774eaf6 100644
--- a/client/dive-common/components/Review/ReviewChip.vue
+++ b/client/dive-common/components/Review/ReviewChip.vue
@@ -90,6 +90,11 @@ export default defineComponent({
       type: Boolean,
       default: true,
     },
+    /** When true with {@link animate}, cycling runs only while the pointer is over the chip. */
+    activateOnHover: {
+      type: Boolean,
+      default: false,
+    },
     cycleIntervalMs: {
       type: Number,
       default: 400,
@@ -196,6 +201,8 @@ export default defineComponent({
     const ownView = ref<ChipView>({ scale: 1, x: 0, y: 0 });
     const view = computed<ChipView>(() => props.controlledView ?? ownView.value);
     const wrap = ref<HTMLElement | null>(null);
+    const hovered = ref(false);
+    const cycling = computed(() => props.animate && (!props.activateOnHover || hovered.value));
     let pan: {
       startX: number; startY: number; originX: number; originY: number; pointerId: number; capture: Element | null;
     } | null = null;
@@ -210,10 +217,10 @@ export default defineComponent({
     }, { immediate: true });
 
     /** Sequence slot on screen; 0 while only the primary chip is available. */
-    const currentSlot = computed(() => (hasSequence.value && props.animate ? cycleIndex.value : 0));
+    const currentSlot = computed(() => (hasSequence.value && cycling.value ? cycleIndex.value : 0));
 
     const displaySrc = computed(() => {
-      if (hasSequence.value && props.animate) {
+      if (hasSequence.value && cycling.value) {
         return props.srcs?.[cycleIndex.value] ?? props.src;
       }
       return props.src;
@@ -221,7 +228,7 @@ export default defineComponent({
 
     /** Transform of the chip on screen (the primary's when a slot is still loading). */
     const displayTransform = computed<ChipTransform | null>(() => {
-      if (hasSequence.value && props.animate) {
+      if (hasSequence.value && cycling.value) {
         const slotSrc = props.srcs?.[cycleIndex.value];
         if (slotSrc) return props.transforms?.[cycleIndex.value] ?? null;
       }
@@ -253,7 +260,7 @@ export default defineComponent({
     }
 
     function syncTimer() {
-      const shouldRun = props.animate && hasSequence.value && !editing.value && !paused.value
+      const shouldRun = cycling.value && hasSequence.value && !editing.value && !paused.value
         && !controlled.value;
       if (shouldRun && timer === null) {
         timer = window.setInterval(advance, props.cycleIntervalMs);
@@ -263,7 +270,7 @@ export default defineComponent({
         if (!editing.value && !paused.value) cycleIndex.value = 0;
       }
     }
-    watch([() => props.animate, () => props.srcs, () => props.cycleIntervalMs, editing, paused], () => {
+    watch([cycling, () => props.srcs, () => props.cycleIntervalMs, editing, paused], () => {
       if (timer !== null) {
         window.clearInterval(timer);
         timer = null;
@@ -722,6 +729,7 @@ export default defineComponent({
       onWrapPointerUp,
       missing,
       addBox,
+      hovered,
     };
   },
 });
@@ -731,8 +739,10 @@ export default defineComponent({
   <div
     ref="wrap"
     class="cell-image-wrap"
-    :class="{ 'chip-editing': editing }"
+    :class="{ 'chip-editing': editing, 'chip-hovered': hovered }"
     :aria-label="title"
+    @mouseenter="hovered = true"
+    @mouseleave="hovered = false"
     @dblclick="onImageDoubleClick"
     @contextmenu="onContextMenu"
     @wheel="onWheel"
@@ -1109,6 +1119,10 @@ export default defineComponent({
   cursor: pointer;
   min-width: 0;
   flex: 1 1 0;
+
+  &.chip-hovered {
+    box-shadow: inset 0 0 0 2px #90caf9;
+  }
 }
 
 .cell-image-wrap.chip-editing {
diff --git a/client/dive-common/components/Review/ReviewPage.vue b/client/dive-common/components/Review/ReviewPage.vue
index fecc106c7..d77f1eeb9 100644
--- a/client/dive-common/components/Review/ReviewPage.vue
+++ b/client/dive-common/components/Review/ReviewPage.vue
@@ -10,7 +10,7 @@ import { usePrompt } from 'dive-common/vue-utilities/prompt-service';
 import { createReviewService, provideReview } from 'dive-common/use/useReview';
 import { useReviewGrid } from 'dive-common/review/useReviewGrid';
 import { cellScaleFor } from 'dive-common/review/gridSettings';
-import { cycleIntervalFor } from 'dive-common/review/reviewItems';
+import { chipCycleIntervalMs } from 'dive-common/review/reviewItems';
 import {
   holdReviewSession, sessionKey, shouldResume, takeReviewSession,
 } from 'dive-common/review/reviewSession';
@@ -90,6 +90,7 @@ export default defineComponent({
     const opening = ref(!hasReady && initialIds.length > 0);
     const pageTypeInput = ref('');
     const showSettings = ref(false);
+    const hoveredEntryKeys = ref(new Set<string>());
     const typeField = ref<{ isMenuActive: boolean; activateMenu(): void; blur(): void } | null>(null);
 
     /** The type field's arrow opens its list, and closes it again on a second press. */
@@ -117,7 +118,18 @@ export default defineComponent({
       outline: '',
       // Deleting or editing an entry keeps the page; only a new query resets it.
       retainPage: true,
+      activateOnHover: computed(() => review.settings.activateOnHover),
+      hoverEntryKeys: hoveredEntryKeys,
+      entryKeyOf: (entry) => entry.key,
     });
+
+    function setEntryHovered(key: string, hovered: boolean) {
+      const next = new Set(hoveredEntryKeys.value);
+      if (hovered) next.add(key);
+      else next.delete(key);
+      hoveredEntryKeys.value = next;
+      grid.ensureVisible();
+    }
     watch(review.queryGeneration, () => grid.goToPage(0));
 
     const showDatasetNames = computed(() => review.datasets.value.length > 1);
@@ -163,7 +175,12 @@ export default defineComponent({
           title: `${review.datasetName(parent)} · track ${item.trackId} · frame ${item.primary.frame}`,
           subtitle: subtitleBits.join(' · '),
           attributeText,
-          cycleIntervalMs: cycleIntervalFor(item.frames, fps, review.grid.cycleIntervalMs),
+          cycleIntervalMs: chipCycleIntervalMs(
+            item.frames,
+            fps,
+            review.settings.playbackFps,
+            review.grid.cycleIntervalMs,
+          ),
         };
       });
     });
@@ -424,6 +441,7 @@ export default defineComponent({
       countLabel,
       pageTypeInput,
       showSettings,
+      setEntryHovered,
       setView,
       openItem,
       openDataset,
@@ -806,7 +824,9 @@ export default defineComponent({
             :key="cell.entry.key"
             :views="cell.views"
             :animate="true"
+            :activate-on-hover="review.settings.activateOnHover"
             :cycle-interval-ms="cell.cycleIntervalMs"
+            @hover-change="setEntryHovered(cell.entry.key, $event)"
             :scale="cellScale"
             :color="review.colorFor(cell.type)"
             :type="cell.type"
@@ -829,6 +849,7 @@ export default defineComponent({
 
     <UserSettingsDialog
       :value="showSettings"
+      :review-settings="review.settings"
       @input="showSettings = $event"
     />
 
diff --git a/client/dive-common/review/useReviewGrid.ts b/client/dive-common/review/useReviewGrid.ts
index fb238cd36..c0ae17a33 100644
--- a/client/dive-common/review/useReviewGrid.ts
+++ b/client/dive-common/review/useReviewGrid.ts
@@ -6,7 +6,7 @@
  * visible page (plus a prefetch of the next one).
  */
 import {
-  computed, ref, Ref, unref, watch,
+  computed, ref, Ref, unref, watch, isRef,
 } from 'vue';
 import { debounce } from 'lodash';
 import type { ChipStore } from './chipStore';
@@ -45,6 +45,15 @@ export interface ReviewGridOptions<T> {
    * returning to the first one, for lists that shrink as entries are hidden.
    */
   retainPage?: boolean;
+  /**
+   * When true, only sequence frames wait for hover; primary chips still load
+   * for the visible page (and the next page when prefetching).
+   */
+  activateOnHover?: Ref<boolean> | boolean;
+  /** Keys of entries currently under the pointer (see {@link entryKeyOf}). */
+  hoverEntryKeys?: Ref<ReadonlySet<string>>;
+  /** Stable key for a grid entry; defaults to `entry.key`. */
+  entryKeyOf?: (entry: T) => string;
 }
 
 /** How long paging must be idle before chips load, so skipped pages never render. */
@@ -55,10 +64,27 @@ export function useReviewGrid<T = ReviewItem>(options: ReviewGridOptions<T>) {
     items, grid, chipStore, active,
   } = options;
   const chipItemsOf = options.chipItemsOf ?? ((entry: T) => [entry as unknown as ReviewItem]);
+  const entryKeyOf = options.entryKeyOf ?? ((entry: T) => (entry as { key: string }).key);
   const chipItems = (entries: readonly T[]) => entries.flatMap((entry) => chipItemsOf(entry));
   const page = ref(0);
   const cellSize = ref({ width: 0, height: 0 });
 
+  const activateOnHover = computed(() => (
+    isRef(options.activateOnHover) ? options.activateOnHover.value : options.activateOnHover ?? false
+  ));
+
+  function primaryItemsToLoad(includePrefetch: boolean): readonly ReviewItem[] {
+    const list = chipItems(pageItems.value);
+    if (activateOnHover.value || !includePrefetch) return list;
+    return [...list, ...chipItems(nextPageItems.value)];
+  }
+
+  function sequenceEntriesToLoad(): readonly T[] {
+    if (!activateOnHover.value || !options.hoverEntryKeys) return pageItems.value;
+    const hovered = options.hoverEntryKeys.value;
+    return pageItems.value.filter((entry) => hovered.has(entryKeyOf(entry)));
+  }
+
   const perPage = computed(() => grid.columns * grid.rows);
   const pageCount = computed(() => Math.max(1, Math.ceil(items.value.length / perPage.value)));
   const pageItems = computed(() => items.value.slice(page.value * perPage.value, (page.value + 1) * perPage.value));
@@ -66,11 +92,12 @@ export function useReviewGrid<T = ReviewItem>(options: ReviewGridOptions<T>) {
 
   function ensureVisible() {
     if (!active.value) return;
-    const visible = chipItems(pageItems.value);
-    const prefetch = chipItems(nextPageItems.value);
-    chipStore.trimQueues(new Set([...visible, ...prefetch].map((i) => i.key)));
-    chipStore.ensurePrimary([...visible, ...prefetch]);
-    chipStore.ensureSequences(visible);
+    const primary = primaryItemsToLoad(!activateOnHover.value);
+    const sequences = chipItems(sequenceEntriesToLoad());
+    const protectedKeys = new Set([...primary, ...sequences].map((i) => i.key));
+    chipStore.trimQueues(protectedKeys);
+    chipStore.ensurePrimary(primary);
+    chipStore.ensureSequences(sequences);
   }
 
   const applyChipOptions = debounce(() => {
@@ -93,13 +120,17 @@ export function useReviewGrid<T = ReviewItem>(options: ReviewGridOptions<T>) {
   const ensureVisibleSettled = debounce(ensureVisible, PAGE_SETTLE_MS);
   function onPageChanged() {
     if (!active.value) return;
-    chipStore.trimQueues(new Set(chipItems(pageItems.value).map((i) => i.key)));
+    chipStore.trimQueues(new Set(primaryItemsToLoad(false).map((i) => i.key)));
     ensureVisibleSettled();
   }
 
   watch(() => [grid.padding, cellSize.value.width, cellSize.value.height, unref(options.footerPx)], applyChipOptions);
   watch(page, onPageChanged);
   watch(active, ensureVisible);
+  if (options.hoverEntryKeys) {
+    watch([options.hoverEntryKeys, activateOnHover], ensureVisible, { deep: true });
+  }
+  watch(activateOnHover, ensureVisible);
   watch(items, () => {
     page.value = options.retainPage ? Math.min(page.value, pageCount.value - 1) : 0;
     ensureVisible();
diff --git a/client/dive-common/use/useReview.ts b/client/dive-common/use/useReview.ts
index fea365578..6acb48f6a 100644
--- a/client/dive-common/use/useReview.ts
+++ b/client/dive-common/use/useReview.ts
@@ -26,6 +26,7 @@ import {
   frameRefFor, groupReviewItems, sortReviewItems,
 } from 'dive-common/review/reviewItems';
 import { usePersistentGridSettings } from 'dive-common/review/gridSettings';
+import { usePersistentReviewSettings } from 'dive-common/review/reviewSettings';
 import {
   DEFAULT_REVIEW_QUERY,
   ReviewEntry,
@@ -33,6 +34,7 @@ import {
   ReviewItem,
   ReviewPolygon,
   ReviewQuery,
+  ReviewSettings,
   ReviewSortOrder,
 } from 'dive-common/review/types';
 
@@ -74,6 +76,7 @@ export interface ReviewService {
   available: Readonly<Ref<ScoringDatasetSummary[]>>;
   query: ReviewQuery;
   grid: ReviewGridSettings;
+  settings: ReviewSettings;
   sort: Ref<ReviewSortOrder>;
   items: Readonly<Ref<ReviewItem[]>>;
   /** Items grouped into grid entries (one per track across its cameras). */
@@ -247,6 +250,7 @@ function createScopedReviewService(deps: ReviewServiceDeps): ReviewService {
   const available = ref<ScoringDatasetSummary[]>([]);
   const query = reactive<ReviewQuery>({ ...DEFAULT_REVIEW_QUERY });
   const grid = usePersistentGridSettings();
+  const settings = usePersistentReviewSettings();
   const sort = ref<ReviewSortOrder>('confidence-desc');
   const items = ref<ReviewItem[]>([]);
   const dataRevision = ref(0);
@@ -888,6 +892,7 @@ function createScopedReviewService(deps: ReviewServiceDeps): ReviewService {
     available,
     query,
     grid,
+    settings,
     sort,
     items,
     entries,
diff --git a/client/platform/desktop/frontend/components/QueryPage.vue b/client/platform/desktop/frontend/components/QueryPage.vue
index 565143b42..f2d100e0f 100644
--- a/client/platform/desktop/frontend/components/QueryPage.vue
+++ b/client/platform/desktop/frontend/components/QueryPage.vue
@@ -13,6 +13,7 @@ import { createItemChips, createSearchChips } from 'platform/desktop/frontend/us
 import { createSearchReview, OverlapChoice, OverlapSummary } from 'platform/desktop/frontend/useSearchReview';
 import { holdQuerySession, takeQuerySession } from 'platform/desktop/frontend/querySession';
 import { usePersistentGridSettings } from 'dive-common/review/gridSettings';
+import { usePersistentReviewSettings } from 'dive-common/review/reviewSettings';
 import { useReviewGrid } from 'dive-common/review/useReviewGrid';
 import { reviewViewerLocation } from 'dive-common/review/viewerNavigation';
 import type { ReviewItem } from 'dive-common/review/types';
@@ -89,6 +90,8 @@ export default defineComponent({
     const textChips = resumed?.textChips ?? createItemChips(page.textItems);
     const resultsMemory = resumed?.results ?? reactive({ page: 0, hideReviewed: false });
     const gridSettings = usePersistentGridSettings();
+    const reviewSettings = usePersistentReviewSettings();
+    const hoveredTextEntryKeys = ref(new Set<string>());
     const textGridActive = computed(() => view.value === 'query' && page.mode.value === 'text');
     const textGrid = useReviewGrid({
       items: page.textItems,
@@ -97,8 +100,18 @@ export default defineComponent({
       active: textGridActive,
       footerPx: TextCellFooterPx,
       outline: '',
+      activateOnHover: computed(() => reviewSettings.activateOnHover),
+      hoverEntryKeys: hoveredTextEntryKeys,
     });
 
+    function setTextEntryHovered(key: string, hovered: boolean) {
+      const next = new Set(hoveredTextEntryKeys.value);
+      if (hovered) next.add(key);
+      else next.delete(key);
+      hoveredTextEntryKeys.value = next;
+      textGrid.ensureVisible();
+    }
+
     const imageUrl = ref('');
     watch(page.imagePath, async (path) => {
       imageUrl.value = path ? await getMediaUrl(path) : '';
@@ -308,6 +321,8 @@ export default defineComponent({
       chooseOverlap,
       textChips,
       gridSettings,
+      reviewSettings,
+      setTextEntryHovered,
       textGrid,
       textCells,
       textCountLabel,
@@ -838,7 +853,9 @@ export default defineComponent({
                       :frames="cell.item.frames"
                       :failure="textChips.store.failures.value[cell.item.key] || null"
                       :animate="false"
+                      :activate-on-hover="reviewSettings.activateOnHover"
                       :type="cell.item.type"
+                      @hover-change="setTextEntryHovered(cell.item.key, $event)"
                       :confidence="cell.item.confidence"
                       :title="cell.title"
                       :subtitle="cell.subtitle"

From 4a416c21646796cd4e9817360a6227324970f663 Mon Sep 17 00:00:00 2001
From: Bryon Lewis <Bryon.Lewis@kitware.com>
Date: Tue, 29 Sep 2026 11:29:48 -0400
Subject: [PATCH 3/4] documentation, add to Video search

---
 client/dive-common/review/reviewItems.spec.ts | 14 ++++++++++
 .../components/VideoSearchResultsGrid.vue     | 26 ++++++++++++++++++-
 docs/Review.md                                |  2 +-
 3 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/client/dive-common/review/reviewItems.spec.ts b/client/dive-common/review/reviewItems.spec.ts
index 559234227..ca4b6c211 100644
--- a/client/dive-common/review/reviewItems.spec.ts
+++ b/client/dive-common/review/reviewItems.spec.ts
@@ -4,6 +4,7 @@ import {
   buildReviewItems,
   collectAttributeKeys,
   collectTypes,
+  chipCycleIntervalMs,
   cycleIntervalFor,
   frameGeometry,
   groupReviewItems,
@@ -201,6 +202,19 @@ describe('frameGeometry', () => {
   });
 });
 
+describe('chipCycleIntervalMs', () => {
+  const frames = [0, 1, 2, 3].map((frame) => ({ frame, bounds: [0, 0, 1, 1] as [number, number, number, number] }));
+
+  it('uses a fixed rate when playback fps is set', () => {
+    expect(chipCycleIntervalMs(frames, 10, 10, 400)).toBe(100);
+    expect(chipCycleIntervalMs(frames, 10, 4, 400)).toBe(250);
+  });
+
+  it('falls back to real-time when playback fps is zero', () => {
+    expect(chipCycleIntervalMs(frames, 10, 0, 400)).toBe(100);
+  });
+});
+
 describe('cycleIntervalFor', () => {
   it('plays consecutive frames at the dataset rate and sparse samples proportionally slower', () => {
     const consecutive = [0, 1, 2, 3].map((frame) => ({ frame, bounds: [0, 0, 1, 1] as [number, number, number, number] }));
diff --git a/client/platform/desktop/frontend/components/VideoSearchResultsGrid.vue b/client/platform/desktop/frontend/components/VideoSearchResultsGrid.vue
index 29c06b8d2..82cc57dac 100644
--- a/client/platform/desktop/frontend/components/VideoSearchResultsGrid.vue
+++ b/client/platform/desktop/frontend/components/VideoSearchResultsGrid.vue
@@ -11,7 +11,9 @@ import type { ResultsGridMemory } from 'platform/desktop/frontend/querySession';
 import { useReview } from 'dive-common/use/useReview';
 import type { ReviewService } from 'dive-common/use/useReview';
 import { usePersistentGridSettings } from 'dive-common/review/gridSettings';
+import { usePersistentReviewSettings } from 'dive-common/review/reviewSettings';
 import { useReviewGrid } from 'dive-common/review/useReviewGrid';
+import { chipCycleIntervalMs } from 'dive-common/review/reviewItems';
 import type { ReviewItem } from 'dive-common/review/types';
 import type { VideoSearchResult } from 'dive-common/apispec';
 import ReviewGrid from 'dive-common/components/Review/ReviewGrid.vue';
@@ -67,6 +69,8 @@ export default defineComponent({
     const review: ReviewService | null = props.searchReview ? useReview() : null;
     const { prompt } = usePrompt();
     const gridSettings = usePersistentGridSettings();
+    const reviewSettings = usePersistentReviewSettings();
+    const hoveredEntryKeys = ref(new Set<string>());
     const open = computed(() => props.inline || props.value);
 
     const state = computed(() => search?.state ?? null);
@@ -90,7 +94,17 @@ export default defineComponent({
       // The box is drawn over the chip so it follows edits.
       outline: '',
       retainPage: true,
+      activateOnHover: computed(() => reviewSettings.activateOnHover),
+      hoverEntryKeys: hoveredEntryKeys,
     });
+
+    function setEntryHovered(key: string, hovered: boolean) {
+      const next = new Set(hoveredEntryKeys.value);
+      if (hovered) next.add(key);
+      else next.delete(key);
+      hoveredEntryKeys.value = next;
+      grid.ensureVisible();
+    }
     watch(() => state.value?.queryGeneration, () => grid.goToPage(0));
     if (props.memory) {
       grid.goToPage(props.memory.page);
@@ -133,6 +147,12 @@ export default defineComponent({
           color: review ? review.colorFor(type) : '#00e5ff',
           subtitle: bits.join(' · '),
           title: `${datasetName || 'This dataset'} · frame ${item.primary.frame}`,
+          cycleIntervalMs: chipCycleIntervalMs(
+            item.frames,
+            review?.datasetFps(item.datasetId) ?? 0,
+            reviewSettings.playbackFps,
+            gridSettings.cycleIntervalMs,
+          ),
         };
       });
     });
@@ -226,7 +246,9 @@ export default defineComponent({
       review,
       open,
       gridSettings,
+      reviewSettings,
       grid,
+      setEntryHovered,
       cells,
       countLabel,
       adjudicationCounts,
@@ -453,7 +475,9 @@ export default defineComponent({
             :frames="cell.item.frames"
             :failure="searchChips.store.failures.value[cell.item.key] || null"
             :animate="open"
-            :cycle-interval-ms="gridSettings.cycleIntervalMs"
+            :activate-on-hover="reviewSettings.activateOnHover"
+            :cycle-interval-ms="cell.cycleIntervalMs"
+            @hover-change="setEntryHovered(cell.item.key, $event)"
             :confidence="cell.item.confidence"
             :frame-count="cell.item.keyframeCount"
             :type="cell.type"
diff --git a/docs/Review.md b/docs/Review.md
index 3f39dfd00..52374a9ef 100644
--- a/docs/Review.md
+++ b/docs/Review.md
@@ -62,7 +62,7 @@ Two query modes are available in the toolbar:
 
 Changes to the query take effect as soon as they settle. The grid otherwise keeps its entries, so editing a type never reshuffles the page you are working on.
 
-The gear next to **Save** opens the same settings as the annotator, including the auto-save switch and delay.
+The gear next to **Save** opens settings: a **Review** section (load and animate extra track frames on hover, on by default—the primary frame of every chip still loads) and chip playback in frames per second (1 by default; 0 = real-time from the dataset), plus the same annotator options as elsewhere, including the auto-save switch and delay.
 
 Entries are sorted by confidence, highest first, by default; the sort field also offers lowest first, dataset and track id, or frame.
 

From 6db21a81a89186d54d3766abf5f4368c08d584c3 Mon Sep 17 00:00:00 2001
From: Bryon Lewis <Bryon.Lewis@kitware.com>
Date: Tue, 29 Sep 2026 11:33:22 -0400
Subject: [PATCH 4/4] fix minor issues

---
 client/dive-common/review/reviewItems.spec.ts |  5 ++
 client/dive-common/review/reviewItems.ts      | 14 +++-
 .../dive-common/review/reviewSettings.spec.ts | 23 ++++++
 client/dive-common/review/reviewSettings.ts   | 19 ++++-
 .../dive-common/review/useReviewGrid.spec.ts  | 77 +++++++++++++++++++
 .../desktop/frontend/components/QueryPage.vue | 17 ----
 6 files changed, 131 insertions(+), 24 deletions(-)
 create mode 100644 client/dive-common/review/reviewSettings.spec.ts
 create mode 100644 client/dive-common/review/useReviewGrid.spec.ts

diff --git a/client/dive-common/review/reviewItems.spec.ts b/client/dive-common/review/reviewItems.spec.ts
index ca4b6c211..7b9bc8009 100644
--- a/client/dive-common/review/reviewItems.spec.ts
+++ b/client/dive-common/review/reviewItems.spec.ts
@@ -213,6 +213,11 @@ describe('chipCycleIntervalMs', () => {
   it('falls back to real-time when playback fps is zero', () => {
     expect(chipCycleIntervalMs(frames, 10, 0, 400)).toBe(100);
   });
+
+  it('clamps playback fps before computing the interval', () => {
+    expect(chipCycleIntervalMs(frames, 10, 120, 400)).toBe(33);
+    expect(chipCycleIntervalMs(frames, 10, -3, 400)).toBe(100);
+  });
 });
 
 describe('cycleIntervalFor', () => {
diff --git a/client/dive-common/review/reviewItems.ts b/client/dive-common/review/reviewItems.ts
index 1b6f5da5f..6f1c4d031 100644
--- a/client/dive-common/review/reviewItems.ts
+++ b/client/dive-common/review/reviewItems.ts
@@ -7,8 +7,9 @@ import type { StringKeyObject } from 'vue-media-annotator/BaseAnnotation';
 import type { Attribute } from 'vue-media-annotator/use/AttributeTypes';
 import { compareTypeNames } from 'dive-common/typeHierarchy';
 import type { RectBounds } from 'vue-media-annotator/utils';
-import type {
-  ReviewEntry, ReviewFrameGeometry, ReviewFrameRef, ReviewItem, ReviewPolygon, ReviewQuery, ReviewSortOrder,
+import {
+  REVIEW_PLAYBACK_FPS_LIMITS,
+  type ReviewEntry, type ReviewFrameGeometry, type ReviewFrameRef, type ReviewItem, type ReviewPolygon, type ReviewQuery, type ReviewSortOrder,
 } from './types';
 
 function isPoint(value: unknown): value is [number, number] {
@@ -94,8 +95,13 @@ export function chipCycleIntervalMs(
   playbackFps: number,
   fallbackMs: number,
 ): number {
-  if (playbackFps > 0) {
-    return Math.min(2000, Math.max(33, Math.round(1000 / playbackFps)));
+  const [minFps, maxFps] = REVIEW_PLAYBACK_FPS_LIMITS.fps;
+  const rawFps = Number(playbackFps);
+  const fps = Number.isFinite(rawFps)
+    ? Math.min(maxFps, Math.max(minFps, Math.round(rawFps)))
+    : 0;
+  if (fps > 0) {
+    return Math.min(2000, Math.max(33, Math.round(1000 / fps)));
   }
   return cycleIntervalFor(frames, datasetFps, fallbackMs);
 }
diff --git a/client/dive-common/review/reviewSettings.spec.ts b/client/dive-common/review/reviewSettings.spec.ts
new file mode 100644
index 000000000..a4fab5a39
--- /dev/null
+++ b/client/dive-common/review/reviewSettings.spec.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeReviewSettings } from './reviewSettings';
+
+describe('normalizeReviewSettings', () => {
+  it('defaults activate on hover and clamps playback fps', () => {
+    expect(normalizeReviewSettings({ activateOnHover: true, playbackFps: 1 })).toEqual({
+      activateOnHover: true,
+      playbackFps: 1,
+    });
+    expect(normalizeReviewSettings({ activateOnHover: false, playbackFps: 4.6 })).toEqual({
+      activateOnHover: false,
+      playbackFps: 5,
+    });
+    expect(normalizeReviewSettings({ activateOnHover: undefined as unknown as boolean, playbackFps: 120 })).toEqual({
+      activateOnHover: true,
+      playbackFps: 60,
+    });
+    expect(normalizeReviewSettings({ activateOnHover: true, playbackFps: Number.NaN })).toEqual({
+      activateOnHover: true,
+      playbackFps: 1,
+    });
+  });
+});
diff --git a/client/dive-common/review/reviewSettings.ts b/client/dive-common/review/reviewSettings.ts
index faea80038..655e0d128 100644
--- a/client/dive-common/review/reviewSettings.ts
+++ b/client/dive-common/review/reviewSettings.ts
@@ -8,6 +8,8 @@ import {
 
 const SETTINGS_STORAGE_KEY = 'dive.review.settings';
 
+let sharedSettings: ReviewSettings | null = null;
+
 export function loadReviewSettings(): ReviewSettings {
   try {
     const raw = window.localStorage.getItem(SETTINGS_STORAGE_KEY);
@@ -43,9 +45,20 @@ export function normalizeReviewSettings(settings: ReviewSettings): ReviewSetting
   };
 }
 
+function applyNormalizedReviewSettings(settings: ReviewSettings) {
+  const normalized = normalizeReviewSettings(settings);
+  if (normalized.playbackFps !== settings.playbackFps
+    || normalized.activateOnHover !== settings.activateOnHover) {
+    Object.assign(settings, normalized);
+  }
+  storeReviewSettings(normalized);
+}
+
 /** A reactive settings object seeded from storage and written back on change. */
 export function usePersistentReviewSettings(): ReviewSettings {
-  const settings = reactive<ReviewSettings>(normalizeReviewSettings(loadReviewSettings()));
-  watch(settings, () => storeReviewSettings({ ...settings }), { deep: true });
-  return settings;
+  if (!sharedSettings) {
+    sharedSettings = reactive<ReviewSettings>(normalizeReviewSettings(loadReviewSettings()));
+    watch(sharedSettings, () => applyNormalizedReviewSettings(sharedSettings!), { deep: true });
+  }
+  return sharedSettings;
 }
diff --git a/client/dive-common/review/useReviewGrid.spec.ts b/client/dive-common/review/useReviewGrid.spec.ts
new file mode 100644
index 000000000..0bd5b24b7
--- /dev/null
+++ b/client/dive-common/review/useReviewGrid.spec.ts
@@ -0,0 +1,77 @@
+import {
+  computed, reactive, ref,
+} from 'vue';
+import {
+  describe, expect, it, vi,
+} from 'vitest';
+import type { ChipStore } from './chipStore';
+import { useReviewGrid } from './useReviewGrid';
+import { DEFAULT_REVIEW_GRID, type ReviewGridSettings, type ReviewItem } from './types';
+
+function reviewItem(key: string, multiFrame = false): ReviewItem {
+  const primary = { frame: 0, bounds: [0, 0, 1, 1] as [number, number, number, number] };
+  const frames = multiFrame
+    ? [primary, { frame: 10, bounds: [0, 0, 1, 1] as [number, number, number, number] }]
+    : [primary];
+  return {
+    key,
+    datasetId: 'd',
+    trackId: 1,
+    primary,
+    frames,
+    keyframeCount: frames.length,
+    type: 'fish',
+    confidence: 0.9,
+  };
+}
+
+function mockChipStore(): { chipStore: ChipStore; ensureSequences: ReturnType<typeof vi.fn> } {
+  const ensureSequences = vi.fn();
+  const chipStore = {
+    ensurePrimary: vi.fn(),
+    ensureSequences,
+    trimQueues: vi.fn(),
+    setOptions: vi.fn(),
+  } as unknown as ChipStore;
+  return { chipStore, ensureSequences };
+}
+
+describe('useReviewGrid sequence loading', () => {
+  it('loads sequence frames for the whole page unless hover mode is on', () => {
+    const items = ref([reviewItem('a', true), reviewItem('b', true)]);
+    const grid = reactive<ReviewGridSettings>({ ...DEFAULT_REVIEW_GRID, columns: 2, rows: 1 });
+    const { chipStore, ensureSequences } = mockChipStore();
+    const controller = useReviewGrid({
+      items,
+      grid,
+      chipStore,
+      active: ref(true),
+      activateOnHover: false,
+    });
+    controller.ensureVisible();
+    const sequences = ensureSequences.mock.calls[0][0] as ReviewItem[];
+    expect(sequences.map((item) => item.key).sort()).toEqual(['a', 'b']);
+  });
+
+  it('loads sequence frames only for hovered entries when hover mode is on', () => {
+    const items = ref([reviewItem('a', true), reviewItem('b', true)]);
+    const grid = reactive<ReviewGridSettings>({ ...DEFAULT_REVIEW_GRID, columns: 2, rows: 1 });
+    const { chipStore, ensureSequences } = mockChipStore();
+    const hoverEntryKeys = ref(new Set<string>());
+    const controller = useReviewGrid({
+      items,
+      grid,
+      chipStore,
+      active: ref(true),
+      activateOnHover: computed(() => true),
+      hoverEntryKeys,
+      entryKeyOf: (entry) => entry.key,
+    });
+    controller.ensureVisible();
+    expect(ensureSequences.mock.calls[0][0]).toEqual([]);
+    hoverEntryKeys.value = new Set(['b']);
+    controller.ensureVisible();
+    const sequences = ensureSequences.mock.calls[1][0] as ReviewItem[];
+    expect(sequences.map((item) => item.key)).toEqual(['b']);
+  });
+});
diff --git a/client/platform/desktop/frontend/components/QueryPage.vue b/client/platform/desktop/frontend/components/QueryPage.vue
index f2d100e0f..565143b42 100644
--- a/client/platform/desktop/frontend/components/QueryPage.vue
+++ b/client/platform/desktop/frontend/components/QueryPage.vue
@@ -13,7 +13,6 @@ import { createItemChips, createSearchChips } from 'platform/desktop/frontend/us
 import { createSearchReview, OverlapChoice, OverlapSummary } from 'platform/desktop/frontend/useSearchReview';
 import { holdQuerySession, takeQuerySession } from 'platform/desktop/frontend/querySession';
 import { usePersistentGridSettings } from 'dive-common/review/gridSettings';
-import { usePersistentReviewSettings } from 'dive-common/review/reviewSettings';
 import { useReviewGrid } from 'dive-common/review/useReviewGrid';
 import { reviewViewerLocation } from 'dive-common/review/viewerNavigation';
 import type { ReviewItem } from 'dive-common/review/types';
@@ -90,8 +89,6 @@ export default defineComponent({
     const textChips = resumed?.textChips ?? createItemChips(page.textItems);
     const resultsMemory = resumed?.results ?? reactive({ page: 0, hideReviewed: false });
     const gridSettings = usePersistentGridSettings();
-    const reviewSettings = usePersistentReviewSettings();
-    const hoveredTextEntryKeys = ref(new Set<string>());
     const textGridActive = computed(() => view.value === 'query' && page.mode.value === 'text');
     const textGrid = useReviewGrid({
       items: page.textItems,
@@ -100,18 +97,8 @@ export default defineComponent({
       active: textGridActive,
       footerPx: TextCellFooterPx,
       outline: '',
-      activateOnHover: computed(() => reviewSettings.activateOnHover),
-      hoverEntryKeys: hoveredTextEntryKeys,
     });
 
-    function setTextEntryHovered(key: string, hovered: boolean) {
-      const next = new Set(hoveredTextEntryKeys.value);
-      if (hovered) next.add(key);
-      else next.delete(key);
-      hoveredTextEntryKeys.value = next;
-      textGrid.ensureVisible();
-    }
-
     const imageUrl = ref('');
     watch(page.imagePath, async (path) => {
       imageUrl.value = path ? await getMediaUrl(path) : '';
@@ -321,8 +308,6 @@ export default defineComponent({
       chooseOverlap,
       textChips,
       gridSettings,
-      reviewSettings,
-      setTextEntryHovered,
       textGrid,
       textCells,
       textCountLabel,
@@ -853,9 +838,7 @@ export default defineComponent({
                       :frames="cell.item.frames"
                       :failure="textChips.store.failures.value[cell.item.key] || null"
                       :animate="false"
-                      :activate-on-hover="reviewSettings.activateOnHover"
                       :type="cell.item.type"
-                      @hover-change="setTextEntryHovered(cell.item.key, $event)"
                       :confidence="cell.item.confidence"
                       :title="cell.title"
                       :subtitle="cell.subtitle"