feat(slideshow): per-event play order + category filter (#202)

The Live Slideshow already covers the core of #202 (fullscreen kiosk,
live-appending new uploads, timing/transitions/watermark, per-event
opt-in via the share link). This adds the two customization dimensions
the reporter also asked for:

- **Play order** (show_order): 'chronological' (upload order, default) or
  'random' — the client shuffles the initial set (Fisher-Yates) so
  live-appended uploads keep working.
- **Category filter** (show_category_id): restrict the slideshow to a
  single photo category (NULL = all photos, default). Enforced
  server-side on the slideshow /photos access and mirrored in the
  /session + /state photo_count, so the kiosk viewer can't widen the set.

Per-event enable/disable (default off) is unchanged — it's the existing
'Generate/Disable slideshow link' flow (no token = no slideshow).

- Migration 158: show_order (default 'chronological') + show_category_id.
- Admin: Play-order dropdown + category picker in the Live Slideshow card
  (picker hidden for events without categories); EN + DE i18n.
- Verified: migration (SQLite + PG); live API (category filter → 3/2/5
  photos + matching count; order propagates) and the running kiosk
  requests exactly the filtered set; tsc clean, 136 backend tests pass.

backend/src/routes/adminEvents/helpers.js

@@ -307,6 +307,9 @@ async function deleteEventCascade(eventId, adminContext) {
 const SLIDESHOW_TRANSITIONS = ['crossfade', 'cut', 'slide', 'kenburns', 'dipwhite', 'dipblack'];
 // Allowed per-slide color filters.
 const SLIDESHOW_COLORFILTERS = ['none', 'bw', 'sepia', 'warm', 'cool', 'vignette'];
+// Allowed slideshow play orders (#202). 'chronological' = upload order,
+// 'random' = client-side shuffle.
+const SLIDESHOW_ORDERS = ['chronological', 'random'];
 module.exports = {
   validateHeroImageAnchor,
   getStoragePath,
@@ -321,6 +324,7 @@ module.exports = {
   mapEventForApi,
   hasCustomerContactColumns,
   deleteEventCascade,
+  SLIDESHOW_ORDERS,
   SLIDESHOW_TRANSITIONS,
   SLIDESHOW_COLORFILTERS,
 };

backend/src/routes/adminEvents/slideshow.js

@@ -13,7 +13,7 @@ const { parseBooleanInput } = require('../../utils/parsers');
 const { requireEventOwnership } = require('../../middleware/ownership');
 const { requireFeatureFlag } = require('../../middleware/requireFeatureFlag');
 const { getFrontendBaseUrl } = require('../../utils/frontendUrl');
-const { SLIDESHOW_TRANSITIONS, SLIDESHOW_COLORFILTERS } = require('./helpers');
+const { SLIDESHOW_TRANSITIONS, SLIDESHOW_COLORFILTERS, SLIDESHOW_ORDERS } = require('./helpers');
 
 // The watermark LOOK (source/position/opacity/style/size) is global-only
 // (app_settings, Settings → Slideshow); events only carry the show_watermark
@@ -105,7 +105,9 @@ module.exports = (router) => {
     body('show_transition').optional().isIn(SLIDESHOW_TRANSITIONS),
     body('show_transition_ms').optional().isInt({ min: 100, max: 5000 }),
     body('show_watermark').optional({ nullable: true }),
-    body('show_colorfilter').optional().isIn(SLIDESHOW_COLORFILTERS)
+    body('show_colorfilter').optional().isIn(SLIDESHOW_COLORFILTERS),
+    body('show_order').optional().isIn(SLIDESHOW_ORDERS),
+    body('show_category_id').optional({ nullable: true }).isInt({ min: 1 })
   ], async (req, res) => {
     try {
       const errors = validationResult(req);
@@ -130,6 +132,23 @@ module.exports = (router) => {
           : formatBoolean(parseBooleanInput(req.body.show_watermark, false));
       }
       if (req.body.show_colorfilter !== undefined) updates.show_colorfilter = req.body.show_colorfilter;
+      if (req.body.show_order !== undefined) updates.show_order = req.body.show_order;
+      // Category filter (#202). null clears it (all photos). A non-null id must
+      // belong to this event or be a global category — otherwise ignore it so a
+      // stale/foreign id can't leak another event's category selection.
+      if (req.body.show_category_id !== undefined) {
+        if (req.body.show_category_id === null) {
+          updates.show_category_id = null;
+        } else {
+          const catId = parseInt(req.body.show_category_id, 10);
+          const cat = await db('photo_categories')
+            .where({ id: catId })
+            .where(function () { this.where('event_id', event.id).orWhere('is_global', formatBoolean(true)); })
+            .first();
+          if (!cat) return res.status(400).json({ error: 'Category does not belong to this event' });
+          updates.show_category_id = catId;
+        }
+      }
 
       // Knex throws on an empty update; only write if something changed.
       if (Object.keys(updates).length > 0) {
@@ -141,7 +160,9 @@ module.exports = (router) => {
         show_transition: updates.show_transition ?? event.show_transition ?? 'crossfade',
         show_transition_ms: updates.show_transition_ms ?? event.show_transition_ms ?? 800,
         show_watermark: updates.show_watermark ?? event.show_watermark ?? null,
-        show_colorfilter: updates.show_colorfilter ?? event.show_colorfilter ?? 'none'
+        show_colorfilter: updates.show_colorfilter ?? event.show_colorfilter ?? 'none',
+        show_order: updates.show_order ?? event.show_order ?? 'chronological',
+        show_category_id: 'show_category_id' in updates ? updates.show_category_id : (event.show_category_id ?? null)
       });
     } catch (error) {
       errorResponse(res, error, 500, 'Failed to update slideshow settings');

backend/src/routes/gallery.js

@@ -243,8 +243,8 @@ router.get('/:slug/info', async (req, res) => {
 
 // Photos a slideshow may display: published, finished, non-hidden. Mirrors the
 // guest filter in GET /:slug/photos so the live count matches the rendered set.
-function slideshowPhotosQuery(eventId) {
-  return db('photos')
+function slideshowPhotosQuery(eventId, categoryId = null) {
+  const q = db('photos')
     .where('photos.event_id', eventId)
     .where(function() {
       this.where('photos.processing_status', 'complete').orWhereNull('photos.processing_status');
@@ -252,6 +252,10 @@ function slideshowPhotosQuery(eventId) {
     .where(function() {
       this.where('photos.visibility', 'visible').orWhereNull('photos.visibility');
     });
+  // Category filter (#202) — keep the /session + /state count in sync with the
+  // photos the kiosk actually renders.
+  if (categoryId) q.where('photos.category_id', categoryId);
+  return q;
 }
 
 // Resolve an active slideshow by slug + token. Returns the event row, or null
@@ -324,6 +328,9 @@ async function slideshowSettings(event) {
     transition: event.show_transition || 'crossfade',
     transition_ms: event.show_transition_ms || 800,
     colorfilter: event.show_colorfilter || 'none',
+    // Play order (#202): 'chronological' | 'random'. The client shuffles when
+    // 'random' so live-appended uploads keep working.
+    order: event.show_order || 'chronological',
     fit: g.fit,
     watermark,
   };
@@ -356,7 +363,7 @@ router.get('/:slug/show/:token/session', handleAsync(async (req, res) => {
   // here so the kiosk's image requests are authorized with zero extra wiring.
   setGalleryAuthCookies(res, sessionToken, event.slug);
 
-  const [{ count }] = await slideshowPhotosQuery(event.id).count('* as count');
+  const [{ count }] = await slideshowPhotosQuery(event.id, event.show_category_id).count('* as count');
 
   res.json({
     token: sessionToken,
@@ -382,7 +389,7 @@ router.get('/:slug/show/:token/state', handleAsync(async (req, res) => {
     throw new NotFoundError('Slideshow');
   }
 
-  const [{ count }] = await slideshowPhotosQuery(event.id).count('* as count');
+  const [{ count }] = await slideshowPhotosQuery(event.id, event.show_category_id).count('* as count');
 
   res.json({
     ...(await slideshowSettings(event)),
@@ -426,6 +433,13 @@ router.get('/:slug/photos', verifyGalleryAccess, resolveGuest, async (req, res)
       });
     }
 
+    // Live Slideshow category filter (#202). Enforced server-side so the kiosk
+    // viewer can't widen the set: when the event pins show_category_id, the
+    // slideshow only sees that category. NULL = all photos (unchanged).
+    if (req.accessLevel === 'slideshow' && req.event.show_category_id) {
+      photosQuery = photosQuery.where('photos.category_id', req.event.show_category_id);
+    }
+
     // Apply sort option
     if (sort === 'capture_date') {
       // Sort by capture date, falling back to uploaded_at if capture date is null