From 1b5daf3c736a7e81727a8e028d7902b704e0d47e Mon Sep 17 00:00:00 2001
From: Matt Davis <matteius@gmail.com>
Date: Sat, 17 Oct 2026 05:46:52 -0400
Subject: [PATCH 1/2] Add slideshow mode to the live view

Auto-advance the live grid on a timer: a 1x1 layout cycles through
cameras, larger grids cycle through pages. Interval is 5-60s, persisted
per browser and mirrored to ?slideshow=<seconds> so wall displays and
kiosks can bookmark it.

The slideshow pauses during tile reorder, per-tile native fullscreen,
the building plan surface, and while the tab is hidden. Manual paging
restarts the countdown. Wired into both the HLS/MSE and WebRTC views.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../preact/LiveSlideshowControl.jsx           |  48 ++++++
 web/js/components/preact/LiveView.jsx         |  26 +++
 web/js/components/preact/WebRTCView.jsx       |  26 +++
 web/js/components/preact/useLiveSlideshow.js  | 156 ++++++++++++++++++
 web/public/locales/en.json                    |   5 +
 web/public/locales/fil.json                   |   5 +
 web/tests/liveSlideshow.spec.js               |  85 ++++++++++
 7 files changed, 351 insertions(+)
 create mode 100644 web/js/components/preact/LiveSlideshowControl.jsx
 create mode 100644 web/js/components/preact/useLiveSlideshow.js
 create mode 100644 web/tests/liveSlideshow.spec.js

diff --git a/web/js/components/preact/LiveSlideshowControl.jsx b/web/js/components/preact/LiveSlideshowControl.jsx
new file mode 100644
index 00000000..337470b6
--- /dev/null
+++ b/web/js/components/preact/LiveSlideshowControl.jsx
@@ -0,0 +1,48 @@
+import { useI18n } from '../../i18n.js';
+import { LIVE_SLIDESHOW_INTERVALS } from './useLiveSlideshow.js';
+
+/**
+ * Slideshow toggle for the live view toolbar, with an interval picker shown
+ * while it is on. In a 1x1 layout it cycles cameras; otherwise grid pages.
+ */
+export function LiveSlideshowControl({ enabled, interval, isSingleStream, onToggle, onIntervalChange }) {
+  const { t } = useI18n();
+  const label = enabled
+    ? t('live.slideshowStop')
+    : t(isSingleStream ? 'live.slideshowStartCameras' : 'live.slideshowStartPages');
+  return (
+    <div className="inline-flex items-center gap-1" data-testid="live-slideshow">
+      <button
+        type="button"
+        className={`rounded-full p-2 focus:outline-none focus:ring-2 focus:ring-primary ${enabled ? 'bg-primary text-primary-foreground hover:bg-primary/90' : 'bg-secondary text-secondary-foreground hover:bg-secondary/80'}`}
+        onClick={() => onToggle(!enabled)}
+        title={label}
+        aria-label={label}
+        aria-pressed={enabled}
+      >
+        <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <rect x="2" y="4" width="20" height="14" rx="2" />
+          {enabled
+            ? <path d="M10 8v6M14 8v6" />
+            : <path d="M10 8l5 3-5 3z" />}
+          <path d="M8 21h8" />
+        </svg>
+      </button>
+      {enabled && (
+        <select
+          className="px-2 py-2 border border-border rounded-md bg-background text-foreground text-sm focus:outline-none focus:ring-2 focus:ring-primary"
+          value={interval}
+          onChange={(event) => onIntervalChange(event.currentTarget.value)}
+          title={t('live.slideshowInterval')}
+          aria-label={t('live.slideshowInterval')}
+        >
+          {LIVE_SLIDESHOW_INTERVALS.map((seconds) => (
+            <option key={seconds} value={seconds}>{t('live.slideshowSeconds', { seconds })}</option>
+          ))}
+        </select>
+      )}
+    </div>
+  );
+}
+
+export default LiveSlideshowControl;
diff --git a/web/js/components/preact/LiveView.jsx b/web/js/components/preact/LiveView.jsx
index 8bef20d7..c0dc24dc 100644
--- a/web/js/components/preact/LiveView.jsx
+++ b/web/js/components/preact/LiveView.jsx
@@ -20,6 +20,8 @@ import { AlwaysFullscreenToggle } from './AlwaysFullscreenToggle.jsx';
 import { useAlwaysFullscreenOnTap } from './useAlwaysFullscreenOnTap.js';
 import { LiveDisplayModeToggle } from './LiveDisplayModeToggle.jsx';
 import { useLiveDisplayMode } from './useLiveDisplayMode.js';
+import { LiveSlideshowControl } from './LiveSlideshowControl.jsx';
+import { useLiveSlideshow } from './useLiveSlideshow.js';
 import { usePullToRefresh } from './usePullToRefresh.js';
 import { shouldShowGestureTip } from './mobileLiveGestures.js';
 import { fetchAllStreamSummaries } from '../../utils/stream-summaries.js';
@@ -522,6 +524,20 @@ export function LiveView({audioDisabled = false, isAutoDisabled = false, isWebRT
     });
   }, [applyOperatorLayout, setOperatorSurface]);
 
+  // Auto-advance cameras (1x1) or grid pages on a timer. Paused while the
+  // operator is rearranging tiles, has one tile in native fullscreen, or is
+  // looking at the building plan instead of the grid.
+  const slideshow = useLiveSlideshow({
+    paused: reorderMode || !!fullscreenCellStream || operatorSurface !== 'grid',
+    isSingleStream,
+    orderedStreams,
+    selectedStream,
+    setSelectedStream,
+    currentPage,
+    setCurrentPage,
+    maxStreams,
+  });
+
   // Ensure current page is valid when orderedStreams or layout changes
   useEffect(() => {
     if (orderedStreams.length === 0) return;
@@ -824,6 +840,16 @@ export function LiveView({audioDisabled = false, isAutoDisabled = false, isWebRT
             />
           )}
 
+          {slideshow.canCycle && (
+            <LiveSlideshowControl
+              enabled={slideshow.enabled}
+              interval={slideshow.interval}
+              isSingleStream={isSingleStream}
+              onToggle={slideshow.setEnabled}
+              onIntervalChange={slideshow.setInterval}
+            />
+          )}
+
           {orderedStreams.length > 1 && (
             <button
               className={`p-2 rounded-full focus:outline-none focus:ring-2 focus:ring-primary ${reorderMode ? 'bg-primary text-primary-foreground hover:bg-primary/90' : 'bg-secondary hover:bg-secondary/80 text-secondary-foreground'}`}
diff --git a/web/js/components/preact/WebRTCView.jsx b/web/js/components/preact/WebRTCView.jsx
index 37c5e211..93113d7c 100644
--- a/web/js/components/preact/WebRTCView.jsx
+++ b/web/js/components/preact/WebRTCView.jsx
@@ -21,6 +21,8 @@ import { AlwaysFullscreenToggle } from './AlwaysFullscreenToggle.jsx';
 import { useAlwaysFullscreenOnTap } from './useAlwaysFullscreenOnTap.js';
 import { LiveDisplayModeToggle } from './LiveDisplayModeToggle.jsx';
 import { useLiveDisplayMode } from './useLiveDisplayMode.js';
+import { LiveSlideshowControl } from './LiveSlideshowControl.jsx';
+import { useLiveSlideshow } from './useLiveSlideshow.js';
 import { usePullToRefresh } from './usePullToRefresh.js';
 import { shouldShowGestureTip } from './mobileLiveGestures.js';
 import { fetchAllStreamSummaries } from '../../utils/stream-summaries.js';
@@ -553,6 +555,20 @@ export function WebRTCView({ audioDisabled = false, isAutoDisabled = false, isWe
     });
   }, [applyOperatorLayout, setOperatorSurface]);
 
+  // Auto-advance cameras (1x1) or grid pages on a timer. Paused while the
+  // operator is rearranging tiles, has one tile in native fullscreen, or is
+  // looking at the building plan instead of the grid.
+  const slideshow = useLiveSlideshow({
+    paused: reorderMode || !!fullscreenCellStream || operatorSurface !== 'grid',
+    isSingleStream,
+    orderedStreams,
+    selectedStream,
+    setSelectedStream,
+    currentPage,
+    setCurrentPage,
+    maxStreams,
+  });
+
   // Ensure current page is valid when orderedStreams or maxStreams changes
   useEffect(() => {
     if (orderedStreams.length === 0) return;
@@ -854,6 +870,16 @@ export function WebRTCView({ audioDisabled = false, isAutoDisabled = false, isWe
             />
           )}
 
+          {slideshow.canCycle && (
+            <LiveSlideshowControl
+              enabled={slideshow.enabled}
+              interval={slideshow.interval}
+              isSingleStream={isSingleStream}
+              onToggle={slideshow.setEnabled}
+              onIntervalChange={slideshow.setInterval}
+            />
+          )}
+
           {orderedStreams.length > 1 && (
             <button
               className={`p-2 rounded-full focus:outline-none focus:ring-2 focus:ring-primary ${reorderMode ? 'bg-primary text-primary-foreground hover:bg-primary/90' : 'bg-secondary hover:bg-secondary/80 text-secondary-foreground'}`}
diff --git a/web/js/components/preact/useLiveSlideshow.js b/web/js/components/preact/useLiveSlideshow.js
new file mode 100644
index 00000000..94239e1b
--- /dev/null
+++ b/web/js/components/preact/useLiveSlideshow.js
@@ -0,0 +1,156 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks';
+
+/**
+ * Live view slideshow: auto-advance the live grid on a timer.
+ *
+ *   1x1 layout  - cycles through the cameras one at a time.
+ *   larger grid - cycles through the pages of the grid.
+ *
+ * The preference is persisted in localStorage and mirrored to the URL as
+ * ?slideshow=<seconds>, so a wall display or kiosk can bookmark it.
+ */
+export const LIVE_SLIDESHOW_KEY = 'lightnvr-live-slideshow';
+export const LIVE_SLIDESHOW_INTERVAL_KEY = 'lightnvr-live-slideshow-interval';
+export const LIVE_SLIDESHOW_URL_PARAM = 'slideshow';
+export const LIVE_SLIDESHOW_INTERVALS = Object.freeze([5, 10, 15, 30, 60]);
+export const DEFAULT_LIVE_SLIDESHOW_INTERVAL = 10;
+
+export function normalizeSlideshowInterval(value) {
+  const seconds = Number.parseInt(value, 10);
+  return LIVE_SLIDESHOW_INTERVALS.includes(seconds) ? seconds : DEFAULT_LIVE_SLIDESHOW_INTERVAL;
+}
+
+/**
+ * Initial slideshow state. A ?slideshow=<seconds> URL param wins over the
+ * stored preference; ?slideshow=0 turns it off.
+ *
+ * @returns {{enabled: boolean, interval: number}}
+ */
+export function readLiveSlideshow(storage, search) {
+  try {
+    const param = new URLSearchParams(search ?? globalThis.location?.search ?? '').get(LIVE_SLIDESHOW_URL_PARAM);
+    if (param !== null) {
+      if (param === '0' || param === 'off') {
+        return { enabled: false, interval: DEFAULT_LIVE_SLIDESHOW_INTERVAL };
+      }
+      return { enabled: true, interval: normalizeSlideshowInterval(param) };
+    }
+  } catch {
+    // Fall through to the stored preference.
+  }
+  try {
+    const selectedStorage = storage ?? globalThis.localStorage;
+    return {
+      enabled: selectedStorage?.getItem(LIVE_SLIDESHOW_KEY) === 'true',
+      interval: normalizeSlideshowInterval(selectedStorage?.getItem(LIVE_SLIDESHOW_INTERVAL_KEY)),
+    };
+  } catch {
+    return { enabled: false, interval: DEFAULT_LIVE_SLIDESHOW_INTERVAL };
+  }
+}
+
+export function writeLiveSlideshow({ enabled, interval }, storage) {
+  try {
+    const selectedStorage = storage ?? globalThis.localStorage;
+    selectedStorage?.setItem(LIVE_SLIDESHOW_KEY, String(!!enabled));
+    selectedStorage?.setItem(LIVE_SLIDESHOW_INTERVAL_KEY, String(normalizeSlideshowInterval(interval)));
+  } catch {
+    // Storage can be disabled in private browsing; keep the in-memory choice.
+  }
+}
+
+/** Number of slides the slideshow would cycle through. */
+export function slideshowSlideCount({ isSingleStream, streamCount, maxStreams }) {
+  if (streamCount <= 0) return 0;
+  if (isSingleStream) return streamCount;
+  return Math.ceil(streamCount / Math.max(1, maxStreams));
+}
+
+/**
+ * The next slide after the current one, wrapping around at the end.
+ * Returns {selectedStream} in 1x1 mode, {page} in grid mode, or null when
+ * there is nothing to cycle to.
+ */
+export function nextSlideshowTarget({ isSingleStream, streamNames, selectedStream, currentPage, maxStreams }) {
+  const slides = slideshowSlideCount({ isSingleStream, streamCount: streamNames.length, maxStreams });
+  if (slides < 2) return null;
+  if (isSingleStream) {
+    const index = streamNames.indexOf(selectedStream);
+    return { selectedStream: streamNames[(index + 1) % streamNames.length] };
+  }
+  return { page: (Math.max(0, currentPage) + 1) % slides };
+}
+
+function useDocumentVisible() {
+  const [visible, setVisible] = useState(() => typeof document === 'undefined' || !document.hidden);
+  useEffect(() => {
+    const onChange = () => setVisible(!document.hidden);
+    document.addEventListener('visibilitychange', onChange);
+    return () => document.removeEventListener('visibilitychange', onChange);
+  }, []);
+  return visible;
+}
+
+/**
+ * Drive the live view slideshow. The countdown restarts whenever the visible
+ * slide changes, so manual paging or camera selection gets a full interval.
+ * It also stops while `paused` is set (reorder mode, a tile in native
+ * fullscreen) and while the browser tab is hidden.
+ */
+export function useLiveSlideshow({
+  paused = false,
+  isSingleStream,
+  orderedStreams,
+  selectedStream,
+  setSelectedStream,
+  currentPage,
+  setCurrentPage,
+  maxStreams,
+}) {
+  const [state, setState] = useState(() => readLiveSlideshow());
+  const visible = useDocumentVisible();
+
+  useEffect(() => {
+    writeLiveSlideshow(state);
+    const url = new URL(window.location);
+    if (state.enabled) url.searchParams.set(LIVE_SLIDESHOW_URL_PARAM, String(state.interval));
+    else url.searchParams.delete(LIVE_SLIDESHOW_URL_PARAM);
+    window.history.replaceState({}, '', url);
+  }, [state]);
+
+  // Streams are refetched periodically; key the timer on the names so a
+  // refresh with the same cameras does not restart the countdown.
+  const streamNames = useMemo(() => orderedStreams.map((stream) => stream.name), [orderedStreams]);
+  const namesKey = streamNames.join('\n');
+  const latest = useRef(null);
+  latest.current = { isSingleStream, streamNames, selectedStream, currentPage, maxStreams, setSelectedStream, setCurrentPage };
+
+  const slideCount = slideshowSlideCount({ isSingleStream, streamCount: streamNames.length, maxStreams });
+  const canCycle = slideCount > 1;
+  const running = state.enabled && canCycle && !paused && visible;
+
+  useEffect(() => {
+    if (!running) return undefined;
+    const timer = setTimeout(() => {
+      const current = latest.current;
+      const target = nextSlideshowTarget(current);
+      if (!target) return;
+      if (target.selectedStream !== undefined) current.setSelectedStream(target.selectedStream);
+      else current.setCurrentPage(target.page);
+    }, state.interval * 1000);
+    return () => clearTimeout(timer);
+  }, [running, state.interval, isSingleStream, selectedStream, currentPage, maxStreams, namesKey]);
+
+  const setEnabled = useCallback((enabled) => setState((s) => ({ ...s, enabled: !!enabled })), []);
+  const setInterval = useCallback((interval) =>
+    setState((s) => ({ ...s, interval: normalizeSlideshowInterval(interval) })), []);
+
+  return {
+    enabled: state.enabled,
+    interval: state.interval,
+    canCycle,
+    running,
+    setEnabled,
+    setInterval,
+  };
+}
diff --git a/web/public/locales/en.json b/web/public/locales/en.json
index 4ec4100d..784da9ac 100644
--- a/web/public/locales/en.json
+++ b/web/public/locales/en.json
@@ -1555,6 +1555,11 @@
   "live.displayModeFill": "Fill",
   "live.displayModeFitDescription": "Fit: show the whole frame with letterboxing",
   "live.displayModeFillDescription": "Fill: fill the tile and crop the frame edges",
+  "live.slideshowStartCameras": "Start slideshow: cycle through cameras",
+  "live.slideshowStartPages": "Start slideshow: cycle through grid pages",
+  "live.slideshowStop": "Stop slideshow",
+  "live.slideshowInterval": "Slideshow interval",
+  "live.slideshowSeconds": "{seconds}s",
   "streams.toggleDisable": "Disable stream",
   "streams.toggleEnable": "Enable stream",
   "streams.readOnlyInsufficientPermissions": "Read-only (insufficient permissions to modify)",
diff --git a/web/public/locales/fil.json b/web/public/locales/fil.json
index a1dae1be..559113c2 100644
--- a/web/public/locales/fil.json
+++ b/web/public/locales/fil.json
@@ -331,6 +331,11 @@
   "live.displayModeFill": "Punuin",
   "live.displayModeFitDescription": "Iangkop: ipakita ang buong frame na may mga bar sa gilid",
   "live.displayModeFillDescription": "Punuin: punuin ang tile at putulin ang mga gilid ng frame",
+  "live.slideshowStartCameras": "Simulan ang slideshow: isa-isahin ang mga camera",
+  "live.slideshowStartPages": "Simulan ang slideshow: isa-isahin ang mga pahina ng grid",
+  "live.slideshowStop": "Itigil ang slideshow",
+  "live.slideshowInterval": "Pagitan ng slideshow",
+  "live.slideshowSeconds": "{seconds}s",
   "recordings.filters": "Mga Filter",
   "recordings.showFilters": "Ipakita ang mga filter",
   "recordings.hideFilters": "Itago ang mga filter",
diff --git a/web/tests/liveSlideshow.spec.js b/web/tests/liveSlideshow.spec.js
new file mode 100644
index 00000000..cb07d04d
--- /dev/null
+++ b/web/tests/liveSlideshow.spec.js
@@ -0,0 +1,85 @@
+import {
+  DEFAULT_LIVE_SLIDESHOW_INTERVAL,
+  LIVE_SLIDESHOW_INTERVAL_KEY,
+  LIVE_SLIDESHOW_KEY,
+  nextSlideshowTarget,
+  normalizeSlideshowInterval,
+  readLiveSlideshow,
+  slideshowSlideCount,
+  writeLiveSlideshow,
+} from '../js/components/preact/useLiveSlideshow.js';
+
+function memoryStorage(initial = {}) {
+  const values = new Map(Object.entries(initial));
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => values.set(key, value),
+  };
+}
+
+const names = ['front', 'back', 'garage', 'side', 'drive'];
+
+describe('live slideshow preference', () => {
+  test('is off by default with a 10 second interval', () => {
+    expect(readLiveSlideshow(memoryStorage(), '')).toEqual({ enabled: false, interval: 10 });
+    expect(DEFAULT_LIVE_SLIDESHOW_INTERVAL).toBe(10);
+  });
+
+  test('round-trips through storage', () => {
+    const storage = memoryStorage();
+    writeLiveSlideshow({ enabled: true, interval: 30 }, storage);
+    expect(storage.getItem(LIVE_SLIDESHOW_KEY)).toBe('true');
+    expect(storage.getItem(LIVE_SLIDESHOW_INTERVAL_KEY)).toBe('30');
+    expect(readLiveSlideshow(storage, '')).toEqual({ enabled: true, interval: 30 });
+  });
+
+  test('a ?slideshow= URL param overrides storage so kiosks can bookmark it', () => {
+    const storage = memoryStorage({ [LIVE_SLIDESHOW_KEY]: 'false', [LIVE_SLIDESHOW_INTERVAL_KEY]: '5' });
+    expect(readLiveSlideshow(storage, '?slideshow=15')).toEqual({ enabled: true, interval: 15 });
+    expect(readLiveSlideshow(memoryStorage({ [LIVE_SLIDESHOW_KEY]: 'true' }), '?slideshow=0').enabled).toBe(false);
+  });
+
+  test('rejects intervals outside the offered list', () => {
+    expect(normalizeSlideshowInterval('60')).toBe(60);
+    expect(normalizeSlideshowInterval('1')).toBe(DEFAULT_LIVE_SLIDESHOW_INTERVAL);
+    expect(normalizeSlideshowInterval('abc')).toBe(DEFAULT_LIVE_SLIDESHOW_INTERVAL);
+    expect(readLiveSlideshow(memoryStorage(), '?slideshow=7')).toEqual({ enabled: true, interval: 10 });
+  });
+
+  test('survives storage that throws', () => {
+    const broken = { getItem: () => { throw new Error('denied'); }, setItem: () => { throw new Error('denied'); } };
+    expect(readLiveSlideshow(broken, '')).toEqual({ enabled: false, interval: 10 });
+    expect(() => writeLiveSlideshow({ enabled: true, interval: 5 }, broken)).not.toThrow();
+  });
+});
+
+describe('live slideshow advancing', () => {
+  test('counts cameras in 1x1 and pages in a grid', () => {
+    expect(slideshowSlideCount({ isSingleStream: true, streamCount: 5, maxStreams: 1 })).toBe(5);
+    expect(slideshowSlideCount({ isSingleStream: false, streamCount: 5, maxStreams: 4 })).toBe(2);
+    expect(slideshowSlideCount({ isSingleStream: false, streamCount: 0, maxStreams: 4 })).toBe(0);
+  });
+
+  test('1x1 cycles to the next camera and wraps', () => {
+    const base = { isSingleStream: true, streamNames: names, currentPage: 0, maxStreams: 1 };
+    expect(nextSlideshowTarget({ ...base, selectedStream: 'front' })).toEqual({ selectedStream: 'back' });
+    expect(nextSlideshowTarget({ ...base, selectedStream: 'drive' })).toEqual({ selectedStream: 'front' });
+    // A selection that no longer exists restarts from the first camera.
+    expect(nextSlideshowTarget({ ...base, selectedStream: 'gone' })).toEqual({ selectedStream: 'front' });
+  });
+
+  test('a grid cycles pages and wraps', () => {
+    const base = { isSingleStream: false, streamNames: names, selectedStream: '', maxStreams: 4 };
+    expect(nextSlideshowTarget({ ...base, currentPage: 0 })).toEqual({ page: 1 });
+    expect(nextSlideshowTarget({ ...base, currentPage: 1 })).toEqual({ page: 0 });
+  });
+
+  test('does nothing when everything already fits on screen', () => {
+    expect(nextSlideshowTarget({
+      isSingleStream: false, streamNames: names, selectedStream: '', currentPage: 0, maxStreams: 9,
+    })).toBeNull();
+    expect(nextSlideshowTarget({
+      isSingleStream: true, streamNames: ['front'], selectedStream: 'front', currentPage: 0, maxStreams: 1,
+    })).toBeNull();
+  });
+});

From 14701f7fbbb080ed42f7d49e3ea169be518b52b9 Mon Sep 17 00:00:00 2001
From: Matt Davis <matteius@gmail.com>
Date: Sat, 17 Oct 2026 05:53:28 -0400
Subject: [PATCH 2/2] Add behaviour tests for the live slideshow

Cover the useLiveSlideshow timer with a deps-aware preact/hooks shim:
page and camera cycling with wrap, interval choice, countdown reset on
manual navigation, no reset on same-camera refetch, pause/resume for the
caller's pause flag and hidden tabs, the nothing-to-cycle case, and
localStorage / ?slideshow= sync. Render LiveSlideshowControl via esbuild
and check its labels, pressed state, interval options and callbacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 web/tests/liveSlideshowControl.spec.js |  79 ++++++
 web/tests/liveSlideshowHook.spec.js    | 337 +++++++++++++++++++++++++
 2 files changed, 416 insertions(+)
 create mode 100644 web/tests/liveSlideshowControl.spec.js
 create mode 100644 web/tests/liveSlideshowHook.spec.js

diff --git a/web/tests/liveSlideshowControl.spec.js b/web/tests/liveSlideshowControl.spec.js
new file mode 100644
index 00000000..c7901c4c
--- /dev/null
+++ b/web/tests/liveSlideshowControl.spec.js
@@ -0,0 +1,79 @@
+/**
+ * LiveSlideshowControl render tests. The component is bundled with esbuild
+ * (Jest's Babel config has no JSX transform) with i18n left external and stubbed, then called
+ * directly so the returned preact vnode tree can be inspected.
+ */
+const path = require('path');
+const { buildSync } = require('esbuild');
+
+function loadControl() {
+  const output = buildSync({
+    absWorkingDir: path.resolve(__dirname, '..'),
+    entryPoints: ['js/components/preact/LiveSlideshowControl.jsx'],
+    bundle: true,
+    format: 'cjs',
+    platform: 'node',
+    jsx: 'automatic',
+    jsxImportSource: 'preact',
+    write: false,
+    logLevel: 'silent',
+    external: ['*/i18n.js'],
+  }).outputFiles[0].text;
+  const loaded = { exports: {} };
+  const i18nStub = { useI18n: () => ({ t: (key, params) => (params ? `${key}:${JSON.stringify(params)}` : key) }) };
+  const requireWithStub = (id) => (id.endsWith('i18n.js') ? i18nStub : require(id));
+  Function('module', 'exports', 'require', output)(loaded, loaded.exports, requireWithStub);
+  return loaded.exports;
+}
+
+const { LiveSlideshowControl } = loadControl();
+
+function findAll(node, type, found = []) {
+  if (!node || typeof node !== 'object') return found;
+  if (Array.isArray(node)) {
+    node.forEach((child) => findAll(child, type, found));
+    return found;
+  }
+  if (node.type === type) found.push(node);
+  findAll(node.props?.children, type, found);
+  return found;
+}
+
+function render(props) {
+  const handlers = { onToggle: jest.fn(), onIntervalChange: jest.fn() };
+  const tree = LiveSlideshowControl({ enabled: false, interval: 10, isSingleStream: false, ...handlers, ...props });
+  return { tree, handlers, button: findAll(tree, 'button')[0], select: findAll(tree, 'select')[0] };
+}
+
+describe('LiveSlideshowControl', () => {
+  test('off: offers to start cycling pages and hides the interval picker', () => {
+    const { button, select, handlers } = render({ enabled: false });
+    expect(button.props['aria-pressed']).toBe(false);
+    expect(button.props['aria-label']).toBe('live.slideshowStartPages');
+    expect(select).toBeUndefined();
+
+    button.props.onClick();
+    expect(handlers.onToggle).toHaveBeenCalledWith(true);
+  });
+
+  test('off in a 1x1 layout: describes cycling cameras', () => {
+    const { button } = render({ enabled: false, isSingleStream: true });
+    expect(button.props['aria-label']).toBe('live.slideshowStartCameras');
+  });
+
+  test('on: shows stop and the interval picker with every offered interval', () => {
+    const { button, select, handlers } = render({ enabled: true, interval: 30 });
+    expect(button.props['aria-pressed']).toBe(true);
+    expect(button.props['aria-label']).toBe('live.slideshowStop');
+
+    button.props.onClick();
+    expect(handlers.onToggle).toHaveBeenCalledWith(false);
+
+    expect(select.props.value).toBe(30);
+    const options = findAll(select, 'option').map((option) => option.props.value);
+    expect(options).toEqual([5, 10, 15, 30, 60]);
+
+    select.props.onChange({ currentTarget: { value: '60' } });
+    expect(handlers.onIntervalChange).toHaveBeenCalledWith('60');
+  });
+});
diff --git a/web/tests/liveSlideshowHook.spec.js b/web/tests/liveSlideshowHook.spec.js
new file mode 100644
index 00000000..623886b2
--- /dev/null
+++ b/web/tests/liveSlideshowHook.spec.js
@@ -0,0 +1,337 @@
+/**
+ * Behaviour tests for the useLiveSlideshow hook: the timer, pausing, and the
+ * localStorage / URL sync. There is no DOM renderer in this project (see
+ * jest.config.cjs), so preact/hooks is replaced with a small deps-aware shim
+ * and the hook is re-run as a "component" whenever its state changes.
+ */
+
+const mockHarness = {
+  slots: [],
+  cursor: 0,
+  pendingEffects: [],
+  dirty: false,
+};
+
+function mockDepsChanged(prev, next) {
+  if (!prev || !next) return true;
+  return prev.length !== next.length || prev.some((value, i) => !Object.is(value, next[i]));
+}
+
+jest.mock('preact/hooks', () => ({
+  useState: (initial) => {
+    const slot = mockHarness.cursor++;
+    if (!mockHarness.slots[slot]) {
+      const value = typeof initial === 'function' ? initial() : initial;
+      const cell = { value };
+      cell.set = (next) => {
+        const resolved = typeof next === 'function' ? next(cell.value) : next;
+        if (!Object.is(resolved, cell.value)) {
+          cell.value = resolved;
+          mockHarness.dirty = true;
+        }
+      };
+      mockHarness.slots[slot] = cell;
+    }
+    return [mockHarness.slots[slot].value, mockHarness.slots[slot].set];
+  },
+  useRef: (initial) => {
+    const slot = mockHarness.cursor++;
+    if (!mockHarness.slots[slot]) mockHarness.slots[slot] = { current: initial };
+    return mockHarness.slots[slot];
+  },
+  useMemo: (fn, deps) => {
+    const slot = mockHarness.cursor++;
+    const cell = mockHarness.slots[slot];
+    if (!cell || mockDepsChanged(cell.deps, deps)) mockHarness.slots[slot] = { value: fn(), deps };
+    return mockHarness.slots[slot].value;
+  },
+  useCallback: (fn, deps) => {
+    const slot = mockHarness.cursor++;
+    const cell = mockHarness.slots[slot];
+    if (!cell || mockDepsChanged(cell.deps, deps)) mockHarness.slots[slot] = { value: fn, deps };
+    return mockHarness.slots[slot].value;
+  },
+  useEffect: (fn, deps) => {
+    const slot = mockHarness.cursor++;
+    const cell = mockHarness.slots[slot] || (mockHarness.slots[slot] = { deps: undefined, cleanup: null });
+    if (mockDepsChanged(cell.deps, deps)) {
+      cell.deps = deps;
+      mockHarness.pendingEffects.push(() => {
+        if (cell.cleanup) cell.cleanup();
+        cell.cleanup = fn() || null;
+      });
+    }
+  },
+}));
+
+const {
+  LIVE_SLIDESHOW_INTERVAL_KEY,
+  LIVE_SLIDESHOW_KEY,
+  useLiveSlideshow,
+} = require('../js/components/preact/useLiveSlideshow.js');
+
+function memoryStorage(initial = {}) {
+  const values = new Map(Object.entries(initial));
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => values.set(key, String(value)),
+    removeItem: (key) => values.delete(key),
+  };
+}
+
+function installBrowser({ search = '', storage = memoryStorage() } = {}) {
+  const listeners = new Map();
+  const doc = {
+    hidden: false,
+    addEventListener: (type, fn) => listeners.set(type, fn),
+    removeEventListener: (type) => listeners.delete(type),
+  };
+  const location = new URL(`http://nvr.local/${search}`);
+  const win = {
+    location,
+    history: {
+      state: null,
+      replaceState: jest.fn((_state, _title, url) => {
+        win.location = new URL(String(url));
+      }),
+    },
+  };
+  global.document = doc;
+  global.window = win;
+  global.localStorage = storage;
+  Object.defineProperty(global, 'location', { configurable: true, get: () => win.location });
+  return {
+    storage,
+    url: () => win.location,
+    setHidden(hidden) {
+      doc.hidden = hidden;
+      listeners.get('visibilitychange')?.();
+    },
+  };
+}
+
+function uninstallBrowser() {
+  delete global.document;
+  delete global.window;
+  delete global.localStorage;
+  delete global.location;
+}
+
+const stream = (name) => ({ name });
+
+/**
+ * Mount the hook with a mutable "parent" whose selectedStream / currentPage
+ * are real state the hook can drive, like LiveView's.
+ */
+function mount(initialProps) {
+  mockHarness.slots = [];
+  mockHarness.pendingEffects = [];
+  const parent = {
+    props: {
+      paused: false,
+      isSingleStream: false,
+      orderedStreams: ['a', 'b', 'c', 'd', 'e'].map(stream),
+      selectedStream: '',
+      currentPage: 0,
+      maxStreams: 4,
+      ...initialProps,
+    },
+    result: null,
+  };
+  parent.props.setSelectedStream = jest.fn((name) => { parent.props.selectedStream = name; mockHarness.dirty = true; });
+  parent.props.setCurrentPage = jest.fn((page) => { parent.props.currentPage = page; mockHarness.dirty = true; });
+
+  const render = () => {
+    for (let pass = 0; pass < 20; pass += 1) {
+      mockHarness.dirty = false;
+      mockHarness.cursor = 0;
+      parent.result = useLiveSlideshow(parent.props);
+      const effects = mockHarness.pendingEffects.splice(0);
+      effects.forEach((run) => run());
+      if (!mockHarness.dirty) return;
+    }
+    throw new Error('render loop did not settle');
+  };
+  render();
+
+  return {
+    get result() { return parent.result; },
+    get props() { return parent.props; },
+    rerender(next = {}) { Object.assign(parent.props, next); render(); },
+    act(fn) { fn(); render(); },
+    tick(ms) { jest.advanceTimersByTime(ms); render(); },
+  };
+}
+
+describe('useLiveSlideshow', () => {
+  let browser;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+    uninstallBrowser();
+  });
+
+  test('stays idle until enabled', () => {
+    browser = installBrowser();
+    const view = mount();
+    expect(view.result.enabled).toBe(false);
+    expect(view.result.canCycle).toBe(true);
+    expect(view.result.running).toBe(false);
+    view.tick(60_000);
+    expect(view.props.setCurrentPage).not.toHaveBeenCalled();
+  });
+
+  test('cycles grid pages on the interval and wraps to the first page', () => {
+    browser = installBrowser();
+    const view = mount();
+    view.act(() => view.result.setEnabled(true));
+    expect(view.result.running).toBe(true);
+
+    view.tick(9_999);
+    expect(view.props.currentPage).toBe(0);
+    view.tick(1);
+    expect(view.props.currentPage).toBe(1);
+    view.tick(10_000);
+    expect(view.props.currentPage).toBe(0);
+    expect(view.props.setSelectedStream).not.toHaveBeenCalled();
+  });
+
+  test('cycles cameras one at a time in a 1x1 layout', () => {
+    browser = installBrowser();
+    const view = mount({ isSingleStream: true, maxStreams: 1, selectedStream: 'd' });
+    view.act(() => view.result.setEnabled(true));
+
+    view.tick(10_000);
+    expect(view.props.selectedStream).toBe('e');
+    view.tick(10_000);
+    expect(view.props.selectedStream).toBe('a');
+    expect(view.props.setCurrentPage).not.toHaveBeenCalled();
+  });
+
+  test('uses the chosen interval', () => {
+    browser = installBrowser();
+    const view = mount();
+    view.act(() => { view.result.setEnabled(true); view.result.setInterval('30'); });
+    expect(view.result.interval).toBe(30);
+    view.tick(29_000);
+    expect(view.props.currentPage).toBe(0);
+    view.tick(1_000);
+    expect(view.props.currentPage).toBe(1);
+  });
+
+  test('a manual page change restarts the countdown', () => {
+    browser = installBrowser();
+    const view = mount({ orderedStreams: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i'].map(stream) });
+    view.act(() => view.result.setEnabled(true));
+
+    view.tick(8_000);
+    view.rerender({ currentPage: 2 }); // operator clicked through to page 3
+    view.tick(8_000);
+    expect(view.props.currentPage).toBe(2);
+    view.tick(2_000);
+    expect(view.props.currentPage).toBe(0);
+  });
+
+  test('a stream refetch with the same cameras does not restart the countdown', () => {
+    browser = installBrowser();
+    const view = mount();
+    view.act(() => view.result.setEnabled(true));
+
+    view.tick(6_000);
+    view.rerender({ orderedStreams: ['a', 'b', 'c', 'd', 'e'].map(stream) }); // new array, same names
+    view.tick(4_000);
+    expect(view.props.currentPage).toBe(1);
+  });
+
+  test('pauses while the caller says so and resumes with a full interval', () => {
+    browser = installBrowser();
+    const view = mount();
+    view.act(() => view.result.setEnabled(true));
+
+    view.tick(5_000);
+    view.rerender({ paused: true });
+    expect(view.result.running).toBe(false);
+    view.tick(60_000);
+    expect(view.props.currentPage).toBe(0);
+
+    view.rerender({ paused: false });
+    view.tick(9_000);
+    expect(view.props.currentPage).toBe(0);
+    view.tick(1_000);
+    expect(view.props.currentPage).toBe(1);
+  });
+
+  test('pauses while the browser tab is hidden', () => {
+    browser = installBrowser();
+    const view = mount();
+    view.act(() => view.result.setEnabled(true));
+
+    view.act(() => browser.setHidden(true));
+    expect(view.result.running).toBe(false);
+    view.tick(60_000);
+    expect(view.props.currentPage).toBe(0);
+
+    view.act(() => browser.setHidden(false));
+    view.tick(10_000);
+    expect(view.props.currentPage).toBe(1);
+  });
+
+  test('does not run when everything fits on one screen', () => {
+    browser = installBrowser({ search: '?slideshow=5' });
+    const view = mount({ maxStreams: 9 });
+    expect(view.result.enabled).toBe(true);
+    expect(view.result.canCycle).toBe(false);
+    expect(view.result.running).toBe(false);
+    view.tick(60_000);
+    expect(view.props.setCurrentPage).not.toHaveBeenCalled();
+  });
+
+  test('stops cycling once the camera list shrinks to a single page', () => {
+    browser = installBrowser();
+    const view = mount();
+    view.act(() => view.result.setEnabled(true));
+    view.rerender({ orderedStreams: ['a', 'b'].map(stream) });
+    expect(view.result.canCycle).toBe(false);
+    view.tick(60_000);
+    expect(view.props.setCurrentPage).not.toHaveBeenCalled();
+  });
+
+  test('disabling clears the pending advance', () => {
+    browser = installBrowser();
+    const view = mount();
+    view.act(() => view.result.setEnabled(true));
+    view.tick(9_000);
+    view.act(() => view.result.setEnabled(false));
+    view.tick(60_000);
+    expect(view.props.currentPage).toBe(0);
+  });
+
+  test('persists the preference and mirrors it to ?slideshow=', () => {
+    browser = installBrowser({ search: '?cols=1&rows=1' });
+    const view = mount();
+    expect(browser.url().searchParams.has('slideshow')).toBe(false);
+
+    view.act(() => { view.result.setEnabled(true); view.result.setInterval(15); });
+    expect(browser.storage.getItem(LIVE_SLIDESHOW_KEY)).toBe('true');
+    expect(browser.storage.getItem(LIVE_SLIDESHOW_INTERVAL_KEY)).toBe('15');
+    expect(browser.url().searchParams.get('slideshow')).toBe('15');
+    // Other live view params are left alone.
+    expect(browser.url().searchParams.get('cols')).toBe('1');
+
+    view.act(() => view.result.setEnabled(false));
+    expect(browser.storage.getItem(LIVE_SLIDESHOW_KEY)).toBe('false');
+    expect(browser.url().searchParams.has('slideshow')).toBe(false);
+  });
+
+  test('starts from a bookmarked ?slideshow= URL', () => {
+    browser = installBrowser({ search: '?slideshow=5' });
+    const view = mount();
+    expect(view.result).toMatchObject({ enabled: true, interval: 5, running: true });
+    view.tick(5_000);
+    expect(view.props.currentPage).toBe(1);
+  });
+});