From 0d002e054e32e19597fe6d6d70c1871177a211cc Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:16:42 +0800
Subject: [PATCH 001/105] docs: design webbooth improvement program

---
 ...-24-webbooth-improvement-program-design.md | 588 ++++++++++++++++++
 1 file changed, 588 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md

diff --git a/docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md b/docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md
new file mode 100644
index 0000000..4bd237c
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md
@@ -0,0 +1,588 @@
+# Webbooth improvement program
+
+**Date:** 2026-07-24  
+**Status:** Draft for review
+
+## Problem
+
+Webbooth already has strong storage isolation, exact-key moderation, durable
+photo recovery, data-driven Frames, and staged releases. Its remaining risks
+are concentrated at the product boundaries:
+
+- The Booth can appear usable before its credential, camera, storage, or
+  upload path has been verified.
+- Temporary upload failures require operator intervention, and a lost upload
+  response can produce a duplicate when retried.
+- Admin cannot see whether an actual Booth device is healthy or whether its
+  local Photo Outbox is draining.
+- The projector Live Gallery also serves phone users, despite those audiences
+  needing different interaction models.
+- Configuration has no immutable history, reusable presets, or private capture
+  metadata for meaningful post-event reporting.
+
+This program delivers the fifteen approved improvements without weakening the
+accepted architecture or event-day safety rules.
+
+## Goals
+
+1. Make a Booth prove readiness before accepting guests.
+2. Recover from transient connectivity failures automatically and without
+   duplicate photos.
+3. Give operators private, actionable device and rehearsal evidence.
+4. Improve capture review, personal photo handoff, accessibility, and
+   localization without reducing guest throughput.
+5. Separate projector and phone gallery experiences while retaining the
+   incremental Photo Feed.
+6. Make moderation scale beyond the recent contact sheet without weakening
+   complete-key Event ownership checks.
+7. Add immutable configuration history, reusable safe presets, and richer
+   streamed post-event packages.
+
+## Non-goals
+
+- No database, WebSockets, or Durable Object control plane.
+- No guest accounts, facial recognition, personal profiles, or stable guest
+  identifiers.
+- No bulk, prefix, or cross-Event photo deletion.
+- No secret, operational record, index, or metadata sidecar in public
+  `PHOTOS`.
+- No background-upload guarantee after iOS has killed or suspended the app.
+- No replacement for the real-iPad and projector rehearsal.
+- No automatic deletion or destructive migration of legacy records.
+
+## Approaches considered
+
+### Reliability-first
+
+Complete Booth and operations work before guest-facing changes. This minimizes
+event-day risk but delays visible product value.
+
+### Guest-experience-first
+
+Ship review, handoff, browse gallery, and localization first. This produces the
+fastest visible improvement but builds on an upload contract that is not yet
+idempotent.
+
+### Balanced dependency ladder — selected
+
+First establish immutable configuration, stable capture identity, and shared
+authentication. Then ship Booth reliability, guest capture, gallery and
+moderation, operator reuse, and post-event reporting as independent releases.
+This gives early reliability wins while keeping every release deployable and
+reversible at the Worker-code level.
+
+## Architectural decisions
+
+### Preserve the existing seams
+
+- `app/event-store.ts` remains the only owner of `PHOTOS` and `STATE` keys,
+  photo identity, configuration, indexes, exact deletion, and migrations.
+- Route handlers authenticate, canonicalize and validate HTTP input, then
+  delegate storage behavior to the Event Store.
+- The Booth Session owns accepted-photo durability, ordering, retry, and
+  upload acknowledgment.
+- Frame manifests continue to drive capture. A completed capture always
+  returns to a fresh Frame choice.
+- The Live Gallery and new browse Gallery share a Photo Feed controller but
+  keep separate presentations.
+
+### Make uploads idempotent before retrying automatically
+
+Every accepted capture receives one cryptographically random `captureId` and
+one monotonic `capturedAt` when it enters the Photo Outbox. The upload sends
+both values. The Event Store validates them and derives the same exact object
+key on every attempt:
+
+```text
+{event}/{13-digit-capturedAt}-{captureId}.jpg
+```
+
+A retry therefore acknowledges the existing object instead of creating a
+second photo. Old Booth clients without the new headers keep the current
+random-key upload path during rollout.
+
+The upload response adds `key`, `url`, and `duplicate` without removing the
+existing `url` field.
+
+### Keep operational state out of revisioned experience configuration
+
+Long-lived Event experience settings are revisioned. Transient pause state,
+device heartbeats, rehearsals, health, and photo indexes have separate private
+records. Pausing a Booth does not create a configuration revision.
+
+### Use private, rebuildable derived records
+
+Photo metadata and the moderation index live in `STATE`. `PHOTOS` remains the
+source of truth for whether a photo exists. Derived records are add-only or
+exact-key cleaned, can tolerate partial failure, and can be rebuilt from
+stored photos.
+
+## Private data model
+
+All keys below are in `STATE`:
+
+```text
+events/{event}/config.json
+events/{event}/config-revisions/{revisionId}.json
+events/{event}/booth-state.json
+events/{event}/booths/{deviceId}.json
+events/{event}/rehearsals/{rehearsalId}/session.json
+events/{event}/rehearsals/{rehearsalId}/evidence/{time}-{id}.json
+events/{event}/rehearsals/latest.json
+events/{event}/photo-index/v1/{inverseTime}-{encodedPhotoKey}.json
+events/{event}/photo-metadata/{photoFilename}.json
+presets/{presetId}.json
+```
+
+No new object type is stored under the public photo prefix except image bytes.
+
+### Event experience and revisions
+
+```ts
+type EventExperience = {
+  frames: string[];
+  locales?: LocaleCode[];
+  defaultLocale?: LocaleCode;
+  timeZone?: string;
+  capture?: {
+    reviewEnabled?: boolean;
+    autoAcceptSeconds?: number;
+    countdownAudioDefault?: boolean;
+  };
+  gallery?: {
+    title?: string;
+    accentColor?: string;
+  };
+};
+
+type EventConfig = EventExperience & {
+  boothKeyHash?: string;
+  currentRevisionId?: string;
+};
+
+type ConfigRevision = {
+  version: 1;
+  id: string;
+  createdAt: string;
+  parentRevisionId: string | null;
+  reason: "baseline" | "save" | "restore" | "preset";
+  sourceRevisionId?: string;
+  sourcePresetId?: string;
+  config: EventExperience;
+};
+```
+
+Revision records cannot contain a Booth Key hash. Saving requires a client
+mutation ID and the current base revision. A stale base returns `409`. The
+first revision-aware save appends a baseline for the legacy head. Restore
+creates a new revision and preserves the current Booth credential.
+
+R2 cannot transact the revision and head writes. An appended revision whose
+head update fails is harmless and is hidden unless it becomes reachable from
+the head. Retrying the same mutation ID is idempotent.
+
+### Outbox and private photo metadata
+
+The Outbox schema grows additively, so old IndexedDB rows remain readable:
+
+```ts
+type CaptureMetadata = {
+  frameKey?: string;
+  capturedAt: number;
+  source: "framed" | "camera-fallback";
+  configRevisionId?: string;
+};
+
+type OutboxItem = {
+  id: string;
+  event: string;
+  blob: Blob;
+  createdAt: number;
+  attempts: number;
+  lastError?: string;
+  nextAttemptAt?: number;
+  metadata?: CaptureMetadata;
+  rehearsalId?: string;
+};
+```
+
+After the photo write succeeds, the Event Store writes a best-effort private
+receipt with the complete key, upload and capture times, Frame, source, and
+config revision. Receipt failure must not cause an acknowledged photo to be
+retried. The export reports missing metadata as `unknown`.
+
+The private moderation index has different acknowledgment semantics: a new
+upload is acknowledged only after its deterministic photo key and immutable
+index record both exist. If indexing fails after the photo write, the route
+returns a retryable failure; the retry targets the same exact photo key and
+finishes the missing index without producing another image.
+
+### Booth heartbeat
+
+Each installed Booth has a locally generated UUID independent of its
+credential. Its bounded record includes server-controlled `lastSeenAt`,
+session start, pending count, durable-storage flag, online/camera/upload
+states, last successful upload, sanitized error class, and build identifier.
+
+It never includes credentials, hashes, thumbnails, arbitrary exception text,
+URLs, headers, user-agent strings, or guest identifiers.
+
+### Operational pause
+
+```ts
+type BoothOperationalState = {
+  version: 1;
+  paused: boolean;
+  messages?: Partial<Record<LocaleCode, string>>;
+  updatedAt: string;
+};
+```
+
+Pausing blocks new captures, lets an in-progress capture or review finish,
+stops the camera at the picker, and always lets the Photo Outbox drain.
+
+### Presets
+
+```ts
+type EventPreset = {
+  version: 1;
+  id: string;
+  label: string;
+  createdAt: string;
+  updatedAt: string;
+  config: EventExperience;
+};
+```
+
+Preset serialization constructs every field explicitly. It cannot copy Event
+identity, Booth credentials, revision IDs, health, device, or rehearsal state.
+Applying a preset creates a normal configuration revision. It preserves an
+existing target Booth Key and leaves a new Event visibly without one.
+
+## HTTP interfaces
+
+All Event parameters use `canonicalEvent()` and reject aliases.
+
+### Booth control
+
+- `POST /api/booth/preflight?event=` — Booth-or-Admin authenticated; validates
+  the credential and returns the safe enabled experience.
+- `POST /api/booths?event=` — Booth-or-Admin authenticated; writes one
+  sanitized heartbeat.
+- `GET /api/booths?event=` — Admin-only; pages through Booth records.
+- `GET /api/booth-state?event=` — public safe pause/message projection.
+- `PUT /api/booth-state?event=` — Admin-only pause/resume.
+
+One shared `boothOrAdminOk()` helper supplies identical authentication rules
+to preflight, upload, heartbeat, and rehearsal routes.
+
+### Configuration and presets
+
+- Existing `GET /api/config` remains public but constructs an allowlisted safe
+  response rather than serializing `EventConfig`.
+- Existing `PUT /api/config` becomes revision-aware and remains Admin-only.
+- `GET /api/config/revisions?event=` lists redacted history.
+- `POST /api/config/revisions/restore?event=` appends a restore revision.
+- `GET /api/presets`, `PUT /api/presets/{id}`, and
+  `POST /api/presets/apply?event=` are Admin-only.
+
+Initial preset scope omits deletion.
+
+### Photos, gallery, and moderation
+
+- Existing `POST /api/upload` accepts stable capture identity and returns the
+  complete key.
+- Existing public `GET /api/photos` retains its incremental
+  `after=<cursor>` contract.
+- `GET /api/photo?event=&key=` validates a complete Event-owned image key and
+  returns only public lightbox metadata.
+- `GET /api/moderation/photos?event=&cursor=&limit=&from=&to=` is Admin-only
+  and uses an opaque reverse-time pagination cursor.
+- Existing exact-key `DELETE /api/photos?event=&key=` remains externally
+  unchanged.
+
+### Rehearsal and export
+
+- Admin starts and reads a rehearsal through `/api/rehearsals`.
+- Booth-or-Admin authenticated actions append bounded evidence records.
+- Existing `/api/export` keeps its photo-only compatibility mode.
+- `GET /api/export?event=&format=package&contactSheet=1` streams the enriched
+  package and remains Admin-only.
+
+## User flows
+
+### Unlock and preflight
+
+The Booth state machine becomes:
+
+```text
+locked → checking → ready → capturing
+                 ↘ recovery-only
+                 ↘ unavailable
+```
+
+The Booth recovers and displays pending Outbox state before authentication,
+but does not start the camera or allow new captures until online preflight
+succeeds. The key lives in memory, with session persistence by default and an
+explicit “Remember on this iPad” local option. A `401` preserves the Outbox,
+clears the credential, and relocks.
+
+### Automatic retry
+
+Retryable network, `408`, `425`, `429`, and `5xx` failures use jittered
+exponential delays capped at 30 seconds and honor `Retry-After`. Reconnect and
+foreground events immediately reconsider the oldest eligible item.
+
+`400`, `401`, `403`, `413`, and `415` do not loop automatically. A `401`
+enters `auth-required`; manual Retry remains available. One permanent failure
+continues to block later items, preserving order.
+
+An IndexedDB Event lease prevents two tabs from actively draining the same
+queue. Server idempotency remains the final defense against races and lost
+acknowledgments.
+
+### Review, acceptance, and handoff
+
+```text
+picker → ready → capturing → reviewing → accepting → handoff
+                         ↘ retake → ready with the same Frame
+```
+
+The exact final composite is shown for a default five seconds with Use Photo,
+Retake, and More Time. Only acceptance encodes and enqueues the JPEG. A guarded
+decision prevents timer/button races. More Time cancels auto-accept.
+
+After acceptance, the Frame selection clears immediately. When the exact
+current handoff item is acknowledged, the Booth generates a local QR for:
+
+```text
+/{event}/gallery?photo={complete-object-key}
+```
+
+The complete key is percent-encoded as one query value. An older delayed upload
+never replaces the current guest’s handoff. Offline guests may continue
+without blocking the Booth; the Photo Outbox remains safe.
+
+### Projector and browse galleries
+
+`/{event}/live` remains the projector marquee with its existing newest-first
+insertion, independent looping columns, manual scrolling, lightbox, and
+reduced-motion behavior.
+
+`/{event}/gallery` is a phone-first, naturally scrolling newest-first view
+with shared save/share lightbox, direct-photo opening, scroll anchoring, an
+“N new photos” notice, and Jump to Latest. The projector QR points to
+`/{event}/gallery`.
+
+A shared pure Photo Feed controller owns cursor retention, deduplication,
+ordering, aborts, visibility, and scheduling. Projector polling begins around
+two seconds, browse around three to four seconds, quiet periods slow to 10–20
+seconds, hidden tabs stop, errors back off to 60 seconds, and foreground or
+manual retry refreshes immediately. Requests never overlap.
+
+### Scalable moderation
+
+New uploads append immutable reverse-time private index records. An add-only,
+checkpointed rebuild indexes legacy photos and writes a completion marker only
+after a full successful scan.
+
+Admin pages through the full Event with time filters, a larger inspection
+dialog, keyboard navigation, focus restoration, and an exact filename/key in
+the deletion confirmation. The photo is deleted first by complete key; index
+and receipt cleanup then target only their exact corresponding keys. Cleanup
+failure does not turn a confirmed photo deletion into an ambiguous retry.
+
+### Localization and accessibility
+
+A typed message catalog supplies English fallback. Only complete supported
+catalogs may be enabled. The selected per-device locale updates document
+language and direction. Frame manifests may add localized labels while
+retaining their required default label.
+
+Guest flows include at least 44×44 px controls, visible focus in high-contrast
+and forced-color modes, concise live announcements, optional countdown tones
+after user activation, persistent visual cues, reduced-motion behavior,
+semantic photo buttons, and a focus-managed lightbox. Every QR has a visible
+text link.
+
+### Guided rehearsal
+
+Admin starts a private rehearsal that snapshots the current Frames and config
+revision. Booth evidence is append-only. Completion requires:
+
+1. Valid unlock, camera readiness, and durable IndexedDB.
+2. One acknowledged capture for every enabled Frame.
+3. Two real network-class upload failures.
+4. Reload under a different boot ID with both items recovered.
+5. Ordered drain after reconnection.
+6. Exact Photo Feed and public-image observation.
+7. Exact-key deletion of one designated moderation canary photo.
+8. Empty Photo Outbox.
+
+Config changes make the rehearsal stale. Physical composition, projector,
+power, charging, and backup-network checks remain manual. Abandoned sessions
+show any remaining exact test keys and never bulk-clean them.
+
+Every rehearsal upload is tracked. Photos other than the designated moderation
+canary are either explicitly retained or individually removed by complete key;
+rehearsal completion never authorizes automatic or prefix cleanup.
+
+### Installed Booth mode
+
+A public per-Event manifest opens the same canonical Event in standalone
+landscape mode without credentials in its URL or manifest. Operator actions
+request and reacquire Screen Wake Lock where supported, with iPad Auto-Lock
+instructions as fallback.
+
+Navigation warnings appear only during capture, durable handoff, or a non-empty
+Outbox. A discoverable authenticated operator exit stops camera tracks and
+wake lock but preserves pending photos.
+
+If an offline shell is added, it caches only the Booth shell, build-versioned
+static assets, icons, and Frame artwork. It never caches authenticated APIs,
+photos, Admin, export, moderation, heartbeat, health, or rehearsal requests,
+and it never touches Outbox IndexedDB. Offline reload permits recovery only;
+fresh capture still requires online preflight.
+
+Release 1 requires the manifest, standalone detection, wake behavior,
+navigation protection, and operator exit. A service-worker shell is included
+only if staging tests show that installed-mode relaunch cannot reliably load
+the network shell; it is not required for accepted-photo durability.
+
+### Post-event package
+
+The streamed package contains:
+
+```text
+photos/{filename}.jpg
+manifest.csv
+summary.json
+contact-sheet.html
+```
+
+The manifest records complete key, filename, size, upload and capture times,
+timestamp source, Frame key/label, and capture source. The summary includes
+photo and byte counts, metadata coverage, Frame usage, first/last capture,
+hourly buckets, and busiest periods in the configured time zone.
+
+Analytics are rebuilt from current photos joined to optional private receipts.
+Missing receipts produce `unknown`; deleted photos are excluded. The contact
+sheet is printable, self-contained HTML with relative photo references, inline
+CSS, no JavaScript, and no external requests. CSV cells and HTML are escaped,
+including spreadsheet-formula prefixes.
+
+## Delivery plan
+
+### Release 0 — compatible foundations
+
+- Characterization and privacy regression tests.
+- Revision-aware Event experience schema and configuration history (#13).
+- Shared Booth authentication.
+- Stable capture identity and idempotent upload.
+- Additive Outbox metadata and private photo receipt/index interfaces.
+
+### Release 1 — reliable Booth control
+
+- Automatic Outbox retry (#2).
+- Unlock and authenticated preflight (#1).
+- Private Booth heartbeat and Admin device status (#3).
+- Pause/resume control (#8).
+- Installed Booth/PWA behavior (#5).
+
+### Release 2 — guest capture
+
+- Timed review/retake (#6).
+- Exact-photo handoff QR (#7).
+- Localization and accessibility foundations applied to changed screens (#12).
+
+### Release 3 — gallery and moderation
+
+- Separate browse Gallery while preserving projector Live Gallery (#9).
+- Shared adaptive polling controller (#10).
+- Reverse-time moderation index, migration, and paged Admin UI (#11).
+- Complete accessibility and localization coverage (#12).
+
+### Release 4 — repeatable operations
+
+- Safe Event presets (#14).
+- Guided real-device rehearsal and evidence (#4).
+
+### Release 5 — post-event value
+
+- Private capture analytics.
+- Streamed manifest, summary, and contact sheet package (#15).
+
+Each release receives its own implementation plan, verification pass, staging
+smoke test, and real-device checks where camera, storage, installed mode, or
+VoiceOver behavior is involved.
+
+## Error handling and migration
+
+- All schema additions are optional or versioned; old config and Outbox records
+  remain readable.
+- Unsupported future stored versions fail explicitly rather than falling back
+  to stale legacy state.
+- Every new private write targets a complete key. Migrations are add-only and
+  checkpointed.
+- A photo write is authoritative. Private receipt failure is observable but
+  does not requeue an acknowledged image.
+- Heartbeat failure never blocks capture or upload.
+- Pause polling failure retains the last-known state and shows connectivity
+  status.
+- Gallery failures leave existing photos visible and provide manual retry.
+- Config conflicts return `409` and require reload instead of last-writer-wins.
+- Staging and production retain separate Workers, buckets, domains, and
+  secrets.
+- Rollback changes Worker code only; it never rolls back or deletes data.
+
+## Verification
+
+### Unit and contract coverage
+
+- Shared authentication and preflight response redaction.
+- Stable upload identity, lost acknowledgment, and concurrent retry behavior.
+- Retry policy, `Retry-After`, reconnect, reload, permanent errors, ordering,
+  lease expiry, and Event isolation.
+- Revision baseline/save/restore, mutation idempotency, stale-head conflict,
+  key preservation, and secret redaction.
+- Heartbeat validation, server timestamps, paging, stale derivation, and
+  cross-Event isolation.
+- Review timeout, More Time, button/timer race, encode failure, and retake.
+- Current-handoff QR identity and delayed-upload protection.
+- Pause during picker, capture, review, and Outbox drain.
+- Photo Feed cadence, visibility, abort, no-overlap, deduplication, and cursor
+  reset.
+- Moderation ordering, opaque cursor, time filters, index rebuild resume, and
+  exact deletion cleanup.
+- Locale completeness, fallback, direction, Frame label fallback, and pure
+  focus/scroll-anchor logic.
+- Rehearsal evidence reduction, config invalidation, reload proof, exact
+  gallery correlation, and exact deletion.
+- Preset validation and proof that credentials and Event identity cannot copy.
+- ZIP structure, manifest escaping, metadata gaps, generated-entry limits, and
+  absence of private operational records.
+
+### Browser and real-device coverage
+
+- Playwright/WebKit journeys with mocked camera and feed.
+- Keyboard-only and automated accessibility checks.
+- Real iPad Safari and installed-mode unlock, permissions, wake behavior,
+  review, audio, offline queue, reload, reconnect, and exit.
+- VoiceOver on iPad/iPhone.
+- Projector marquee and phone browse anchoring.
+- Multi-page moderation with one exact-key deletion.
+- Full rehearsal on staging using a throwaway Event distinct from production.
+
+The standard Bun type checks, tests, Frame validation, and production build
+remain mandatory in CI and before every deployment.
+
+## Safety invariants
+
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+- Never expose Event state, indexes, metadata, revision records, Booth
+  heartbeats, or credential hashes through public objects.
+- Never accept a photo prefix or filename fragment for moderation.
+- Never silently slug an Event at an HTTP boundary.
+- Never auto-select or retain a Frame after a completed capture.
+- Never remove an accepted Outbox item before storage acknowledgment.
+- Never deploy the unnamed Wrangler environment to an event domain.

From bbffbae83c35ae8f2e726c810b6afb32e5a3cc63 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:16:56 +0800
Subject: [PATCH 002/105] docs: clean improvement spec formatting

---
 .../specs/2026-07-24-webbooth-improvement-program-design.md     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md b/docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md
index 4bd237c..950707e 100644
--- a/docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md
+++ b/docs/superpowers/specs/2026-07-24-webbooth-improvement-program-design.md
@@ -1,6 +1,6 @@
 # Webbooth improvement program
 
-**Date:** 2026-07-24  
+**Date:** 2026-07-24
 **Status:** Draft for review
 
 ## Problem

From 3c31c369f6a4ab0d58963866f9b0b0173fd587ee Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:34:24 +0800
Subject: [PATCH 003/105] docs: plan release zero foundations

---
 .../2026-07-24-release-0a-config-history.md   | 763 ++++++++++++++++++
 ...2026-07-24-release-0b-idempotent-ingest.md | 557 +++++++++++++
 2 files changed, 1320 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-24-release-0a-config-history.md
 create mode 100644 docs/superpowers/plans/2026-07-24-release-0b-idempotent-ingest.md

diff --git a/docs/superpowers/plans/2026-07-24-release-0a-config-history.md b/docs/superpowers/plans/2026-07-24-release-0a-config-history.md
new file mode 100644
index 0000000..b566a1f
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-24-release-0a-config-history.md
@@ -0,0 +1,763 @@
+# Release 0A Configuration History Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add immutable, conflict-safe Event configuration revisions, restore, and an Admin history panel without exposing or restoring Booth credentials.
+
+**Architecture:** A focused `event-config` module owns versioned parsing and explicit public projection. `EventStore` appends immutable revision objects in private `STATE` and advances the config head with compare-and-swap; API handlers are dependency-injected and route files remain thin. Admin saves and restores against an explicit base revision and retains mutation IDs across ambiguous network failures.
+
+**Tech Stack:** Bun, TypeScript, Next.js 15 App Router, React 19, Cloudflare Workers, R2, CSS Modules.
+
+## Global Constraints
+
+- Use Bun commands only.
+- `EventStore` remains the sole owner of `PHOTOS` and `STATE` keys.
+- Event route inputs use `canonicalEvent()` and reject non-canonical aliases.
+- Config heads, revisions, and Booth Key hashes remain in private `STATE`.
+- Public config is constructed from an allowlist and never includes `boothKeyHash` or `currentRevisionId`.
+- Revisions are immutable, reachable-history only, and never contain a Booth credential.
+- Restore creates a new revision and preserves the current Booth Key hash.
+- All migrations are additive; legacy public config remains untouched for rollback.
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+
+---
+
+## File structure
+
+- Create `app/event-config.ts` — config/revision types, validation, safe projection, revision-ID validation.
+- Create `app/event-config.test.ts` — schema and privacy characterization.
+- Modify `app/event-store.ts` — object etags/CAS, revision keys, save/restore/history.
+- Modify `app/event-store.test.ts` — CAS, concurrency, immutable history, restore.
+- Create `app/api/config/handlers.ts` — dependency-injected config HTTP behavior.
+- Create `app/api/config/handlers.test.ts` — HTTP status, auth, redaction, conflict tests.
+- Modify `app/api/config/route.ts` — thin GET/PUT adapters.
+- Create `app/api/config/revisions/route.ts` — thin history GET adapter.
+- Create `app/api/config/revisions/restore/route.ts` — thin restore POST adapter.
+- Create `app/[event]/admin/config-history-panel.tsx` — focused history presentation.
+- Create `app/[event]/admin/config-history-panel.test.tsx` — pure diff and server-render tests.
+- Modify `app/[event]/admin/page.tsx` — revision-aware load/save/restore state.
+- Modify `app/[event]/admin/admin.module.css` — history panel styling.
+- Modify `tsconfig.test.json` — include `.test.tsx`.
+
+### Task 1: Define the revisioned Event schema and safe projection
+
+**Files:**
+- Create: `app/event-config.ts`
+- Create: `app/event-config.test.ts`
+
+**Interfaces:**
+- Produces: `EventExperience`, `EventConfig`, `ConfigRevision`, `PublicEventConfig`.
+- Produces: `parseEventConfig(value)`, `parseConfigRevision(value)`, `projectPublicConfig(config)`, `isRevisionId(value)`.
+- Consumed by: Tasks 2–5.
+
+- [ ] **Step 1: Write the failing schema and privacy tests**
+
+```ts
+import { describe, expect, test } from "bun:test";
+import {
+  isRevisionId,
+  parseConfigRevision,
+  parseEventConfig,
+  projectPublicConfig,
+} from "./event-config";
+
+describe("event config schema", () => {
+  test("parses the complete additive experience", () => {
+    expect(parseEventConfig({
+      version: 1,
+      frames: ["square"],
+      boothKeyHash: "secret-hash",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    })).toEqual({
+      frames: ["square"],
+      boothKeyHash: "secret-hash",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+  });
+
+  test("rejects unsupported versions and malformed nested settings", () => {
+    expect(parseEventConfig({ version: 2, frames: [] })).toBeNull();
+    expect(parseEventConfig({ version: 1, frames: [], capture: { autoAcceptSeconds: -1 } })).toBeNull();
+    expect(parseEventConfig({ version: 1, frames: [], gallery: { accentColor: "red<script>" } })).toBeNull();
+  });
+
+  test("projects only public allowlisted fields", () => {
+    const projected = projectPublicConfig({
+      frames: ["square"],
+      boothKeyHash: "secret-hash",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      locales: ["en"],
+      defaultLocale: "en",
+    });
+    expect(projected).toEqual({
+      frames: ["square"],
+      hasBoothKey: true,
+      locales: ["en"],
+      defaultLocale: "en",
+    });
+    const json = JSON.stringify(projected);
+    expect(json).not.toContain("boothKeyHash");
+    expect(json).not.toContain("currentRevisionId");
+    expect(projectPublicConfig(null)).toEqual({ frames: null, hasBoothKey: false });
+  });
+
+  test("revision parsing rejects credentials inside experience", () => {
+    const base = {
+      version: 1,
+      id: "018f0000-0000-7000-8000-000000000001",
+      createdAt: "2026-07-24T00:00:00.000Z",
+      parentRevisionId: null,
+      reason: "baseline",
+    };
+    expect(parseConfigRevision({ ...base, config: { frames: ["square"] } })).not.toBeNull();
+    expect(parseConfigRevision({ ...base, config: { frames: ["square"], boothKeyHash: "leak" } })).toBeNull();
+  });
+
+  test("accepts UUID mutation/revision IDs only", () => {
+    expect(isRevisionId("018f0000-0000-7000-8000-000000000001")).toBe(true);
+    expect(isRevisionId("../config")).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test and verify the missing module failure**
+
+Run: `bun test app/event-config.test.ts`
+
+Expected: FAIL because `./event-config` does not exist.
+
+- [ ] **Step 3: Implement the schema and explicit projection**
+
+```ts
+export const EVENT_CONFIG_VERSION = 1 as const;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+
+export type LocaleCode = string;
+export type EventExperience = {
+  frames: string[];
+  locales?: LocaleCode[];
+  defaultLocale?: LocaleCode;
+  timeZone?: string;
+  capture?: {
+    reviewEnabled?: boolean;
+    autoAcceptSeconds?: number;
+    countdownAudioDefault?: boolean;
+  };
+  gallery?: { title?: string; accentColor?: string };
+};
+export type EventConfig = EventExperience & {
+  boothKeyHash?: string;
+  currentRevisionId?: string;
+};
+export type ConfigRevision = {
+  version: 1;
+  id: string;
+  createdAt: string;
+  parentRevisionId: string | null;
+  reason: "baseline" | "save" | "restore" | "preset";
+  sourceRevisionId?: string;
+  sourcePresetId?: string;
+  config: EventExperience;
+};
+export type PublicEventConfig = Omit<EventExperience, "frames"> & {
+  frames: string[] | null;
+  hasBoothKey: boolean;
+};
+
+export const isRevisionId = (value: unknown): value is string =>
+  typeof value === "string" && UUID.test(value);
+
+function parseExperience(value: unknown): EventExperience | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (!Array.isArray(v.frames) || !v.frames.every((x) => typeof x === "string" && TOKEN.test(x))) return null;
+  if (v.locales !== undefined && (!Array.isArray(v.locales) || !v.locales.every((x) => typeof x === "string" && TOKEN.test(x)))) return null;
+  if (v.defaultLocale !== undefined && (typeof v.defaultLocale !== "string" || !TOKEN.test(v.defaultLocale))) return null;
+  if (v.timeZone !== undefined && (typeof v.timeZone !== "string" || v.timeZone.length > 128)) return null;
+  const capture = v.capture as Record<string, unknown> | undefined;
+  if (capture !== undefined && (!capture || typeof capture !== "object")) return null;
+  if (capture?.reviewEnabled !== undefined && typeof capture.reviewEnabled !== "boolean") return null;
+  if (capture?.countdownAudioDefault !== undefined && typeof capture.countdownAudioDefault !== "boolean") return null;
+  if (capture?.autoAcceptSeconds !== undefined && (typeof capture.autoAcceptSeconds !== "number" || !Number.isInteger(capture.autoAcceptSeconds) || capture.autoAcceptSeconds < 1 || capture.autoAcceptSeconds > 30)) return null;
+  const gallery = v.gallery as Record<string, unknown> | undefined;
+  if (gallery !== undefined && (!gallery || typeof gallery !== "object")) return null;
+  if (gallery?.title !== undefined && (typeof gallery.title !== "string" || gallery.title.length > 120)) return null;
+  if (gallery?.accentColor !== undefined && (typeof gallery.accentColor !== "string" || !HEX_COLOR.test(gallery.accentColor))) return null;
+  return {
+    frames: [...v.frames] as string[],
+    ...(v.locales ? { locales: [...v.locales] as string[] } : {}),
+    ...(typeof v.defaultLocale === "string" ? { defaultLocale: v.defaultLocale } : {}),
+    ...(typeof v.timeZone === "string" ? { timeZone: v.timeZone } : {}),
+    ...(capture ? { capture: { ...capture } as EventExperience["capture"] } : {}),
+    ...(gallery ? { gallery: { ...gallery } as EventExperience["gallery"] } : {}),
+  };
+}
+
+export function parseEventConfig(value: unknown): EventConfig | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.version !== undefined && v.version !== EVENT_CONFIG_VERSION) return null;
+  const experience = parseExperience({ ...v, frames: v.frames ?? [] });
+  if (!experience) return null;
+  if (v.boothKeyHash !== undefined && typeof v.boothKeyHash !== "string") return null;
+  if (v.currentRevisionId !== undefined && !isRevisionId(v.currentRevisionId)) return null;
+  return {
+    ...experience,
+    ...(typeof v.boothKeyHash === "string" ? { boothKeyHash: v.boothKeyHash } : {}),
+    ...(typeof v.currentRevisionId === "string" ? { currentRevisionId: v.currentRevisionId } : {}),
+  };
+}
+
+export function parseConfigRevision(value: unknown): ConfigRevision | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.version !== 1 || !isRevisionId(v.id) || typeof v.createdAt !== "string") return null;
+  if (v.parentRevisionId !== null && !isRevisionId(v.parentRevisionId)) return null;
+  if (!["baseline", "save", "restore", "preset"].includes(String(v.reason))) return null;
+  const config = parseExperience(v.config);
+  if (!config || (v.config as Record<string, unknown>).boothKeyHash !== undefined) return null;
+  return { ...v, config } as ConfigRevision;
+}
+
+export function projectPublicConfig(config: EventConfig | null): PublicEventConfig {
+  if (!config) return { frames: null, hasBoothKey: false };
+  return {
+    frames: [...config.frames],
+    hasBoothKey: Boolean(config.boothKeyHash),
+    ...(config.locales ? { locales: [...config.locales] } : {}),
+    ...(config.defaultLocale ? { defaultLocale: config.defaultLocale } : {}),
+    ...(config.timeZone ? { timeZone: config.timeZone } : {}),
+    ...(config.capture ? { capture: { ...config.capture } } : {}),
+    ...(config.gallery ? { gallery: { ...config.gallery } } : {}),
+  };
+}
+```
+
+- [ ] **Step 4: Run schema tests and both type-checkers**
+
+Run: `bun test app/event-config.test.ts && bun run typecheck && bun run typecheck:tests`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/event-config.ts app/event-config.test.ts
+git commit -m "feat: define revisioned event experience schema"
+```
+
+### Task 2: Add immutable revision storage and compare-and-swap
+
+**Files:**
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: Task 1 config parsers and types.
+- Produces: `ObjectStore.compareAndSwap()`, `eventConfigRevisionKey()`, `saveConfigRevision()`.
+- Produces: `ConfigConflictError`, `ConfigMutationConflictError`, `ConfigMutationResult`.
+
+- [ ] **Step 1: Add failing CAS and save-history tests**
+
+Add tests that perform these exact assertions:
+
+```ts
+test("compareAndSwap rejects a stale etag", async () => {
+  const state = new InMemoryObjectStore();
+  expect(await state.compareAndSwap("head", null, "one")).toBe(true);
+  const first = await state.get("head");
+  expect(await state.compareAndSwap("head", "stale", "two")).toBe(false);
+  expect(await state.compareAndSwap("head", first!.etag, "two")).toBe(true);
+  expect(await first!.text()).toBe("one");
+  expect(await (await state.get("head"))!.text()).toBe("two");
+});
+
+test("first revision save appends baseline and preserves booth key", async () => {
+  const state = new InMemoryObjectStore({
+    [eventConfigKey("launch")]: JSON.stringify({ version: 1, frames: ["old"], boothKeyHash: "hash" }),
+  });
+  const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example", () => new Date("2026-07-24T00:00:00Z"));
+  const result = await store.saveConfigRevision("launch", {
+    config: { frames: ["new"] },
+    baseRevisionId: null,
+    mutationId: "018f0000-0000-7000-8000-000000000002",
+  });
+  expect(result.config.boothKeyHash).toBe("hash");
+  expect(result.revision.parentRevisionId).not.toBeNull();
+  expect(result.idempotent).toBe(false);
+  expect((await store.readConfig("launch"))?.currentRevisionId).toBe(result.revision.id);
+});
+
+test("stale save conflicts and an identical mutation retry is idempotent", async () => {
+  const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+  const input = {
+    config: { frames: ["one"] },
+    baseRevisionId: null,
+    mutationId: "018f0000-0000-7000-8000-000000000003",
+  };
+  expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(false);
+  expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(true);
+  await expect(store.saveConfigRevision("launch", {
+    ...input,
+    mutationId: "018f0000-0000-7000-8000-000000000004",
+  })).rejects.toBeInstanceOf(ConfigConflictError);
+});
+```
+
+Also add tests for one CAS winner from two concurrent saves, an orphan revision
+hidden from later history, and a mutation ID reused with different config
+throwing `ConfigMutationConflictError`.
+
+- [ ] **Step 2: Run the Event Store tests and confirm missing-interface failures**
+
+Run: `bun test app/event-store.test.ts`
+
+Expected: FAIL because `etag`, `compareAndSwap`, and `saveConfigRevision` do not exist.
+
+- [ ] **Step 3: Implement etags, immutable revision keys, and CAS save**
+
+Add to the storage interface:
+
+```ts
+export type StoredObject = {
+  key: string;
+  size: number;
+  uploaded: Date;
+  etag: string;
+};
+
+export interface ObjectStore {
+  get(key: string): Promise<StoredObjectBody | null>;
+  put(key: string, value: ArrayBuffer | ArrayBufferView | string, options?: R2PutOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: ListOptions): Promise<ListResult>;
+  compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string,
+    options?: R2PutOptions
+  ): Promise<boolean>;
+}
+```
+
+Implement R2 CAS with `onlyIf: expectedEtag === null
+? { etagDoesNotMatch: "*" } : { etagMatches: expectedEtag }`. Implement the
+memory adapter by checking the current entry etag immediately before replacing
+it and assigning a new `crypto.randomUUID()` etag.
+
+Add the public revision interfaces:
+
+```ts
+export const eventConfigRevisionPrefix = (event: string) =>
+  `events/${event}/config-revisions/`;
+export const eventConfigRevisionKey = (event: string, id: string) =>
+  `${eventConfigRevisionPrefix(event)}${id}.json`;
+
+export type ConfigMutationResult = {
+  config: EventConfig;
+  revision: ConfigRevision;
+  idempotent: boolean;
+};
+
+export class ConfigConflictError extends Error {
+  constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
+    super("event configuration changed");
+  }
+}
+export class ConfigMutationConflictError extends Error {
+  constructor() { super("mutation ID was already used for different configuration"); }
+}
+```
+
+Implement `saveConfigRevision(event, input)` in this order:
+
+1. Read the current head plus etag.
+2. If a revision with `mutationId` exists, compare its canonical JSON payload
+   with the requested revision and either finish/return idempotently or throw
+   `ConfigMutationConflictError`.
+3. Compare `baseRevisionId` with the current head.
+4. If the head is legacy, append one `crypto.randomUUID()` baseline revision;
+   never include its Booth Key hash. The following save revision records that
+   baseline as its parent, so an existing mutation revision is the recovery
+   anchor after a partial failure.
+5. Append the immutable save revision with `compareAndSwap(key, null, json)`.
+6. Advance `config.json` with CAS, merging the new experience with the existing
+   hash unless a replacement hash was supplied.
+7. Throw `ConfigConflictError` if the head CAS loses.
+
+- [ ] **Step 4: Run Event Store tests and type-check**
+
+Run: `bun test app/event-store.test.ts && bun run typecheck && bun run typecheck:tests`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/event-store.ts app/event-store.test.ts
+git commit -m "feat: append immutable event config revisions"
+```
+
+### Task 3: Add reachable history and restore
+
+**Files:**
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: Task 2 immutable revisions.
+- Produces: `readConfigHistory(event)`, `restoreConfigRevision(event, input)`.
+- Produces: `ConfigRevisionNotFoundError`, `InvalidStoredConfigRevisionError`.
+
+- [ ] **Step 1: Write failing history and restore tests**
+
+```ts
+test("history follows only the reachable head chain and restore appends", async () => {
+  const state = new InMemoryObjectStore();
+  const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+  const first = await store.saveConfigRevision("launch", {
+    config: { frames: ["one"] },
+    baseRevisionId: null,
+    mutationId: "018f0000-0000-7000-8000-000000000010",
+  });
+  const second = await store.saveConfigRevision("launch", {
+    config: { frames: ["two"] },
+    baseRevisionId: first.revision.id,
+    mutationId: "018f0000-0000-7000-8000-000000000011",
+  });
+  state.set(eventConfigRevisionKey("launch", "018f0000-0000-7000-8000-000000000099"), JSON.stringify({
+    version: 1,
+    id: "018f0000-0000-7000-8000-000000000099",
+    createdAt: "2026-07-24T00:00:00Z",
+    parentRevisionId: null,
+    reason: "save",
+    config: { frames: ["orphan"] },
+  }));
+  expect((await store.readConfigHistory("launch")).revisions.map((r) => r.id)).toEqual([
+    second.revision.id,
+    first.revision.id,
+  ]);
+  const restored = await store.restoreConfigRevision("launch", {
+    revisionId: first.revision.id,
+    baseRevisionId: second.revision.id,
+    mutationId: "018f0000-0000-7000-8000-000000000012",
+  });
+  expect(restored.config.frames).toEqual(["one"]);
+  expect(restored.revision).toMatchObject({
+    reason: "restore",
+    sourceRevisionId: first.revision.id,
+    parentRevisionId: second.revision.id,
+  });
+});
+```
+
+Add explicit tests for a missing source, corrupt reachable JSON, a missing
+parent, a cycle, stale restore, idempotent retry, and Booth Key preservation.
+
+- [ ] **Step 2: Run the focused tests and verify missing-method failures**
+
+Run: `bun test app/event-store.test.ts`
+
+Expected: FAIL because history and restore methods are missing.
+
+- [ ] **Step 3: Implement reachable traversal and restore-as-append**
+
+```ts
+export type ConfigHistory = {
+  config: EventConfig | null;
+  currentRevisionId: string | null;
+  revisions: ConfigRevision[];
+};
+export class ConfigRevisionNotFoundError extends Error {}
+export class InvalidStoredConfigRevisionError extends Error {}
+```
+
+`readConfigHistory()` starts at `config.currentRevisionId`, loads each complete
+revision key, validates it, tracks visited IDs, and follows `parentRevisionId`
+until null. It throws on missing/corrupt/future/cyclic reachable records and
+never lists prefix orphans.
+
+`restoreConfigRevision()` loads the selected reachable revision, then calls the
+same append/CAS primitive as save with `reason: "restore"` and
+`sourceRevisionId`. It uses the selected `EventExperience` and always carries
+the current head’s Booth Key hash.
+
+- [ ] **Step 4: Run the Event Store suite**
+
+Run: `bun test app/event-store.test.ts && bun run typecheck && bun run typecheck:tests`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/event-store.ts app/event-store.test.ts
+git commit -m "feat: restore event config from revision history"
+```
+
+### Task 4: Expose revision-aware HTTP contracts
+
+**Files:**
+- Create: `app/api/config/handlers.ts`
+- Create: `app/api/config/handlers.test.ts`
+- Modify: `app/api/config/route.ts`
+- Create: `app/api/config/revisions/route.ts`
+- Create: `app/api/config/revisions/restore/route.ts`
+
+**Interfaces:**
+- Consumes: Tasks 1–3.
+- Produces: public GET, Admin save/history/restore handlers with deterministic status mapping.
+- Consumed by: Task 5 Admin UI.
+
+- [ ] **Step 1: Write failing dependency-injected handler tests**
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import { EventStore, InMemoryObjectStore } from "@/app/event-store";
+import { getPublicConfig, getConfigRevisions, postConfigRestore, putConfig } from "./handlers";
+
+const deps = () => ({
+  store: new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example"),
+  adminKey: "admin-secret",
+  hashBoothKey: async (key: string) => `hashed:${key}`,
+});
+const request = (url: string, init: RequestInit = {}) => new NextRequest(url, init);
+
+describe("config handlers", () => {
+  test("public config is explicitly redacted", async () => {
+    const d = deps();
+    await d.store.writeConfig("launch", { frames: ["square"], boothKeyHash: "secret" });
+    const response = await getPublicConfig(request("https://app.test/api/config?event=launch"), d);
+    expect(await response.json()).toEqual({ frames: ["square"], hasBoothKey: true });
+  });
+
+  test("save requires canonical Event, Admin Key, mutation, and base", async () => {
+    const d = deps();
+    const response = await putConfig(request("https://app.test/api/config?event=launch", {
+      method: "PUT",
+      headers: { "x-booth-key": "admin-secret", "content-type": "application/json" },
+      body: JSON.stringify({
+        frames: ["square"],
+        boothKey: "123456789012",
+        mutationId: "018f0000-0000-7000-8000-000000000020",
+        baseRevisionId: null,
+      }),
+    }), d);
+    expect(response.status).toBe(200);
+    expect(await response.json()).toMatchObject({
+      frames: ["square"],
+      hasBoothKey: true,
+      currentRevisionId: "018f0000-0000-7000-8000-000000000020",
+      idempotent: false,
+    });
+  });
+});
+```
+
+Add cases for `400`, `401`, `503`, `404`, `409`, alias rejection, unknown
+Frame, invalid key length, idempotent retry, authenticated history, restore,
+and recursive response scans for credential fields.
+
+- [ ] **Step 2: Run handler tests and verify missing-module failure**
+
+Run: `bun test app/api/config/handlers.test.ts`
+
+Expected: FAIL because `handlers.ts` does not exist.
+
+- [ ] **Step 3: Implement handlers and thin route adapters**
+
+Use these exact request bodies:
+
+```ts
+type SaveBody = {
+  frames: string[];
+  boothKey?: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+};
+type RestoreBody = {
+  revisionId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+};
+```
+
+Export:
+
+```ts
+export type ConfigHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+  hashBoothKey: (key: string) => Promise<string>;
+};
+export function getPublicConfig(req: NextRequest, deps: ConfigHandlerDeps): Promise<NextResponse>;
+export function putConfig(req: NextRequest, deps: ConfigHandlerDeps): Promise<NextResponse>;
+export function getConfigRevisions(req: NextRequest, deps: ConfigHandlerDeps): Promise<NextResponse>;
+export function postConfigRestore(req: NextRequest, deps: ConfigHandlerDeps): Promise<NextResponse>;
+```
+
+Return `400` for malformed input, `401` for rejected Admin Key, `503` when the
+Admin Key is unavailable, `404` for a missing restore source, and `409` for
+stale base or mutation reuse. Successful save/restore returns the safe
+projection plus `currentRevisionId` and `idempotent`. History returns only
+reachable revisions and safe current config.
+
+Each route file obtains `{ env }`, creates `EventStore.fromEnv(env)`, and calls
+one handler. No route constructs storage keys.
+
+- [ ] **Step 4: Run handler tests and application type-check**
+
+Run: `bun test app/api/config/handlers.test.ts && bun run typecheck && bun run typecheck:tests`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/api/config
+git commit -m "feat: expose config history and restore APIs"
+```
+
+### Task 5: Add Admin configuration history and conflict-safe save
+
+**Files:**
+- Create: `app/[event]/admin/config-history-panel.tsx`
+- Create: `app/[event]/admin/config-history-panel.test.tsx`
+- Modify: `app/[event]/admin/page.tsx`
+- Modify: `app/[event]/admin/admin.module.css`
+- Modify: `tsconfig.test.json`
+
+**Interfaces:**
+- Consumes: Task 4 API shapes.
+- Produces: visible history, restore confirmation, retained mutation retries, and conflict reload.
+
+- [ ] **Step 1: Write failing pure component and diff tests**
+
+```tsx
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ConfigHistoryPanel, diffFrameKeys } from "./config-history-panel";
+
+test("diffFrameKeys reports additions and removals", () => {
+  expect(diffFrameKeys(["one", "three"], ["one", "two"])).toEqual({
+    added: ["two"],
+    removed: ["three"],
+  });
+});
+
+test("history renders reasons and disables restoring the current revision", () => {
+  const html = renderToStaticMarkup(
+    <ConfigHistoryPanel
+      currentFrames={["one"]}
+      currentRevisionId="018f0000-0000-7000-8000-000000000030"
+      revisions={[{
+        version: 1,
+        id: "018f0000-0000-7000-8000-000000000030",
+        createdAt: "2026-07-24T00:00:00.000Z",
+        parentRevisionId: null,
+        reason: "save",
+        config: { frames: ["one"] },
+      }]}
+      loading={false}
+      restoringRevisionId={null}
+      error=""
+      onReload={() => {}}
+      onRestore={() => {}}
+    />
+  );
+  expect(html).toContain("Configuration history");
+  expect(html).toContain("Current");
+  expect(html).toContain("disabled");
+  expect(html).not.toContain("boothKey");
+});
+```
+
+- [ ] **Step 2: Run the component test and verify missing-module failure**
+
+Run: `bun test 'app/[event]/admin/config-history-panel.test.tsx'`
+
+Expected: FAIL because the panel does not exist.
+
+- [ ] **Step 3: Implement the focused panel**
+
+```tsx
+"use client";
+import type { ConfigRevision } from "../../event-config";
+
+export type ConfigHistoryPanelProps = {
+  currentFrames: readonly string[];
+  currentRevisionId: string | null;
+  revisions: readonly ConfigRevision[];
+  loading: boolean;
+  restoringRevisionId: string | null;
+  error: string;
+  onReload: () => void;
+  onRestore: (revisionId: string) => void;
+};
+
+export function diffFrameKeys(current: readonly string[], historical: readonly string[]) {
+  return {
+    added: historical.filter((key) => !current.includes(key)),
+    removed: current.filter((key) => !historical.includes(key)),
+  };
+}
+```
+
+Render revision time, reason, Frame count, Current marker, added/removed Frame
+labels, reload failure state, and a two-step exact revision/time confirmation.
+Current revisions cannot be restored. The component accepts no credential prop.
+
+- [ ] **Step 4: Integrate revision state into Admin**
+
+Add one authenticated history load returning `config`,
+`currentRevisionId`, and `revisions`. Save sends `baseRevisionId` and a
+`crypto.randomUUID()` mutation ID. Retain the same pending mutation ID after a
+network/unknown failure; clear it when the editable Frames/Booth Key changes or
+after a definitive `400`, `401`, or `409`.
+
+On `409`, reload history and show:
+
+```text
+Configuration changed; review the latest version before saving.
+```
+
+Restore uses the same retained-ID rule per selected target, reloads history on
+success, updates Frames and `hasBoothKey`, and never fills the Booth Key input.
+Disable Save until authenticated history supplies the editor base.
+
+Add `"app/**/*.test.tsx"` to `tsconfig.test.json`.
+
+- [ ] **Step 5: Run component, type, and full repository verification**
+
+Run:
+
+```bash
+bun test 'app/[event]/admin/config-history-panel.test.tsx'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+```
+
+Expected: every command exits 0.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add 'app/[event]/admin' tsconfig.test.json
+git commit -m "feat: add admin config history and restore"
+```
diff --git a/docs/superpowers/plans/2026-07-24-release-0b-idempotent-ingest.md b/docs/superpowers/plans/2026-07-24-release-0b-idempotent-ingest.md
new file mode 100644
index 0000000..6510b8e
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-24-release-0b-idempotent-ingest.md
@@ -0,0 +1,557 @@
+# Release 0B Idempotent Photo Ingest Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Give every durable Outbox item a stable upload identity so repeated or concurrent attempts produce one public photo and one private moderation index record.
+
+**Architecture:** A browser-safe upload-contract module parses and emits strict stable identity headers. `EventStore` uses conditional create for deterministic photo keys, requires a private immutable index before acknowledging stable clients, and writes optional private receipts without requeuing an accepted photo. Booth Session passes the complete durable Outbox item to its upload adapter so identity survives reload and rollback-compatible old rows remain uploadable.
+
+**Tech Stack:** Bun, TypeScript, Next.js 15 App Router, React 19, Cloudflare Workers, R2, IndexedDB.
+
+## Global Constraints
+
+- Use Bun commands only.
+- This plan starts after Release 0A; reuse its `ObjectStore` conditional-write primitives and config revision types.
+- `EventStore` remains the sole owner of public and private object keys.
+- Only image bytes are written to public `PHOTOS`.
+- Indexes, receipts, capture metadata, credentials, and revisions remain in private `STATE`.
+- Stable uploads require both the deterministic photo and immutable index before acknowledgment.
+- Receipt failure is best-effort and never causes an acknowledged photo to retry.
+- Legacy clients without stable headers preserve the random-key acknowledgment behavior.
+- Accepted Photo Outbox items are removed only after storage acknowledgment.
+- Existing IndexedDB rows remain readable without destructive migration.
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+
+---
+
+## File structure
+
+- Create `app/upload-contract.ts` — stable identity/metadata types and strict header codec.
+- Create `app/upload-contract.test.ts` — legacy, malformed, and round-trip contracts.
+- Modify `app/event-store.ts` — conditional photo create, deterministic keys, private index/receipt.
+- Modify `app/event-store.test.ts` — lost acknowledgment, concurrency, partial private failure.
+- Refactor `app/api/upload/route.ts` — dependency-injected handler and additive response.
+- Create `app/api/upload/route.test.ts` — real HTTP contract over in-memory stores.
+- Modify `app/upload-auth.ts` — shared Booth-or-Admin authentication helper.
+- Modify `app/upload-auth.test.ts` — shared authentication behavior.
+- Modify `app/[event]/booth-session/outbox.ts` — additive metadata fields.
+- Modify `app/[event]/booth-session/session.ts` — upload complete Outbox items.
+- Modify `app/[event]/booth-session/session.test.ts` — identity persistence and old-row compatibility.
+- Create `app/[event]/booth-session/upload.ts` — pure Outbox-to-header adapter.
+- Create `app/[event]/booth-session/upload.test.ts` — stable header tests.
+- Modify `app/[event]/page.tsx` — upload item body/headers and capture source/Frame metadata.
+
+### Task 1: Define the stable upload header contract
+
+**Files:**
+- Create: `app/upload-contract.ts`
+- Create: `app/upload-contract.test.ts`
+
+**Interfaces:**
+- Produces: `CaptureMetadata`, `StableCaptureIdentity`, `StableUpload`, `UploadIntent`.
+- Produces: `parseUploadHeaders(headers)` and `stableUploadHeaders(input)`.
+- Consumed by: Tasks 2–4.
+
+- [ ] **Step 1: Write failing parser and round-trip tests**
+
+```ts
+import { describe, expect, test } from "bun:test";
+import {
+  InvalidUploadHeadersError,
+  parseUploadHeaders,
+  stableUploadHeaders,
+} from "./upload-contract";
+
+const headers = (values: Record<string, string>) => new Headers(values);
+
+describe("stable upload headers", () => {
+  test("all stable fields round-trip", () => {
+    const stable = {
+      captureId: "018f0000-0000-4000-8000-000000000001",
+      capturedAt: 1753315200000,
+      source: "framed" as const,
+      frameKey: "square",
+      configRevisionId: "018f0000-0000-7000-8000-000000000002",
+    };
+    expect(parseUploadHeaders(headers(stableUploadHeaders(stable)))).toEqual({
+      kind: "stable",
+      ...stable,
+    });
+  });
+
+  test("no new headers is the legacy contract", () => {
+    expect(parseUploadHeaders(headers({ "content-type": "image/jpeg" }))).toEqual({ kind: "legacy" });
+  });
+
+  test("partial identity and metadata without identity are rejected", () => {
+    expect(() => parseUploadHeaders(headers({ "x-capture-id": "018f0000-0000-4000-8000-000000000001" })))
+      .toThrow(InvalidUploadHeadersError);
+    expect(() => parseUploadHeaders(headers({ "x-capture-source": "framed" })))
+      .toThrow(InvalidUploadHeadersError);
+  });
+
+  test("rejects malformed UUID, timestamp, source, and bounded tokens", () => {
+    const base = {
+      "x-capture-id": "018f0000-0000-4000-8000-000000000001",
+      "x-captured-at": "1753315200000",
+    };
+    for (const invalid of [
+      { ...base, "x-capture-id": "../photo" },
+      { ...base, "x-captured-at": "1e12" },
+      { ...base, "x-capture-source": "video" },
+      { ...base, "x-frame-key": "../frame" },
+    ]) expect(() => parseUploadHeaders(headers(invalid))).toThrow();
+  });
+});
+```
+
+- [ ] **Step 2: Run the test and verify missing-module failure**
+
+Run: `bun test app/upload-contract.test.ts`
+
+Expected: FAIL because `upload-contract.ts` does not exist.
+
+- [ ] **Step 3: Implement strict parsing and emission**
+
+```ts
+export type CaptureSource = "framed" | "camera-fallback";
+export type CaptureMetadata = {
+  frameKey?: string;
+  capturedAt: number;
+  source: CaptureSource;
+  configRevisionId?: string;
+};
+export type StableCaptureIdentity = { captureId: string; capturedAt: number };
+export type StableUpload = StableCaptureIdentity & {
+  source?: CaptureSource;
+  frameKey?: string;
+  configRevisionId?: string;
+};
+export type UploadIntent = { kind: "legacy" } | ({ kind: "stable" } & StableUpload);
+
+export class InvalidUploadHeadersError extends Error {
+  constructor(
+    readonly code:
+      | "incomplete_capture_identity"
+      | "invalid_capture_id"
+      | "invalid_captured_at"
+      | "invalid_capture_source"
+      | "invalid_frame_key"
+      | "invalid_config_revision_id",
+    message: string
+  ) { super(message); }
+}
+```
+
+Use lowercase RFC-4122 UUID-v4 for `x-capture-id`, exactly 13 decimal digits
+for `x-captured-at`, exact source enum values, and 1–128 character
+`[A-Za-z0-9][A-Za-z0-9_-]*` tokens for Frame and revision IDs. Both identity
+headers absent means legacy. Exactly one, or metadata without identity, throws
+`InvalidUploadHeadersError`. Unknown headers are ignored.
+
+`stableUploadHeaders()` emits:
+
+```ts
+{
+  "x-capture-id": input.captureId,
+  "x-captured-at": String(input.capturedAt),
+  ...(input.source ? { "x-capture-source": input.source } : {}),
+  ...(input.frameKey ? { "x-frame-key": input.frameKey } : {}),
+  ...(input.configRevisionId ? { "x-config-revision-id": input.configRevisionId } : {}),
+}
+```
+
+- [ ] **Step 4: Run tests and type-check**
+
+Run: `bun test app/upload-contract.test.ts && bun run typecheck && bun run typecheck:tests`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/upload-contract.ts app/upload-contract.test.ts
+git commit -m "feat: define stable capture upload contract"
+```
+
+### Task 2: Make Event Store photo ingest idempotent and privately indexed
+
+**Files:**
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: Task 1 upload types and Release 0A conditional-write support.
+- Produces: `stablePhotoKey()`, `photoIndexKey()`, `photoReceiptKey()`.
+- Produces: `putPhoto(event, body, options)` returning `PutPhotoResult`.
+- Produces: `PhotoIndexWriteError`.
+
+- [ ] **Step 1: Write failing lost-acknowledgment and privacy tests**
+
+```ts
+test("stable ingest creates one immutable photo across retries", async () => {
+  const photos = new InMemoryObjectStore();
+  const state = new InMemoryObjectStore();
+  const store = new EventStore(photos, state, "https://photos.example", () => new Date("2026-07-24T00:00:00Z"));
+  const upload = {
+    captureId: "018f0000-0000-4000-8000-000000000001",
+    capturedAt: 1753315200000,
+    source: "framed" as const,
+    frameKey: "square",
+  };
+  const first = await store.putPhoto("launch", new TextEncoder().encode("first").buffer, { upload });
+  const retry = await store.putPhoto("launch", new TextEncoder().encode("replacement").buffer, { upload });
+  expect(first.key).toBe("launch/1753315200000-018f0000-0000-4000-8000-000000000001.jpg");
+  expect(retry).toMatchObject({ key: first.key, url: first.url, duplicate: true });
+  expect(await (await photos.get(first.key))!.text()).toBe("first");
+  expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+  expect(state.has(photoIndexKey("launch", first.key, upload.capturedAt))).toBe(true);
+  expect(state.has(photoReceiptKey("launch", first.key))).toBe(true);
+});
+
+test("concurrent stable attempts produce one public image", async () => {
+  const photos = new InMemoryObjectStore();
+  const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+  const upload = {
+    captureId: "018f0000-0000-4000-8000-000000000002",
+    capturedAt: 1753315200001,
+  };
+  const results = await Promise.all([
+    store.putPhoto("launch", new Uint8Array([1]).buffer, { upload }),
+    store.putPhoto("launch", new Uint8Array([2]).buffer, { upload }),
+  ]);
+  expect(results.filter((x) => x.duplicate)).toHaveLength(1);
+  expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+});
+```
+
+Add test-local failing `ObjectStore` wrappers to prove:
+
+- Stable index failure leaves one photo, throws `PhotoIndexWriteError`, and an
+  identical retry creates the missing index without another photo.
+- Receipt failure returns success with `receiptStored: false`.
+- Legacy uploads keep random keys and return success even when derived private
+  writes fail.
+- Same capture identity in two Events produces isolated keys.
+- Receipt/index JSON contains no credential or hash fields.
+
+- [ ] **Step 2: Run focused Event Store tests and confirm missing exports**
+
+Run: `bun test app/event-store.test.ts`
+
+Expected: FAIL because stable ingest helpers/options do not exist.
+
+- [ ] **Step 3: Implement deterministic keys and derived private writes**
+
+Add:
+
+```ts
+export const stablePhotoKey = (event: string, id: StableCaptureIdentity) =>
+  `${event}/${String(id.capturedAt).padStart(13, "0")}-${id.captureId}.jpg`;
+export const photoReceiptKey = (event: string, key: string) =>
+  `events/${event}/photo-metadata/${key.slice(event.length + 1)}.json`;
+export const photoIndexKey = (event: string, key: string, sortTime: number) =>
+  `events/${event}/photo-index/v1/${String(9_999_999_999_999 - sortTime).padStart(13, "0")}-${base64url(key)}.json`;
+
+export type PutPhotoResult = {
+  key: string;
+  url: string;
+  duplicate: boolean;
+  receiptStored: boolean;
+  indexStored: boolean;
+};
+export class PhotoIndexWriteError extends Error {
+  constructor(readonly photo: { key: string; url: string; duplicate: boolean }, options: { cause: unknown }) {
+    super("photo index write failed", options);
+  }
+}
+```
+
+Use the Release 0A conditional-create primitive so a stable photo is never
+overwritten. Capture one server time per call. For stable uploads:
+
+1. Conditionally create the deterministic `PHOTOS` key.
+2. Conditionally create the immutable `STATE` index.
+3. Throw `PhotoIndexWriteError` when the index is unavailable.
+4. Attempt the immutable receipt; return `receiptStored: false` on failure.
+
+For legacy uploads, retain the current random key. Attempt index/receipt
+best-effort and always acknowledge the successful photo write; a retryable
+failure would create a second legacy image.
+
+- [ ] **Step 4: Run Event Store tests and both type-checkers**
+
+Run: `bun test app/event-store.test.ts && bun run typecheck && bun run typecheck:tests`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/event-store.ts app/event-store.test.ts
+git commit -m "feat: make photo ingest idempotent and privately indexed"
+```
+
+### Task 3: Validate stable uploads at the HTTP boundary
+
+**Files:**
+- Modify: `app/upload-auth.ts`
+- Modify: `app/upload-auth.test.ts`
+- Modify: `app/api/upload/route.ts`
+- Create: `app/api/upload/route.test.ts`
+
+**Interfaces:**
+- Consumes: Tasks 1–2.
+- Produces: shared `boothOrAdminOk()` auth and a dependency-injected upload handler.
+- Produces: additive `{ url, key, duplicate }` upload response.
+
+- [ ] **Step 1: Add failing shared-auth and route contract tests**
+
+```ts
+test("boothOrAdminOk preserves the admin-required fail-closed rule", async () => {
+  const stored = await hashBoothKey("event-key-123");
+  expect(await boothOrAdminOk("admin", "admin", stored)).toBe("ok");
+  expect(await boothOrAdminOk("event-key-123", "admin", stored)).toBe("ok");
+  expect(await boothOrAdminOk("wrong", "admin", stored)).toBe("unauthorized");
+  expect(await boothOrAdminOk("event-key-123", undefined, stored)).toBe("disabled");
+});
+```
+
+Create route tests against a dependency-injected handler:
+
+```ts
+test("a stable retry returns the same key as a duplicate", async () => {
+  const photos = new InMemoryObjectStore();
+  const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+  const request = () => new NextRequest("https://app.test/api/upload?event=launch", {
+    method: "POST",
+    headers: {
+      "x-booth-key": "admin",
+      "content-type": "image/jpeg",
+      "x-capture-id": "018f0000-0000-4000-8000-000000000001",
+      "x-captured-at": "1753315200000",
+    },
+    body: new Uint8Array([0xff, 0xd8, 0xff, 0xe0]),
+  });
+  const first = await handleUpload(request(), { store, adminKey: "admin" });
+  const retry = await handleUpload(request(), { store, adminKey: "admin" });
+  expect(await first.json()).toMatchObject({ duplicate: false });
+  expect(await retry.json()).toMatchObject({ duplicate: true });
+  expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+});
+```
+
+Add cases for legacy response compatibility, partial headers `400` with zero
+writes, canonical alias `400`, `401`, `413`, `415`, index failure `503` plus
+`Retry-After: 1`, identical recovery retry, and receipt failure `200`.
+
+- [ ] **Step 2: Run auth and route tests and verify failures**
+
+Run: `bun test app/upload-auth.test.ts app/api/upload/route.test.ts`
+
+Expected: FAIL because shared auth and injected handler do not exist.
+
+- [ ] **Step 3: Implement shared auth and injected upload handling**
+
+```ts
+export async function boothOrAdminOk(
+  provided: string,
+  adminKey: string | undefined,
+  boothKeyHash?: string
+): Promise<"ok" | "unauthorized" | "disabled"> {
+  const admin = adminOk(provided, adminKey);
+  if (admin !== "unauthorized") return admin;
+  return boothKeyHash && provided && await boothKeyMatches(provided, boothKeyHash)
+    ? "ok"
+    : "unauthorized";
+}
+```
+
+Export a handler dependency:
+
+```ts
+export type UploadHandlerDeps = { store: EventStore; adminKey?: string };
+export async function handleUpload(req: NextRequest, deps: UploadHandlerDeps): Promise<NextResponse>;
+```
+
+After auth and declared-size validation, parse stable headers before buffering
+the body. Map `InvalidUploadHeadersError` to `400` with its code and no writes.
+Map `PhotoIndexWriteError` to `503`, `{ retryable: true }`, and
+`Retry-After: 1`. Success returns:
+
+```ts
+{ url: photo.url, key: photo.key, duplicate: photo.duplicate }
+```
+
+Keep `url` for old clients. Log only Event, complete photo key, and bounded
+error class; never log credential headers or arbitrary exception strings.
+
+The exported `POST` obtains Cloudflare context and delegates.
+
+- [ ] **Step 4: Run route tests and type-check**
+
+Run: `bun test app/upload-auth.test.ts app/api/upload/route.test.ts && bun run typecheck && bun run typecheck:tests`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/upload-auth.ts app/upload-auth.test.ts app/api/upload/route.ts app/api/upload/route.test.ts
+git commit -m "feat: validate and expose stable upload identity"
+```
+
+### Task 4: Upload the complete durable Outbox item
+
+**Files:**
+- Modify: `app/[event]/booth-session/outbox.ts`
+- Modify: `app/[event]/booth-session/session.ts`
+- Modify: `app/[event]/booth-session/session.test.ts`
+- Create: `app/[event]/booth-session/upload.ts`
+- Create: `app/[event]/booth-session/upload.test.ts`
+- Modify: `app/[event]/page.tsx`
+
+**Interfaces:**
+- Consumes: Task 1 `CaptureMetadata` and header emitter.
+- Produces: stable identity from capture through IndexedDB, reload, and upload.
+
+- [ ] **Step 1: Write failing Outbox identity and header tests**
+
+```ts
+test("enqueue persists one identity and metadata before upload", async () => {
+  const store = new MemoryOutboxStore();
+  const seen: OutboxItem[] = [];
+  const session = new BoothSession(
+    "launch",
+    store,
+    async (item) => { seen.push(item); return { url: "/photo", key: "launch/photo.jpg" }; },
+    () => {},
+    () => "018f0000-0000-4000-8000-000000000001",
+    () => 1753315200000
+  );
+  const item = await session.enqueueCapture(
+    async () => new Blob(["photo"], { type: "image/jpeg" }),
+    { metadata: { source: "framed", frameKey: "square" } }
+  );
+  expect(item).toMatchObject({
+    id: "018f0000-0000-4000-8000-000000000001",
+    createdAt: 1753315200000,
+    metadata: { capturedAt: 1753315200000, source: "framed", frameKey: "square" },
+  });
+  await session.process();
+  expect(seen[0]).toEqual(item);
+});
+
+test("old rows gain stable headers from id and createdAt", () => {
+  const item = {
+    id: "018f0000-0000-4000-8000-000000000001",
+    event: "launch",
+    blob: new Blob(["photo"]),
+    createdAt: 1753315200000,
+    attempts: 0,
+  };
+  expect(outboxUploadHeaders(item)).toEqual({
+    "x-capture-id": item.id,
+    "x-captured-at": "1753315200000",
+  });
+});
+
+test("an invalid historical ID falls back to the legacy upload contract", () => {
+  expect(outboxUploadHeaders({
+    id: "old-non-uuid-id",
+    event: "launch",
+    blob: new Blob(["photo"]),
+    createdAt: 1753315200000,
+    attempts: 0,
+  })).toEqual({});
+});
+```
+
+Update the existing ordered-failure test upload callbacks to accept
+`OutboxItem` and read `item.blob`. Add reload/retry assertions that the same
+item ID and headers are observed on every attempt.
+
+- [ ] **Step 2: Run Booth Session tests and verify type/interface failures**
+
+Run: `bun test 'app/[event]/booth-session/session.test.ts' 'app/[event]/booth-session/upload.test.ts'`
+
+Expected: FAIL because uploads still receive only `Blob`.
+
+- [ ] **Step 3: Extend the additive Outbox and Session contracts**
+
+```ts
+export type OutboxItem = {
+  id: string;
+  event: string;
+  blob: Blob;
+  createdAt: number;
+  attempts: number;
+  lastError?: string;
+  nextAttemptAt?: number;
+  metadata?: CaptureMetadata;
+  rehearsalId?: string;
+};
+export type UploadResult = { url: string; key?: string; duplicate?: boolean };
+export type Upload = (item: OutboxItem) => Promise<UploadResult>;
+export type EnqueueCaptureOptions = {
+  signal?: AbortSignal;
+  metadata: Omit<CaptureMetadata, "capturedAt">;
+  rehearsalId?: string;
+};
+```
+
+`enqueueCapture(capture, options)` creates the ID and monotonic time only after
+capture/composition succeeds, sets both `createdAt` and
+`metadata.capturedAt`, writes the item, and returns it. `drain()` passes the
+whole stored item. Old records use `metadata?.capturedAt ?? createdAt`.
+
+Do not bump IndexedDB version or delete/transform existing rows.
+
+- [ ] **Step 4: Add the pure header adapter and wire the Booth**
+
+```ts
+import { InvalidUploadHeadersError, stableUploadHeaders } from "../../upload-contract";
+import type { OutboxItem } from "./outbox";
+
+export function outboxUploadHeaders(item: OutboxItem): Record<string, string> {
+  try {
+    return stableUploadHeaders({
+      captureId: item.id,
+      capturedAt: item.metadata?.capturedAt ?? item.createdAt,
+      source: item.metadata?.source,
+      frameKey: item.metadata?.frameKey,
+      configRevisionId: item.metadata?.configRevisionId,
+    });
+  } catch (error) {
+    if (error instanceof InvalidUploadHeadersError) return {};
+    throw error;
+  }
+}
+```
+
+In the Booth page, `uploadOne(item)` sends `item.blob` and the adapter headers.
+Framed capture supplies `{ source: "framed", frameKey: mode }`; camera fallback
+supplies `{ source: "camera-fallback" }`. Read `key` and `duplicate`
+additively, tolerating a rolled-back server that returns only `url`.
+
+- [ ] **Step 5: Run Booth tests and the full Release 0 gate**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/session.test.ts' 'app/[event]/booth-session/upload.test.ts'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+```
+
+Expected: every command exits 0.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add 'app/[event]/booth-session' 'app/[event]/page.tsx'
+git commit -m "feat: upload stable identity from the durable outbox"
+```

From 36242dfb36c2edc3f687b768fececb824669bfe8 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:35:37 +0800
Subject: [PATCH 004/105] chore: ignore local worktrees

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index e73604a..0dba8bf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,4 +11,5 @@ next-env.d.ts
 .wrangler/
 scripts/.migrated.json
 .claude/
+.worktrees/
 EDMUNDS-STUFF.md

From d9bb06ef7287d9b256c3db340b13c28341203ff1 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:38:43 +0800
Subject: [PATCH 005/105] feat: define revisioned event experience schema

---
 app/event-config.test.ts |  75 ++++++++++++++++++++++++++
 app/event-config.ts      | 112 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 187 insertions(+)
 create mode 100644 app/event-config.test.ts
 create mode 100644 app/event-config.ts

diff --git a/app/event-config.test.ts b/app/event-config.test.ts
new file mode 100644
index 0000000..1ac31d3
--- /dev/null
+++ b/app/event-config.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import {
+  isRevisionId,
+  parseConfigRevision,
+  parseEventConfig,
+  projectPublicConfig,
+} from "./event-config";
+
+describe("event config schema", () => {
+  test("parses the complete additive experience", () => {
+    expect(parseEventConfig({
+      version: 1,
+      frames: ["square"],
+      boothKeyHash: "secret-hash",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    })).toEqual({
+      frames: ["square"],
+      boothKeyHash: "secret-hash",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+  });
+
+  test("rejects unsupported versions and malformed nested settings", () => {
+    expect(parseEventConfig({ version: 2, frames: [] })).toBeNull();
+    expect(parseEventConfig({ version: 1, frames: [], capture: { autoAcceptSeconds: -1 } })).toBeNull();
+    expect(parseEventConfig({ version: 1, frames: [], gallery: { accentColor: "red<script>" } })).toBeNull();
+  });
+
+  test("projects only public allowlisted fields", () => {
+    const projected = projectPublicConfig({
+      frames: ["square"],
+      boothKeyHash: "secret-hash",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      locales: ["en"],
+      defaultLocale: "en",
+    });
+    expect(projected).toEqual({
+      frames: ["square"],
+      hasBoothKey: true,
+      locales: ["en"],
+      defaultLocale: "en",
+    });
+    const json = JSON.stringify(projected);
+    expect(json).not.toContain("boothKeyHash");
+    expect(json).not.toContain("currentRevisionId");
+    expect(projectPublicConfig(null)).toEqual({ frames: null, hasBoothKey: false });
+  });
+
+  test("revision parsing rejects credentials inside experience", () => {
+    const base = {
+      version: 1,
+      id: "018f0000-0000-7000-8000-000000000001",
+      createdAt: "2026-07-24T00:00:00.000Z",
+      parentRevisionId: null,
+      reason: "baseline",
+    };
+    expect(parseConfigRevision({ ...base, config: { frames: ["square"] } })).not.toBeNull();
+    expect(parseConfigRevision({ ...base, config: { frames: ["square"], boothKeyHash: "leak" } })).toBeNull();
+  });
+
+  test("accepts UUID mutation/revision IDs only", () => {
+    expect(isRevisionId("018f0000-0000-7000-8000-000000000001")).toBe(true);
+    expect(isRevisionId("../config")).toBe(false);
+  });
+});
diff --git a/app/event-config.ts b/app/event-config.ts
new file mode 100644
index 0000000..12a19fa
--- /dev/null
+++ b/app/event-config.ts
@@ -0,0 +1,112 @@
+export const EVENT_CONFIG_VERSION = 1 as const;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+
+export type LocaleCode = string;
+
+export type EventExperience = {
+  frames: string[];
+  locales?: LocaleCode[];
+  defaultLocale?: LocaleCode;
+  timeZone?: string;
+  capture?: {
+    reviewEnabled?: boolean;
+    autoAcceptSeconds?: number;
+    countdownAudioDefault?: boolean;
+  };
+  gallery?: { title?: string; accentColor?: string };
+};
+
+export type EventConfig = EventExperience & {
+  boothKeyHash?: string;
+  currentRevisionId?: string;
+};
+
+export type ConfigRevision = {
+  version: 1;
+  id: string;
+  createdAt: string;
+  parentRevisionId: string | null;
+  reason: "baseline" | "save" | "restore" | "preset";
+  sourceRevisionId?: string;
+  sourcePresetId?: string;
+  config: EventExperience;
+};
+
+export type PublicEventConfig = Omit<EventExperience, "frames"> & {
+  frames: string[] | null;
+  hasBoothKey: boolean;
+};
+
+export const isRevisionId = (value: unknown): value is string =>
+  typeof value === "string" && UUID.test(value);
+
+function parseExperience(value: unknown): EventExperience | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (!Array.isArray(v.frames) || !v.frames.every((x) => typeof x === "string" && TOKEN.test(x))) return null;
+  if (v.locales !== undefined && (!Array.isArray(v.locales) || !v.locales.every((x) => typeof x === "string" && TOKEN.test(x)))) return null;
+  if (v.defaultLocale !== undefined && (typeof v.defaultLocale !== "string" || !TOKEN.test(v.defaultLocale))) return null;
+  if (v.timeZone !== undefined && (typeof v.timeZone !== "string" || v.timeZone.length > 128)) return null;
+
+  const capture = v.capture as Record<string, unknown> | undefined;
+  if (capture !== undefined && (!capture || typeof capture !== "object")) return null;
+  if (capture?.reviewEnabled !== undefined && typeof capture.reviewEnabled !== "boolean") return null;
+  if (capture?.countdownAudioDefault !== undefined && typeof capture.countdownAudioDefault !== "boolean") return null;
+  if (capture?.autoAcceptSeconds !== undefined && (typeof capture.autoAcceptSeconds !== "number" || !Number.isInteger(capture.autoAcceptSeconds) || capture.autoAcceptSeconds < 1 || capture.autoAcceptSeconds > 30)) return null;
+
+  const gallery = v.gallery as Record<string, unknown> | undefined;
+  if (gallery !== undefined && (!gallery || typeof gallery !== "object")) return null;
+  if (gallery?.title !== undefined && (typeof gallery.title !== "string" || gallery.title.length > 120)) return null;
+  if (gallery?.accentColor !== undefined && (typeof gallery.accentColor !== "string" || !HEX_COLOR.test(gallery.accentColor))) return null;
+
+  return {
+    frames: [...v.frames] as string[],
+    ...(v.locales ? { locales: [...v.locales] as string[] } : {}),
+    ...(typeof v.defaultLocale === "string" ? { defaultLocale: v.defaultLocale } : {}),
+    ...(typeof v.timeZone === "string" ? { timeZone: v.timeZone } : {}),
+    ...(capture ? { capture: { ...capture } as EventExperience["capture"] } : {}),
+    ...(gallery ? { gallery: { ...gallery } as EventExperience["gallery"] } : {}),
+  };
+}
+
+export function parseEventConfig(value: unknown): EventConfig | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.version !== undefined && v.version !== EVENT_CONFIG_VERSION) return null;
+  const experience = parseExperience({ ...v, frames: v.frames ?? [] });
+  if (!experience) return null;
+  if (v.boothKeyHash !== undefined && typeof v.boothKeyHash !== "string") return null;
+  if (v.currentRevisionId !== undefined && !isRevisionId(v.currentRevisionId)) return null;
+  return {
+    ...experience,
+    ...(typeof v.boothKeyHash === "string" ? { boothKeyHash: v.boothKeyHash } : {}),
+    ...(typeof v.currentRevisionId === "string" ? { currentRevisionId: v.currentRevisionId } : {}),
+  };
+}
+
+export function parseConfigRevision(value: unknown): ConfigRevision | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.version !== 1 || !isRevisionId(v.id) || typeof v.createdAt !== "string") return null;
+  if (v.parentRevisionId !== null && !isRevisionId(v.parentRevisionId)) return null;
+  if (!["baseline", "save", "restore", "preset"].includes(String(v.reason))) return null;
+  const config = parseExperience(v.config);
+  if (!config || (v.config as Record<string, unknown>).boothKeyHash !== undefined) return null;
+  return { ...v, config } as ConfigRevision;
+}
+
+export function projectPublicConfig(config: EventConfig | null): PublicEventConfig {
+  if (!config) return { frames: null, hasBoothKey: false };
+  return {
+    frames: [...config.frames],
+    hasBoothKey: Boolean(config.boothKeyHash),
+    ...(config.locales ? { locales: [...config.locales] } : {}),
+    ...(config.defaultLocale ? { defaultLocale: config.defaultLocale } : {}),
+    ...(config.timeZone ? { timeZone: config.timeZone } : {}),
+    ...(config.capture ? { capture: { ...config.capture } } : {}),
+    ...(config.gallery ? { gallery: { ...config.gallery } } : {}),
+  };
+}

From fd217d730f18b5f08416a31d79d48b51020f4e20 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:40:52 +0800
Subject: [PATCH 006/105] fix: harden config revision parsing

---
 app/event-config.test.ts | 30 ++++++++++++++++++++++++++++++
 app/event-config.ts      | 18 +++++++++++++++---
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/app/event-config.test.ts b/app/event-config.test.ts
index 1ac31d3..26bbcf6 100644
--- a/app/event-config.test.ts
+++ b/app/event-config.test.ts
@@ -68,6 +68,36 @@ describe("event config schema", () => {
     expect(parseConfigRevision({ ...base, config: { frames: ["square"], boothKeyHash: "leak" } })).toBeNull();
   });
 
+  test("revision parsing rejects top-level credentials", () => {
+    expect(parseConfigRevision({
+      version: 1,
+      id: "018f0000-0000-7000-8000-000000000001",
+      createdAt: "2026-07-24T00:00:00.000Z",
+      parentRevisionId: null,
+      reason: "baseline",
+      boothKeyHash: "leak",
+      config: { frames: ["square"] },
+    })).toBeNull();
+  });
+
+  test("revision parsing rejects invalid source IDs", () => {
+    const base = {
+      version: 1,
+      id: "018f0000-0000-7000-8000-000000000001",
+      createdAt: "2026-07-24T00:00:00.000Z",
+      parentRevisionId: null,
+      reason: "baseline",
+      config: { frames: ["square"] },
+    };
+    expect(parseConfigRevision({ ...base, sourceRevisionId: "../revision" })).toBeNull();
+    expect(parseConfigRevision({ ...base, sourcePresetId: "preset<script>" })).toBeNull();
+  });
+
+  test("rejects array capture and gallery settings", () => {
+    expect(parseEventConfig({ version: 1, frames: [], capture: [] })).toBeNull();
+    expect(parseEventConfig({ version: 1, frames: [], gallery: [] })).toBeNull();
+  });
+
   test("accepts UUID mutation/revision IDs only", () => {
     expect(isRevisionId("018f0000-0000-7000-8000-000000000001")).toBe(true);
     expect(isRevisionId("../config")).toBe(false);
diff --git a/app/event-config.ts b/app/event-config.ts
index 12a19fa..a2317c9 100644
--- a/app/event-config.ts
+++ b/app/event-config.ts
@@ -52,13 +52,13 @@ function parseExperience(value: unknown): EventExperience | null {
   if (v.timeZone !== undefined && (typeof v.timeZone !== "string" || v.timeZone.length > 128)) return null;
 
   const capture = v.capture as Record<string, unknown> | undefined;
-  if (capture !== undefined && (!capture || typeof capture !== "object")) return null;
+  if (capture !== undefined && (!capture || typeof capture !== "object" || Array.isArray(capture))) return null;
   if (capture?.reviewEnabled !== undefined && typeof capture.reviewEnabled !== "boolean") return null;
   if (capture?.countdownAudioDefault !== undefined && typeof capture.countdownAudioDefault !== "boolean") return null;
   if (capture?.autoAcceptSeconds !== undefined && (typeof capture.autoAcceptSeconds !== "number" || !Number.isInteger(capture.autoAcceptSeconds) || capture.autoAcceptSeconds < 1 || capture.autoAcceptSeconds > 30)) return null;
 
   const gallery = v.gallery as Record<string, unknown> | undefined;
-  if (gallery !== undefined && (!gallery || typeof gallery !== "object")) return null;
+  if (gallery !== undefined && (!gallery || typeof gallery !== "object" || Array.isArray(gallery))) return null;
   if (gallery?.title !== undefined && (typeof gallery.title !== "string" || gallery.title.length > 120)) return null;
   if (gallery?.accentColor !== undefined && (typeof gallery.accentColor !== "string" || !HEX_COLOR.test(gallery.accentColor))) return null;
 
@@ -93,9 +93,21 @@ export function parseConfigRevision(value: unknown): ConfigRevision | null {
   if (v.version !== 1 || !isRevisionId(v.id) || typeof v.createdAt !== "string") return null;
   if (v.parentRevisionId !== null && !isRevisionId(v.parentRevisionId)) return null;
   if (!["baseline", "save", "restore", "preset"].includes(String(v.reason))) return null;
+  if (v.boothKeyHash !== undefined) return null;
+  if (v.sourceRevisionId !== undefined && !isRevisionId(v.sourceRevisionId)) return null;
+  if (v.sourcePresetId !== undefined && (typeof v.sourcePresetId !== "string" || !TOKEN.test(v.sourcePresetId))) return null;
   const config = parseExperience(v.config);
   if (!config || (v.config as Record<string, unknown>).boothKeyHash !== undefined) return null;
-  return { ...v, config } as ConfigRevision;
+  return {
+    version: EVENT_CONFIG_VERSION,
+    id: v.id,
+    createdAt: v.createdAt,
+    parentRevisionId: v.parentRevisionId,
+    reason: v.reason as ConfigRevision["reason"],
+    ...(typeof v.sourceRevisionId === "string" ? { sourceRevisionId: v.sourceRevisionId } : {}),
+    ...(typeof v.sourcePresetId === "string" ? { sourcePresetId: v.sourcePresetId } : {}),
+    config,
+  };
 }
 
 export function projectPublicConfig(config: EventConfig | null): PublicEventConfig {

From 56cbad3579fa0e7615ced046a9d11404d234b31e Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:42:42 +0800
Subject: [PATCH 007/105] fix: allowlist nested event config fields

---
 app/event-config.test.ts | 39 +++++++++++++++++++++++++++++++++++++++
 app/event-config.ts      | 27 +++++++++++++++++++++++----
 2 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/app/event-config.test.ts b/app/event-config.test.ts
index 26bbcf6..97397dd 100644
--- a/app/event-config.test.ts
+++ b/app/event-config.test.ts
@@ -98,6 +98,45 @@ describe("event config schema", () => {
     expect(parseEventConfig({ version: 1, frames: [], gallery: [] })).toBeNull();
   });
 
+  test("omits unknown nested fields from parsed and public config", () => {
+    const nestedCapture = {
+      reviewEnabled: true,
+      boothKeyHash: "leak",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      unknownNestedField: "discard",
+    };
+    const nestedGallery = {
+      title: "Launch Night",
+      boothKeyHash: "leak",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      unknownNestedField: "discard",
+    };
+    const expectedExperience = {
+      frames: ["square"],
+      capture: { reviewEnabled: true },
+      gallery: { title: "Launch Night" },
+    };
+
+    expect(parseEventConfig({ version: 1, ...expectedExperience, capture: nestedCapture, gallery: nestedGallery }))
+      .toEqual(expectedExperience);
+    expect(parseConfigRevision({
+      version: 1,
+      id: "018f0000-0000-7000-8000-000000000001",
+      createdAt: "2026-07-24T00:00:00.000Z",
+      parentRevisionId: null,
+      reason: "baseline",
+      config: { ...expectedExperience, capture: nestedCapture, gallery: nestedGallery },
+    })?.config).toEqual(expectedExperience);
+    expect(projectPublicConfig({
+      ...expectedExperience,
+      capture: nestedCapture,
+      gallery: nestedGallery,
+    } as Parameters<typeof projectPublicConfig>[0])).toEqual({
+      ...expectedExperience,
+      hasBoothKey: false,
+    });
+  });
+
   test("accepts UUID mutation/revision IDs only", () => {
     expect(isRevisionId("018f0000-0000-7000-8000-000000000001")).toBe(true);
     expect(isRevisionId("../config")).toBe(false);
diff --git a/app/event-config.ts b/app/event-config.ts
index a2317c9..4e80049 100644
--- a/app/event-config.ts
+++ b/app/event-config.ts
@@ -62,13 +62,23 @@ function parseExperience(value: unknown): EventExperience | null {
   if (gallery?.title !== undefined && (typeof gallery.title !== "string" || gallery.title.length > 120)) return null;
   if (gallery?.accentColor !== undefined && (typeof gallery.accentColor !== "string" || !HEX_COLOR.test(gallery.accentColor))) return null;
 
+  const parsedCapture = capture && {
+    ...(typeof capture.reviewEnabled === "boolean" ? { reviewEnabled: capture.reviewEnabled } : {}),
+    ...(typeof capture.autoAcceptSeconds === "number" ? { autoAcceptSeconds: capture.autoAcceptSeconds } : {}),
+    ...(typeof capture.countdownAudioDefault === "boolean" ? { countdownAudioDefault: capture.countdownAudioDefault } : {}),
+  };
+  const parsedGallery = gallery && {
+    ...(typeof gallery.title === "string" ? { title: gallery.title } : {}),
+    ...(typeof gallery.accentColor === "string" ? { accentColor: gallery.accentColor } : {}),
+  };
+
   return {
     frames: [...v.frames] as string[],
     ...(v.locales ? { locales: [...v.locales] as string[] } : {}),
     ...(typeof v.defaultLocale === "string" ? { defaultLocale: v.defaultLocale } : {}),
     ...(typeof v.timeZone === "string" ? { timeZone: v.timeZone } : {}),
-    ...(capture ? { capture: { ...capture } as EventExperience["capture"] } : {}),
-    ...(gallery ? { gallery: { ...gallery } as EventExperience["gallery"] } : {}),
+    ...(parsedCapture ? { capture: parsedCapture } : {}),
+    ...(parsedGallery ? { gallery: parsedGallery } : {}),
   };
 }
 
@@ -112,13 +122,22 @@ export function parseConfigRevision(value: unknown): ConfigRevision | null {
 
 export function projectPublicConfig(config: EventConfig | null): PublicEventConfig {
   if (!config) return { frames: null, hasBoothKey: false };
+  const capture = config.capture && {
+    ...(config.capture.reviewEnabled !== undefined ? { reviewEnabled: config.capture.reviewEnabled } : {}),
+    ...(config.capture.autoAcceptSeconds !== undefined ? { autoAcceptSeconds: config.capture.autoAcceptSeconds } : {}),
+    ...(config.capture.countdownAudioDefault !== undefined ? { countdownAudioDefault: config.capture.countdownAudioDefault } : {}),
+  };
+  const gallery = config.gallery && {
+    ...(config.gallery.title !== undefined ? { title: config.gallery.title } : {}),
+    ...(config.gallery.accentColor !== undefined ? { accentColor: config.gallery.accentColor } : {}),
+  };
   return {
     frames: [...config.frames],
     hasBoothKey: Boolean(config.boothKeyHash),
     ...(config.locales ? { locales: [...config.locales] } : {}),
     ...(config.defaultLocale ? { defaultLocale: config.defaultLocale } : {}),
     ...(config.timeZone ? { timeZone: config.timeZone } : {}),
-    ...(config.capture ? { capture: { ...config.capture } } : {}),
-    ...(config.gallery ? { gallery: { ...config.gallery } } : {}),
+    ...(capture ? { capture } : {}),
+    ...(gallery ? { gallery } : {}),
   };
 }

From d234e433057d0b389d5128d47203809532e5757f Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 09:56:13 +0800
Subject: [PATCH 008/105] feat: append immutable event config revisions

---
 app/event-store.test.ts | 208 +++++++++++++++++++++++++
 app/event-store.ts      | 328 ++++++++++++++++++++++++++++++++++++----
 2 files changed, 506 insertions(+), 30 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index b880fab..c49f2b0 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -1,12 +1,43 @@
 import { describe, expect, test } from "bun:test";
 import {
   canonicalEvent,
+  ConfigConflictError,
+  ConfigMutationConflictError,
   EventStore,
   InMemoryObjectStore,
   eventConfigKey,
+  eventConfigRevisionKey,
   legacyEventConfigKey,
 } from "./event-store";
 
+class FailNextConfigHeadCasStore extends InMemoryObjectStore {
+  private failNextConfigHeadCas = true;
+
+  override async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    if (this.failNextConfigHeadCas && key === eventConfigKey("launch")) {
+      this.failNextConfigHeadCas = false;
+      return false;
+    }
+    return super.compareAndSwap(key, expectedEtag, value);
+  }
+}
+
+describe("ObjectStore", () => {
+  test("compareAndSwap rejects a stale etag", async () => {
+    const state = new InMemoryObjectStore();
+    expect(await state.compareAndSwap("head", null, "one")).toBe(true);
+    const first = await state.get("head");
+    expect(await state.compareAndSwap("head", "stale", "two")).toBe(false);
+    expect(await state.compareAndSwap("head", first!.etag, "two")).toBe(true);
+    expect(await first!.text()).toBe("one");
+    expect(await (await state.get("head"))!.text()).toBe("two");
+  });
+});
+
 describe("canonical event identity", () => {
   test("accepts canonical slugs and keeps the default event", () => {
     expect(canonicalEvent("launch-2026")).toBe("launch-2026");
@@ -59,6 +90,183 @@ describe("EventStore", () => {
     });
   });
 
+  test("first revision save appends baseline and preserves booth key", async () => {
+    const state = new InMemoryObjectStore({
+      [eventConfigKey("launch")]: JSON.stringify({ version: 1, frames: ["old"], boothKeyHash: "hash" }),
+    });
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example", () => new Date("2026-07-24T00:00:00Z"));
+    const result = await store.saveConfigRevision("launch", {
+      config: { frames: ["new"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-000000000002",
+    });
+    expect(result.config.boothKeyHash).toBe("hash");
+    expect(result.revision.parentRevisionId).not.toBeNull();
+    expect(result.idempotent).toBe(false);
+    expect((await store.readConfig("launch"))?.currentRevisionId).toBe(result.revision.id);
+    const baseline = await state.get(eventConfigRevisionKey("launch", result.revision.parentRevisionId!));
+    expect(await baseline?.json()).toMatchObject({
+      reason: "baseline",
+      config: { frames: ["old"] },
+    });
+    expect(await baseline!.text()).not.toContain("boothKeyHash");
+  });
+
+  test("stale save conflicts and an identical mutation retry is idempotent", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const input = {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-000000000003",
+    };
+    expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(false);
+    expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(true);
+    await expect(store.saveConfigRevision("launch", {
+      ...input,
+      mutationId: "018f0000-0000-7000-8000-000000000004",
+    })).rejects.toBeInstanceOf(ConfigConflictError);
+  });
+
+  test("only one concurrent save advances the head", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const results = await Promise.allSettled([
+      store.saveConfigRevision("launch", {
+        config: { frames: ["one"] },
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-7000-8000-000000000005",
+      }),
+      store.saveConfigRevision("launch", {
+        config: { frames: ["two"] },
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-7000-8000-000000000006",
+      }),
+    ]);
+
+    const fulfilled = results.filter((result) => result.status === "fulfilled");
+    const rejected = results.filter((result) => result.status === "rejected");
+    expect(fulfilled).toHaveLength(1);
+    expect(rejected).toHaveLength(1);
+    expect(rejected[0]).toMatchObject({ reason: expect.any(ConfigConflictError) });
+    const winner = fulfilled[0];
+    if (!winner || winner.status !== "fulfilled") throw new Error("expected a winning save");
+    expect((await store.readConfig("launch"))?.currentRevisionId).toBe(winner.value.revision.id);
+  });
+
+  test("an orphaned concurrent revision stays outside the later head chain", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const mutationIds = [
+      "018f0000-0000-7000-8000-000000000007",
+      "018f0000-0000-7000-8000-000000000008",
+    ] as const;
+    const results = await Promise.allSettled(mutationIds.map((mutationId, index) =>
+      store.saveConfigRevision("launch", {
+        config: { frames: [`concurrent-${index}`] },
+        baseRevisionId: null,
+        mutationId,
+      })
+    ));
+    const winner = results.find((result) => result.status === "fulfilled");
+    expect(winner?.status).toBe("fulfilled");
+    if (!winner || winner.status !== "fulfilled") throw new Error("expected a winning save");
+    const orphanId = mutationIds.find((id) => id !== winner.value.revision.id)!;
+    expect(state.has(eventConfigRevisionKey("launch", orphanId))).toBe(true);
+
+    const later = await store.saveConfigRevision("launch", {
+      config: { frames: ["later"] },
+      baseRevisionId: winner.value.revision.id,
+      mutationId: "018f0000-0000-7000-8000-000000000009",
+    });
+    expect(later.revision.parentRevisionId).toBe(winner.value.revision.id);
+    expect(later.revision.parentRevisionId).not.toBe(orphanId);
+  });
+
+  test("reusing a mutation ID with different config conflicts", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const mutationId = "018f0000-0000-7000-8000-00000000000a";
+    await store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId,
+    });
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: ["two"] },
+      baseRevisionId: null,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+  });
+
+  test("reusing a mutation ID with a different base revision conflicts", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const first = await store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-00000000000b",
+    });
+    const mutationId = "018f0000-0000-7000-8000-00000000000c";
+    await store.saveConfigRevision("launch", {
+      config: { frames: ["two"] },
+      baseRevisionId: first.revision.id,
+      mutationId,
+    });
+
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: ["two"] },
+      baseRevisionId: null,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+  });
+
+  test("a mutation key containing a revision with another ID conflicts", async () => {
+    const state = new InMemoryObjectStore();
+    const mutationId = "018f0000-0000-7000-8000-00000000000e";
+    state.set(eventConfigRevisionKey("launch", mutationId), JSON.stringify({
+      version: 1,
+      id: "018f0000-0000-7000-8000-00000000000f",
+      createdAt: "2026-07-24T00:00:00Z",
+      parentRevisionId: null,
+      reason: "save",
+      config: { frames: ["one"] },
+    }));
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+  });
+
+  test("an identical retry finishes a legacy save after the revision append succeeds", async () => {
+    const state = new FailNextConfigHeadCasStore({
+      [eventConfigKey("launch")]: JSON.stringify({
+        version: 1,
+        frames: ["old"],
+        boothKeyHash: "hash",
+      }),
+    });
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const input = {
+      config: { frames: ["new"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-00000000000d",
+    };
+
+    await expect(store.saveConfigRevision("launch", input)).rejects.toBeInstanceOf(ConfigConflictError);
+    expect(state.has(eventConfigRevisionKey("launch", input.mutationId))).toBe(true);
+    expect((await store.readConfig("launch"))?.currentRevisionId).toBeUndefined();
+
+    const recovered = await store.saveConfigRevision("launch", input);
+    expect(recovered.idempotent).toBe(true);
+    expect(recovered.config).toMatchObject({
+      frames: ["new"],
+      boothKeyHash: "hash",
+      currentRevisionId: input.mutationId,
+    });
+    expect(recovered.revision.parentRevisionId).not.toBeNull();
+  });
+
   test("returns an initial snapshot and efficient start-after delta", async () => {
     const photos = new InMemoryObjectStore();
     photos.set("launch/0000000001000-aaaa.jpg", "a", new Date("2026-01-01T00:00:01Z"));
diff --git a/app/event-store.ts b/app/event-store.ts
index adfbf45..4edf2e5 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -4,25 +4,29 @@ import type {
   R2Objects,
   R2PutOptions,
 } from "@cloudflare/workers-types";
+import {
+  EVENT_CONFIG_VERSION,
+  parseConfigRevision,
+  parseEventConfig,
+  type ConfigRevision,
+  type EventConfig,
+  type EventExperience,
+} from "./event-config";
 export { canonicalEvent, InvalidEventSlugError, slugifyEvent } from "./event-identity";
-
-export const EVENT_CONFIG_VERSION = 1 as const;
+export { EVENT_CONFIG_VERSION };
+export type { EventConfig } from "./event-config";
 export const HEALTH_CANARY_KEY = "_health/canary";
 const HEALTH_STATE_KEY = "health/statuspage.json";
 const LEGACY_HEALTH_STATE_KEY = "_health/state.json";
 const PAGE_SIZE = 1000;
 
-export type EventConfig = {
-  frames?: string[];
-  boothKeyHash?: string;
-};
-
 type StoredEventConfig = EventConfig & { version: typeof EVENT_CONFIG_VERSION };
 
 export type StoredObject = {
   key: string;
   size: number;
   uploaded: Date;
+  etag: string;
 };
 
 export interface StoredObjectBody extends StoredObject {
@@ -49,6 +53,12 @@ export interface ObjectStore {
   put(key: string, value: ArrayBuffer | ArrayBufferView | string, options?: R2PutOptions): Promise<void>;
   delete(key: string): Promise<void>;
   list(options?: ListOptions): Promise<ListResult>;
+  compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string,
+    options?: R2PutOptions
+  ): Promise<boolean>;
 }
 
 /** Production adapter. Keeping R2 behind this seam makes key and paging rules testable. */
@@ -63,6 +73,21 @@ export class R2ObjectStore implements ObjectStore {
     await this.bucket.put(key, value, options);
   }
 
+  async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string,
+    options?: R2PutOptions
+  ): Promise<boolean> {
+    const result = await this.bucket.put(key, value, {
+      ...options,
+      onlyIf: expectedEtag === null
+        ? { etagDoesNotMatch: "*" }
+        : { etagMatches: expectedEtag },
+    });
+    return result !== null;
+  }
+
   delete(key: string): Promise<void> {
     return this.bucket.delete(key);
   }
@@ -73,7 +98,7 @@ export class R2ObjectStore implements ObjectStore {
   }
 }
 
-type MemoryEntry = { bytes: Uint8Array; uploaded: Date };
+type MemoryEntry = { bytes: Uint8Array; uploaded: Date; etag: string };
 
 /** Deterministic, committed fake used by unit/contract tests and local tooling. */
 export class InMemoryObjectStore implements ObjectStore {
@@ -87,7 +112,7 @@ export class InMemoryObjectStore implements ObjectStore {
 
   set(key: string, value: string | Uint8Array, uploaded = new Date()): void {
     const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value.slice();
-    this.entries.set(key, { bytes, uploaded });
+    this.entries.set(key, { bytes, uploaded, etag: crypto.randomUUID() });
   }
 
   has(key: string): boolean {
@@ -102,6 +127,7 @@ export class InMemoryObjectStore implements ObjectStore {
       key,
       size: bytes.byteLength,
       uploaded: entry.uploaded,
+      etag: entry.etag,
       async arrayBuffer() {
         return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
       },
@@ -115,11 +141,26 @@ export class InMemoryObjectStore implements ObjectStore {
   }
 
   async put(_key: string, value: ArrayBuffer | ArrayBufferView | string): Promise<void> {
-    let bytes: Uint8Array;
-    if (typeof value === "string") bytes = new TextEncoder().encode(value);
-    else if (ArrayBuffer.isView(value)) bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice();
-    else bytes = new Uint8Array(value.slice(0));
-    this.entries.set(_key, { bytes, uploaded: new Date() });
+    this.entries.set(_key, {
+      bytes: memoryBytes(value),
+      uploaded: new Date(),
+      etag: crypto.randomUUID(),
+    });
+  }
+
+  async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    const current = this.entries.get(key);
+    if (expectedEtag === null ? current !== undefined : current?.etag !== expectedEtag) return false;
+    this.entries.set(key, {
+      bytes: memoryBytes(value),
+      uploaded: new Date(),
+      etag: crypto.randomUUID(),
+    });
+    return true;
   }
 
   async delete(key: string): Promise<void> {
@@ -136,7 +177,7 @@ export class InMemoryObjectStore implements ObjectStore {
     const selected = keys.slice(offset, offset + limit);
     const objects = selected.map((key) => {
       const entry = this.entries.get(key)!;
-      return { key, size: entry.bytes.byteLength, uploaded: entry.uploaded };
+      return { key, size: entry.bytes.byteLength, uploaded: entry.uploaded, etag: entry.etag };
     });
     const next = offset + selected.length;
     return { objects, truncated: next < keys.length, cursor: next < keys.length ? String(next) : undefined };
@@ -144,21 +185,13 @@ export class InMemoryObjectStore implements ObjectStore {
 }
 
 export const eventConfigKey = (event: string) => `events/${event}/config.json`;
+export const eventConfigRevisionPrefix = (event: string) =>
+  `events/${event}/config-revisions/`;
+export const eventConfigRevisionKey = (event: string, id: string) =>
+  `${eventConfigRevisionPrefix(event)}${id}.json`;
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
 
-function parseConfig(value: unknown): EventConfig | null {
-  if (!value || typeof value !== "object") return null;
-  const config = value as Record<string, unknown>;
-  if (config.version !== undefined && config.version !== EVENT_CONFIG_VERSION) return null;
-  if (config.frames !== undefined && (!Array.isArray(config.frames) || !config.frames.every((f) => typeof f === "string"))) return null;
-  if (config.boothKeyHash !== undefined && typeof config.boothKeyHash !== "string") return null;
-  return {
-    ...(config.frames !== undefined ? { frames: config.frames as string[] } : {}),
-    ...(typeof config.boothKeyHash === "string" ? { boothKeyHash: config.boothKeyHash } : {}),
-  };
-}
-
 function photoTimestamp(key: string): number {
   const filename = key.slice(key.lastIndexOf("/") + 1);
   return Number(filename.split("-")[0]) || 0;
@@ -170,6 +203,23 @@ function isPhotoKey(event: string, key: string): boolean {
 
 export type Photo = { key: string; url: string; uploadedAt: Date };
 export type PhotoFeed = { photos: Photo[]; cursor: string | null; unchanged: boolean; truncated: boolean };
+export type ConfigMutationResult = {
+  config: EventConfig;
+  revision: ConfigRevision;
+  idempotent: boolean;
+};
+
+export class ConfigConflictError extends Error {
+  constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
+    super("event configuration changed");
+  }
+}
+
+export class ConfigMutationConflictError extends Error {
+  constructor() {
+    super("mutation ID was already used for different configuration");
+  }
+}
 
 export class InvalidStoredEventConfigError extends Error {
   constructor(readonly event: string) {
@@ -183,7 +233,8 @@ export class EventStore {
   constructor(
     readonly photos: ObjectStore,
     readonly state: ObjectStore,
-    readonly publicBase: string
+    readonly publicBase: string,
+    private readonly now: () => Date = () => new Date()
   ) {}
 
   static fromEnv(env: Pick<CloudflareEnv, "PHOTOS" | "STATE" | "R2_PUBLIC_BASE">): EventStore {
@@ -205,7 +256,7 @@ export class EventStore {
         } catch {
           throw new InvalidStoredEventConfigError(event);
         }
-        const parsed = parseConfig(current);
+        const parsed = parseEventConfig(current);
         if (!parsed) throw new InvalidStoredEventConfigError(event);
         return parsed;
       }
@@ -215,7 +266,7 @@ export class EventStore {
     }
 
     // Compatibility migration: old configs remain readable after STATE is introduced.
-    const legacy = parseConfig(await this.readJson(this.photos, legacyEventConfigKey(event)));
+    const legacy = parseEventConfig(await this.readJson(this.photos, legacyEventConfigKey(event)));
     if (!legacy) return null;
     try {
       await this.writeConfig(event, legacy);
@@ -233,6 +284,84 @@ export class EventStore {
     });
   }
 
+  async saveConfigRevision(
+    event: string,
+    input: {
+      config: EventConfig;
+      baseRevisionId: string | null;
+      mutationId: string;
+    }
+  ): Promise<ConfigMutationResult> {
+    const requested = parseEventConfig({
+      version: EVENT_CONFIG_VERSION,
+      ...input.config,
+      currentRevisionId: undefined,
+    });
+    if (!requested) throw new TypeError("invalid event configuration");
+    const requestedExperience = configExperience(requested);
+    const head = await this.readConfigHead(event);
+    const existing = await this.readRevision(event, input.mutationId);
+
+    if (existing) {
+      await this.assertMatchingMutation(event, existing, requestedExperience, input.baseRevisionId, input.mutationId);
+      return this.finishExistingMutation(event, input, requested, head, existing);
+    }
+
+    const currentRevisionId = head.config?.currentRevisionId ?? null;
+    if (input.baseRevisionId !== currentRevisionId) {
+      throw new ConfigConflictError(input.baseRevisionId, currentRevisionId);
+    }
+
+    let parentRevisionId = currentRevisionId;
+    if (head.config && !head.config.currentRevisionId) {
+      const baseline: ConfigRevision = {
+        version: EVENT_CONFIG_VERSION,
+        id: crypto.randomUUID(),
+        createdAt: this.now().toISOString(),
+        parentRevisionId: null,
+        reason: "baseline",
+        config: configExperience(head.config),
+      };
+      const appended = await this.state.compareAndSwap(
+        eventConfigRevisionKey(event, baseline.id),
+        null,
+        JSON.stringify(baseline),
+        jsonWriteOptions()
+      );
+      if (!appended) throw new ConfigMutationConflictError();
+      parentRevisionId = baseline.id;
+    }
+
+    const revision: ConfigRevision = {
+      version: EVENT_CONFIG_VERSION,
+      id: input.mutationId,
+      createdAt: this.now().toISOString(),
+      parentRevisionId,
+      reason: "save",
+      config: requestedExperience,
+    };
+    const appended = await this.state.compareAndSwap(
+      eventConfigRevisionKey(event, revision.id),
+      null,
+      JSON.stringify(revision),
+      jsonWriteOptions()
+    );
+    if (!appended) {
+      const racedRevision = await this.readRevision(event, input.mutationId);
+      if (!racedRevision) throw new ConfigMutationConflictError();
+      await this.assertMatchingMutation(
+        event,
+        racedRevision,
+        requestedExperience,
+        input.baseRevisionId,
+        input.mutationId
+      );
+      return this.finishExistingMutation(event, input, requested, head, racedRevision);
+    }
+
+    return this.advanceConfigHead(event, input.baseRevisionId, requested, head, revision, false);
+  }
+
   photoKey(event: string, now = Date.now(), suffix = randomSuffix()): string {
     return `${event}/${String(now).padStart(13, "0")}-${suffix}.jpg`;
   }
@@ -315,6 +444,145 @@ export class EventStore {
       return null;
     }
   }
+
+  private async readConfigHead(event: string): Promise<{ config: EventConfig | null; etag: string | null }> {
+    const object = await this.state.get(eventConfigKey(event));
+    if (object) {
+      let value: unknown;
+      try {
+        value = await object.json<unknown>();
+      } catch {
+        throw new InvalidStoredEventConfigError(event);
+      }
+      const config = parseEventConfig(value);
+      if (!config) throw new InvalidStoredEventConfigError(event);
+      return { config, etag: object.etag };
+    }
+    const legacy = parseEventConfig(await this.readJson(this.photos, legacyEventConfigKey(event)));
+    return { config: legacy, etag: null };
+  }
+
+  private async readRevision(event: string, id: string): Promise<ConfigRevision | null> {
+    const object = await this.state.get(eventConfigRevisionKey(event, id));
+    if (!object) return null;
+    try {
+      return parseConfigRevision(await object.json<unknown>());
+    } catch {
+      return null;
+    }
+  }
+
+  private async assertMatchingMutation(
+    event: string,
+    revision: ConfigRevision,
+    requested: EventExperience,
+    baseRevisionId: string | null,
+    mutationId: string
+  ): Promise<void> {
+    if (
+      revision.id !== mutationId
+      || revision.reason !== "save"
+      || revision.sourceRevisionId !== undefined
+      || revision.sourcePresetId !== undefined
+      || !sameExperience(revision.config, requested)
+    ) {
+      throw new ConfigMutationConflictError();
+    }
+    if (revision.parentRevisionId === baseRevisionId) return;
+    if (baseRevisionId !== null || revision.parentRevisionId === null) {
+      throw new ConfigMutationConflictError();
+    }
+
+    // A first save over an unrevisioned config receives an internal baseline
+    // parent even though the caller's base remains null.
+    const parent = await this.readRevision(event, revision.parentRevisionId);
+    if (parent?.reason !== "baseline") throw new ConfigMutationConflictError();
+  }
+
+  private async finishExistingMutation(
+    event: string,
+    input: { config: EventConfig; baseRevisionId: string | null; mutationId: string },
+    requested: EventConfig,
+    head: { config: EventConfig | null; etag: string | null },
+    revision: ConfigRevision
+  ): Promise<ConfigMutationResult> {
+    if (head.config?.currentRevisionId === revision.id) {
+      return { config: head.config, revision, idempotent: true };
+    }
+
+    const currentRevisionId = head.config?.currentRevisionId ?? null;
+    let canAdvance = currentRevisionId === revision.parentRevisionId
+      && input.baseRevisionId === currentRevisionId;
+    if (
+      !canAdvance
+      && input.baseRevisionId === null
+      && currentRevisionId === null
+      && revision.parentRevisionId
+    ) {
+      const baseline = await this.readRevision(event, revision.parentRevisionId);
+      canAdvance = baseline?.reason === "baseline"
+        && sameExperience(baseline.config, configExperience(head.config ?? { frames: [] }));
+    }
+    if (!canAdvance) {
+      throw new ConfigConflictError(input.baseRevisionId, currentRevisionId);
+    }
+
+    return this.advanceConfigHead(event, input.baseRevisionId, requested, head, revision, true);
+  }
+
+  private async advanceConfigHead(
+    event: string,
+    baseRevisionId: string | null,
+    requested: EventConfig,
+    head: { config: EventConfig | null; etag: string | null },
+    revision: ConfigRevision,
+    idempotent: boolean
+  ): Promise<ConfigMutationResult> {
+    const config = mergedRevisionHead(requested, head.config, revision.id);
+    const advanced = await this.state.compareAndSwap(
+      eventConfigKey(event),
+      head.etag,
+      JSON.stringify({ version: EVENT_CONFIG_VERSION, ...config }),
+      jsonWriteOptions()
+    );
+    if (advanced) return { config, revision, idempotent };
+    const current = await this.readConfigHead(event);
+    if (current.config?.currentRevisionId === revision.id) {
+      return { config: current.config, revision, idempotent: true };
+    }
+    throw new ConfigConflictError(baseRevisionId, current.config?.currentRevisionId ?? null);
+  }
+}
+
+function memoryBytes(value: ArrayBuffer | ArrayBufferView | string): Uint8Array {
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice();
+  return new Uint8Array(value.slice(0));
+}
+
+function configExperience(config: EventConfig): EventExperience {
+  const { boothKeyHash: _boothKeyHash, currentRevisionId: _currentRevisionId, ...experience } = config;
+  return experience;
+}
+
+function sameExperience(left: EventExperience, right: EventExperience): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function mergedRevisionHead(requested: EventConfig, current: EventConfig | null, revisionId: string): EventConfig {
+  const config: EventConfig = {
+    ...configExperience(requested),
+    currentRevisionId: revisionId,
+  };
+  const boothKeyHash = requested.boothKeyHash ?? current?.boothKeyHash;
+  if (boothKeyHash !== undefined) config.boothKeyHash = boothKeyHash;
+  return config;
+}
+
+function jsonWriteOptions(): R2PutOptions {
+  return {
+    httpMetadata: { contentType: "application/json", cacheControl: "no-store" },
+  };
 }
 
 function randomSuffix(): string {

From 308787e90302b281fd4949463614fecb7d24b59d Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 10:04:35 +0800
Subject: [PATCH 009/105] fix: harden event config mutation saves

---
 app/event-store.test.ts | 192 +++++++++++++++++++++++++++++++++++++++-
 app/event-store.ts      | 126 +++++++++++++++++++++-----
 2 files changed, 296 insertions(+), 22 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index c49f2b0..68de527 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -26,6 +26,61 @@ class FailNextConfigHeadCasStore extends InMemoryObjectStore {
   }
 }
 
+class GateFirstConfigHeadWriteStore extends InMemoryObjectStore {
+  private gateOpen = false;
+  private gated = false;
+  private readonly blocked: Promise<void>;
+  private markBlocked!: () => void;
+  private readonly released: Promise<void>;
+  private releaseGate!: () => void;
+
+  constructor() {
+    super();
+    this.blocked = new Promise((resolve) => {
+      this.markBlocked = resolve;
+    });
+    this.released = new Promise((resolve) => {
+      this.releaseGate = resolve;
+    });
+  }
+
+  waitUntilBlocked(): Promise<void> {
+    return this.blocked;
+  }
+
+  release(): void {
+    this.gateOpen = true;
+    this.releaseGate();
+  }
+
+  override async put(
+    key: string,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<void> {
+    await this.gateConfigHeadWrite(key);
+    return super.put(key, value);
+  }
+
+  override async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    await this.gateConfigHeadWrite(key);
+    return super.compareAndSwap(key, expectedEtag, value);
+  }
+
+  private async gateConfigHeadWrite(key: string): Promise<void> {
+    if (this.gated || key !== eventConfigKey("launch")) return;
+    this.gated = true;
+    this.markBlocked();
+    if (!this.gateOpen) await this.released;
+  }
+}
+
+const eventConfigMutationKey = (event: string, mutationId: string) =>
+  `events/${event}/config-mutations/${mutationId}.json`;
+
 describe("ObjectStore", () => {
   test("compareAndSwap rejects a stale etag", async () => {
     const state = new InMemoryObjectStore();
@@ -90,6 +145,27 @@ describe("EventStore", () => {
     });
   });
 
+  test("lazy legacy migration cannot overwrite a concurrent revision save", async () => {
+    const photos = new InMemoryObjectStore({
+      [legacyEventConfigKey("launch")]: JSON.stringify({ frames: ["legacy"] }),
+    });
+    const state = new GateFirstConfigHeadWriteStore();
+    const store = new EventStore(photos, state, "https://photos.example");
+
+    const migrating = store.readConfig("launch");
+    await state.waitUntilBlocked();
+    const saved = await store.saveConfigRevision("launch", {
+      config: { frames: ["saved"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-000000000020",
+    });
+    state.release();
+
+    expect(await migrating).toEqual(saved.config);
+    expect(await store.readConfig("launch")).toEqual(saved.config);
+    expect((await store.readConfig("launch"))?.currentRevisionId).toBe(saved.revision.id);
+  });
+
   test("first revision save appends baseline and preserves booth key", async () => {
     const state = new InMemoryObjectStore({
       [eventConfigKey("launch")]: JSON.stringify({ version: 1, frames: ["old"], boothKeyHash: "hash" }),
@@ -120,6 +196,13 @@ describe("EventStore", () => {
       mutationId: "018f0000-0000-7000-8000-000000000003",
     };
     expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(false);
+    expect(await (await store.state.get(eventConfigMutationKey("launch", input.mutationId)))?.json<{
+      version: number;
+      boothKeyMutationFingerprint: null;
+    }>()).toEqual({
+      version: 1,
+      boothKeyMutationFingerprint: null,
+    });
     expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(true);
     await expect(store.saveConfigRevision("launch", {
       ...input,
@@ -197,6 +280,103 @@ describe("EventStore", () => {
     })).rejects.toBeInstanceOf(ConfigMutationConflictError);
   });
 
+  test("stores a credential-free mutation intent and rejects fingerprint reuse", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const mutationId = "018f0000-0000-7000-8000-000000000021";
+    const fingerprint = "a".repeat(64);
+    const input = {
+      config: { frames: ["one"], boothKeyHash: "replacement-hash" },
+      baseRevisionId: null,
+      mutationId,
+      boothKeyMutationFingerprint: fingerprint,
+    };
+
+    expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(false);
+    expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(true);
+    const intent = await state.get(eventConfigMutationKey("launch", mutationId));
+    expect(await intent?.json<{ version: number; boothKeyMutationFingerprint: string }>()).toEqual({
+      version: 1,
+      boothKeyMutationFingerprint: fingerprint,
+    });
+    expect(await intent!.text()).not.toContain("replacement-hash");
+    expect(await intent!.text()).not.toContain("boothKeyHash");
+
+    await expect(store.saveConfigRevision("launch", {
+      ...input,
+      boothKeyMutationFingerprint: "b".repeat(64),
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: input.config.frames },
+      baseRevisionId: input.baseRevisionId,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+  });
+
+  test("only one concurrent credential mutation intent wins", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const mutationId = "018f0000-0000-7000-8000-000000000022";
+    const results = await Promise.allSettled([
+      store.saveConfigRevision("launch", {
+        config: { frames: ["one"], boothKeyHash: "hash-one" },
+        baseRevisionId: null,
+        mutationId,
+        boothKeyMutationFingerprint: "a".repeat(64),
+      }),
+      store.saveConfigRevision("launch", {
+        config: { frames: ["one"], boothKeyHash: "hash-two" },
+        baseRevisionId: null,
+        mutationId,
+        boothKeyMutationFingerprint: "b".repeat(64),
+      }),
+    ]);
+
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    const rejected = results.filter((result) => result.status === "rejected");
+    expect(rejected).toHaveLength(1);
+    expect(rejected[0]).toMatchObject({ reason: expect.any(ConfigMutationConflictError) });
+  });
+
+  test("invalid mutation IDs and credential fingerprints write nothing", async () => {
+    const invalidInputs = [
+      {
+        config: { frames: ["one"] },
+        baseRevisionId: null,
+        mutationId: "not-a-revision-id",
+      },
+      {
+        config: { frames: ["one"], boothKeyHash: "hash" },
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-7000-8000-000000000023",
+      },
+      {
+        config: { frames: ["one"] },
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-7000-8000-000000000024",
+        boothKeyMutationFingerprint: "a".repeat(64),
+      },
+      {
+        config: { frames: ["one"], boothKeyHash: "hash" },
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-7000-8000-000000000025",
+        boothKeyMutationFingerprint: "A".repeat(64),
+      },
+      {
+        config: { frames: ["one"], boothKeyHash: "hash" },
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-7000-8000-000000000026",
+        boothKeyMutationFingerprint: "a".repeat(63),
+      },
+    ];
+
+    for (const input of invalidInputs) {
+      const state = new InMemoryObjectStore();
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      await expect(store.saveConfigRevision("launch", input)).rejects.toBeInstanceOf(TypeError);
+      expect((await state.list()).objects).toHaveLength(0);
+    }
+  });
+
   test("reusing a mutation ID with a different base revision conflicts", async () => {
     const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
     const first = await store.saveConfigRevision("launch", {
@@ -248,9 +428,10 @@ describe("EventStore", () => {
     });
     const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
     const input = {
-      config: { frames: ["new"] },
+      config: { frames: ["new"], boothKeyHash: "new-hash" },
       baseRevisionId: null,
       mutationId: "018f0000-0000-7000-8000-00000000000d",
+      boothKeyMutationFingerprint: "c".repeat(64),
     };
 
     await expect(store.saveConfigRevision("launch", input)).rejects.toBeInstanceOf(ConfigConflictError);
@@ -261,10 +442,17 @@ describe("EventStore", () => {
     expect(recovered.idempotent).toBe(true);
     expect(recovered.config).toMatchObject({
       frames: ["new"],
-      boothKeyHash: "hash",
+      boothKeyHash: "new-hash",
       currentRevisionId: input.mutationId,
     });
     expect(recovered.revision.parentRevisionId).not.toBeNull();
+    expect(await (await state.get(eventConfigMutationKey("launch", input.mutationId)))?.json<{
+      version: number;
+      boothKeyMutationFingerprint: string;
+    }>()).toEqual({
+      version: 1,
+      boothKeyMutationFingerprint: input.boothKeyMutationFingerprint,
+    });
   });
 
   test("returns an initial snapshot and efficient start-after delta", async () => {
diff --git a/app/event-store.ts b/app/event-store.ts
index 4edf2e5..758cf84 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -6,6 +6,7 @@ import type {
 } from "@cloudflare/workers-types";
 import {
   EVENT_CONFIG_VERSION,
+  isRevisionId,
   parseConfigRevision,
   parseEventConfig,
   type ConfigRevision,
@@ -19,8 +20,19 @@ export const HEALTH_CANARY_KEY = "_health/canary";
 const HEALTH_STATE_KEY = "health/statuspage.json";
 const LEGACY_HEALTH_STATE_KEY = "_health/state.json";
 const PAGE_SIZE = 1000;
+const BOOTH_KEY_MUTATION_FINGERPRINT = /^[0-9a-f]{64}$/;
 
 type StoredEventConfig = EventConfig & { version: typeof EVENT_CONFIG_VERSION };
+type ConfigSaveInput = {
+  config: EventConfig;
+  baseRevisionId: string | null;
+  mutationId: string;
+  boothKeyMutationFingerprint?: string;
+};
+type ConfigMutationIntent = {
+  version: typeof EVENT_CONFIG_VERSION;
+  boothKeyMutationFingerprint: string | null;
+};
 
 export type StoredObject = {
   key: string;
@@ -189,6 +201,8 @@ export const eventConfigRevisionPrefix = (event: string) =>
   `events/${event}/config-revisions/`;
 export const eventConfigRevisionKey = (event: string, id: string) =>
   `${eventConfigRevisionPrefix(event)}${id}.json`;
+const eventConfigMutationKey = (event: string, mutationId: string) =>
+  `events/${event}/config-mutations/${mutationId}.json`;
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
 
@@ -248,18 +262,8 @@ export class EventStore {
 
   async readConfig(event: string): Promise<EventConfig | null> {
     try {
-      const object = await this.state.get(eventConfigKey(event));
-      if (object) {
-        let current: unknown;
-        try {
-          current = await object.json<unknown>();
-        } catch {
-          throw new InvalidStoredEventConfigError(event);
-        }
-        const parsed = parseEventConfig(current);
-        if (!parsed) throw new InvalidStoredEventConfigError(event);
-        return parsed;
-      }
+      const current = await this.readPrivateConfig(event);
+      if (current) return current;
     } catch (error) {
       if (error instanceof InvalidStoredEventConfigError) throw error;
       // During rollout, STATE may not exist yet. Legacy reads keep events live.
@@ -269,8 +273,17 @@ export class EventStore {
     const legacy = parseEventConfig(await this.readJson(this.photos, legacyEventConfigKey(event)));
     if (!legacy) return null;
     try {
-      await this.writeConfig(event, legacy);
-    } catch {
+      const migrated = await this.state.compareAndSwap(
+        eventConfigKey(event),
+        null,
+        JSON.stringify({ version: EVENT_CONFIG_VERSION, ...legacy }),
+        jsonWriteOptions()
+      );
+      if (migrated) return legacy;
+      const current = await this.readPrivateConfig(event);
+      if (current) return current;
+    } catch (error) {
+      if (error instanceof InvalidStoredEventConfigError) throw error;
       // Returning the legacy value is safer than failing an event while the
       // operator creates/binds STATE. A later read retries the migration.
     }
@@ -286,12 +299,9 @@ export class EventStore {
 
   async saveConfigRevision(
     event: string,
-    input: {
-      config: EventConfig;
-      baseRevisionId: string | null;
-      mutationId: string;
-    }
+    input: ConfigSaveInput
   ): Promise<ConfigMutationResult> {
+    const boothKeyMutationFingerprint = validateConfigMutationInput(input);
     const requested = parseEventConfig({
       version: EVENT_CONFIG_VERSION,
       ...input.config,
@@ -300,6 +310,7 @@ export class EventStore {
     if (!requested) throw new TypeError("invalid event configuration");
     const requestedExperience = configExperience(requested);
     const head = await this.readConfigHead(event);
+    await this.ensureConfigMutationIntent(event, input.mutationId, boothKeyMutationFingerprint);
     const existing = await this.readRevision(event, input.mutationId);
 
     if (existing) {
@@ -445,6 +456,20 @@ export class EventStore {
     }
   }
 
+  private async readPrivateConfig(event: string): Promise<EventConfig | null> {
+    const object = await this.state.get(eventConfigKey(event));
+    if (!object) return null;
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredEventConfigError(event);
+    }
+    const config = parseEventConfig(value);
+    if (!config) throw new InvalidStoredEventConfigError(event);
+    return config;
+  }
+
   private async readConfigHead(event: string): Promise<{ config: EventConfig | null; etag: string | null }> {
     const object = await this.state.get(eventConfigKey(event));
     if (object) {
@@ -462,6 +487,37 @@ export class EventStore {
     return { config: legacy, etag: null };
   }
 
+  private async ensureConfigMutationIntent(
+    event: string,
+    mutationId: string,
+    boothKeyMutationFingerprint: string | null
+  ): Promise<void> {
+    const intent: ConfigMutationIntent = {
+      version: EVENT_CONFIG_VERSION,
+      boothKeyMutationFingerprint,
+    };
+    const key = eventConfigMutationKey(event, mutationId);
+    const created = await this.state.compareAndSwap(
+      key,
+      null,
+      JSON.stringify(intent),
+      jsonWriteOptions()
+    );
+    if (created) return;
+
+    const existing = await this.state.get(key);
+    if (!existing) throw new ConfigMutationConflictError();
+    let value: unknown;
+    try {
+      value = await existing.json<unknown>();
+    } catch {
+      throw new ConfigMutationConflictError();
+    }
+    if (!isConfigMutationIntent(value) || value.boothKeyMutationFingerprint !== boothKeyMutationFingerprint) {
+      throw new ConfigMutationConflictError();
+    }
+  }
+
   private async readRevision(event: string, id: string): Promise<ConfigRevision | null> {
     const object = await this.state.get(eventConfigRevisionKey(event, id));
     if (!object) return null;
@@ -501,7 +557,7 @@ export class EventStore {
 
   private async finishExistingMutation(
     event: string,
-    input: { config: EventConfig; baseRevisionId: string | null; mutationId: string },
+    input: ConfigSaveInput,
     requested: EventConfig,
     head: { config: EventConfig | null; etag: string | null },
     revision: ConfigRevision
@@ -554,6 +610,36 @@ export class EventStore {
   }
 }
 
+function validateConfigMutationInput(input: ConfigSaveInput): string | null {
+  if (!isRevisionId(input.mutationId)) throw new TypeError("mutationId must be a revision ID");
+  const hasBoothKeyHash = input.config.boothKeyHash !== undefined;
+  const hasFingerprint = input.boothKeyMutationFingerprint !== undefined;
+  if (hasBoothKeyHash !== hasFingerprint) {
+    throw new TypeError("boothKeyMutationFingerprint must be supplied exactly when boothKeyHash is supplied");
+  }
+  if (
+    input.boothKeyMutationFingerprint !== undefined
+    && !BOOTH_KEY_MUTATION_FINGERPRINT.test(input.boothKeyMutationFingerprint)
+  ) {
+    throw new TypeError("boothKeyMutationFingerprint must be 64 lowercase hexadecimal characters");
+  }
+  return input.boothKeyMutationFingerprint ?? null;
+}
+
+function isConfigMutationIntent(value: unknown): value is ConfigMutationIntent {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const intent = value as Record<string, unknown>;
+  return Object.keys(intent).length === 2
+    && intent.version === EVENT_CONFIG_VERSION
+    && (
+      intent.boothKeyMutationFingerprint === null
+      || (
+        typeof intent.boothKeyMutationFingerprint === "string"
+        && BOOTH_KEY_MUTATION_FINGERPRINT.test(intent.boothKeyMutationFingerprint)
+      )
+    );
+}
+
 function memoryBytes(value: ArrayBuffer | ArrayBufferView | string): Uint8Array {
   if (typeof value === "string") return new TextEncoder().encode(value);
   if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice();

From ccf9a24438407d611f802dd29f36ffe3692a9a62 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 10:10:59 +0800
Subject: [PATCH 010/105] fix: bind complete config mutation identity

---
 app/event-store.test.ts | 76 +++++++++++++++++++++++++++++++++++++++--
 app/event-store.ts      | 71 +++++++++++++++++++++++++++++++-------
 2 files changed, 131 insertions(+), 16 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 68de527..6b5e813 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -6,6 +6,7 @@ import {
   EventStore,
   InMemoryObjectStore,
   eventConfigKey,
+  eventConfigMutationKey,
   eventConfigRevisionKey,
   legacyEventConfigKey,
 } from "./event-store";
@@ -78,8 +79,16 @@ class GateFirstConfigHeadWriteStore extends InMemoryObjectStore {
   }
 }
 
-const eventConfigMutationKey = (event: string, mutationId: string) =>
-  `events/${event}/config-mutations/${mutationId}.json`;
+function stateWithUnfinishedMutation(mutationId: string): InMemoryObjectStore {
+  return new InMemoryObjectStore({
+    [eventConfigMutationKey("launch", mutationId)]: JSON.stringify({
+      version: 1,
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      boothKeyMutationFingerprint: null,
+    }),
+  });
+}
 
 describe("ObjectStore", () => {
   test("compareAndSwap rejects a stale etag", async () => {
@@ -198,9 +207,13 @@ describe("EventStore", () => {
     expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(false);
     expect(await (await store.state.get(eventConfigMutationKey("launch", input.mutationId)))?.json<{
       version: number;
+      config: { frames: string[] };
+      baseRevisionId: string | null;
       boothKeyMutationFingerprint: null;
     }>()).toEqual({
       version: 1,
+      config: { frames: ["one"] },
+      baseRevisionId: null,
       boothKeyMutationFingerprint: null,
     });
     expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(true);
@@ -295,8 +308,15 @@ describe("EventStore", () => {
     expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(false);
     expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(true);
     const intent = await state.get(eventConfigMutationKey("launch", mutationId));
-    expect(await intent?.json<{ version: number; boothKeyMutationFingerprint: string }>()).toEqual({
+    expect(await intent?.json<{
+      version: number;
+      config: { frames: string[] };
+      baseRevisionId: string | null;
+      boothKeyMutationFingerprint: string;
+    }>()).toEqual({
       version: 1,
+      config: { frames: ["one"] },
+      baseRevisionId: null,
       boothKeyMutationFingerprint: fingerprint,
     });
     expect(await intent!.text()).not.toContain("replacement-hash");
@@ -337,6 +357,52 @@ describe("EventStore", () => {
     expect(rejected[0]).toMatchObject({ reason: expect.any(ConfigMutationConflictError) });
   });
 
+  test("an unfinished mutation intent rejects a changed experience without writing a revision", async () => {
+    const mutationId = "018f0000-0000-7000-8000-000000000027";
+    const state = stateWithUnfinishedMutation(mutationId);
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: ["two"] },
+      baseRevisionId: null,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+    expect(state.has(eventConfigRevisionKey("launch", mutationId))).toBe(false);
+    expect(state.has(eventConfigKey("launch"))).toBe(false);
+  });
+
+  test("an unfinished mutation intent rejects a changed base without writing a revision", async () => {
+    const mutationId = "018f0000-0000-7000-8000-000000000028";
+    const state = stateWithUnfinishedMutation(mutationId);
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: "018f0000-0000-7000-8000-000000000099",
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+    expect(state.has(eventConfigRevisionKey("launch", mutationId))).toBe(false);
+    expect(state.has(eventConfigKey("launch"))).toBe(false);
+  });
+
+  test("an unfinished identical mutation intent proceeds to the revision and head", async () => {
+    const mutationId = "018f0000-0000-7000-8000-000000000029";
+    const state = stateWithUnfinishedMutation(mutationId);
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+
+    const recovered = await store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId,
+    });
+    expect(recovered).toMatchObject({
+      config: { frames: ["one"], currentRevisionId: mutationId },
+      revision: { id: mutationId, parentRevisionId: null },
+      idempotent: false,
+    });
+    expect(state.has(eventConfigRevisionKey("launch", mutationId))).toBe(true);
+  });
+
   test("invalid mutation IDs and credential fingerprints write nothing", async () => {
     const invalidInputs = [
       {
@@ -448,9 +514,13 @@ describe("EventStore", () => {
     expect(recovered.revision.parentRevisionId).not.toBeNull();
     expect(await (await state.get(eventConfigMutationKey("launch", input.mutationId)))?.json<{
       version: number;
+      config: { frames: string[] };
+      baseRevisionId: string | null;
       boothKeyMutationFingerprint: string;
     }>()).toEqual({
       version: 1,
+      config: { frames: ["new"] },
+      baseRevisionId: null,
       boothKeyMutationFingerprint: input.boothKeyMutationFingerprint,
     });
   });
diff --git a/app/event-store.ts b/app/event-store.ts
index 758cf84..a1c7ae9 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -31,6 +31,8 @@ type ConfigSaveInput = {
 };
 type ConfigMutationIntent = {
   version: typeof EVENT_CONFIG_VERSION;
+  config: EventExperience;
+  baseRevisionId: string | null;
   boothKeyMutationFingerprint: string | null;
 };
 
@@ -201,7 +203,7 @@ export const eventConfigRevisionPrefix = (event: string) =>
   `events/${event}/config-revisions/`;
 export const eventConfigRevisionKey = (event: string, id: string) =>
   `${eventConfigRevisionPrefix(event)}${id}.json`;
-const eventConfigMutationKey = (event: string, mutationId: string) =>
+export const eventConfigMutationKey = (event: string, mutationId: string) =>
   `events/${event}/config-mutations/${mutationId}.json`;
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
@@ -310,7 +312,13 @@ export class EventStore {
     if (!requested) throw new TypeError("invalid event configuration");
     const requestedExperience = configExperience(requested);
     const head = await this.readConfigHead(event);
-    await this.ensureConfigMutationIntent(event, input.mutationId, boothKeyMutationFingerprint);
+    await this.ensureConfigMutationIntent(
+      event,
+      input.mutationId,
+      requestedExperience,
+      input.baseRevisionId,
+      boothKeyMutationFingerprint
+    );
     const existing = await this.readRevision(event, input.mutationId);
 
     if (existing) {
@@ -490,10 +498,14 @@ export class EventStore {
   private async ensureConfigMutationIntent(
     event: string,
     mutationId: string,
+    config: EventExperience,
+    baseRevisionId: string | null,
     boothKeyMutationFingerprint: string | null
   ): Promise<void> {
     const intent: ConfigMutationIntent = {
       version: EVENT_CONFIG_VERSION,
+      config,
+      baseRevisionId,
       boothKeyMutationFingerprint,
     };
     const key = eventConfigMutationKey(event, mutationId);
@@ -513,7 +525,13 @@ export class EventStore {
     } catch {
       throw new ConfigMutationConflictError();
     }
-    if (!isConfigMutationIntent(value) || value.boothKeyMutationFingerprint !== boothKeyMutationFingerprint) {
+    const parsed = parseConfigMutationIntent(value);
+    if (
+      !parsed
+      || parsed.baseRevisionId !== baseRevisionId
+      || parsed.boothKeyMutationFingerprint !== boothKeyMutationFingerprint
+      || !sameExperience(parsed.config, config)
+    ) {
       throw new ConfigMutationConflictError();
     }
   }
@@ -626,18 +644,45 @@ function validateConfigMutationInput(input: ConfigSaveInput): string | null {
   return input.boothKeyMutationFingerprint ?? null;
 }
 
-function isConfigMutationIntent(value: unknown): value is ConfigMutationIntent {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+function parseConfigMutationIntent(value: unknown): ConfigMutationIntent | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const intent = value as Record<string, unknown>;
-  return Object.keys(intent).length === 2
-    && intent.version === EVENT_CONFIG_VERSION
-    && (
-      intent.boothKeyMutationFingerprint === null
-      || (
-        typeof intent.boothKeyMutationFingerprint === "string"
-        && BOOTH_KEY_MUTATION_FINGERPRINT.test(intent.boothKeyMutationFingerprint)
+  if (
+    Object.keys(intent).length !== 4
+    || intent.version !== EVENT_CONFIG_VERSION
+    || (
+      intent.baseRevisionId !== null
+      && !isRevisionId(intent.baseRevisionId)
+    )
+    || (
+      intent.boothKeyMutationFingerprint !== null
+      && (
+        typeof intent.boothKeyMutationFingerprint !== "string"
+        || !BOOTH_KEY_MUTATION_FINGERPRINT.test(intent.boothKeyMutationFingerprint)
       )
-    );
+    )
+    || !intent.config
+    || typeof intent.config !== "object"
+    || Array.isArray(intent.config)
+  ) {
+    return null;
+  }
+  const rawConfig = intent.config as Record<string, unknown>;
+  if (
+    "version" in rawConfig
+    || "boothKeyHash" in rawConfig
+    || "currentRevisionId" in rawConfig
+  ) {
+    return null;
+  }
+  const parsed = parseEventConfig({ version: EVENT_CONFIG_VERSION, ...rawConfig });
+  if (!parsed) return null;
+  return {
+    version: EVENT_CONFIG_VERSION,
+    config: configExperience(parsed),
+    baseRevisionId: intent.baseRevisionId as string | null,
+    boothKeyMutationFingerprint: intent.boothKeyMutationFingerprint as string | null,
+  };
 }
 
 function memoryBytes(value: ArrayBuffer | ArrayBufferView | string): Uint8Array {

From fd3bd3645625d2f3a1d8784c2e95d33fe4526f79 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 11:00:29 +0800
Subject: [PATCH 011/105] fix: validate config mutation base revisions

---
 app/event-store.test.ts | 26 ++++++++++++++++++++++++++
 app/event-store.ts      |  3 +++
 2 files changed, 29 insertions(+)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 6b5e813..3912fcf 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -433,6 +433,11 @@ describe("EventStore", () => {
         mutationId: "018f0000-0000-7000-8000-000000000026",
         boothKeyMutationFingerprint: "a".repeat(63),
       },
+      {
+        config: { frames: ["one"] },
+        baseRevisionId: "not-a-revision-id",
+        mutationId: "018f0000-0000-7000-8000-00000000002a",
+      },
     ];
 
     for (const input of invalidInputs) {
@@ -443,6 +448,27 @@ describe("EventStore", () => {
     }
   });
 
+  test("an invalid base does not poison a corrected retry of the same mutation", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const mutationId = "018f0000-0000-7000-8000-00000000002b";
+
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: "not-a-revision-id",
+      mutationId,
+    })).rejects.toBeInstanceOf(TypeError);
+    expect((await state.list()).objects).toHaveLength(0);
+
+    const saved = await store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId,
+    });
+    expect(saved.revision.id).toBe(mutationId);
+    expect(saved.config.currentRevisionId).toBe(mutationId);
+  });
+
   test("reusing a mutation ID with a different base revision conflicts", async () => {
     const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
     const first = await store.saveConfigRevision("launch", {
diff --git a/app/event-store.ts b/app/event-store.ts
index a1c7ae9..ff3db94 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -630,6 +630,9 @@ export class EventStore {
 
 function validateConfigMutationInput(input: ConfigSaveInput): string | null {
   if (!isRevisionId(input.mutationId)) throw new TypeError("mutationId must be a revision ID");
+  if (input.baseRevisionId !== null && !isRevisionId(input.baseRevisionId)) {
+    throw new TypeError("baseRevisionId must be a revision ID or null");
+  }
   const hasBoothKeyHash = input.config.boothKeyHash !== undefined;
   const hasFingerprint = input.boothKeyMutationFingerprint !== undefined;
   if (hasBoothKeyHash !== hasFingerprint) {

From cf645f2d4fa06cb8010ffaf2a763fbd49c579c03 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 11:12:12 +0800
Subject: [PATCH 012/105] feat: restore event config from revision history

---
 app/event-store.test.ts | 330 ++++++++++++++++++++++++++++++++++++++++
 app/event-store.ts      | 139 ++++++++++++++---
 2 files changed, 452 insertions(+), 17 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 3912fcf..4d7e9b0 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -3,8 +3,10 @@ import {
   canonicalEvent,
   ConfigConflictError,
   ConfigMutationConflictError,
+  ConfigRevisionNotFoundError,
   EventStore,
   InMemoryObjectStore,
+  InvalidStoredConfigRevisionError,
   eventConfigKey,
   eventConfigMutationKey,
   eventConfigRevisionKey,
@@ -551,6 +553,334 @@ describe("EventStore", () => {
     });
   });
 
+  test("history follows only the reachable head chain and restore appends", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const first = await store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-000000000010",
+    });
+    const second = await store.saveConfigRevision("launch", {
+      config: { frames: ["two"] },
+      baseRevisionId: first.revision.id,
+      mutationId: "018f0000-0000-7000-8000-000000000011",
+    });
+    state.set(eventConfigRevisionKey("launch", "018f0000-0000-7000-8000-000000000099"), JSON.stringify({
+      version: 1,
+      id: "018f0000-0000-7000-8000-000000000099",
+      createdAt: "2026-07-24T00:00:00Z",
+      parentRevisionId: null,
+      reason: "save",
+      config: { frames: ["orphan"] },
+    }));
+
+    expect((await store.readConfigHistory("launch")).revisions.map((revision) => revision.id)).toEqual([
+      second.revision.id,
+      first.revision.id,
+    ]);
+    const restored = await store.restoreConfigRevision("launch", {
+      revisionId: first.revision.id,
+      baseRevisionId: second.revision.id,
+      mutationId: "018f0000-0000-7000-8000-000000000012",
+    });
+    expect(restored.config.frames).toEqual(["one"]);
+    expect(restored.revision).toMatchObject({
+      reason: "restore",
+      sourceRevisionId: first.revision.id,
+      parentRevisionId: second.revision.id,
+    });
+    expect((await store.readConfigHistory("launch")).revisions.map((revision) => revision.id)).toEqual([
+      restored.revision.id,
+      second.revision.id,
+      first.revision.id,
+    ]);
+  });
+
+  test("restore rejects missing and unreachable source revisions", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const current = await store.saveConfigRevision("launch", {
+      config: { frames: ["current"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-000000000030",
+    });
+    const orphanId = "018f0000-0000-7000-8000-000000000031";
+    state.set(eventConfigRevisionKey("launch", orphanId), JSON.stringify({
+      version: 1,
+      id: orphanId,
+      createdAt: "2026-07-24T00:00:00Z",
+      parentRevisionId: null,
+      reason: "save",
+      config: { frames: ["orphan"] },
+    }));
+    const attempts = [
+      {
+        revisionId: "018f0000-0000-7000-8000-000000000098",
+        mutationId: "018f0000-0000-7000-8000-000000000032",
+      },
+      {
+        revisionId: orphanId,
+        mutationId: "018f0000-0000-7000-8000-000000000046",
+      },
+    ];
+
+    for (const attempt of attempts) {
+      await expect(store.restoreConfigRevision("launch", {
+        ...attempt,
+        baseRevisionId: current.revision.id,
+      })).rejects.toBeInstanceOf(ConfigRevisionNotFoundError);
+      expect(state.has(eventConfigMutationKey("launch", attempt.mutationId))).toBe(false);
+      expect(state.has(eventConfigRevisionKey("launch", attempt.mutationId))).toBe(false);
+    }
+  });
+
+  test("history rejects corrupt and unsupported reachable revisions", async () => {
+    const corruptId = "018f0000-0000-7000-8000-000000000033";
+    const futureId = "018f0000-0000-7000-8000-000000000034";
+    const invalidValues = [
+      [corruptId, "{not-json"],
+      [futureId, JSON.stringify({
+        version: 2,
+        id: futureId,
+        createdAt: "2026-07-24T00:00:00Z",
+        parentRevisionId: null,
+        reason: "save",
+        config: { frames: ["future"] },
+      })],
+    ] as const;
+
+    for (const [revisionId, value] of invalidValues) {
+      const state = new InMemoryObjectStore({
+        [eventConfigKey("launch")]: JSON.stringify({
+          version: 1,
+          frames: ["current"],
+          currentRevisionId: revisionId,
+        }),
+        [eventConfigRevisionKey("launch", revisionId)]: value,
+      });
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      await expect(store.readConfigHistory("launch")).rejects.toBeInstanceOf(InvalidStoredConfigRevisionError);
+    }
+  });
+
+  test("history rejects a missing reachable parent", async () => {
+    const headId = "018f0000-0000-7000-8000-000000000035";
+    const missingParentId = "018f0000-0000-7000-8000-000000000036";
+    const state = new InMemoryObjectStore({
+      [eventConfigKey("launch")]: JSON.stringify({
+        version: 1,
+        frames: ["head"],
+        currentRevisionId: headId,
+      }),
+      [eventConfigRevisionKey("launch", headId)]: JSON.stringify({
+        version: 1,
+        id: headId,
+        createdAt: "2026-07-24T00:00:00Z",
+        parentRevisionId: missingParentId,
+        reason: "save",
+        config: { frames: ["head"] },
+      }),
+    });
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+
+    await expect(store.readConfigHistory("launch")).rejects.toBeInstanceOf(InvalidStoredConfigRevisionError);
+  });
+
+  test("history rejects a cycle in the reachable chain", async () => {
+    const firstId = "018f0000-0000-7000-8000-000000000037";
+    const secondId = "018f0000-0000-7000-8000-000000000038";
+    const state = new InMemoryObjectStore({
+      [eventConfigKey("launch")]: JSON.stringify({
+        version: 1,
+        frames: ["first"],
+        currentRevisionId: firstId,
+      }),
+      [eventConfigRevisionKey("launch", firstId)]: JSON.stringify({
+        version: 1,
+        id: firstId,
+        createdAt: "2026-07-24T00:00:00Z",
+        parentRevisionId: secondId,
+        reason: "save",
+        config: { frames: ["first"] },
+      }),
+      [eventConfigRevisionKey("launch", secondId)]: JSON.stringify({
+        version: 1,
+        id: secondId,
+        createdAt: "2026-07-23T00:00:00Z",
+        parentRevisionId: firstId,
+        reason: "save",
+        config: { frames: ["second"] },
+      }),
+    });
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+
+    await expect(store.readConfigHistory("launch")).rejects.toBeInstanceOf(InvalidStoredConfigRevisionError);
+  });
+
+  test("stale restore conflicts without appending a revision", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const first = await store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-000000000039",
+    });
+    const second = await store.saveConfigRevision("launch", {
+      config: { frames: ["two"] },
+      baseRevisionId: first.revision.id,
+      mutationId: "018f0000-0000-7000-8000-00000000003a",
+    });
+    const mutationId = "018f0000-0000-7000-8000-00000000003b";
+
+    await expect(store.restoreConfigRevision("launch", {
+      revisionId: first.revision.id,
+      baseRevisionId: first.revision.id,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigConflictError);
+    expect((await store.readConfig("launch"))?.currentRevisionId).toBe(second.revision.id);
+    expect(state.has(eventConfigRevisionKey("launch", mutationId))).toBe(false);
+  });
+
+  test("an identical restore retry is idempotent", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const first = await store.saveConfigRevision("launch", {
+      config: { frames: ["one"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-00000000003c",
+    });
+    const second = await store.saveConfigRevision("launch", {
+      config: { frames: ["two"] },
+      baseRevisionId: first.revision.id,
+      mutationId: "018f0000-0000-7000-8000-00000000003d",
+    });
+    const input = {
+      revisionId: first.revision.id,
+      baseRevisionId: second.revision.id,
+      mutationId: "018f0000-0000-7000-8000-00000000003e",
+    };
+
+    expect((await store.restoreConfigRevision("launch", input)).idempotent).toBe(false);
+    const retried = await store.restoreConfigRevision("launch", input);
+    expect(retried.idempotent).toBe(true);
+    expect(retried.revision).toMatchObject({
+      id: input.mutationId,
+      reason: "restore",
+      sourceRevisionId: first.revision.id,
+    });
+  });
+
+  test("an identical retry finishes a restore after the revision append succeeds", async () => {
+    const firstId = "018f0000-0000-7000-8000-000000000047";
+    const secondId = "018f0000-0000-7000-8000-000000000048";
+    const state = new FailNextConfigHeadCasStore({
+      [eventConfigKey("launch")]: JSON.stringify({
+        version: 1,
+        frames: ["two"],
+        boothKeyHash: "current-hash",
+        currentRevisionId: secondId,
+      }),
+      [eventConfigRevisionKey("launch", firstId)]: JSON.stringify({
+        version: 1,
+        id: firstId,
+        createdAt: "2026-07-23T00:00:00Z",
+        parentRevisionId: null,
+        reason: "save",
+        config: { frames: ["one"] },
+      }),
+      [eventConfigRevisionKey("launch", secondId)]: JSON.stringify({
+        version: 1,
+        id: secondId,
+        createdAt: "2026-07-24T00:00:00Z",
+        parentRevisionId: firstId,
+        reason: "save",
+        config: { frames: ["two"] },
+      }),
+    });
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const input = {
+      revisionId: firstId,
+      baseRevisionId: secondId,
+      mutationId: "018f0000-0000-7000-8000-000000000049",
+    };
+
+    await expect(store.restoreConfigRevision("launch", input)).rejects.toBeInstanceOf(ConfigConflictError);
+    expect(state.has(eventConfigRevisionKey("launch", input.mutationId))).toBe(true);
+    expect((await store.readConfigHistory("launch")).revisions.map((revision) => revision.id)).toEqual([
+      secondId,
+      firstId,
+    ]);
+
+    const recovered = await store.restoreConfigRevision("launch", input);
+    expect(recovered).toMatchObject({
+      config: {
+        frames: ["one"],
+        boothKeyHash: "current-hash",
+        currentRevisionId: input.mutationId,
+      },
+      revision: {
+        id: input.mutationId,
+        parentRevisionId: secondId,
+        reason: "restore",
+        sourceRevisionId: firstId,
+      },
+      idempotent: true,
+    });
+  });
+
+  test("restore preserves the current Booth Key without writing it to immutable records", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const first = await store.saveConfigRevision("launch", {
+      config: { frames: ["one"], boothKeyHash: "old-hash" },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-7000-8000-00000000003f",
+      boothKeyMutationFingerprint: "d".repeat(64),
+    });
+    const second = await store.saveConfigRevision("launch", {
+      config: { frames: ["two"], boothKeyHash: "current-hash" },
+      baseRevisionId: first.revision.id,
+      mutationId: "018f0000-0000-7000-8000-000000000040",
+      boothKeyMutationFingerprint: "e".repeat(64),
+    });
+
+    const restored = await store.restoreConfigRevision("launch", {
+      revisionId: first.revision.id,
+      baseRevisionId: second.revision.id,
+      mutationId: "018f0000-0000-7000-8000-000000000041",
+    });
+    expect(restored.config.boothKeyHash).toBe("current-hash");
+    expect(await (await state.get(eventConfigRevisionKey("launch", restored.revision.id)))?.text()).not.toContain("current-hash");
+    expect(await (await state.get(eventConfigMutationKey("launch", restored.revision.id)))?.text()).not.toContain("current-hash");
+  });
+
+  test("invalid restore revision IDs write nothing", async () => {
+    const invalidInputs = [
+      {
+        revisionId: "not-a-revision-id",
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-7000-8000-000000000042",
+      },
+      {
+        revisionId: "018f0000-0000-7000-8000-000000000043",
+        baseRevisionId: "not-a-revision-id",
+        mutationId: "018f0000-0000-7000-8000-000000000044",
+      },
+      {
+        revisionId: "018f0000-0000-7000-8000-000000000045",
+        baseRevisionId: null,
+        mutationId: "not-a-revision-id",
+      },
+    ];
+
+    for (const input of invalidInputs) {
+      const state = new InMemoryObjectStore();
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      await expect(store.restoreConfigRevision("launch", input)).rejects.toBeInstanceOf(TypeError);
+      expect((await state.list()).objects).toHaveLength(0);
+    }
+  });
+
   test("returns an initial snapshot and efficient start-after delta", async () => {
     const photos = new InMemoryObjectStore();
     photos.set("launch/0000000001000-aaaa.jpg", "a", new Date("2026-01-01T00:00:01Z"));
diff --git a/app/event-store.ts b/app/event-store.ts
index ff3db94..f552618 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -29,12 +29,25 @@ type ConfigSaveInput = {
   mutationId: string;
   boothKeyMutationFingerprint?: string;
 };
+export type ConfigRestoreInput = {
+  revisionId: string;
+  baseRevisionId: string | null;
+  mutationId: string;
+};
 type ConfigMutationIntent = {
   version: typeof EVENT_CONFIG_VERSION;
   config: EventExperience;
   baseRevisionId: string | null;
   boothKeyMutationFingerprint: string | null;
 };
+type ConfigAppendInput = {
+  config: EventConfig;
+  baseRevisionId: string | null;
+  mutationId: string;
+  boothKeyMutationFingerprint: string | null;
+  reason: "save" | "restore";
+  sourceRevisionId?: string;
+};
 
 export type StoredObject = {
   key: string;
@@ -224,6 +237,11 @@ export type ConfigMutationResult = {
   revision: ConfigRevision;
   idempotent: boolean;
 };
+export type ConfigHistory = {
+  config: EventConfig | null;
+  currentRevisionId: string | null;
+  revisions: ConfigRevision[];
+};
 
 export class ConfigConflictError extends Error {
   constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
@@ -237,6 +255,18 @@ export class ConfigMutationConflictError extends Error {
   }
 }
 
+export class ConfigRevisionNotFoundError extends Error {
+  constructor(readonly event: string, readonly revisionId: string) {
+    super(`config revision ${revisionId} is not reachable for ${event}`);
+  }
+}
+
+export class InvalidStoredConfigRevisionError extends Error {
+  constructor(readonly event: string, readonly revisionId: string) {
+    super(`stored config revision ${revisionId} for ${event} is corrupt or uses an unsupported version`);
+  }
+}
+
 export class InvalidStoredEventConfigError extends Error {
   constructor(readonly event: string) {
     super(`stored config for ${event} is corrupt or uses an unsupported version`);
@@ -310,20 +340,72 @@ export class EventStore {
       currentRevisionId: undefined,
     });
     if (!requested) throw new TypeError("invalid event configuration");
-    const requestedExperience = configExperience(requested);
+    return this.appendConfigRevision(event, {
+      config: requested,
+      baseRevisionId: input.baseRevisionId,
+      mutationId: input.mutationId,
+      boothKeyMutationFingerprint,
+      reason: "save",
+    });
+  }
+
+  async readConfigHistory(event: string): Promise<ConfigHistory> {
+    const config = await this.readConfig(event);
+    const currentRevisionId = config?.currentRevisionId ?? null;
+    const revisions: ConfigRevision[] = [];
+    const visited = new Set<string>();
+    let revisionId = currentRevisionId;
+
+    while (revisionId !== null) {
+      if (visited.has(revisionId)) {
+        throw new InvalidStoredConfigRevisionError(event, revisionId);
+      }
+      visited.add(revisionId);
+      const revision = await this.readReachableRevision(event, revisionId);
+      revisions.push(revision);
+      revisionId = revision.parentRevisionId;
+    }
+
+    return { config, currentRevisionId, revisions };
+  }
+
+  async restoreConfigRevision(
+    event: string,
+    input: ConfigRestoreInput
+  ): Promise<ConfigMutationResult> {
+    validateConfigRestoreInput(input);
+    const history = await this.readConfigHistory(event);
+    const source = history.revisions.find((revision) => revision.id === input.revisionId);
+    if (!source) throw new ConfigRevisionNotFoundError(event, input.revisionId);
+
+    return this.appendConfigRevision(event, {
+      config: source.config,
+      baseRevisionId: input.baseRevisionId,
+      mutationId: input.mutationId,
+      boothKeyMutationFingerprint: null,
+      reason: "restore",
+      sourceRevisionId: source.id,
+    });
+  }
+
+  private async appendConfigRevision(
+    event: string,
+    input: ConfigAppendInput
+  ): Promise<ConfigMutationResult> {
+    const requestedExperience = configExperience(input.config);
     const head = await this.readConfigHead(event);
     await this.ensureConfigMutationIntent(
       event,
       input.mutationId,
       requestedExperience,
       input.baseRevisionId,
-      boothKeyMutationFingerprint
+      input.boothKeyMutationFingerprint
     );
     const existing = await this.readRevision(event, input.mutationId);
 
     if (existing) {
-      await this.assertMatchingMutation(event, existing, requestedExperience, input.baseRevisionId, input.mutationId);
-      return this.finishExistingMutation(event, input, requested, head, existing);
+      await this.assertMatchingMutation(event, existing, requestedExperience, input);
+      return this.finishExistingMutation(event, input, input.config, head, existing);
     }
 
     const currentRevisionId = head.config?.currentRevisionId ?? null;
@@ -356,7 +438,8 @@ export class EventStore {
       id: input.mutationId,
       createdAt: this.now().toISOString(),
       parentRevisionId,
-      reason: "save",
+      reason: input.reason,
+      ...(input.sourceRevisionId ? { sourceRevisionId: input.sourceRevisionId } : {}),
       config: requestedExperience,
     };
     const appended = await this.state.compareAndSwap(
@@ -372,13 +455,12 @@ export class EventStore {
         event,
         racedRevision,
         requestedExperience,
-        input.baseRevisionId,
-        input.mutationId
+        input
       );
-      return this.finishExistingMutation(event, input, requested, head, racedRevision);
+      return this.finishExistingMutation(event, input, input.config, head, racedRevision);
     }
 
-    return this.advanceConfigHead(event, input.baseRevisionId, requested, head, revision, false);
+    return this.advanceConfigHead(event, input.baseRevisionId, input.config, head, revision, false);
   }
 
   photoKey(event: string, now = Date.now(), suffix = randomSuffix()): string {
@@ -546,24 +628,39 @@ export class EventStore {
     }
   }
 
+  private async readReachableRevision(event: string, id: string): Promise<ConfigRevision> {
+    const object = await this.state.get(eventConfigRevisionKey(event, id));
+    if (!object) throw new InvalidStoredConfigRevisionError(event, id);
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredConfigRevisionError(event, id);
+    }
+    const revision = parseConfigRevision(value);
+    if (!revision || revision.id !== id) {
+      throw new InvalidStoredConfigRevisionError(event, id);
+    }
+    return revision;
+  }
+
   private async assertMatchingMutation(
     event: string,
     revision: ConfigRevision,
     requested: EventExperience,
-    baseRevisionId: string | null,
-    mutationId: string
+    input: ConfigAppendInput
   ): Promise<void> {
     if (
-      revision.id !== mutationId
-      || revision.reason !== "save"
-      || revision.sourceRevisionId !== undefined
+      revision.id !== input.mutationId
+      || revision.reason !== input.reason
+      || revision.sourceRevisionId !== input.sourceRevisionId
       || revision.sourcePresetId !== undefined
       || !sameExperience(revision.config, requested)
     ) {
       throw new ConfigMutationConflictError();
     }
-    if (revision.parentRevisionId === baseRevisionId) return;
-    if (baseRevisionId !== null || revision.parentRevisionId === null) {
+    if (revision.parentRevisionId === input.baseRevisionId) return;
+    if (input.baseRevisionId !== null || revision.parentRevisionId === null) {
       throw new ConfigMutationConflictError();
     }
 
@@ -575,7 +672,7 @@ export class EventStore {
 
   private async finishExistingMutation(
     event: string,
-    input: ConfigSaveInput,
+    input: Pick<ConfigAppendInput, "baseRevisionId">,
     requested: EventConfig,
     head: { config: EventConfig | null; etag: string | null },
     revision: ConfigRevision
@@ -647,6 +744,14 @@ function validateConfigMutationInput(input: ConfigSaveInput): string | null {
   return input.boothKeyMutationFingerprint ?? null;
 }
 
+function validateConfigRestoreInput(input: ConfigRestoreInput): void {
+  if (!isRevisionId(input.revisionId)) throw new TypeError("revisionId must be a revision ID");
+  if (!isRevisionId(input.mutationId)) throw new TypeError("mutationId must be a revision ID");
+  if (input.baseRevisionId !== null && !isRevisionId(input.baseRevisionId)) {
+    throw new TypeError("baseRevisionId must be a revision ID or null");
+  }
+}
+
 function parseConfigMutationIntent(value: unknown): ConfigMutationIntent | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const intent = value as Record<string, unknown>;

From ae306f6f7a94a90c06373f95b25318dcdc6fb1b7 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 11:18:09 +0800
Subject: [PATCH 013/105] fix: bind config mutation operation identity

---
 app/event-store.test.ts | 129 ++++++++++++++++++++++++++++++++++++++++
 app/event-store.ts      |  26 ++++++--
 2 files changed, 151 insertions(+), 4 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 4d7e9b0..0400730 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -29,6 +29,26 @@ class FailNextConfigHeadCasStore extends InMemoryObjectStore {
   }
 }
 
+class FailArmedRevisionAppendStore extends InMemoryObjectStore {
+  private revisionKeyToFail: string | null = null;
+
+  failNextRevisionAppend(key: string): void {
+    this.revisionKeyToFail = key;
+  }
+
+  override async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    if (key === this.revisionKeyToFail) {
+      this.revisionKeyToFail = null;
+      throw new Error("simulated revision append failure");
+    }
+    return super.compareAndSwap(key, expectedEtag, value);
+  }
+}
+
 class GateFirstConfigHeadWriteStore extends InMemoryObjectStore {
   private gateOpen = false;
   private gated = false;
@@ -88,10 +108,29 @@ function stateWithUnfinishedMutation(mutationId: string): InMemoryObjectStore {
       config: { frames: ["one"] },
       baseRevisionId: null,
       boothKeyMutationFingerprint: null,
+      reason: "save",
     }),
   });
 }
 
+async function saveSameContentHistory(
+  store: EventStore,
+  firstMutationId: string,
+  secondMutationId: string
+) {
+  const first = await store.saveConfigRevision("launch", {
+    config: { frames: ["same"] },
+    baseRevisionId: null,
+    mutationId: firstMutationId,
+  });
+  const second = await store.saveConfigRevision("launch", {
+    config: { frames: ["same"] },
+    baseRevisionId: first.revision.id,
+    mutationId: secondMutationId,
+  });
+  return { first, second };
+}
+
 describe("ObjectStore", () => {
   test("compareAndSwap rejects a stale etag", async () => {
     const state = new InMemoryObjectStore();
@@ -212,11 +251,13 @@ describe("EventStore", () => {
       config: { frames: string[] };
       baseRevisionId: string | null;
       boothKeyMutationFingerprint: null;
+      reason: "save";
     }>()).toEqual({
       version: 1,
       config: { frames: ["one"] },
       baseRevisionId: null,
       boothKeyMutationFingerprint: null,
+      reason: "save",
     });
     expect((await store.saveConfigRevision("launch", input)).idempotent).toBe(true);
     await expect(store.saveConfigRevision("launch", {
@@ -315,11 +356,13 @@ describe("EventStore", () => {
       config: { frames: string[] };
       baseRevisionId: string | null;
       boothKeyMutationFingerprint: string;
+      reason: "save";
     }>()).toEqual({
       version: 1,
       config: { frames: ["one"] },
       baseRevisionId: null,
       boothKeyMutationFingerprint: fingerprint,
+      reason: "save",
     });
     expect(await intent!.text()).not.toContain("replacement-hash");
     expect(await intent!.text()).not.toContain("boothKeyHash");
@@ -545,11 +588,13 @@ describe("EventStore", () => {
       config: { frames: string[] };
       baseRevisionId: string | null;
       boothKeyMutationFingerprint: string;
+      reason: "save";
     }>()).toEqual({
       version: 1,
       config: { frames: ["new"] },
       baseRevisionId: null,
       boothKeyMutationFingerprint: input.boothKeyMutationFingerprint,
+      reason: "save",
     });
   });
 
@@ -770,6 +815,90 @@ describe("EventStore", () => {
     });
   });
 
+  test("an unfinished restore intent rejects a different same-content source", async () => {
+    const state = new FailArmedRevisionAppendStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const { first, second } = await saveSameContentHistory(
+      store,
+      "018f0000-0000-7000-8000-00000000004a",
+      "018f0000-0000-7000-8000-00000000004b"
+    );
+    const mutationId = "018f0000-0000-7000-8000-00000000004c";
+    state.failNextRevisionAppend(eventConfigRevisionKey("launch", mutationId));
+
+    await expect(store.restoreConfigRevision("launch", {
+      revisionId: first.revision.id,
+      baseRevisionId: second.revision.id,
+      mutationId,
+    })).rejects.toThrow("simulated revision append failure");
+    await expect(store.restoreConfigRevision("launch", {
+      revisionId: second.revision.id,
+      baseRevisionId: second.revision.id,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+    expect(state.has(eventConfigRevisionKey("launch", mutationId))).toBe(false);
+  });
+
+  test("an unfinished restore mutation cannot be reused as an equivalent save", async () => {
+    const state = new FailArmedRevisionAppendStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const { first, second } = await saveSameContentHistory(
+      store,
+      "018f0000-0000-7000-8000-00000000004d",
+      "018f0000-0000-7000-8000-00000000004e"
+    );
+    const mutationId = "018f0000-0000-7000-8000-00000000004f";
+    state.failNextRevisionAppend(eventConfigRevisionKey("launch", mutationId));
+
+    await expect(store.restoreConfigRevision("launch", {
+      revisionId: first.revision.id,
+      baseRevisionId: second.revision.id,
+      mutationId,
+    })).rejects.toThrow("simulated revision append failure");
+    await expect(store.saveConfigRevision("launch", {
+      config: { frames: ["same"] },
+      baseRevisionId: second.revision.id,
+      mutationId,
+    })).rejects.toBeInstanceOf(ConfigMutationConflictError);
+    expect(state.has(eventConfigRevisionKey("launch", mutationId))).toBe(false);
+  });
+
+  test("an identical unfinished restore intent recovers idempotently", async () => {
+    const state = new FailArmedRevisionAppendStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const { first, second } = await saveSameContentHistory(
+      store,
+      "018f0000-0000-7000-8000-000000000050",
+      "018f0000-0000-7000-8000-000000000051"
+    );
+    const input = {
+      revisionId: first.revision.id,
+      baseRevisionId: second.revision.id,
+      mutationId: "018f0000-0000-7000-8000-000000000052",
+    };
+    state.failNextRevisionAppend(eventConfigRevisionKey("launch", input.mutationId));
+
+    await expect(store.restoreConfigRevision("launch", input)).rejects.toThrow("simulated revision append failure");
+    expect(await (await state.get(eventConfigMutationKey("launch", input.mutationId)))?.json<{
+      version: number;
+      config: { frames: string[] };
+      baseRevisionId: string;
+      boothKeyMutationFingerprint: null;
+      reason: "restore";
+      sourceRevisionId: string;
+    }>()).toEqual({
+      version: 1,
+      config: { frames: ["same"] },
+      baseRevisionId: second.revision.id,
+      boothKeyMutationFingerprint: null,
+      reason: "restore",
+      sourceRevisionId: first.revision.id,
+    });
+
+    expect((await store.restoreConfigRevision("launch", input)).idempotent).toBe(false);
+    expect((await store.restoreConfigRevision("launch", input)).idempotent).toBe(true);
+  });
+
   test("an identical retry finishes a restore after the revision append succeeds", async () => {
     const firstId = "018f0000-0000-7000-8000-000000000047";
     const secondId = "018f0000-0000-7000-8000-000000000048";
diff --git a/app/event-store.ts b/app/event-store.ts
index f552618..69e08ef 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -39,6 +39,8 @@ type ConfigMutationIntent = {
   config: EventExperience;
   baseRevisionId: string | null;
   boothKeyMutationFingerprint: string | null;
+  reason: "save" | "restore";
+  sourceRevisionId?: string;
 };
 type ConfigAppendInput = {
   config: EventConfig;
@@ -399,7 +401,9 @@ export class EventStore {
       input.mutationId,
       requestedExperience,
       input.baseRevisionId,
-      input.boothKeyMutationFingerprint
+      input.boothKeyMutationFingerprint,
+      input.reason,
+      input.sourceRevisionId
     );
     const existing = await this.readRevision(event, input.mutationId);
 
@@ -582,13 +586,17 @@ export class EventStore {
     mutationId: string,
     config: EventExperience,
     baseRevisionId: string | null,
-    boothKeyMutationFingerprint: string | null
+    boothKeyMutationFingerprint: string | null,
+    reason: "save" | "restore",
+    sourceRevisionId?: string
   ): Promise<void> {
     const intent: ConfigMutationIntent = {
       version: EVENT_CONFIG_VERSION,
       config,
       baseRevisionId,
       boothKeyMutationFingerprint,
+      reason,
+      ...(sourceRevisionId ? { sourceRevisionId } : {}),
     };
     const key = eventConfigMutationKey(event, mutationId);
     const created = await this.state.compareAndSwap(
@@ -612,6 +620,8 @@ export class EventStore {
       !parsed
       || parsed.baseRevisionId !== baseRevisionId
       || parsed.boothKeyMutationFingerprint !== boothKeyMutationFingerprint
+      || parsed.reason !== reason
+      || parsed.sourceRevisionId !== sourceRevisionId
       || !sameExperience(parsed.config, config)
     ) {
       throw new ConfigMutationConflictError();
@@ -755,9 +765,15 @@ function validateConfigRestoreInput(input: ConfigRestoreInput): void {
 function parseConfigMutationIntent(value: unknown): ConfigMutationIntent | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const intent = value as Record<string, unknown>;
+  const reason = intent.reason;
   if (
-    Object.keys(intent).length !== 4
-    || intent.version !== EVENT_CONFIG_VERSION
+    intent.version !== EVENT_CONFIG_VERSION
+    || (reason !== "save" && reason !== "restore")
+    || (
+      reason === "save"
+        ? Object.keys(intent).length !== 5 || "sourceRevisionId" in intent
+        : Object.keys(intent).length !== 6 || !isRevisionId(intent.sourceRevisionId)
+    )
     || (
       intent.baseRevisionId !== null
       && !isRevisionId(intent.baseRevisionId)
@@ -790,6 +806,8 @@ function parseConfigMutationIntent(value: unknown): ConfigMutationIntent | null
     config: configExperience(parsed),
     baseRevisionId: intent.baseRevisionId as string | null,
     boothKeyMutationFingerprint: intent.boothKeyMutationFingerprint as string | null,
+    reason,
+    ...(reason === "restore" ? { sourceRevisionId: intent.sourceRevisionId as string } : {}),
   };
 }
 

From 788073267b8ef0dcec31589dc227a6753aefa749 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 11:24:24 +0800
Subject: [PATCH 014/105] feat: expose config history and restore APIs

---
 app/api/config/handlers.test.ts           | 494 ++++++++++++++++++++++
 app/api/config/handlers.ts                | 265 ++++++++++++
 app/api/config/revisions/restore/route.ts |  17 +
 app/api/config/revisions/route.ts         |  17 +
 app/api/config/route.ts                   |  67 +--
 5 files changed, 808 insertions(+), 52 deletions(-)
 create mode 100644 app/api/config/handlers.test.ts
 create mode 100644 app/api/config/handlers.ts
 create mode 100644 app/api/config/revisions/restore/route.ts
 create mode 100644 app/api/config/revisions/route.ts

diff --git a/app/api/config/handlers.test.ts b/app/api/config/handlers.test.ts
new file mode 100644
index 0000000..b5d48d0
--- /dev/null
+++ b/app/api/config/handlers.test.ts
@@ -0,0 +1,494 @@
+import { createHash, createHmac } from "node:crypto";
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import {
+  EventStore,
+  InMemoryObjectStore,
+  eventConfigMutationKey,
+} from "@/app/event-store";
+import {
+  boothKeyMutationFingerprint,
+  getConfigRevisions,
+  getPublicConfig,
+  postConfigRestore,
+  putConfig,
+  type ConfigHandlerDeps,
+} from "./handlers";
+
+const ADMIN_KEY = "admin-secret";
+const FIRST_ID = "018f0000-0000-7000-8000-000000000020";
+const SECOND_ID = "018f0000-0000-7000-8000-000000000021";
+const THIRD_ID = "018f0000-0000-7000-8000-000000000022";
+const BOOTH_KEY = "123456789012";
+
+function deps(options: { adminKey?: string; hashBoothKey?: (key: string) => Promise<string> } = {}) {
+  const state = new InMemoryObjectStore();
+  const store = new EventStore(
+    new InMemoryObjectStore(),
+    state,
+    "https://photos.example",
+    () => new Date("2026-07-24T00:00:00.000Z")
+  );
+  return {
+    state,
+    deps: {
+      store,
+      adminKey: "adminKey" in options ? options.adminKey : ADMIN_KEY,
+      hashBoothKey: options.hashBoothKey ?? (async (key: string) => `hashed:${key}`),
+    } satisfies ConfigHandlerDeps,
+  };
+}
+
+const request = (
+  url: string,
+  init: ConstructorParameters<typeof NextRequest>[1] = {}
+) => new NextRequest(url, init);
+
+function adminRequest(
+  path: string,
+  method: "GET" | "PUT" | "POST",
+  body?: unknown,
+  key = ADMIN_KEY
+) {
+  return request(`https://app.test${path}`, {
+    method,
+    headers: {
+      "x-booth-key": key,
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+}
+
+function saveBody(overrides: Record<string, unknown> = {}) {
+  return {
+    frames: ["square"],
+    mutationId: FIRST_ID,
+    baseRevisionId: null,
+    ...overrides,
+  };
+}
+
+function credentialFields(value: unknown, path = "$"): string[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => credentialFields(item, `${path}[${index}]`));
+  }
+  if (!value || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([key, item]) => [
+    ...(["boothKey", "boothKeyHash", "boothKeyMutationFingerprint"].includes(key)
+      ? [`${path}.${key}`]
+      : []),
+    ...credentialFields(item, `${path}.${key}`),
+  ]);
+}
+
+describe("boothKeyMutationFingerprint", () => {
+  test("is a stable lowercase HMAC-SHA256 keyed by the Admin Key", async () => {
+    const expected = createHmac("sha256", ADMIN_KEY).update(BOOTH_KEY).digest("hex");
+    const first = await boothKeyMutationFingerprint(BOOTH_KEY, ADMIN_KEY);
+    const retry = await boothKeyMutationFingerprint(BOOTH_KEY, ADMIN_KEY);
+
+    expect(first).toBe(expected);
+    expect(retry).toBe(first);
+    expect(first).toMatch(/^[0-9a-f]{64}$/);
+    expect(first).not.toBe(createHash("sha256").update(BOOTH_KEY).digest("hex"));
+  });
+
+  test("changes for a different plaintext or Admin Key", async () => {
+    const original = await boothKeyMutationFingerprint(BOOTH_KEY, ADMIN_KEY);
+
+    expect(await boothKeyMutationFingerprint(`${BOOTH_KEY}x`, ADMIN_KEY)).not.toBe(original);
+    expect(await boothKeyMutationFingerprint(BOOTH_KEY, "different-admin")).not.toBe(original);
+  });
+});
+
+describe("config handlers", () => {
+  test("public config is explicitly redacted", async () => {
+    const d = deps();
+    await d.deps.store.writeConfig("launch", {
+      frames: ["square"],
+      boothKeyHash: "private-hash",
+    });
+
+    const response = await getPublicConfig(
+      request("https://app.test/api/config?event=launch"),
+      d.deps
+    );
+    const json = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(json).toEqual({ frames: ["square"], hasBoothKey: true });
+    expect(credentialFields(json)).toEqual([]);
+    expect(JSON.stringify(json)).not.toContain("private-hash");
+  });
+
+  test("public config preserves the unsaved compatibility projection", async () => {
+    const d = deps();
+    const response = await getPublicConfig(
+      request("https://app.test/api/config?event=launch"),
+      d.deps
+    );
+
+    expect(await response.json()).toEqual({ frames: null, hasBoothKey: false });
+  });
+
+  test("save requires canonical Event, Admin Key, mutation, and base", async () => {
+    const d = deps();
+    const response = await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({ boothKey: BOOTH_KEY })
+      ),
+      d.deps
+    );
+    const json = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(json).toEqual({
+      frames: ["square"],
+      hasBoothKey: true,
+      currentRevisionId: FIRST_ID,
+      idempotent: false,
+    });
+    expect(credentialFields(json)).toEqual([]);
+    expect(JSON.stringify(json)).not.toContain(BOOTH_KEY);
+  });
+
+  test("save stores an opaque fingerprint privately with the independently hashed key", async () => {
+    const d = deps({ hashBoothKey: async () => "salted-pbkdf2-hash" });
+    await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({ boothKey: BOOTH_KEY })
+      ),
+      d.deps
+    );
+
+    expect((await d.deps.store.readConfig("launch"))?.boothKeyHash).toBe("salted-pbkdf2-hash");
+    const intent = await d.state.get(eventConfigMutationKey("launch", FIRST_ID));
+    const text = await intent?.text();
+    const json = JSON.parse(text ?? "{}") as Record<string, unknown>;
+    expect(json.boothKeyMutationFingerprint).toBe(
+      await boothKeyMutationFingerprint(BOOTH_KEY, ADMIN_KEY)
+    );
+    expect(text).not.toContain(BOOTH_KEY);
+    expect(text).not.toContain("salted-pbkdf2-hash");
+  });
+
+  test("same plaintext mutation retries despite fresh salted hashes", async () => {
+    let hashes = 0;
+    const d = deps({ hashBoothKey: async () => `salted-hash-${++hashes}` });
+    const req = () => adminRequest(
+      "/api/config?event=launch",
+      "PUT",
+      saveBody({ boothKey: BOOTH_KEY })
+    );
+
+    expect((await putConfig(req(), d.deps)).status).toBe(200);
+    const response = await putConfig(req(), d.deps);
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toMatchObject({ idempotent: true });
+    expect(hashes).toBe(2);
+    expect((await d.deps.store.readConfig("launch"))?.boothKeyHash).toBe("salted-hash-1");
+  });
+
+  test("different Booth key plaintext under one mutation conflicts", async () => {
+    const d = deps();
+    expect((await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody({ boothKey: BOOTH_KEY })),
+      d.deps
+    )).status).toBe(200);
+
+    const response = await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({ boothKey: "different-key-123" })
+      ),
+      d.deps
+    );
+
+    expect(response.status).toBe(409);
+  });
+
+  test("save rejects unavailable and incorrect Admin Keys", async () => {
+    const disabled = deps({ adminKey: undefined });
+    const unauthorized = deps();
+
+    expect((await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody()),
+      disabled.deps
+    )).status).toBe(503);
+    expect((await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody(), "wrong-key"),
+      unauthorized.deps
+    )).status).toBe(401);
+  });
+
+  test("save rejects malformed bodies, unknown Frames, and invalid Booth keys", async () => {
+    const invalidBodies = [
+      null,
+      {},
+      saveBody({ frames: "square" }),
+      saveBody({ frames: ["not-a-frame"] }),
+      saveBody({ boothKey: "too-short" }),
+      saveBody({ boothKey: "x".repeat(129) }),
+      saveBody({ mutationId: "not-a-revision" }),
+      { frames: ["square"], mutationId: FIRST_ID },
+      saveBody({ baseRevisionId: "not-a-revision" }),
+    ];
+
+    for (const body of invalidBodies) {
+      const d = deps();
+      const response = await putConfig(
+        adminRequest("/api/config?event=launch", "PUT", body),
+        d.deps
+      );
+      expect(response.status).toBe(400);
+    }
+
+    const d = deps();
+    const malformed = await putConfig(
+      request("https://app.test/api/config?event=launch", {
+        method: "PUT",
+        headers: {
+          "x-booth-key": ADMIN_KEY,
+          "content-type": "application/json",
+        },
+        body: "{",
+      }),
+      d.deps
+    );
+    expect(malformed.status).toBe(400);
+  });
+
+  test("save maps stale bases and mutation reuse to conflict", async () => {
+    const d = deps();
+    expect((await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody()),
+      d.deps
+    )).status).toBe(200);
+
+    expect((await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({ mutationId: SECOND_ID, baseRevisionId: null })
+      ),
+      d.deps
+    )).status).toBe(409);
+    expect((await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({ frames: ["birthday"] })
+      ),
+      d.deps
+    )).status).toBe(409);
+  });
+
+  test("all config handlers reject Event aliases rather than slugging them", async () => {
+    const d = deps();
+    const responses = await Promise.all([
+      getPublicConfig(request("https://app.test/api/config?event=Launch%20Party"), d.deps),
+      putConfig(
+        adminRequest("/api/config?event=Launch%20Party", "PUT", saveBody()),
+        d.deps
+      ),
+      getConfigRevisions(
+        adminRequest("/api/config/revisions?event=Launch%20Party", "GET"),
+        d.deps
+      ),
+      postConfigRestore(
+        adminRequest("/api/config/revisions/restore?event=Launch%20Party", "POST", {
+          revisionId: FIRST_ID,
+          mutationId: SECOND_ID,
+          baseRevisionId: FIRST_ID,
+        }),
+        d.deps
+      ),
+    ]);
+
+    expect(responses.map((response) => response.status)).toEqual([400, 400, 400, 400]);
+  });
+
+  test("history is Admin-only and returns reachable redacted revisions", async () => {
+    const d = deps();
+    await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({ boothKey: BOOTH_KEY })
+      ),
+      d.deps
+    );
+    await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({
+          frames: ["birthday"],
+          mutationId: SECOND_ID,
+          baseRevisionId: FIRST_ID,
+        })
+      ),
+      d.deps
+    );
+
+    expect((await getConfigRevisions(
+      request("https://app.test/api/config/revisions?event=launch"),
+      d.deps
+    )).status).toBe(401);
+
+    const response = await getConfigRevisions(
+      adminRequest("/api/config/revisions?event=launch", "GET"),
+      d.deps
+    );
+    const json = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(json).toMatchObject({
+      config: { frames: ["birthday"], hasBoothKey: true },
+      currentRevisionId: SECOND_ID,
+    });
+    expect(json.revisions.map((revision: { id: string }) => revision.id)).toEqual([
+      SECOND_ID,
+      FIRST_ID,
+    ]);
+    expect(credentialFields(json)).toEqual([]);
+    expect(JSON.stringify(json)).not.toContain(BOOTH_KEY);
+    expect(JSON.stringify(json)).not.toContain("hashed:");
+  });
+
+  test("history returns 503 when the Admin Key is unavailable", async () => {
+    const d = deps({ adminKey: undefined });
+    const response = await getConfigRevisions(
+      adminRequest("/api/config/revisions?event=launch", "GET"),
+      d.deps
+    );
+
+    expect(response.status).toBe(503);
+  });
+
+  test("restore appends the selected reachable revision and preserves the Booth key", async () => {
+    const d = deps();
+    await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({ boothKey: BOOTH_KEY })
+      ),
+      d.deps
+    );
+    await putConfig(
+      adminRequest(
+        "/api/config?event=launch",
+        "PUT",
+        saveBody({
+          frames: ["birthday"],
+          mutationId: SECOND_ID,
+          baseRevisionId: FIRST_ID,
+        })
+      ),
+      d.deps
+    );
+
+    const restore = () => postConfigRestore(
+      adminRequest("/api/config/revisions/restore?event=launch", "POST", {
+        revisionId: FIRST_ID,
+        mutationId: THIRD_ID,
+        baseRevisionId: SECOND_ID,
+      }),
+      d.deps
+    );
+    const response = await restore();
+    const json = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(json).toEqual({
+      frames: ["square"],
+      hasBoothKey: true,
+      currentRevisionId: THIRD_ID,
+      idempotent: false,
+    });
+    expect(credentialFields(json)).toEqual([]);
+    const retry = await restore();
+    expect(retry.status).toBe(200);
+    expect(await retry.json()).toMatchObject({ idempotent: true });
+  });
+
+  test("restore maps a missing source to 404 and stale or reused mutations to 409", async () => {
+    const d = deps();
+    await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody()),
+      d.deps
+    );
+
+    expect((await postConfigRestore(
+      adminRequest("/api/config/revisions/restore?event=launch", "POST", {
+        revisionId: SECOND_ID,
+        mutationId: THIRD_ID,
+        baseRevisionId: FIRST_ID,
+      }),
+      d.deps
+    )).status).toBe(404);
+    expect((await postConfigRestore(
+      adminRequest("/api/config/revisions/restore?event=launch", "POST", {
+        revisionId: FIRST_ID,
+        mutationId: SECOND_ID,
+        baseRevisionId: null,
+      }),
+      d.deps
+    )).status).toBe(409);
+    expect((await postConfigRestore(
+      adminRequest("/api/config/revisions/restore?event=launch", "POST", {
+        revisionId: FIRST_ID,
+        mutationId: FIRST_ID,
+        baseRevisionId: FIRST_ID,
+      }),
+      d.deps
+    )).status).toBe(409);
+  });
+
+  test("restore rejects malformed input and enforces Admin authentication", async () => {
+    const invalidBodies = [
+      null,
+      {},
+      { revisionId: "bad", mutationId: SECOND_ID, baseRevisionId: FIRST_ID },
+      { revisionId: FIRST_ID, mutationId: "bad", baseRevisionId: FIRST_ID },
+      { revisionId: FIRST_ID, mutationId: SECOND_ID },
+      { revisionId: FIRST_ID, mutationId: SECOND_ID, baseRevisionId: "bad" },
+    ];
+
+    for (const body of invalidBodies) {
+      const d = deps();
+      expect((await postConfigRestore(
+        adminRequest("/api/config/revisions/restore?event=launch", "POST", body),
+        d.deps
+      )).status).toBe(400);
+    }
+
+    const unauthorized = deps();
+    expect((await postConfigRestore(
+      adminRequest("/api/config/revisions/restore?event=launch", "POST", {
+        revisionId: FIRST_ID,
+        mutationId: SECOND_ID,
+        baseRevisionId: FIRST_ID,
+      }, "wrong"),
+      unauthorized.deps
+    )).status).toBe(401);
+
+    const disabled = deps({ adminKey: undefined });
+    expect((await postConfigRestore(
+      adminRequest("/api/config/revisions/restore?event=launch", "POST", {
+        revisionId: FIRST_ID,
+        mutationId: SECOND_ID,
+        baseRevisionId: FIRST_ID,
+      }),
+      disabled.deps
+    )).status).toBe(503);
+  });
+});
diff --git a/app/api/config/handlers.ts b/app/api/config/handlers.ts
new file mode 100644
index 0000000..545b071
--- /dev/null
+++ b/app/api/config/handlers.ts
@@ -0,0 +1,265 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  ConfigConflictError,
+  ConfigMutationConflictError,
+  ConfigRevisionNotFoundError,
+  EventStore,
+  InvalidEventSlugError,
+} from "@/app/event-store";
+import {
+  isRevisionId,
+  projectPublicConfig,
+  type ConfigRevision,
+} from "@/app/event-config";
+import { TEMPLATES } from "@/app/templates";
+import { adminOk } from "@/app/upload-auth";
+
+type SaveBody = {
+  frames: string[];
+  boothKey?: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+};
+
+type RestoreBody = {
+  revisionId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+};
+
+export type ConfigHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+  hashBoothKey: (key: string) => Promise<string>;
+};
+
+const jsonError = (error: string, status: number) =>
+  NextResponse.json({ error }, { status });
+
+const toHex = (bytes: Uint8Array) =>
+  Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+
+/**
+ * Stable, opaque retry identity for Booth key mutations. The independently
+ * salted PBKDF2 hash remains the only credential verifier stored in config.
+ */
+export async function boothKeyMutationFingerprint(
+  boothKey: string,
+  adminKey: string
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(adminKey),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(boothKey));
+  return toHex(new Uint8Array(signature));
+}
+
+function eventFrom(req: NextRequest): string | NextResponse {
+  try {
+    return canonicalEvent(req.nextUrl.searchParams.get("event"));
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) {
+      return jsonError(error.message, 400);
+    }
+    throw error;
+  }
+}
+
+function requireAdmin(req: NextRequest, deps: ConfigHandlerDeps): NextResponse | null {
+  if (!deps.adminKey) {
+    return jsonError("config disabled: no key configured", 503);
+  }
+  const auth = adminOk(req.headers.get("x-booth-key") ?? "", deps.adminKey);
+  return auth === "ok" ? null : jsonError("unauthorized", 401);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  const allowlist = new Set(allowed);
+  return Object.keys(value).every((key) => allowlist.has(key));
+}
+
+function parseSaveBody(value: unknown): SaveBody | null {
+  if (!isObject(value) || !hasOnlyKeys(value, [
+    "frames",
+    "boothKey",
+    "mutationId",
+    "baseRevisionId",
+  ])) {
+    return null;
+  }
+  if (
+    !Array.isArray(value.frames)
+    || !value.frames.every((frame) => typeof frame === "string" && frame in TEMPLATES)
+    || !isRevisionId(value.mutationId)
+    || (value.baseRevisionId !== null && !isRevisionId(value.baseRevisionId))
+  ) {
+    return null;
+  }
+  if (
+    value.boothKey !== undefined
+    && (
+      typeof value.boothKey !== "string"
+      || value.boothKey.length < 12
+      || value.boothKey.length > 128
+    )
+  ) {
+    return null;
+  }
+  return {
+    frames: [...value.frames],
+    ...(typeof value.boothKey === "string" ? { boothKey: value.boothKey } : {}),
+    mutationId: value.mutationId,
+    baseRevisionId: value.baseRevisionId,
+  };
+}
+
+function parseRestoreBody(value: unknown): RestoreBody | null {
+  if (!isObject(value) || !hasOnlyKeys(value, [
+    "revisionId",
+    "mutationId",
+    "baseRevisionId",
+  ])) {
+    return null;
+  }
+  if (
+    !isRevisionId(value.revisionId)
+    || !isRevisionId(value.mutationId)
+    || (value.baseRevisionId !== null && !isRevisionId(value.baseRevisionId))
+  ) {
+    return null;
+  }
+  return {
+    revisionId: value.revisionId,
+    mutationId: value.mutationId,
+    baseRevisionId: value.baseRevisionId,
+  };
+}
+
+function safeRevision(revision: ConfigRevision): ConfigRevision {
+  const { hasBoothKey: _hasBoothKey, ...config } = projectPublicConfig(revision.config);
+  return {
+    version: revision.version,
+    id: revision.id,
+    createdAt: revision.createdAt,
+    parentRevisionId: revision.parentRevisionId,
+    reason: revision.reason,
+    ...(revision.sourceRevisionId ? { sourceRevisionId: revision.sourceRevisionId } : {}),
+    ...(revision.sourcePresetId ? { sourcePresetId: revision.sourcePresetId } : {}),
+    config: { ...config, frames: config.frames ?? [] },
+  };
+}
+
+function conflictResponse(error: unknown): NextResponse | null {
+  if (error instanceof ConfigConflictError || error instanceof ConfigMutationConflictError) {
+    return jsonError("configuration conflict", 409);
+  }
+  return null;
+}
+
+export async function getPublicConfig(
+  req: NextRequest,
+  deps: ConfigHandlerDeps
+): Promise<NextResponse> {
+  const event = eventFrom(req);
+  if (event instanceof NextResponse) return event;
+  const config = await deps.store.readConfig(event);
+  return NextResponse.json(projectPublicConfig(config));
+}
+
+export async function putConfig(
+  req: NextRequest,
+  deps: ConfigHandlerDeps
+): Promise<NextResponse> {
+  const rejected = requireAdmin(req, deps);
+  if (rejected) return rejected;
+  const event = eventFrom(req);
+  if (event instanceof NextResponse) return event;
+  const body = parseSaveBody(await req.json().catch(() => null));
+  if (!body) return jsonError("invalid config request", 400);
+
+  const boothKeyHash = body.boothKey === undefined
+    ? undefined
+    : await deps.hashBoothKey(body.boothKey);
+  const fingerprint = body.boothKey === undefined
+    ? undefined
+    : await boothKeyMutationFingerprint(body.boothKey, deps.adminKey!);
+
+  try {
+    const result = await deps.store.saveConfigRevision(event, {
+      config: {
+        frames: body.frames,
+        ...(boothKeyHash === undefined ? {} : { boothKeyHash }),
+      },
+      mutationId: body.mutationId,
+      baseRevisionId: body.baseRevisionId,
+      ...(fingerprint === undefined
+        ? {}
+        : { boothKeyMutationFingerprint: fingerprint }),
+    });
+    return NextResponse.json({
+      ...projectPublicConfig(result.config),
+      currentRevisionId: result.revision.id,
+      idempotent: result.idempotent,
+    });
+  } catch (error) {
+    const conflict = conflictResponse(error);
+    if (conflict) return conflict;
+    if (error instanceof TypeError) return jsonError("invalid config request", 400);
+    throw error;
+  }
+}
+
+export async function getConfigRevisions(
+  req: NextRequest,
+  deps: ConfigHandlerDeps
+): Promise<NextResponse> {
+  const rejected = requireAdmin(req, deps);
+  if (rejected) return rejected;
+  const event = eventFrom(req);
+  if (event instanceof NextResponse) return event;
+  const history = await deps.store.readConfigHistory(event);
+  return NextResponse.json({
+    config: projectPublicConfig(history.config),
+    currentRevisionId: history.currentRevisionId,
+    revisions: history.revisions.map(safeRevision),
+  });
+}
+
+export async function postConfigRestore(
+  req: NextRequest,
+  deps: ConfigHandlerDeps
+): Promise<NextResponse> {
+  const rejected = requireAdmin(req, deps);
+  if (rejected) return rejected;
+  const event = eventFrom(req);
+  if (event instanceof NextResponse) return event;
+  const body = parseRestoreBody(await req.json().catch(() => null));
+  if (!body) return jsonError("invalid restore request", 400);
+
+  try {
+    const result = await deps.store.restoreConfigRevision(event, body);
+    return NextResponse.json({
+      ...projectPublicConfig(result.config),
+      currentRevisionId: result.revision.id,
+      idempotent: result.idempotent,
+    });
+  } catch (error) {
+    if (error instanceof ConfigRevisionNotFoundError) {
+      return jsonError("configuration revision not found", 404);
+    }
+    const conflict = conflictResponse(error);
+    if (conflict) return conflict;
+    if (error instanceof TypeError) return jsonError("invalid restore request", 400);
+    throw error;
+  }
+}
diff --git a/app/api/config/revisions/restore/route.ts b/app/api/config/revisions/restore/route.ts
new file mode 100644
index 0000000..2dbad08
--- /dev/null
+++ b/app/api/config/revisions/restore/route.ts
@@ -0,0 +1,17 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { hashBoothKey } from "@/app/upload-auth";
+import { postConfigRestore } from "../../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  const store = EventStore.fromEnv(env);
+  return postConfigRestore(req, {
+    store,
+    adminKey: env.BOOTH_UPLOAD_KEY,
+    hashBoothKey,
+  });
+}
diff --git a/app/api/config/revisions/route.ts b/app/api/config/revisions/route.ts
new file mode 100644
index 0000000..f805c94
--- /dev/null
+++ b/app/api/config/revisions/route.ts
@@ -0,0 +1,17 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { hashBoothKey } from "@/app/upload-auth";
+import { getConfigRevisions } from "../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  const store = EventStore.fromEnv(env);
+  return getConfigRevisions(req, {
+    store,
+    adminKey: env.BOOTH_UPLOAD_KEY,
+    hashBoothKey,
+  });
+}
diff --git a/app/api/config/route.ts b/app/api/config/route.ts
index 4466e37..df1c057 100644
--- a/app/api/config/route.ts
+++ b/app/api/config/route.ts
@@ -1,65 +1,28 @@
 import { getCloudflareContext } from "@opennextjs/cloudflare";
-import { NextRequest, NextResponse } from "next/server";
-import { canonicalEvent, EventStore, InvalidEventSlugError } from "@/app/event-store";
-import { adminOk, hashBoothKey } from "@/app/upload-auth";
-import { TEMPLATES } from "@/app/templates";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { hashBoothKey } from "@/app/upload-auth";
+import { getPublicConfig, putConfig } from "./handlers";
 
 // no caching by Next — the booth reads this on every load and admin edits must show up.
 export const dynamic = "force-dynamic";
 
-// Public: which frames an event has enabled isn't secret, and the booth picker
-// needs it before (or without) a key. The booth key hash is deliberately NOT
-// returned — only `hasBoothKey`. { frames: null } = no config saved yet.
 export async function GET(req: NextRequest) {
-  let event: string;
-  try {
-    event = canonicalEvent(req.nextUrl.searchParams.get("event"));
-  } catch (error) {
-    if (error instanceof InvalidEventSlugError) return NextResponse.json({ error: error.message }, { status: 400 });
-    throw error;
-  }
   const { env } = getCloudflareContext();
-  const cfg = await EventStore.fromEnv(env).readConfig(event);
-  const frames = Array.isArray(cfg?.frames) ? cfg.frames.filter((f: unknown) => typeof f === "string") : null;
-  return NextResponse.json({ frames, hasBoothKey: !!cfg?.boothKeyHash });
+  const store = EventStore.fromEnv(env);
+  return getPublicConfig(req, {
+    store,
+    adminKey: env.BOOTH_UPLOAD_KEY,
+    hashBoothKey,
+  });
 }
 
-// Admin-key only. Saves the frame allowlist and (optionally) this event's
-// booth key — stored as a salted PBKDF2 hash in the private STATE bucket.
-// Omitting boothKey keeps the old one.
 export async function PUT(req: NextRequest) {
   const { env } = getCloudflareContext();
-  const auth = adminOk(req.headers.get("x-booth-key") ?? "", env.BOOTH_UPLOAD_KEY);
-  if (auth === "disabled") {
-    return NextResponse.json({ error: "config disabled: no key configured" }, { status: 503 });
-  }
-  if (auth === "unauthorized") {
-    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
-  }
-
-  const body = await req.json().catch(() => null);
-  const frames = body?.frames;
-  if (!Array.isArray(frames) || !frames.every((f) => typeof f === "string" && f in TEMPLATES)) {
-    return NextResponse.json({ error: "frames must be an array of template keys" }, { status: 400 });
-  }
-  const boothKey = body?.boothKey;
-  // 12-char floor still protects operator-chosen keys if private state is ever
-  // exposed through a backup or configuration mistake.
-  if (boothKey !== undefined && (typeof boothKey !== "string" || boothKey.length < 12 || boothKey.length > 128)) {
-    return NextResponse.json({ error: "boothKey must be a string of 12-128 chars" }, { status: 400 });
-  }
-
-  let event: string;
-  try {
-    event = canonicalEvent(req.nextUrl.searchParams.get("event"));
-  } catch (error) {
-    if (error instanceof InvalidEventSlugError) return NextResponse.json({ error: error.message }, { status: 400 });
-    throw error;
-  }
   const store = EventStore.fromEnv(env);
-  const prev = await store.readConfig(event);
-  const boothKeyHash = typeof boothKey === "string" ? await hashBoothKey(boothKey) : prev?.boothKeyHash;
-  await store.writeConfig(event, { frames, ...(boothKeyHash ? { boothKeyHash } : {}) });
-
-  return NextResponse.json({ frames, hasBoothKey: !!boothKeyHash });
+  return putConfig(req, {
+    store,
+    adminKey: env.BOOTH_UPLOAD_KEY,
+    hashBoothKey,
+  });
 }

From 13624c2433ad5fcbf0784402ec59f19624ba4b78 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 11:28:42 +0800
Subject: [PATCH 015/105] fix: require own frame template keys

---
 app/api/config/handlers.test.ts | 17 +++++++++++++++++
 app/api/config/handlers.ts      |  4 +++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/app/api/config/handlers.test.ts b/app/api/config/handlers.test.ts
index b5d48d0..d5d538b 100644
--- a/app/api/config/handlers.test.ts
+++ b/app/api/config/handlers.test.ts
@@ -265,6 +265,23 @@ describe("config handlers", () => {
     expect(malformed.status).toBe(400);
   });
 
+  test("save rejects inherited object names as Frames without writing config", async () => {
+    for (const frame of ["constructor", "toString"]) {
+      const d = deps();
+      const response = await putConfig(
+        adminRequest(
+          "/api/config?event=launch",
+          "PUT",
+          saveBody({ frames: [frame] })
+        ),
+        d.deps
+      );
+
+      expect(response.status).toBe(400);
+      expect(await d.deps.store.readConfig("launch")).toBeNull();
+    }
+  });
+
   test("save maps stale bases and mutation reuse to conflict", async () => {
     const d = deps();
     expect((await putConfig(
diff --git a/app/api/config/handlers.ts b/app/api/config/handlers.ts
index 545b071..3d53340 100644
--- a/app/api/config/handlers.ts
+++ b/app/api/config/handlers.ts
@@ -99,7 +99,9 @@ function parseSaveBody(value: unknown): SaveBody | null {
   }
   if (
     !Array.isArray(value.frames)
-    || !value.frames.every((frame) => typeof frame === "string" && frame in TEMPLATES)
+    || !value.frames.every((frame) =>
+      typeof frame === "string" && Object.hasOwn(TEMPLATES, frame)
+    )
     || !isRevisionId(value.mutationId)
     || (value.baseRevisionId !== null && !isRevisionId(value.baseRevisionId))
   ) {

From ca068cdd7a18eb1e835cd3f8342876dd509d8bdf Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 11:36:36 +0800
Subject: [PATCH 016/105] feat: add admin config history and restore

---
 app/[event]/admin/admin.module.css            |  30 +++-
 .../admin/config-history-panel.test.tsx       |  38 +++++
 app/[event]/admin/config-history-panel.tsx    | 137 +++++++++++++++++
 app/[event]/admin/page.tsx                    | 141 ++++++++++++++++--
 tsconfig.test.json                            |   1 +
 5 files changed, 333 insertions(+), 14 deletions(-)
 create mode 100644 app/[event]/admin/config-history-panel.test.tsx
 create mode 100644 app/[event]/admin/config-history-panel.tsx

diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index ae3d581..caf7a23 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -25,6 +25,34 @@
 .frameGroups { display: flex; flex-direction: column; gap: 25px; padding-top: 20px; }.groupHead { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }.groupHead h3 { font: 900 14px/1 ui-monospace, monospace; text-transform: uppercase; }.filmRail { display: grid; grid-template-columns: repeat(auto-fill, minmax(145px, 1fr)); gap: 8px; }
 .frameCard { position: relative; display: flex; flex-direction: column; min-width: 0; padding: 8px; border: 2px solid #b7b2a8; background: #e3dfd5; cursor: pointer; }.frameCard[data-enabled="true"] { border-color: var(--ink); background: #fff; box-shadow: inset 0 -6px var(--pink); }.frameCard input { position: absolute; opacity: 0; }.frameCard:focus-within { outline: 4px solid var(--amber); outline-offset: 2px; }
 .framePreview { position: relative; display: block; width: 100%; max-height: 220px; overflow: hidden; isolation: isolate; }.frameLayer, .overlayLayer { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: fill; }.frameLayer { z-index: 1; }.photoSlot { position: absolute; z-index: 2; background: linear-gradient(135deg, #53504d 0 35%, #d8d0c2 35% 55%, #79736d 55%); box-shadow: inset 0 0 0 1px rgba(255,255,255,.4); }.overlayLayer { z-index: 3; }.frameMeta { display: flex; flex-direction: column; gap: 3px; padding: 9px 0 5px; }.frameMeta strong { font: 900 14px/1 system-ui, sans-serif; }.frameMeta small { font: 10px/1.2 ui-monospace, monospace; color: #666159; }.frameCheck { position: absolute; z-index: 4; right: 12px; top: 12px; background: var(--ink); color: #fff; padding: 5px; font: 900 9px/1 ui-monospace, monospace; }
+.historySection { min-width: 0; }
+.historyLoading { margin-top: 15px; padding: 28px; color: var(--paper); background: var(--ink); font: 800 12px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; }
+.revisionRail { position: relative; display: flex; flex-direction: column; gap: 1px; margin-top: 15px; padding: 20px 12px; overflow: hidden; list-style: none; background: var(--ink); }
+.revisionRail::before, .revisionRail::after { content: ""; position: absolute; z-index: 2; right: 10px; left: 10px; height: 6px; background: repeating-linear-gradient(90deg, var(--paper) 0 12px, transparent 12px 22px); pointer-events: none; }
+.revisionRail::before { top: 6px; }.revisionRail::after { bottom: 6px; }
+.revisionRecord { position: relative; display: grid; grid-template-columns: 50px minmax(0, 1fr) minmax(150px, 220px); min-width: 0; background: var(--paper); }
+.revisionRecord[data-current="true"] { box-shadow: inset 5px 0 var(--green); }
+.revisionIndex { display: grid; place-items: center; border-right: 1px solid var(--ink); color: var(--paper); background: var(--ink); }
+.revisionIndex span { font: 900 18px/1 Impact, "Arial Narrow", sans-serif; letter-spacing: .08em; }
+.revisionDetails { min-width: 0; padding: 13px 15px; }
+.revisionHeadline { display: flex; flex-wrap: wrap; align-items: center; gap: 7px 12px; }
+.revisionHeadline time { font: 800 12px/1 ui-monospace, monospace; }
+.revisionHeadline strong { font: 900 15px/1 "Arial Narrow", Arial, sans-serif; text-transform: uppercase; }
+.currentStamp { padding: 5px 7px 4px; color: var(--ink); background: var(--green); font: 900 9px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .1em; transform: rotate(-1deg); }
+.revisionDetails > code { display: block; max-width: 100%; margin-top: 7px; overflow: hidden; color: var(--ink); font: 9px/1 ui-monospace, monospace; text-overflow: ellipsis; white-space: nowrap; opacity: .62; }
+.revisionDelta { display: flex; flex-wrap: wrap; gap: 5px; margin-top: 10px; }
+.revisionDelta span { border: 1px solid var(--ink); padding: 4px 6px; color: var(--paper); background: var(--ink); font: 800 9px/1 ui-monospace, monospace; }
+.revisionDelta span[data-delta="added"] { color: var(--ink); background: var(--green); }
+.revisionDelta span[data-delta="removed"] { color: #fff; background: var(--pink); }
+.revisionDelta span[data-delta="same"] { color: var(--ink); background: var(--paper); }
+.revisionAction { display: flex; align-items: stretch; border-left: 1px solid var(--ink); }
+.restoreButton { width: 100%; border: 0; padding: 14px; color: var(--ink); background: var(--amber); font: 900 11px/1.15 system-ui, sans-serif; cursor: pointer; }
+.restoreButton:disabled { color: var(--ink); background: var(--green); cursor: default; opacity: 1; }
+.restoreConfirm { display: grid; grid-template-columns: 1fr 1fr; width: 100%; padding: 10px; gap: 7px; color: var(--paper); background: var(--ink); }
+.restoreConfirm p { grid-column: 1 / -1; overflow-wrap: anywhere; font: 10px/1.35 ui-monospace, monospace; }
+.restoreConfirm button { border: 1px solid var(--paper); padding: 8px; color: var(--ink); background: var(--amber); font: 800 10px/1.2 system-ui, sans-serif; cursor: pointer; }
+.restoreConfirm button:last-child { color: var(--paper); background: var(--ink); }
+.restoreConfirm button:disabled { cursor: wait; opacity: .6; }
 .sideCard, .linkCard { border: 2px solid var(--ink); padding: 17px; background: #fff; }.sideCard .cardNumber { color: var(--pink); display: block; margin-bottom: 16px; }.sideCard h2 { font-size: 30px; margin-bottom: 10px; }.sideCard p { margin-bottom: 16px; }
 .keyRow { display: flex; }.keyRow input { min-width: 0; width: 100%; border: 1px solid var(--ink); padding: 11px; font: 12px/1 ui-monospace, monospace; }.keyRow button, .copyWide, .clearKey, .saveButton, .exportButton, .linkActions a, .linkActions button, .failure button { border: 1px solid var(--ink); color: var(--ink); background: var(--amber); padding: 10px 12px; font: 800 12px/1 system-ui, sans-serif; cursor: pointer; text-decoration: none; }.copyWide, .clearKey { margin-top: 7px; width: 100%; background: #fff; }.clearKey { border-style: dashed; color: #555; }
 .linkCard { display: grid; grid-template-columns: minmax(0, 1fr) 94px; gap: 12px; background: var(--ink); color: #fff; }.linkCard > div > span { color: var(--amber); font: 800 9px/1 ui-monospace, monospace; text-transform: uppercase; }.linkCard h2 { font-size: 25px; margin: 6px 0 10px; }.linkCard code { display: block; color: #d3cec4; font: 10px/1.35 ui-monospace, monospace; word-break: break-all; }.linkCard img { width: 94px; height: 94px; background: #fff; padding: 5px; }.linkActions { display: flex; gap: 5px; margin-top: 12px; }.linkActions a, .linkActions button { flex: 1; padding: 8px; text-align: center; background: transparent; color: #fff; border-color: #777; }.saveButton, .exportButton { width: 100%; padding: 14px; background: var(--pink); color: #fff; border: 0; }.exportButton { margin-top: 8px; color: var(--ink); background: var(--amber); }.saveButton:disabled, .exportButton:disabled { opacity: .5; cursor: wait; }
@@ -33,5 +61,5 @@
 .authPage { display: grid; place-items: center; padding: 20px; background: var(--ink); color: #fff; }.authCard { width: min(500px, 100%); border-top: 8px solid var(--pink); padding: clamp(25px, 5vw, 55px); background: #1a1a19; }.authCard h1 { margin: 25px 0; font: 900 clamp(58px, 10vw, 90px)/.78 Impact, sans-serif; text-transform: uppercase; }.authCard > p:not(.kicker) { color: #bbb; line-height: 1.4; margin-bottom: 28px; }.authCard label { display: block; margin-bottom: 8px; font: 800 11px/1 ui-monospace, monospace; text-transform: uppercase; }.authCard input { width: 100%; padding: 14px; border: 1px solid #777; background: #080808; color: #fff; font: 16px/1 ui-monospace, monospace; }.authCard button { width: 100%; margin-top: 10px; padding: 15px; border: 0; color: #fff; background: var(--pink); font-weight: 900; cursor: pointer; }
 .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
 @media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; } }
-@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; } }
+@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; }.revisionRecord { grid-template-columns: 40px minmax(0, 1fr); }.revisionAction { grid-column: 2; border-top: 1px solid var(--ink); border-left: 0; }.restoreButton { min-height: 44px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; } }
 @media (prefers-reduced-motion: reduce) { .console *, .console *::before, .console *::after, .authPage *, .authPage *::before, .authPage *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; } }
diff --git a/app/[event]/admin/config-history-panel.test.tsx b/app/[event]/admin/config-history-panel.test.tsx
new file mode 100644
index 0000000..c726616
--- /dev/null
+++ b/app/[event]/admin/config-history-panel.test.tsx
@@ -0,0 +1,38 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ConfigHistoryPanel, diffFrameKeys } from "./config-history-panel";
+
+test("diffFrameKeys reports additions and removals", () => {
+  expect(diffFrameKeys(["one", "three"], ["one", "two"])).toEqual({
+    added: ["two"],
+    removed: ["three"],
+  });
+});
+
+test("history renders reasons and disables restoring the current revision", () => {
+  const html = renderToStaticMarkup(
+    <ConfigHistoryPanel
+      currentFrames={["one"]}
+      currentRevisionId="018f0000-0000-7000-8000-000000000030"
+      revisions={[{
+        version: 1,
+        id: "018f0000-0000-7000-8000-000000000030",
+        createdAt: "2026-07-24T00:00:00.000Z",
+        parentRevisionId: null,
+        reason: "save",
+        config: { frames: ["one"] },
+      }]}
+      loading={false}
+      restoringRevisionId={null}
+      error=""
+      onReload={() => {}}
+      onRestore={() => {}}
+    />
+  );
+
+  expect(html).toContain("Configuration history");
+  expect(html).toContain("R01");
+  expect(html).toContain("Current");
+  expect(html).toContain("disabled");
+  expect(html).not.toContain("boothKey");
+});
diff --git a/app/[event]/admin/config-history-panel.tsx b/app/[event]/admin/config-history-panel.tsx
new file mode 100644
index 0000000..e98376f
--- /dev/null
+++ b/app/[event]/admin/config-history-panel.tsx
@@ -0,0 +1,137 @@
+"use client";
+
+import { useState } from "react";
+import type { ConfigRevision } from "../../event-config";
+import styles from "./admin.module.css";
+
+export type ConfigHistoryPanelProps = {
+  currentFrames: readonly string[];
+  currentRevisionId: string | null;
+  revisions: readonly ConfigRevision[];
+  loading: boolean;
+  restoringRevisionId: string | null;
+  error: string;
+  onReload: () => void;
+  onRestore: (revisionId: string) => void;
+};
+
+export function diffFrameKeys(
+  current: readonly string[],
+  historical: readonly string[]
+) {
+  return {
+    added: historical.filter((key) => !current.includes(key)),
+    removed: current.filter((key) => !historical.includes(key)),
+  };
+}
+
+const reasonLabel: Record<ConfigRevision["reason"], string> = {
+  baseline: "Baseline",
+  save: "Saved",
+  restore: "Restored",
+  preset: "Preset",
+};
+
+export function ConfigHistoryPanel({
+  currentFrames,
+  currentRevisionId,
+  revisions,
+  loading,
+  restoringRevisionId,
+  error,
+  onReload,
+  onRestore,
+}: ConfigHistoryPanelProps) {
+  const [confirmRevisionId, setConfirmRevisionId] = useState<string | null>(null);
+
+  return (
+    <section className={styles.historySection} aria-labelledby="configuration-history-title">
+      <div className={styles.sectionHead}>
+        <div><span>02</span><h2 id="configuration-history-title">Configuration history</h2></div>
+        <p>Review each recorded exposure, or restore an earlier Frame selection.</p>
+      </div>
+
+      {error ? (
+        <div className={styles.failure}>
+          <strong>History unavailable</strong>
+          <p>{error}</p>
+          <button type="button" onClick={onReload}>Reload history</button>
+        </div>
+      ) : loading ? (
+        <p className={styles.historyLoading}>Loading configuration history…</p>
+      ) : revisions.length === 0 ? (
+        <div className={styles.emptySheet}>
+          <strong>No revisions yet.</strong>
+          <p>Your first saved configuration will appear here.</p>
+        </div>
+      ) : (
+        <ol className={styles.revisionRail}>
+          {revisions.map((revision, index) => {
+            const isCurrent = revision.id === currentRevisionId;
+            const isRestoring = revision.id === restoringRevisionId;
+            const isConfirming = revision.id === confirmRevisionId;
+            const frameDiff = diffFrameKeys(currentFrames, revision.config.frames);
+            const timestamp = new Date(revision.createdAt);
+            const readableTime = timestamp.toLocaleString([], {
+              dateStyle: "medium",
+              timeStyle: "short",
+            });
+
+            return (
+              <li className={styles.revisionRecord} key={revision.id} data-current={isCurrent}>
+                <div className={styles.revisionIndex} aria-hidden="true">
+                  <span>R{String(revisions.length - index).padStart(2, "0")}</span>
+                </div>
+                <div className={styles.revisionDetails}>
+                  <div className={styles.revisionHeadline}>
+                    <time dateTime={revision.createdAt}>{readableTime}</time>
+                    <strong>{reasonLabel[revision.reason]}</strong>
+                    {isCurrent && <span className={styles.currentStamp}>Current</span>}
+                  </div>
+                  <code title={revision.id}>{revision.id}</code>
+                  <div className={styles.revisionDelta}>
+                    <span>{revision.config.frames.length} Frame{revision.config.frames.length === 1 ? "" : "s"}</span>
+                    {frameDiff.added.map((key) => <span data-delta="added" key={`add-${key}`}>+ {key}</span>)}
+                    {frameDiff.removed.map((key) => <span data-delta="removed" key={`remove-${key}`}>− {key}</span>)}
+                    {!isCurrent && frameDiff.added.length === 0 && frameDiff.removed.length === 0 && (
+                      <span data-delta="same">Same Frames</span>
+                    )}
+                  </div>
+                </div>
+                <div className={styles.revisionAction}>
+                  {isConfirming && !isCurrent ? (
+                    <div className={styles.restoreConfirm}>
+                      <p>Restore revision {revision.id} from <time dateTime={revision.createdAt}>{readableTime}</time>?</p>
+                      <button
+                        type="button"
+                        onClick={() => {
+                          setConfirmRevisionId(null);
+                          onRestore(revision.id);
+                        }}
+                        disabled={isRestoring}
+                      >
+                        {isRestoring ? "Restoring…" : "Confirm exact restore"}
+                      </button>
+                      <button type="button" onClick={() => setConfirmRevisionId(null)} disabled={isRestoring}>
+                        Keep current
+                      </button>
+                    </div>
+                  ) : (
+                    <button
+                      type="button"
+                      className={styles.restoreButton}
+                      onClick={() => setConfirmRevisionId(revision.id)}
+                      disabled={isCurrent || restoringRevisionId !== null}
+                    >
+                      {isCurrent ? "Current" : "Restore this version"}
+                    </button>
+                  )}
+                </div>
+              </li>
+            );
+          })}
+        </ol>
+      )}
+    </section>
+  );
+}
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index 8eaaa91..f436b88 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -4,14 +4,22 @@ import { FormEvent, useCallback, useEffect, useMemo, useRef, useState } from "re
 import { useParams } from "next/navigation";
 import QRCode from "qrcode";
 import { GROUPS, TEMPLATES } from "../../templates";
+import type { ConfigRevision, PublicEventConfig } from "../../event-config";
 import type { Template } from "../../frame-packs/types";
+import { ConfigHistoryPanel } from "./config-history-panel";
 import styles from "./admin.module.css";
 
 type Photo = { key: string; url: string; uploadedAt: string };
 type AuthState = "missing" | "ready" | "invalid";
 type Probe = { status: "up" | "degraded" | "down"; detail: string };
 type Health = { upload: Probe; live: Probe };
+type ConfigHistoryResponse = {
+  config: PublicEventConfig;
+  currentRevisionId: string | null;
+  revisions: ConfigRevision[];
+};
 type FilePickerWindow = Window & { showSaveFilePicker?: (options: { suggestedName: string; types: { description: string; accept: Record<string, string[]> }[] }) => Promise<{ createWritable(): Promise<WritableStream<Uint8Array>> }> };
+const CONFIG_CONFLICT_MESSAGE = "Configuration changed; review the latest version before saving.";
 
 function FramePreview({ frame }: { frame: Template }) {
   return (
@@ -41,6 +49,9 @@ export default function Admin() {
   const [frames, setFrames] = useState<Set<string>>(new Set());
   const [configLoaded, setConfigLoaded] = useState(false);
   const [configError, setConfigError] = useState("");
+  const [currentRevisionId, setCurrentRevisionId] = useState<string | null>(null);
+  const [revisions, setRevisions] = useState<ConfigRevision[]>([]);
+  const [restoringRevisionId, setRestoringRevisionId] = useState<string | null>(null);
   const [hasBoothKey, setHasBoothKey] = useState(false);
   const [boothKey, setBoothKey] = useState("");
   const [boothKeySaved, setBoothKeySaved] = useState(false);
@@ -60,10 +71,16 @@ export default function Admin() {
   const [health, setHealth] = useState<Health | null>(null);
   const [checkingHealth, setCheckingHealth] = useState(false);
   const photoCursor = useRef<string | null>(null);
+  const pendingSaveMutationId = useRef<string | null>(null);
+  const pendingRestoreMutationIds = useRef(new Map<string, string>());
 
   const boothUrl = `${origin}/${event}`;
   const liveUrl = `${boothUrl}/live`;
   const defaults = useMemo(() => Object.keys(TEMPLATES).filter((key) => !TEMPLATES[key].group), []);
+  const clearPendingSave = () => {
+    pendingSaveMutationId.current = null;
+    setError((current) => current === CONFIG_CONFLICT_MESSAGE ? "" : current);
+  };
 
   const runHealth = useCallback(async (key = adminKey) => {
     setCheckingHealth(true); setError("");
@@ -98,18 +115,36 @@ export default function Admin() {
   }, [boothUrl, liveUrl, origin]);
 
   const loadConfig = useCallback(async () => {
+    setConfigLoaded(false);
     setConfigError("");
     try {
-      const response = await fetch(`/api/config?event=${encodeURIComponent(event)}`, { cache: "no-store" });
-      if (!response.ok) throw new Error(`Config returned ${response.status}`);
-      const data = await response.json();
-      setFrames(new Set(Array.isArray(data.frames) ? data.frames : defaults));
-      setHasBoothKey(Boolean(data.hasBoothKey));
+      const response = await fetch(`/api/config/revisions?event=${encodeURIComponent(event)}`, {
+        cache: "no-store",
+        headers: { "x-booth-key": adminKey },
+      });
+      if (response.status === 401) {
+        sessionStorage.removeItem("adminKey");
+        setAuth("invalid");
+        throw new Error("That admin key was rejected.");
+      }
+      if (!response.ok) throw new Error(`Configuration history returned ${response.status}`);
+      const data = await response.json() as ConfigHistoryResponse;
+      if (
+        !data.config
+        || !Array.isArray(data.revisions)
+        || (data.currentRevisionId !== null && typeof data.currentRevisionId !== "string")
+      ) {
+        throw new Error("Configuration history had an unexpected shape");
+      }
+      setFrames(new Set(Array.isArray(data.config.frames) ? data.config.frames : defaults));
+      setHasBoothKey(Boolean(data.config.hasBoothKey));
+      setCurrentRevisionId(data.currentRevisionId);
+      setRevisions(data.revisions);
       setConfigLoaded(true);
     } catch (cause) {
       setConfigError(cause instanceof Error ? cause.message : "Config could not be loaded");
     }
-  }, [defaults, event]);
+  }, [adminKey, defaults, event]);
 
   const loadPhotos = useCallback(async (reset = false) => {
     setPhotosError("");
@@ -134,12 +169,16 @@ export default function Admin() {
   }, [event]);
 
   useEffect(() => {
-    void loadConfig();
     photoCursor.current = null;
     void loadPhotos(true);
     const poll = window.setInterval(() => void loadPhotos(), 5000);
     return () => window.clearInterval(poll);
-  }, [loadConfig, loadPhotos]);
+  }, [loadPhotos]);
+
+  useEffect(() => {
+    if (auth !== "ready" || !adminKey) return;
+    void loadConfig();
+  }, [adminKey, auth, loadConfig]);
 
   const authenticate = (submitEvent: FormEvent) => {
     submitEvent.preventDefault();
@@ -158,6 +197,7 @@ export default function Admin() {
   };
 
   const toggle = (key: string) => {
+    clearPendingSave();
     setFrames((current) => {
       const next = new Set(current);
       if (next.has(key)) next.delete(key); else next.add(key);
@@ -167,6 +207,7 @@ export default function Admin() {
   };
 
   const setGroup = (group: string, enabled: boolean) => {
+    clearPendingSave();
     const keys = Object.keys(TEMPLATES).filter((key) => TEMPLATES[key].group === group);
     setFrames((current) => {
       const next = new Set(current);
@@ -176,6 +217,7 @@ export default function Admin() {
   };
 
   const generateBoothKey = () => {
+    clearPendingSave();
     const bytes = crypto.getRandomValues(new Uint8Array(12));
     setBoothKey(Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""));
     setBoothKeySaved(false);
@@ -193,26 +235,88 @@ export default function Admin() {
   };
 
   const save = async () => {
+    if (!configLoaded) return;
     if (boothKey && boothKey.length < 12) {
       setError("Booth keys need at least 12 characters.");
       return;
     }
     setSaving(true); setError(""); setNotice("");
+    const mutationId = pendingSaveMutationId.current ?? crypto.randomUUID();
+    pendingSaveMutationId.current = mutationId;
     try {
       const response = await fetch(`/api/config?event=${encodeURIComponent(event)}`, {
         method: "PUT",
         headers: { "x-booth-key": adminKey, "content-type": "application/json" },
-        body: JSON.stringify({ frames: [...frames], ...(boothKey ? { boothKey } : {}) }),
+        body: JSON.stringify({
+          frames: [...frames],
+          ...(boothKey ? { boothKey } : {}),
+          mutationId,
+          baseRevisionId: currentRevisionId,
+        }),
       });
+      if ([400, 401, 409].includes(response.status)) pendingSaveMutationId.current = null;
       if (response.status === 401) { invalidateAuth(); throw new Error("That admin key was rejected."); }
+      if (response.status === 409) {
+        await loadConfig();
+        setError(CONFIG_CONFLICT_MESSAGE);
+        return;
+      }
       if (!response.ok) throw new Error(`Save failed (${response.status})`);
+      const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
+      pendingSaveMutationId.current = null;
+      setCurrentRevisionId(data.currentRevisionId);
       if (boothKey) { setHasBoothKey(true); setBoothKeySaved(true); }
+      await loadConfig();
       setNotice(boothKey ? "Event saved. Keep the new booth key somewhere secure." : "Event configuration saved.");
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : "Event could not be saved");
     } finally { setSaving(false); }
   };
 
+  const restoreRevision = async (revisionId: string) => {
+    if (!configLoaded) return;
+    const pending = pendingRestoreMutationIds.current;
+    const mutationId = pending.get(revisionId) ?? crypto.randomUUID();
+    pending.set(revisionId, mutationId);
+    setRestoringRevisionId(revisionId);
+    setError("");
+    setNotice("");
+    try {
+      const response = await fetch(`/api/config/revisions/restore?event=${encodeURIComponent(event)}`, {
+        method: "POST",
+        headers: { "x-booth-key": adminKey, "content-type": "application/json" },
+        body: JSON.stringify({
+          revisionId,
+          mutationId,
+          baseRevisionId: currentRevisionId,
+        }),
+      });
+      if ([400, 401, 404, 409].includes(response.status)) pending.delete(revisionId);
+      if (response.status === 401) { invalidateAuth(); throw new Error("That admin key was rejected."); }
+      if (response.status === 409) {
+        await loadConfig();
+        setError(CONFIG_CONFLICT_MESSAGE);
+        return;
+      }
+      if (!response.ok) throw new Error(`Restore failed (${response.status})`);
+      const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
+      pending.delete(revisionId);
+      pendingSaveMutationId.current = null;
+      setFrames(new Set(Array.isArray(data.frames) ? data.frames : defaults));
+      setHasBoothKey(Boolean(data.hasBoothKey));
+      setCurrentRevisionId(data.currentRevisionId);
+      setBoothKey("");
+      setBoothKeySaved(false);
+      setCopied((current) => current === "key" ? "" : current);
+      await loadConfig();
+      setNotice("Configuration restored.");
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : "Configuration could not be restored");
+    } finally {
+      setRestoringRevisionId(null);
+    }
+  };
+
   const exportZip = async () => {
     setExporting(true); setError("");
     try {
@@ -317,8 +421,19 @@ export default function Admin() {
             </div>}
           </section>
 
+          <ConfigHistoryPanel
+            currentFrames={[...frames]}
+            currentRevisionId={currentRevisionId}
+            revisions={revisions}
+            loading={!configLoaded && !configError}
+            restoringRevisionId={restoringRevisionId}
+            error={configError}
+            onReload={() => void loadConfig()}
+            onRestore={(revisionId) => void restoreRevision(revisionId)}
+          />
+
           <section className={styles.section}>
-            <div className={styles.sectionHead}><div><span>02</span><h2>Recent contact sheet</h2></div><p>{photos.length} photograph{photos.length === 1 ? "" : "s"} currently in this event.</p></div>
+            <div className={styles.sectionHead}><div><span>03</span><h2>Recent contact sheet</h2></div><p>{photos.length} photograph{photos.length === 1 ? "" : "s"} currently in this event.</p></div>
             {photosError && photos.length === 0 ? <div className={styles.failure}><strong>Photo feed unavailable</strong><p>{photosError}</p><button onClick={() => void loadPhotos(true)}>Retry photos</button></div> : photosLoaded && photos.length === 0 ?
               <div className={styles.emptySheet}><strong>No exposures yet.</strong><p>Open the booth link and take a test photo before doors open.</p></div> :
               <div className={styles.contactSheet}>{photos.slice(0, 16).map((photo) => <article key={photo.key} className={styles.contactPhoto}>
@@ -331,11 +446,11 @@ export default function Admin() {
 
         <aside className={styles.sideColumn}>
           <section className={styles.sideCard}>
-            <span className={styles.cardNumber}>03</span><h2>Booth credential</h2>
+            <span className={styles.cardNumber}>04</span><h2>Booth credential</h2>
             <p>{hasBoothKey ? "A booth key is installed. Generate a replacement only when rotating iPad access." : "No booth key yet. Generate one before the booth can upload."}</p>
-            <div className={styles.keyRow}><input aria-label="New booth key" value={boothKey} onChange={(e) => { setBoothKey(e.target.value.trim()); setBoothKeySaved(false); }} placeholder={hasBoothKey ? "Unchanged" : "Generate a key"} autoComplete="off" /><button onClick={generateBoothKey}>Generate</button></div>
+            <div className={styles.keyRow}><input aria-label="New booth key" value={boothKey} onChange={(e) => { clearPendingSave(); setBoothKey(e.target.value.trim()); setBoothKeySaved(false); }} placeholder={hasBoothKey ? "Unchanged" : "Generate a key"} autoComplete="off" /><button onClick={generateBoothKey}>Generate</button></div>
             {boothKey && <button className={styles.copyWide} onClick={() => void copy(boothKey, "key")}>{copied === "key" ? "Copied ✓" : "Copy generated key"}</button>}
-            {boothKey && boothKeySaved && <button className={styles.clearKey} onClick={() => { setBoothKey(""); setBoothKeySaved(false); setCopied(""); }}>Stored safely — clear key</button>}
+            {boothKey && boothKeySaved && <button className={styles.clearKey} onClick={() => { clearPendingSave(); setBoothKey(""); setBoothKeySaved(false); setCopied(""); }}>Stored safely — clear key</button>}
           </section>
 
           <LinkCard label="Booth / iPad" url={boothUrl} qr={boothQr} copied={copied === "booth"} copy={() => void copy(boothUrl, "booth")} />
diff --git a/tsconfig.test.json b/tsconfig.test.json
index 73ae60d..c9cda62 100644
--- a/tsconfig.test.json
+++ b/tsconfig.test.json
@@ -9,6 +9,7 @@
     "next-env.d.ts",
     "cloudflare-env.d.ts",
     "app/**/*.test.ts",
+    "app/**/*.test.tsx",
     "scripts/**/*.test.ts"
   ],
   "exclude": ["node_modules"]

From d68252f3812eff9584f9e03bed55620f4da61c94 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 14:38:17 +0800
Subject: [PATCH 017/105] fix: harden admin config history interactions

---
 .../admin/admin-config-controls.test.tsx      |  56 +++++
 app/[event]/admin/admin-config-controls.tsx   | 191 ++++++++++++++++++
 app/[event]/admin/admin-styles.test.ts        |  18 ++
 app/[event]/admin/admin.module.css            |  23 +--
 .../admin/config-history-panel.test.tsx       |  58 ++++++
 app/[event]/admin/config-history-panel.tsx    |  16 +-
 app/[event]/admin/config-mutation.test.ts     |  66 ++++++
 app/[event]/admin/config-mutation.ts          |  27 +++
 app/[event]/admin/page.tsx                    | 139 +++++++------
 9 files changed, 512 insertions(+), 82 deletions(-)
 create mode 100644 app/[event]/admin/admin-config-controls.test.tsx
 create mode 100644 app/[event]/admin/admin-config-controls.tsx
 create mode 100644 app/[event]/admin/admin-styles.test.ts
 create mode 100644 app/[event]/admin/config-mutation.test.ts
 create mode 100644 app/[event]/admin/config-mutation.ts

diff --git a/app/[event]/admin/admin-config-controls.test.tsx b/app/[event]/admin/admin-config-controls.test.tsx
new file mode 100644
index 0000000..17fab6d
--- /dev/null
+++ b/app/[event]/admin/admin-config-controls.test.tsx
@@ -0,0 +1,56 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { GROUPS, TEMPLATES } from "../../templates";
+import {
+  BoothKeyControls,
+  FrameProgrammeControls,
+  SaveConfigurationButton,
+} from "./admin-config-controls";
+
+test("Frame and pack controls are disabled while a configuration mutation is busy", () => {
+  const [defaultFrame] = Object.keys(TEMPLATES).filter((key) => !TEMPLATES[key].group);
+  const html = renderToStaticMarkup(
+    <FrameProgrammeControls
+      frames={new Set([defaultFrame])}
+      defaults={[defaultFrame]}
+      disabled
+      onToggle={() => {}}
+      onSetGroup={() => {}}
+    />
+  );
+  const controls = html.match(/<(?:button|input)\b/g) ?? [];
+  const disabledControls = html.match(/disabled=""/g) ?? [];
+
+  expect(controls.length).toBeGreaterThan(Object.keys(GROUPS).length);
+  expect(disabledControls.length).toBe(controls.length);
+});
+
+test("Booth-key input, generate, and clear are disabled while copy remains available", () => {
+  const html = renderToStaticMarkup(
+    <BoothKeyControls
+      value="a-secure-booth-key"
+      saved
+      copied={false}
+      disabled
+      placeholder="Unchanged"
+      onChange={() => {}}
+      onGenerate={() => {}}
+      onCopy={() => {}}
+      onClear={() => {}}
+    />
+  );
+
+  expect((html.match(/disabled=""/g) ?? []).length).toBe(3);
+  expect(html).toContain(">Generate</button>");
+  expect(html).toContain(">Copy generated key</button>");
+  expect(html).toContain(">Stored safely — clear key</button>");
+});
+
+test("Save is disabled while a configuration mutation is busy", () => {
+  const html = renderToStaticMarkup(
+    <SaveConfigurationButton disabled saving={false} onSave={() => {}} />
+  );
+
+  expect(html).toContain("disabled");
+  expect(html).toContain(">Save configuration</button>");
+});
diff --git a/app/[event]/admin/admin-config-controls.tsx b/app/[event]/admin/admin-config-controls.tsx
new file mode 100644
index 0000000..e250c8f
--- /dev/null
+++ b/app/[event]/admin/admin-config-controls.tsx
@@ -0,0 +1,191 @@
+"use client";
+
+import { GROUPS, TEMPLATES } from "../../templates";
+import type { Template } from "../../frame-packs/types";
+import styles from "./admin.module.css";
+
+type FrameProgrammeControlsProps = {
+  frames: ReadonlySet<string>;
+  defaults: readonly string[];
+  disabled: boolean;
+  onToggle: (key: string) => void;
+  onSetGroup: (group: string, enabled: boolean) => void;
+};
+
+type BoothKeyControlsProps = {
+  value: string;
+  saved: boolean;
+  copied: boolean;
+  disabled: boolean;
+  placeholder: string;
+  onChange: (value: string) => void;
+  onGenerate: () => void;
+  onCopy: () => void;
+  onClear: () => void;
+};
+
+function FramePreview({ frame }: { frame: Template }) {
+  return (
+    <span className={styles.framePreview} style={{ aspectRatio: `${frame.canvas.w}/${frame.canvas.h}`, backgroundColor: frame.background || "#d8d5cc" }}>
+      {frame.bgImage && <img src={frame.bgImage} alt="" className={styles.frameLayer} />}
+      {frame.slots.map((slot, index) => (
+        <span
+          key={index}
+          className={styles.photoSlot}
+          style={{
+            left: `${slot.x / frame.canvas.w * 100}%`,
+            top: `${slot.y / frame.canvas.h * 100}%`,
+            width: `${slot.w / frame.canvas.w * 100}%`,
+            height: `${slot.h / frame.canvas.h * 100}%`,
+          }}
+        />
+      ))}
+      {frame.overlay && <img src={frame.overlay} alt="" className={styles.overlayLayer} />}
+    </span>
+  );
+}
+
+function FrameCard({
+  frameKey,
+  enabled,
+  disabled,
+  onToggle,
+}: {
+  frameKey: string;
+  enabled: boolean;
+  disabled: boolean;
+  onToggle: (key: string) => void;
+}) {
+  const frame = TEMPLATES[frameKey];
+  return (
+    <label className={styles.frameCard} data-enabled={enabled} data-disabled={disabled}>
+      <input
+        type="checkbox"
+        checked={enabled}
+        disabled={disabled}
+        onChange={() => onToggle(frameKey)}
+      />
+      <FramePreview frame={frame} />
+      <span className={styles.frameMeta}>
+        <strong>{frame.label}</strong>
+        <small>{frame.shots} shot{frame.shots === 1 ? "" : "s"} / {frame.canvas.w}×{frame.canvas.h}</small>
+      </span>
+      <span className={styles.frameCheck}>{enabled ? "ON" : "OFF"}</span>
+    </label>
+  );
+}
+
+export function FrameProgrammeControls({
+  frames,
+  defaults,
+  disabled,
+  onToggle,
+  onSetGroup,
+}: FrameProgrammeControlsProps) {
+  return (
+    <div className={styles.frameGroups}>
+      <div className={styles.frameGroup}>
+        <div className={styles.groupHead}><h3>House frames</h3></div>
+        <div className={styles.filmRail}>
+          {defaults.map((key) => (
+            <FrameCard
+              key={key}
+              frameKey={key}
+              enabled={frames.has(key)}
+              disabled={disabled}
+              onToggle={onToggle}
+            />
+          ))}
+        </div>
+      </div>
+      {Object.entries(GROUPS).map(([group, label]) => {
+        const keys = Object.keys(TEMPLATES).filter((key) => TEMPLATES[key].group === group);
+        const allOn = keys.every((key) => frames.has(key));
+        return (
+          <div className={styles.frameGroup} key={group}>
+            <div className={styles.groupHead}>
+              <h3>{label}</h3>
+              <button
+                type="button"
+                onClick={() => onSetGroup(group, !allOn)}
+                disabled={disabled}
+              >
+                {allOn ? "Disable pack" : "Enable pack"}
+              </button>
+            </div>
+            <div className={styles.filmRail}>
+              {keys.map((key) => (
+                <FrameCard
+                  key={key}
+                  frameKey={key}
+                  enabled={frames.has(key)}
+                  disabled={disabled}
+                  onToggle={onToggle}
+                />
+              ))}
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+export function BoothKeyControls({
+  value,
+  saved,
+  copied,
+  disabled,
+  placeholder,
+  onChange,
+  onGenerate,
+  onCopy,
+  onClear,
+}: BoothKeyControlsProps) {
+  return (
+    <>
+      <div className={styles.keyRow}>
+        <input
+          aria-label="New booth key"
+          value={value}
+          onChange={(event) => onChange(event.target.value.trim())}
+          placeholder={placeholder}
+          autoComplete="off"
+          disabled={disabled}
+        />
+        <button type="button" onClick={onGenerate} disabled={disabled}>Generate</button>
+      </div>
+      {value && (
+        <button className={styles.copyWide} type="button" onClick={onCopy}>
+          {copied ? "Copied ✓" : "Copy generated key"}
+        </button>
+      )}
+      {value && saved && (
+        <button className={styles.clearKey} type="button" onClick={onClear} disabled={disabled}>
+          Stored safely — clear key
+        </button>
+      )}
+    </>
+  );
+}
+
+export function SaveConfigurationButton({
+  disabled,
+  saving,
+  onSave,
+}: {
+  disabled: boolean;
+  saving: boolean;
+  onSave: () => void;
+}) {
+  return (
+    <button
+      className={styles.saveButton}
+      type="button"
+      onClick={onSave}
+      disabled={disabled}
+    >
+      {saving ? "Saving event…" : "Save configuration"}
+    </button>
+  );
+}
diff --git a/app/[event]/admin/admin-styles.test.ts b/app/[event]/admin/admin-styles.test.ts
new file mode 100644
index 0000000..71fd6c5
--- /dev/null
+++ b/app/[event]/admin/admin-styles.test.ts
@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+
+function declarationBlock(css: string, selector: string): string {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return css.match(new RegExp(`${escaped}\\s*\\{([^}]+)\\}`))?.[1] ?? "";
+}
+
+test("configuration history is a horizontal square contact strip", async () => {
+  const css = await Bun.file(`${import.meta.dir}/admin.module.css`).text();
+  const rail = declarationBlock(css, ".revisionRail");
+  const record = declarationBlock(css, ".revisionRecord");
+
+  expect(rail).toContain("flex-direction: row");
+  expect(rail).toContain("overflow-x: auto");
+  expect(rail).toContain("background: var(--ink)");
+  expect(record).toContain("aspect-ratio: 1");
+  expect(record).toContain("flex:");
+});
diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index caf7a23..538b265 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -23,18 +23,17 @@
 .sectionHead { display: grid; grid-template-columns: 1fr minmax(200px, 340px); gap: 30px; padding-bottom: 14px; border-bottom: 2px solid var(--ink); align-items: end; }
 .sectionHead > div { display: flex; align-items: baseline; gap: 12px; }.sectionHead span { color: var(--pink); font: 900 13px/1 ui-monospace, monospace; }.sectionHead h2, .sideCard h2, .linkCard h2 { font: 900 clamp(26px, 3.5vw, 48px)/.9 Impact, "Arial Narrow", sans-serif; text-transform: uppercase; letter-spacing: -.02em; }.sectionHead p, .sideCard p { font-size: 13px; line-height: 1.4; }
 .frameGroups { display: flex; flex-direction: column; gap: 25px; padding-top: 20px; }.groupHead { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }.groupHead h3 { font: 900 14px/1 ui-monospace, monospace; text-transform: uppercase; }.filmRail { display: grid; grid-template-columns: repeat(auto-fill, minmax(145px, 1fr)); gap: 8px; }
-.frameCard { position: relative; display: flex; flex-direction: column; min-width: 0; padding: 8px; border: 2px solid #b7b2a8; background: #e3dfd5; cursor: pointer; }.frameCard[data-enabled="true"] { border-color: var(--ink); background: #fff; box-shadow: inset 0 -6px var(--pink); }.frameCard input { position: absolute; opacity: 0; }.frameCard:focus-within { outline: 4px solid var(--amber); outline-offset: 2px; }
+.frameCard { position: relative; display: flex; flex-direction: column; min-width: 0; padding: 8px; border: 2px solid #b7b2a8; background: #e3dfd5; cursor: pointer; }.frameCard[data-enabled="true"] { border-color: var(--ink); background: #fff; box-shadow: inset 0 -6px var(--pink); }.frameCard[data-disabled="true"] { cursor: wait; opacity: .62; }.frameCard input { position: absolute; opacity: 0; }.frameCard:focus-within { outline: 4px solid var(--amber); outline-offset: 2px; }
 .framePreview { position: relative; display: block; width: 100%; max-height: 220px; overflow: hidden; isolation: isolate; }.frameLayer, .overlayLayer { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: fill; }.frameLayer { z-index: 1; }.photoSlot { position: absolute; z-index: 2; background: linear-gradient(135deg, #53504d 0 35%, #d8d0c2 35% 55%, #79736d 55%); box-shadow: inset 0 0 0 1px rgba(255,255,255,.4); }.overlayLayer { z-index: 3; }.frameMeta { display: flex; flex-direction: column; gap: 3px; padding: 9px 0 5px; }.frameMeta strong { font: 900 14px/1 system-ui, sans-serif; }.frameMeta small { font: 10px/1.2 ui-monospace, monospace; color: #666159; }.frameCheck { position: absolute; z-index: 4; right: 12px; top: 12px; background: var(--ink); color: #fff; padding: 5px; font: 900 9px/1 ui-monospace, monospace; }
 .historySection { min-width: 0; }
 .historyLoading { margin-top: 15px; padding: 28px; color: var(--paper); background: var(--ink); font: 800 12px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; }
-.revisionRail { position: relative; display: flex; flex-direction: column; gap: 1px; margin-top: 15px; padding: 20px 12px; overflow: hidden; list-style: none; background: var(--ink); }
-.revisionRail::before, .revisionRail::after { content: ""; position: absolute; z-index: 2; right: 10px; left: 10px; height: 6px; background: repeating-linear-gradient(90deg, var(--paper) 0 12px, transparent 12px 22px); pointer-events: none; }
-.revisionRail::before { top: 6px; }.revisionRail::after { bottom: 6px; }
-.revisionRecord { position: relative; display: grid; grid-template-columns: 50px minmax(0, 1fr) minmax(150px, 220px); min-width: 0; background: var(--paper); }
+.revisionRail { position: relative; display: flex; flex-direction: row; gap: 8px; margin-top: 15px; padding: 22px 12px; overflow-x: auto; overflow-y: hidden; overscroll-behavior-inline: contain; list-style: none; background: var(--ink); background-image: repeating-linear-gradient(90deg, var(--paper) 0 12px, transparent 12px 22px), repeating-linear-gradient(90deg, var(--paper) 0 12px, transparent 12px 22px); background-position: top 6px left 12px, bottom 6px left 12px; background-repeat: repeat-x; background-size: auto 6px; scroll-padding-inline: 12px; scroll-snap-type: x proximity; scrollbar-color: var(--amber) var(--ink); -webkit-overflow-scrolling: touch; }
+.revisionRecord { position: relative; display: grid; flex: 0 0 clamp(260px, 34vw, 300px); grid-template-rows: 42px minmax(0, 1fr) minmax(54px, auto); grid-template-columns: minmax(0, 1fr); min-width: 0; aspect-ratio: 1; overflow: hidden; background: var(--paper); scroll-margin-inline: 12px; scroll-snap-align: start; }
 .revisionRecord[data-current="true"] { box-shadow: inset 5px 0 var(--green); }
-.revisionIndex { display: grid; place-items: center; border-right: 1px solid var(--ink); color: var(--paper); background: var(--ink); }
+.revisionRecord:focus-within { outline: 3px solid var(--amber); outline-offset: -3px; }
+.revisionIndex { display: grid; place-items: center; border-bottom: 1px solid var(--ink); color: var(--paper); background: var(--ink); }
 .revisionIndex span { font: 900 18px/1 Impact, "Arial Narrow", sans-serif; letter-spacing: .08em; }
-.revisionDetails { min-width: 0; padding: 13px 15px; }
+.revisionDetails { min-width: 0; min-height: 0; padding: 13px 15px; overflow: auto; }
 .revisionHeadline { display: flex; flex-wrap: wrap; align-items: center; gap: 7px 12px; }
 .revisionHeadline time { font: 800 12px/1 ui-monospace, monospace; }
 .revisionHeadline strong { font: 900 15px/1 "Arial Narrow", Arial, sans-serif; text-transform: uppercase; }
@@ -45,21 +44,21 @@
 .revisionDelta span[data-delta="added"] { color: var(--ink); background: var(--green); }
 .revisionDelta span[data-delta="removed"] { color: #fff; background: var(--pink); }
 .revisionDelta span[data-delta="same"] { color: var(--ink); background: var(--paper); }
-.revisionAction { display: flex; align-items: stretch; border-left: 1px solid var(--ink); }
-.restoreButton { width: 100%; border: 0; padding: 14px; color: var(--ink); background: var(--amber); font: 900 11px/1.15 system-ui, sans-serif; cursor: pointer; }
+.revisionAction { display: flex; min-height: 0; align-items: stretch; border-top: 1px solid var(--ink); }
+.restoreButton { width: 100%; min-height: 44px; border: 0; padding: 14px; color: var(--ink); background: var(--amber); font: 900 11px/1.15 system-ui, sans-serif; cursor: pointer; }
 .restoreButton:disabled { color: var(--ink); background: var(--green); cursor: default; opacity: 1; }
-.restoreConfirm { display: grid; grid-template-columns: 1fr 1fr; width: 100%; padding: 10px; gap: 7px; color: var(--paper); background: var(--ink); }
+.restoreConfirm { position: absolute; inset: 0; z-index: 3; display: grid; grid-template-columns: 1fr 1fr; width: 100%; padding: 18px; gap: 10px; color: var(--paper); background: var(--ink); }
 .restoreConfirm p { grid-column: 1 / -1; overflow-wrap: anywhere; font: 10px/1.35 ui-monospace, monospace; }
 .restoreConfirm button { border: 1px solid var(--paper); padding: 8px; color: var(--ink); background: var(--amber); font: 800 10px/1.2 system-ui, sans-serif; cursor: pointer; }
 .restoreConfirm button:last-child { color: var(--paper); background: var(--ink); }
 .restoreConfirm button:disabled { cursor: wait; opacity: .6; }
 .sideCard, .linkCard { border: 2px solid var(--ink); padding: 17px; background: #fff; }.sideCard .cardNumber { color: var(--pink); display: block; margin-bottom: 16px; }.sideCard h2 { font-size: 30px; margin-bottom: 10px; }.sideCard p { margin-bottom: 16px; }
-.keyRow { display: flex; }.keyRow input { min-width: 0; width: 100%; border: 1px solid var(--ink); padding: 11px; font: 12px/1 ui-monospace, monospace; }.keyRow button, .copyWide, .clearKey, .saveButton, .exportButton, .linkActions a, .linkActions button, .failure button { border: 1px solid var(--ink); color: var(--ink); background: var(--amber); padding: 10px 12px; font: 800 12px/1 system-ui, sans-serif; cursor: pointer; text-decoration: none; }.copyWide, .clearKey { margin-top: 7px; width: 100%; background: #fff; }.clearKey { border-style: dashed; color: #555; }
+.keyRow { display: flex; }.keyRow input { min-width: 0; width: 100%; border: 1px solid var(--ink); padding: 11px; font: 12px/1 ui-monospace, monospace; }.keyRow button, .copyWide, .clearKey, .saveButton, .exportButton, .linkActions a, .linkActions button, .failure button { border: 1px solid var(--ink); color: var(--ink); background: var(--amber); padding: 10px 12px; font: 800 12px/1 system-ui, sans-serif; cursor: pointer; text-decoration: none; }.groupHead button:disabled, .keyRow input:disabled, .keyRow button:disabled, .clearKey:disabled { cursor: wait; opacity: .55; }.copyWide, .clearKey { margin-top: 7px; width: 100%; background: #fff; }.clearKey { border-style: dashed; color: #555; }
 .linkCard { display: grid; grid-template-columns: minmax(0, 1fr) 94px; gap: 12px; background: var(--ink); color: #fff; }.linkCard > div > span { color: var(--amber); font: 800 9px/1 ui-monospace, monospace; text-transform: uppercase; }.linkCard h2 { font-size: 25px; margin: 6px 0 10px; }.linkCard code { display: block; color: #d3cec4; font: 10px/1.35 ui-monospace, monospace; word-break: break-all; }.linkCard img { width: 94px; height: 94px; background: #fff; padding: 5px; }.linkActions { display: flex; gap: 5px; margin-top: 12px; }.linkActions a, .linkActions button { flex: 1; padding: 8px; text-align: center; background: transparent; color: #fff; border-color: #777; }.saveButton, .exportButton { width: 100%; padding: 14px; background: var(--pink); color: #fff; border: 0; }.exportButton { margin-top: 8px; color: var(--ink); background: var(--amber); }.saveButton:disabled, .exportButton:disabled { opacity: .5; cursor: wait; }
 .contactSheet { display: grid; grid-template-columns: repeat(auto-fill, minmax(155px, 1fr)); gap: 8px; padding-top: 15px; }.contactPhoto { position: relative; min-width: 0; padding: 7px; background: #fff; border: 1px solid #b2aea5; }.contactPhoto > img { display: block; width: 100%; aspect-ratio: 1; object-fit: cover; background: #ccc; }.contactPhoto > div:not(.deleteConfirm) { display: flex; justify-content: space-between; gap: 8px; padding-top: 7px; }.contactPhoto time { font: 800 10px/1 ui-monospace, monospace; }.contactPhoto code { overflow: hidden; text-overflow: ellipsis; font: 9px/1 ui-monospace, monospace; color: #777; }.removePhoto { width: 100%; margin-top: 7px; border: 0; padding: 6px; background: transparent; color: #b3154a; font: 700 10px/1 system-ui, sans-serif; cursor: pointer; }.deleteConfirm { position: absolute; inset: 7px; z-index: 3; display: flex; flex-direction: column; justify-content: center; gap: 7px; padding: 12px; color: #fff; background: rgba(16,16,16,.96); }.deleteConfirm span { font: 800 12px/1.3 system-ui, sans-serif; }.deleteConfirm button { padding: 7px; border: 1px solid #777; color: #fff; background: transparent; cursor: pointer; }.deleteConfirm button:first-of-type { color: #fff; background: #c51651; border-color: #c51651; }
 .failure, .emptySheet { padding: 28px; margin-top: 15px; border: 2px dashed #8c8880; background: rgba(255,255,255,.5); }.failure strong, .emptySheet strong { font: 900 22px/1 Impact, sans-serif; text-transform: uppercase; }.failure p, .emptySheet p { margin: 8px 0 14px; font-size: 13px; }.failure button { background: var(--amber); }
 .authPage { display: grid; place-items: center; padding: 20px; background: var(--ink); color: #fff; }.authCard { width: min(500px, 100%); border-top: 8px solid var(--pink); padding: clamp(25px, 5vw, 55px); background: #1a1a19; }.authCard h1 { margin: 25px 0; font: 900 clamp(58px, 10vw, 90px)/.78 Impact, sans-serif; text-transform: uppercase; }.authCard > p:not(.kicker) { color: #bbb; line-height: 1.4; margin-bottom: 28px; }.authCard label { display: block; margin-bottom: 8px; font: 800 11px/1 ui-monospace, monospace; text-transform: uppercase; }.authCard input { width: 100%; padding: 14px; border: 1px solid #777; background: #080808; color: #fff; font: 16px/1 ui-monospace, monospace; }.authCard button { width: 100%; margin-top: 10px; padding: 15px; border: 0; color: #fff; background: var(--pink); font-weight: 900; cursor: pointer; }
 .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
 @media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; } }
-@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; }.revisionRecord { grid-template-columns: 40px minmax(0, 1fr); }.revisionAction { grid-column: 2; border-top: 1px solid var(--ink); border-left: 0; }.restoreButton { min-height: 44px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; } }
+@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; } }
 @media (prefers-reduced-motion: reduce) { .console *, .console *::before, .console *::after, .authPage *, .authPage *::before, .authPage *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; } }
diff --git a/app/[event]/admin/config-history-panel.test.tsx b/app/[event]/admin/config-history-panel.test.tsx
index c726616..bd9cf6c 100644
--- a/app/[event]/admin/config-history-panel.test.tsx
+++ b/app/[event]/admin/config-history-panel.test.tsx
@@ -24,6 +24,7 @@ test("history renders reasons and disables restoring the current revision", () =
       }]}
       loading={false}
       restoringRevisionId={null}
+      mutationBusy={false}
       error=""
       onReload={() => {}}
       onRestore={() => {}}
@@ -36,3 +37,60 @@ test("history renders reasons and disables restoring the current revision", () =
   expect(html).toContain("disabled");
   expect(html).not.toContain("boothKey");
 });
+
+const revisions = [
+  {
+    version: 1 as const,
+    id: "018f0000-0000-7000-8000-000000000030",
+    createdAt: "2026-07-24T00:00:00.000Z",
+    parentRevisionId: "018f0000-0000-7000-8000-000000000029",
+    reason: "save" as const,
+    config: { frames: ["one"] },
+  },
+  {
+    version: 1 as const,
+    id: "018f0000-0000-7000-8000-000000000029",
+    createdAt: "2026-07-23T23:00:00.000Z",
+    parentRevisionId: null,
+    reason: "baseline" as const,
+    config: { frames: ["two"] },
+  },
+];
+
+test("the active restore control says exactly Restoring after confirmation closes", () => {
+  const html = renderToStaticMarkup(
+    <ConfigHistoryPanel
+      currentFrames={["one"]}
+      currentRevisionId={revisions[0].id}
+      revisions={revisions}
+      loading={false}
+      restoringRevisionId={revisions[1].id}
+      mutationBusy
+      error=""
+      onReload={() => {}}
+      onRestore={() => {}}
+    />
+  );
+
+  const buttonLabels = [...html.matchAll(/<button[^>]*>([^<]*)<\/button>/g)]
+    .map((match) => match[1]);
+  expect(buttonLabels).toContain("Restoring…");
+});
+
+test("saving disables every restore control", () => {
+  const html = renderToStaticMarkup(
+    <ConfigHistoryPanel
+      currentFrames={["one"]}
+      currentRevisionId={revisions[0].id}
+      revisions={revisions}
+      loading={false}
+      restoringRevisionId={null}
+      mutationBusy
+      error=""
+      onReload={() => {}}
+      onRestore={() => {}}
+    />
+  );
+
+  expect((html.match(/disabled=""/g) ?? []).length).toBe(2);
+});
diff --git a/app/[event]/admin/config-history-panel.tsx b/app/[event]/admin/config-history-panel.tsx
index e98376f..7708ad9 100644
--- a/app/[event]/admin/config-history-panel.tsx
+++ b/app/[event]/admin/config-history-panel.tsx
@@ -10,6 +10,7 @@ export type ConfigHistoryPanelProps = {
   revisions: readonly ConfigRevision[];
   loading: boolean;
   restoringRevisionId: string | null;
+  mutationBusy: boolean;
   error: string;
   onReload: () => void;
   onRestore: (revisionId: string) => void;
@@ -38,6 +39,7 @@ export function ConfigHistoryPanel({
   revisions,
   loading,
   restoringRevisionId,
+  mutationBusy,
   error,
   onReload,
   onRestore,
@@ -105,14 +107,15 @@ export function ConfigHistoryPanel({
                       <button
                         type="button"
                         onClick={() => {
+                          if (mutationBusy) return;
                           setConfirmRevisionId(null);
                           onRestore(revision.id);
                         }}
-                        disabled={isRestoring}
+                        disabled={mutationBusy}
                       >
                         {isRestoring ? "Restoring…" : "Confirm exact restore"}
                       </button>
-                      <button type="button" onClick={() => setConfirmRevisionId(null)} disabled={isRestoring}>
+                      <button type="button" onClick={() => setConfirmRevisionId(null)}>
                         Keep current
                       </button>
                     </div>
@@ -120,10 +123,13 @@ export function ConfigHistoryPanel({
                     <button
                       type="button"
                       className={styles.restoreButton}
-                      onClick={() => setConfirmRevisionId(revision.id)}
-                      disabled={isCurrent || restoringRevisionId !== null}
+                      onClick={() => {
+                        if (mutationBusy) return;
+                        setConfirmRevisionId(revision.id);
+                      }}
+                      disabled={isCurrent || mutationBusy}
                     >
-                      {isCurrent ? "Current" : "Restore this version"}
+                      {isCurrent ? "Current" : isRestoring ? "Restoring…" : "Restore this version"}
                     </button>
                   )}
                 </div>
diff --git a/app/[event]/admin/config-mutation.test.ts b/app/[event]/admin/config-mutation.test.ts
new file mode 100644
index 0000000..c92735e
--- /dev/null
+++ b/app/[event]/admin/config-mutation.test.ts
@@ -0,0 +1,66 @@
+import { expect, test } from "bun:test";
+import {
+  getOrCreateRestoreRequest,
+  shouldClearRestoreRequest,
+  type RestoreRequest,
+} from "./config-mutation";
+
+const SOURCE_REVISION = "018f0000-0000-7000-8000-000000000030";
+const FIRST_BASE = "018f0000-0000-7000-8000-000000000031";
+const LATER_BASE = "018f0000-0000-7000-8000-000000000032";
+const MUTATION_ID = "018f0000-0000-7000-8000-000000000033";
+const NEXT_MUTATION_ID = "018f0000-0000-7000-8000-000000000034";
+
+test("restore retries retain the complete immutable request when the editor base changes", () => {
+  const pending = new Map<string, RestoreRequest>();
+  let generated = 0;
+  const createMutationId = () => {
+    generated += 1;
+    return MUTATION_ID;
+  };
+
+  const first = getOrCreateRestoreRequest(
+    pending,
+    SOURCE_REVISION,
+    FIRST_BASE,
+    createMutationId
+  );
+  const retry = getOrCreateRestoreRequest(
+    pending,
+    SOURCE_REVISION,
+    LATER_BASE,
+    createMutationId
+  );
+
+  expect(first).toEqual({
+    revisionId: SOURCE_REVISION,
+    mutationId: MUTATION_ID,
+    baseRevisionId: FIRST_BASE,
+  });
+  expect(retry).toBe(first);
+  expect(Object.isFrozen(retry)).toBe(true);
+  expect(generated).toBe(1);
+
+  pending.delete(SOURCE_REVISION);
+  const nextIntent = getOrCreateRestoreRequest(
+    pending,
+    SOURCE_REVISION,
+    LATER_BASE,
+    () => NEXT_MUTATION_ID
+  );
+  expect(nextIntent).toEqual({
+    revisionId: SOURCE_REVISION,
+    mutationId: NEXT_MUTATION_ID,
+    baseRevisionId: LATER_BASE,
+  });
+  expect(nextIntent).not.toBe(first);
+});
+
+test("only definitive restore responses clear a retained request", () => {
+  for (const status of [400, 401, 404, 409, 200]) {
+    expect(shouldClearRestoreRequest(status)).toBe(true);
+  }
+  for (const status of [0, 408, 425, 429, 500, 503]) {
+    expect(shouldClearRestoreRequest(status)).toBe(false);
+  }
+});
diff --git a/app/[event]/admin/config-mutation.ts b/app/[event]/admin/config-mutation.ts
new file mode 100644
index 0000000..1cb0996
--- /dev/null
+++ b/app/[event]/admin/config-mutation.ts
@@ -0,0 +1,27 @@
+export type RestoreRequest = Readonly<{
+  revisionId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+}>;
+
+export function getOrCreateRestoreRequest(
+  pending: Map<string, RestoreRequest>,
+  revisionId: string,
+  baseRevisionId: string | null,
+  createMutationId: () => string
+): RestoreRequest {
+  const retained = pending.get(revisionId);
+  if (retained) return retained;
+
+  const request = Object.freeze({
+    revisionId,
+    mutationId: createMutationId(),
+    baseRevisionId,
+  });
+  pending.set(revisionId, request);
+  return request;
+}
+
+export function shouldClearRestoreRequest(status: number): boolean {
+  return (status >= 200 && status < 300) || [400, 401, 404, 409].includes(status);
+}
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index f436b88..550c7bd 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -3,10 +3,19 @@
 import { FormEvent, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useParams } from "next/navigation";
 import QRCode from "qrcode";
-import { GROUPS, TEMPLATES } from "../../templates";
+import { TEMPLATES } from "../../templates";
 import type { ConfigRevision, PublicEventConfig } from "../../event-config";
-import type { Template } from "../../frame-packs/types";
+import {
+  BoothKeyControls,
+  FrameProgrammeControls,
+  SaveConfigurationButton,
+} from "./admin-config-controls";
 import { ConfigHistoryPanel } from "./config-history-panel";
+import {
+  getOrCreateRestoreRequest,
+  shouldClearRestoreRequest,
+  type RestoreRequest,
+} from "./config-mutation";
 import styles from "./admin.module.css";
 
 type Photo = { key: string; url: string; uploadedAt: string };
@@ -21,27 +30,6 @@ type ConfigHistoryResponse = {
 type FilePickerWindow = Window & { showSaveFilePicker?: (options: { suggestedName: string; types: { description: string; accept: Record<string, string[]> }[] }) => Promise<{ createWritable(): Promise<WritableStream<Uint8Array>> }> };
 const CONFIG_CONFLICT_MESSAGE = "Configuration changed; review the latest version before saving.";
 
-function FramePreview({ frame }: { frame: Template }) {
-  return (
-    <span className={styles.framePreview} style={{ aspectRatio: `${frame.canvas.w}/${frame.canvas.h}`, backgroundColor: frame.background || "#d8d5cc" }}>
-      {frame.bgImage && <img src={frame.bgImage} alt="" className={styles.frameLayer} />}
-      {frame.slots.map((slot, index) => (
-        <span
-          key={index}
-          className={styles.photoSlot}
-          style={{
-            left: `${slot.x / frame.canvas.w * 100}%`,
-            top: `${slot.y / frame.canvas.h * 100}%`,
-            width: `${slot.w / frame.canvas.w * 100}%`,
-            height: `${slot.h / frame.canvas.h * 100}%`,
-          }}
-        />
-      ))}
-      {frame.overlay && <img src={frame.overlay} alt="" className={styles.overlayLayer} />}
-    </span>
-  );
-}
-
 export default function Admin() {
   const { event } = useParams<{ event: string }>();
   const [adminKey, setAdminKey] = useState("");
@@ -71,12 +59,14 @@ export default function Admin() {
   const [health, setHealth] = useState<Health | null>(null);
   const [checkingHealth, setCheckingHealth] = useState(false);
   const photoCursor = useRef<string | null>(null);
+  const configMutationBusy = useRef(false);
   const pendingSaveMutationId = useRef<string | null>(null);
-  const pendingRestoreMutationIds = useRef(new Map<string, string>());
+  const pendingRestoreRequests = useRef(new Map<string, RestoreRequest>());
 
   const boothUrl = `${origin}/${event}`;
   const liveUrl = `${boothUrl}/live`;
   const defaults = useMemo(() => Object.keys(TEMPLATES).filter((key) => !TEMPLATES[key].group), []);
+  const configBusy = saving || restoringRevisionId !== null;
   const clearPendingSave = () => {
     pendingSaveMutationId.current = null;
     setError((current) => current === CONFIG_CONFLICT_MESSAGE ? "" : current);
@@ -197,6 +187,7 @@ export default function Admin() {
   };
 
   const toggle = (key: string) => {
+    if (configMutationBusy.current) return;
     clearPendingSave();
     setFrames((current) => {
       const next = new Set(current);
@@ -207,6 +198,7 @@ export default function Admin() {
   };
 
   const setGroup = (group: string, enabled: boolean) => {
+    if (configMutationBusy.current) return;
     clearPendingSave();
     const keys = Object.keys(TEMPLATES).filter((key) => TEMPLATES[key].group === group);
     setFrames((current) => {
@@ -217,6 +209,7 @@ export default function Admin() {
   };
 
   const generateBoothKey = () => {
+    if (configMutationBusy.current) return;
     clearPendingSave();
     const bytes = crypto.getRandomValues(new Uint8Array(12));
     setBoothKey(Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""));
@@ -224,6 +217,21 @@ export default function Admin() {
     setNotice("New key generated. Copy it now, then save the event.");
   };
 
+  const changeBoothKey = (value: string) => {
+    if (configMutationBusy.current) return;
+    clearPendingSave();
+    setBoothKey(value);
+    setBoothKeySaved(false);
+  };
+
+  const clearBoothKey = () => {
+    if (configMutationBusy.current) return;
+    clearPendingSave();
+    setBoothKey("");
+    setBoothKeySaved(false);
+    setCopied("");
+  };
+
   const copy = async (value: string, label: string) => {
     try {
       await navigator.clipboard.writeText(value);
@@ -235,11 +243,12 @@ export default function Admin() {
   };
 
   const save = async () => {
-    if (!configLoaded) return;
+    if (!configLoaded || configMutationBusy.current) return;
     if (boothKey && boothKey.length < 12) {
       setError("Booth keys need at least 12 characters.");
       return;
     }
+    configMutationBusy.current = true;
     setSaving(true); setError(""); setNotice("");
     const mutationId = pendingSaveMutationId.current ?? crypto.randomUUID();
     pendingSaveMutationId.current = mutationId;
@@ -270,14 +279,22 @@ export default function Admin() {
       setNotice(boothKey ? "Event saved. Keep the new booth key somewhere secure." : "Event configuration saved.");
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : "Event could not be saved");
-    } finally { setSaving(false); }
+    } finally {
+      configMutationBusy.current = false;
+      setSaving(false);
+    }
   };
 
   const restoreRevision = async (revisionId: string) => {
-    if (!configLoaded) return;
-    const pending = pendingRestoreMutationIds.current;
-    const mutationId = pending.get(revisionId) ?? crypto.randomUUID();
-    pending.set(revisionId, mutationId);
+    if (!configLoaded || configMutationBusy.current) return;
+    configMutationBusy.current = true;
+    const pending = pendingRestoreRequests.current;
+    const request = getOrCreateRestoreRequest(
+      pending,
+      revisionId,
+      currentRevisionId,
+      () => crypto.randomUUID()
+    );
     setRestoringRevisionId(revisionId);
     setError("");
     setNotice("");
@@ -285,13 +302,9 @@ export default function Admin() {
       const response = await fetch(`/api/config/revisions/restore?event=${encodeURIComponent(event)}`, {
         method: "POST",
         headers: { "x-booth-key": adminKey, "content-type": "application/json" },
-        body: JSON.stringify({
-          revisionId,
-          mutationId,
-          baseRevisionId: currentRevisionId,
-        }),
+        body: JSON.stringify(request),
       });
-      if ([400, 401, 404, 409].includes(response.status)) pending.delete(revisionId);
+      if (shouldClearRestoreRequest(response.status)) pending.delete(revisionId);
       if (response.status === 401) { invalidateAuth(); throw new Error("That admin key was rejected."); }
       if (response.status === 409) {
         await loadConfig();
@@ -300,7 +313,6 @@ export default function Admin() {
       }
       if (!response.ok) throw new Error(`Restore failed (${response.status})`);
       const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
-      pending.delete(revisionId);
       pendingSaveMutationId.current = null;
       setFrames(new Set(Array.isArray(data.frames) ? data.frames : defaults));
       setHasBoothKey(Boolean(data.hasBoothKey));
@@ -313,6 +325,7 @@ export default function Admin() {
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : "Configuration could not be restored");
     } finally {
+      configMutationBusy.current = false;
       setRestoringRevisionId(null);
     }
   };
@@ -405,20 +418,13 @@ export default function Admin() {
           <section className={styles.section}>
             <div className={styles.sectionHead}><div><span>01</span><h2>Frame programme</h2></div><p>Choose what guests see at the booth. Previews follow the real background → photo → overlay composition.</p></div>
             {configError ? <div className={styles.failure}><strong>Config unavailable</strong><p>{configError}</p><button onClick={() => void loadConfig()}>Retry config</button></div> :
-            <div className={styles.frameGroups}>
-              <div className={styles.frameGroup}>
-                <div className={styles.groupHead}><h3>House frames</h3></div>
-                <div className={styles.filmRail}>{defaults.map((key) => <FrameCard key={key} frameKey={key} enabled={frames.has(key)} toggle={toggle} />)}</div>
-              </div>
-              {Object.entries(GROUPS).map(([group, label]) => {
-                const keys = Object.keys(TEMPLATES).filter((key) => TEMPLATES[key].group === group);
-                const allOn = keys.every((key) => frames.has(key));
-                return <div className={styles.frameGroup} key={group}>
-                  <div className={styles.groupHead}><h3>{label}</h3><button onClick={() => setGroup(group, !allOn)}>{allOn ? "Disable pack" : "Enable pack"}</button></div>
-                  <div className={styles.filmRail}>{keys.map((key) => <FrameCard key={key} frameKey={key} enabled={frames.has(key)} toggle={toggle} />)}</div>
-                </div>;
-              })}
-            </div>}
+            <FrameProgrammeControls
+              frames={frames}
+              defaults={defaults}
+              disabled={configBusy}
+              onToggle={toggle}
+              onSetGroup={setGroup}
+            />}
           </section>
 
           <ConfigHistoryPanel
@@ -427,6 +433,7 @@ export default function Admin() {
             revisions={revisions}
             loading={!configLoaded && !configError}
             restoringRevisionId={restoringRevisionId}
+            mutationBusy={configBusy}
             error={configError}
             onReload={() => void loadConfig()}
             onRestore={(revisionId) => void restoreRevision(revisionId)}
@@ -448,9 +455,17 @@ export default function Admin() {
           <section className={styles.sideCard}>
             <span className={styles.cardNumber}>04</span><h2>Booth credential</h2>
             <p>{hasBoothKey ? "A booth key is installed. Generate a replacement only when rotating iPad access." : "No booth key yet. Generate one before the booth can upload."}</p>
-            <div className={styles.keyRow}><input aria-label="New booth key" value={boothKey} onChange={(e) => { clearPendingSave(); setBoothKey(e.target.value.trim()); setBoothKeySaved(false); }} placeholder={hasBoothKey ? "Unchanged" : "Generate a key"} autoComplete="off" /><button onClick={generateBoothKey}>Generate</button></div>
-            {boothKey && <button className={styles.copyWide} onClick={() => void copy(boothKey, "key")}>{copied === "key" ? "Copied ✓" : "Copy generated key"}</button>}
-            {boothKey && boothKeySaved && <button className={styles.clearKey} onClick={() => { clearPendingSave(); setBoothKey(""); setBoothKeySaved(false); setCopied(""); }}>Stored safely — clear key</button>}
+            <BoothKeyControls
+              value={boothKey}
+              saved={boothKeySaved}
+              copied={copied === "key"}
+              disabled={configBusy}
+              placeholder={hasBoothKey ? "Unchanged" : "Generate a key"}
+              onChange={changeBoothKey}
+              onGenerate={generateBoothKey}
+              onCopy={() => void copy(boothKey, "key")}
+              onClear={clearBoothKey}
+            />
           </section>
 
           <LinkCard label="Booth / iPad" url={boothUrl} qr={boothQr} copied={copied === "booth"} copy={() => void copy(boothUrl, "booth")} />
@@ -458,7 +473,11 @@ export default function Admin() {
 
           <section className={styles.sideCard}>
             <span className={styles.cardNumber}>06</span><h2>Ship the event</h2>
-            <button className={styles.saveButton} onClick={() => void save()} disabled={!configLoaded || saving}>{saving ? "Saving event…" : "Save configuration"}</button>
+            <SaveConfigurationButton
+              disabled={!configLoaded || configBusy}
+              saving={saving}
+              onSave={() => void save()}
+            />
             <button className={styles.exportButton} onClick={() => void exportZip()} disabled={exporting}>{exporting ? "Building archive…" : `Export ${photos.length} photos (.zip)`}</button>
           </section>
         </aside>
@@ -467,16 +486,6 @@ export default function Admin() {
   );
 }
 
-function FrameCard({ frameKey, enabled, toggle }: { frameKey: string; enabled: boolean; toggle: (key: string) => void }) {
-  const frame = TEMPLATES[frameKey];
-  return <label className={styles.frameCard} data-enabled={enabled}>
-    <input type="checkbox" checked={enabled} onChange={() => toggle(frameKey)} />
-    <FramePreview frame={frame} />
-    <span className={styles.frameMeta}><strong>{frame.label}</strong><small>{frame.shots} shot{frame.shots === 1 ? "" : "s"} / {frame.canvas.w}×{frame.canvas.h}</small></span>
-    <span className={styles.frameCheck}>{enabled ? "ON" : "OFF"}</span>
-  </label>;
-}
-
 function LinkCard({ label, url, qr, copied, copy }: { label: string; url: string; qr: string; copied: boolean; copy: () => void }) {
   return <section className={styles.linkCard}>
     <div><span>Event route</span><h2>{label}</h2><code>{url || "Building URL…"}</code><div className={styles.linkActions}><a href={url}>Open ↗</a><button onClick={copy}>{copied ? "Copied ✓" : "Copy URL"}</button></div></div>

From 6288a45567bed88226b739010d262231b7e3f960 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 14:51:40 +0800
Subject: [PATCH 018/105] fix: reconcile admin mutation retries

---
 app/[event]/admin/config-mutation.test.ts | 49 +++++++++++++++++++++--
 app/[event]/admin/config-mutation.ts      | 38 +++++++++++++++++-
 app/[event]/admin/page.tsx                | 40 +++++++++---------
 3 files changed, 105 insertions(+), 22 deletions(-)

diff --git a/app/[event]/admin/config-mutation.test.ts b/app/[event]/admin/config-mutation.test.ts
index c92735e..700ad31 100644
--- a/app/[event]/admin/config-mutation.test.ts
+++ b/app/[event]/admin/config-mutation.test.ts
@@ -1,6 +1,8 @@
 import { expect, test } from "bun:test";
 import {
+  clearRestoreRequestAfterReconciliation,
   getOrCreateRestoreRequest,
+  rebaseConfigHistory,
   shouldClearRestoreRequest,
   type RestoreRequest,
 } from "./config-mutation";
@@ -56,11 +58,52 @@ test("restore retries retain the complete immutable request when the editor base
   expect(nextIntent).not.toBe(first);
 });
 
-test("only definitive restore responses clear a retained request", () => {
-  for (const status of [400, 401, 404, 409, 200]) {
+test("only definitive restore failures clear a retained request before reconciliation", () => {
+  for (const status of [400, 401, 404, 409]) {
     expect(shouldClearRestoreRequest(status)).toBe(true);
   }
-  for (const status of [0, 408, 425, 429, 500, 503]) {
+  for (const status of [0, 200, 204, 408, 425, 429, 500, 503]) {
     expect(shouldClearRestoreRequest(status)).toBe(false);
   }
 });
+
+test("a successful history rebase clears an ambiguous Save mutation ID", () => {
+  const pendingSave = { current: MUTATION_ID as string | null };
+
+  const rebased = rebaseConfigHistory(
+    {
+      config: { frames: ["one"], hasBoothKey: true },
+      currentRevisionId: LATER_BASE,
+      revisions: [],
+    },
+    ["fallback"],
+    pendingSave
+  );
+
+  expect(rebased.frames).toEqual(["one"]);
+  expect(rebased.hasBoothKey).toBe(true);
+  expect(rebased.currentRevisionId).toBe(LATER_BASE);
+  expect(pendingSave.current).toBeNull();
+});
+
+test("a 2xx restore retains its exact tuple until parsing, apply, and history reload finish", async () => {
+  const pending = new Map<string, RestoreRequest>();
+  const request = getOrCreateRestoreRequest(
+    pending,
+    SOURCE_REVISION,
+    FIRST_BASE,
+    () => MUTATION_ID
+  );
+
+  for (const failedStep of ["response JSON", "response apply", "history reload"]) {
+    await expect(
+      clearRestoreRequestAfterReconciliation(pending, request, async () => {
+        throw new Error(`${failedStep} failed`);
+      })
+    ).rejects.toThrow(`${failedStep} failed`);
+    expect(pending.get(SOURCE_REVISION)).toBe(request);
+  }
+
+  await clearRestoreRequestAfterReconciliation(pending, request, async () => {});
+  expect(pending.has(SOURCE_REVISION)).toBe(false);
+});
diff --git a/app/[event]/admin/config-mutation.ts b/app/[event]/admin/config-mutation.ts
index 1cb0996..aaee785 100644
--- a/app/[event]/admin/config-mutation.ts
+++ b/app/[event]/admin/config-mutation.ts
@@ -1,9 +1,34 @@
+import type { ConfigRevision, PublicEventConfig } from "../../event-config";
+
 export type RestoreRequest = Readonly<{
   revisionId: string;
   mutationId: string;
   baseRevisionId: string | null;
 }>;
 
+export type ConfigHistoryResponse = {
+  config: PublicEventConfig;
+  currentRevisionId: string | null;
+  revisions: ConfigRevision[];
+};
+
+export function rebaseConfigHistory(
+  history: ConfigHistoryResponse,
+  defaultFrames: readonly string[],
+  pendingSaveMutationId: { current: string | null }
+) {
+  const rebased = {
+    frames: Array.isArray(history.config.frames)
+      ? [...history.config.frames]
+      : [...defaultFrames],
+    hasBoothKey: Boolean(history.config.hasBoothKey),
+    currentRevisionId: history.currentRevisionId,
+    revisions: history.revisions,
+  };
+  pendingSaveMutationId.current = null;
+  return rebased;
+}
+
 export function getOrCreateRestoreRequest(
   pending: Map<string, RestoreRequest>,
   revisionId: string,
@@ -23,5 +48,16 @@ export function getOrCreateRestoreRequest(
 }
 
 export function shouldClearRestoreRequest(status: number): boolean {
-  return (status >= 200 && status < 300) || [400, 401, 404, 409].includes(status);
+  return [400, 401, 404, 409].includes(status);
+}
+
+export async function clearRestoreRequestAfterReconciliation(
+  pending: Map<string, RestoreRequest>,
+  request: RestoreRequest,
+  reconcile: () => Promise<void>
+): Promise<void> {
+  await reconcile();
+  if (pending.get(request.revisionId) === request) {
+    pending.delete(request.revisionId);
+  }
 }
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index 550c7bd..bc69058 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -12,8 +12,11 @@ import {
 } from "./admin-config-controls";
 import { ConfigHistoryPanel } from "./config-history-panel";
 import {
+  clearRestoreRequestAfterReconciliation,
   getOrCreateRestoreRequest,
+  rebaseConfigHistory,
   shouldClearRestoreRequest,
+  type ConfigHistoryResponse,
   type RestoreRequest,
 } from "./config-mutation";
 import styles from "./admin.module.css";
@@ -22,11 +25,6 @@ type Photo = { key: string; url: string; uploadedAt: string };
 type AuthState = "missing" | "ready" | "invalid";
 type Probe = { status: "up" | "degraded" | "down"; detail: string };
 type Health = { upload: Probe; live: Probe };
-type ConfigHistoryResponse = {
-  config: PublicEventConfig;
-  currentRevisionId: string | null;
-  revisions: ConfigRevision[];
-};
 type FilePickerWindow = Window & { showSaveFilePicker?: (options: { suggestedName: string; types: { description: string; accept: Record<string, string[]> }[] }) => Promise<{ createWritable(): Promise<WritableStream<Uint8Array>> }> };
 const CONFIG_CONFLICT_MESSAGE = "Configuration changed; review the latest version before saving.";
 
@@ -126,13 +124,16 @@ export default function Admin() {
       ) {
         throw new Error("Configuration history had an unexpected shape");
       }
-      setFrames(new Set(Array.isArray(data.config.frames) ? data.config.frames : defaults));
-      setHasBoothKey(Boolean(data.config.hasBoothKey));
-      setCurrentRevisionId(data.currentRevisionId);
-      setRevisions(data.revisions);
+      const rebased = rebaseConfigHistory(data, defaults, pendingSaveMutationId);
+      setFrames(new Set(rebased.frames));
+      setHasBoothKey(rebased.hasBoothKey);
+      setCurrentRevisionId(rebased.currentRevisionId);
+      setRevisions(rebased.revisions);
       setConfigLoaded(true);
+      return true;
     } catch (cause) {
       setConfigError(cause instanceof Error ? cause.message : "Config could not be loaded");
+      return false;
     }
   }, [adminKey, defaults, event]);
 
@@ -312,15 +313,18 @@ export default function Admin() {
         return;
       }
       if (!response.ok) throw new Error(`Restore failed (${response.status})`);
-      const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
-      pendingSaveMutationId.current = null;
-      setFrames(new Set(Array.isArray(data.frames) ? data.frames : defaults));
-      setHasBoothKey(Boolean(data.hasBoothKey));
-      setCurrentRevisionId(data.currentRevisionId);
-      setBoothKey("");
-      setBoothKeySaved(false);
-      setCopied((current) => current === "key" ? "" : current);
-      await loadConfig();
+      await clearRestoreRequestAfterReconciliation(pending, request, async () => {
+        const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
+        setFrames(new Set(Array.isArray(data.frames) ? data.frames : defaults));
+        setHasBoothKey(Boolean(data.hasBoothKey));
+        setCurrentRevisionId(data.currentRevisionId);
+        setBoothKey("");
+        setBoothKeySaved(false);
+        setCopied((current) => current === "key" ? "" : current);
+        if (!await loadConfig()) {
+          throw new Error("Configuration restored, but history could not be reloaded.");
+        }
+      });
       setNotice("Configuration restored.");
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : "Configuration could not be restored");

From 5feafd998af5aa3db74d73b1d69ebcb7046cd249 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 14:57:22 +0800
Subject: [PATCH 019/105] feat: define stable capture upload contract

---
 app/upload-contract.test.ts | 87 +++++++++++++++++++++++++++++++++
 app/upload-contract.ts      | 97 +++++++++++++++++++++++++++++++++++++
 2 files changed, 184 insertions(+)
 create mode 100644 app/upload-contract.test.ts
 create mode 100644 app/upload-contract.ts

diff --git a/app/upload-contract.test.ts b/app/upload-contract.test.ts
new file mode 100644
index 0000000..713d892
--- /dev/null
+++ b/app/upload-contract.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import {
+  InvalidUploadHeadersError,
+  parseUploadHeaders,
+  stableUploadHeaders,
+} from "./upload-contract";
+
+const headers = (values: Record<string, string>) => new Headers(values);
+
+const identity = {
+  "x-capture-id": "018f0000-0000-4000-8000-000000000001",
+  "x-captured-at": "1753315200000",
+};
+
+describe("stable upload headers", () => {
+  test("all stable fields round-trip exactly", () => {
+    const stable = {
+      captureId: "018f0000-0000-4000-8000-000000000001",
+      capturedAt: 1753315200000,
+      source: "framed" as const,
+      frameKey: "square",
+      configRevisionId: "018f0000-0000-7000-8000-000000000002",
+    };
+
+    expect(stableUploadHeaders(stable)).toEqual({
+      "x-capture-id": "018f0000-0000-4000-8000-000000000001",
+      "x-captured-at": "1753315200000",
+      "x-capture-source": "framed",
+      "x-frame-key": "square",
+      "x-config-revision-id": "018f0000-0000-7000-8000-000000000002",
+    });
+    expect(parseUploadHeaders(headers(stableUploadHeaders(stable)))).toEqual({ kind: "stable", ...stable });
+  });
+
+  test("no new headers is the legacy contract", () => {
+    expect(parseUploadHeaders(headers({ "content-type": "image/jpeg" }))).toEqual({ kind: "legacy" });
+  });
+
+  test("rejects partial capture identity", () => {
+    expect(() => parseUploadHeaders(headers({ "x-capture-id": identity["x-capture-id"] })))
+      .toThrow(InvalidUploadHeadersError);
+    expect(() => parseUploadHeaders(headers({ "x-captured-at": identity["x-captured-at"] })))
+      .toThrow(InvalidUploadHeadersError);
+  });
+
+  test("rejects metadata without capture identity", () => {
+    expect(() => parseUploadHeaders(headers({ "x-capture-source": "framed" })))
+      .toThrow(InvalidUploadHeadersError);
+  });
+
+  test("rejects non-lowercase UUID-v4 capture IDs", () => {
+    for (const captureId of [
+      "018F0000-0000-4000-8000-000000000001",
+      "018f0000-0000-1000-8000-000000000001",
+      "018f0000-0000-4000-c000-000000000001",
+      "../photo",
+    ]) {
+      expect(() => parseUploadHeaders(headers({ ...identity, "x-capture-id": captureId }))).toThrow(InvalidUploadHeadersError);
+    }
+  });
+
+  test("rejects malformed timestamp, source, and bounded tokens", () => {
+    for (const invalid of [
+      { ...identity, "x-captured-at": "1e12" },
+      { ...identity, "x-captured-at": "175331520000" },
+      { ...identity, "x-capture-source": "video" },
+      { ...identity, "x-frame-key": "../frame" },
+      { ...identity, "x-config-revision-id": "-revision" },
+      { ...identity, "x-frame-key": "a".repeat(129) },
+    ]) {
+      expect(() => parseUploadHeaders(headers(invalid))).toThrow(InvalidUploadHeadersError);
+    }
+  });
+
+  test("accepts optional metadata and ignores unknown headers", () => {
+    expect(parseUploadHeaders(headers({
+      ...identity,
+      "x-capture-source": "camera-fallback",
+      "x-unknown": "ignored",
+    }))).toEqual({
+      kind: "stable",
+      captureId: identity["x-capture-id"],
+      capturedAt: 1753315200000,
+      source: "camera-fallback",
+    });
+  });
+});
diff --git a/app/upload-contract.ts b/app/upload-contract.ts
new file mode 100644
index 0000000..5217bf9
--- /dev/null
+++ b/app/upload-contract.ts
@@ -0,0 +1,97 @@
+export type CaptureSource = "framed" | "camera-fallback";
+
+export type CaptureMetadata = {
+  frameKey?: string;
+  capturedAt: number;
+  source: CaptureSource;
+  configRevisionId?: string;
+};
+
+export type StableCaptureIdentity = {
+  captureId: string;
+  capturedAt: number;
+};
+
+export type StableUpload = StableCaptureIdentity & {
+  source?: CaptureSource;
+  frameKey?: string;
+  configRevisionId?: string;
+};
+
+export type UploadIntent = { kind: "legacy" } | ({ kind: "stable" } & StableUpload);
+
+type InvalidUploadHeadersCode =
+  | "incomplete_capture_identity"
+  | "invalid_capture_id"
+  | "invalid_captured_at"
+  | "invalid_capture_source"
+  | "invalid_frame_key"
+  | "invalid_config_revision_id";
+
+export class InvalidUploadHeadersError extends Error {
+  constructor(readonly code: InvalidUploadHeadersCode, message: string) {
+    super(message);
+    this.name = "InvalidUploadHeadersError";
+  }
+}
+
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const CAPTURED_AT = /^\d{13}$/;
+const SAFE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+const invalid = (code: InvalidUploadHeadersCode, message: string): never => {
+  throw new InvalidUploadHeadersError(code, message);
+};
+
+export function parseUploadHeaders(headers: Headers): UploadIntent {
+  const captureId = headers.get("x-capture-id");
+  const capturedAt = headers.get("x-captured-at");
+  const source = headers.get("x-capture-source");
+  const frameKey = headers.get("x-frame-key");
+  const configRevisionId = headers.get("x-config-revision-id");
+
+  const hasMetadata = source !== null || frameKey !== null || configRevisionId !== null;
+
+  if (captureId === null && capturedAt === null) {
+    if (hasMetadata) invalid("incomplete_capture_identity", "Capture metadata requires a capture identity.");
+    return { kind: "legacy" };
+  }
+
+  if (captureId === null || capturedAt === null) {
+    throw new InvalidUploadHeadersError("incomplete_capture_identity", "Both capture identity headers are required.");
+  }
+
+  if (!UUID_V4.test(captureId)) invalid("invalid_capture_id", "Capture ID must be a lowercase UUID-v4.");
+  if (!CAPTURED_AT.test(capturedAt)) invalid("invalid_captured_at", "Captured-at must be exactly 13 decimal digits.");
+  let parsedSource: CaptureSource | undefined;
+  if (source !== null) {
+    if (source === "framed" || source === "camera-fallback") {
+      parsedSource = source;
+    } else {
+      throw new InvalidUploadHeadersError("invalid_capture_source", "Capture source is invalid.");
+    }
+  }
+  if (frameKey !== null && !SAFE_TOKEN.test(frameKey)) invalid("invalid_frame_key", "Frame key is invalid.");
+  if (configRevisionId !== null && !SAFE_TOKEN.test(configRevisionId)) {
+    invalid("invalid_config_revision_id", "Config revision ID is invalid.");
+  }
+
+  return {
+    kind: "stable",
+    captureId,
+    capturedAt: Number(capturedAt),
+    ...(parsedSource ? { source: parsedSource } : {}),
+    ...(frameKey !== null ? { frameKey } : {}),
+    ...(configRevisionId !== null ? { configRevisionId } : {}),
+  };
+}
+
+export function stableUploadHeaders(input: StableUpload): Record<string, string> {
+  return {
+    "x-capture-id": input.captureId,
+    "x-captured-at": String(input.capturedAt),
+    ...(input.source ? { "x-capture-source": input.source } : {}),
+    ...(input.frameKey ? { "x-frame-key": input.frameKey } : {}),
+    ...(input.configRevisionId ? { "x-config-revision-id": input.configRevisionId } : {}),
+  };
+}

From 4e176c93392c891de2876b3f3bec519f20aa4ee5 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:02:43 +0800
Subject: [PATCH 020/105] feat: make photo ingest idempotent and privately
 indexed

---
 app/event-store.test.ts | 145 ++++++++++++++++++++++++++++++++++++++++
 app/event-store.ts      | 120 +++++++++++++++++++++++++++++++--
 2 files changed, 261 insertions(+), 4 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 0400730..dd11f67 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -11,8 +11,34 @@ import {
   eventConfigMutationKey,
   eventConfigRevisionKey,
   legacyEventConfigKey,
+  PhotoIndexWriteError,
+  photoIndexKey,
+  photoReceiptKey,
 } from "./event-store";
 
+class FailPrivatePhotoWriteStore extends InMemoryObjectStore {
+  private writesFail = true;
+
+  constructor(private readonly failingPrefix: string) {
+    super();
+  }
+
+  allowWrites(): void {
+    this.writesFail = false;
+  }
+
+  override async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    if (this.writesFail && key.startsWith(this.failingPrefix)) {
+      throw new Error(`simulated private write failure for ${key}`);
+    }
+    return super.compareAndSwap(key, expectedEtag, value);
+  }
+}
+
 class FailNextConfigHeadCasStore extends InMemoryObjectStore {
   private failNextConfigHeadCas = true;
 
@@ -1010,6 +1036,125 @@ describe("EventStore", () => {
     }
   });
 
+  test("stable ingest creates one immutable photo across retries", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example", () => new Date("2026-07-24T00:00:00Z"));
+    const upload = {
+      captureId: "018f0000-0000-4000-8000-000000000001",
+      capturedAt: 1753315200000,
+      source: "framed" as const,
+      frameKey: "square",
+    };
+
+    const first = await store.putPhoto("launch", new TextEncoder().encode("first").buffer, { upload });
+    const retry = await store.putPhoto("launch", new TextEncoder().encode("replacement").buffer, { upload });
+
+    expect(first).toMatchObject({
+      key: "launch/1753315200000-018f0000-0000-4000-8000-000000000001.jpg",
+      duplicate: false,
+      indexStored: true,
+      receiptStored: true,
+    });
+    expect(retry).toMatchObject({ key: first.key, url: first.url, duplicate: true, indexStored: true, receiptStored: true });
+    expect(await (await photos.get(first.key))!.text()).toBe("first");
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+    expect(state.has(photoIndexKey("launch", first.key, upload.capturedAt))).toBe(true);
+    expect(state.has(photoReceiptKey("launch", first.key))).toBe(true);
+  });
+
+  test("concurrent stable attempts produce one public image", async () => {
+    const photos = new InMemoryObjectStore();
+    const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+    const upload = {
+      captureId: "018f0000-0000-4000-8000-000000000002",
+      capturedAt: 1753315200001,
+    };
+
+    const results = await Promise.all([
+      store.putPhoto("launch", new Uint8Array([1]).buffer, { upload }),
+      store.putPhoto("launch", new Uint8Array([2]).buffer, { upload }),
+    ]);
+
+    expect(results.filter((result) => result.duplicate)).toHaveLength(1);
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+  });
+
+  test("a stable retry repairs a missing index without another public photo", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new FailPrivatePhotoWriteStore("events/launch/photo-index/");
+    const store = new EventStore(photos, state, "https://photos.example");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000003", capturedAt: 1753315200002 };
+
+    const first = store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    await expect(first).rejects.toBeInstanceOf(PhotoIndexWriteError);
+    const key = "launch/1753315200002-018f0000-0000-4000-8000-000000000003.jpg";
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+    expect(state.has(photoIndexKey("launch", key, upload.capturedAt))).toBe(false);
+
+    state.allowWrites();
+    await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).resolves.toMatchObject({
+      key,
+      duplicate: true,
+      indexStored: true,
+    });
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+  });
+
+  test("receipt failure is observable but does not reject an acknowledged stable photo", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new FailPrivatePhotoWriteStore("events/launch/photo-metadata/");
+    const store = new EventStore(photos, state, "https://photos.example");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000004", capturedAt: 1753315200003 };
+
+    await expect(store.putPhoto("launch", new Uint8Array([1]).buffer, { upload })).resolves.toMatchObject({
+      duplicate: false,
+      indexStored: true,
+      receiptStored: false,
+    });
+  });
+
+  test("legacy uploads keep random keys and acknowledge private derived-write failures", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new FailPrivatePhotoWriteStore("events/launch/photo-");
+    const store = new EventStore(photos, state, "https://photos.example", () => new Date("2026-07-24T00:00:00Z"));
+
+    const first = await store.putPhoto("launch", new Uint8Array([1]).buffer);
+    const retry = await store.putPhoto("launch", new Uint8Array([2]).buffer);
+
+    expect(first).toMatchObject({ duplicate: false, indexStored: false, receiptStored: false });
+    expect(retry).toMatchObject({ duplicate: false, indexStored: false, receiptStored: false });
+    expect(first.key).not.toBe(retry.key);
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(2);
+  });
+
+  test("stable identities are event-isolated and private records contain no credentials", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example", () => new Date("2026-07-24T00:00:00Z"));
+    const upload = {
+      captureId: "018f0000-0000-4000-8000-000000000005",
+      capturedAt: 1753315200004,
+      source: "camera-fallback" as const,
+      frameKey: "square",
+      configRevisionId: "018f0000-0000-7000-8000-000000000006",
+    };
+
+    const launch = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    const other = await store.putPhoto("other", new Uint8Array([2]).buffer, { upload });
+    expect(launch.key).not.toBe(other.key);
+    expect((await photos.list()).objects).toHaveLength(2);
+
+    const index = await (await state.get(photoIndexKey("launch", launch.key, upload.capturedAt)))!.json<Record<string, unknown>>();
+    const receipt = await (await state.get(photoReceiptKey("launch", launch.key)))!.json<Record<string, unknown>>();
+    for (const record of [index, receipt]) {
+      expect(record).not.toHaveProperty("boothKeyHash");
+      expect(record).not.toHaveProperty("boothKey");
+      expect(record).not.toHaveProperty("credential");
+      expect(JSON.stringify(record)).not.toContain("hash");
+    }
+  });
+
   test("returns an initial snapshot and efficient start-after delta", async () => {
     const photos = new InMemoryObjectStore();
     photos.set("launch/0000000001000-aaaa.jpg", "a", new Date("2026-01-01T00:00:01Z"));
diff --git a/app/event-store.ts b/app/event-store.ts
index 69e08ef..69378a2 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -13,6 +13,7 @@ import {
   type EventConfig,
   type EventExperience,
 } from "./event-config";
+import type { StableCaptureIdentity, StableUpload } from "./upload-contract";
 export { canonicalEvent, InvalidEventSlugError, slugifyEvent } from "./event-identity";
 export { EVENT_CONFIG_VERSION };
 export type { EventConfig } from "./event-config";
@@ -222,6 +223,12 @@ export const eventConfigMutationKey = (event: string, mutationId: string) =>
   `events/${event}/config-mutations/${mutationId}.json`;
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
+export const stablePhotoKey = (event: string, id: StableCaptureIdentity) =>
+  `${event}/${String(id.capturedAt).padStart(13, "0")}-${id.captureId}.jpg`;
+export const photoReceiptKey = (event: string, key: string) =>
+  `events/${event}/photo-metadata/${key.slice(eventPhotoPrefix(event).length)}.json`;
+export const photoIndexKey = (event: string, key: string, sortTime: number) =>
+  `events/${event}/photo-index/v1/${String(9_999_999_999_999 - sortTime).padStart(13, "0")}-${base64url(key)}.json`;
 
 function photoTimestamp(key: string): number {
   const filename = key.slice(key.lastIndexOf("/") + 1);
@@ -234,6 +241,14 @@ function isPhotoKey(event: string, key: string): boolean {
 
 export type Photo = { key: string; url: string; uploadedAt: Date };
 export type PhotoFeed = { photos: Photo[]; cursor: string | null; unchanged: boolean; truncated: boolean };
+export type PutPhotoOptions = { upload?: StableUpload };
+export type PutPhotoResult = {
+  key: string;
+  url: string;
+  duplicate: boolean;
+  receiptStored: boolean;
+  indexStored: boolean;
+};
 export type ConfigMutationResult = {
   config: EventConfig;
   revision: ConfigRevision;
@@ -275,6 +290,16 @@ export class InvalidStoredEventConfigError extends Error {
   }
 }
 
+export class PhotoIndexWriteError extends Error {
+  constructor(
+    readonly photo: Pick<PutPhotoResult, "key" | "url" | "duplicate">,
+    options: { cause: unknown }
+  ) {
+    super("photo index write failed", options);
+    this.name = "PhotoIndexWriteError";
+  }
+}
+
 export class EventStore {
   // Consistency policy: no process-global response cache. Reads reach the
   // backing store, so config writes/uploads/deletions need no invalidation fanout.
@@ -471,10 +496,41 @@ export class EventStore {
     return `${event}/${String(now).padStart(13, "0")}-${suffix}.jpg`;
   }
 
-  async putPhoto(event: string, body: ArrayBuffer): Promise<{ key: string; url: string }> {
-    const key = this.photoKey(event);
-    await this.photos.put(key, body, { httpMetadata: { contentType: "image/jpeg" } });
-    return { key, url: this.publicUrl(key) };
+  async putPhoto(event: string, body: ArrayBuffer, options: PutPhotoOptions = {}): Promise<PutPhotoResult> {
+    // Capture server time once: the immutable records for this attempt then
+    // agree even when a retry completes a previously interrupted upload.
+    const uploadedAt = this.now();
+    const upload = options.upload;
+    const key = upload ? stablePhotoKey(event, upload) : this.photoKey(event, uploadedAt.getTime());
+    const url = this.publicUrl(key);
+    let duplicate = false;
+
+    if (upload) {
+      const created = await this.photos.compareAndSwap(key, null, body, jpegWriteOptions());
+      duplicate = !created;
+    } else {
+      // Legacy clients cannot retry the same public key. Keep their original
+      // acknowledgment behavior even when private derived writes are down.
+      await this.photos.put(key, body, jpegWriteOptions());
+    }
+
+    const photo = { key, url, duplicate };
+    const metadata = photoPrivateMetadata(key, uploadedAt, upload);
+    const indexKey = photoIndexKey(event, key, metadata.capturedAt);
+
+    if (upload) {
+      try {
+        await this.state.compareAndSwap(indexKey, null, JSON.stringify(metadata), jsonWriteOptions());
+      } catch (cause) {
+        throw new PhotoIndexWriteError(photo, { cause });
+      }
+      const receiptStored = await this.tryWritePhotoReceipt(event, key, metadata);
+      return { ...photo, indexStored: true, receiptStored };
+    }
+
+    const indexStored = await this.tryWritePhotoIndex(indexKey, metadata);
+    const receiptStored = await this.tryWritePhotoReceipt(event, key, metadata);
+    return { ...photo, indexStored, receiptStored };
   }
 
   async listPhotos(event: string, after: string | null = null): Promise<PhotoFeed> {
@@ -540,6 +596,29 @@ export class EventStore {
     });
   }
 
+  private async tryWritePhotoIndex(key: string, metadata: PrivatePhotoMetadata): Promise<boolean> {
+    try {
+      await this.state.compareAndSwap(key, null, JSON.stringify(metadata), jsonWriteOptions());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async tryWritePhotoReceipt(event: string, photoKey: string, metadata: PrivatePhotoMetadata): Promise<boolean> {
+    try {
+      await this.state.compareAndSwap(
+        photoReceiptKey(event, photoKey),
+        null,
+        JSON.stringify(metadata),
+        jsonWriteOptions()
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   private async readJson(store: ObjectStore, key: string): Promise<unknown | null> {
     const object = await store.get(key);
     if (!object) return null;
@@ -842,6 +921,39 @@ function jsonWriteOptions(): R2PutOptions {
   };
 }
 
+function jpegWriteOptions(): R2PutOptions {
+  return { httpMetadata: { contentType: "image/jpeg" } };
+}
+
+type PrivatePhotoMetadata = {
+  version: 1;
+  key: string;
+  uploadedAt: string;
+  capturedAt: number;
+  source?: StableUpload["source"];
+  frameKey?: string;
+  configRevisionId?: string;
+};
+
+function photoPrivateMetadata(key: string, uploadedAt: Date, upload?: StableUpload): PrivatePhotoMetadata {
+  return {
+    version: 1,
+    key,
+    uploadedAt: uploadedAt.toISOString(),
+    capturedAt: upload?.capturedAt ?? uploadedAt.getTime(),
+    ...(upload?.source ? { source: upload.source } : {}),
+    ...(upload?.frameKey ? { frameKey: upload.frameKey } : {}),
+    ...(upload?.configRevisionId ? { configRevisionId: upload.configRevisionId } : {}),
+  };
+}
+
+function base64url(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
 function randomSuffix(): string {
   const bytes = crypto.getRandomValues(new Uint8Array(4));
   return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");

From 50c809055da53d9a70fe0d73300da6c9fe8a0f22 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:08:58 +0800
Subject: [PATCH 021/105] feat: validate and expose stable upload identity

---
 app/api/upload/handlers.ts   |  86 ++++++++++++++
 app/api/upload/route.test.ts | 217 +++++++++++++++++++++++++++++++++++
 app/api/upload/route.ts      |  51 ++------
 app/upload-auth.test.ts      |  23 +++-
 app/upload-auth.ts           |  17 +++
 5 files changed, 349 insertions(+), 45 deletions(-)
 create mode 100644 app/api/upload/handlers.ts
 create mode 100644 app/api/upload/route.test.ts

diff --git a/app/api/upload/handlers.ts b/app/api/upload/handlers.ts
new file mode 100644
index 0000000..4aa35bb
--- /dev/null
+++ b/app/api/upload/handlers.ts
@@ -0,0 +1,86 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  EventStore,
+  InvalidEventSlugError,
+  PhotoIndexWriteError,
+} from "@/app/event-store";
+import { InvalidUploadHeadersError, parseUploadHeaders } from "@/app/upload-contract";
+import { boothOrAdminOk, isImage, MAX_UPLOAD_BYTES } from "@/app/upload-auth";
+
+export type UploadHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+};
+
+const jsonError = (error: string, status: number, headers?: HeadersInit) =>
+  NextResponse.json({ error }, { status, headers });
+
+function eventFrom(req: NextRequest): string | NextResponse {
+  try {
+    return canonicalEvent(req.nextUrl.searchParams.get("event"));
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) return jsonError(error.message, 400);
+    throw error;
+  }
+}
+
+function declaredSizeTooLarge(req: NextRequest): boolean {
+  const contentLength = req.headers.get("content-length");
+  return contentLength !== null && /^\d+$/.test(contentLength) && Number(contentLength) > MAX_UPLOAD_BYTES;
+}
+
+/**
+ * HTTP-only validation around the Event Store's upload seam. Kept outside the
+ * route module because Next.js route modules may only export HTTP methods.
+ */
+export async function handleUpload(req: NextRequest, deps: UploadHandlerDeps): Promise<NextResponse> {
+  const event = eventFrom(req);
+  if (event instanceof NextResponse) return event;
+
+  const provided = req.headers.get("x-booth-key") ?? "";
+  // The overwhelmingly common Admin-Key path requires no config read (and
+  // therefore cannot trigger a compatibility migration before body/header
+  // validation). Only an otherwise unauthorized request looks up an Event's
+  // private Booth Key hash.
+  let auth = await boothOrAdminOk(provided, deps.adminKey);
+  if (auth === "unauthorized") {
+    const config = await deps.store.readConfig(event);
+    auth = await boothOrAdminOk(provided, deps.adminKey, config?.boothKeyHash);
+  }
+  if (auth === "disabled") return jsonError("upload disabled: no key configured", 503);
+  if (auth !== "ok") return jsonError("unauthorized", 401);
+
+  // Early reject via declared size before buffering the whole body.
+  if (declaredSizeTooLarge(req)) return jsonError("too large", 413);
+
+  let intent;
+  try {
+    // Stable headers are checked before consuming the potentially large body,
+    // guaranteeing malformed identities make no public or private writes.
+    intent = parseUploadHeaders(req.headers);
+  } catch (error) {
+    if (error instanceof InvalidUploadHeadersError) return jsonError(error.code, 400);
+    throw error;
+  }
+
+  const body = await req.arrayBuffer();
+  if (body.byteLength === 0) return jsonError("empty body", 400);
+  if (body.byteLength > MAX_UPLOAD_BYTES) return jsonError("too large", 413);
+  if (!isImage(new Uint8Array(body.slice(0, 12)))) return jsonError("not an image", 415);
+
+  try {
+    const photo = await deps.store.putPhoto(event, body, {
+      ...(intent.kind === "stable" ? { upload: intent } : {}),
+    });
+    // `url` remains first-class for older Booth clients; identity fields are
+    // additive for stable clients and moderation/retry diagnostics.
+    return NextResponse.json({ url: photo.url, key: photo.key, duplicate: photo.duplicate });
+  } catch (error) {
+    if (error instanceof PhotoIndexWriteError) {
+      // An acknowledged stable client can safely retry this exact identity.
+      return jsonError("photo index unavailable", 503, { "Retry-After": "1" });
+    }
+    throw error;
+  }
+}
diff --git a/app/api/upload/route.test.ts b/app/api/upload/route.test.ts
new file mode 100644
index 0000000..763e24f
--- /dev/null
+++ b/app/api/upload/route.test.ts
@@ -0,0 +1,217 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import {
+  EventStore,
+  InMemoryObjectStore,
+  type ObjectStore,
+  type StoredObjectBody,
+  type StoredObject,
+  type ListOptions,
+  type ListResult,
+} from "@/app/event-store";
+import { hashBoothKey, MAX_UPLOAD_BYTES } from "@/app/upload-auth";
+import { handleUpload, type UploadHandlerDeps } from "./handlers";
+
+const ADMIN_KEY = "admin";
+const CAPTURE_ID = "018f0000-0000-4000-8000-000000000001";
+const CAPTURED_AT = "1753315200000";
+const JPEG = new Uint8Array([0xff, 0xd8, 0xff, 0xe0]);
+
+function request(
+  event = "launch",
+  init: ConstructorParameters<typeof NextRequest>[1] = {}
+): NextRequest {
+  const { headers, body, ...rest } = init;
+  return new NextRequest(`https://app.test/api/upload?event=${event}`, {
+    method: "POST",
+    ...rest,
+    headers: { "x-booth-key": ADMIN_KEY, "content-type": "image/jpeg", ...headers },
+    body: body ?? JPEG,
+  });
+}
+
+function memoryDeps(options: { state?: ObjectStore; adminKey?: string } = {}) {
+  const photos = new InMemoryObjectStore();
+  const state = options.state ?? new InMemoryObjectStore();
+  return {
+    photos,
+    state,
+    deps: {
+      store: new EventStore(photos, state, "https://photos.example"),
+      adminKey: "adminKey" in options ? options.adminKey : ADMIN_KEY,
+    } satisfies UploadHandlerDeps,
+  };
+}
+
+class FailPrivateWrites implements ObjectStore {
+  private readonly inner = new InMemoryObjectStore();
+  private failing = true;
+
+  constructor(private readonly prefix: string) {}
+
+  allowWrites(): void {
+    this.failing = false;
+  }
+
+  has(key: string): boolean {
+    return this.inner.has(key);
+  }
+
+  get(key: string): Promise<StoredObjectBody | null> {
+    return this.inner.get(key);
+  }
+
+  put(key: string, value: ArrayBuffer | ArrayBufferView | string): Promise<void> {
+    return this.inner.put(key, value);
+  }
+
+  delete(key: string): Promise<void> {
+    return this.inner.delete(key);
+  }
+
+  list(options?: ListOptions): Promise<ListResult> {
+    return this.inner.list(options);
+  }
+
+  async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    if (this.failing && key.startsWith(this.prefix)) throw new Error("private storage unavailable");
+    return this.inner.compareAndSwap(key, expectedEtag, value);
+  }
+}
+
+function stableHeaders(overrides: Record<string, string> = {}): Record<string, string> {
+  return {
+    "x-capture-id": CAPTURE_ID,
+    "x-captured-at": CAPTURED_AT,
+    ...overrides,
+  };
+}
+
+describe("upload route", () => {
+  test("a stable retry returns the same key as a duplicate", async () => {
+    const { photos, deps } = memoryDeps();
+    const first = await handleUpload(request("launch", { headers: stableHeaders() }), deps);
+    const retry = await handleUpload(request("launch", { headers: stableHeaders() }), deps);
+
+    expect(first.status).toBe(200);
+    expect(await first.json()).toMatchObject({
+      key: "launch/1753315200000-018f0000-0000-4000-8000-000000000001.jpg",
+      duplicate: false,
+      url: "https://photos.example/launch/1753315200000-018f0000-0000-4000-8000-000000000001.jpg",
+    });
+    expect(await retry.json()).toMatchObject({ duplicate: true });
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+  });
+
+  test("legacy uploads retain the url response field", async () => {
+    const { deps } = memoryDeps();
+    const response = await handleUpload(request(), deps);
+    const body = await response.json() as Record<string, unknown>;
+
+    expect(response.status).toBe(200);
+    expect(typeof body.url).toBe("string");
+    expect(typeof body.key).toBe("string");
+    expect(body.duplicate).toBe(false);
+  });
+
+  test("an Event Booth Key can upload only after its private hash is resolved", async () => {
+    const { deps } = memoryDeps();
+    await deps.store.writeConfig("launch", {
+      frames: ["square"],
+      boothKeyHash: await hashBoothKey("event-key-123"),
+    });
+
+    const response = await handleUpload(request("launch", {
+      headers: { "x-booth-key": "event-key-123", ...stableHeaders() },
+    }), deps);
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toMatchObject({ duplicate: false });
+  });
+
+  test("rejects partial stable identity before writing either store", async () => {
+    const { photos, state, deps } = memoryDeps();
+    const response = await handleUpload(request("launch", {
+      headers: { "x-capture-id": CAPTURE_ID },
+    }), deps);
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({ error: "incomplete_capture_identity" });
+    expect((await photos.list()).objects).toHaveLength(0);
+    expect((await state.list()).objects).toHaveLength(0);
+  });
+
+  test("rejects canonical aliases and unauthorized uploads without writes", async () => {
+    const alias = memoryDeps();
+    const aliasResponse = await handleUpload(request("Launch", { headers: stableHeaders() }), alias.deps);
+    expect(aliasResponse.status).toBe(400);
+    expect((await alias.photos.list()).objects).toHaveLength(0);
+    expect((await alias.state.list()).objects).toHaveLength(0);
+
+    const unauthorized = memoryDeps();
+    const denied = await handleUpload(request("launch", {
+      headers: { "x-booth-key": "wrong", ...stableHeaders() },
+    }), unauthorized.deps);
+    expect(denied.status).toBe(401);
+    expect((await unauthorized.photos.list()).objects).toHaveLength(0);
+    expect((await unauthorized.state.list()).objects).toHaveLength(0);
+  });
+
+  test("maps declared size, empty/non-image data, and missing key configuration precisely", async () => {
+    const { deps } = memoryDeps();
+    const tooLarge = await handleUpload(request("launch", {
+      headers: { "content-length": String(MAX_UPLOAD_BYTES + 1) },
+    }), deps);
+    expect(tooLarge.status).toBe(413);
+
+    const empty = await handleUpload(new NextRequest("https://app.test/api/upload?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY, "content-type": "image/jpeg" },
+    }), deps);
+    expect(empty.status).toBe(400);
+
+    const unsupported = await handleUpload(new NextRequest("https://app.test/api/upload?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY, "content-type": "application/octet-stream" },
+      body: new Uint8Array([1, 2, 3]),
+    }), deps);
+    expect(unsupported.status).toBe(415);
+
+    const previous = process.env.ALLOW_KEYLESS;
+    delete process.env.ALLOW_KEYLESS;
+    const disabled = await handleUpload(request(), memoryDeps({ adminKey: undefined }).deps);
+    expect(disabled.status).toBe(503);
+    if (previous === undefined) delete process.env.ALLOW_KEYLESS;
+    else process.env.ALLOW_KEYLESS = previous;
+  });
+
+  test("an index failure is retryable and an identical retry recovers the same public photo", async () => {
+    const state = new FailPrivateWrites("events/launch/photo-index/");
+    const { photos, deps } = memoryDeps({ state });
+    const first = await handleUpload(request("launch", { headers: stableHeaders() }), deps);
+
+    expect(first.status).toBe(503);
+    expect(first.headers.get("Retry-After")).toBe("1");
+    expect(await first.json()).toEqual({ error: "photo index unavailable" });
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+
+    state.allowWrites();
+    const retry = await handleUpload(request("launch", { headers: stableHeaders() }), deps);
+    expect(retry.status).toBe(200);
+    expect(await retry.json()).toMatchObject({ duplicate: true });
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+  });
+
+  test("a receipt failure still acknowledges the stable upload", async () => {
+    const state = new FailPrivateWrites("events/launch/photo-metadata/");
+    const { deps } = memoryDeps({ state });
+    const response = await handleUpload(request("launch", { headers: stableHeaders() }), deps);
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toMatchObject({ duplicate: false });
+  });
+});
diff --git a/app/api/upload/route.ts b/app/api/upload/route.ts
index e146fb5..7e4983c 100644
--- a/app/api/upload/route.ts
+++ b/app/api/upload/route.ts
@@ -1,49 +1,12 @@
 import { getCloudflareContext } from "@opennextjs/cloudflare";
-import { NextRequest, NextResponse } from "next/server";
-import { canonicalEvent, EventStore, InvalidEventSlugError } from "@/app/event-store";
-import { adminOk, boothKeyMatches, isImage, MAX_UPLOAD_BYTES } from "@/app/upload-auth";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { handleUpload } from "./handlers";
 
 export async function POST(req: NextRequest) {
   const { env } = getCloudflareContext();
-  let event: string;
-  try {
-    event = canonicalEvent(req.nextUrl.searchParams.get("event"));
-  } catch (error) {
-    if (error instanceof InvalidEventSlugError) return NextResponse.json({ error: error.message }, { status: 400 });
-    throw error;
-  }
-  const store = EventStore.fromEnv(env);
-  const provided = req.headers.get("x-booth-key") ?? "";
-
-  // Two accepted keys: the admin key (BOOTH_UPLOAD_KEY), or this event's own
-  // booth key — set per event in /{event}/admin, stored hashed in the config
-  // object. A booth key only ever uploads to its own event.
-  const admin = adminOk(provided, env.BOOTH_UPLOAD_KEY);
-  if (admin === "disabled") {
-    return NextResponse.json({ error: "upload disabled: no key configured" }, { status: 503 });
-  }
-  if (admin === "unauthorized") {
-    const cfg = await store.readConfig(event);
-    const ok = !!cfg?.boothKeyHash && provided !== "" && (await boothKeyMatches(provided, cfg.boothKeyHash));
-    if (!ok) return NextResponse.json({ error: "unauthorized" }, { status: 401 });
-  }
-
-  // Early reject via declared size before buffering the whole body.
-  if (Number(req.headers.get("content-length") ?? 0) > MAX_UPLOAD_BYTES) {
-    return NextResponse.json({ error: "too large" }, { status: 413 });
-  }
-
-  const body = await req.arrayBuffer();
-  if (body.byteLength === 0) {
-    return NextResponse.json({ error: "empty body" }, { status: 400 });
-  }
-  if (body.byteLength > MAX_UPLOAD_BYTES) {
-    return NextResponse.json({ error: "too large" }, { status: 413 });
-  }
-  if (!isImage(new Uint8Array(body.slice(0, 12)))) {
-    return NextResponse.json({ error: "not an image" }, { status: 415 });
-  }
-
-  const photo = await store.putPhoto(event, body);
-  return NextResponse.json({ url: photo.url });
+  return handleUpload(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
 }
diff --git a/app/upload-auth.test.ts b/app/upload-auth.test.ts
index 928de22..5ca9f5b 100644
--- a/app/upload-auth.test.ts
+++ b/app/upload-auth.test.ts
@@ -1,5 +1,13 @@
 import { test, expect } from "bun:test";
-import { keyOk, adminOk, hashBoothKey, boothKeyMatches, safeEvent, isImage } from "./upload-auth";
+import {
+  keyOk,
+  adminOk,
+  boothOrAdminOk,
+  hashBoothKey,
+  boothKeyMatches,
+  safeEvent,
+  isImage,
+} from "./upload-auth";
 
 test("keyOk accepts the exact key", () => {
   expect(keyOk("b29b8260981f1548", "b29b8260981f1548")).toBe(true);
@@ -52,6 +60,19 @@ test("booth key hashing round-trips and is salted", async () => {
   expect(await hashBoothKey("my-booth-key-123")).not.toBe(stored);
 });
 
+test("boothOrAdminOk preserves the admin-required fail-closed rule", async () => {
+  const stored = await hashBoothKey("event-key-123");
+  expect(await boothOrAdminOk("admin", "admin", stored)).toBe("ok");
+  expect(await boothOrAdminOk("event-key-123", "admin", stored)).toBe("ok");
+  expect(await boothOrAdminOk("wrong", "admin", stored)).toBe("unauthorized");
+
+  const previous = process.env.ALLOW_KEYLESS;
+  delete process.env.ALLOW_KEYLESS;
+  expect(await boothOrAdminOk("event-key-123", undefined, stored)).toBe("disabled");
+  if (previous === undefined) delete process.env.ALLOW_KEYLESS;
+  else process.env.ALLOW_KEYLESS = previous;
+});
+
 test("safeEvent slugs to a-z0-9- and never emits an underscore", () => {
   expect(safeEvent("My Event! 2026")).toBe("my-event-2026");
   expect(safeEvent("_config")).toBe("config");
diff --git a/app/upload-auth.ts b/app/upload-auth.ts
index b12bbc7..cff329e 100644
--- a/app/upload-auth.ts
+++ b/app/upload-auth.ts
@@ -55,6 +55,23 @@ export async function boothKeyMatches(key: string, stored: string): Promise<bool
   return keyOk(await pbkdf2(key, fromHex(saltHex)), hashHex);
 }
 
+/**
+ * Upload authentication accepts either the operational Admin Key or the
+ * current Event's Booth Key. An unavailable Admin Key remains fail-closed:
+ * an Event Booth Key cannot quietly enable uploads in that configuration.
+ */
+export async function boothOrAdminOk(
+  provided: string,
+  adminKey: string | undefined,
+  boothKeyHash?: string
+): Promise<"ok" | "unauthorized" | "disabled"> {
+  const admin = adminOk(provided, adminKey);
+  if (admin !== "unauthorized") return admin;
+  return boothKeyHash && provided && await boothKeyMatches(provided, boothKeyHash)
+    ? "ok"
+    : "unauthorized";
+}
+
 // Slugs an event name to a safe key prefix; anything else -> "event".
 // Shared by every API route (was four hand-synced copies).
 export const safeEvent = slugifyEvent;

From 35d6849395ba53ac4b1a7e40da1d6d55dc02008b Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:10:47 +0800
Subject: [PATCH 022/105] docs: plan reliable booth control

---
 ...-07-24-release-1-reliable-booth-control.md | 1107 +++++++++++++++++
 1 file changed, 1107 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-24-release-1-reliable-booth-control.md

diff --git a/docs/superpowers/plans/2026-07-24-release-1-reliable-booth-control.md b/docs/superpowers/plans/2026-07-24-release-1-reliable-booth-control.md
new file mode 100644
index 0000000..208c016
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-24-release-1-reliable-booth-control.md
@@ -0,0 +1,1107 @@
+# Release 1 Reliable Booth Control Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the Booth safely operable through unreliable connectivity, authenticated startup, remote pause/resume, private device monitoring, and installed iPad mode.
+
+**Architecture:** The Booth Session remains the owner of durable ordered retry and storage acknowledgment. `EventStore` remains the only owner of private Booth heartbeat and operational-state keys, while HTTP handlers authenticate, canonicalize, validate, and delegate. The Booth recovers the Photo Outbox before authentication but starts no camera and accepts no new capture until online preflight succeeds.
+
+**Tech Stack:** Bun, TypeScript, Next.js 15 App Router, React 19, Cloudflare Workers, R2, IndexedDB, Web App Manifest, Screen Wake Lock API, Playwright WebKit.
+
+## Global Constraints
+
+- Start only after Release 0B stable Outbox identity, idempotent upload, and shared `boothOrAdminOk()` are complete.
+- Use Bun commands only.
+- `EventStore` remains the sole owner of `PHOTOS` and `STATE` keys.
+- Heartbeats and operational pause state live only in private `STATE`.
+- Never store credentials, hashes, thumbnails, arbitrary exception text, URLs, headers, user agents, or guest identifiers in a heartbeat.
+- Outbox items leave storage only after upload acknowledgment.
+- Automatic retry preserves oldest-first ordering and never skips a blocked first item.
+- Pause blocks new captures but never blocks Photo Outbox draining.
+- A fresh capture requires successful online preflight.
+- Existing Outbox rows and IndexedDB data remain readable; migrations are additive only.
+- Event HTTP parameters use `canonicalEvent()` and reject aliases.
+- Never silently slug an Event at an HTTP boundary.
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+- Never deploy the unnamed Wrangler environment to an Event domain.
+
+---
+
+## File Structure
+
+- Create `app/[event]/booth-session/retry-policy.ts` — upload failure classification and retry timing.
+- Create `app/[event]/booth-session/retry-policy.test.ts` — status, backoff, and `Retry-After` contracts.
+- Modify `app/[event]/booth-session/outbox.ts` — additive failure fields and atomic Event leases.
+- Modify `app/[event]/booth-session/session.ts` — automatic scheduling, lease ownership, and auth-required state.
+- Modify `app/[event]/booth-session/session.test.ts` — reload, ordering, reconnect, and lease coverage.
+- Create `app/booth-control.ts` — bounded private Booth schemas and safe public projections.
+- Create `app/booth-control.test.ts` — schema and projection tests.
+- Modify `app/event-store.ts` — private Booth records and paging.
+- Modify `app/event-store.test.ts` — private storage, stale derivation, and Event isolation.
+- Modify `app/event-config.ts` — explicit safe `EventExperience` projection.
+- Modify `app/event-config.test.ts` — preflight projection redaction.
+- Create `app/api/booth/handlers.ts` — dependency-injected Booth control handlers.
+- Create `app/api/booth/handlers.test.ts` — auth, redaction, validation, and paging.
+- Create `app/api/booth/preflight/route.ts` — preflight route adapter.
+- Create `app/api/booths/route.ts` — heartbeat write and Admin list adapter.
+- Create `app/api/booth-state/route.ts` — public read and Admin pause adapter.
+- Create `app/[event]/booth-session/credential.ts` — session/local Booth credential persistence.
+- Create `app/[event]/booth-session/credential.test.ts` — persistence and clearing tests.
+- Create `app/[event]/booth-session/access.ts` — pure Booth access state transitions.
+- Create `app/[event]/booth-session/access.test.ts` — lock, checking, recovery, and unavailable transitions.
+- Create `app/[event]/booth-unlock.tsx` — accessible unlock form.
+- Create `app/[event]/booth-unlock.test.tsx` — unlock markup and secret-redaction tests.
+- Create `app/[event]/booth-session/operational-client.ts` — pause polling and heartbeat reporting.
+- Create `app/[event]/booth-session/operational-client.test.ts` — no-overlap and failure tests.
+- Create `app/[event]/booth-session/device-identity.ts` — credential-independent local device UUID.
+- Create `app/[event]/booth-session/device-identity.test.ts` — stable ID and fallback tests.
+- Modify `app/[event]/page.tsx` — unlock, preflight, retry triggers, pause, heartbeat, wake, and exit integration.
+- Modify `app/[event]/booth.module.css` — Booth control surfaces and status states.
+- Create `app/[event]/admin/booth-operations.ts` — pure Admin Booth paging/merge helpers.
+- Create `app/[event]/admin/booth-operations.test.ts` — paging and merge behavior.
+- Create `app/[event]/admin/booth-operations-panel.tsx` — pause controls and private device status.
+- Create `app/[event]/admin/booth-operations-panel.test.tsx` — Admin rendering and busy-state tests.
+- Modify `app/[event]/admin/page.tsx` — authenticated operational polling and mutations.
+- Modify `app/[event]/admin/admin.module.css` — operations panel styling.
+- Create `app/[event]/manifest.ts` — public per-Event installed Booth manifest.
+- Create `app/[event]/manifest.test.ts` — canonical installed-mode contract.
+- Create `public/booth-icon.svg` — credential-free Booth icon.
+- Create `app/[event]/booth-session/installed-mode.ts` — standalone detection, wake lock, and navigation rules.
+- Create `app/[event]/booth-session/installed-mode.test.ts` — installed behavior tests.
+- Create `app/[event]/operator-controls.tsx` — authenticated operator exit.
+- Create `app/[event]/operator-controls.test.tsx` — exit validation and queue-preservation markup.
+- Modify `app/layout.tsx` — iOS installed-mode metadata.
+- Modify `package.json` and `bun.lock` — WebKit browser test command/dependency.
+- Create `playwright.config.ts` — local WebKit test server.
+- Create `tests/booth-control.spec.ts` — mocked-camera Booth control journey.
+- Modify `.github/workflows/verify.yml` — browser verification.
+- Modify `docs/runbooks/pre-event-readiness.md` — Release 1 real-iPad checks.
+- Modify `docs/runbooks/deployment.md` — Release 1 staging smoke gate.
+
+### Task 1: Add automatic retry and an atomic cross-tab Event lease
+
+**Files:**
+- Create: `app/[event]/booth-session/retry-policy.ts`
+- Create: `app/[event]/booth-session/retry-policy.test.ts`
+- Modify: `app/[event]/booth-session/outbox.ts`
+- Modify: `app/[event]/booth-session/session.ts`
+- Modify: `app/[event]/booth-session/session.test.ts`
+- Modify: `app/[event]/page.tsx`
+
+**Interfaces:**
+- Consumes: Release 0B `OutboxItem`, stable upload identity, and idempotent upload response.
+- Produces: `HttpUploadError`, `UploadErrorClass`, `RetryDisposition`, and `classifyUploadFailure()`.
+- Produces: `OutboxStore.acquireLease()`, `renewLease()`, and `releaseLease()`.
+- Produces: automatic `BoothSession.start()`, `stop()`, `reconsider()`, and retained manual `retry()`.
+
+- [ ] **Step 1: Write failing retry-policy tests**
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { HttpUploadError, classifyUploadFailure } from "./retry-policy";
+
+describe("upload retry policy", () => {
+  test("retries network, 408, 425, 429, and 5xx failures", () => {
+    for (const status of [408, 425, 429, 500, 503]) {
+      expect(classifyUploadFailure(
+        new HttpUploadError(status, null, status >= 500 ? "server" : "timeout"),
+        1,
+        1_000,
+        () => 0.5
+      ).kind).toBe("retryable");
+    }
+    expect(classifyUploadFailure(new TypeError("fetch failed"), 1, 1_000, () => 0.5).kind)
+      .toBe("retryable");
+  });
+
+  test("401 requires auth and permanent statuses do not loop", () => {
+    expect(classifyUploadFailure(new HttpUploadError(401, null, "auth"), 1, 0, () => 0.5))
+      .toEqual({ kind: "auth-required", errorClass: "auth" });
+    for (const status of [400, 403, 413, 415]) {
+      expect(classifyUploadFailure(new HttpUploadError(status, null, "payload"), 1, 0, () => 0.5).kind)
+        .toBe("permanent");
+    }
+  });
+});
+```
+
+Add cases for delta-seconds and HTTP-date `Retry-After`, deterministic jitter,
+exponential growth, and the 30-second cap.
+
+- [ ] **Step 2: Run the retry-policy test and verify missing-module failure**
+
+Run: `bun test 'app/[event]/booth-session/retry-policy.test.ts'`
+
+Expected: FAIL because `retry-policy.ts` does not exist.
+
+- [ ] **Step 3: Implement strict failure classification**
+
+```ts
+export type UploadErrorClass =
+  | "network" | "timeout" | "auth" | "payload" | "server" | "unknown";
+
+export class HttpUploadError extends Error {
+  constructor(
+    readonly status: number,
+    readonly retryAfter: string | null,
+    readonly errorClass: UploadErrorClass
+  ) {
+    super(`upload failed with status ${status}`);
+  }
+}
+
+export type RetryDisposition =
+  | { kind: "retryable"; delayMs: number; errorClass: UploadErrorClass }
+  | { kind: "auth-required"; errorClass: "auth" }
+  | { kind: "permanent"; errorClass: UploadErrorClass };
+```
+
+`classifyUploadFailure(error, attempt, now, random)` retries thrown network
+errors and HTTP `408`, `425`, `429`, and `5xx`; returns `auth-required` for
+`401`; and returns `permanent` for `400`, `403`, `413`, and `415`. Backoff is
+`min(30_000, 1_000 * 2 ** (attempt - 1) * (0.5 + random()))`. A valid
+`Retry-After` delta or date chooses the later delay before the same 30-second
+cap.
+
+- [ ] **Step 4: Write failing Session reload, ordering, and lease tests**
+
+Add tests proving:
+
+- `nextAttemptAt`, `failureKind`, and `errorClass` survive reload.
+- The oldest failed item blocks every later item.
+- Reconnect and foreground immediately reconsider the oldest retryable item.
+- A permanent or auth failure does not automatically restart.
+- Manual retry can reconsider the first blocked item.
+- Concurrent `process()` calls coalesce.
+- Two sessions for one Event cannot drain simultaneously.
+- An expired lease can be acquired by a second owner.
+- Different Events have independent leases.
+
+- [ ] **Step 5: Implement additive Outbox failure state and leases**
+
+Extend `OutboxItem`:
+
+```ts
+nextAttemptAt?: number;
+failureKind?: "retryable" | "permanent" | "auth";
+errorClass?: UploadErrorClass;
+```
+
+Extend `OutboxStore`:
+
+```ts
+acquireLease(event: string, ownerId: string, now: number, ttlMs: number): Promise<boolean>;
+renewLease(event: string, ownerId: string, now: number, ttlMs: number): Promise<boolean>;
+releaseLease(event: string, ownerId: string): Promise<void>;
+```
+
+Bump IndexedDB to version `2` and add only `photo-outbox-leases`. Implement
+lease acquisition as one read/write transaction that replaces only a missing,
+expired, or same-owner record. Never delete or rewrite `photo-outbox`.
+
+- [ ] **Step 6: Implement automatic Session scheduling**
+
+Add `start()`, `stop()`, `reconsider("connectivity" | "foreground")`, and keep
+manual `retry()`. Acquire the Event lease before drain, renew it during drain,
+release it on stop, persist retry eligibility before publishing state, and
+schedule one timer for the first retryable item. A `401` invokes
+`onAuthRequired` without removing the item. Keep `processing` coalescing.
+
+In the Booth page, convert non-OK upload responses to `HttpUploadError`, call
+`session.start()` after valid preflight, call `reconsider("connectivity")` on
+`online`, call `reconsider("foreground")` when the document becomes visible,
+and call `stop()` on unmount.
+
+- [ ] **Step 7: Run focused and full tests**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/retry-policy.test.ts' 'app/[event]/booth-session/session.test.ts'
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add 'app/[event]/booth-session' 'app/[event]/page.tsx'
+git commit -m "feat: retry queued photos automatically"
+```
+
+### Task 2: Add bounded private Booth operational records
+
+**Files:**
+- Create: `app/booth-control.ts`
+- Create: `app/booth-control.test.ts`
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Produces: heartbeat and pause schemas shared by Event Store, handlers, and clients.
+- Produces: exact private keys and Event Store read/write/list methods.
+- Consumed by: Tasks 3, 5, and 6.
+
+- [ ] **Step 1: Write failing schema and privacy tests**
+
+```ts
+expect(parseBoothHeartbeat({
+  version: 1,
+  deviceId: "018f0000-0000-4000-8000-000000000001",
+  sessionStartedAt: 1753315200000,
+  pendingCount: 2,
+  durableStorage: true,
+  online: true,
+  installed: true,
+  camera: "ready",
+  upload: "retry-wait",
+  buildId: "release_1",
+})).not.toBeNull();
+
+expect(parseBoothHeartbeat({
+  version: 1,
+  deviceId: "018f0000-0000-4000-8000-000000000001",
+  sessionStartedAt: 1753315200000,
+  pendingCount: 0,
+  durableStorage: true,
+  online: true,
+  installed: false,
+  camera: "ready",
+  upload: "idle",
+  buildId: "release_1",
+  error: "credential=x",
+})).toBeNull();
+```
+
+Add Event Store tests for server-controlled timestamps, paging, stale
+derivation, exact device overwrite, cross-Event isolation, malformed/future
+stored versions, pause defaults, localized messages, and zero writes to
+`PHOTOS`.
+
+- [ ] **Step 2: Run tests and verify missing exports**
+
+Run: `bun test app/booth-control.test.ts app/event-store.test.ts`
+
+Expected: FAIL because Booth control schemas and Event Store methods do not exist.
+
+- [ ] **Step 3: Implement bounded shared schemas**
+
+```ts
+export const BOOTH_HEARTBEAT_INTERVAL_MS = 15_000;
+export const BOOTH_STALE_AFTER_MS = 45_000;
+
+export type BoothCameraState =
+  | "stopped" | "starting" | "ready" | "denied" | "unavailable";
+export type BoothUploadState =
+  | "idle" | "uploading" | "retry-wait" | "blocked" | "auth-required";
+export type BoothErrorClass =
+  | "network" | "timeout" | "auth" | "payload" | "camera-permission"
+  | "camera-unavailable" | "storage" | "server" | "unknown";
+
+export type BoothHeartbeatInput = {
+  version: 1;
+  deviceId: string;
+  sessionStartedAt: number;
+  pendingCount: number;
+  durableStorage: boolean;
+  online: boolean;
+  installed: boolean;
+  camera: BoothCameraState;
+  upload: BoothUploadState;
+  lastSuccessfulUploadAt?: number;
+  errorClass?: BoothErrorClass;
+  buildId: string;
+};
+
+export type BoothHeartbeatRecord = BoothHeartbeatInput & { lastSeenAt: string };
+export type AdminBoothRecord = BoothHeartbeatRecord & { stale: boolean };
+export type BoothOperationalState = {
+  version: 1;
+  paused: boolean;
+  messages?: Record<string, string>;
+  updatedAt: string;
+};
+```
+
+Require lowercase UUID-v4, integer millisecond fields, `pendingCount` from
+`0..10_000`, exact enums, a 1–128 character token build ID, at most 20 locale
+messages, token locale keys, and messages of at most 280 characters. Reject
+unknown keys and unsupported versions.
+
+- [ ] **Step 4: Implement exact private keys and Event Store methods**
+
+```ts
+export const boothHeartbeatKey = (event: string, deviceId: string) =>
+  `events/${event}/booths/${deviceId}.json`;
+export const boothHeartbeatPrefix = (event: string) =>
+  `events/${event}/booths/`;
+export const boothOperationalStateKey = (event: string) =>
+  `events/${event}/booth-state.json`;
+```
+
+Add:
+
+```ts
+writeBoothHeartbeat(event, input): Promise<BoothHeartbeatRecord>;
+listBoothHeartbeats(event, options): Promise<{
+  booths: AdminBoothRecord[];
+  cursor: string | null;
+}>;
+readBoothOperationalState(event): Promise<BoothOperationalState>;
+writeBoothOperationalState(
+  event,
+  input: { paused: boolean; messages?: Record<string, string> }
+): Promise<BoothOperationalState>;
+```
+
+Use `STATE` only. Server time controls `lastSeenAt` and `updatedAt`. Listing
+accepts an opaque cursor and a `1..100` limit, default `50`, and derives
+`stale` at 45 seconds. Missing operational state returns an unpaused version-1
+default without forcing a write.
+
+- [ ] **Step 5: Run tests and type-check**
+
+Run:
+
+```bash
+bun test app/booth-control.test.ts app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/booth-control.ts app/booth-control.test.ts app/event-store.ts app/event-store.test.ts
+git commit -m "feat: store private booth operations"
+```
+
+### Task 3: Expose authenticated Booth control HTTP contracts
+
+**Files:**
+- Modify: `app/event-config.ts`
+- Modify: `app/event-config.test.ts`
+- Create: `app/api/booth/handlers.ts`
+- Create: `app/api/booth/handlers.test.ts`
+- Create: `app/api/booth/preflight/route.ts`
+- Create: `app/api/booths/route.ts`
+- Create: `app/api/booth-state/route.ts`
+
+**Interfaces:**
+- Consumes: Task 2 Event Store methods and Release 0B `boothOrAdminOk()`.
+- Produces: safe preflight, heartbeat, device-list, and operational-state handlers.
+- Consumed by: Tasks 4–6.
+
+- [ ] **Step 1: Write failing projection and handler tests**
+
+Add a projection test proving this input:
+
+```ts
+{
+  frames: ["square"],
+  boothKeyHash: "salt:hash",
+  currentRevisionId: "018f0000-0000-4000-8000-000000000001",
+}
+```
+
+projects to `{frames:["square"]}` without either private field.
+
+Add handler tests proving:
+
+- Preflight accepts the matching Booth key or Admin key.
+- Missing Admin secret fails closed with `503`.
+- Wrong key returns `401`.
+- Missing config or zero Frames returns `409`.
+- Preflight response contains only safe experience, operational state, and server time.
+- Heartbeat rejects unknown/unbounded fields before any write.
+- Booth key cannot write another Event's heartbeat.
+- Device list and pause mutation are Admin-only.
+- Public pause read contains no private device/config data.
+- Canonical aliases return `400`.
+
+- [ ] **Step 2: Run tests and verify missing handlers**
+
+Run: `bun test app/event-config.test.ts app/api/booth/handlers.test.ts`
+
+Expected: FAIL because the safe projector and handlers do not exist.
+
+- [ ] **Step 3: Implement the explicit safe experience projector**
+
+```ts
+export function projectEventExperience(config: EventConfig): EventExperience {
+  return {
+    frames: [...config.frames],
+    ...(config.locales ? { locales: [...config.locales] } : {}),
+    ...(config.defaultLocale ? { defaultLocale: config.defaultLocale } : {}),
+    ...(config.timeZone ? { timeZone: config.timeZone } : {}),
+    ...(config.capture ? { capture: { ...config.capture } } : {}),
+    ...(config.gallery ? { gallery: { ...config.gallery } } : {}),
+  };
+}
+```
+
+Do not serialize `EventConfig` directly.
+
+- [ ] **Step 4: Implement dependency-injected handlers**
+
+```ts
+export type BoothControlHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+};
+```
+
+Implement:
+
+- `postBoothPreflight(req, deps)` returning
+  `{experience, operationalState, serverTime}`.
+- `postBoothHeartbeat(req, deps)` returning the sanitized stored record.
+- `getBoothHeartbeats(req, deps)` returning `{booths, cursor}`.
+- `getBoothState(req, deps)` returning the safe public state with
+  `Cache-Control: no-store`.
+- `putBoothState(req, deps)` accepting only `{paused, messages?}`.
+
+All handlers canonicalize Event input. Preflight and heartbeat use the same
+`boothOrAdminOk()` rules as upload. Device listing and mutation use Admin auth.
+
+- [ ] **Step 5: Add thin route adapters**
+
+Each `route.ts` obtains `getCloudflareContext()`, constructs
+`EventStore.fromEnv(env)`, supplies `env.BOOTH_UPLOAD_KEY`, and delegates.
+Route modules own no key construction or storage logic.
+
+- [ ] **Step 6: Run route tests and type-check**
+
+Run:
+
+```bash
+bun test app/event-config.test.ts app/api/booth/handlers.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/event-config.ts app/event-config.test.ts app/api/booth app/api/booths app/api/booth-state
+git commit -m "feat: expose booth control APIs"
+```
+
+### Task 4: Replace prompt startup with unlock and online preflight
+
+**Files:**
+- Create: `app/[event]/booth-session/credential.ts`
+- Create: `app/[event]/booth-session/credential.test.ts`
+- Create: `app/[event]/booth-session/access.ts`
+- Create: `app/[event]/booth-session/access.test.ts`
+- Create: `app/[event]/booth-unlock.tsx`
+- Create: `app/[event]/booth-unlock.test.tsx`
+- Modify: `app/[event]/page.tsx`
+- Modify: `app/[event]/booth.module.css`
+
+**Interfaces:**
+- Consumes: Task 3 preflight response and Task 1 Session auth-required callback.
+- Produces: credential persistence and a tested Booth access state machine.
+- Consumed by: Tasks 5 and 7.
+
+- [ ] **Step 1: Write failing persistence and access-state tests**
+
+```ts
+expect(loadBoothCredential("launch", session, local)).toEqual({
+  key: "session-key",
+  persistence: "session",
+});
+
+saveBoothCredential("launch", "remembered-key", true, session, local);
+expect(session.getItem("webbooth:launch:booth-key")).toBeNull();
+expect(local.getItem("webbooth:launch:booth-key")).toBe("remembered-key");
+
+clearBoothCredential("launch", session, local);
+expect(session.length).toBe(0);
+expect(local.length).toBe(0);
+```
+
+Add pure transition tests for:
+
+```text
+locked → checking → ready
+                 ↘ recovery-only
+                 ↘ unavailable
+401 → locked
+operator exit → exited
+```
+
+Add static markup tests proving the unlock form exposes a password input and
+“Remember on this iPad” checkbox without rendering a supplied secret.
+
+- [ ] **Step 2: Run tests and verify missing modules**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/credential.test.ts' \
+  'app/[event]/booth-session/access.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Expected: FAIL because the modules do not exist.
+
+- [ ] **Step 3: Implement credential persistence**
+
+```ts
+export type StoredCredential = {
+  key: string;
+  persistence: "session" | "local";
+};
+
+export function loadBoothCredential(event, session, local): StoredCredential | null;
+export function saveBoothCredential(event, key, remember, session, local): void;
+export function clearBoothCredential(event, session, local): void;
+```
+
+Default saves use `sessionStorage`. The explicit remember option moves the key
+to `localStorage`. Clearing removes both. Storage failures retain an in-memory
+key for the current page without claiming persistence.
+
+- [ ] **Step 4: Implement access state and unlock form**
+
+```ts
+export type BoothAccessState =
+  | "locked" | "checking" | "ready" | "recovery-only"
+  | "unavailable" | "exited";
+```
+
+The unlock form uses labeled controls, an error/status region, and a retry
+preflight action. It accepts callbacks and never owns Outbox or camera state.
+
+- [ ] **Step 5: Integrate preflight before camera**
+
+In `page.tsx`:
+
+1. Construct and recover the Photo Outbox before reading credentials.
+2. Remove `window.prompt` and the public `/api/config` startup fetch.
+3. Load a stored credential and attempt preflight.
+4. Install enabled Frames only from a successful preflight.
+5. Start Session retry and camera only after success.
+6. Enter `recovery-only` on network failure while retaining pending state.
+7. Enter `unavailable` on `409` or `503`.
+8. Clear both credential stores, keep Outbox, and relock on preflight/upload `401`.
+9. Disable camera and file fallback outside `ready`.
+
+- [ ] **Step 6: Run focused and full verification**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/credential.test.ts' \
+  'app/[event]/booth-session/access.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add 'app/[event]/booth-session' 'app/[event]/booth-unlock.tsx' \
+  'app/[event]/booth-unlock.test.tsx' 'app/[event]/page.tsx' \
+  'app/[event]/booth.module.css'
+git commit -m "feat: unlock booths with authenticated preflight"
+```
+
+### Task 5: Poll pause state and report private Booth heartbeat
+
+**Files:**
+- Create: `app/[event]/booth-session/operational-client.ts`
+- Create: `app/[event]/booth-session/operational-client.test.ts`
+- Create: `app/[event]/booth-session/device-identity.ts`
+- Create: `app/[event]/booth-session/device-identity.test.ts`
+- Modify: `app/[event]/page.tsx`
+- Modify: `app/[event]/booth.module.css`
+
+**Interfaces:**
+- Consumes: Task 2 types, Task 3 routes, Task 4 credential/access state, and Task 1 upload state.
+- Produces: non-overlapping pause polling, bounded heartbeat reporting, and stable device identity.
+
+- [ ] **Step 1: Write failing device and client-controller tests**
+
+Test that `loadOrCreateDeviceId()` returns the stored lowercase UUID-v4,
+creates one when missing, and falls back to a session-only ID if local storage
+throws. Clearing Booth credentials must not clear the device ID.
+
+Using injected fetch, clock, and timer fakes, test:
+
+- Immediate poll plus completion-driven 5-second scheduling.
+- No overlapping state requests.
+- Poll failure retains the last-known pause value and reports disconnected.
+- Heartbeat sends immediately, every 15 seconds, and after a coalesced state change.
+- Heartbeat failure never rejects the caller or blocks Session work.
+- Heartbeat `401` invokes the auth-required callback.
+- `stop()` aborts requests and timers.
+
+- [ ] **Step 2: Run tests and verify missing modules**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/device-identity.test.ts' \
+  'app/[event]/booth-session/operational-client.test.ts'
+```
+
+Expected: FAIL because the modules do not exist.
+
+- [ ] **Step 3: Implement device identity and controllers**
+
+```ts
+export function loadOrCreateDeviceId(
+  storage: Pick<Storage, "getItem" | "setItem">,
+  makeId: () => string = () => crypto.randomUUID()
+): string;
+
+export class BoothStatePoller {
+  start(): void;
+  refresh(): Promise<void>;
+  stop(): void;
+}
+
+export class BoothHeartbeatReporter {
+  start(): void;
+  update(snapshot: BoothHeartbeatInput): void;
+  flush(): Promise<void>;
+  stop(): void;
+}
+```
+
+Use `setTimeout` only after a request settles. Heartbeat payload construction
+must explicitly enumerate every allowed field and use only bounded error
+classes.
+
+- [ ] **Step 4: Integrate pause semantics**
+
+In the Booth page:
+
+- At picker or Frame-ready, pause clears the Frame, blocks capture/file input,
+  and stops all camera tracks.
+- During active capture or durable handoff, pause allows the operation to
+  finish, returns to the fresh picker, then stops the camera.
+- Resume restarts the camera after the server is observed unpaused.
+- Poll failure retains last-known state and shows a connectivity indicator.
+- Session retry continues regardless of pause.
+
+- [ ] **Step 5: Integrate heartbeat snapshots**
+
+Generate one device ID independent of credentials. Send session start,
+pending count, durable-storage flag, online/installed status, bounded camera
+and upload states, last successful upload time, sanitized error class, and
+`process.env.NEXT_PUBLIC_BUILD_ID ?? "development"`. Never send arbitrary
+exception messages. Start after preflight; stop on unmount or exit.
+
+- [ ] **Step 6: Run tests and build**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/device-identity.test.ts' \
+  'app/[event]/booth-session/operational-client.test.ts' \
+  'app/[event]/booth-session/session.test.ts'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add 'app/[event]/booth-session' 'app/[event]/page.tsx' 'app/[event]/booth.module.css'
+git commit -m "feat: pause and monitor booth sessions"
+```
+
+### Task 6: Add Admin pause controls and paged device status
+
+**Files:**
+- Create: `app/[event]/admin/booth-operations.ts`
+- Create: `app/[event]/admin/booth-operations.test.ts`
+- Create: `app/[event]/admin/booth-operations-panel.tsx`
+- Create: `app/[event]/admin/booth-operations-panel.test.tsx`
+- Modify: `app/[event]/admin/page.tsx`
+- Modify: `app/[event]/admin/admin.module.css`
+
+**Interfaces:**
+- Consumes: Task 3 Admin APIs and Task 2 safe Admin records.
+- Produces: pure page merging and an authenticated operational panel.
+
+- [ ] **Step 1: Write failing paging and static rendering tests**
+
+```ts
+expect(mergeBoothPages(
+  [{ deviceId: "a", lastSeenAt: "2026-07-24T00:00:00Z" }],
+  [{ deviceId: "a", lastSeenAt: "2026-07-24T00:01:00Z" },
+   { deviceId: "b", lastSeenAt: "2026-07-24T00:00:30Z" }]
+).map((record) => record.deviceId)).toEqual(["a", "b"]);
+```
+
+Render the panel to static markup and verify live/stale status, pending count,
+durable/degraded storage, installed mode, camera/upload state, build ID,
+pause/resume busy state, and absence of `boothKey`, hashes, and raw error text.
+
+- [ ] **Step 2: Run tests and verify missing components**
+
+Run:
+
+```bash
+bun test 'app/[event]/admin/booth-operations.test.ts' \
+  'app/[event]/admin/booth-operations-panel.test.tsx'
+```
+
+Expected: FAIL because the helpers and panel do not exist.
+
+- [ ] **Step 3: Implement pure paging and the operations panel**
+
+`mergeBoothPages()` deduplicates by device ID and retains the newest
+`lastSeenAt`. The panel accepts records, cursor, operational state, loading
+and mutation flags, an English message draft, and callbacks for refresh, load
+more, pause, and resume.
+
+Rows show abbreviated device ID, live/stale, last seen, session start, pending
+count, durable state, online, installed, camera, upload, last upload, bounded
+error class, and build ID.
+
+- [ ] **Step 4: Integrate authenticated Admin polling**
+
+After Admin authentication:
+
+- Fetch operational state and the first device page.
+- Refresh the first page every 15 seconds with a no-overlap guard.
+- Merge first-page refreshes with already loaded later pages.
+- Use the opaque cursor for “Load more”.
+- Preserve non-English messages when editing the default English message.
+- Disable pause/resume while `PUT /api/booth-state` is active.
+- Route `401` through the existing Admin invalidation.
+- Keep config, photos, moderation, and export usable when device polling fails.
+
+- [ ] **Step 5: Run Admin and full tests**
+
+Run:
+
+```bash
+bun test 'app/[event]/admin/booth-operations.test.ts' \
+  'app/[event]/admin/booth-operations-panel.test.tsx' \
+  'app/[event]/admin/admin-config-controls.test.tsx'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add 'app/[event]/admin'
+git commit -m "feat: control and inspect event booths"
+```
+
+### Task 7: Add installed Booth mode, wake behavior, and authenticated exit
+
+**Files:**
+- Create: `app/[event]/manifest.ts`
+- Create: `app/[event]/manifest.test.ts`
+- Create: `public/booth-icon.svg`
+- Create: `app/[event]/booth-session/installed-mode.ts`
+- Create: `app/[event]/booth-session/installed-mode.test.ts`
+- Create: `app/[event]/operator-controls.tsx`
+- Create: `app/[event]/operator-controls.test.tsx`
+- Modify: `app/layout.tsx`
+- Modify: `app/[event]/page.tsx`
+- Modify: `app/[event]/booth.module.css`
+
+**Interfaces:**
+- Consumes: Task 4 preflight/credential flow and Task 5 client controllers.
+- Produces: public per-Event manifest, standalone detection, wake management, navigation predicate, and verified operator exit.
+
+- [ ] **Step 1: Write failing manifest and installed-mode tests**
+
+Test that the `launch-night` manifest has:
+
+```ts
+{
+  id: "/launch-night",
+  start_url: "/launch-night",
+  scope: "/launch-night",
+  display: "standalone",
+  orientation: "landscape",
+}
+```
+
+and that its serialized form has no `?`, `boothKey`, credential, or hash.
+
+Test:
+
+```ts
+expect(isStandalone(() => ({ matches: true }), false)).toBe(true);
+expect(isStandalone(() => ({ matches: false }), true)).toBe(true);
+expect(shouldWarnBeforeUnload({
+  captureActive: false,
+  durableHandoffActive: false,
+  pendingCount: 0,
+})).toBe(false);
+expect(shouldWarnBeforeUnload({
+  captureActive: false,
+  durableHandoffActive: false,
+  pendingCount: 1,
+})).toBe(true);
+```
+
+Use a fake wake provider to test acquire, release, denied/unsupported fallback,
+and visible-page reacquisition.
+
+- [ ] **Step 2: Run tests and verify missing modules**
+
+Run:
+
+```bash
+bun test 'app/[event]/manifest.test.ts' \
+  'app/[event]/booth-session/installed-mode.test.ts' \
+  'app/[event]/operator-controls.test.tsx'
+```
+
+Expected: FAIL because the installed-mode files do not exist.
+
+- [ ] **Step 3: Implement the per-Event manifest and iOS metadata**
+
+Use `canonicalEvent()` for the dynamic Event. Return a black, landscape,
+standalone manifest with the Event path as ID/start/scope and
+`/booth-icon.svg` as an `"any maskable"` icon. Add root
+`appleWebApp.capable`, a black-translucent status bar, and the existing
+zoom-accessible viewport behavior. Never include a key or query string.
+
+- [ ] **Step 4: Implement installed-mode helpers**
+
+```ts
+export function isStandalone(
+  matchMedia: (query: string) => { matches: boolean },
+  navigatorStandalone?: boolean
+): boolean;
+
+export function shouldWarnBeforeUnload(input: {
+  captureActive: boolean;
+  durableHandoffActive: boolean;
+  pendingCount: number;
+}): boolean;
+
+export class ScreenWakeController {
+  request(): Promise<"active" | "unsupported" | "denied">;
+  release(): Promise<void>;
+}
+```
+
+Detect both `(display-mode: standalone)` and iOS `navigator.standalone`.
+Request wake on unlock/operator gestures and visible-page return. Show iPad
+Auto-Lock instructions when unsupported or denied. Register `beforeunload`
+only when the pure predicate is true.
+
+- [ ] **Step 5: Implement authenticated operator exit**
+
+The discoverable Operator control asks for a fresh Booth or Admin key and
+verifies it through preflight. On success:
+
+1. Stop camera tracks.
+2. Release Screen Wake Lock.
+3. Stop heartbeat/state polling and Session retry timers/lease.
+4. Clear active/session/local credential state.
+5. Return to the locked/exited screen.
+6. Leave every Outbox record intact.
+
+Failed verification changes no runtime resource or credential state.
+
+- [ ] **Step 6: Run installed-mode and full verification**
+
+Run:
+
+```bash
+bun test 'app/[event]/manifest.test.ts' \
+  'app/[event]/booth-session/installed-mode.test.ts' \
+  'app/[event]/operator-controls.test.tsx'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/layout.tsx 'app/[event]' public/booth-icon.svg
+git commit -m "feat: support installed booth operation"
+```
+
+Do not add a service worker in this task. The design makes it conditional on a
+failed installed-relaunch staging test. If evidence requires one, write a
+separate reviewed plan whose cache allowlist contains only the Booth shell,
+build-versioned static assets, icons, and Frame artwork, and explicitly
+excludes every API, photo, Admin, export, moderation, heartbeat, health, and
+rehearsal request plus the Outbox IndexedDB database.
+
+### Task 8: Add WebKit coverage, runbooks, and the Release 1 gate
+
+**Files:**
+- Modify: `package.json`
+- Modify: `bun.lock`
+- Create: `playwright.config.ts`
+- Create: `tests/booth-control.spec.ts`
+- Modify: `.github/workflows/verify.yml`
+- Modify: `docs/runbooks/pre-event-readiness.md`
+- Modify: `docs/runbooks/deployment.md`
+
+**Interfaces:**
+- Consumes: Tasks 1–7.
+- Produces: repeatable mocked-camera WebKit coverage and exact operator validation steps.
+
+- [ ] **Step 1: Add Playwright WebKit and a failing Booth control journey**
+
+Add `@playwright/test` as a dev dependency and:
+
+```json
+{
+  "scripts": {
+    "test:browser": "playwright test --project=webkit"
+  }
+}
+```
+
+Configure `bun dev` as the Playwright web server. In
+`tests/booth-control.spec.ts`, install a `MediaStream`-returning mocked
+`getUserMedia` before page load and intercept preflight, Booth state,
+heartbeat, and upload requests.
+
+The journey verifies:
+
+- Outbox recovery UI is available before unlock.
+- Camera is not requested before successful preflight.
+- Session-default and remembered unlock.
+- Wrong credential relocks without removing pending state.
+- Pause at picker stops camera.
+- Pause during capture finishes durable handoff before stopping.
+- Reconnect wakes retry and retains one acknowledged photo identity.
+- Operator exit stops camera and preserves pending count.
+- Page URL and manifest contain no credential.
+
+- [ ] **Step 2: Run the browser test and verify expected initial failure**
+
+Run:
+
+```bash
+bunx playwright install webkit
+bun run test:browser
+```
+
+Expected: FAIL until the route mocks and selectors match the completed Release
+1 UI; no production or staging service is contacted.
+
+- [ ] **Step 3: Complete browser fixtures and CI integration**
+
+Keep API interception scoped to the test context. Update
+`.github/workflows/verify.yml` to install WebKit and run `bun run
+test:browser` after the existing Bun tests and production build. Preserve all
+existing verification steps.
+
+- [ ] **Step 4: Update real-device runbooks**
+
+Add staging-first checks for:
+
+1. Valid unlock and camera readiness.
+2. Session-only versus remembered credential.
+3. Durable IndexedDB and reload recovery.
+4. Offline captures, automatic reconnect drain, and no duplicate after lost acknowledgment.
+5. Two-tab Event lease behavior.
+6. Pause at picker and during a real multi-shot capture.
+7. Heartbeat live/stale transitions in Admin.
+8. Add-to-Home-Screen canonical launch and landscape standalone mode.
+9. Wake behavior and iPad Auto-Lock fallback.
+10. Authenticated exit releasing camera/wake while preserving pending photos.
+
+Use a throwaway canonical staging Event distinct from production. Any
+moderation cleanup uses one complete Event-owned image key.
+
+- [ ] **Step 5: Run the complete automated Release 1 gate**
+
+Run:
+
+```bash
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+bun run test:browser
+```
+
+Expected: every command exits 0.
+
+- [ ] **Step 6: Perform required real-iPad staging validation**
+
+Automated tests do not prove:
+
+- Real Safari camera permission, orientation, crop, or camera indicator shutdown.
+- Add-to-Home-Screen launch into the canonical Event.
+- Real standalone/background/foreground behavior.
+- Screen Wake Lock or Auto-Lock fallback behavior on the target iPadOS.
+- IndexedDB survival across Safari and installed-mode relaunch.
+- Cross-tab lease behavior in Safari.
+- Venue-network offline/reconnect timing and lost-acknowledgment recovery.
+- Pause timing during a real multi-shot capture.
+- Camera and wake release during operator exit.
+
+Follow `docs/runbooks/deployment.md`, deploy only the named staging
+environment, and stop promotion if any check fails.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add package.json bun.lock playwright.config.ts tests/booth-control.spec.ts \
+  .github/workflows/verify.yml docs/runbooks/pre-event-readiness.md \
+  docs/runbooks/deployment.md
+git commit -m "test: verify reliable booth control"
+```
+
+## Dependency Order
+
+1. Task 1 requires Release 0B.
+2. Task 2 is independent of Task 1.
+3. Task 3 requires Task 2 and Release 0B shared auth.
+4. Task 4 requires Task 3.
+5. Task 5 requires Tasks 1, 3, and 4.
+6. Task 6 requires Task 3 and may proceed independently of Task 5.
+7. Task 7 requires Tasks 4 and 5.
+8. Task 8 follows Tasks 1–7.
+
+## Final Safety Review
+
+- Heartbeats, pause state, and device IDs exist only in `STATE`.
+- Preflight explicitly constructs `EventExperience`; it never serializes private config.
+- No credential is placed in a URL, manifest, heartbeat, public object, or log.
+- Pause never deletes or suspends the Photo Outbox drain.
+- Operator exit preserves every pending item.
+- IndexedDB changes add one store and preserve old rows.
+- Fresh capture remains impossible without online authenticated preflight.
+- Frame choice returns fresh after every completed capture.
+- No unnamed Wrangler environment is deployed.

From 450220549925f1317bde72efc746013f6de5c6d7 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:12:19 +0800
Subject: [PATCH 023/105] fix: validate upload identity before config migration

---
 app/api/upload/handlers.ts   | 23 +++++++++++++----------
 app/api/upload/route.test.ts | 28 +++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/app/api/upload/handlers.ts b/app/api/upload/handlers.ts
index 4aa35bb..c4581fc 100644
--- a/app/api/upload/handlers.ts
+++ b/app/api/upload/handlers.ts
@@ -39,17 +39,8 @@ export async function handleUpload(req: NextRequest, deps: UploadHandlerDeps): P
   if (event instanceof NextResponse) return event;
 
   const provided = req.headers.get("x-booth-key") ?? "";
-  // The overwhelmingly common Admin-Key path requires no config read (and
-  // therefore cannot trigger a compatibility migration before body/header
-  // validation). Only an otherwise unauthorized request looks up an Event's
-  // private Booth Key hash.
   let auth = await boothOrAdminOk(provided, deps.adminKey);
-  if (auth === "unauthorized") {
-    const config = await deps.store.readConfig(event);
-    auth = await boothOrAdminOk(provided, deps.adminKey, config?.boothKeyHash);
-  }
   if (auth === "disabled") return jsonError("upload disabled: no key configured", 503);
-  if (auth !== "ok") return jsonError("unauthorized", 401);
 
   // Early reject via declared size before buffering the whole body.
   if (declaredSizeTooLarge(req)) return jsonError("too large", 413);
@@ -64,6 +55,15 @@ export async function handleUpload(req: NextRequest, deps: UploadHandlerDeps): P
     throw error;
   }
 
+  // Resolve the private Event-scoped Booth Key only after strict upload-header
+  // validation. readConfig() may lazily migrate a legacy public config, so
+  // calling it earlier would let an invalid request write to STATE.
+  if (auth === "unauthorized") {
+    const config = await deps.store.readConfig(event);
+    auth = await boothOrAdminOk(provided, deps.adminKey, config?.boothKeyHash);
+  }
+  if (auth !== "ok") return jsonError("unauthorized", 401);
+
   const body = await req.arrayBuffer();
   if (body.byteLength === 0) return jsonError("empty body", 400);
   if (body.byteLength > MAX_UPLOAD_BYTES) return jsonError("too large", 413);
@@ -79,7 +79,10 @@ export async function handleUpload(req: NextRequest, deps: UploadHandlerDeps): P
   } catch (error) {
     if (error instanceof PhotoIndexWriteError) {
       // An acknowledged stable client can safely retry this exact identity.
-      return jsonError("photo index unavailable", 503, { "Retry-After": "1" });
+      return NextResponse.json(
+        { error: "photo index unavailable", retryable: true },
+        { status: 503, headers: { "Retry-After": "1" } }
+      );
     }
     throw error;
   }
diff --git a/app/api/upload/route.test.ts b/app/api/upload/route.test.ts
index 763e24f..22ecc83 100644
--- a/app/api/upload/route.test.ts
+++ b/app/api/upload/route.test.ts
@@ -3,6 +3,7 @@ import { NextRequest } from "next/server";
 import {
   EventStore,
   InMemoryObjectStore,
+  legacyEventConfigKey,
   type ObjectStore,
   type StoredObjectBody,
   type StoredObject,
@@ -145,6 +146,28 @@ describe("upload route", () => {
     expect((await state.list()).objects).toHaveLength(0);
   });
 
+  test("invalid stable identity cannot trigger lazy legacy-config migration", async () => {
+    const boothKey = "event-key-123";
+    const boothKeyHash = await hashBoothKey(boothKey);
+    const { photos, state, deps } = memoryDeps();
+    photos.set(
+      legacyEventConfigKey("launch"),
+      JSON.stringify({ frames: ["square"], boothKeyHash })
+    );
+
+    const response = await handleUpload(request("launch", {
+      headers: { "x-booth-key": boothKey, "x-capture-id": CAPTURE_ID },
+    }), deps);
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({ error: "incomplete_capture_identity" });
+    expect((await state.list()).objects).toHaveLength(0);
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(0);
+    expect((await photos.list()).objects.map((object) => object.key)).toEqual([
+      legacyEventConfigKey("launch"),
+    ]);
+  });
+
   test("rejects canonical aliases and unauthorized uploads without writes", async () => {
     const alias = memoryDeps();
     const aliasResponse = await handleUpload(request("Launch", { headers: stableHeaders() }), alias.deps);
@@ -196,7 +219,10 @@ describe("upload route", () => {
 
     expect(first.status).toBe(503);
     expect(first.headers.get("Retry-After")).toBe("1");
-    expect(await first.json()).toEqual({ error: "photo index unavailable" });
+    expect(await first.json()).toEqual({
+      error: "photo index unavailable",
+      retryable: true,
+    });
     expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
 
     state.allowWrites();

From a550fc7bf5fe43efa618f5b5dbfdbef456a52d37 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:17:00 +0800
Subject: [PATCH 024/105] feat: upload stable identity from the durable outbox

---
 app/[event]/booth-session/outbox.ts       |  7 ++
 app/[event]/booth-session/session.test.ts | 92 ++++++++++++++++++++---
 app/[event]/booth-session/session.ts      | 26 +++++--
 app/[event]/booth-session/upload.test.ts  | 59 +++++++++++++++
 app/[event]/booth-session/upload.ts       | 31 ++++++++
 app/[event]/page.tsx                      | 37 +++++++--
 6 files changed, 225 insertions(+), 27 deletions(-)
 create mode 100644 app/[event]/booth-session/upload.test.ts
 create mode 100644 app/[event]/booth-session/upload.ts

diff --git a/app/[event]/booth-session/outbox.ts b/app/[event]/booth-session/outbox.ts
index 7c1eb89..95a023f 100644
--- a/app/[event]/booth-session/outbox.ts
+++ b/app/[event]/booth-session/outbox.ts
@@ -1,3 +1,5 @@
+import type { CaptureMetadata } from "../../upload-contract";
+
 export type OutboxItem = {
   id: string;
   event: string;
@@ -5,6 +7,11 @@ export type OutboxItem = {
   createdAt: number;
   attempts: number;
   lastError?: string;
+  nextAttemptAt?: number;
+  /** Optional so rows saved by earlier Booth versions remain readable. */
+  metadata?: CaptureMetadata;
+  /** Reserved for the operator rehearsal flow; durable rows retain it verbatim. */
+  rehearsalId?: string;
 };
 
 export interface OutboxStore {
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index b632264..97adb9d 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { createOutboxStore, MemoryOutboxStore } from "./outbox";
+import { createOutboxStore, MemoryOutboxStore, type OutboxItem } from "./outbox";
 import { BoothSession, runCaptureSequence } from "./session";
+import { outboxUploadHeaders } from "./upload";
 
 const photo = (name: string) => new Blob([name], { type: "image/jpeg" });
 const text = (blob: Blob) => blob.text();
@@ -9,25 +10,31 @@ describe("BoothSession outbox", () => {
   test("retains an older failure when a later capture is queued, then recovers in order", async () => {
     const store = new MemoryOutboxStore();
     const attempted: string[] = [];
+    const uploadIdentities: Array<{ id: string; headers: Record<string, string> }> = [];
     let offline = true;
     let nextId = 0;
     const session = new BoothSession(
       "party",
       store,
-      async (blob) => {
-        attempted.push(await text(blob));
+      async (item) => {
+        attempted.push(await text(item.blob));
+        uploadIdentities.push({ id: item.id, headers: outboxUploadHeaders(item) });
         if (offline) throw new Error("venue Wi-Fi offline");
-        return { url: `/photos/${await text(blob)}` };
+        return { url: `/photos/${await text(item.blob)}` };
       },
       () => {},
-      () => String(++nextId),
-      () => nextId
+      () => `018f0000-0000-4000-8000-${String(++nextId).padStart(12, "0")}`,
+      () => 1753315200000 + nextId
     );
 
     await session.recover();
-    await session.enqueueCapture(async () => photo("first"));
+    const first = await session.enqueueCapture(async () => photo("first"), {
+      metadata: { source: "framed", frameKey: "square" },
+    });
     await session.process();
-    await session.enqueueCapture(async () => photo("second"));
+    const second = await session.enqueueCapture(async () => photo("second"), {
+      metadata: { source: "camera-fallback" },
+    });
 
     const failedQueue = await store.list("party");
     await expect(Promise.all(failedQueue.map((item) => text(item.blob)))).resolves.toEqual(["first", "second"]);
@@ -36,9 +43,10 @@ describe("BoothSession outbox", () => {
     // A reload creates a new session over the same durable store.
     offline = false;
     const recoveredUrls: string[] = [];
-    const recovered = new BoothSession("party", store, async (blob) => {
-      attempted.push(await text(blob));
-      return { url: `/photos/${await text(blob)}` };
+    const recovered = new BoothSession("party", store, async (item) => {
+      attempted.push(await text(item.blob));
+      uploadIdentities.push({ id: item.id, headers: outboxUploadHeaders(item) });
+      return { url: `/photos/${await text(item.blob)}` };
     }, ({ url }) => recoveredUrls.push(url));
     const states: string[] = [];
     recovered.subscribe((state) => states.push(`${state.status}:${state.pendingCount}:${state.error ?? ""}`));
@@ -46,6 +54,13 @@ describe("BoothSession outbox", () => {
     await recovered.retry();
 
     expect(attempted).toEqual(["first", "first", "second"]);
+    expect(first.id).toBe(failedQueue[0].id);
+    expect(second.id).toBe(failedQueue[1].id);
+    expect(uploadIdentities).toEqual([
+      { id: first.id, headers: outboxUploadHeaders(first) },
+      { id: first.id, headers: outboxUploadHeaders(first) },
+      { id: second.id, headers: outboxUploadHeaders(second) },
+    ]);
     expect(recoveredUrls).toEqual(["/photos/first", "/photos/second"]);
     expect(await store.list("party")).toEqual([]);
     expect(states.at(-1)).toBe("idle:0:");
@@ -59,11 +74,64 @@ describe("BoothSession outbox", () => {
       await Promise.resolve();
       return { url: "/photo" };
     });
-    await session.enqueueCapture(async () => photo("one"));
+    await session.enqueueCapture(async () => photo("one"), { metadata: { source: "camera-fallback" } });
     await Promise.all([session.process(), session.process(), session.process()]);
     expect(uploads).toBe(1);
   });
 
+  test("persists one identity and metadata before upload", async () => {
+    const store = new MemoryOutboxStore();
+    const seen: OutboxItem[] = [];
+    const session = new BoothSession(
+      "launch",
+      store,
+      async (item) => {
+        seen.push(item);
+        return { url: "/photo", key: "launch/photo.jpg" };
+      },
+      () => {},
+      () => "018f0000-0000-4000-8000-000000000001",
+      () => 1753315200000
+    );
+
+    const item = await session.enqueueCapture(
+      async () => new Blob(["photo"], { type: "image/jpeg" }),
+      { metadata: { source: "framed", frameKey: "square" } }
+    );
+
+    expect(item).toMatchObject({
+      id: "018f0000-0000-4000-8000-000000000001",
+      createdAt: 1753315200000,
+      metadata: { capturedAt: 1753315200000, source: "framed", frameKey: "square" },
+    });
+    expect(await store.list("launch")).toEqual([item]);
+    await session.process();
+    expect(seen).toEqual([item]);
+  });
+
+  test("allocates identity only after capture succeeds", async () => {
+    const store = new MemoryOutboxStore();
+    let ids = 0;
+    const session = new BoothSession(
+      "launch",
+      store,
+      async () => ({ url: "/photo" }),
+      () => {},
+      () => {
+        ids++;
+        return "018f0000-0000-4000-8000-000000000001";
+      }
+    );
+
+    await expect(session.enqueueCapture(
+      async () => Promise.reject(new Error("composite failed")),
+      { metadata: { source: "framed", frameKey: "square" } }
+    )).rejects.toThrow("composite failed");
+
+    expect(ids).toBe(0);
+    expect(await store.list("launch")).toEqual([]);
+  });
+
   test("memory store keeps events isolated and items ordered", async () => {
     const store = new MemoryOutboxStore();
     await store.put({ id: "b", event: "party", blob: photo("later"), createdAt: 2, attempts: 0 });
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index c0dd4fe..6799bed 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -1,4 +1,5 @@
 import type { OutboxItem, OutboxStore } from "./outbox";
+import type { CaptureMetadata } from "../../upload-contract";
 
 export type UploadState = {
   status: "idle" | "uploading" | "failed";
@@ -7,8 +8,14 @@ export type UploadState = {
   durable: boolean;
 };
 
-type UploadResult = { url: string };
-type Upload = (blob: Blob) => Promise<UploadResult>;
+export type UploadResult = { url: string; key?: string; duplicate?: boolean };
+export type Upload = (item: OutboxItem) => Promise<UploadResult>;
+
+export type EnqueueCaptureOptions = {
+  signal?: AbortSignal;
+  metadata: Omit<CaptureMetadata, "capturedAt">;
+  rehearsalId?: string;
+};
 
 export class BoothSession {
   private state: UploadState = { status: "idle", pendingCount: 0, error: null, durable: true };
@@ -48,21 +55,26 @@ export class BoothSession {
   }
 
   /** The capture adapter owns camera/file decoding; the session owns durable handoff. */
-  async enqueueCapture(capture: (signal?: AbortSignal) => Promise<Blob>, signal?: AbortSignal) {
-    const blob = await capture(signal);
-    if (signal?.aborted) throw abortError();
+  async enqueueCapture(
+    capture: (signal?: AbortSignal) => Promise<Blob>,
+    options: EnqueueCaptureOptions
+  ) {
+    const blob = await capture(options.signal);
+    if (options.signal?.aborted) throw abortError();
     // Preserve enqueue order even if two captures share a millisecond or the
     // device clock moves backwards while the booth is running.
     const createdAt = Math.max(this.now(), this.lastCreatedAt + 1);
-    this.lastCreatedAt = createdAt;
     const item: OutboxItem = {
       id: this.makeId(),
       event: this.event,
       blob,
       createdAt,
       attempts: 0,
+      metadata: { ...options.metadata, capturedAt: createdAt },
+      ...(options.rehearsalId === undefined ? {} : { rehearsalId: options.rehearsalId }),
     };
     await this.store.put(item);
+    this.lastCreatedAt = createdAt;
     const pending = await this.store.list(this.event);
     this.publish({
       status: this.state.status === "failed" ? "failed" : "idle",
@@ -97,7 +109,7 @@ export class BoothSession {
         durable: this.store.isDurable(),
       });
       try {
-        const result = await this.upload(item.blob);
+        const result = await this.upload(item);
         await this.store.remove(item.id);
         this.onUploaded(result);
         pending = await this.store.list(this.event);
diff --git a/app/[event]/booth-session/upload.test.ts b/app/[event]/booth-session/upload.test.ts
new file mode 100644
index 0000000..a608dfc
--- /dev/null
+++ b/app/[event]/booth-session/upload.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { outboxUploadHeaders } from "./upload";
+
+const blob = new Blob(["photo"], { type: "image/jpeg" });
+
+describe("outboxUploadHeaders", () => {
+  test("old rows gain stable headers from id and createdAt", () => {
+    const item = {
+      id: "018f0000-0000-4000-8000-000000000001",
+      event: "launch",
+      blob,
+      createdAt: 1753315200000,
+      attempts: 0,
+    };
+    expect(outboxUploadHeaders(item)).toEqual({
+      "x-capture-id": item.id,
+      "x-captured-at": "1753315200000",
+    });
+  });
+
+  test("uses persisted optional metadata when it is valid", () => {
+    expect(outboxUploadHeaders({
+      id: "018f0000-0000-4000-8000-000000000001",
+      event: "launch",
+      blob,
+      createdAt: 1753315200000,
+      attempts: 0,
+      metadata: {
+        capturedAt: 1753315200999,
+        source: "framed",
+        frameKey: "square",
+        configRevisionId: "release_1",
+      },
+    })).toEqual({
+      "x-capture-id": "018f0000-0000-4000-8000-000000000001",
+      "x-captured-at": "1753315200999",
+      "x-capture-source": "framed",
+      "x-frame-key": "square",
+      "x-config-revision-id": "release_1",
+    });
+  });
+
+  test("an invalid historical ID or timestamp falls back to the legacy upload contract", () => {
+    expect(outboxUploadHeaders({
+      id: "old-non-uuid-id",
+      event: "launch",
+      blob,
+      createdAt: 1753315200000,
+      attempts: 0,
+    })).toEqual({});
+    expect(outboxUploadHeaders({
+      id: "018f0000-0000-4000-8000-000000000001",
+      event: "launch",
+      blob,
+      createdAt: 1,
+      attempts: 0,
+    })).toEqual({});
+  });
+});
diff --git a/app/[event]/booth-session/upload.ts b/app/[event]/booth-session/upload.ts
new file mode 100644
index 0000000..efb8c50
--- /dev/null
+++ b/app/[event]/booth-session/upload.ts
@@ -0,0 +1,31 @@
+import {
+  InvalidUploadHeadersError,
+  parseUploadHeaders,
+  stableUploadHeaders,
+} from "../../upload-contract";
+import type { OutboxItem } from "./outbox";
+
+/**
+ * Adapts a durable row into the additive stable-upload protocol. Historical
+ * queue rows can predate stable identity, so malformed legacy data must still
+ * use the random-key upload path instead of wedging the ordered outbox.
+ */
+export function outboxUploadHeaders(item: OutboxItem): Record<string, string> {
+  const headers = stableUploadHeaders({
+    captureId: item.id,
+    capturedAt: item.metadata?.capturedAt ?? item.createdAt,
+    source: item.metadata?.source,
+    frameKey: item.metadata?.frameKey,
+    configRevisionId: item.metadata?.configRevisionId,
+  });
+
+  try {
+    // stableUploadHeaders deliberately only serializes. Validate its result so
+    // old IndexedDB rows with non-UUID ids/timestamps fall back safely.
+    parseUploadHeaders(new Headers(headers));
+    return headers;
+  } catch (error) {
+    if (error instanceof InvalidUploadHeadersError) return {};
+    throw error;
+  }
+}
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 24146be..dc84da0 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -4,8 +4,9 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { useParams } from "next/navigation";
 import styles from "./booth.module.css";
 import { TEMPLATES, availableTemplates, composite } from "../templates";
-import { createOutboxStore } from "./booth-session/outbox";
+import { createOutboxStore, type OutboxItem } from "./booth-session/outbox";
 import { BoothSession, runCaptureSequence, type UploadState } from "./booth-session/session";
+import { outboxUploadHeaders } from "./booth-session/upload";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
 
@@ -32,11 +33,15 @@ export default function Booth() {
   // per-event frame allowlist from /api/config; null (no config / not loaded
   // yet / fetch failed) degrades to defaults-only, never to all frames
   const [enabled, setEnabled] = useState<string[] | null>(null);
+  const [configRevisionId, setConfigRevisionId] = useState<string | undefined>();
 
   useEffect(() => {
     fetch(`/api/config?event=${encodeURIComponent(event)}`)
       .then((r) => r.json())
-      .then((d) => setEnabled(Array.isArray(d.frames) ? d.frames : null))
+      .then((d) => {
+        setEnabled(Array.isArray(d.frames) ? d.frames : null);
+        setConfigRevisionId(typeof d.currentRevisionId === "string" ? d.currentRevisionId : undefined);
+      })
       .catch(() => {});
   }, [event]);
 
@@ -108,11 +113,15 @@ export default function Booth() {
   }, []);
 
   const uploadOne = useCallback(
-    async (blob: Blob) => {
+    async (item: OutboxItem) => {
       const res = await fetch(`/api/upload?event=${encodeURIComponent(event)}`, {
         method: "POST",
-        headers: { "x-booth-key": keyRef.current, "content-type": "image/jpeg" },
-        body: blob,
+        headers: {
+          "x-booth-key": keyRef.current,
+          "content-type": "image/jpeg",
+          ...outboxUploadHeaders(item),
+        },
+        body: item.blob,
       });
       if (res.status === 401) {
         localStorage.removeItem(storageKey);
@@ -120,7 +129,7 @@ export default function Booth() {
         throw new Error("Wrong booth key — tap Retry to re-enter it");
       }
       if (!res.ok) throw new Error(`Upload failed (${res.status}) — tap Retry`);
-      return res.json() as Promise<{ url: string }>;
+      return res.json() as Promise<{ url: string; key?: string; duplicate?: boolean }>;
     },
     [event, storageKey]
   );
@@ -172,7 +181,14 @@ export default function Booth() {
           });
           return composite(frames, frames.map((f) => ({ w: f.width, h: f.height })), t);
         },
-        controller.signal
+        {
+          signal: controller.signal,
+          metadata: {
+            source: "framed",
+            frameKey: mode,
+            ...(configRevisionId ? { configRevisionId } : {}),
+          },
+        }
       );
       // Durable handoff is complete. Return to the picker before uploading so
       // the next guest is never trapped on the previous guest's frame.
@@ -221,6 +237,11 @@ export default function Booth() {
             // Undecodable file: preserve it; the server signature check decides.
           }
           return blob;
+        }, {
+          metadata: {
+            source: "camera-fallback",
+            ...(configRevisionId ? { configRevisionId } : {}),
+          },
         });
         setError(null);
         void session.process();
@@ -228,7 +249,7 @@ export default function Booth() {
         setError(uploadError instanceof Error ? uploadError.message : String(uploadError));
       }
     },
-    []
+    [configRevisionId]
   );
 
   const pick = (m: keyof typeof TEMPLATES) => {

From 2df641a49e9a7c1ae839c8ae20cf81c7d024d26b Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:20:24 +0800
Subject: [PATCH 025/105] docs: plan guest capture improvements

---
 .../2026-07-24-release-2-guest-capture.md     | 869 ++++++++++++++++++
 1 file changed, 869 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-24-release-2-guest-capture.md

diff --git a/docs/superpowers/plans/2026-07-24-release-2-guest-capture.md b/docs/superpowers/plans/2026-07-24-release-2-guest-capture.md
new file mode 100644
index 0000000..f3a6986
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-24-release-2-guest-capture.md
@@ -0,0 +1,869 @@
+# Release 2 Guest Capture Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add exact-composite review and Retake, guarded acceptance, exact-current-photo QR handoff, and the first complete localized and accessibility-aware guest flow.
+
+**Architecture:** Composition produces an unencoded canvas. A pure capture-flow reducer and guarded decision gate own review state; only the winning acceptance encodes and hands one JPEG to the Booth Session. The Session reports acknowledgements with both the exact Outbox item and server result so a pure handoff reducer can ignore stale uploads. Release 2 also creates a minimal exact-photo `/{event}/gallery?photo=` shell because the QR must work now; Release 3 expands that route without changing its direct-photo contract.
+
+**Tech Stack:** Bun, TypeScript, Next.js 15 App Router, React 19, Canvas, IndexedDB, Web Audio, local `qrcode`, Cloudflare Workers/R2, Playwright WebKit.
+
+## Global Constraints
+
+- Start only after Release 0B stable Outbox identity/idempotent upload and Release 1 Booth control pass their complete gates.
+- Use Bun commands only.
+- The Booth Session remains the owner of accepted-photo durability, ordered upload, retry, and acknowledgement.
+- `EventStore` remains the only owner of `PHOTOS` keys, exact Event-owned photo validation, and public photo URLs.
+- Review shows the exact final composite canvas; composition never JPEG-encodes before acceptance.
+- Only one guarded acceptance may encode and enqueue a candidate.
+- Retake keeps the same Frame; durable acceptance clears the Frame immediately.
+- An older delayed acknowledgement never replaces or reopens the current guest handoff.
+- Offline/queued handoff never blocks the next guest and never invents a QR before acknowledgement.
+- Every QR is generated locally and has a visible text link.
+- The direct-photo endpoint exposes no receipt, index, revision, credential, heartbeat, or other private state.
+- Existing Outbox rows and legacy config locale tokens remain readable.
+- No service worker or iOS background-upload guarantee is added.
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+- Never silently slug an Event at an HTTP boundary.
+- Never deploy the unnamed Wrangler environment to an Event domain.
+
+---
+
+## File Structure
+
+- Create `app/i18n/catalog.ts` — complete typed guest message catalogs.
+- Create `app/i18n/catalog.test.ts` — catalog completeness and interpolation tests.
+- Create `app/i18n/locale.ts` — supported-locale resolution, persistence, and document direction.
+- Create `app/i18n/locale.test.ts` — fallback, storage, and RTL tests.
+- Modify `app/event-config.ts` — safe supported-locale helpers without breaking legacy reads.
+- Modify `app/event-config.test.ts` — locale and capture-setting validation.
+- Modify `app/api/config/handlers.ts` — save the complete allowlisted experience.
+- Modify `app/api/config/handlers.test.ts` — settings preservation and rejection tests.
+- Modify `app/frame-packs/types.ts` — optional localized Frame labels.
+- Modify `app/frame-packs/catalog.ts` — runtime label preservation.
+- Modify `app/frame-packs/validate.ts` — bounded localized-label validation.
+- Modify `app/frame-packs/validate.test.ts` — fallback and invalid-label tests.
+- Modify `app/[event]/admin/page.tsx` — load/save/restore capture and locale settings.
+- Modify `app/[event]/admin/admin-config-controls.tsx` — locale and capture controls.
+- Modify `app/[event]/admin/admin-config-controls.test.tsx` — control markup and disabled states.
+- Modify `app/[event]/admin/config-mutation.ts` — complete experience rebasing.
+- Modify `app/[event]/admin/config-mutation.test.ts` — setting preservation.
+- Modify `app/[event]/admin/config-history-panel.tsx` — summarize revision capture/locales.
+- Modify `app/[event]/admin/config-history-panel.test.tsx` — revision summary tests.
+- Modify `app/[event]/admin/admin.module.css` — settings controls.
+- Modify `app/templates.ts` — separate exact canvas composition from JPEG encoding.
+- Modify `app/templates.test.ts` — draw order and encoding-boundary tests.
+- Create `app/[event]/booth-session/review.ts` — guarded review timeout decisions.
+- Create `app/[event]/booth-session/review.test.ts` — timer/button race tests.
+- Create `app/[event]/booth-session/capture-flow.ts` — pure guest capture state reducer.
+- Create `app/[event]/booth-session/capture-flow.test.ts` — transition and stale-action tests.
+- Create `app/[event]/capture-review.tsx` — exact-canvas review presentation.
+- Create `app/[event]/capture-review.test.tsx` — accessible review markup.
+- Create `app/[event]/booth-session/countdown-audio.ts` — gesture-activated optional tones.
+- Create `app/[event]/booth-session/countdown-audio.test.ts` — activation and failure tests.
+- Modify `app/[event]/page.tsx` — review, acceptance, localization, audio, and pause integration.
+- Modify `app/[event]/booth.module.css` — review/handoff/accessibility styling.
+- Modify `app/event-store.ts` — exact public photo lookup.
+- Modify `app/event-store.test.ts` — exact ownership and privacy tests.
+- Create `app/api/photo/handlers.ts` — dependency-injected exact-photo handler.
+- Create `app/api/photo/handlers.test.ts` — canonical Event/key/error tests.
+- Create `app/api/photo/route.ts` — thin Cloudflare route adapter.
+- Create `app/[event]/gallery/page.tsx` — direct-photo Gallery route.
+- Create `app/[event]/gallery/handoff-gallery.tsx` — minimal exact-photo landing.
+- Create `app/[event]/gallery/handoff-gallery.test.tsx` — query/error/save markup tests.
+- Create `app/[event]/gallery/gallery.module.css` — phone-first landing styles.
+- Modify `app/[event]/booth-session/session.ts` — exact item acknowledgement callback.
+- Modify `app/[event]/booth-session/session.test.ts` — acknowledgement ordering/correlation.
+- Create `app/[event]/booth-session/handoff.ts` — pure current-handoff state and URL builder.
+- Create `app/[event]/booth-session/handoff.test.ts` — stale/delayed acknowledgement tests.
+- Create `app/[event]/handoff-panel.tsx` — local QR, visible link, and queued state.
+- Create `app/[event]/handoff-panel.test.tsx` — stale QR and link identity tests.
+- Create `tests/guest-capture.spec.ts` — mocked-camera WebKit guest journey.
+- Modify `docs/runbooks/pre-event-readiness.md` — real-iPad Release 2 checks.
+- Modify `docs/runbooks/deployment.md` — Release 2 staging gate.
+
+### Task 1: Add complete catalogs, locale resolution, localized Frame labels, and capture configuration
+
+**Files:**
+- Create: `app/i18n/catalog.ts`
+- Create: `app/i18n/catalog.test.ts`
+- Create: `app/i18n/locale.ts`
+- Create: `app/i18n/locale.test.ts`
+- Modify: `app/event-config.ts`
+- Modify: `app/event-config.test.ts`
+- Modify: `app/api/config/handlers.ts`
+- Modify: `app/api/config/handlers.test.ts`
+- Modify: `app/frame-packs/types.ts`
+- Modify: `app/frame-packs/catalog.ts`
+- Modify: `app/frame-packs/validate.ts`
+- Modify: `app/frame-packs/validate.test.ts`
+- Modify: `app/[event]/admin/page.tsx`
+- Modify: `app/[event]/admin/admin-config-controls.tsx`
+- Modify: `app/[event]/admin/admin-config-controls.test.tsx`
+- Modify: `app/[event]/admin/config-mutation.ts`
+- Modify: `app/[event]/admin/config-mutation.test.ts`
+- Modify: `app/[event]/admin/config-history-panel.tsx`
+- Modify: `app/[event]/admin/config-history-panel.test.tsx`
+- Modify: `app/[event]/admin/admin.module.css`
+
+**Interfaces:**
+- Consumes: Release 1 preflight `EventExperience`.
+- Produces: complete built-in `en`, `zh-SG`, and `ar` guest catalogs.
+- Produces: supported-locale selection and per-Event/device persistence.
+- Produces: localized Frame-label fallback and complete revision-aware Admin settings.
+
+- [ ] **Step 1: Write failing catalog, locale, and Frame-label tests**
+
+Test these contracts:
+
+```ts
+export const SUPPORTED_LOCALES = ["en", "zh-SG", "ar"] as const;
+export type SupportedLocale = typeof SUPPORTED_LOCALES[number];
+export type MessageKey = keyof typeof englishMessages;
+
+export function isSupportedLocale(value: unknown): value is SupportedLocale;
+export function message(
+  locale: SupportedLocale,
+  key: MessageKey,
+  values?: Record<string, string | number>
+): string;
+export function localeDirection(locale: SupportedLocale): "ltr" | "rtl";
+```
+
+Prove every catalog has exactly the English key set and the same interpolation
+placeholders. Prove English fallback, Arabic RTL, stored-locale precedence,
+configured-default/browser-language fallback, and Event-isolated persistence.
+
+Extend the Frame contract additively:
+
+```ts
+type FrameDefinition = {
+  label: string;
+  labels?: Partial<Record<SupportedLocale, string>>;
+  // existing fields unchanged
+};
+```
+
+Test localized lookup plus fallback to the required default `label`. Validator
+tests reject unsupported locale keys, blank labels, and labels longer than 80
+characters.
+
+- [ ] **Step 2: Run focused tests and verify missing-module failures**
+
+Run:
+
+```bash
+bun test app/i18n/catalog.test.ts app/i18n/locale.test.ts \
+  app/frame-packs/validate.test.ts
+```
+
+Expected: FAIL because catalog and locale modules do not exist.
+
+- [ ] **Step 3: Implement catalogs, locale resolution, and Frame labels**
+
+Add:
+
+```ts
+export function resolveEnabledLocales(
+  configured: readonly string[] | undefined
+): SupportedLocale[];
+
+export function resolveDeviceLocale(input: {
+  event: string;
+  configured: readonly string[] | undefined;
+  defaultLocale?: string;
+  storedLocale?: string | null;
+  navigatorLanguages?: readonly string[];
+}): SupportedLocale;
+
+export function saveDeviceLocale(
+  event: string,
+  locale: SupportedLocale,
+  storage: Pick<Storage, "setItem">
+): void;
+
+export function applyDocumentLocale(
+  documentElement: Pick<HTMLElement, "lang" | "dir">,
+  locale: SupportedLocale
+): void;
+
+export function frameLabel(
+  frame: Pick<FrameDefinition, "label" | "labels">,
+  locale: SupportedLocale
+): string;
+```
+
+Keep stored `LocaleCode` parsing permissive so old configuration remains
+readable. Runtime resolution intersects configured locales with the complete
+built-in catalogs and always retains English fallback.
+
+- [ ] **Step 4: Write failing configuration and Admin preservation tests**
+
+Test:
+
+- New saves accept only supported enabled/default locales.
+- `defaultLocale` must be enabled.
+- `autoAcceptSeconds` remains an integer from `1..30`.
+- Admin loads, saves, restores, and rebases locales, default locale,
+  `reviewEnabled`, `autoAcceptSeconds`, and `countdownAudioDefault`.
+- A save preserves existing `timeZone` and `gallery` values even though their
+  controls are outside this release.
+- Booth credentials remain preserved when unchanged and are never exposed.
+- History summaries make capture/locale changes visible.
+
+- [ ] **Step 5: Implement complete safe experience saving and controls**
+
+The config handler explicitly constructs the whole allowlisted
+`EventExperience`; never spread the request body. Keep frames-only requests
+compatible. The Admin retains every safe experience field returned by history,
+sends the complete experience, and updates all controls after restore.
+
+Controls expose:
+
+- Enabled locale checkboxes.
+- Default locale selector.
+- Review enabled.
+- Auto-accept seconds, default `5`.
+- Countdown audio default.
+
+Disable them under the existing config mutation guard.
+
+- [ ] **Step 6: Run focused and full checks**
+
+Run:
+
+```bash
+bun test app/i18n/catalog.test.ts app/i18n/locale.test.ts \
+  app/event-config.test.ts app/api/config/handlers.test.ts \
+  app/frame-packs/validate.test.ts \
+  'app/[event]/admin/admin-config-controls.test.tsx' \
+  'app/[event]/admin/config-mutation.test.ts' \
+  'app/[event]/admin/config-history-panel.test.tsx'
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/i18n app/event-config.ts app/event-config.test.ts \
+  app/api/config/handlers.ts app/api/config/handlers.test.ts \
+  app/frame-packs 'app/[event]/admin'
+git commit -m "feat: configure localized guest capture"
+```
+
+### Task 2: Separate exact canvas composition from encoding and guard review decisions
+
+**Files:**
+- Modify: `app/templates.ts`
+- Modify: `app/templates.test.ts`
+- Create: `app/[event]/booth-session/review.ts`
+- Create: `app/[event]/booth-session/review.test.ts`
+- Create: `app/[event]/booth-session/capture-flow.ts`
+- Create: `app/[event]/booth-session/capture-flow.test.ts`
+
+**Interfaces:**
+- Produces: an exact unencoded composite canvas and one JPEG encoding boundary.
+- Produces: a timer/button decision gate and pure capture-flow reducer.
+- Consumed by: Task 3.
+
+- [ ] **Step 1: Write failing composition-boundary and decision-race tests**
+
+Define:
+
+```ts
+export async function composeToCanvas(
+  frames: CanvasImageSource[],
+  frameSizes: { w: number; h: number }[],
+  template: Template
+): Promise<HTMLCanvasElement>;
+
+export function encodeCanvas(
+  canvas: HTMLCanvasElement,
+  quality?: number
+): Promise<Blob>;
+```
+
+Keep `composite()` as a compatibility wrapper over both functions. Tests prove
+background/photo/overlay draw order is unchanged and `composeToCanvas()` never
+calls `toBlob()` or `toDataURL()`.
+
+Define:
+
+```ts
+export type ReviewChoice = "accept" | "retake";
+
+export interface ReviewClock {
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+export class ReviewDecisionGate {
+  constructor(
+    autoAcceptSeconds: number,
+    onDecision: (choice: ReviewChoice) => void,
+    clock?: ReviewClock
+  );
+  start(): void;
+  accept(): boolean;
+  retake(): boolean;
+  moreTime(): boolean;
+  cancel(): void;
+}
+```
+
+Test five-second timeout, More Time cancellation, Retake-before-timeout,
+button/timer race, repeated clicks, and unmount cancellation.
+
+- [ ] **Step 2: Run focused tests and verify failures**
+
+Run:
+
+```bash
+bun test app/templates.test.ts \
+  'app/[event]/booth-session/review.test.ts' \
+  'app/[event]/booth-session/capture-flow.test.ts'
+```
+
+Expected: FAIL because the new APIs do not exist.
+
+- [ ] **Step 3: Implement composition and guarded decisions**
+
+The first `accept()`, `retake()`, or timer callback wins synchronously. Losing
+decisions return `false`. `moreTime()` cancels automatic acceptance without
+choosing, and `cancel()` prevents stale callbacks.
+
+Add a pure reducer:
+
+```ts
+type CapturePhase =
+  | "picker" | "ready" | "capturing"
+  | "reviewing" | "accepting" | "handoff";
+
+type ReviewCandidate = {
+  id: string;
+  source: "framed" | "camera-fallback";
+  frameKey?: string;
+  canvas: HTMLCanvasElement;
+};
+
+export function reduceCaptureFlow(
+  state: CaptureFlowState,
+  action: CaptureFlowAction
+): CaptureFlowState;
+```
+
+Required transitions:
+
+- Capture completion retains the Frame and enters review.
+- Retake returns to ready with the same Frame.
+- Acceptance synchronously enters `accepting`.
+- Encode/enqueue failure returns to review with no restarted timer.
+- Durable enqueue success clears the Frame and enters handoff.
+- Review-disabled capture moves directly to accepting.
+- Candidate IDs make stale callbacks/actions no-ops.
+
+- [ ] **Step 4: Run focused and full checks**
+
+Run:
+
+```bash
+bun test app/templates.test.ts \
+  'app/[event]/booth-session/review.test.ts' \
+  'app/[event]/booth-session/capture-flow.test.ts'
+bun run typecheck
+bun run typecheck:tests
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/templates.ts app/templates.test.ts 'app/[event]/booth-session'
+git commit -m "feat: guard exact composite review decisions"
+```
+
+### Task 3: Integrate review, Retake, More Time, localization, and countdown tones
+
+**Files:**
+- Create: `app/[event]/capture-review.tsx`
+- Create: `app/[event]/capture-review.test.tsx`
+- Create: `app/[event]/booth-session/countdown-audio.ts`
+- Create: `app/[event]/booth-session/countdown-audio.test.ts`
+- Modify: `app/[event]/page.tsx`
+- Modify: `app/[event]/booth.module.css`
+
+**Interfaces:**
+- Consumes: Tasks 1–2, Release 0B Outbox metadata, and Release 1 pause/access state.
+- Produces: exact-canvas guest review and one guarded durable acceptance.
+
+- [ ] **Step 1: Write failing review markup, acceptance, and audio tests**
+
+Define:
+
+```ts
+type CaptureReviewProps = {
+  canvas: HTMLCanvasElement;
+  autoAcceptSeconds: number;
+  accepting: boolean;
+  error: string | null;
+  labels: {
+    usePhoto: string;
+    retake: string;
+    moreTime: string;
+    accepting: string;
+    preview: string;
+  };
+  onAccept(): void;
+  onRetake(): void;
+  onMoreTime(): void;
+};
+```
+
+Test semantic canvas labeling, default-focus target, disabled accepting
+controls, status/error regions, and localized labels.
+
+Define:
+
+```ts
+export class CountdownToneController {
+  activate(): Promise<boolean>;
+  tick(count: number): void;
+  captured(): void;
+  dispose(): Promise<void>;
+}
+```
+
+Test that calls before activation are no-ops, activation requires an explicit
+caller gesture, unsupported/denied audio degrades silently, ticks are bounded,
+and disposal releases resources.
+
+- [ ] **Step 2: Run focused tests and verify missing components**
+
+Run:
+
+```bash
+bun test 'app/[event]/capture-review.test.tsx' \
+  'app/[event]/booth-session/countdown-audio.test.ts'
+```
+
+Expected: FAIL because the components do not exist.
+
+- [ ] **Step 3: Implement the exact review and acceptance flow**
+
+In the Booth:
+
+1. Capture frames and call `composeToCanvas()`.
+2. Display that exact canvas in review.
+3. Focus Use Photo when review opens.
+4. Start the configured timer, default five seconds.
+5. More Time permanently cancels auto-accept for that candidate.
+6. The winning acceptance disables all actions before any `await`.
+7. Call `encodeCanvas()` and then `session.enqueueCapture()` with
+   framed/fallback metadata.
+8. Only after the Outbox write succeeds, release the canvas, clear the Frame,
+   and enter handoff.
+9. Encode/Outbox failure keeps the same Frame/canvas, creates no Outbox item,
+   shows an accessible error, and requires an explicit retry or Retake.
+10. Retake releases the candidate and returns to camera-ready with the same
+    Frame.
+11. File-camera fallback decodes to a canvas first and uses the same review
+    path; undecodable input is never enqueued under a JPEG content type.
+
+- [ ] **Step 4: Apply locale, pause, audio, and accessibility behavior**
+
+- Persist locale per canonical Event/device and update document `lang`/`dir`.
+- Localize all changed picker, countdown, review, queued, handoff, and
+  direct-photo strings.
+- Use localized Frame labels with default-label fallback.
+- Activate optional tones only from a guest gesture; visual countdown remains.
+- Pause during capture/review/accepting lets the current flow finish or Retake,
+  then clears the Frame and stops camera tracks. Outbox drain continues.
+- Make every target at least `44×44px`.
+- Add visible `:focus-visible`, forced-color outlines, reduced-motion removal
+  of flash/fade/scale animation, concise live announcements, and pointer-
+  independent error dismissal.
+- Retake returns focus to the shutter; handoff later focuses its heading.
+
+- [ ] **Step 5: Run focused and full verification**
+
+Run:
+
+```bash
+bun test 'app/[event]/capture-review.test.tsx' \
+  'app/[event]/booth-session/countdown-audio.test.ts' \
+  'app/[event]/booth-session/capture-flow.test.ts' \
+  'app/[event]/booth-session/session.test.ts'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add 'app/[event]/capture-review.tsx' \
+  'app/[event]/capture-review.test.tsx' \
+  'app/[event]/booth-session/countdown-audio.ts' \
+  'app/[event]/booth-session/countdown-audio.test.ts' \
+  'app/[event]/page.tsx' 'app/[event]/booth.module.css'
+git commit -m "feat: review and retake guest captures"
+```
+
+### Task 4: Add a safe exact-photo endpoint and minimal direct-photo Gallery shell
+
+**Files:**
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+- Create: `app/api/photo/handlers.ts`
+- Create: `app/api/photo/handlers.test.ts`
+- Create: `app/api/photo/route.ts`
+- Create: `app/[event]/gallery/page.tsx`
+- Create: `app/[event]/gallery/handoff-gallery.tsx`
+- Create: `app/[event]/gallery/handoff-gallery.test.tsx`
+- Create: `app/[event]/gallery/gallery.module.css`
+
+**Interfaces:**
+- Produces: an exact Event-owned public-photo lookup.
+- Produces: the stable `/{event}/gallery?photo=<complete-key>` landing contract.
+- Consumed by: Task 5 and expanded, not replaced, by Release 3.
+
+- [ ] **Step 1: Write failing exact ownership and privacy tests**
+
+Define:
+
+```ts
+export type PublicPhoto = {
+  key: string;
+  url: string;
+  uploadedAt: string;
+};
+
+EventStore.getPublicPhoto(
+  event: string,
+  completeKey: string
+): Promise<PublicPhoto | null>;
+```
+
+Test:
+
+- Exact Event-owned image success.
+- Canonical alias, prefix, filename fragment, traversal, and cross-Event
+  rejection before a storage read.
+- A valid exact missing key returns not found.
+- Only the exact `PHOTOS` key is read.
+- Response contains no receipt, Frame, revision, index, credential, or
+  operational data.
+
+- [ ] **Step 2: Run focused tests and verify missing APIs**
+
+Run:
+
+```bash
+bun test app/api/photo/handlers.test.ts app/event-store.test.ts
+```
+
+Expected: FAIL because exact public-photo lookup does not exist.
+
+- [ ] **Step 3: Implement EventStore lookup, handler, and route**
+
+Add:
+
+```ts
+export async function getPublicPhoto(
+  request: NextRequest,
+  deps: { store: EventStore }
+): Promise<NextResponse>;
+```
+
+Canonicalize Event first. Require a complete owned image key. Return `400` for
+malformed/cross-Event keys, `404` for an exact missing photo, and only
+`{key,url,uploadedAt}` with `Cache-Control: no-store` on success. The route is
+a thin Cloudflare adapter and owns no key logic.
+
+- [ ] **Step 4: Write and implement the direct-photo Gallery shell**
+
+Tests cover one decoded `photo` query value, loading/success/invalid/not-found/
+offline states, manual retry, semantic image markup, and save/share fallback.
+
+The shell:
+
+- Fetches `/api/photo?event=…&key=…`.
+- Shows only the exact photo.
+- Provides a visible save/share action.
+- Uses localized, focus-managed status and error UI.
+- Does not poll or implement the Release 3 browse feed.
+
+- [ ] **Step 5: Run focused and full checks**
+
+Run:
+
+```bash
+bun test app/api/photo/handlers.test.ts app/event-store.test.ts \
+  'app/[event]/gallery/handoff-gallery.test.tsx'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/event-store.ts app/event-store.test.ts app/api/photo \
+  'app/[event]/gallery'
+git commit -m "feat: open exact handoff photos safely"
+```
+
+### Task 5: Correlate the exact current guest acknowledgement and render local QR handoff
+
+**Files:**
+- Modify: `app/[event]/booth-session/session.ts`
+- Modify: `app/[event]/booth-session/session.test.ts`
+- Create: `app/[event]/booth-session/handoff.ts`
+- Create: `app/[event]/booth-session/handoff.test.ts`
+- Create: `app/[event]/handoff-panel.tsx`
+- Create: `app/[event]/handoff-panel.test.tsx`
+- Modify: `app/[event]/page.tsx`
+- Modify: `app/[event]/booth.module.css`
+
+**Interfaces:**
+- Consumes: Release 0B upload result `{url,key?,duplicate?}` and Task 4 Gallery route.
+- Produces: exact item/result acknowledgements and current-handoff correlation.
+
+- [ ] **Step 1: Write failing Session acknowledgement tests**
+
+Extend:
+
+```ts
+export type UploadAcknowledgement = {
+  item: OutboxItem;
+  result: UploadResult;
+};
+
+type OnAcknowledged = (acknowledgement: UploadAcknowledgement) => void;
+```
+
+Prove the callback receives the exact stored item and response and runs only
+after upload acknowledgement plus successful removal of that exact Outbox row.
+
+- [ ] **Step 2: Write failing pure handoff and QR tests**
+
+Define:
+
+```ts
+export type CurrentHandoff =
+  | { captureId: string; status: "waiting" }
+  | {
+      captureId: string;
+      status: "ready";
+      key: string;
+      photoUrl: string;
+      galleryUrl: string;
+    };
+
+export function beginHandoff(item: OutboxItem): CurrentHandoff;
+
+export function applyAcknowledgement(
+  current: CurrentHandoff | null,
+  acknowledgement: UploadAcknowledgement,
+  origin: string
+): CurrentHandoff | null;
+
+export function buildPhotoHandoffUrl(
+  origin: string,
+  event: string,
+  completeKey: string
+): string;
+```
+
+Test:
+
+- Compare by exact Outbox `id`, never URL/time/queue position.
+- Older delayed acknowledgement is ignored.
+- Current duplicate acknowledgement succeeds.
+- Missing/legacy `key` cannot create an exact QR.
+- New acceptance replaces an old waiting/ready handoff.
+- Dismissed handoff stays dismissed after late acknowledgement.
+- The complete key is one percent-encoded query value.
+- A stale async QR result cannot overwrite a newer handoff.
+- QR data and visible anchor use the identical URL.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-session/handoff.test.ts' \
+  'app/[event]/handoff-panel.test.tsx'
+```
+
+Expected: FAIL because acknowledgement correlation does not exist.
+
+- [ ] **Step 4: Implement Session and handoff state**
+
+Call `onAcknowledged` only after the exact Outbox row is removed. In the page,
+begin waiting handoff immediately after durable enqueue and before calling
+`process()`. Generate:
+
+```text
+/{event}/gallery?photo={complete-object-key}
+```
+
+with `URLSearchParams`. Waiting/offline UI states that the photo is safely
+queued and offers Continue; it never blocks retry or the next guest. Continue
+returns to the fresh picker and late acknowledgement does not reopen handoff.
+
+- [ ] **Step 5: Implement local QR presentation**
+
+Use local `QRCode.toDataURL(galleryUrl)`. Cancel/ignore stale QR promises on
+handoff change. Always show a visible text anchor to the same URL. Focus the
+handoff heading and retain reduced-motion/forced-color behavior.
+
+- [ ] **Step 6: Run focused and full checks**
+
+Run:
+
+```bash
+bun test 'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-session/handoff.test.ts' \
+  'app/[event]/handoff-panel.test.tsx'
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add 'app/[event]/booth-session/session.ts' \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-session/handoff.ts' \
+  'app/[event]/booth-session/handoff.test.ts' \
+  'app/[event]/handoff-panel.tsx' \
+  'app/[event]/handoff-panel.test.tsx' \
+  'app/[event]/page.tsx' 'app/[event]/booth.module.css'
+git commit -m "feat: hand off the exact current guest photo"
+```
+
+### Task 6: Add WebKit coverage, runbooks, and the Release 2 gate
+
+**Files:**
+- Create: `tests/guest-capture.spec.ts`
+- Modify: `docs/runbooks/pre-event-readiness.md`
+- Modify: `docs/runbooks/deployment.md`
+
+**Interfaces:**
+- Consumes: Tasks 1–5 and Release 1 Playwright WebKit setup.
+- Produces: repeatable mocked-camera coverage and exact real-device validation.
+
+- [ ] **Step 1: Add a failing mocked-camera guest journey**
+
+Intercept preflight, pause, camera, upload delays, exact-photo lookup, and QR
+dependencies. Test:
+
+- One-shot and multi-shot exact canvas review.
+- Auto-accept at the configured timeout.
+- More Time cancellation.
+- Same-Frame Retake.
+- Button/timer race creates one Outbox item and one identity.
+- Encoding failure creates no row and recovers.
+- Frame clears after durable acceptance.
+- Offline acceptance shows queued handoff and permits the next guest.
+- Older delayed acknowledgement cannot replace the current handoff.
+- Current acknowledgement creates matching QR/link.
+- Direct-photo navigation opens the exact object.
+- Locale persistence, Arabic direction, and English fallback.
+- Keyboard-only focus, reduced motion, forced colors, and no serious automated
+  accessibility violations on changed screens.
+
+- [ ] **Step 2: Run browser coverage and fix only deterministic failures**
+
+Run:
+
+```bash
+bun run test:browser -- tests/guest-capture.spec.ts
+```
+
+Expected: PASS with no staging or production request.
+
+- [ ] **Step 3: Update staging-first runbooks**
+
+Add real-device checks for:
+
+1. Every enabled Frame's real crop/composite at iPad camera resolution.
+2. One-shot and multi-shot review.
+3. Auto-accept, More Time, rapid Use Photo/Retake race, and encode recovery.
+4. HEIC/file-camera fallback decode and review.
+5. Pause during review and accepting.
+6. Offline acceptance, next-guest continuation, reconnect, and no duplicates.
+7. Two pending guests where the older upload acknowledges after the newer
+   handoff starts.
+8. QR scan with a second physical phone over the staging HTTPS hostname,
+   verifying the exact complete key/photo.
+9. VoiceOver focus order and concise announcements on iPad/iPhone.
+10. Arabic RTL, `zh-SG`, English fallback, and Frame-label fallback.
+11. Countdown audio after user activation plus an audio-unavailable fallback.
+12. Installed landscape mode, Larger Text, Reduce Motion, and high contrast.
+
+- [ ] **Step 4: Run the complete automated Release 2 gate**
+
+Run:
+
+```bash
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+bun run test:browser
+```
+
+Expected: every command exits 0.
+
+- [ ] **Step 5: Perform required real-device staging validation**
+
+Use a throwaway canonical staging Event distinct from production. A browser
+simulator cannot certify camera permission/orientation, full-resolution canvas
+memory, Safari HEIC decode, Web Audio activation/silent-mode behavior, QR
+readability, VoiceOver timing, iOS suspension, IndexedDB eviction, or installed
+mode. A second phone cannot follow a localhost QR, so use the staging HTTPS
+hostname.
+
+Do not perform prefix cleanup. Any test photo removal uses its one complete
+Event-owned key.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tests/guest-capture.spec.ts docs/runbooks/pre-event-readiness.md \
+  docs/runbooks/deployment.md
+git commit -m "test: verify guest capture and handoff"
+```
+
+## Release 2 Completion Gate
+
+Release 2 is complete only when:
+
+- Every task review is clean.
+- The complete automated gate passes.
+- Real iPad Safari review/Retake/acceptance passes for every enabled Frame.
+- A second physical phone opens the exact current guest photo from the QR.
+- Delayed older acknowledgement cannot replace the current handoff.
+- Offline accepted photos remain in the Outbox and the next guest can proceed.
+- VoiceOver, RTL, reduced-motion, focus, and visible-link checks pass.
+- No private record appears in `PHOTOS` or a public response.
+

From 2d601fd572a09479c5c20d3d9e54f81e9b34d7a5 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:22:06 +0800
Subject: [PATCH 026/105] fix: preserve durable outbox ordering and
 acknowledgements

---
 app/[event]/booth-session/session.test.ts | 77 +++++++++++++++++++++++
 app/[event]/booth-session/session.ts      | 15 ++++-
 2 files changed, 89 insertions(+), 3 deletions(-)

diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index 97adb9d..37b7dd1 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -7,6 +7,58 @@ const photo = (name: string) => new Blob([name], { type: "image/jpeg" });
 const text = (blob: Blob) => blob.text();
 
 describe("BoothSession outbox", () => {
+  test("reserves strictly increasing FIFO order across concurrent durable puts", async () => {
+    let releasePuts!: () => void;
+    const putBarrier = new Promise<void>((resolve) => {
+      releasePuts = resolve;
+    });
+    let waitingPuts = 0;
+    class ConcurrentPutStore extends MemoryOutboxStore {
+      override async put(item: OutboxItem) {
+        waitingPuts++;
+        if (waitingPuts === 2) releasePuts();
+        await putBarrier;
+        await super.put(item);
+      }
+    }
+
+    const store = new ConcurrentPutStore();
+    const ids = [
+      "018f0000-0000-4000-8000-000000000002",
+      "018f0000-0000-4000-8000-000000000001",
+    ];
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => ({ url: "/photo" }),
+      () => {},
+      () => ids.shift()!,
+      () => 1753315200000
+    );
+
+    const [first, second] = await Promise.all([
+      session.enqueueCapture(async () => photo("first"), {
+        metadata: { source: "framed", frameKey: "square" },
+      }),
+      session.enqueueCapture(async () => photo("second"), {
+        metadata: { source: "camera-fallback" },
+      }),
+    ]);
+
+    expect([first.createdAt, second.createdAt]).toEqual([
+      1753315200000,
+      1753315200001,
+    ]);
+    expect(first.metadata?.capturedAt).toBe(first.createdAt);
+    expect(second.metadata?.capturedAt).toBe(second.createdAt);
+    const queued = await store.list("party");
+    expect(queued.map((item) => item.id)).toEqual([first.id, second.id]);
+    await expect(Promise.all(queued.map((item) => text(item.blob)))).resolves.toEqual([
+      "first",
+      "second",
+    ]);
+  });
+
   test("retains an older failure when a later capture is queued, then recovers in order", async () => {
     const store = new MemoryOutboxStore();
     const attempted: string[] = [];
@@ -79,6 +131,31 @@ describe("BoothSession outbox", () => {
     expect(uploads).toBe(1);
   });
 
+  test("does not resurrect an acknowledged item when its notification throws", async () => {
+    const store = new MemoryOutboxStore();
+    let uploads = 0;
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploads++;
+        return { url: "/photo" };
+      },
+      () => {
+        throw new Error("thumbnail render failed");
+      }
+    );
+    await session.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await session.process();
+    await session.retry();
+
+    expect(uploads).toBe(1);
+    expect(await store.list("party")).toEqual([]);
+  });
+
   test("persists one identity and metadata before upload", async () => {
     const store = new MemoryOutboxStore();
     const seen: OutboxItem[] = [];
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index 6799bed..0f910e6 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -62,8 +62,11 @@ export class BoothSession {
     const blob = await capture(options.signal);
     if (options.signal?.aborted) throw abortError();
     // Preserve enqueue order even if two captures share a millisecond or the
-    // device clock moves backwards while the booth is running.
+    // device clock moves backwards while the booth is running. Reserve before
+    // awaiting persistence so concurrent successful captures cannot share a
+    // timestamp; a failed put may leave a harmless gap.
     const createdAt = Math.max(this.now(), this.lastCreatedAt + 1);
+    this.lastCreatedAt = createdAt;
     const item: OutboxItem = {
       id: this.makeId(),
       event: this.event,
@@ -74,7 +77,6 @@ export class BoothSession {
       ...(options.rehearsalId === undefined ? {} : { rehearsalId: options.rehearsalId }),
     };
     await this.store.put(item);
-    this.lastCreatedAt = createdAt;
     const pending = await this.store.list(this.event);
     this.publish({
       status: this.state.status === "failed" ? "failed" : "idle",
@@ -111,7 +113,14 @@ export class BoothSession {
       try {
         const result = await this.upload(item);
         await this.store.remove(item.id);
-        this.onUploaded(result);
+        // Notification is outside the durable retry boundary. Storage already
+        // acknowledged and the item is gone, so a UI callback failure must not
+        // resurrect a duplicate upload.
+        try {
+          this.onUploaded(result);
+        } catch {
+          // The next state publication still reconciles the Booth UI.
+        }
         pending = await this.store.list(this.event);
         this.publish({
           status: "idle",

From 3862af08ffa21f78db9a9747dc00d76a41feed4f Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:24:33 +0800
Subject: [PATCH 027/105] fix: isolate acknowledged outbox notifications

---
 app/[event]/booth-session/session.test.ts | 61 +++++++++++++++++++++++
 app/[event]/booth-session/session.ts      | 53 +++++++++++++-------
 2 files changed, 97 insertions(+), 17 deletions(-)

diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index 37b7dd1..bff439d 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -156,6 +156,67 @@ describe("BoothSession outbox", () => {
     expect(await store.list("party")).toEqual([]);
   });
 
+  test("does not resurrect an acknowledged item when a state subscriber throws", async () => {
+    const store = new MemoryOutboxStore();
+    let uploads = 0;
+    const session = new BoothSession("party", store, async () => {
+      uploads++;
+      return { url: "/photo" };
+    });
+    session.subscribe((state) => {
+      if (uploads === 1 && state.status === "idle" && state.pendingCount === 0) {
+        throw new Error("state render failed");
+      }
+    });
+    await session.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await session.process();
+    await session.retry();
+
+    expect(uploads).toBe(1);
+    expect(await store.list("party")).toEqual([]);
+  });
+
+  test("a post-ack list failure stops safely and retry continues with the next item", async () => {
+    class FailingReconcileStore extends MemoryOutboxStore {
+      private failNextList = false;
+
+      override async remove(id: string) {
+        await super.remove(id);
+        this.failNextList = true;
+      }
+
+      override async list(event: string) {
+        if (this.failNextList) {
+          this.failNextList = false;
+          throw new Error("outbox reconciliation failed");
+        }
+        return super.list(event);
+      }
+    }
+
+    const store = new FailingReconcileStore();
+    const uploads: string[] = [];
+    const session = new BoothSession("party", store, async (item) => {
+      uploads.push(await text(item.blob));
+      return { url: "/photo" };
+    });
+    await session.enqueueCapture(async () => photo("first"), {
+      metadata: { source: "camera-fallback" },
+    });
+    await session.enqueueCapture(async () => photo("second"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await session.process();
+    await session.retry();
+
+    expect(uploads).toEqual(["first", "second"]);
+    expect(await store.list("party")).toEqual([]);
+  });
+
   test("persists one identity and metadata before upload", async () => {
     const store = new MemoryOutboxStore();
     const seen: OutboxItem[] = [];
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index 0f910e6..020993e 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -40,7 +40,13 @@ export class BoothSession {
 
   private publish(next: UploadState) {
     this.state = next;
-    this.listeners.forEach((listener) => listener(next));
+    for (const listener of this.listeners) {
+      try {
+        listener(next);
+      } catch {
+        // State observers are UI-only and cannot affect durable queue state.
+      }
+    }
   }
 
   async recover() {
@@ -110,24 +116,10 @@ export class BoothSession {
         error: null,
         durable: this.store.isDurable(),
       });
+      let result: UploadResult;
       try {
-        const result = await this.upload(item);
+        result = await this.upload(item);
         await this.store.remove(item.id);
-        // Notification is outside the durable retry boundary. Storage already
-        // acknowledged and the item is gone, so a UI callback failure must not
-        // resurrect a duplicate upload.
-        try {
-          this.onUploaded(result);
-        } catch {
-          // The next state publication still reconciles the Booth UI.
-        }
-        pending = await this.store.list(this.event);
-        this.publish({
-          status: "idle",
-          pendingCount: pending.length,
-          error: null,
-          durable: this.store.isDurable(),
-        });
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         await this.store.put({ ...item, attempts: item.attempts + 1, lastError: message });
@@ -139,6 +131,33 @@ export class BoothSession {
         });
         return;
       }
+
+      // Everything below runs after the upload was acknowledged and the exact
+      // item was removed. Post-ack failures may pause reconciliation, but can
+      // never enter the retry path and recreate that item.
+      try {
+        this.onUploaded(result);
+      } catch {
+        // The next state publication still reconciles the Booth UI.
+      }
+
+      try {
+        pending = await this.store.list(this.event);
+      } catch (error) {
+        this.publish({
+          status: "failed",
+          pendingCount: Math.max(0, pending.length - 1),
+          error: error instanceof Error ? error.message : String(error),
+          durable: this.store.isDurable(),
+        });
+        return;
+      }
+      this.publish({
+        status: "idle",
+        pendingCount: pending.length,
+        error: null,
+        durable: this.store.isDurable(),
+      });
     }
   }
 }

From 01987457a4fc3a486b66143c7c4a99736fb513b1 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:29:06 +0800
Subject: [PATCH 028/105] docs: plan gallery and moderation improvements

---
 ...2026-07-24-release-3-gallery-moderation.md | 1062 +++++++++++++++++
 1 file changed, 1062 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-24-release-3-gallery-moderation.md

diff --git a/docs/superpowers/plans/2026-07-24-release-3-gallery-moderation.md b/docs/superpowers/plans/2026-07-24-release-3-gallery-moderation.md
new file mode 100644
index 0000000..f070770
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-24-release-3-gallery-moderation.md
@@ -0,0 +1,1062 @@
+# Release 3 Gallery and Moderation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Separate the phone browse Gallery from the projector Live Gallery, share one adaptive incremental Photo Feed controller, make full-Event moderation privately pageable and rebuildable, and complete localization and accessibility coverage without weakening exact-key deletion.
+
+**Architecture:** A pure Photo Feed reducer owns cursor retention, exact-key deduplication, request generations, visibility, cadence, and abort/scheduling effects; a thin React interpreter performs fetches and timers for both Gallery presentations. The existing projector marquee remains intact while the Release 2 direct-photo route grows into a phone-first browse Gallery with a shared focus-managed lightbox and pure scroll anchoring. `EventStore` remains the only owner of private reverse-time index, rebuild-checkpoint, receipt, and exact deletion keys. Admin routes authenticate and validate, then delegate paged reads, bounded add-only rebuilds, and exact public-first deletion to the Event Store.
+
+**Tech Stack:** Bun, TypeScript, Next.js 15 App Router, React 19, Cloudflare Workers/R2, typed message catalogs, Playwright WebKit, `@axe-core/playwright`.
+
+## Global Constraints
+
+- Start only after Release 0B idempotent upload/private index and Release 2 direct-photo Gallery pass their complete gates.
+- Use Bun commands only.
+- `EventStore` remains the only owner of `PHOTOS` and `STATE` keys.
+- `PHOTOS` remains authoritative for whether a photo exists.
+- Existing public `GET /api/photos?event=&after=` remains incremental and backward compatible.
+- `/{event}/live` remains the projector marquee with balanced independent columns, newest-first insertion, manual scroll pause, lightbox, and reduced-motion behavior.
+- `/{event}/gallery?photo=<complete-key>` remains the direct-photo handoff contract.
+- Public responses never expose receipts, private index records, rebuild state, config revisions, credentials, Booth records, or other operational state.
+- New private writes are create-only, add-only, or exact-key cleanup. Rebuild never deletes or overwrites photos or existing index records.
+- Moderation accepts only one complete Event-owned image key. Never accept a prefix, filename fragment, alias, traversal path, or cross-Event key.
+- Delete the public photo first. Cleanup then targets only its one exact receipt key and one exact index key.
+- A cleanup failure after confirmed public deletion must not turn the deletion into an ambiguous retry.
+- Every Event parameter uses `canonicalEvent()` and rejects aliases.
+- Gallery failures retain already-visible photos and provide manual retry.
+- Hidden tabs stop polling; requests never overlap.
+- Existing and future unsupported stored versions fail explicitly.
+- No browser simulator replaces physical iPhone/iPad VoiceOver, native Share/Save, Safari visibility/suspension, or projector checks.
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+- Never deploy the unnamed Wrangler environment to an Event domain.
+
+---
+
+## File Structure
+
+- Create `app/photo-feed/types.ts` — shared public Photo Feed types and profiles.
+- Create `app/photo-feed/controller.ts` — pure feed reducer, merge, cadence, and effect model.
+- Create `app/photo-feed/controller.test.ts` — cursor, dedupe, cadence, visibility, and no-overlap tests.
+- Create `app/photo-feed/use-photo-feed.ts` — React fetch/timer/abort effect interpreter.
+- Create `app/photo-feed/use-photo-feed.test.ts` — deterministic interpreter lifecycle tests.
+- Create `app/[event]/gallery/photo-actions.ts` — exact Gallery URLs and save/share behavior.
+- Create `app/[event]/gallery/photo-actions.test.ts` — URL, native share, and fallback tests.
+- Create `app/[event]/gallery/photo-lightbox.tsx` — shared accessible localized lightbox.
+- Create `app/[event]/gallery/photo-lightbox.test.tsx` — semantic/focus/action markup tests.
+- Modify `app/[event]/live/page.tsx` — shared feed/lightbox integration and browse QR.
+- Modify `app/[event]/live/live.module.css` — semantic tiles, forced colors, and focus.
+- Modify `app/[event]/live/wrap.test.ts` — retain marquee wrapping characterization.
+- Modify `app/[event]/gallery/page.tsx` — preserve the direct-photo route contract.
+- Replace or expand `app/[event]/gallery/handoff-gallery.tsx` — phone browse Gallery.
+- Create `app/[event]/gallery/browse-gallery.test.tsx` — feed/deep-link/error markup tests.
+- Create `app/[event]/gallery/scroll-anchor.ts` — pure visible-anchor and scroll-delta logic.
+- Create `app/[event]/gallery/scroll-anchor.test.ts` — mixed-height/prepend tests.
+- Modify `app/[event]/gallery/gallery.module.css` — phone-first browse and notices.
+- Create `app/moderation.ts` — private moderation schemas and opaque cursor codec.
+- Create `app/moderation.test.ts` — strict schema/cursor validation.
+- Modify `app/event-store.ts` — moderation paging, rebuild, and exact derived cleanup.
+- Modify `app/event-store.test.ts` — paging, rebuild, races, privacy, and deletion tests.
+- Create `app/api/moderation/photos/handlers.ts` — dependency-injected moderation read/rebuild handlers.
+- Create `app/api/moderation/photos/handlers.test.ts` — auth/input/status/redaction tests.
+- Create `app/api/moderation/photos/route.ts` — thin Admin-only page adapter.
+- Create `app/api/moderation/photos/rebuild/route.ts` — thin Admin-only bounded rebuild adapter.
+- Create `app/api/photos/handlers.ts` — dependency-injected public feed and exact delete handlers.
+- Create `app/api/photos/handlers.test.ts` — compatibility and exact cleanup status tests.
+- Modify `app/api/photos/route.ts` — thin Cloudflare route adapter.
+- Create `app/[event]/admin/moderation-state.ts` — pure page merge/filter/deletion state.
+- Create `app/[event]/admin/moderation-state.test.ts` — paging, reset, and focus-target tests.
+- Create `app/[event]/admin/moderation-panel.tsx` — filters, pages, rebuild, and photo grid.
+- Create `app/[event]/admin/moderation-panel.test.tsx` — accessible localized panel markup.
+- Create `app/[event]/admin/moderation-dialog.tsx` — inspection, keyboard navigation, and exact confirmation.
+- Create `app/[event]/admin/moderation-dialog.test.tsx` — focus, exact key, and cleanup-warning tests.
+- Modify `app/[event]/admin/page.tsx` — authenticated moderation integration.
+- Modify `app/[event]/admin/admin.module.css` — scalable grid/dialog/filter styling.
+- Modify `app/i18n/catalog.ts` — complete projector, browse, moderation, and Admin messages.
+- Modify `app/i18n/catalog.test.ts` — exact locale-key and placeholder parity.
+- Modify `app/i18n/locale.ts` — reusable Event/device locale client integration if absent.
+- Modify `app/i18n/locale.test.ts` — Admin/Gallery locale persistence and direction.
+- Create `tests/gallery-moderation.spec.ts` — WebKit gallery/moderation/accessibility journey.
+- Modify `package.json` and `bun.lock` — axe browser dependency only if absent.
+- Modify `.github/workflows/verify.yml` — retain browser verification.
+- Modify `docs/runbooks/pre-event-readiness.md` — phone/projector/moderation/VoiceOver checks.
+- Modify `docs/runbooks/deployment.md` — Release 3 staging gate and add-only rebuild procedure.
+
+### Task 1: Add the shared pure adaptive Photo Feed controller
+
+**Files:**
+- Create: `app/photo-feed/types.ts`
+- Create: `app/photo-feed/controller.ts`
+- Create: `app/photo-feed/controller.test.ts`
+- Create: `app/photo-feed/use-photo-feed.ts`
+- Create: `app/photo-feed/use-photo-feed.test.ts`
+
+**Interfaces:**
+- Consumes: the existing public `GET /api/photos?event=&after=` response.
+- Produces: pure cursor/dedupe/request/scheduling state shared by projector and browse.
+- Produces: a thin React interpreter that owns real abort controllers and timers.
+
+- [ ] **Step 1: Write failing merge and state-transition tests**
+
+Define:
+
+```ts
+export type FeedPhoto = {
+  key: string;
+  url: string;
+  uploadedAt: string;
+};
+
+export type FeedProfile = {
+  activeMs: number;
+  quietMinMs: number;
+  quietMaxMs: number;
+  errorBaseMs: number;
+  errorMaxMs: number;
+};
+
+export type PhotoFeedState = {
+  event: string;
+  photos: FeedPhoto[];
+  cursor: string | null;
+  status: "loading" | "ready" | "error";
+  visible: boolean;
+  request: { id: number; after: string | null } | null;
+  refreshPending: boolean;
+  quietCount: number;
+  failureCount: number;
+  error: string | null;
+  generation: number;
+};
+
+export function reducePhotoFeed(
+  state: PhotoFeedState,
+  event: PhotoFeedEvent
+): { state: PhotoFeedState; effects: PhotoFeedEffect[] };
+
+export function mergePhotoFeed(
+  current: readonly FeedPhoto[],
+  incoming: readonly FeedPhoto[]
+): { photos: FeedPhoto[]; inserted: FeedPhoto[] };
+```
+
+Test:
+
+- Exact-key deduplication, including duplicates inside one response.
+- Incoming copies replace stale same-key URL/timestamp values.
+- New photos prepend while retained photos keep their relative order.
+- Empty deltas retain cursor and photos.
+- A successful response adopts only a valid non-empty response cursor.
+- Event change clears cursor/photos/errors, increments generation, and aborts the old request.
+- Stale response, error, or abort completion from an old request/generation is ignored.
+- Manual refresh while idle schedules immediately.
+- Manual refresh while active marks one serialized refresh and emits an abort, never a second simultaneous request.
+- Hidden visibility emits abort, clears scheduling, and retains photos.
+- Foreground visibility refreshes immediately.
+- Request failure retains photos and increments capped error delay.
+
+- [ ] **Step 2: Write failing deterministic cadence tests**
+
+Export profiles:
+
+```ts
+export const PROJECTOR_FEED_PROFILE: FeedProfile;
+export const BROWSE_FEED_PROFILE: FeedProfile;
+```
+
+Prove:
+
+- Projector active arrival cadence is approximately 2 seconds.
+- Browse active arrival cadence is approximately 3.5 seconds.
+- Consecutive quiet responses slow into their configured 10–20 second range.
+- Errors use injected jittered exponential backoff capped at 60 seconds.
+- Success clears failure backoff.
+- Injected random/clock values make every assertion exact.
+
+- [ ] **Step 3: Run focused tests and verify missing-module failures**
+
+```bash
+bun test app/photo-feed/controller.test.ts app/photo-feed/use-photo-feed.test.ts
+```
+
+Expected: FAIL because the modules do not exist.
+
+- [ ] **Step 4: Implement the pure reducer and response validation**
+
+Effects explicitly describe:
+
+```ts
+type PhotoFeedEffect =
+  | { type: "request"; requestId: number; generation: number; after: string | null }
+  | { type: "abort"; requestId: number }
+  | { type: "schedule"; delayMs: number }
+  | { type: "cancel-schedule" };
+```
+
+Validate every response field before a success action. Unknown top-level fields
+are ignored; malformed `photos` or `cursor` fail the request without clearing
+existing photos. Do not sort by client clock: retain server newest-first order
+and exact-key tie behavior.
+
+- [ ] **Step 5: Implement the React effect interpreter**
+
+The interpreter:
+
+- Uses one active `AbortController`.
+- Awaits abort settlement before executing a queued immediate refresh.
+- Uses one timer and cancels it before replacement.
+- Listens to `visibilitychange`; hidden stops, visible refreshes.
+- Aborts and resets on Event change/unmount.
+- Exposes `{photos,status,error,refresh}` plus the exact inserted photos from
+  the latest applied response.
+- Never calls `setInterval`.
+
+Test it with injected fetch, clock, timer, visibility, and abort providers.
+
+- [ ] **Step 6: Run focused and full checks**
+
+```bash
+bun test app/photo-feed/controller.test.ts app/photo-feed/use-photo-feed.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/photo-feed
+git commit -m "feat: share adaptive photo feed polling"
+```
+
+### Task 2: Share accessible photo actions and preserve the projector marquee
+
+**Files:**
+- Create: `app/[event]/gallery/photo-actions.ts`
+- Create: `app/[event]/gallery/photo-actions.test.ts`
+- Create: `app/[event]/gallery/photo-lightbox.tsx`
+- Create: `app/[event]/gallery/photo-lightbox.test.tsx`
+- Modify: `app/[event]/live/page.tsx`
+- Modify: `app/[event]/live/live.module.css`
+- Modify: `app/[event]/live/wrap.test.ts`
+- Modify: `app/i18n/catalog.ts`
+- Modify: `app/i18n/catalog.test.ts`
+
+**Interfaces:**
+- Consumes: Task 1 controller and Release 2 typed locale/message helpers.
+- Produces: one exact-photo save/share implementation and focus-managed lightbox.
+- Preserves: every existing projector marquee/manual-scroll invariant.
+
+- [ ] **Step 1: Characterize the existing projector before refactoring**
+
+Add focused tests for:
+
+- `wrap()` positive, negative, and multi-period positions.
+- Independent per-column periods.
+- Newest-first stable tile keys.
+- Duplicate copy is `aria-hidden`.
+- Ten-pixel drag threshold suppresses a tile activation.
+- Manual wheel/drag pause is four seconds.
+- Reduced motion removes auto-marquee but keeps the photos available.
+
+Extract only small pure marquee calculations when needed for tests; do not
+replace the working rendering model.
+
+- [ ] **Step 2: Write failing exact action and lightbox tests**
+
+Define:
+
+```ts
+export function exactGalleryUrl(
+  origin: string,
+  event: string,
+  completeKey: string
+): string;
+
+export async function savePhoto(input: PhotoActionInput): Promise<PhotoActionResult>;
+export async function sharePhoto(input: PhotoActionInput): Promise<PhotoActionResult>;
+```
+
+Test:
+
+- The complete key is one percent-encoded `photo` query value.
+- Native file share is preferred when supported.
+- Link share and object-URL download are bounded fallbacks.
+- Share cancellation is not rendered as an error.
+- Object URLs are always revoked.
+- A stale prefetched Blob cannot be used for a newer photo.
+- The visible exact-photo link and share URL are identical.
+
+Render the lightbox and assert a labelled modal, semantic image, Save, Share,
+Close, status/error regions, localized labels, and 44×44 controls.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test 'app/[event]/gallery/photo-actions.test.ts' \
+  'app/[event]/gallery/photo-lightbox.test.tsx' \
+  'app/[event]/live/wrap.test.ts'
+```
+
+Expected: FAIL because shared actions/lightbox do not exist.
+
+- [ ] **Step 4: Implement the shared lightbox**
+
+The lightbox:
+
+- Focuses its heading or Close button on open.
+- Traps Tab/Shift+Tab, closes on Escape, and restores the exact trigger focus.
+- Prefetches bytes for Safari without requiring an external service.
+- Uses a visible exact-photo text link.
+- Announces non-cancelled failures concisely.
+- Uses `<bdi>` for exact keys/URLs in RTL.
+- Supports previous/next callbacks without owning moderation state.
+- Ignores stale prefetch/action promises after the photo changes.
+
+- [ ] **Step 5: Refactor only projector feed and photo presentation**
+
+In `app/[event]/live/page.tsx`:
+
+- Replace fixed polling with `usePhotoFeed(PROJECTOR_FEED_PROFILE)`.
+- Keep existing photos visible during errors and wire manual retry.
+- Replace `img role="button"` with a semantic button containing the image.
+- Use the shared lightbox.
+- Generate the projector QR locally for `/{event}/gallery`, not `/live`.
+- Preserve balanced masonry, duplicated copies, independent loop periods,
+  manual scrolling, momentum, four-second resume, click suppression, and
+  newest-first insertion.
+
+Add forced-color focus outlines and reduced-motion coverage without changing
+the projector's visual hierarchy.
+
+- [ ] **Step 6: Extend every complete catalog**
+
+Add all projector and shared-lightbox keys to `en`, `zh-SG`, and `ar`. Prove
+exact key parity and exact interpolation-placeholder parity.
+
+- [ ] **Step 7: Run focused and full checks**
+
+```bash
+bun test 'app/[event]/gallery/photo-actions.test.ts' \
+  'app/[event]/gallery/photo-lightbox.test.tsx' \
+  'app/[event]/live/wrap.test.ts' \
+  app/i18n/catalog.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add 'app/[event]/gallery' 'app/[event]/live' app/i18n
+git commit -m "feat: preserve projector with shared gallery controls"
+```
+
+### Task 3: Expand the direct-photo shell into the phone browse Gallery
+
+**Files:**
+- Modify: `app/[event]/gallery/page.tsx`
+- Modify: `app/[event]/gallery/handoff-gallery.tsx`
+- Create: `app/[event]/gallery/browse-gallery.test.tsx`
+- Create: `app/[event]/gallery/scroll-anchor.ts`
+- Create: `app/[event]/gallery/scroll-anchor.test.ts`
+- Modify: `app/[event]/gallery/gallery.module.css`
+- Modify: `app/i18n/catalog.ts`
+- Modify: `app/i18n/catalog.test.ts`
+
+**Interfaces:**
+- Consumes: Task 1 browse feed, Task 2 lightbox, and Release 2 exact-photo API.
+- Preserves: `/{event}/gallery?photo=<complete-key>`.
+- Produces: naturally scrolling newest-first browse with stable anchoring.
+
+- [ ] **Step 1: Write failing pure scroll-anchor tests**
+
+Define:
+
+```ts
+export type ScrollAnchor = { key: string; top: number };
+
+export function chooseScrollAnchor(
+  visible: readonly { key: string; top: number; bottom: number }[]
+): ScrollAnchor | null;
+
+export function anchoredScrollTop(input: {
+  previousScrollTop: number;
+  beforeTop: number;
+  afterTop: number;
+}): number;
+```
+
+Test mixed-height photos, partially visible first rows, several prepends,
+deleted/missing anchors, zero/negative offsets, and no adjustment while at the
+top.
+
+- [ ] **Step 2: Write failing browse/deep-link tests**
+
+Test:
+
+- No query opens the browse feed.
+- One decoded `photo` query value is fetched immediately through `/api/photo`.
+- Direct photo opens before the initial feed completes.
+- Direct photo is deduplicated if it later appears in the feed.
+- Invalid/not-found direct photo shows a localized retryable state while browse
+  remains available.
+- Opening a feed tile writes the exact-photo query without full navigation.
+- Closing restores the browse URL.
+- Old deep-link requests cannot open over a newer selected photo.
+- Feed errors retain tiles and manual retry.
+- Loading, empty, offline, and ready states.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test 'app/[event]/gallery/scroll-anchor.test.ts' \
+  'app/[event]/gallery/browse-gallery.test.tsx'
+```
+
+Expected: FAIL because browse/anchor behavior does not exist.
+
+- [ ] **Step 4: Implement browse rendering and direct-photo correlation**
+
+Use `usePhotoFeed(BROWSE_FEED_PROFILE)`. Render a phone-first lazy-image grid
+in natural document flow. Use exact keys for React and DOM anchor identity.
+
+For `?photo=`:
+
+- Preserve the complete-key query contract from Release 2.
+- Fetch `/api/photo` immediately and open the shared lightbox.
+- Never infer or reconstruct private metadata.
+- Use `history.pushState`/`replaceState` only after exact URL construction.
+- Keep link/share URLs identical to the current exact key.
+
+- [ ] **Step 5: Implement anchoring and new-photo notice**
+
+When the user is away from the top:
+
+1. Capture the first visible exact-key element and its top before the prepend.
+2. Render the merged feed.
+3. In a layout effect, find the same exact key and adjust `scrollTop` by its
+   measured top delta.
+4. Increment a localized `N new photos` notice.
+
+“Jump to Latest” scrolls to zero and clears the count. Reduced-motion users get
+an immediate jump. A missing or stale anchor performs no adjustment.
+
+- [ ] **Step 6: Complete responsive and accessible presentation**
+
+- Use semantic photo buttons and useful localized accessible names.
+- Keep targets at least 44×44.
+- Preserve focus while new photos prepend.
+- Add high-contrast/forced-color focus, RTL layout, reduced motion, and 200%
+  text reflow.
+- Do not turn the browse Gallery into the projector marquee.
+
+- [ ] **Step 7: Run focused and full checks**
+
+```bash
+bun test 'app/[event]/gallery/scroll-anchor.test.ts' \
+  'app/[event]/gallery/browse-gallery.test.tsx' \
+  'app/[event]/gallery/photo-lightbox.test.tsx' \
+  app/i18n/catalog.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add 'app/[event]/gallery' app/i18n
+git commit -m "feat: add the phone browse gallery"
+```
+
+### Task 4: Page and rebuild the private reverse-time moderation index
+
+**Files:**
+- Create: `app/moderation.ts`
+- Create: `app/moderation.test.ts`
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: Release 0B `photoIndexKey()` and private version-1 metadata.
+- Produces: strict Admin-only page records and opaque stable cursors.
+- Produces: bounded add-only legacy index rebuild with CAS checkpoint.
+
+- [ ] **Step 1: Write failing schema and opaque cursor tests**
+
+Define:
+
+```ts
+export type ModerationPhoto = {
+  key: string;
+  url: string;
+  uploadedAt: string;
+  capturedAt: number;
+  source?: "framed" | "camera-fallback";
+  frameKey?: string;
+};
+
+export type ModerationCursor = {
+  version: 1;
+  event: string;
+  afterIndexKey: string;
+  from: number | null;
+  to: number | null;
+};
+
+export function encodeModerationCursor(cursor: ModerationCursor): string;
+export function decodeModerationCursor(
+  encoded: string,
+  expected: Pick<ModerationCursor, "event" | "from" | "to">
+): ModerationCursor;
+```
+
+Test malformed base64/JSON, extra/missing fields, unsupported versions,
+cross-Event cursors, changed filters, non-index `afterIndexKey`, and a valid
+round trip. The encoded value is opaque API state, not a storage cursor.
+
+- [ ] **Step 2: Write failing EventStore paging tests**
+
+Define:
+
+```ts
+EventStore.listModerationPhotos(
+  event: string,
+  options: {
+    cursor?: string;
+    limit: number;
+    from?: number;
+    to?: number;
+  }
+): Promise<{
+  photos: ModerationPhoto[];
+  nextCursor: string | null;
+}>;
+```
+
+Test:
+
+- Ascending inverse-time keys produce newest-first photos.
+- Stable key tie-breaking.
+- Default/bounded limits and pages larger than one R2 response.
+- Inclusive from/to filtering by `capturedAt`.
+- Stable `startAfter` continuation while new uploads arrive.
+- Exact-key deduplication.
+- Missing public photos are skipped because `PHOTOS` is authoritative.
+- Corrupt/future private records fail explicitly.
+- A record naming another Event never becomes public/Admin output.
+- No receipt, revision, credential, heartbeat, or rebuild field is returned.
+
+- [ ] **Step 3: Write failing checkpointed rebuild tests**
+
+Add private keys:
+
+```ts
+export const photoIndexRebuildCheckpointKey = (event: string) =>
+  `events/${event}/photo-index-rebuild/v1/checkpoint.json`;
+
+export const photoIndexRebuildCompleteKey = (event: string) =>
+  `events/${event}/photo-index-rebuild/v1/complete.json`;
+```
+
+Define:
+
+```ts
+EventStore.rebuildPhotoIndex(
+  event: string,
+  options: { batchSize: number }
+): Promise<{
+  complete: boolean;
+  scanned: number;
+  indexed: number;
+  checkpoint: string | null;
+}>;
+```
+
+Test:
+
+- Legacy photos gain create-only reverse-time index records.
+- Existing index bytes/etag are never replaced.
+- Rebuild never creates a synthetic receipt.
+- A failed index write does not checkpoint past the failed batch.
+- Retrying safely re-observes prior create-only writes.
+- Resume uses the last complete photo key via `startAfter`.
+- Concurrent checkpoint CAS cannot regress or skip progress.
+- Non-image objects advance scanning but do not get indexed.
+- A photo deleted during scanning is not treated as current source truth.
+- Completion marker appears only after a full successful final scan.
+- A crash after final checkpoint but before marker is recoverable.
+- Cross-Event photos and state are untouched.
+
+- [ ] **Step 4: Run focused tests and verify failures**
+
+```bash
+bun test app/moderation.test.ts app/event-store.test.ts
+```
+
+Expected: FAIL because moderation page/rebuild APIs do not exist.
+
+- [ ] **Step 5: Implement strict parsing and stable paging**
+
+List only under `events/{event}/photo-index/v1/`. Use `startAfter` from the
+validated opaque cursor, not an offset/R2 cursor. Read bounded chunks until the
+requested number of current public photos is filled or the index is exhausted.
+Advance the returned cursor by the last scanned private index key so stale
+deleted records cannot cause loops.
+
+- [ ] **Step 6: Implement bounded add-only rebuild**
+
+For each legacy public image, derive the sort time from its 13-digit filename
+timestamp, falling back to its stored upload time. Recheck source existence
+before create-only index write. Commit the checkpoint only after the entire
+batch succeeds. CAS prevents concurrent workers from overwriting progress.
+Never list/delete a private prefix for cleanup.
+
+- [ ] **Step 7: Run focused and full checks**
+
+```bash
+bun test app/moderation.test.ts app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add app/moderation.ts app/moderation.test.ts \
+  app/event-store.ts app/event-store.test.ts
+git commit -m "feat: page and rebuild private moderation index"
+```
+
+### Task 5: Add Admin moderation HTTP boundaries and exact derived cleanup
+
+**Files:**
+- Create: `app/api/moderation/photos/handlers.ts`
+- Create: `app/api/moderation/photos/handlers.test.ts`
+- Create: `app/api/moderation/photos/route.ts`
+- Create: `app/api/moderation/photos/rebuild/route.ts`
+- Create: `app/api/photos/handlers.ts`
+- Create: `app/api/photos/handlers.test.ts`
+- Modify: `app/api/photos/route.ts`
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: Task 4 paging/rebuild and existing `adminOk()`.
+- Produces: strict Admin-only moderation pages and rebuild batches.
+- Preserves: public incremental feed and exact-key DELETE routes.
+
+- [ ] **Step 1: Write failing exact deletion/cleanup tests**
+
+Change the EventStore result additively:
+
+```ts
+export type DeletePhotoResult =
+  | { deleted: false }
+  | {
+      deleted: true;
+      cleanup: {
+        index: "deleted" | "missing" | "failed";
+        receipt: "deleted" | "missing" | "failed";
+      };
+    };
+```
+
+Test:
+
+- Alias, prefix, filename fragment, traversal, non-image, and cross-Event key
+  are rejected before deletion.
+- The exact public object is read and deleted first.
+- Exact receipt metadata supplies the index sort time when valid.
+- Filename/upload time supplies the safe fallback.
+- Only `photoReceiptKey(event,key)` and
+  `photoIndexKey(event,key,exactSortTime)` are cleaned.
+- No prefix list/delete is called.
+- Public deletion failure performs no private cleanup.
+- Index/receipt cleanup failure after public deletion returns `deleted: true`
+  with failed cleanup, rather than throwing an ambiguous delete error.
+- An exact missing public photo preserves the existing `deleted: false` result.
+- Adjacent and cross-Event photos/indexes/receipts remain byte-identical.
+
+- [ ] **Step 2: Write failing handler tests**
+
+HTTP contracts:
+
+```text
+GET  /api/moderation/photos?event=&cursor=&limit=&from=&to=
+POST /api/moderation/photos/rebuild?event=
+GET  /api/photos?event=&after=
+DELETE /api/photos?event=&key=
+```
+
+Test:
+
+- Missing Admin secret is `503`; wrong key is `401`.
+- No store call occurs after failed authentication.
+- Canonical Event validation rejects aliases.
+- `limit` defaults to 48 and accepts only integers `1..100`.
+- `from`/`to` require RFC3339 instants with a time-zone and `from <= to`.
+- Malformed cursor returns `400`.
+- Page response is explicitly allowlisted.
+- Rebuild is bounded, returns `202` while incomplete and `200` when complete.
+- Public GET retains its existing response and `after` compatibility.
+- Exact DELETE retains `404` for a missing photo.
+- Confirmed delete returns `200 {deleted:true,key}` and additively reports
+  `cleanupPending` without exposing private key names.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test app/api/moderation/photos/handlers.test.ts \
+  app/api/photos/handlers.test.ts app/event-store.test.ts
+```
+
+Expected: FAIL because the handlers and cleanup result do not exist.
+
+- [ ] **Step 4: Implement public-first exact cleanup**
+
+Before deleting the public photo, read only its exact receipt and public object
+to determine the one exact index key. Delete the public photo. Then perform the
+two exact private deletes independently and capture failures. Never turn a
+confirmed photo deletion into a 5xx that invites an ambiguous retry.
+
+Moderation reads must skip stale index records whose public photo is missing,
+so cleanup failure cannot resurrect a deleted photo in Admin.
+
+- [ ] **Step 5: Implement dependency-injected handlers and thin routes**
+
+Handlers authenticate and validate before delegating. Route modules only obtain
+Cloudflare bindings and call handlers. Response construction explicitly
+allowlists fields and adds `Cache-Control: no-store`.
+
+- [ ] **Step 6: Run focused and full checks**
+
+```bash
+bun test app/api/moderation/photos/handlers.test.ts \
+  app/api/photos/handlers.test.ts app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/api/moderation app/api/photos \
+  app/event-store.ts app/event-store.test.ts
+git commit -m "feat: moderate photos with exact private cleanup"
+```
+
+### Task 6: Replace the recent contact sheet with scalable localized Admin moderation
+
+**Files:**
+- Create: `app/[event]/admin/moderation-state.ts`
+- Create: `app/[event]/admin/moderation-state.test.ts`
+- Create: `app/[event]/admin/moderation-panel.tsx`
+- Create: `app/[event]/admin/moderation-panel.test.tsx`
+- Create: `app/[event]/admin/moderation-dialog.tsx`
+- Create: `app/[event]/admin/moderation-dialog.test.tsx`
+- Modify: `app/[event]/admin/page.tsx`
+- Modify: `app/[event]/admin/admin.module.css`
+- Modify: `app/i18n/catalog.ts`
+- Modify: `app/i18n/catalog.test.ts`
+- Modify: `app/i18n/locale.ts`
+- Modify: `app/i18n/locale.test.ts`
+
+**Interfaces:**
+- Consumes: Task 5 Admin APIs and Release 2 Event/device locale.
+- Produces: full-Event paging, time filters, inspection, rebuild, and exact deletion.
+- Completes: typed localization and accessibility coverage for product-facing screens.
+
+- [ ] **Step 1: Write failing pure moderation-state tests**
+
+Define:
+
+```ts
+export function mergeModerationPage(
+  current: readonly ModerationPhoto[],
+  incoming: readonly ModerationPhoto[]
+): ModerationPhoto[];
+
+export function removeModeratedPhoto(
+  photos: readonly ModerationPhoto[],
+  exactKey: string
+): {
+  photos: ModerationPhoto[];
+  nextFocusKey: string | null;
+};
+
+export function filtersChanged(
+  current: ModerationFilters,
+  next: ModerationFilters
+): boolean;
+```
+
+Test exact-key dedupe, reverse-time retention, filter reset, stale page response
+rejection, exact removal, next/previous focus target, and an empty final page.
+
+- [ ] **Step 2: Write failing accessible panel/dialog tests**
+
+Render and assert:
+
+- Labelled from/to filters and Apply/Clear controls.
+- Loaded count that does not falsely claim an Event total.
+- Semantic photo buttons and lazy images.
+- Load More disabled/busy state.
+- Index rebuild status and explicit bounded Continue action.
+- Larger labelled modal with previous/next, Close, and exact trigger restoration.
+- Arrow-key navigation and Escape contract.
+- Deletion confirmation includes both exact filename and complete key in
+  `<bdi><code>`.
+- Confirm/Cancel are separate 44×44 controls.
+- Cleanup-pending warning says the public photo is already deleted and does not
+  offer a public delete retry.
+- Polite success and assertive error regions.
+- No private receipt/index/revision/device values appear in markup.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test 'app/[event]/admin/moderation-state.test.ts' \
+  'app/[event]/admin/moderation-panel.test.tsx' \
+  'app/[event]/admin/moderation-dialog.test.tsx'
+```
+
+Expected: FAIL because the Admin moderation modules do not exist.
+
+- [ ] **Step 4: Implement authenticated page/filter/rebuild integration**
+
+After Admin authentication:
+
+- Load the first moderation page.
+- Reset rows/cursor atomically when filters change.
+- Append Load More pages by exact key.
+- Ignore stale responses from prior filters/Event/auth state.
+- Route `401` through existing Admin invalidation.
+- Keep config, Booth controls, health, and export usable when moderation fails.
+- Replace the public Photo Feed/16-item recent contact sheet; do not run both.
+- Present rebuild as explicit bounded batches, never an unbounded request.
+
+- [ ] **Step 5: Implement inspection and exact deletion UX**
+
+Opening remembers the exact tile trigger. Previous/next use the loaded reverse-
+time order and keyboard arrows. Successful deletion removes only the exact key,
+announces it, and focuses the next tile or moderation heading. A private cleanup
+warning is informational because the public deletion is already confirmed.
+
+- [ ] **Step 6: Complete localization coverage**
+
+Extend `en`, `zh-SG`, and `ar` with every projector, browse, moderation, Admin
+status, filter, empty, busy, confirmation, cleanup, and error key. Preserve
+exact catalog and placeholder parity.
+
+Migrate remaining product-facing Admin shell literals and reusable Admin panel
+strings to the typed catalog so “complete coverage” is not limited to the new
+panel. Use `Intl.DateTimeFormat` for locale-aware display and retain English
+fallback for unsupported legacy locale values. The locale selector and
+document `lang`/`dir` remain Event/device scoped.
+
+Frame Lab may remain developer tooling, but audit its semantics/focus/reflow.
+If it is considered an operator-facing product route, migrate its literals in
+this task as well.
+
+- [ ] **Step 7: Complete accessibility coverage**
+
+- Semantic heading hierarchy and labelled landmarks.
+- Keyboard-only access to all actions.
+- Focus trap/restoration for both Gallery and moderation dialogs.
+- Concise live announcements without repeated feed chatter.
+- At least 44×44 pointer targets.
+- Visible focus under high contrast and forced colors.
+- Reduced-motion removal of nonessential animation/scrolling.
+- Arabic RTL with exact keys/URLs isolated using `<bdi>`.
+- 200% text and narrow-screen reflow without hidden actions.
+- Native images retain useful localized accessible names.
+
+- [ ] **Step 8: Run focused and full checks**
+
+```bash
+bun test 'app/[event]/admin/moderation-state.test.ts' \
+  'app/[event]/admin/moderation-panel.test.tsx' \
+  'app/[event]/admin/moderation-dialog.test.tsx' \
+  'app/[event]/admin/admin-config-controls.test.tsx' \
+  'app/[event]/admin/config-history-panel.test.tsx' \
+  app/i18n/catalog.test.ts app/i18n/locale.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add 'app/[event]/admin' app/i18n
+git commit -m "feat: scale and localize admin moderation"
+```
+
+### Task 7: Add browser coverage, runbooks, and the Release 3 gate
+
+**Files:**
+- Create: `tests/gallery-moderation.spec.ts`
+- Modify: `package.json`
+- Modify: `bun.lock`
+- Modify: `.github/workflows/verify.yml`
+- Modify: `docs/runbooks/pre-event-readiness.md`
+- Modify: `docs/runbooks/deployment.md`
+
+**Interfaces:**
+- Consumes: Tasks 1–6 and the Release 1 Playwright WebKit setup.
+- Produces: repeatable browser coverage and exact staging/manual validation.
+
+- [ ] **Step 1: Add failing WebKit gallery/controller journeys**
+
+Intercept Photo Feed, exact-photo, and save/share dependencies. Test:
+
+- Slow response plus several timer ticks never overlaps requests.
+- Projector active cadence, quiet slowdown, error backoff, and manual retry.
+- Hidden state aborts/stops; foreground immediately refreshes.
+- Feed errors retain existing photos.
+- Projector retains independent looping columns and four-second manual pause.
+- Projector QR targets browse Gallery.
+- Browse prepends several photos without moving the visible exact-key anchor.
+- New-photo count and Jump to Latest.
+- Direct-photo deep link opens the exact complete key before feed completion.
+- URL open/close history and exact save/share link.
+- Localized loading/empty/offline/error states.
+
+- [ ] **Step 2: Add failing WebKit moderation/accessibility journeys**
+
+Test:
+
+- Multiple reverse-time pages and from/to filters.
+- Stale page response after filter change is ignored.
+- Inspection previous/next, arrows, Escape, focus trap, and restoration.
+- Confirmation displays the exact filename and complete key.
+- One exact-key deletion removes only one tile.
+- Cleanup-pending response is not retried as a public deletion.
+- Rebuild continues bounded batches and reports completion.
+- Keyboard-only operation.
+- Arabic direction, reduced motion, forced colors, 200% text reflow.
+- No serious automated axe violations on Live, browse Gallery, direct photo,
+  Admin moderation, and shared dialogs.
+
+If `@axe-core/playwright` is absent, add it with Bun. Do not add a second browser
+runner.
+
+- [ ] **Step 3: Run browser coverage and fix deterministic failures**
+
+```bash
+bun run test:browser -- tests/gallery-moderation.spec.ts
+```
+
+Expected: PASS without staging or production traffic.
+
+- [ ] **Step 4: Update staging-first runbooks**
+
+Add:
+
+1. Use a throwaway canonical staging Event distinct from production.
+2. Upload enough exact photos to require several moderation pages.
+3. Interrupt and resume a bounded add-only index rebuild.
+4. Confirm checkpoint/completion/index/receipt records exist only in `STATE`.
+5. Exercise projector polling and manual scrolling over an extended period.
+6. Confirm phone browse anchoring while new photos arrive.
+7. Open an exact handoff link and native Share/Save on a physical phone.
+8. Delete one designated canary by its complete key.
+9. Confirm adjacent public photos and private records remain.
+10. Confirm a simulated derived-cleanup failure never resurrects a public photo
+    or invites ambiguous re-deletion.
+11. Exercise keyboard-only Admin moderation.
+12. Check VoiceOver, Arabic RTL, Larger Text, Reduce Motion, high contrast, and
+    focus restoration on iPhone/iPad.
+13. Obtain native-speaker review for supported non-English catalog changes.
+
+Never use prefix cleanup. Abandoned staging records are retained or removed one
+at a time by complete key.
+
+- [ ] **Step 5: Run the complete automated Release 3 gate**
+
+```bash
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+bun run test:browser
+```
+
+Expected: every command exits 0.
+
+- [ ] **Step 6: Perform required staging/manual validation**
+
+Automated WebKit cannot certify:
+
+- iOS native Share user activation, cancellation, or Save to Photos.
+- VoiceOver timing/focus speech on iPhone/iPad.
+- Safari process suspension and real visibility/foreground behavior.
+- Long-running physical projector layout, performance, visual gaps, or QR
+  readability at venue distance.
+- Production-like R2 listing/CAS behavior during rebuild/deletion races.
+- Translation quality.
+
+Use staging and physical devices for these checks. Delete only the designated
+canary by its complete Event-owned key.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add tests/gallery-moderation.spec.ts package.json bun.lock \
+  .github/workflows/verify.yml docs/runbooks/pre-event-readiness.md \
+  docs/runbooks/deployment.md
+git commit -m "test: verify gallery and moderation release"
+```
+
+## Release 3 Completion Gate
+
+Release 3 is complete only when:
+
+- Every task review is clean.
+- The complete automated gate passes.
+- The shared controller proves cursor retention, exact-key dedupe, request
+  serialization, visibility abort, foreground/manual refresh, adaptive quiet
+  cadence, capped error backoff, Event reset, and stale-result rejection.
+- `/live` retains newest-first balanced independent marquee columns, manual
+  scrolling, four-second resume, lightbox, and reduced-motion behavior.
+- The projector QR opens `/{event}/gallery`.
+- `/{event}/gallery?photo=` remains backward compatible and opens the exact
+  public photo without waiting for the browse feed.
+- Phone browse preserves the visible anchor across incoming photos and offers
+  localized new-photo notice/Jump to Latest.
+- Moderation pages the full private reverse-time index with stable opaque
+  cursors and inclusive time filters.
+- Legacy rebuild is bounded, add-only, resumable, concurrency-safe, and marks
+  completion only after a full successful scan.
+- Exact moderation never accepts a prefix/fragment/cross-Event key.
+- Public photo deletion happens before cleanup; cleanup targets only its exact
+  receipt and index keys and cannot make a confirmed deletion ambiguous.
+- Stale private index records never make a deleted public photo visible.
+- Every supported catalog remains complete with English fallback and correct
+  direction.
+- Keyboard, focus, forced-color, reduced-motion, large-text, and automated
+  accessibility checks pass.
+- Staging verifies multiple pages, interrupted rebuild/resume, one exact canary
+  deletion, private-state isolation, physical phone browse/share, VoiceOver,
+  and real projector behavior.

From 2ac3f549230400651973e34bff9d8c40282fb19b Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:40:58 +0800
Subject: [PATCH 029/105] docs: plan repeatable operations and export

---
 ...6-07-24-release-4-repeatable-operations.md | 1432 +++++++++++++++++
 ...2026-07-24-release-5-post-event-package.md | 1003 ++++++++++++
 2 files changed, 2435 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md
 create mode 100644 docs/superpowers/plans/2026-07-24-release-5-post-event-package.md

diff --git a/docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md b/docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md
new file mode 100644
index 0000000..bd72846
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md
@@ -0,0 +1,1432 @@
+# Release 4 Repeatable Operations Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add safe reusable Event presets and a guided private rehearsal that proves real-device readiness without copying credentials, weakening exact-key deletion, or automatically cleaning up test photos.
+
+**Architecture:** Presets store only explicitly serialized `EventExperience` in private `STATE`; applying one passes through the existing revision/CAS path with reason `"preset"` and preserves the target Event's Booth credential. Rehearsals are immutable private snapshots plus append-only evidence. A pure reducer derives completion, staleness, manual checks, and outstanding exact photo keys, while a small durable Booth evidence outbox preserves evidence created during the required offline/reload sequence.
+
+**Tech Stack:** Bun, TypeScript, Next.js 15 App Router, React 19, Cloudflare Workers, R2, IndexedDB, typed `en`/`zh-SG`/`ar` catalogs, QRCode, Playwright WebKit.
+
+## Global Constraints
+
+- Start only after Release 1 Booth auth/retry/heartbeat, Release 2 localization/handoff, and Release 3 public feed, exact-photo lookup, moderation, and exact deletion pass their complete gates.
+- Use Bun commands only.
+- `EventStore` remains the sole owner of `PHOTOS` and `STATE` keys.
+- Presets and rehearsals live only in private `STATE`.
+- Preset serialization constructs every allowed `EventExperience` field explicitly.
+- Presets cannot contain Event identity, Booth credentials or hashes, revision IDs, health, heartbeat, moderation, photo, or rehearsal state.
+- Applying a preset creates a normal config revision with `reason: "preset"`, a stable mutation ID, and the current `baseRevisionId`.
+- Applying a preset preserves an existing target Booth Key and leaves a new target Event visibly without one.
+- A config revision change makes an existing rehearsal stale even when the resulting experience is otherwise equivalent.
+- Rehearsal uploads retain stable capture identity and remain idempotent under retries or lost acknowledgements.
+- Rehearsal evidence is private, bounded, versioned, append-only, and idempotent by exact evidence identity.
+- Rehearsal completion never authorizes prefix deletion, automatic photo cleanup, or bulk cleanup.
+- The designated moderation canary is one exact rehearsal photo key deleted through the existing `DELETE /api/photos?event=&key=` contract.
+- Every other rehearsal photo is explicitly retained or individually deleted by complete key.
+- The rehearsal canary is not the short-lived `_health/canary`; `app/health.ts` keeps its existing independent exact cleanup behavior.
+- A stale or abandoned rehearsal continues to show every outstanding exact test-photo key.
+- All Event HTTP parameters use `canonicalEvent()` and reject aliases.
+- Every changed UI uses complete `en`, `zh-SG`, and `ar` catalogs, English fallback, at least 44×44 controls, visible forced-color focus, reduced-motion behavior, RTL-safe exact keys, and concise live announcements.
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+- Never deploy the unnamed Wrangler environment to an Event domain.
+
+---
+
+## File Structure
+
+- Create `app/event-preset.ts` — strict preset schema and explicit experience serialization.
+- Create `app/event-preset.test.ts` — preset validation, privacy, and serialization tests.
+- Modify `app/event-config.ts` — reuse/export explicit safe experience parsing/projection.
+- Modify `app/event-config.test.ts` — projection and preset-boundary regression tests.
+- Modify `app/event-store.ts` — private preset storage, preset application, rehearsal storage, and upload evidence.
+- Modify `app/event-store.test.ts` — CAS, idempotency, privacy, staleness, evidence, and exact-key tests.
+- Create `app/api/presets/handlers.ts` — dependency-injected Admin preset handlers.
+- Create `app/api/presets/handlers.test.ts` — auth, validation, conflict, and redaction tests.
+- Create `app/api/presets/route.ts` — preset list adapter.
+- Create `app/api/presets/[presetId]/route.ts` — preset create/update adapter.
+- Create `app/api/presets/apply/route.ts` — revisioned preset application adapter.
+- Create `app/[event]/admin/preset-state.ts` — pure preset request/reconciliation state.
+- Create `app/[event]/admin/preset-state.test.ts` — conflict, retry, and rebase tests.
+- Create `app/[event]/admin/preset-panel.tsx` — localized safe preset controls.
+- Create `app/[event]/admin/preset-panel.test.tsx` — accessible preset markup and busy-state tests.
+- Modify `app/[event]/admin/page.tsx` — authenticated preset and rehearsal integration.
+- Modify `app/[event]/admin/config-mutation.ts` — complete experience reconciliation after preset application.
+- Modify `app/[event]/admin/config-mutation.test.ts` — preset rebase and Booth-key preservation tests.
+- Modify `app/[event]/admin/config-history-panel.tsx` — localized preset revision reason.
+- Modify `app/[event]/admin/config-history-panel.test.tsx` — preset-source summary tests.
+- Create `app/rehearsal.ts` — strict session/evidence schemas and pure completion reducer.
+- Create `app/rehearsal.test.ts` — reduction, staleness, exact correlation, and bounds tests.
+- Modify `app/upload-contract.ts` — optional stable rehearsal identity header.
+- Modify `app/upload-contract.test.ts` — rehearsal header validation and legacy compatibility.
+- Modify `app/api/upload/handlers.ts` — require upload evidence before acknowledging rehearsal uploads.
+- Modify `app/api/upload/route.test.ts` — retry, evidence failure, and cross-Event tests.
+- Create `app/api/rehearsals/handlers.ts` — start/read/join/evidence HTTP handlers.
+- Create `app/api/rehearsals/handlers.test.ts` — role, auth, canonicalization, and evidence tests.
+- Create `app/api/rehearsals/route.ts` — Admin start/read adapter.
+- Create `app/api/rehearsals/join/route.ts` — Booth-or-Admin join adapter.
+- Create `app/api/rehearsals/evidence/route.ts` — append-only evidence adapter.
+- Create `app/[event]/booth-session/rehearsal-evidence-outbox.ts` — durable private operational evidence queue.
+- Create `app/[event]/booth-session/rehearsal-evidence-outbox.test.ts` — reload, ordering, and Event isolation tests.
+- Create `app/[event]/booth-session/rehearsal-client.ts` — join, evidence capture, and durable drain controller.
+- Create `app/[event]/booth-session/rehearsal-client.test.ts` — offline failure, reload, and ordered-drain tests.
+- Modify `app/[event]/booth-session/session.ts` — exact item/failure callbacks needed by rehearsal.
+- Modify `app/[event]/booth-session/session.test.ts` — callback isolation and acknowledgement ordering.
+- Modify `app/[event]/booth-session/upload.ts` — emit rehearsal identity from durable Outbox rows.
+- Modify `app/[event]/booth-session/upload.test.ts` — stable rehearsal header tests.
+- Create `app/[event]/rehearsal-status.tsx` — localized Booth rehearsal guidance.
+- Create `app/[event]/rehearsal-status.test.tsx` — accessible Booth status tests.
+- Create `app/[event]/admin/rehearsal-panel.tsx` — guided Admin checklist and exact photo disposition.
+- Create `app/[event]/admin/rehearsal-panel.test.tsx` — checklist, canary, stale, and abandon tests.
+- Modify `app/[event]/page.tsx` — safe rehearsal join/tag/recovery integration.
+- Modify `app/[event]/booth.module.css` — rehearsal guidance and accessibility.
+- Modify `app/[event]/admin/admin.module.css` — preset and rehearsal layouts.
+- Modify `app/i18n/catalog.ts` — complete preset/rehearsal messages.
+- Modify `app/i18n/catalog.test.ts` — exact key and placeholder parity.
+- Create `tests/rehearsal-operations.spec.ts` — mocked WebKit preset and rehearsal journeys.
+- Modify `docs/runbooks/pre-event-readiness.md` — real-device rehearsal procedure.
+- Modify `docs/runbooks/deployment.md` — Release 4 staging gate and exact disposition rules.
+
+### Task 1: Define and store safe reusable Event presets
+
+**Files:**
+- Create: `app/event-preset.ts`
+- Create: `app/event-preset.test.ts`
+- Modify: `app/event-config.ts`
+- Modify: `app/event-config.test.ts`
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: Release 0A revision-aware `EventExperience` and explicit safe projection.
+- Produces: strict `EventPreset` parsing and explicit safe serialization.
+- Produces: private bounded preset get/list/create/update methods.
+- Consumed by: Tasks 2–3.
+
+- [ ] **Step 1: Write failing preset schema and privacy tests**
+
+Define and test:
+
+```ts
+export type EventPreset = {
+  version: 1;
+  id: string;
+  label: string;
+  createdAt: string;
+  updatedAt: string;
+  config: EventExperience;
+};
+
+export function parseEventPreset(value: unknown): EventPreset | null;
+
+export function serializePresetExperience(
+  experience: EventExperience
+): EventExperience;
+```
+
+Prove a complete experience round-trips:
+
+```ts
+const experience: EventExperience = {
+  frames: ["square", "strip"],
+  locales: ["en", "zh-SG", "ar"],
+  defaultLocale: "en",
+  timeZone: "Asia/Singapore",
+  capture: {
+    reviewEnabled: true,
+    autoAcceptSeconds: 5,
+    countdownAudioDefault: false,
+  },
+  gallery: {
+    title: "Launch Night",
+    accentColor: "#c45f39",
+  },
+};
+```
+
+The serialized result must contain only those explicitly named fields and
+fresh nested arrays/objects. Add attempts containing `event`, `boothKey`,
+`boothKeyHash`, `currentRevisionId`, `health`, `booths`, `rehearsal`,
+`photos`, and arbitrary nested fields; none may enter the serialized or stored
+result. Reject unknown versions, invalid IDs, blank labels, labels over 80
+characters, invalid safe experience fields, and unexpected top-level keys.
+
+- [ ] **Step 2: Run focused tests and verify missing exports**
+
+```bash
+bun test app/event-preset.test.ts app/event-config.test.ts
+```
+
+Expected: FAIL because the preset module and exported safe experience helpers
+do not exist.
+
+- [ ] **Step 3: Implement explicit preset parsing and serialization**
+
+Use one strict preset ID contract:
+
+```ts
+export const isPresetId = (value: unknown): value is string =>
+  typeof value === "string"
+  && /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(value);
+```
+
+Export or reuse `parseEventExperience()` and `projectEventExperience()` from
+`app/event-config.ts`. `serializePresetExperience()` must construct `frames`,
+`locales`, `defaultLocale`, `timeZone`, `capture`, and `gallery` explicitly;
+never spread an HTTP body or `EventConfig`.
+
+- [ ] **Step 4: Write failing private store and conflict tests**
+
+Define:
+
+```ts
+export const eventPresetKey = (presetId: string) =>
+  `presets/${presetId}.json`;
+
+export const eventPresetPrefix = () => "presets/";
+
+EventStore.getEventPreset(
+  presetId: string
+): Promise<EventPreset | null>;
+
+EventStore.listEventPresets(options?: {
+  cursor?: string;
+  limit?: number;
+}): Promise<{
+  presets: EventPreset[];
+  cursor: string | null;
+}>;
+
+EventStore.putEventPreset(
+  presetId: string,
+  input: {
+    label: string;
+    config: EventExperience;
+    expectedUpdatedAt: string | null;
+  }
+): Promise<EventPreset>;
+```
+
+Test:
+
+- `expectedUpdatedAt: null` is create-only.
+- Updating requires the exact currently observed `updatedAt`.
+- `createdAt` remains unchanged and server time controls `updatedAt`.
+- Concurrent stale updates produce a dedicated preset conflict.
+- Lists accept opaque cursors and limits `1..100`, default `50`.
+- Corrupt or unsupported stored versions fail explicitly.
+- Presets are sorted by label then ID without trusting client locale.
+- Only `STATE/presets/{id}.json` is written.
+- `PHOTOS`, Events, config revisions, and adjacent presets stay untouched.
+- No delete method or prefix cleanup exists.
+
+- [ ] **Step 5: Implement CAS-backed private preset methods**
+
+Use `ObjectStore.compareAndSwap()` with the exact stored etag. For create,
+compare against `null`. For update, read and validate the record, compare
+`expectedUpdatedAt`, then CAS against its etag. A lost response followed by a
+retry may return a conflict; the Admin reconciles by reloading and comparing
+the safe content rather than overwriting a newer change.
+
+- [ ] **Step 6: Run focused and full checks**
+
+```bash
+bun test app/event-preset.test.ts app/event-config.test.ts app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/event-preset.ts app/event-preset.test.ts \
+  app/event-config.ts app/event-config.test.ts \
+  app/event-store.ts app/event-store.test.ts
+git commit -m "feat: store reusable event presets"
+```
+
+### Task 2: Apply presets through configuration history and expose Admin APIs
+
+**Files:**
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+- Modify: `app/api/config/handlers.ts`
+- Modify: `app/api/config/handlers.test.ts`
+- Create: `app/api/presets/handlers.ts`
+- Create: `app/api/presets/handlers.test.ts`
+- Create: `app/api/presets/route.ts`
+- Create: `app/api/presets/[presetId]/route.ts`
+- Create: `app/api/presets/apply/route.ts`
+
+**Interfaces:**
+- Consumes: Task 1 presets and Release 0A config revision CAS/idempotency.
+- Produces: normal `reason: "preset"` revisions with `sourcePresetId`.
+- Produces: Admin-only list, create/update, and apply HTTP contracts.
+- Consumed by: Task 3 and rehearsal staleness in Task 4.
+
+- [ ] **Step 1: Write failing preset-application mutation tests**
+
+Define:
+
+```ts
+export type ConfigPresetApplyInput = {
+  presetId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+};
+
+EventStore.applyEventPreset(
+  event: string,
+  input: ConfigPresetApplyInput
+): Promise<ConfigMutationResult>;
+```
+
+Extend the private config mutation intent with an exact preset variant:
+
+```ts
+type ConfigPresetMutationIntent = {
+  version: 1;
+  config: EventExperience;
+  baseRevisionId: string | null;
+  boothKeyMutationFingerprint: null;
+  reason: "preset";
+  sourcePresetId: string;
+};
+```
+
+Test:
+
+- Applying creates a reachable revision with `reason: "preset"` and the exact
+  `sourcePresetId`.
+- The revision contains only preset `EventExperience`.
+- An existing target `boothKeyHash` remains byte-identical.
+- A target without a Booth Key remains without one.
+- Applying over a legacy unrevisioned head creates the normal baseline.
+- Same mutation ID/body retry is idempotent.
+- Reusing a mutation ID for another preset, another base, or changed preset
+  content conflicts.
+- Stale base returns `ConfigConflictError`.
+- Missing preset returns a dedicated not-found error.
+- Concurrent apply/save has one head winner and harmless unreachable records.
+- Save and Restore behavior remains unchanged.
+
+- [ ] **Step 2: Run Event Store tests and verify failures**
+
+```bash
+bun test app/event-store.test.ts
+```
+
+Expected: FAIL because preset application and the preset mutation-intent
+variant do not exist.
+
+- [ ] **Step 3: Extend the existing revision append seam**
+
+Extend `ConfigAppendInput`, intent parsing, matching, and revision construction
+to accept:
+
+```ts
+{
+  reason: "preset";
+  sourcePresetId: string;
+  sourceRevisionId?: never;
+  boothKeyMutationFingerprint: null;
+}
+```
+
+Call the same private `appendConfigRevision()` used by Save and Restore.
+`mergedRevisionHead()` remains the only place that preserves the current Booth
+hash. Do not create a preset-specific config head write path.
+
+- [ ] **Step 4: Write failing handler and route tests**
+
+HTTP contracts:
+
+```text
+GET  /api/presets?cursor=&limit=
+PUT  /api/presets/{presetId}
+POST /api/presets/apply?event=
+```
+
+PUT body:
+
+```ts
+{
+  label: string;
+  config: EventExperience;
+  expectedUpdatedAt: string | null;
+}
+```
+
+Apply body:
+
+```ts
+{
+  presetId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+}
+```
+
+Test missing Admin secret `503`, wrong key `401`, invalid ID/body `400`,
+missing preset `404`, stale preset/config `409`, opaque bounded paging,
+canonical Event rejection, exact response allowlists, and zero store calls
+after failed auth. Attempt credential/state fields in the PUT body and prove
+they are rejected before any write.
+
+- [ ] **Step 5: Implement dependency-injected handlers and thin routes**
+
+Add:
+
+```ts
+export type PresetHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+};
+```
+
+All handlers require Admin auth before storage. The apply response is:
+
+```ts
+{
+  config: PublicEventConfig;
+  currentRevisionId: string;
+  sourcePresetId: string;
+  idempotent: boolean;
+}
+```
+
+Construct every response field explicitly. Route modules only obtain
+Cloudflare bindings, construct `EventStore`, and delegate.
+
+- [ ] **Step 6: Run focused and full checks**
+
+```bash
+bun test app/event-store.test.ts \
+  app/api/config/handlers.test.ts \
+  app/api/presets/handlers.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/event-store.ts app/event-store.test.ts \
+  app/api/config app/api/presets
+git commit -m "feat: apply presets through config revisions"
+```
+
+### Task 3: Add the localized Admin preset workflow
+
+**Files:**
+- Create: `app/[event]/admin/preset-state.ts`
+- Create: `app/[event]/admin/preset-state.test.ts`
+- Create: `app/[event]/admin/preset-panel.tsx`
+- Create: `app/[event]/admin/preset-panel.test.tsx`
+- Modify: `app/[event]/admin/page.tsx`
+- Modify: `app/[event]/admin/config-mutation.ts`
+- Modify: `app/[event]/admin/config-mutation.test.ts`
+- Modify: `app/[event]/admin/config-history-panel.tsx`
+- Modify: `app/[event]/admin/config-history-panel.test.tsx`
+- Modify: `app/[event]/admin/admin.module.css`
+- Modify: `app/i18n/catalog.ts`
+- Modify: `app/i18n/catalog.test.ts`
+
+**Interfaces:**
+- Consumes: Task 2 APIs and Release 2 complete safe Admin experience state.
+- Produces: safe preset create/update/apply controls with retry reconciliation.
+- Preserves: the one shared config mutation guard and Booth plaintext rules.
+
+- [ ] **Step 1: Write failing pure preset-state tests**
+
+Define:
+
+```ts
+export type PendingPresetApply = {
+  presetId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+};
+
+export function mergePresetPage(
+  current: readonly EventPreset[],
+  incoming: readonly EventPreset[]
+): EventPreset[];
+
+export function getOrCreatePresetApply(
+  pending: Map<string, PendingPresetApply>,
+  presetId: string,
+  baseRevisionId: string | null,
+  makeId: () => string
+): PendingPresetApply;
+
+export function reconcileAppliedPreset(input: {
+  response: PublicEventConfig & { currentRevisionId: string };
+  history: ConfigHistoryResponse;
+  sourcePresetId: string;
+}): {
+  experience: EventExperience;
+  currentRevisionId: string;
+  hasBoothKey: boolean;
+};
+```
+
+Test exact-ID page dedupe, updated preset replacement, label/ID ordering,
+stable apply tuple retries, base changes, stale response rejection, complete
+experience rebase, and server-authoritative `hasBoothKey`.
+
+- [ ] **Step 2: Write failing accessible preset-panel tests**
+
+Render and assert:
+
+- Labelled preset ID and label fields.
+- “Save current setup as preset” summary covering Frames, locales, capture,
+  time zone, and Gallery settings.
+- Create-only and selected-preset update states.
+- Apply confirmation naming the target Event and preset.
+- A visible statement that Booth credentials are never copied.
+- A warning when the target Event has no Booth Key.
+- No Delete button.
+- Separate Apply/Cancel controls, at least 44×44.
+- Busy/disabled state under Save, Restore, or Apply.
+- Polite success and assertive error regions.
+- RTL-safe IDs in `<bdi><code>`.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test 'app/[event]/admin/preset-state.test.ts' \
+  'app/[event]/admin/preset-panel.test.tsx'
+```
+
+Expected: FAIL because the Admin preset modules do not exist.
+
+- [ ] **Step 4: Implement authenticated loading and safe preset saves**
+
+After Admin authentication, load preset pages with `Cache-Control: no-store`.
+Route `401` through the existing Admin invalidation. A preset request failure
+must not disable config, moderation, Booth controls, health, or export.
+
+Create the body from the complete current safe experience held by Admin. Never
+read Booth plaintext or `hasBoothKey` into preset content. Updates send the
+selected preset's exact `updatedAt`.
+
+- [ ] **Step 5: Integrate revisioned Apply with the config mutation guard**
+
+Apply shares `configMutationBusy` with Save and Restore. Retain the complete
+request tuple across network, 5xx, body-parse, and history-refresh failures.
+Clear it only after response parsing and config-history reconciliation.
+
+On success:
+
+- Rebase every safe experience field, not only Frames.
+- Clear unsaved Booth plaintext and copied-key state.
+- Preserve `hasBoothKey` only from the server response.
+- Reload history and render “Applied preset {label}” using
+  `sourcePresetId`.
+
+On `409`, clear the stale tuple, reload both config history and presets, and
+show the existing review-before-saving conflict pattern.
+
+- [ ] **Step 6: Extend complete catalogs and accessible styling**
+
+Add every preset label, status, confirmation, warning, conflict, empty, and
+error key to `en`, `zh-SG`, and `ar`. Keep exact key and placeholder parity.
+Add visible high-contrast/forced-color focus, RTL layout, reduced motion, and
+200% text reflow.
+
+- [ ] **Step 7: Run focused and full checks**
+
+```bash
+bun test 'app/[event]/admin/preset-state.test.ts' \
+  'app/[event]/admin/preset-panel.test.tsx' \
+  'app/[event]/admin/config-mutation.test.ts' \
+  'app/[event]/admin/config-history-panel.test.tsx' \
+  app/i18n/catalog.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add 'app/[event]/admin' app/i18n
+git commit -m "feat: manage event presets in admin"
+```
+
+### Task 4: Define rehearsal evidence, completion reduction, and private storage
+
+**Files:**
+- Create: `app/rehearsal.ts`
+- Create: `app/rehearsal.test.ts`
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: config revisions, stable capture IDs, Booth device IDs, and exact photo keys.
+- Produces: strict rehearsal session/evidence schemas and pure completion reduction.
+- Produces: private create-only session/evidence storage and latest pointer.
+- Consumed by: Tasks 5–7.
+
+- [ ] **Step 1: Write failing session and evidence schema tests**
+
+Define:
+
+```ts
+export type RehearsalSession = {
+  version: 1;
+  id: string;
+  startedAt: string;
+  configRevisionId: string | null;
+  frames: string[];
+};
+
+type RehearsalEvidenceBase = {
+  version: 1;
+  id: string;
+  rehearsalId: string;
+  observedAt: number;
+  recordedAt: string;
+};
+```
+
+Define a strict discriminated evidence union:
+
+```ts
+type RehearsalEvidence =
+  | (RehearsalEvidenceBase & {
+      kind: "booth-ready";
+      deviceId: string;
+      bootId: string;
+      cameraReady: true;
+      durableStorage: true;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "network-failure";
+      captureId: string;
+      bootId: string;
+      errorClass: "network" | "timeout";
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "outbox-recovered";
+      previousBootId: string;
+      bootId: string;
+      captureIds: string[];
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "photo-acknowledged";
+      captureId: string;
+      capturedAt: number;
+      frameKey?: string;
+      photoKey: string;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "ordered-drain";
+      bootId: string;
+      captureIds: string[];
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "delivery-observed";
+      photoKey: string;
+      feedObserved: true;
+      publicImageObserved: true;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "canary-designated";
+      photoKey: string;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "canary-deleted";
+      photoKey: string;
+      cleanupPending: boolean;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "outbox-empty";
+      bootId: string;
+      pendingCount: 0;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "photo-retained" | "photo-deleted";
+      photoKey: string;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "manual-check";
+      check: "composition" | "projector" | "power" | "charging" | "backup-network";
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "abandoned";
+    });
+```
+
+Require lowercase UUID-v4 session, device, boot, capture, and client evidence
+IDs; exact safe Frame tokens; integer 13-digit millisecond fields; complete
+Event-owned image keys where an Event is supplied; maximum 256 IDs per array;
+and exact keys for each union member. Reject unknown fields, arbitrary error
+text, credentials, URLs, headers, user agents, unsupported versions, and
+cross-Event keys.
+
+- [ ] **Step 2: Write failing completion-reducer tests**
+
+Define:
+
+```ts
+export type RehearsalRequirement =
+  | "booth-ready"
+  | "frames-covered"
+  | "two-network-failures"
+  | "reload-recovered"
+  | "ordered-drain"
+  | "public-delivery"
+  | "canary-deleted"
+  | "outbox-empty";
+
+export function reduceRehearsal(input: {
+  session: RehearsalSession;
+  evidence: readonly RehearsalEvidence[];
+  currentRevisionId: string | null;
+}): RehearsalSummary;
+```
+
+Test:
+
+- Authenticated readiness requires camera and durable storage in one record.
+- Every snapshot Frame requires one acknowledged record with that Frame.
+- Camera fallback never satisfies Frame coverage.
+- Network failures require two distinct capture IDs.
+- Recovery contains both failed IDs and a boot ID different from their failure
+  boot.
+- Ordered drain exactly matches the recovered order and every ID is
+  acknowledged.
+- Delivery observation refers to one acknowledged key and proves both feed and
+  public bytes.
+- Canary designation/deletion use the same acknowledged exact key.
+- Empty Outbox is explicit.
+- Any revision mismatch marks the summary stale.
+- `null` remains non-stale only while both snapshot and current head are
+  `null`.
+- `remainingExactKeys` includes acknowledged photos without retained/deleted
+  disposition and excludes the confirmed canary.
+- Abandonment never hides outstanding keys.
+- Manual checks are separate from the eight evidence requirements.
+- Duplicate/idempotent evidence cannot overcount requirements.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test app/rehearsal.test.ts
+```
+
+Expected: FAIL because the schema and reducer do not exist.
+
+- [ ] **Step 4: Implement strict parsing and a deterministic pure reducer**
+
+Sort evidence by `recordedAt`, then exact evidence key/ID; never trust client
+clock for sequence. Reduce exact capture/key sets without fuzzy filename or URL
+matching. Return:
+
+```ts
+type RehearsalSummary = {
+  status: "active" | "stale" | "complete" | "abandoned";
+  stale: boolean;
+  requirements: Record<RehearsalRequirement, {
+    complete: boolean;
+    evidenceIds: string[];
+  }>;
+  manualChecks: Record<
+    "composition" | "projector" | "power" | "charging" | "backup-network",
+    boolean
+  >;
+  trackedPhotos: {
+    captureId: string;
+    frameKey?: string;
+    photoKey: string;
+    disposition: "pending" | "canary-deleted" | "retained" | "deleted";
+  }[];
+  remainingExactKeys: string[];
+};
+```
+
+`status: "complete"` means the eight required evidence checks pass and the
+session is not stale/abandoned. Manual checks and remaining dispositions stay
+visible rather than silently changing the evidence definition.
+
+- [ ] **Step 5: Write failing private Event Store tests**
+
+Define keys:
+
+```ts
+export const rehearsalSessionKey = (event: string, rehearsalId: string) =>
+  `events/${event}/rehearsals/${rehearsalId}/session.json`;
+
+export const rehearsalEvidencePrefix = (event: string, rehearsalId: string) =>
+  `events/${event}/rehearsals/${rehearsalId}/evidence/`;
+
+export const rehearsalEvidenceKey = (
+  event: string,
+  rehearsalId: string,
+  observedAt: number,
+  evidenceId: string
+) => `${rehearsalEvidencePrefix(event, rehearsalId)}${String(observedAt).padStart(13, "0")}-${evidenceId}.json`;
+
+export const latestRehearsalKey = (event: string) =>
+  `events/${event}/rehearsals/latest.json`;
+```
+
+Define:
+
+```ts
+EventStore.startRehearsal(
+  event: string,
+  input: { rehearsalId: string }
+): Promise<RehearsalSession>;
+
+EventStore.readRehearsal(
+  event: string,
+  rehearsalId?: string
+): Promise<{
+  session: RehearsalSession;
+  evidence: RehearsalEvidence[];
+}>;
+
+EventStore.appendRehearsalEvidence(
+  event: string,
+  rehearsalId: string,
+  evidence: RehearsalEvidenceInput
+): Promise<{
+  evidence: RehearsalEvidence;
+  idempotent: boolean;
+}>;
+```
+
+Test immutable config-revision/Frame snapshot, create-only session, lost start
+response retry, exact latest pointer, same-evidence retry, differing-evidence
+collision, server-controlled `recordedAt`, at most 512 records, paged reads,
+corrupt/future versions, cross-Event isolation, and zero `PHOTOS` writes or
+deletes. A latest-pointer failure may leave a harmless private orphan; retrying
+the same rehearsal ID finishes the pointer without replacing the snapshot.
+
+- [ ] **Step 6: Implement private session/evidence storage**
+
+`startRehearsal()` reads the current config head, snapshots its exact
+`currentRevisionId` and enabled Frames, create-only writes the session, then
+writes the small latest pointer. It never mutates config to manufacture a
+revision.
+
+Evidence uses create-only CAS. If the key exists, parse it and require exact
+semantic equality for idempotent success. No rehearsal method lists or deletes
+a `PHOTOS` prefix, and no completion/abandon method deletes any photo.
+
+- [ ] **Step 7: Run focused and full checks**
+
+```bash
+bun test app/rehearsal.test.ts app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add app/rehearsal.ts app/rehearsal.test.ts \
+  app/event-store.ts app/event-store.test.ts
+git commit -m "feat: reduce private rehearsal evidence"
+```
+
+### Task 5: Expose rehearsal APIs and require upload evidence before acknowledgement
+
+**Files:**
+- Modify: `app/upload-contract.ts`
+- Modify: `app/upload-contract.test.ts`
+- Modify: `app/[event]/booth-session/upload.ts`
+- Modify: `app/[event]/booth-session/upload.test.ts`
+- Modify: `app/api/upload/handlers.ts`
+- Modify: `app/api/upload/route.test.ts`
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+- Create: `app/api/rehearsals/handlers.ts`
+- Create: `app/api/rehearsals/handlers.test.ts`
+- Create: `app/api/rehearsals/route.ts`
+- Create: `app/api/rehearsals/join/route.ts`
+- Create: `app/api/rehearsals/evidence/route.ts`
+
+**Interfaces:**
+- Consumes: Task 4 private store, stable upload identity, and shared `boothOrAdminOk()`.
+- Produces: Admin start/read, safe Booth join, append-only evidence, and tracked uploads.
+- Preserves: legacy/non-rehearsal upload behavior and exact moderation deletion.
+
+- [ ] **Step 1: Write failing rehearsal upload-header tests**
+
+Extend stable upload types:
+
+```ts
+export type StableUpload = StableCaptureIdentity & {
+  source?: CaptureSource;
+  frameKey?: string;
+  configRevisionId?: string;
+  rehearsalId?: string;
+};
+```
+
+Emit `x-rehearsal-id` only when present. Test complete round trip, malformed
+UUID, metadata without stable capture identity, unknown-header tolerance,
+legacy requests with no new headers, and `outboxUploadHeaders()` preserving a
+durable row's `rehearsalId` across reload.
+
+- [ ] **Step 2: Write failing tracked-upload and retry tests**
+
+Add:
+
+```ts
+EventStore.recordRehearsalUpload(
+  event: string,
+  rehearsalId: string,
+  upload: StableUpload,
+  photo: Pick<PutPhotoResult, "key" | "duplicate">
+): Promise<RehearsalEvidence>;
+```
+
+The deterministic evidence identity is `upload-${captureId}`. Test:
+
+- It requires an existing same-Event session.
+- The evidence uses the complete returned photo key.
+- Exact retry is idempotent.
+- Another photo for the same evidence identity conflicts.
+- Evidence failure after photo/index write leaves one public image.
+- Identical upload retry creates missing evidence and returns the same photo as
+  a duplicate.
+- Cross-Event rehearsal IDs do not attach evidence.
+- Receipt failure remains best-effort.
+- Rehearsal evidence failure does not weaken stable index requirements.
+
+- [ ] **Step 3: Write failing rehearsal handler tests**
+
+HTTP contracts:
+
+```text
+POST /api/rehearsals?event=
+GET  /api/rehearsals?event=&id=
+POST /api/rehearsals/join?event=
+POST /api/rehearsals/evidence?event=&id=
+```
+
+Start body:
+
+```ts
+{ rehearsalId: string }
+```
+
+Join body:
+
+```ts
+{ rehearsalId: string }
+```
+
+Join returns only:
+
+```ts
+{
+  rehearsal: {
+    id: string;
+    startedAt: string;
+    configRevisionId: string | null;
+    frames: string[];
+    stale: boolean;
+  };
+  serverTime: string;
+}
+```
+
+Test:
+
+- Start/read are Admin-only.
+- Join and Booth evidence accept matching Booth or Admin auth.
+- Missing Admin secret fails closed.
+- Canonical aliases return `400`.
+- Missing session returns `404`.
+- Stale join returns the safe session with `stale: true`.
+- Booth can append only readiness/failure/recovery/drain/empty evidence.
+- Canary, dispositions, manual checks, and abandon are Admin-only.
+- Unknown/unbounded fields are rejected before writes.
+- Admin read returns the pure reduced summary and allowlisted evidence without
+  storage keys.
+- No endpoint returns credentials, hashes, heartbeat records, arbitrary
+  errors, or private R2 key names.
+
+- [ ] **Step 4: Run focused tests and verify failures**
+
+```bash
+bun test app/upload-contract.test.ts \
+  'app/[event]/booth-session/upload.test.ts' \
+  app/api/upload/route.test.ts \
+  app/api/rehearsals/handlers.test.ts \
+  app/event-store.test.ts
+```
+
+Expected: FAIL because rehearsal upload tracking and handlers do not exist.
+
+- [ ] **Step 5: Implement tracked upload acknowledgement**
+
+In `handleUpload()`:
+
+1. Parse rehearsal/stable headers before the body.
+2. Authenticate and validate the same-Event rehearsal before the photo write.
+3. Perform deterministic photo/index ingest.
+4. Create server-generated `photo-acknowledged` evidence.
+5. Return success only after that evidence exists.
+
+Map rehearsal evidence write failure to:
+
+```ts
+NextResponse.json(
+  { error: "rehearsal evidence unavailable", retryable: true },
+  { status: 503, headers: { "Retry-After": "1" } }
+);
+```
+
+Stable retry finishes evidence without duplicating the image. Invalid/missing
+rehearsal identity returns `409` before photo bytes are written. Non-rehearsal
+stable uploads and all legacy behavior remain unchanged.
+
+- [ ] **Step 6: Implement handlers and thin route adapters**
+
+Add:
+
+```ts
+export type RehearsalHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+};
+```
+
+Role-check each evidence kind explicitly. Route modules own no private key
+construction. Use `Cache-Control: no-store` for every rehearsal response.
+
+Canary deletion remains outside these routes:
+
+```text
+DELETE /api/photos?event={canonical-event}&key={complete-event-owned-key}
+```
+
+The evidence endpoint records designation and confirmed outcome but never
+performs bulk or prefix cleanup.
+
+- [ ] **Step 7: Run focused and full checks**
+
+```bash
+bun test app/upload-contract.test.ts \
+  'app/[event]/booth-session/upload.test.ts' \
+  app/api/upload/route.test.ts \
+  app/api/rehearsals/handlers.test.ts \
+  app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add app/upload-contract.ts app/upload-contract.test.ts \
+  'app/[event]/booth-session/upload.ts' \
+  'app/[event]/booth-session/upload.test.ts' \
+  app/api/upload app/api/rehearsals \
+  app/event-store.ts app/event-store.test.ts
+git commit -m "feat: track authenticated rehearsal uploads"
+```
+
+### Task 6: Guide the Booth and Admin through a durable real-device rehearsal
+
+**Files:**
+- Create: `app/[event]/booth-session/rehearsal-evidence-outbox.ts`
+- Create: `app/[event]/booth-session/rehearsal-evidence-outbox.test.ts`
+- Create: `app/[event]/booth-session/rehearsal-client.ts`
+- Create: `app/[event]/booth-session/rehearsal-client.test.ts`
+- Modify: `app/[event]/booth-session/session.ts`
+- Modify: `app/[event]/booth-session/session.test.ts`
+- Create: `app/[event]/rehearsal-status.tsx`
+- Create: `app/[event]/rehearsal-status.test.tsx`
+- Create: `app/[event]/admin/rehearsal-panel.tsx`
+- Create: `app/[event]/admin/rehearsal-panel.test.tsx`
+- Modify: `app/[event]/page.tsx`
+- Modify: `app/[event]/admin/page.tsx`
+- Modify: `app/[event]/booth.module.css`
+- Modify: `app/[event]/admin/admin.module.css`
+- Modify: `app/i18n/catalog.ts`
+- Modify: `app/i18n/catalog.test.ts`
+
+**Interfaces:**
+- Consumes: Release 1 preflight/retry/outbox, Task 5 APIs, Release 3 feed/exact deletion, and Task 4 reducer.
+- Produces: durable offline evidence, guided Booth state, and exact Admin rehearsal operations.
+- Preserves: Photo Outbox ordering, independent draining, and fresh Frame choice.
+
+- [ ] **Step 1: Write failing durable evidence-outbox tests**
+
+Define:
+
+```ts
+export type PendingRehearsalEvidence = {
+  id: string;
+  event: string;
+  rehearsalId: string;
+  createdAt: number;
+  attempts: number;
+  evidence: RehearsalEvidenceInput;
+};
+
+export interface RehearsalEvidenceOutbox {
+  isDurable(): boolean;
+  list(event: string, rehearsalId: string): Promise<PendingRehearsalEvidence[]>;
+  put(item: PendingRehearsalEvidence): Promise<void>;
+  remove(id: string): Promise<void>;
+}
+
+export function createRehearsalEvidenceOutbox(
+  indexedDB?: IDBFactory | null
+): RehearsalEvidenceOutbox;
+```
+
+Use a separate additive database named `ipad-webbooth-rehearsal` with store
+`evidence-outbox`; do not version-race or migrate the Photo Outbox database.
+
+Test durable reload, created-at/ID ordering, exact remove, retry fields,
+Event/rehearsal isolation, memory fallback, visible degraded durability, and
+zero access to `photo-outbox`.
+
+- [ ] **Step 2: Write failing Session callback and rehearsal-controller tests**
+
+Extend Session observation without letting callbacks affect persistence:
+
+```ts
+type BoothSessionObserver = {
+  onAcknowledged?: (item: OutboxItem, result: UploadResult) => void;
+  onUploadFailure?: (
+    item: OutboxItem,
+    failure: { kind: "retryable" | "permanent" | "auth"; errorClass: UploadErrorClass }
+  ) => void;
+};
+```
+
+Test callbacks run only after durable state is saved, throwing callbacks cannot
+change queue state, and acknowledgement identifies the exact removed item.
+
+Define:
+
+```ts
+export class RehearsalClient {
+  join(): Promise<void>;
+  recordReadiness(input: {
+    deviceId: string;
+    cameraReady: boolean;
+    durableStorage: boolean;
+  }): Promise<void>;
+  recordUploadFailure(item: OutboxItem, failure: ClassifiedFailure): Promise<void>;
+  recordRecovery(items: readonly OutboxItem[]): Promise<void>;
+  recordAcknowledgement(item: OutboxItem): Promise<void>;
+  recordEmptyOutbox(): Promise<void>;
+  drainEvidence(): Promise<void>;
+  stop(): void;
+}
+```
+
+Test:
+
+- Join occurs only after successful preflight.
+- One new `bootId` is generated per page load.
+- Only new accepted rows receive the active `rehearsalId`.
+- Two network-class failures are persisted before scheduling/reload.
+- Permanent/auth/server failures do not masquerade as network evidence.
+- Reload under a new boot ID records the exact prior ordered capture IDs.
+- Acknowledgement sequence creates matching ordered-drain evidence.
+- Empty Outbox creates one idempotent evidence item.
+- Evidence drains oldest-first and leaves storage only after server ack.
+- Evidence failure never blocks Photo Outbox drain.
+- Online/foreground immediately reconsiders evidence.
+- Leaving rehearsal stops tagging new rows but does not alter existing rows.
+
+- [ ] **Step 3: Write failing Booth and Admin component tests**
+
+Booth status must render:
+
+- Rehearsal name/ID and visible operator context.
+- Stale warning that blocks new rehearsal captures but allows Outbox drain.
+- Current Frame coverage and pending evidence count.
+- Durable-evidence warning.
+- Localized next-step guidance.
+- A visible Leave Rehearsal action.
+
+Admin panel must render:
+
+- Start/new-session control and confirmation.
+- Local QR plus visible `/{event}?rehearsal={id}` link.
+- All eight reducer requirements.
+- Five explicit manual checks.
+- Exact tracked keys in `<bdi><code>`.
+- Canary selector limited to acknowledged rehearsal photos.
+- Exact delete confirmation with filename and complete key.
+- Separate Retain and Delete Exact Photo actions for every non-canary photo.
+- No cleanup-all or bulk-delete control.
+- Stale and abandoned state with outstanding exact keys still visible.
+- Focus restoration, live status, 44×44 controls, forced-color focus, RTL,
+  and reduced motion.
+
+- [ ] **Step 4: Run focused tests and verify failures**
+
+```bash
+bun test 'app/[event]/booth-session/rehearsal-evidence-outbox.test.ts' \
+  'app/[event]/booth-session/rehearsal-client.test.ts' \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/rehearsal-status.test.tsx' \
+  'app/[event]/admin/rehearsal-panel.test.tsx'
+```
+
+Expected: FAIL because the durable evidence controller and presentations do
+not exist.
+
+- [ ] **Step 5: Implement Booth rehearsal integration**
+
+Admin generates a link with only the public rehearsal ID; never include a
+credential. The Booth:
+
+1. Recovers the Photo Outbox before auth as Release 1 requires.
+2. Completes online authenticated preflight.
+3. Joins the rehearsal and displays stale state if applicable.
+4. Starts camera/readiness evidence only after join.
+5. Tags only newly accepted captures with `rehearsalId`.
+6. Persists network evidence locally before any reload can lose it.
+7. On reload, filters recovered exact rows by rehearsal ID and records their
+   order with the new boot ID.
+8. Lets stable uploads create server acknowledgement evidence.
+9. Records ordered drain and empty Outbox without blocking the next guest.
+
+Pause, auth-required, installed exit, Retake, handoff, and fresh Frame choice
+retain their existing semantics.
+
+- [ ] **Step 6: Implement Admin public observation and exact canary flow**
+
+The “Observe public delivery” action:
+
+1. Fetches public `GET /api/photos?event={event}`.
+2. Locates one exact acknowledged rehearsal key.
+3. Fetches the exact public URL returned by that response.
+4. Requires a successful byte response.
+5. Appends `delivery-observed` for that same exact key.
+
+The canary action:
+
+1. Appends `canary-designated` for one acknowledged exact key.
+2. Calls the existing exact `DELETE /api/photos?event=&key=`.
+3. Treats `deleted: true` as authoritative even when cleanup is pending.
+4. Appends `canary-deleted` with the exact same key and cleanup status.
+5. Never retries a confirmed public deletion.
+
+All other photos receive individual Retain or Delete Exact Photo actions.
+Completion and abandonment trigger no photo cleanup.
+
+- [ ] **Step 7: Integrate Admin polling and staleness**
+
+After Admin auth, load the latest rehearsal and refresh with completion-driven
+non-overlapping requests. Route `401` through the shared invalidation. Config
+revision mismatch derives stale state client/server-side; do not write stale
+markers or overwrite evidence. “Start new rehearsal” creates a new immutable
+session and leaves the old one readable.
+
+- [ ] **Step 8: Extend complete catalogs and styles**
+
+Add every Booth/Admin rehearsal action, requirement, manual check, error,
+empty, stale, abandon, canary, exact-disposition, and evidence durability key
+to `en`, `zh-SG`, and `ar`. Preserve exact key and placeholder parity.
+
+- [ ] **Step 9: Run focused and full checks**
+
+```bash
+bun test 'app/[event]/booth-session/rehearsal-evidence-outbox.test.ts' \
+  'app/[event]/booth-session/rehearsal-client.test.ts' \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/rehearsal-status.test.tsx' \
+  'app/[event]/admin/rehearsal-panel.test.tsx' \
+  app/i18n/catalog.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add 'app/[event]/booth-session' \
+  'app/[event]/rehearsal-status.tsx' \
+  'app/[event]/rehearsal-status.test.tsx' \
+  'app/[event]/page.tsx' \
+  'app/[event]/booth.module.css' \
+  'app/[event]/admin' app/i18n
+git commit -m "feat: guide real-device rehearsals"
+```
+
+### Task 7: Add browser coverage, runbooks, and the Release 4 gate
+
+**Files:**
+- Create: `tests/rehearsal-operations.spec.ts`
+- Modify: `.github/workflows/verify.yml` only if Release 1–3 browser coverage is not already retained.
+- Modify: `docs/runbooks/pre-event-readiness.md`
+- Modify: `docs/runbooks/deployment.md`
+
+**Interfaces:**
+- Consumes: Tasks 1–6 and the Release 1 Playwright WebKit setup.
+- Produces: repeatable automated coverage plus mandatory staging/real-device evidence.
+
+- [ ] **Step 1: Add failing WebKit preset journeys**
+
+Intercept preset/config APIs and test:
+
+- Create, list, update, and apply a complete safe preset.
+- Attempted credential/state fields are rejected.
+- Existing Booth Key remains installed after apply.
+- A new Event remains visibly keyless after apply.
+- Lost response retry reconciles without a second revision.
+- Stale preset/config conflicts reload before another mutation.
+- Applying changes every safe experience control.
+- History shows the exact preset source.
+- Keyboard, Arabic RTL, forced colors, reduced motion, 200% text, and no
+  serious axe violations.
+
+- [ ] **Step 2: Add failing WebKit rehearsal journeys**
+
+Mock camera, IndexedDB, upload, feed, public bytes, exact delete, and evidence
+APIs. Test:
+
+- Booth never joins before authenticated preflight.
+- Camera readiness and durable storage evidence.
+- One acknowledged capture for every enabled Frame.
+- Two distinct network-class failures persisted before reload.
+- Reload creates another boot ID and recovers both exact rows in order.
+- Reconnection drains in order and creates no duplicate photos.
+- Feed and public byte observation correlate one exact key.
+- One exact canary deletion leaves adjacent photos intact.
+- Cleanup-pending does not invite another public DELETE.
+- Empty Outbox completes the eighth requirement.
+- Remaining photos are not deleted at completion.
+- Each Retain/Delete action targets one complete key.
+- Config mutation marks the rehearsal stale.
+- Abandonment retains the exact outstanding-key inventory.
+- Evidence endpoint failure never blocks Photo Outbox drain.
+- Keyboard/focus/live regions, Arabic RTL, forced colors, reduced motion,
+  200% text, and no serious axe violations.
+
+- [ ] **Step 3: Run browser coverage and fix deterministic failures**
+
+```bash
+bun run test:browser -- tests/rehearsal-operations.spec.ts
+```
+
+Expected: PASS without staging or production traffic.
+
+- [ ] **Step 4: Update the pre-event readiness runbook**
+
+Add a mandatory staging-first guided rehearsal:
+
+1. Use a throwaway canonical staging Event distinct from production.
+2. Apply the intended preset and separately install/verify its Booth Key.
+3. Open the generated rehearsal link on the actual iPad over HTTPS.
+4. Verify camera readiness and durable IndexedDB.
+5. Capture one accepted photo with every enabled Frame and inspect physical
+   composition.
+6. Create two genuine network-class upload failures on two distinct items.
+7. Reload Safari and confirm a different boot ID recovers both exact items.
+8. Reconnect and confirm exact oldest-first drain with no duplicates.
+9. Observe one exact key in the public Photo Feed and fetch its public bytes.
+10. Designate and delete one exact canary; verify adjacent photos remain.
+11. Explicitly retain or individually delete every other test photo.
+12. Confirm the Outbox and evidence outbox are empty.
+13. Complete projector, power, charging, and backup-network manual checks.
+14. Change config once and verify the old rehearsal becomes stale rather than
+    mutating its evidence.
+
+State explicitly that a browser simulator cannot prove real camera,
+IndexedDB/Safari suspension, genuine venue-network failure, installed wake
+behavior, projector crop/brightness/motion, charging/power, backup network, or
+VoiceOver.
+
+- [ ] **Step 5: Update deployment and rollback guidance**
+
+Add:
+
+- Release 4 uses only explicit `deploy:staging` then `deploy:production`.
+- Inspect exact staging records to confirm presets/rehearsals/evidence exist
+  only in staging `STATE`.
+- Rehearsal photo bytes remain normal exact public photos in staging `PHOTOS`.
+- Never use the health canary prefix for rehearsal.
+- Never add a cleanup-all command.
+- Rollback changes Worker code only; it does not delete presets, sessions,
+  evidence, photos, indexes, or receipts.
+- An abandoned/stale session is resolved through visible exact keys, one at a
+  time.
+
+- [ ] **Step 6: Run the complete Release 4 gate**
+
+```bash
+bun install --frozen-lockfile
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+bun run test:browser -- tests/rehearsal-operations.spec.ts
+```
+
+Expected: every command passes. Do not claim the release operationally ready
+until the staging real-iPad and projector checklist also passes.
+
+- [ ] **Step 7: Self-review safety and compatibility**
+
+Verify:
+
+- No preset or rehearsal object was written to `PHOTOS`.
+- No credential/hash/revision head entered a preset.
+- No rehearsal route accepts a prefix, filename fragment, or cross-Event key.
+- Completion/abandonment performs zero automatic photo deletion.
+- Existing upload, Photo Feed, exact-photo, moderation, health, and export
+  contracts remain backward compatible.
+- Unsupported future stored versions fail explicitly.
+- Existing Outbox rows and Photo Outbox IndexedDB remain readable.
+- CI retains application typecheck, test typecheck, unit tests, Frame
+  validation, production build, and established browser coverage.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add tests/rehearsal-operations.spec.ts \
+  .github/workflows/verify.yml \
+  docs/runbooks/pre-event-readiness.md \
+  docs/runbooks/deployment.md
+git commit -m "test: verify repeatable event operations"
+```
+
+## Manual Acceptance Boundary
+
+Release 4 automation proves protocol, storage, reducer, accessibility markup,
+and mocked browser behavior. It does not replace the staging rehearsal on a
+real iPad and projector. Production promotion remains blocked until an
+operator verifies real camera permissions/composition, durable Safari reload,
+two actual network failures, ordered recovery, installed/wake behavior,
+VoiceOver, projector output, charging/power, backup network, exact canary
+deletion, explicit disposition of every other test photo, and empty Outboxes.
diff --git a/docs/superpowers/plans/2026-07-24-release-5-post-event-package.md b/docs/superpowers/plans/2026-07-24-release-5-post-event-package.md
new file mode 100644
index 0000000..cf41927
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-24-release-5-post-event-package.md
@@ -0,0 +1,1003 @@
+# Release 5 Post-Event Package Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Turn the current Event photos into a private, streamed post-event package with an escaped manifest, timezone-aware analytics, and an offline printable contact sheet while preserving the existing photo-only export exactly.
+
+**Architecture:** `EventStore` remains the only module that knows public photo and private receipt keys. The enriched export first builds an allowlisted inventory from current `PHOTOS` joined to each exact optional receipt in `STATE`, validates ZIP32 and generated-entry limits, and then streams one photo body at a time. It appends CSV, JSON, and HTML generated only from photos actually emitted, so a photo deleted during export cannot remain in the package metadata. The legacy route mode never reads `STATE` or Event config and retains its root-level photo archive.
+
+**Tech Stack:** Bun, TypeScript, Next.js 15 App Router, React 19, Cloudflare Workers/R2, STORE ZIP streaming, `Intl.DateTimeFormat`, typed message catalogs, Playwright WebKit.
+
+## Global Constraints
+
+- Start only after Release 0B private version-1 photo receipts, Release 2 localized Frame labels, Release 3 exact derived cleanup, and Release 4 Event presets/rehearsal pass their complete gates.
+- Use Bun commands only.
+- `EventStore` remains the only owner of `PHOTOS` and `STATE` keys.
+- `PHOTOS` remains authoritative for whether a photo exists.
+- `GET /api/export?event=<canonical-event>` remains an Admin-only photo-only compatibility mode with root-level photo entries and no `STATE` or Event config dependency.
+- `GET /api/export?event=<canonical-event>&format=package&contactSheet=1` is the only enriched mode and contains `photos/`, `manifest.csv`, `summary.json`, and `contact-sheet.html`.
+- Reject incomplete or unsupported `format`/`contactSheet` combinations before any store read.
+- A Booth Key never authorizes export. The Admin Key remains required.
+- Missing private receipts produce `unknown` metadata and do not omit the public photo.
+- Corrupt, mismatched, or unsupported future receipt versions fail the enriched export explicitly before response streaming. They never fall back to stale or guessed private metadata.
+- The package may derive a capture timestamp from the 13-digit photo filename and then the public upload time, but it reports that source explicitly.
+- Raw receipts, config revision IDs, indexes, revision records, Booth records, rehearsals, health state, credentials, and storage key prefixes never appear in package entries.
+- The enriched stream reads at most one photo body at a time and never buffers all JPEG bytes.
+- A photo missing when its body is fetched is skipped. Final generated entries are rebuilt from only photos that were actually emitted.
+- Generated entries and the ZIP central directory remain bounded. No ZIP64 archive is emitted.
+- The contact sheet uses relative package photo paths, inline CSS, no JavaScript, and no external request.
+- CSV cells and HTML are escaped, including spreadsheet-formula prefixes.
+- Every Event HTTP parameter uses `canonicalEvent()` and rejects aliases.
+- Existing and future unsupported stored versions fail explicitly.
+- Never bulk-delete or empty `PHOTOS`, `STATE`, or backup storage.
+- Never deploy the unnamed Wrangler environment to an Event domain.
+
+---
+
+## File Structure
+
+- Create `app/photo-metadata.ts` — strict version-1 private receipt schema and parser.
+- Create `app/photo-metadata.test.ts` — receipt version, exact-key, timestamp, optional-field, and privacy tests.
+- Modify `app/event-store.ts` — allowlisted export inventory iteration and exact receipt reads.
+- Modify `app/event-store.test.ts` — multi-page inventory, missing/corrupt receipt, deletion, and Event-isolation tests.
+- Create `app/export-package.ts` — safe archive names, row projection, CSV, summary, timezone buckets, and HTML.
+- Create `app/export-package.test.ts` — escaping, collision, metadata-gap, timezone, analytics, and contact-sheet tests.
+- Modify `app/zip.ts` — non-copying STORE entry header and exact ZIP-size estimator.
+- Modify `app/zip.test.ts` — split header/data structure, offsets, and limit arithmetic.
+- Create `app/export-stream.ts` — legacy and enriched ZIP stream builders plus hard limits.
+- Create `app/export-stream.test.ts` — ZIP layout, one-photo-at-a-time, deletion race, and generated-entry limits.
+- Create `app/api/export/handlers.ts` — dependency-injected Admin-only export HTTP boundary.
+- Create `app/api/export/handlers.test.ts` — auth, query, status, compatibility, privacy, and headers.
+- Modify `app/api/export/route.ts` — thin Cloudflare binding adapter.
+- Create `app/[event]/admin/export-client.ts` — pure endpoint, filename, and download-mode construction.
+- Create `app/[event]/admin/export-client.test.ts` — exact query/header/name and secret-placement tests.
+- Create `app/[event]/admin/export-panel.tsx` — accessible package and photo-only download controls.
+- Create `app/[event]/admin/export-panel.test.tsx` — mode, busy, errors, and semantic markup tests.
+- Modify `app/[event]/admin/page.tsx` — replace the single count-dependent export button.
+- Modify `app/[event]/admin/admin.module.css` — package panel, busy, warning, and focus styling.
+- Modify `app/i18n/catalog.ts` — complete localized export copy.
+- Modify `app/i18n/catalog.test.ts` — exact export-key and placeholder parity.
+- Create `tests/post-event-package.spec.ts` — Admin download and accessibility journey.
+- Modify `docs/runbooks/pre-event-readiness.md` — legacy/package ZIP and offline contact-sheet checks.
+- Modify `docs/runbooks/deployment.md` — Release 5 staging export gate and size-failure guidance.
+
+### Task 1: Parse private receipts and expose an allowlisted export inventory
+
+**Files:**
+- Create: `app/photo-metadata.ts`
+- Create: `app/photo-metadata.test.ts`
+- Modify: `app/event-store.ts`
+- Modify: `app/event-store.test.ts`
+
+**Interfaces:**
+- Consumes: Release 0B `photoReceiptKey()`, stable capture sources, and the current version-1 receipt bytes.
+- Produces: one strict parser shared by receipt writes, moderation, deletion cleanup, and export.
+- Produces: an Event-isolated export iterator that reveals no raw private record.
+
+- [ ] **Step 1: Write failing strict receipt parser tests**
+
+Define:
+
+```ts
+import type { CaptureSource } from "./upload-contract";
+
+export type PhotoReceiptV1 = {
+  version: 1;
+  key: string;
+  uploadedAt: string;
+  capturedAt: number;
+  source?: CaptureSource;
+  frameKey?: string;
+  configRevisionId?: string;
+};
+
+export class InvalidPhotoReceiptError extends Error {
+  constructor(
+    readonly expectedKey: string,
+    readonly reason:
+      | "invalid_shape"
+      | "unsupported_version"
+      | "key_mismatch"
+      | "invalid_timestamp"
+      | "invalid_metadata"
+  );
+}
+
+export function parsePhotoReceipt(
+  value: unknown,
+  expectedKey: string
+): PhotoReceiptV1;
+```
+
+Test a valid complete receipt and a valid receipt with only required fields.
+Reject:
+
+- `null`, arrays, missing fields, extra fields, and invalid JSON projections.
+- Versions other than `1`.
+- A key different from `expectedKey`, including another Event.
+- Non-RFC3339 `uploadedAt`.
+- Non-integer or non-13-digit `capturedAt`.
+- A source outside `"framed" | "camera-fallback"`.
+- Blank, unsafe, or longer-than-128-character Frame/revision tokens.
+- Credentials, hashes, headers, arbitrary errors, URLs, or nested objects.
+
+The returned object must construct each property explicitly rather than spread
+the stored value.
+
+- [ ] **Step 2: Write failing Event Store export-inventory tests**
+
+Add:
+
+```ts
+export type ExportPhotoSource = {
+  key: string;
+  size: number;
+  uploadedAt: string;
+  receipt: Pick<
+    PhotoReceiptV1,
+    "capturedAt" | "source" | "frameKey"
+  > | null;
+};
+
+EventStore.iterateExportPhotoSources(
+  event: string
+): AsyncGenerator<ExportPhotoSource>;
+```
+
+Test:
+
+- More than one `PHOTOS` list page is visited.
+- Only image objects under the exact canonical Event prefix are yielded.
+- Non-image public objects and cross-Event images are excluded.
+- Each photo reads only `photoReceiptKey(event, photo.key)`.
+- Missing exact receipt returns `receipt: null`.
+- A valid receipt exposes only capture time, source, and Frame key.
+- `configRevisionId`, receipt upload time, credential-like fields, private
+  key names, and unknown stored fields never enter the projection.
+- Corrupt, future, or wrong-key receipts throw `InvalidPhotoReceiptError`.
+- A receipt without a current public photo is never yielded.
+- An exact photo deleted before its inventory page is read is excluded.
+- A thrown private-store read fails the enriched iterator instead of
+  fabricating metadata.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test app/photo-metadata.test.ts app/event-store.test.ts
+```
+
+Expected: FAIL because the receipt parser and export iterator do not exist.
+
+- [ ] **Step 4: Move the version-1 private shape behind the strict parser**
+
+Use `PhotoReceiptV1` for new receipt/index serialization without changing the
+existing stored JSON fields or key layout. The existing upload, moderation,
+rebuild, and exact-deletion behavior must remain byte-compatible.
+
+`parsePhotoReceipt()` must:
+
+```ts
+const RECEIPT_KEYS = new Set([
+  "version",
+  "key",
+  "uploadedAt",
+  "capturedAt",
+  "source",
+  "frameKey",
+  "configRevisionId",
+]);
+```
+
+Validate `Object.keys(value)` against this set, validate the exact expected
+photo key, and return a freshly constructed object. Do not export a function
+that accepts an Event prefix, filename fragment, or optional expected key.
+
+- [ ] **Step 5: Implement page-safe exact receipt joining**
+
+`iterateExportPhotoSources()` must use `iteratePhotoObjects(event)` for public
+source truth. For each yielded object:
+
+1. Read only its exact receipt key from `STATE`.
+2. Treat a missing object as `null`.
+3. Parse an existing object strictly.
+4. Project only the allowlisted fields.
+5. Yield the public object size and ISO upload time.
+
+Do not list `STATE`, read the moderation index, or infer a receipt from an
+index record.
+
+- [ ] **Step 6: Run focused and full checks**
+
+```bash
+bun test app/photo-metadata.test.ts app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/photo-metadata.ts app/photo-metadata.test.ts \
+  app/event-store.ts app/event-store.test.ts
+git commit -m "feat: expose private export photo sources"
+```
+
+### Task 2: Build escaped manifest, timezone analytics, and offline contact sheet
+
+**Files:**
+- Create: `app/export-package.ts`
+- Create: `app/export-package.test.ts`
+
+**Interfaces:**
+- Consumes: Task 1 `ExportPhotoSource` and the Frame catalog's safe default label.
+- Produces: deterministic package photo rows and three bounded UTF-8 generated entries.
+- Does not read storage, environment variables, credentials, or the network.
+
+- [ ] **Step 1: Write failing archive-name and row-projection tests**
+
+Define:
+
+```ts
+export type TimestampSource = "receipt" | "filename" | "upload";
+
+export type PackagePhotoRow = {
+  key: string;
+  filename: string;
+  archivePath: string;
+  sizeBytes: number;
+  uploadedAt: string;
+  capturedAt: string;
+  capturedAtEpochMs: number;
+  timestampSource: TimestampSource;
+  frameKey: string | "unknown";
+  frameLabel: string | "unknown";
+  captureSource: "framed" | "camera-fallback" | "unknown";
+  hasReceipt: boolean;
+};
+
+export function preparePackageRows(
+  sources: readonly ExportPhotoSource[],
+  frameLabelFor: (frameKey: string) => string | undefined
+): PackagePhotoRow[];
+```
+
+Test:
+
+- A normal stable key becomes `photos/{source-filename}.jpg`.
+- Unsafe/non-ASCII filename characters become `_`.
+- Path separators, `.`/`..`, NUL, controls, and empty basenames never become
+  archive traversal.
+- Colliding sanitized basenames receive deterministic `-2`, `-3` suffixes
+  before the extension.
+- The complete original key remains available only as the manifest key.
+- Receipt capture time wins with `timestampSource: "receipt"`.
+- Missing receipt uses a valid leading 13-digit filename timestamp with
+  `timestampSource: "filename"`.
+- A key without a valid timestamp falls back to public upload time with
+  `timestampSource: "upload"`.
+- Missing source/Frame fields become the literal `"unknown"`.
+- Unknown or removed Frame keys keep the key but use label `"unknown"`.
+
+- [ ] **Step 2: Write failing CSV and HTML escaping tests**
+
+Define:
+
+```ts
+export function escapeCsvCell(value: string | number): string;
+export function escapeHtml(value: string): string;
+export function buildManifestCsv(
+  rows: readonly PackagePhotoRow[]
+): string;
+```
+
+The exact manifest header is:
+
+```text
+key,filename,size_bytes,uploaded_at,captured_at,timestamp_source,frame_key,frame_label,capture_source
+```
+
+Test commas, quotes, CR/LF, tabs, Unicode, HTML metacharacters, and cells whose
+first non-space character is `=`, `+`, `-`, or `@`. Formula-like cells must be
+prefixed with a single apostrophe before RFC4180 quoting. Embedded quotes are
+doubled. Output uses UTF-8 text and `\r\n` rows.
+
+Define:
+
+```ts
+export function buildContactSheetHtml(input: {
+  event: string;
+  summary: ExportSummaryV1;
+  rows: readonly PackagePhotoRow[];
+}): string;
+```
+
+Test that the result:
+
+- Starts with `<!doctype html>` and declares UTF-8.
+- Contains inline screen/print CSS and no `<script>`, `<link>`, `<base>`,
+  `@import`, inline event handler, `http:`, `https:`, or protocol-relative URL.
+- References only each row's escaped relative `photos/...` path.
+- Uses escaped Event, Frame label, filename, and caption text.
+- Uses `<time datetime="<UTC ISO>">`.
+- Is valid and useful for an empty Event.
+
+- [ ] **Step 3: Write failing timezone summary tests**
+
+Define:
+
+```ts
+export type ExportSummaryV1 = {
+  version: 1;
+  event: string;
+  generatedAt: string;
+  timeZone: string;
+  timeZoneSource: "configured" | "utc-fallback";
+  photoCount: number;
+  totalBytes: number;
+  metadataCoverage: {
+    receipts: { known: number; unknown: number };
+    frames: { known: number; unknown: number };
+    sources: { known: number; unknown: number };
+  };
+  timestampSources: {
+    receipt: number;
+    filename: number;
+    upload: number;
+  };
+  firstCaptureAt: string | null;
+  lastCaptureAt: string | null;
+  frameUsage: Array<{
+    frameKey: string;
+    frameLabel: string;
+    count: number;
+  }>;
+  hourly: Array<{ period: string; count: number }>;
+  busiestPeriods: Array<{ period: string; count: number }>;
+};
+
+export function buildExportSummary(input: {
+  event: string;
+  generatedAt: Date;
+  configuredTimeZone?: string;
+  rows: readonly PackagePhotoRow[];
+}): ExportSummaryV1;
+
+export function encodePackageArtifacts(input: {
+  event: string;
+  generatedAt: Date;
+  configuredTimeZone?: string;
+  rows: readonly PackagePhotoRow[];
+}): {
+  manifest: Uint8Array;
+  summary: Uint8Array;
+  contactSheet: Uint8Array;
+};
+```
+
+Test:
+
+- Empty summary uses zero counts, empty arrays, and `null` first/last times.
+- `totalBytes` sums emitted bytes.
+- Metadata coverage and timestamp-source counts add exactly to `photoCount`.
+- Frame usage sorts by count descending, then Frame key ascending.
+- First/last capture use capture timestamps rather than upload order.
+- A valid configured IANA zone is retained.
+- Missing and invalid configured zones use `UTC` and
+  `timeZoneSource: "utc-fallback"`.
+- Hour buckets include date, hour, and UTC offset so daylight-saving repeated
+  wall-clock hours remain distinct.
+- Hourly rows sort chronologically.
+- Busiest periods are the top three non-empty hours sorted by count descending
+  and then period ascending.
+- `summary.json` is pretty-printed with a final newline and contains no
+  undefined/raw receipt fields.
+
+- [ ] **Step 4: Run focused tests and verify failures**
+
+```bash
+bun test app/export-package.test.ts
+```
+
+Expected: FAIL because the package projection and encoders do not exist.
+
+- [ ] **Step 5: Implement deterministic safe row projection**
+
+Use one `Set<string>` of emitted filenames to resolve collisions. Keep archive
+paths ASCII so the existing ZIP flags remain valid. Capture timestamp
+precedence is:
+
+```text
+valid exact receipt → valid 13-digit filename prefix → public upload time
+```
+
+Convert timestamps to UTC ISO strings. Do not infer source or Frame metadata
+from the filename, config revision, index, or current Event configuration.
+
+- [ ] **Step 6: Implement summary grouping and generated entries**
+
+Use `Intl.DateTimeFormat("en-CA-u-nu-latn", ...)` with the validated Event
+timezone, numeric year/month/day/hour, `hourCycle: "h23"`, and
+`timeZoneName: "longOffset"`. Normalize UTC to `GMT+00:00`.
+
+Render:
+
+```text
+manifest.csv
+summary.json
+contact-sheet.html
+```
+
+The HTML uses a responsive screen grid and a deterministic print grid with
+page-break avoidance. Captions show filename, Frame label, and localized
+hour-period label without including the complete storage key.
+
+- [ ] **Step 7: Run focused and full checks**
+
+```bash
+bun test app/export-package.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add app/export-package.ts app/export-package.test.ts
+git commit -m "feat: build bounded event package artifacts"
+```
+
+### Task 3: Stream legacy and enriched ZIPs through a strict Admin boundary
+
+**Files:**
+- Modify: `app/zip.ts`
+- Modify: `app/zip.test.ts`
+- Create: `app/export-stream.ts`
+- Create: `app/export-stream.test.ts`
+- Create: `app/api/export/handlers.ts`
+- Create: `app/api/export/handlers.test.ts`
+- Modify: `app/api/export/route.ts`
+
+**Interfaces:**
+- Consumes: Task 1 inventory, Task 2 encoders, current ZIP central-directory primitives, `adminOk()`, and `canonicalEvent()`.
+- Produces: a thin dependency-injected export handler and one-photo-at-a-time ZIP streams.
+- Preserves: the existing legacy URL, authorization, content type, filename, and root photo layout.
+
+- [ ] **Step 1: Write failing non-copying ZIP primitive tests**
+
+Add:
+
+```ts
+export function storedEntryHeader(
+  name: Uint8Array,
+  data: Uint8Array
+): {
+  header: Uint8Array;
+  crc: number;
+  size: number;
+};
+
+export function estimateStoreZipBytes(
+  entries: readonly { nameBytes: number; dataBytes: number }[]
+): number;
+```
+
+Test:
+
+- `storedEntryHeader()` returns only the 30-byte local header plus name, not a
+  second copy of data.
+- Header CRC and size describe the separately enqueued data.
+- Existing `localPart()` remains byte-compatible by concatenating the new
+  header and data.
+- `estimateStoreZipBytes()` exactly includes every local header, filename,
+  data body, central record, central filename, and the 22-byte EOCD.
+- Unicode byte lengths use encoded bytes, not JavaScript string length.
+- The existing two-entry structural ZIP test still passes.
+
+- [ ] **Step 2: Write failing stream and deletion-race tests**
+
+Define:
+
+```ts
+export const MAX_ZIP_ENTRIES = 0xffff;
+export const MAX_ZIP_BYTES = 3_900_000_000;
+export const MAX_GENERATED_ENTRY_BYTES = 8 * 1024 * 1024;
+export const MAX_GENERATED_TOTAL_BYTES = 16 * 1024 * 1024;
+
+export class ExportTooLargeError extends Error {
+  constructor(
+    readonly reason:
+      | "entry_count"
+      | "zip_bytes"
+      | "generated_entry"
+      | "generated_total"
+  );
+}
+
+export type ExportStreamDeps = {
+  store: EventStore;
+  frameLabelFor: (frameKey: string) => string | undefined;
+  now: () => Date;
+};
+
+export async function preparePhotoOnlyExport(
+  event: string,
+  deps: ExportStreamDeps
+): Promise<ReadableStream<Uint8Array>>;
+
+export async function preparePackageExport(
+  event: string,
+  configuredTimeZone: string | undefined,
+  deps: ExportStreamDeps
+): Promise<ReadableStream<Uint8Array>>;
+```
+
+Use a small test-only STORE ZIP reader and test:
+
+- Photo-only entries remain root `{basename}` entries with no generated files.
+- Photo-only export never calls `STATE` or `readConfig()`.
+- Package entries are `photos/...`, `manifest.csv`, `summary.json`, and
+  `contact-sheet.html`.
+- Each public body finishes reading before the next body begins.
+- Header and data are enqueued separately.
+- A photo returning `null` from `getPhoto()` after preflight is absent from
+  photos, manifest, summary counts, analytics, and contact sheet.
+- A photo deleted after its body is returned remains consistently present.
+- New photos arriving after the preflight inventory are left for the next
+  export rather than partially joining the snapshot.
+- Generated entries are last, followed by one correct central directory.
+- A missing receipt exports `unknown` metadata.
+- No private key prefix or raw receipt-only field occurs anywhere in the ZIP.
+- Empty legacy and enriched archives are structurally valid.
+
+- [ ] **Step 3: Write failing size-limit tests**
+
+Preflight must reject before returning a stream when:
+
+- Photo-only entries exceed `65_535`.
+- Package photos plus three generated entries exceed `65_535`.
+- Estimated ZIP bytes exceed `3_900_000_000`.
+- Any generated entry exceeds `8 MiB`.
+- Generated entries together exceed `16 MiB`.
+
+Boundary-equal values pass. Use metadata-sized fakes; do not allocate multi-GB
+buffers.
+
+The enriched builder encodes a full-inventory candidate before returning the
+stream to prove generated limits. During streaming it tracks only successfully
+emitted rows and regenerates final artifacts from that subset. Removing rows
+cannot increase the preflight candidate beyond the established limit.
+
+- [ ] **Step 4: Write failing HTTP compatibility and privacy tests**
+
+Define:
+
+```ts
+export type ExportHandlerDeps = ExportStreamDeps & {
+  adminKey?: string;
+};
+
+export async function handleExport(
+  req: NextRequest,
+  deps: ExportHandlerDeps
+): Promise<NextResponse>;
+```
+
+Accepted query shapes:
+
+```text
+GET /api/export?event=launch
+GET /api/export?event=launch&format=package&contactSheet=1
+```
+
+Test:
+
+- Missing Admin secret returns `503` before any store read.
+- Wrong key and a valid Event Booth Key return `401` before any store read.
+- Canonical aliases and invalid Event values return `400`.
+- `format=package` without `contactSheet=1`, `contactSheet=1` without package,
+  duplicate values, and unknown format values return `400`.
+- Legacy success returns `application/zip` and
+  `attachment; filename="launch-photos.zip"`.
+- Enriched success returns `application/zip` and
+  `attachment; filename="launch-package.zip"`.
+- Both responses set `Cache-Control: private, no-store` and
+  `X-Content-Type-Options: nosniff`.
+- `ExportTooLargeError` maps to a generic `413`.
+- `InvalidPhotoReceiptError` maps to a generic `422` without key/receipt data.
+- Private metadata-store unavailability maps to a generic retryable `503`.
+- No error response includes a credential, receipt key, index key, or raw
+  private exception string.
+
+- [ ] **Step 5: Run focused tests and verify failures**
+
+```bash
+bun test app/zip.test.ts app/export-stream.test.ts \
+  app/api/export/handlers.test.ts
+```
+
+Expected: FAIL because the split ZIP primitive, streams, and handler do not exist.
+
+- [ ] **Step 6: Implement exact preflight and one-photo streaming**
+
+Preflight inventory keeps only small descriptors and package rows, never photo
+bytes. Include exact local-header and central-directory overhead in the
+projected ZIP size.
+
+The stream pull sequence is:
+
+```text
+get exact photo → skip if missing → enqueue header → enqueue photo bytes
+→ record emitted row → next photo
+→ encode generated files from emitted rows → enqueue generated entries
+→ enqueue central directory → enqueue EOCD → close
+```
+
+Keep `centralPart()` records bounded in memory. Never `Promise.all()` photo
+bodies and never concatenate all output.
+
+- [ ] **Step 7: Implement the dependency-injected handler and thin route**
+
+`handleExport()` authenticates first, validates query/Event input, calls only
+the selected stream builder, and constructs the response. `route.ts` only
+obtains Cloudflare bindings, creates `EventStore`, provides the Frame-label
+lookup and clock, then delegates.
+
+Package mode reads the current Event config only for `timeZone`. It constructs
+no other config fields into the package. Missing/invalid timezone uses the
+Task 2 UTC fallback.
+
+- [ ] **Step 8: Run focused and full checks**
+
+```bash
+bun test app/zip.test.ts app/export-stream.test.ts \
+  app/api/export/handlers.test.ts app/event-store.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add app/zip.ts app/zip.test.ts \
+  app/export-stream.ts app/export-stream.test.ts \
+  app/api/export/handlers.ts app/api/export/handlers.test.ts \
+  app/api/export/route.ts
+git commit -m "feat: stream enriched event exports"
+```
+
+### Task 4: Add the localized Admin post-event export panel
+
+**Files:**
+- Create: `app/[event]/admin/export-client.ts`
+- Create: `app/[event]/admin/export-client.test.ts`
+- Create: `app/[event]/admin/export-panel.tsx`
+- Create: `app/[event]/admin/export-panel.test.tsx`
+- Modify: `app/[event]/admin/page.tsx`
+- Modify: `app/[event]/admin/admin.module.css`
+- Modify: `app/i18n/catalog.ts`
+- Modify: `app/i18n/catalog.test.ts`
+
+**Interfaces:**
+- Consumes: Task 3 exact legacy/enriched HTTP contracts and the existing Admin authentication invalidation callback.
+- Produces: one accessible export panel with a streamed desktop path and bounded browser fallback.
+- Preserves: the existing File System Access API optimization.
+
+- [ ] **Step 1: Write failing pure export-request tests**
+
+Define:
+
+```ts
+export type AdminExportMode = "package" | "photos";
+
+export type AdminExportRequest = {
+  url: string;
+  suggestedName: string;
+  headers: { "x-booth-key": string };
+};
+
+export function adminExportRequest(input: {
+  event: string;
+  adminKey: string;
+  mode: AdminExportMode;
+}): AdminExportRequest;
+```
+
+Test:
+
+```ts
+expect(adminExportRequest({
+  event: "launch",
+  adminKey: "secret",
+  mode: "package",
+})).toEqual({
+  url: "/api/export?event=launch&format=package&contactSheet=1",
+  suggestedName: "launch-package.zip",
+  headers: { "x-booth-key": "secret" },
+});
+```
+
+Photo mode uses `/api/export?event=launch` and `launch-photos.zip`. The secret
+must appear only in the header object, never URL or filename.
+
+- [ ] **Step 2: Write failing panel markup and state tests**
+
+Define:
+
+```ts
+export type ExportPanelProps = {
+  event: string;
+  adminKey: string;
+  locale: SupportedLocale;
+  onUnauthorized: () => void;
+  onNotice: (message: string) => void;
+  onError: (message: string) => void;
+};
+
+export function ExportPanel(props: ExportPanelProps): JSX.Element;
+```
+
+Test:
+
+- A heading and description explain manifest, analytics, and printable sheet.
+- The primary action is “Download event package”.
+- The secondary action is “Download photos only”.
+- No loaded moderation/page count is described as the Event total.
+- One active mode disables both actions and exposes a polite busy status.
+- `401` invokes `onUnauthorized`.
+- `413` reports the single-ZIP size limit and recommends photos-only or
+  operator-assisted splitting rather than destructive deletion.
+- `422` reports invalid stored metadata and recommends photos-only plus
+  operator investigation.
+- `503` reports temporary export unavailability and preserves retry.
+- Generic failures do not render raw server exception text.
+- The Admin Key never occurs in markup, error copy, an anchor URL, or local
+  storage.
+- Keyboard semantics, visible focus, high contrast, and large text remain usable.
+
+- [ ] **Step 3: Run focused tests and verify failures**
+
+```bash
+bun test 'app/[event]/admin/export-client.test.ts' \
+  'app/[event]/admin/export-panel.test.tsx' \
+  app/i18n/catalog.test.ts
+```
+
+Expected: FAIL because the client helper, panel, and messages do not exist.
+
+- [ ] **Step 4: Implement direct-to-disk download with a fallback**
+
+For each click:
+
+1. Build the pure request.
+2. Call `showSaveFilePicker()` during the click's user activation when
+   available.
+3. Fetch with the Admin header.
+4. Pipe `response.body` to the chosen writable without building a giant Blob.
+5. Otherwise use the existing Blob/object-URL download fallback.
+6. Revoke fallback object URLs.
+7. Treat picker `AbortError` as cancellation, not failure.
+
+Show localized copy that large archives are best downloaded from a desktop
+browser with direct-to-disk support. Do not add a service worker or third-party
+stream-saver dependency.
+
+- [ ] **Step 5: Integrate the panel and complete catalogs**
+
+Replace the old `Export ${photos.length} photos (.zip)` action. Keep config,
+Booth operations, moderation, presets, rehearsals, health, and navigation
+usable when export fails.
+
+Add every new export key to `en`, `zh-SG`, and `ar`, with exact key and
+placeholder parity. Follow current Admin direction handling.
+
+- [ ] **Step 6: Run focused and full checks**
+
+```bash
+bun test 'app/[event]/admin/export-client.test.ts' \
+  'app/[event]/admin/export-panel.test.tsx' \
+  app/i18n/catalog.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add 'app/[event]/admin/export-client.ts' \
+  'app/[event]/admin/export-client.test.ts' \
+  'app/[event]/admin/export-panel.tsx' \
+  'app/[event]/admin/export-panel.test.tsx' \
+  'app/[event]/admin/page.tsx' \
+  'app/[event]/admin/admin.module.css' \
+  app/i18n/catalog.ts app/i18n/catalog.test.ts
+git commit -m "feat: add admin post-event package export"
+```
+
+### Task 5: Verify the complete Release 5 story and document operations
+
+**Files:**
+- Create: `tests/post-event-package.spec.ts`
+- Modify: `docs/runbooks/pre-event-readiness.md`
+- Modify: `docs/runbooks/deployment.md`
+
+**Interfaces:**
+- Consumes: Tasks 1–4 and the existing WebKit/browser accessibility harness.
+- Produces: release-level compatibility, privacy, download, offline, print, and staging gates.
+
+- [ ] **Step 1: Add a failing WebKit Admin download journey**
+
+Use a canonical throwaway Event and route interception. Verify:
+
+- Admin unlock remains keyboard-operable.
+- Package click sends the exact enriched query and Admin header.
+- Photos-only click sends the legacy query.
+- Neither URL nor suggested filename contains the Admin Key.
+- The correct package/photo filename is offered.
+- Busy status is announced and both actions are disabled during one download.
+- `401`, `413`, `422`, and `503` render their localized actionable states.
+- Retrying after a retryable failure works.
+- Automated accessibility checks report no serious/critical violations.
+
+- [ ] **Step 2: Add deterministic archive contract fixtures**
+
+Exercise a fixture containing:
+
+- A stable framed photo with complete receipt.
+- A camera-fallback photo.
+- A legacy photo with no receipt.
+- An unknown historical Frame.
+- A malicious formula/HTML-like key or Frame label at the pure serialization
+  boundary.
+- A photo that disappears between inventory and body fetch.
+- Capture times spanning local midnight and a daylight-saving offset change.
+
+Assert the ZIP entry list, manifest cells, summary counts, timezone buckets,
+contact-sheet relative sources, and absence of every private operational field.
+
+- [ ] **Step 3: Run the browser test and verify the initial failure**
+
+```bash
+bun run test:browser -- tests/post-event-package.spec.ts
+```
+
+Expected: FAIL until the complete Admin/export integration is wired into the
+browser harness.
+
+- [ ] **Step 4: Update the pre-event readiness runbook**
+
+Add exact checks:
+
+1. Export legacy photo-only ZIP and verify root photo entries.
+2. Export the enriched package and verify its four sections.
+3. Run `unzip -t <event>-package.zip`.
+4. Open extracted `contact-sheet.html` with networking disabled.
+5. Confirm all package images load through relative paths.
+6. Open print preview and inspect grid/page breaks.
+7. Import `manifest.csv` into a spreadsheet and confirm formula-looking cells
+   remain text.
+8. Compare configured timezone, first/last capture, hourly, busiest-period,
+   Frame, byte, and metadata-coverage totals against the fixture.
+9. Confirm a deleted exact photo appears nowhere.
+10. Search the extracted package for receipt/index prefixes, revision IDs,
+    Booth records, rehearsal evidence, health state, and credential material.
+
+- [ ] **Step 5: Update the deployment runbook**
+
+Add a Release 5 staging gate using a throwaway Event distinct from production.
+Upload stable and legacy canaries, export both modes, delete only the
+designated canary by complete key, and confirm staging/production isolation.
+
+Document:
+
+- `413` means the single STORE ZIP/Worker safety limit, not permission to
+  delete stored photos.
+- `422` means private metadata needs investigation; photo-only export remains
+  available.
+- `503` is retryable private/export infrastructure unavailability.
+- Do not test large-event limits by filling production storage.
+- Rollback changes Worker code only and never deletes `PHOTOS` or `STATE`.
+
+- [ ] **Step 6: Run the complete automated gate**
+
+```bash
+bun test app/photo-metadata.test.ts app/export-package.test.ts \
+  app/zip.test.ts app/export-stream.test.ts \
+  app/api/export/handlers.test.ts app/event-store.test.ts \
+  'app/[event]/admin/export-client.test.ts' \
+  'app/[event]/admin/export-panel.test.tsx' \
+  app/i18n/catalog.test.ts
+bun run typecheck
+bun run typecheck:tests
+bun test
+bun run validate:frames
+bun run build
+bun run test:browser -- tests/post-event-package.spec.ts
+```
+
+Expected: every command exits 0.
+
+- [ ] **Step 7: Perform required staging/manual validation**
+
+Automated tests cannot certify:
+
+- Real Cloudflare R2 paging/read behavior during a long streaming response.
+- The browser's native file picker and direct-to-disk writable implementation.
+- Spreadsheet import behavior across Excel, Numbers, and Google Sheets.
+- Offline extracted-file behavior under desktop browser security policies.
+- Print layout across the operator's actual paper size/printer.
+
+On staging:
+
+1. Create a throwaway canonical Event with a configured timezone.
+2. Add stable framed, stable fallback, and legacy/missing-receipt photos.
+3. Export the legacy ZIP and confirm its existing root layout.
+4. Export the enriched package and run `unzip -t`.
+5. Delete one designated canary by its complete Event-owned key, export again,
+   and confirm it is absent from all four package sections.
+6. Open the contact sheet offline and in print preview.
+7. Import the manifest and inspect formula-like fixture cells as text.
+8. Check summary totals and timezone buckets manually.
+9. Confirm `STATE` remains private and no operational record is packaged.
+10. Confirm staging export never returns production photos.
+
+No real camera or iPad is required for Release 5 correctness. Desktop native
+download, offline HTML, spreadsheet import, printing, and production-like R2
+streaming require manual checks.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add tests/post-event-package.spec.ts \
+  docs/runbooks/pre-event-readiness.md docs/runbooks/deployment.md
+git commit -m "test: verify post-event package release"
+```
+
+## Release 5 Completion Gate
+
+Release 5 is complete only when:
+
+- Every task review is clean.
+- The full automated gate passes.
+- Legacy `/api/export?event=` remains Admin-only, root-photo-only, and
+  independent of `STATE` and Event config.
+- Enriched mode accepts only
+  `format=package&contactSheet=1` and contains the exact expected four sections.
+- Booth credentials cannot authorize either export.
+- Current `PHOTOS` is the source of truth; missing receipts become `unknown`
+  and deleted photos are excluded.
+- Corrupt/future/wrong-key receipts fail before streaming without exposing
+  private data.
+- Every manifest cell and HTML interpolation is safely escaped, including
+  spreadsheet-formula prefixes.
+- Summary counts, bytes, metadata coverage, Frame usage, first/last capture,
+  hourly buckets, and busiest periods are deterministic in the configured
+  timezone with explicit UTC fallback.
+- Contact HTML is printable, offline, relative-path-only, inline-CSS-only,
+  JavaScript-free, and external-request-free.
+- Streaming holds at most one photo body and never concatenates all JPEGs.
+- The 65,535-entry, 3.9 GB ZIP, 8 MiB per-generated-entry, and 16 MiB
+  generated-total limits reject before response streaming.
+- A mid-export deletion cannot leave a photo in manifest, summary, or contact
+  sheet after its image entry is skipped.
+- No receipt, index, revision, Booth, rehearsal, health, credential, or
+  private storage key appears in any response or archive entry.
+- Admin offers localized package and photo-only downloads, preserves
+  direct-to-disk streaming when supported, and provides actionable bounded
+  fallback/error states.
+- Staging verifies legacy compatibility, enriched structure, one exact
+  deletion, offline/print/spreadsheet output, timezone analytics, private-state
+  isolation, and staging/production isolation.

From 94c627bb11d5b5095c1469d2f764bb2813d363f4 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 15:46:35 +0800
Subject: [PATCH 030/105] fix: make photo feed arrival ordered

---
 app/api/config/handlers.test.ts | 131 +++++++++
 app/api/config/handlers.ts      |  49 +++-
 app/api/photos/handlers.test.ts |  40 +++
 app/api/photos/handlers.ts      |  28 ++
 app/api/photos/route.ts         |  14 +-
 app/event-store.test.ts         | 216 ++++++++++++--
 app/event-store.ts              | 479 ++++++++++++++++++++++++++++++--
 7 files changed, 905 insertions(+), 52 deletions(-)
 create mode 100644 app/api/photos/handlers.test.ts
 create mode 100644 app/api/photos/handlers.ts

diff --git a/app/api/config/handlers.test.ts b/app/api/config/handlers.test.ts
index d5d538b..8e75223 100644
--- a/app/api/config/handlers.test.ts
+++ b/app/api/config/handlers.test.ts
@@ -155,6 +155,137 @@ describe("config handlers", () => {
     expect(JSON.stringify(json)).not.toContain(BOOTH_KEY);
   });
 
+  test("a normal Frames save preserves the allowlisted experience and existing Booth credential through its revision", async () => {
+    const d = deps();
+    await d.deps.store.writeConfig("launch", {
+      frames: ["birthday"],
+      boothKeyHash: "existing-private-hash",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+
+    const response = await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody()),
+      d.deps
+    );
+    const config = await d.deps.store.readConfig("launch");
+    const history = await d.deps.store.readConfigHistory("launch");
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toMatchObject({
+      frames: ["square"],
+      hasBoothKey: true,
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+    expect(config).toMatchObject({
+      frames: ["square"],
+      boothKeyHash: "existing-private-hash",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+    expect(history.revisions[0]).toMatchObject({
+      id: FIRST_ID,
+      config: {
+        frames: ["square"],
+        locales: ["en", "zh-SG"],
+        defaultLocale: "en",
+        timeZone: "Asia/Singapore",
+        capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+        gallery: { title: "Launch Night", accentColor: "#ff3366" },
+      },
+    });
+    expect(JSON.stringify(history.revisions)).not.toContain("existing-private-hash");
+  });
+
+  test("a stale normal Frames save conflicts without discarding preserved experience fields", async () => {
+    const d = deps();
+    await d.deps.store.writeConfig("launch", {
+      frames: ["birthday"],
+      boothKeyHash: "existing-private-hash",
+      locales: ["en"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true },
+      gallery: { title: "Launch Night" },
+    });
+    expect((await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody()),
+      d.deps
+    )).status).toBe(200);
+
+    const conflict = await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody({
+        frames: ["birthday"],
+        mutationId: SECOND_ID,
+        baseRevisionId: null,
+      })),
+      d.deps
+    );
+
+    expect(conflict.status).toBe(409);
+    expect(await d.deps.store.readConfig("launch")).toMatchObject({
+      frames: ["square"],
+      boothKeyHash: "existing-private-hash",
+      locales: ["en"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true },
+      gallery: { title: "Launch Night" },
+    });
+  });
+
+  test("a Booth-key rotation preserves the allowlisted experience without putting its hash in history", async () => {
+    const d = deps({ hashBoothKey: async () => "new-private-hash" });
+    await d.deps.store.writeConfig("launch", {
+      frames: ["birthday"],
+      boothKeyHash: "old-private-hash",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5 },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+
+    const response = await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody({ boothKey: BOOTH_KEY })),
+      d.deps
+    );
+    const config = await d.deps.store.readConfig("launch");
+    const history = await d.deps.store.readConfigHistory("launch");
+
+    expect(response.status).toBe(200);
+    expect(config).toMatchObject({
+      frames: ["square"],
+      boothKeyHash: "new-private-hash",
+      locales: ["en", "zh-SG"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5 },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+    expect(history.revisions[0]).toMatchObject({
+      config: {
+        frames: ["square"],
+        locales: ["en", "zh-SG"],
+        defaultLocale: "en",
+        timeZone: "Asia/Singapore",
+        capture: { reviewEnabled: true, autoAcceptSeconds: 5 },
+        gallery: { title: "Launch Night", accentColor: "#ff3366" },
+      },
+    });
+    expect(JSON.stringify(history.revisions)).not.toContain("new-private-hash");
+  });
+
   test("save stores an opaque fingerprint privately with the independently hashed key", async () => {
     const d = deps({ hashBoothKey: async () => "salted-pbkdf2-hash" });
     await putConfig(
diff --git a/app/api/config/handlers.ts b/app/api/config/handlers.ts
index 3d53340..3ee095e 100644
--- a/app/api/config/handlers.ts
+++ b/app/api/config/handlers.ts
@@ -11,6 +11,7 @@ import {
   isRevisionId,
   projectPublicConfig,
   type ConfigRevision,
+  type EventConfig,
 } from "@/app/event-config";
 import { TEMPLATES } from "@/app/templates";
 import { adminOk } from "@/app/upload-auth";
@@ -147,6 +148,48 @@ function parseRestoreBody(value: unknown): RestoreBody | null {
   };
 }
 
+/**
+ * Frames and a possible Booth-key rotation are the deliberately small Admin
+ * save surface. Preserve every other known experience field explicitly rather
+ * than spreading an HTTP body into a stored config.
+ */
+function configForSave(
+  current: EventConfig | null,
+  body: SaveBody,
+  boothKeyHash: string | undefined
+): EventConfig {
+  return {
+    frames: [...body.frames],
+    ...(current?.locales ? { locales: [...current.locales] } : {}),
+    ...(current?.defaultLocale ? { defaultLocale: current.defaultLocale } : {}),
+    ...(current?.timeZone ? { timeZone: current.timeZone } : {}),
+    ...(current?.capture
+      ? {
+        capture: {
+          ...(current.capture.reviewEnabled !== undefined
+            ? { reviewEnabled: current.capture.reviewEnabled }
+            : {}),
+          ...(current.capture.autoAcceptSeconds !== undefined
+            ? { autoAcceptSeconds: current.capture.autoAcceptSeconds }
+            : {}),
+          ...(current.capture.countdownAudioDefault !== undefined
+            ? { countdownAudioDefault: current.capture.countdownAudioDefault }
+            : {}),
+        },
+      }
+      : {}),
+    ...(current?.gallery
+      ? {
+        gallery: {
+          ...(current.gallery.title !== undefined ? { title: current.gallery.title } : {}),
+          ...(current.gallery.accentColor !== undefined ? { accentColor: current.gallery.accentColor } : {}),
+        },
+      }
+      : {}),
+    ...(boothKeyHash === undefined ? {} : { boothKeyHash }),
+  };
+}
+
 function safeRevision(revision: ConfigRevision): ConfigRevision {
   const { hasBoothKey: _hasBoothKey, ...config } = projectPublicConfig(revision.config);
   return {
@@ -197,11 +240,9 @@ export async function putConfig(
     : await boothKeyMutationFingerprint(body.boothKey, deps.adminKey!);
 
   try {
+    const current = await deps.store.readConfig(event);
     const result = await deps.store.saveConfigRevision(event, {
-      config: {
-        frames: body.frames,
-        ...(boothKeyHash === undefined ? {} : { boothKeyHash }),
-      },
+      config: configForSave(current, body, boothKeyHash),
       mutationId: body.mutationId,
       baseRevisionId: body.baseRevisionId,
       ...(fingerprint === undefined
diff --git a/app/api/photos/handlers.test.ts b/app/api/photos/handlers.test.ts
new file mode 100644
index 0000000..a50cfcf
--- /dev/null
+++ b/app/api/photos/handlers.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import { EventStore, InMemoryObjectStore } from "@/app/event-store";
+import { getPhotos } from "./handlers";
+
+function request(query = "event=launch") {
+  return new NextRequest(`https://app.test/api/photos?${query}`);
+}
+
+describe("photos handler", () => {
+  test("keeps the after/cursor response contract while reading the private incremental feed", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const initial = await getPhotos(request(), { store });
+    const initialBody = await initial.json() as { cursor: string };
+    const uploaded = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000201", capturedAt: 1753315200000 },
+    });
+
+    const response = await getPhotos(request(`event=launch&cursor=${encodeURIComponent(initialBody.cursor)}`), { store });
+    const body = await response.json() as { photos: Array<{ key: string }>; cursor: string };
+
+    expect(response.status).toBe(200);
+    expect(body.photos.map((photo) => photo.key)).toEqual([uploaded.key]);
+    expect(typeof body.cursor).toBe("string");
+  });
+
+  test("rejects malformed and cross-Event private cursors", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const initial = await getPhotos(request(), { store });
+    const cursor = (await initial.json() as { cursor: string }).cursor;
+
+    const malformed = await getPhotos(request("event=launch&after=bad-cursor"), { store });
+    const crossEvent = await getPhotos(request(`event=other&after=${encodeURIComponent(cursor)}`), { store });
+
+    expect(malformed.status).toBe(400);
+    expect(await malformed.json()).toEqual({ error: "photo feed cursor is invalid for this Event" });
+    expect(crossEvent.status).toBe(400);
+    expect(await crossEvent.json()).toEqual({ error: "photo feed cursor is invalid for this Event" });
+  });
+});
diff --git a/app/api/photos/handlers.ts b/app/api/photos/handlers.ts
new file mode 100644
index 0000000..946d669
--- /dev/null
+++ b/app/api/photos/handlers.ts
@@ -0,0 +1,28 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  EventStore,
+  InvalidEventSlugError,
+  InvalidPhotoCursorError,
+} from "@/app/event-store";
+
+export type PhotoHandlerDeps = { store: EventStore };
+
+export async function getPhotos(req: NextRequest, deps: PhotoHandlerDeps): Promise<NextResponse> {
+  let event: string;
+  try {
+    event = canonicalEvent(req.nextUrl.searchParams.get("event"));
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) return NextResponse.json({ error: error.message }, { status: 400 });
+    throw error;
+  }
+  const after = req.nextUrl.searchParams.get("after") ?? req.nextUrl.searchParams.get("cursor");
+  try {
+    return NextResponse.json(await deps.store.listPhotos(event, after));
+  } catch (error) {
+    if (error instanceof InvalidPhotoCursorError) {
+      return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+    throw error;
+  }
+}
diff --git a/app/api/photos/route.ts b/app/api/photos/route.ts
index 0d74d20..fedee8a 100644
--- a/app/api/photos/route.ts
+++ b/app/api/photos/route.ts
@@ -2,24 +2,14 @@ import { getCloudflareContext } from "@opennextjs/cloudflare";
 import { NextRequest, NextResponse } from "next/server";
 import { canonicalEvent, EventStore, InvalidEventSlugError } from "@/app/event-store";
 import { adminOk } from "@/app/upload-auth";
+import { getPhotos } from "./handlers";
 
 // no caching by Next — the gallery polls this for fresh photos
 export const dynamic = "force-dynamic";
 
 export async function GET(req: NextRequest) {
-  let event: string;
-  try {
-    event = canonicalEvent(req.nextUrl.searchParams.get("event"));
-  } catch (error) {
-    if (error instanceof InvalidEventSlugError) return NextResponse.json({ error: error.message }, { status: 400 });
-    throw error;
-  }
   const { env } = getCloudflareContext();
-  const after = req.nextUrl.searchParams.get("after") ?? req.nextUrl.searchParams.get("cursor");
-  const feed = await EventStore.fromEnv(env).listPhotos(event, after);
-  // `photos` remains the original full-response field. New clients retain
-  // `cursor` and pass it as `after` for a small startAfter delta.
-  return NextResponse.json(feed);
+  return getPhotos(req, { store: EventStore.fromEnv(env) });
 }
 
 export async function DELETE(req: NextRequest) {
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index dd11f67..bd69db6 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -6,14 +6,19 @@ import {
   ConfigRevisionNotFoundError,
   EventStore,
   InMemoryObjectStore,
+  InvalidPhotoCursorError,
   InvalidStoredConfigRevisionError,
   eventConfigKey,
   eventConfigMutationKey,
   eventConfigRevisionKey,
   legacyEventConfigKey,
   PhotoIndexWriteError,
+  photoFeedHeadKey,
   photoIndexKey,
   photoReceiptKey,
+  type ListOptions,
+  type ListResult,
+  type StoredObjectBody,
 } from "./event-store";
 
 class FailPrivatePhotoWriteStore extends InMemoryObjectStore {
@@ -39,6 +44,54 @@ class FailPrivatePhotoWriteStore extends InMemoryObjectStore {
   }
 }
 
+class GuardedPhotoListStore extends InMemoryObjectStore {
+  rejectPhotoLists = false;
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    if (this.rejectPhotoLists && options.prefix === "launch/") {
+      throw new Error("incremental feed must not list PHOTOS");
+    }
+    return super.list(options);
+  }
+}
+
+class WaterlinePhotoStore extends InMemoryObjectStore {
+  private hook: (() => Promise<void>) | null = null;
+
+  setFirstPhotoListHook(hook: () => Promise<void>): void {
+    this.hook = hook;
+  }
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    if (options.prefix === "launch/" && this.hook) {
+      const hook = this.hook;
+      this.hook = null;
+      await hook();
+    }
+    return super.list(options);
+  }
+}
+
+class MissingDuplicatePhotoMetadataStore extends InMemoryObjectStore {
+  hideExistingPhoto = false;
+
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    if (this.hideExistingPhoto && key.startsWith("launch/")) return null;
+    return super.get(key);
+  }
+}
+
+class MarkerOnlyRetryStateStore extends InMemoryObjectStore {
+  rejectFeedNodeReads = false;
+
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    if (this.rejectFeedNodeReads && key.includes("/photo-feed/v1/nodes/")) {
+      throw new Error("normal duplicate retry must use its O(1) commit marker");
+    }
+    return super.get(key);
+  }
+}
+
 class FailNextConfigHeadCasStore extends InMemoryObjectStore {
   private failNextConfigHeadCas = true;
 
@@ -1065,7 +1118,8 @@ describe("EventStore", () => {
 
   test("concurrent stable attempts produce one public image", async () => {
     const photos = new InMemoryObjectStore();
-    const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example");
     const upload = {
       captureId: "018f0000-0000-4000-8000-000000000002",
       capturedAt: 1753315200001,
@@ -1078,6 +1132,7 @@ describe("EventStore", () => {
 
     expect(results.filter((result) => result.duplicate)).toHaveLength(1);
     expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+    expect((await state.list({ prefix: "events/launch/photo-feed/v1/nodes/" })).objects).toHaveLength(1);
   });
 
   test("a stable retry repairs a missing index without another public photo", async () => {
@@ -1101,6 +1156,35 @@ describe("EventStore", () => {
     expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
   });
 
+  test("a stable upload does not acknowledge until its private arrival record is durable", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new FailPrivatePhotoWriteStore("events/launch/photo-feed/");
+    const store = new EventStore(photos, state, "https://photos.example");
+    const before = await store.listPhotos("launch");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000110", capturedAt: 1753315200005 };
+
+    await expect(store.putPhoto("launch", new Uint8Array([1]).buffer, { upload })).rejects.toBeInstanceOf(PhotoIndexWriteError);
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+
+    state.allowWrites();
+    const repaired = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload });
+    const delta = await store.listPhotos("launch", before.cursor);
+
+    expect(repaired).toMatchObject({ duplicate: true, indexStored: true });
+    expect(delta.photos.map((photo) => photo.key)).toEqual([repaired.key]);
+  });
+
+  test("a normal lost-ack retry uses its exact private commit marker without scanning feed history", async () => {
+    const state = new MarkerOnlyRetryStateStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000111", capturedAt: 1753315200006 };
+
+    await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    state.rejectFeedNodeReads = true;
+
+    await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).resolves.toMatchObject({ duplicate: true });
+  });
+
   test("receipt failure is observable but does not reject an acknowledged stable photo", async () => {
     const photos = new InMemoryObjectStore();
     const state = new FailPrivatePhotoWriteStore("events/launch/photo-metadata/");
@@ -1147,7 +1231,10 @@ describe("EventStore", () => {
 
     const index = await (await state.get(photoIndexKey("launch", launch.key, upload.capturedAt)))!.json<Record<string, unknown>>();
     const receipt = await (await state.get(photoReceiptKey("launch", launch.key)))!.json<Record<string, unknown>>();
-    for (const record of [index, receipt]) {
+    const feedRecords = await Promise.all((await state.list({ prefix: "events/launch/photo-feed/" })).objects.map(async (object) =>
+      (await state.get(object.key))!.json<Record<string, unknown>>()
+    ));
+    for (const record of [index, receipt, ...feedRecords]) {
       expect(record).not.toHaveProperty("boothKeyHash");
       expect(record).not.toHaveProperty("boothKey");
       expect(record).not.toHaveProperty("credential");
@@ -1155,26 +1242,123 @@ describe("EventStore", () => {
     }
   });
 
-  test("returns an initial snapshot and efficient start-after delta", async () => {
+  test("uses private server-arrival records so delayed and future-skewed captures both arrive after a cursor", async () => {
     const photos = new InMemoryObjectStore();
-    photos.set("launch/0000000001000-aaaa.jpg", "a", new Date("2026-01-01T00:00:01Z"));
-    photos.set("launch/0000000002000-bbbb.jpg", "b", new Date("2026-01-01T00:00:02Z"));
-    photos.set("launch/readme.txt", "not a photo");
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example");
+    const future = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000101", capturedAt: 9999999999999 },
+    });
+    const initial = await store.listPhotos("launch");
+
+    const delayed = await store.putPhoto("launch", new Uint8Array([2]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000102", capturedAt: 1000 },
+    });
+    const delta = await store.listPhotos("launch", initial.cursor);
+
+    expect(initial.photos.map((photo) => photo.key)).toEqual([future.key]);
+    expect(delta.photos.map((photo) => photo.key)).toEqual([delayed.key]);
+    expect(state.has(photoFeedHeadKey("launch"))).toBe(true);
+  });
+
+  test("records concurrent equal-time stable uploads once each in arrival order", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const before = await store.listPhotos("launch");
+    const uploads = await Promise.all([
+      store.putPhoto("launch", new Uint8Array([1]).buffer, {
+        upload: { captureId: "018f0000-0000-4000-8000-000000000103", capturedAt: 1753315200000 },
+      }),
+      store.putPhoto("launch", new Uint8Array([2]).buffer, {
+        upload: { captureId: "018f0000-0000-4000-8000-000000000104", capturedAt: 1753315200000 },
+      }),
+    ]);
+
+    const delta = await store.listPhotos("launch", before.cursor);
+    expect(delta.photos.map((photo) => photo.key)).toEqual(expect.arrayContaining(uploads.map((upload) => upload.key)));
+    expect(new Set(delta.photos.map((photo) => photo.key)).size).toBe(2);
+  });
+
+  test("takes a feed-head waterline before the initial public scan", async () => {
+    const photos = new WaterlinePhotoStore();
     const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+    let duringSnapshot: Awaited<ReturnType<EventStore["putPhoto"]>> | null = null;
+    photos.setFirstPhotoListHook(async () => {
+      duringSnapshot = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+        upload: { captureId: "018f0000-0000-4000-8000-000000000105", capturedAt: 1000 },
+      });
+    });
 
     const initial = await store.listPhotos("launch");
-    expect(initial.photos.map((photo) => photo.url)).toEqual([
-      "https://photos.example/launch/0000000002000-bbbb.jpg",
-      "https://photos.example/launch/0000000001000-aaaa.jpg",
-    ]);
-    expect(initial.cursor).toBe("launch/0000000002000-bbbb.jpg");
+    const delta = await store.listPhotos("launch", initial.cursor);
+
+    expect(initial.photos).toEqual([]);
+    expect(delta.photos.map((photo) => photo.key)).toEqual([duringSnapshot!.key]);
+  });
+
+  test("pages a delta through private feed records and exact public gets without relisting PHOTOS", async () => {
+    const photos = new GuardedPhotoListStore();
+    const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+    const initial = await store.listPhotos("launch");
+    const upload = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000106", capturedAt: 1000 },
+    });
+    photos.rejectPhotoLists = true;
 
-    const unchanged = await store.listPhotos("launch", initial.cursor);
-    expect(unchanged).toMatchObject({ photos: [], cursor: initial.cursor, unchanged: true });
-    photos.set("launch/0000000003000-cccc.jpg", "c");
     const delta = await store.listPhotos("launch", initial.cursor);
-    expect(delta.photos).toHaveLength(1);
-    expect(delta.cursor).toBe("launch/0000000003000-cccc.jpg");
+
+    expect(delta.photos.map((photo) => photo.key)).toEqual([upload.key]);
+  });
+
+  test("skips deleted feed records while advancing an opaque Event-bound cursor", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const initial = await store.listPhotos("launch");
+    const upload = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000107", capturedAt: 1000 },
+    });
+    await store.deletePhoto("launch", upload.key);
+
+    const skipped = await store.listPhotos("launch", initial.cursor);
+    const unchanged = await store.listPhotos("launch", skipped.cursor);
+
+    expect(skipped).toMatchObject({ photos: [], unchanged: true });
+    expect(skipped.cursor).not.toBe(initial.cursor);
+    expect(unchanged).toMatchObject({ photos: [], unchanged: true, cursor: skipped.cursor });
+    await expect(store.listPhotos("other", skipped.cursor)).rejects.toBeInstanceOf(InvalidPhotoCursorError);
+    await expect(store.listPhotos("launch", "not-an-opaque-cursor")).rejects.toBeInstanceOf(InvalidPhotoCursorError);
+  });
+
+  test("repairs a stable index and receipt with the original public upload time", async () => {
+    let now = new Date("2026-07-24T00:00:00.000Z");
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example", () => now);
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000108", capturedAt: 1753315200000 };
+    const first = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    const originalUploadedAt = (await photos.get(first.key))!.uploaded.toISOString();
+    await state.delete(photoIndexKey("launch", first.key, upload.capturedAt));
+    await state.delete(photoReceiptKey("launch", first.key));
+    now = new Date("2026-07-24T00:05:00.000Z");
+
+    const repaired = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload });
+    const index = await (await state.get(photoIndexKey("launch", first.key, upload.capturedAt)))!.json<{ uploadedAt: string }>();
+    const receipt = await (await state.get(photoReceiptKey("launch", first.key)))!.json<{ uploadedAt: string }>();
+
+    expect(repaired).toMatchObject({ duplicate: true, indexStored: true, receiptStored: true });
+    expect(index.uploadedAt).toBe(originalUploadedAt);
+    expect(receipt.uploadedAt).toBe(originalUploadedAt);
+  });
+
+  test("does not repair a duplicate index with a retry timestamp when the public object is unavailable", async () => {
+    const photos = new MissingDuplicatePhotoMetadataStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000109", capturedAt: 1753315200000 };
+    const first = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    await state.delete(photoIndexKey("launch", first.key, upload.capturedAt));
+    photos.hideExistingPhoto = true;
+
+    await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).rejects.toBeInstanceOf(PhotoIndexWriteError);
+    expect(state.has(photoIndexKey("launch", first.key, upload.capturedAt))).toBe(false);
   });
 
   test("iterates every export page", async () => {
diff --git a/app/event-store.ts b/app/event-store.ts
index 69378a2..57d745c 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -22,6 +22,8 @@ const HEALTH_STATE_KEY = "health/statuspage.json";
 const LEGACY_HEALTH_STATE_KEY = "_health/state.json";
 const PAGE_SIZE = 1000;
 const BOOTH_KEY_MUTATION_FINGERPRINT = /^[0-9a-f]{64}$/;
+const PHOTO_FEED_VERSION = 1 as const;
+const PHOTO_FEED_APPEND_ATTEMPTS = 16;
 
 type StoredEventConfig = EventConfig & { version: typeof EVENT_CONFIG_VERSION };
 type ConfigSaveInput = {
@@ -229,11 +231,14 @@ export const photoReceiptKey = (event: string, key: string) =>
   `events/${event}/photo-metadata/${key.slice(eventPhotoPrefix(event).length)}.json`;
 export const photoIndexKey = (event: string, key: string, sortTime: number) =>
   `events/${event}/photo-index/v1/${String(9_999_999_999_999 - sortTime).padStart(13, "0")}-${base64url(key)}.json`;
-
-function photoTimestamp(key: string): number {
-  const filename = key.slice(key.lastIndexOf("/") + 1);
-  return Number(filename.split("-")[0]) || 0;
-}
+export const photoFeedHeadKey = (event: string) => `events/${event}/photo-feed/v1/head.json`;
+const photoFeedEntryKey = (event: string, key: string) =>
+  `events/${event}/photo-feed/v1/entries/${base64url(key)}.json`;
+const photoFeedCommitKey = (event: string, key: string) =>
+  `events/${event}/photo-feed/v1/commits/${base64url(key)}.json`;
+const photoFeedNodePrefix = (event: string) => `events/${event}/photo-feed/v1/nodes/`;
+const photoFeedNodeKey = (event: string) =>
+  `${photoFeedNodePrefix(event)}${crypto.randomUUID()}.json`;
 
 function isPhotoKey(event: string, key: string): boolean {
   return key.startsWith(eventPhotoPrefix(event)) && /\.(?:jpe?g|png|gif|webp|hei[cf]|avif)$/i.test(key);
@@ -300,6 +305,18 @@ export class PhotoIndexWriteError extends Error {
   }
 }
 
+export class InvalidPhotoCursorError extends Error {
+  constructor() {
+    super("photo feed cursor is invalid for this Event");
+  }
+}
+
+class InvalidStoredPhotoFeedError extends Error {
+  constructor(readonly event: string) {
+    super(`photo feed state for ${event} is corrupt or uses an unsupported version`);
+  }
+}
+
 export class EventStore {
   // Consistency policy: no process-global response cache. Reads reach the
   // backing store, so config writes/uploads/deletions need no invalidation fanout.
@@ -497,17 +514,30 @@ export class EventStore {
   }
 
   async putPhoto(event: string, body: ArrayBuffer, options: PutPhotoOptions = {}): Promise<PutPhotoResult> {
-    // Capture server time once: the immutable records for this attempt then
-    // agree even when a retry completes a previously interrupted upload.
-    const uploadedAt = this.now();
+    // Capture server time once for a newly-created public object. A duplicate
+    // must read the public object's immutable uploaded timestamp instead of
+    // turning a delayed index repair into a false new arrival.
+    const attemptedAt = this.now();
     const upload = options.upload;
-    const key = upload ? stablePhotoKey(event, upload) : this.photoKey(event, uploadedAt.getTime());
+    const key = upload ? stablePhotoKey(event, upload) : this.photoKey(event, attemptedAt.getTime());
     const url = this.publicUrl(key);
     let duplicate = false;
+    let uploadedAt = attemptedAt;
 
     if (upload) {
       const created = await this.photos.compareAndSwap(key, null, body, jpegWriteOptions());
       duplicate = !created;
+      try {
+        const original = await this.photos.get(key);
+        // R2 is authoritative for immutable upload time after either a fresh
+        // conditional create or a lost-ack retry. Never invent retry-time
+        // metadata when the public object cannot be observed.
+        if (!original) throw new PhotoIndexWriteError({ key, url, duplicate }, { cause: new Error("stable photo missing") });
+        uploadedAt = original.uploaded;
+      } catch (cause) {
+        if (cause instanceof PhotoIndexWriteError) throw cause;
+        throw new PhotoIndexWriteError({ key, url, duplicate }, { cause });
+      }
     } else {
       // Legacy clients cannot retry the same public key. Keep their original
       // acknowledgment behavior even when private derived writes are down.
@@ -521,6 +551,7 @@ export class EventStore {
     if (upload) {
       try {
         await this.state.compareAndSwap(indexKey, null, JSON.stringify(metadata), jsonWriteOptions());
+        await this.ensurePhotoFeedRecord(event, key, metadata);
       } catch (cause) {
         throw new PhotoIndexWriteError(photo, { cause });
       }
@@ -529,29 +560,279 @@ export class EventStore {
     }
 
     const indexStored = await this.tryWritePhotoIndex(indexKey, metadata);
+    await this.tryWritePhotoFeedRecord(event, key, metadata);
     const receiptStored = await this.tryWritePhotoReceipt(event, key, metadata);
     return { ...photo, indexStored, receiptStored };
   }
 
   async listPhotos(event: string, after: string | null = null): Promise<PhotoFeed> {
-    const prefix = eventPhotoPrefix(event);
-    const startAfter = after && after.startsWith(prefix) ? after : undefined;
+    if (after === null) return this.initialPhotoFeed(event);
+    return this.incrementalPhotoFeed(event, parsePhotoFeedCursor(event, after));
+  }
+
+  /**
+   * The initial scan remains the compatibility path for photos created before
+   * the private arrival feed existed. Capture a feed waterline first, then
+   * omit any image committed after it so the immediate delta returns it once.
+   */
+  private async initialPhotoFeed(event: string): Promise<PhotoFeed> {
+    const waterline = await this.readPhotoFeedHead(event);
+    const objects = await this.listEventPhotoObjects(event);
+    const current = await this.readPhotoFeedHead(event);
+    const afterWaterline = new Set(
+      (await this.photoFeedNodesAfter(event, current.head.nodeKey, waterline.head.nodeKey))
+        .map((node) => node.entryKey)
+    );
+    const visible = objects
+      .filter((object) => !afterWaterline.has(photoFeedEntryKey(event, object.key)))
+      .sort(newestPublicObjectFirst);
+
+    return {
+      photos: visible.map((object) => this.toPhoto(object)),
+      cursor: encodePhotoFeedCursor(event, waterline.head.nodeKey),
+      unchanged: visible.length === 0,
+      truncated: false,
+    };
+  }
+
+  /** Deltas traverse only private arrival nodes and the exact public images. */
+  private async incrementalPhotoFeed(event: string, cursor: PhotoFeedCursor): Promise<PhotoFeed> {
+    const current = await this.readPhotoFeedHead(event);
+    const nodes = await this.photoFeedNodesAfter(event, current.head.nodeKey, cursor.nodeKey);
+    const photos: Photo[] = [];
+    const seen = new Set<string>();
+    for (const node of nodes) {
+      const entry = await this.readPhotoFeedEntry(event, node.entryKey);
+      if (seen.has(entry.key)) continue;
+      seen.add(entry.key);
+      const object = await this.photos.get(entry.key);
+      // Exact-key deletion or a stale record must never resurrect an image.
+      if (!object || !isPhotoKey(event, object.key)) continue;
+      photos.push(this.toPhoto(object));
+    }
+    return {
+      photos,
+      cursor: encodePhotoFeedCursor(event, current.head.nodeKey),
+      unchanged: photos.length === 0,
+      truncated: false,
+    };
+  }
+
+  private toPhoto(object: StoredObject): Photo {
+    return { key: object.key, url: this.publicUrl(object.key), uploadedAt: object.uploaded };
+  }
+
+  private async listEventPhotoObjects(event: string): Promise<StoredObject[]> {
     const objects: StoredObject[] = [];
     let cursor: string | undefined;
     do {
-      const page = await this.photos.list({ prefix, cursor, ...(!cursor && startAfter ? { startAfter } : {}), limit: PAGE_SIZE });
+      const page = await this.photos.list({ prefix: eventPhotoPrefix(event), cursor, limit: PAGE_SIZE });
       objects.push(...page.objects.filter((object) => isPhotoKey(event, object.key)));
       cursor = page.truncated ? page.cursor : undefined;
     } while (cursor);
+    return objects;
+  }
 
-    objects.sort((a, b) => photoTimestamp(b.key) - photoTimestamp(a.key) || b.key.localeCompare(a.key));
-    const newest = objects[0]?.key ?? after;
-    return {
-      photos: objects.map((object) => ({ key: object.key, url: this.publicUrl(object.key), uploadedAt: object.uploaded })),
-      cursor: newest ?? null,
-      unchanged: objects.length === 0,
-      truncated: false,
-    };
+  /**
+   * Creates one immutable entry per public key, then atomically appends an
+   * immutable linked node by CASing the Event head. The normal lost-ack path
+   * reads the per-photo commit marker in O(1); a chain walk happens only when
+   * recovering a successful head CAS whose marker write was interrupted.
+   */
+  private async ensurePhotoFeedRecord(
+    event: string,
+    key: string,
+    metadata: PrivatePhotoMetadata
+  ): Promise<void> {
+    const entryKey = photoFeedEntryKey(event, key);
+    const entry: PrivatePhotoFeedEntry = { version: PHOTO_FEED_VERSION, key, metadata };
+    const entryCreated = await this.state.compareAndSwap(
+      entryKey,
+      null,
+      JSON.stringify(entry),
+      jsonWriteOptions()
+    );
+    if (!entryCreated) {
+      const existing = await this.readPhotoFeedEntry(event, entryKey);
+      if (existing.key !== key || !samePrivatePhotoMetadata(existing.metadata, metadata)) {
+        throw new InvalidStoredPhotoFeedError(event);
+      }
+      const committed = await this.readPhotoFeedCommit(event, key);
+      if (committed) return;
+      // A prior request might have advanced the head and then lost its marker
+      // write. Recover that exact node before ever attempting a new append.
+      const head = await this.readPhotoFeedHead(event);
+      const recovered = await this.findPhotoFeedEntryNode(event, head.head.nodeKey, entryKey);
+      if (recovered) {
+        await this.writePhotoFeedCommit(event, key, recovered);
+        return;
+      }
+    }
+
+    for (let attempt = 0; attempt < PHOTO_FEED_APPEND_ATTEMPTS; attempt += 1) {
+      const committed = await this.readPhotoFeedCommit(event, key);
+      if (committed) return;
+      const head = await this.readPhotoFeedHead(event);
+      const nodeKey = photoFeedNodeKey(event);
+      const node: PrivatePhotoFeedNode = {
+        version: PHOTO_FEED_VERSION,
+        sequence: head.head.sequence + 1,
+        entryKey,
+        previousNodeKey: head.head.nodeKey,
+      };
+      const nodeCreated = await this.state.compareAndSwap(
+        nodeKey,
+        null,
+        JSON.stringify(node),
+        jsonWriteOptions()
+      );
+      if (!nodeCreated) continue;
+      const advanced = await this.state.compareAndSwap(
+        photoFeedHeadKey(event),
+        head.etag,
+        JSON.stringify({ version: PHOTO_FEED_VERSION, sequence: node.sequence, nodeKey }),
+        jsonWriteOptions()
+      );
+      if (advanced) {
+        await this.writePhotoFeedCommit(event, key, nodeKey);
+        return;
+      }
+
+      // Another duplicate request may have won the head CAS. Its normal path
+      // records a marker; if that write was interrupted, recover by chain.
+      const racedCommit = await this.readPhotoFeedCommit(event, key);
+      if (racedCommit) return;
+      const current = await this.readPhotoFeedHead(event);
+      const recovered = await this.findPhotoFeedEntryNode(event, current.head.nodeKey, entryKey);
+      if (recovered) {
+        await this.writePhotoFeedCommit(event, key, recovered);
+        return;
+      }
+    }
+    throw new Error("photo feed append contention exceeded retry budget");
+  }
+
+  private async tryWritePhotoFeedRecord(
+    event: string,
+    key: string,
+    metadata: PrivatePhotoMetadata
+  ): Promise<boolean> {
+    try {
+      await this.ensurePhotoFeedRecord(event, key, metadata);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async readPhotoFeedHead(event: string): Promise<{ head: PrivatePhotoFeedHead; etag: string | null }> {
+    const object = await this.state.get(photoFeedHeadKey(event));
+    if (!object) {
+      return { head: { version: PHOTO_FEED_VERSION, sequence: 0, nodeKey: null }, etag: null };
+    }
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const head = parsePhotoFeedHead(event, value);
+    if (!head) throw new InvalidStoredPhotoFeedError(event);
+    return { head, etag: object.etag };
+  }
+
+  private async readPhotoFeedEntry(event: string, entryKey: string): Promise<PrivatePhotoFeedEntry> {
+    if (!entryKey.startsWith(`events/${event}/photo-feed/v1/entries/`)) {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const object = await this.state.get(entryKey);
+    if (!object) throw new InvalidStoredPhotoFeedError(event);
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const entry = parsePhotoFeedEntry(event, value);
+    if (!entry) throw new InvalidStoredPhotoFeedError(event);
+    return entry;
+  }
+
+  private async readPhotoFeedNode(event: string, nodeKey: string): Promise<PrivatePhotoFeedNode> {
+    if (!nodeKey.startsWith(photoFeedNodePrefix(event))) throw new InvalidStoredPhotoFeedError(event);
+    const object = await this.state.get(nodeKey);
+    if (!object) throw new InvalidStoredPhotoFeedError(event);
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const node = parsePhotoFeedNode(event, value);
+    if (!node) throw new InvalidStoredPhotoFeedError(event);
+    return node;
+  }
+
+  private async readPhotoFeedCommit(event: string, key: string): Promise<string | null> {
+    const object = await this.state.get(photoFeedCommitKey(event, key));
+    if (!object) return null;
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const marker = parsePhotoFeedCommit(event, value);
+    if (!marker) throw new InvalidStoredPhotoFeedError(event);
+    return marker.nodeKey;
+  }
+
+  private async writePhotoFeedCommit(event: string, key: string, nodeKey: string): Promise<void> {
+    const created = await this.state.compareAndSwap(
+      photoFeedCommitKey(event, key),
+      null,
+      JSON.stringify({ version: PHOTO_FEED_VERSION, nodeKey }),
+      jsonWriteOptions()
+    );
+    if (created) return;
+    const existing = await this.readPhotoFeedCommit(event, key);
+    if (existing !== nodeKey) throw new InvalidStoredPhotoFeedError(event);
+  }
+
+  private async photoFeedNodesAfter(
+    event: string,
+    headNodeKey: string | null,
+    afterNodeKey: string | null
+  ): Promise<PrivatePhotoFeedNode[]> {
+    const nodes: PrivatePhotoFeedNode[] = [];
+    const visited = new Set<string>();
+    let nodeKey = headNodeKey;
+    while (nodeKey !== null && nodeKey !== afterNodeKey) {
+      if (visited.has(nodeKey)) throw new InvalidStoredPhotoFeedError(event);
+      visited.add(nodeKey);
+      const node = await this.readPhotoFeedNode(event, nodeKey);
+      nodes.push(node);
+      nodeKey = node.previousNodeKey;
+    }
+    if (afterNodeKey !== null && nodeKey !== afterNodeKey) throw new InvalidPhotoCursorError();
+    return nodes;
+  }
+
+  private async findPhotoFeedEntryNode(
+    event: string,
+    headNodeKey: string | null,
+    entryKey: string
+  ): Promise<string | null> {
+    const visited = new Set<string>();
+    let nodeKey = headNodeKey;
+    while (nodeKey !== null) {
+      if (visited.has(nodeKey)) throw new InvalidStoredPhotoFeedError(event);
+      visited.add(nodeKey);
+      const node = await this.readPhotoFeedNode(event, nodeKey);
+      if (node.entryKey === entryKey) return nodeKey;
+      nodeKey = node.previousNodeKey;
+    }
+    return null;
   }
 
   async *iteratePhotoObjects(event: string): AsyncGenerator<StoredObject> {
@@ -925,6 +1206,36 @@ function jpegWriteOptions(): R2PutOptions {
   return { httpMetadata: { contentType: "image/jpeg" } };
 }
 
+type PrivatePhotoFeedHead = {
+  version: typeof PHOTO_FEED_VERSION;
+  sequence: number;
+  nodeKey: string | null;
+};
+
+type PrivatePhotoFeedEntry = {
+  version: typeof PHOTO_FEED_VERSION;
+  key: string;
+  metadata: PrivatePhotoMetadata;
+};
+
+type PrivatePhotoFeedNode = {
+  version: typeof PHOTO_FEED_VERSION;
+  sequence: number;
+  entryKey: string;
+  previousNodeKey: string | null;
+};
+
+type PrivatePhotoFeedCommit = {
+  version: typeof PHOTO_FEED_VERSION;
+  nodeKey: string;
+};
+
+type PhotoFeedCursor = {
+  version: typeof PHOTO_FEED_VERSION;
+  event: string;
+  nodeKey: string | null;
+};
+
 type PrivatePhotoMetadata = {
   version: 1;
   key: string;
@@ -947,6 +1258,128 @@ function photoPrivateMetadata(key: string, uploadedAt: Date, upload?: StableUplo
   };
 }
 
+function parsePhotoFeedHead(event: string, value: unknown): PrivatePhotoFeedHead | null {
+  if (!isRecord(value)) return null;
+  if (
+    value.version !== PHOTO_FEED_VERSION
+    || typeof value.sequence !== "number"
+    || !Number.isSafeInteger(value.sequence)
+    || value.sequence < 0
+    || (value.nodeKey !== null && (typeof value.nodeKey !== "string" || !value.nodeKey.startsWith(photoFeedNodePrefix(event))))
+  ) {
+    return null;
+  }
+  return { version: PHOTO_FEED_VERSION, sequence: value.sequence, nodeKey: value.nodeKey as string | null };
+}
+
+function parsePhotoFeedEntry(event: string, value: unknown): PrivatePhotoFeedEntry | null {
+  if (!isRecord(value) || value.version !== PHOTO_FEED_VERSION || typeof value.key !== "string" || !isPhotoKey(event, value.key)) return null;
+  const metadata = parsePrivatePhotoMetadata(event, value.metadata);
+  if (!metadata || metadata.key !== value.key) return null;
+  return { version: PHOTO_FEED_VERSION, key: value.key, metadata };
+}
+
+function parsePhotoFeedNode(event: string, value: unknown): PrivatePhotoFeedNode | null {
+  if (!isRecord(value)) return null;
+  if (
+    value.version !== PHOTO_FEED_VERSION
+    || typeof value.sequence !== "number"
+    || !Number.isSafeInteger(value.sequence)
+    || value.sequence < 1
+    || typeof value.entryKey !== "string"
+    || !value.entryKey.startsWith(`events/${event}/photo-feed/v1/entries/`)
+    || (value.previousNodeKey !== null && (typeof value.previousNodeKey !== "string" || !value.previousNodeKey.startsWith(photoFeedNodePrefix(event))))
+  ) {
+    return null;
+  }
+  return {
+    version: PHOTO_FEED_VERSION,
+    sequence: value.sequence,
+    entryKey: value.entryKey,
+    previousNodeKey: value.previousNodeKey as string | null,
+  };
+}
+
+function parsePhotoFeedCommit(event: string, value: unknown): PrivatePhotoFeedCommit | null {
+  if (
+    !isRecord(value)
+    || value.version !== PHOTO_FEED_VERSION
+    || typeof value.nodeKey !== "string"
+    || !value.nodeKey.startsWith(photoFeedNodePrefix(event))
+  ) {
+    return null;
+  }
+  return { version: PHOTO_FEED_VERSION, nodeKey: value.nodeKey };
+}
+
+function parsePrivatePhotoMetadata(event: string, value: unknown): PrivatePhotoMetadata | null {
+  if (!isRecord(value)) return null;
+  if (
+    value.version !== 1
+    || typeof value.key !== "string"
+    || !isPhotoKey(event, value.key)
+    || typeof value.uploadedAt !== "string"
+    || Number.isNaN(Date.parse(value.uploadedAt))
+    || typeof value.capturedAt !== "number"
+    || !Number.isSafeInteger(value.capturedAt)
+    || (value.source !== undefined && value.source !== "framed" && value.source !== "camera-fallback")
+    || (value.frameKey !== undefined && !isBoundedToken(value.frameKey))
+    || (value.configRevisionId !== undefined && !isBoundedToken(value.configRevisionId))
+  ) {
+    return null;
+  }
+  return {
+    version: 1,
+    key: value.key,
+    uploadedAt: value.uploadedAt,
+    capturedAt: value.capturedAt,
+    ...(value.source ? { source: value.source } : {}),
+    ...(typeof value.frameKey === "string" ? { frameKey: value.frameKey } : {}),
+    ...(typeof value.configRevisionId === "string" ? { configRevisionId: value.configRevisionId } : {}),
+  };
+}
+
+function samePrivatePhotoMetadata(left: PrivatePhotoMetadata, right: PrivatePhotoMetadata): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function newestPublicObjectFirst(left: StoredObject, right: StoredObject): number {
+  return right.uploaded.getTime() - left.uploaded.getTime() || right.key.localeCompare(left.key);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isBoundedToken(value: unknown): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value);
+}
+
+function encodePhotoFeedCursor(event: string, nodeKey: string | null): string {
+  return `pf1.${base64url(JSON.stringify({ version: PHOTO_FEED_VERSION, event, nodeKey }))}`;
+}
+
+function parsePhotoFeedCursor(event: string, value: string): PhotoFeedCursor {
+  if (!value.startsWith("pf1.")) throw new InvalidPhotoCursorError();
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(base64urlDecode(value.slice(4)));
+  } catch {
+    throw new InvalidPhotoCursorError();
+  }
+  if (!isRecord(decoded) || decoded.version !== PHOTO_FEED_VERSION || decoded.event !== event) {
+    throw new InvalidPhotoCursorError();
+  }
+  if (decoded.nodeKey !== null && (typeof decoded.nodeKey !== "string" || !decoded.nodeKey.startsWith(photoFeedNodePrefix(event)))) {
+    throw new InvalidPhotoCursorError();
+  }
+  return {
+    version: PHOTO_FEED_VERSION,
+    event,
+    nodeKey: decoded.nodeKey as string | null,
+  };
+}
+
 function base64url(value: string): string {
   const bytes = new TextEncoder().encode(value);
   let binary = "";
@@ -954,6 +1387,12 @@ function base64url(value: string): string {
   return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
 }
 
+function base64urlDecode(value: string): string {
+  if (!/^[A-Za-z0-9_-]*$/.test(value)) throw new Error("invalid base64url");
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - value.length % 4) % 4);
+  return atob(padded);
+}
+
 function randomSuffix(): string {
   const bytes = crypto.getRandomValues(new Uint8Array(4));
   return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");

From fda9f435efee6888fba2754bc54748159114973e Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 16:06:05 +0800
Subject: [PATCH 031/105] fix: bound photo feed sequence cursors

---
 app/api/photos/handlers.test.ts |  51 +++++
 app/event-store.test.ts         | 192 ++++++++++++++++-
 app/event-store.ts              | 353 ++++++++++++++++++++++++--------
 3 files changed, 497 insertions(+), 99 deletions(-)

diff --git a/app/api/photos/handlers.test.ts b/app/api/photos/handlers.test.ts
index a50cfcf..9573569 100644
--- a/app/api/photos/handlers.test.ts
+++ b/app/api/photos/handlers.test.ts
@@ -37,4 +37,55 @@ describe("photos handler", () => {
     expect(crossEvent.status).toBe(400);
     expect(await crossEvent.json()).toEqual({ error: "photo feed cursor is invalid for this Event" });
   });
+
+  test("rebases an already-open Gallery's legacy raw photo-key cursor", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const uploaded = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000202", capturedAt: 1753315200001 },
+    });
+
+    const response = await getPhotos(
+      request(`event=launch&after=${encodeURIComponent(uploaded.key)}`),
+      { store }
+    );
+    const body = await response.json() as { photos: Array<{ key: string }>; cursor: string };
+
+    expect(response.status).toBe(200);
+    expect(body.photos.map((photo) => photo.key)).toEqual([uploaded.key]);
+    expect(body.cursor).toStartWith("pf1.");
+
+    const crossEvent = await getPhotos(
+      request(`event=other&after=${encodeURIComponent(uploaded.key)}`),
+      { store }
+    );
+    const traversal = await getPhotos(
+      request(`event=launch&after=${encodeURIComponent("launch/../other/photo.jpg")}`),
+      { store }
+    );
+    const fragment = await getPhotos(
+      request(`event=launch&after=${encodeURIComponent(uploaded.key.split("/")[1]!)}`),
+      { store }
+    );
+    expect(crossEvent.status).toBe(400);
+    expect(traversal.status).toBe(400);
+    expect(fragment.status).toBe(400);
+  });
+
+  test("rebases a legacy raw cursor after its exact photo was moderated", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const uploaded = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000203", capturedAt: 1753315200002 },
+    });
+    await store.deletePhoto("launch", uploaded.key);
+
+    const response = await getPhotos(
+      request(`event=launch&after=${encodeURIComponent(uploaded.key)}`),
+      { store }
+    );
+    const body = await response.json() as { photos: Array<{ key: string }>; cursor: string };
+
+    expect(response.status).toBe(200);
+    expect(body.photos).toEqual([]);
+    expect(body.cursor).toStartWith("pf1.");
+  });
 });
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index bd69db6..c16ea19 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -13,7 +13,9 @@ import {
   eventConfigRevisionKey,
   legacyEventConfigKey,
   PhotoIndexWriteError,
+  photoFeedCommittedKey,
   photoFeedHeadKey,
+  photoFeedMarkerKey,
   photoIndexKey,
   photoReceiptKey,
   type ListOptions,
@@ -81,15 +83,23 @@ class MissingDuplicatePhotoMetadataStore extends InMemoryObjectStore {
   }
 }
 
-class MarkerOnlyRetryStateStore extends InMemoryObjectStore {
-  rejectFeedNodeReads = false;
+class InstrumentedStateStore extends InMemoryObjectStore {
+  reads = 0;
 
   override async get(key: string): Promise<StoredObjectBody | null> {
-    if (this.rejectFeedNodeReads && key.includes("/photo-feed/v1/nodes/")) {
-      throw new Error("normal duplicate retry must use its O(1) commit marker");
-    }
+    this.reads += 1;
     return super.get(key);
   }
+
+  resetReads(): void {
+    this.reads = 0;
+  }
+}
+
+function decodePhotoFeedCursor(cursor: string): Record<string, unknown> {
+  const encoded = cursor.slice("pf1.".length).replaceAll("-", "+").replaceAll("_", "/");
+  const padded = encoded + "=".repeat((4 - encoded.length % 4) % 4);
+  return JSON.parse(atob(padded)) as Record<string, unknown>;
 }
 
 class FailNextConfigHeadCasStore extends InMemoryObjectStore {
@@ -1174,15 +1184,24 @@ describe("EventStore", () => {
     expect(delta.photos.map((photo) => photo.key)).toEqual([repaired.key]);
   });
 
-  test("a normal lost-ack retry uses its exact private commit marker without scanning feed history", async () => {
-    const state = new MarkerOnlyRetryStateStore();
+  test("a normal lost-ack retry validates its exact commit proof in bounded O(1) reads", async () => {
+    const state = new InstrumentedStateStore();
     const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
     const upload = { captureId: "018f0000-0000-4000-8000-000000000111", capturedAt: 1753315200006 };
 
     await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
-    state.rejectFeedNodeReads = true;
+    for (let index = 0; index < 50; index += 1) {
+      await store.putPhoto("launch", new Uint8Array([index]).buffer, {
+        upload: {
+          captureId: `018f0000-0000-4000-8000-${String(index + 200).padStart(12, "0")}`,
+          capturedAt: 1753315200100 + index,
+        },
+      });
+    }
+    state.resetReads();
 
     await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).resolves.toMatchObject({ duplicate: true });
+    expect(state.reads).toBeLessThanOrEqual(10);
   });
 
   test("receipt failure is observable but does not reject an acknowledged stable photo", async () => {
@@ -1291,10 +1310,165 @@ describe("EventStore", () => {
     const initial = await store.listPhotos("launch");
     const delta = await store.listPhotos("launch", initial.cursor);
 
-    expect(initial.photos).toEqual([]);
+    // A concurrent post-waterline photo may be in the public snapshot. The
+    // next sequence delta deliberately repeats it so no arrival can be missed;
+    // Gallery clients already deduplicate exact keys.
+    expect(initial.photos.map((photo) => photo.key)).toEqual([duringSnapshot!.key]);
     expect(delta.photos.map((photo) => photo.key)).toEqual([duringSnapshot!.key]);
   });
 
+  test("opaque cursors expose only an Event-bound bounded sequence", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000112", capturedAt: 1753315200007 },
+    });
+
+    const feed = await store.listPhotos("launch");
+    const decoded = decodePhotoFeedCursor(feed.cursor!);
+
+    expect(decoded).toEqual({ version: 1, event: "launch", sequence: 1 });
+    expect(JSON.stringify(decoded)).not.toContain("events/");
+    expect(decoded).not.toHaveProperty("nodeKey");
+  });
+
+  test("bounds fabricated-head delta work and stops before a missing committed sequence", async () => {
+    const state = new InstrumentedStateStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const before = await store.listPhotos("launch");
+    state.set(photoFeedHeadKey("launch"), JSON.stringify({
+      version: 1,
+      sequence: 1_000_000,
+      nodeKey: "events/launch/photo-feed/v1/nodes/fabricated.json",
+    }));
+    state.resetReads();
+
+    const delta = await store.listPhotos("launch", before.cursor);
+
+    expect(delta).toMatchObject({ photos: [], cursor: before.cursor, unchanged: true, truncated: true });
+    expect(state.reads).toBeLessThanOrEqual(3);
+  });
+
+  test("pages more than one feed page without gaps or duplicate keys", async () => {
+    const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+    const before = await store.listPhotos("launch");
+    const uploaded: string[] = [];
+    for (let index = 1; index <= 1002; index += 1) {
+      const photo = await store.putPhoto("launch", new Uint8Array([index % 255]).buffer, {
+        upload: {
+          captureId: `018f0000-0000-4000-8000-${String(index).padStart(12, "0")}`,
+          capturedAt: 1753315300000 + index,
+        },
+      });
+      uploaded.push(photo.key);
+    }
+
+    const first = await store.listPhotos("launch", before.cursor);
+    const second = await store.listPhotos("launch", first.cursor);
+    const keys = [...first.photos, ...second.photos].map((photo) => photo.key);
+
+    expect(first).toMatchObject({ truncated: true, unchanged: false });
+    expect(first.photos).toHaveLength(1000);
+    expect(decodePhotoFeedCursor(first.cursor!).sequence).toBe(1000);
+    expect(second).toMatchObject({ truncated: false, unchanged: false });
+    expect(second.photos).toHaveLength(2);
+    expect(decodePhotoFeedCursor(second.cursor!).sequence).toBe(1002);
+    expect(new Set(keys).size).toBe(1002);
+    expect(keys).toEqual([...uploaded.slice(0, 1000).reverse(), ...uploaded.slice(1000).reverse()]);
+  });
+
+  test("does not advance past a missing committed sequence and retry repairs it", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new FailPrivatePhotoWriteStore("events/launch/photo-feed/v1/committed/");
+    const store = new EventStore(photos, state, "https://photos.example");
+    const before = await store.listPhotos("launch");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000113", capturedAt: 1753315200008 };
+
+    await expect(store.putPhoto("launch", new Uint8Array([1]).buffer, { upload })).rejects.toBeInstanceOf(PhotoIndexWriteError);
+    const blocked = await store.listPhotos("launch", before.cursor);
+    expect(blocked).toMatchObject({ photos: [], cursor: before.cursor, truncated: true });
+
+    state.allowWrites();
+    const repaired = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload });
+    const delta = await store.listPhotos("launch", before.cursor);
+
+    expect(delta.photos.map((photo) => photo.key)).toEqual([repaired.key]);
+    expect(decodePhotoFeedCursor(delta.cursor!).sequence).toBe(1);
+    expect(delta.truncated).toBe(false);
+  });
+
+  test("keeps a valid prior cursor usable while its successor commit is repaired", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const before = await store.listPhotos("launch");
+    await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000117", capturedAt: 1753315200012 },
+    });
+    const throughFirst = await store.listPhotos("launch", before.cursor);
+    const secondUpload = {
+      captureId: "018f0000-0000-4000-8000-000000000118",
+      capturedAt: 1753315200013,
+    };
+    const second = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload: secondUpload });
+    await state.delete(photoFeedCommittedKey("launch", 2));
+
+    const blocked = await store.listPhotos("launch", throughFirst.cursor);
+    expect(blocked).toMatchObject({
+      photos: [],
+      cursor: throughFirst.cursor,
+      unchanged: true,
+      truncated: true,
+    });
+
+    await store.putPhoto("launch", new Uint8Array([3]).buffer, { upload: secondUpload });
+    const repaired = await store.listPhotos("launch", throughFirst.cursor);
+    expect(repaired.photos.map((photo) => photo.key)).toEqual([second.key]);
+    expect(decodePhotoFeedCursor(repaired.cursor!).sequence).toBe(2);
+  });
+
+  test("fails closed on a corrupt per-photo sequence marker", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000114", capturedAt: 1753315200009 };
+    const photo = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    state.set(photoFeedMarkerKey("launch", photo.key), JSON.stringify({ version: 1, sequence: "1" }));
+
+    await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).rejects.toBeInstanceOf(PhotoIndexWriteError);
+  });
+
+  test("fails closed when a marker sequence is inconsistent with the Event head", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000115", capturedAt: 1753315200010 };
+    const photo = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    state.set(photoFeedMarkerKey("launch", photo.key), JSON.stringify({ version: 1, sequence: 2 }));
+
+    await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).rejects.toBeInstanceOf(PhotoIndexWriteError);
+  });
+
+  test("fails closed when exact committed proof points at an orphan node", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const upload = { captureId: "018f0000-0000-4000-8000-000000000116", capturedAt: 1753315200011 };
+    const photo = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    const entryKey = (await state.list({ prefix: "events/launch/photo-feed/v1/entries/" })).objects[0]!.key;
+    const orphanNodeKey = "events/launch/photo-feed/v1/nodes/orphan.json";
+    state.set(orphanNodeKey, JSON.stringify({
+      version: 1,
+      sequence: 1,
+      entryKey,
+      previousNodeKey: null,
+    }));
+    state.set(photoFeedCommittedKey("launch", 1), JSON.stringify({
+      version: 1,
+      sequence: 1,
+      key: photo.key,
+      entryKey,
+      nodeKey: orphanNodeKey,
+    }));
+
+    await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).rejects.toBeInstanceOf(PhotoIndexWriteError);
+  });
+
   test("pages a delta through private feed records and exact public gets without relisting PHOTOS", async () => {
     const photos = new GuardedPhotoListStore();
     const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
diff --git a/app/event-store.ts b/app/event-store.ts
index 57d745c..914e033 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -24,6 +24,8 @@ const PAGE_SIZE = 1000;
 const BOOTH_KEY_MUTATION_FINGERPRINT = /^[0-9a-f]{64}$/;
 const PHOTO_FEED_VERSION = 1 as const;
 const PHOTO_FEED_APPEND_ATTEMPTS = 16;
+const PHOTO_FEED_PAGE_SIZE = 1000;
+const PHOTO_FEED_SEQUENCE_WIDTH = 16;
 
 type StoredEventConfig = EventConfig & { version: typeof EVENT_CONFIG_VERSION };
 type ConfigSaveInput = {
@@ -234,14 +236,19 @@ export const photoIndexKey = (event: string, key: string, sortTime: number) =>
 export const photoFeedHeadKey = (event: string) => `events/${event}/photo-feed/v1/head.json`;
 const photoFeedEntryKey = (event: string, key: string) =>
   `events/${event}/photo-feed/v1/entries/${base64url(key)}.json`;
-const photoFeedCommitKey = (event: string, key: string) =>
-  `events/${event}/photo-feed/v1/commits/${base64url(key)}.json`;
+export const photoFeedMarkerKey = (event: string, key: string) =>
+  `events/${event}/photo-feed/v1/markers/${base64url(key)}.json`;
+export const photoFeedCommittedKey = (event: string, sequence: number) =>
+  `events/${event}/photo-feed/v1/committed/${String(sequence).padStart(PHOTO_FEED_SEQUENCE_WIDTH, "0")}.json`;
 const photoFeedNodePrefix = (event: string) => `events/${event}/photo-feed/v1/nodes/`;
 const photoFeedNodeKey = (event: string) =>
   `${photoFeedNodePrefix(event)}${crypto.randomUUID()}.json`;
 
 function isPhotoKey(event: string, key: string): boolean {
-  return key.startsWith(eventPhotoPrefix(event)) && /\.(?:jpe?g|png|gif|webp|hei[cf]|avif)$/i.test(key);
+  const prefix = eventPhotoPrefix(event);
+  if (!key.startsWith(prefix)) return false;
+  const filename = key.slice(prefix.length);
+  return /^[^/\\?#]+\.(?:jpe?g|png|gif|webp|hei[cf]|avif)$/i.test(filename);
 }
 
 export type Photo = { key: string; url: string; uploadedAt: Date };
@@ -567,54 +574,71 @@ export class EventStore {
 
   async listPhotos(event: string, after: string | null = null): Promise<PhotoFeed> {
     if (after === null) return this.initialPhotoFeed(event);
+    if (isPhotoKey(event, after)) {
+      // One-release compatibility bridge: a Gallery already open during the
+      // deploy may still hold the former raw complete-key cursor. Rebase it
+      // through one safe initial snapshot and return the new sequence cursor.
+      // Structural ownership is sufficient: moderation may already have
+      // deleted the exact photo while that Gallery still held its old cursor.
+      return this.initialPhotoFeed(event);
+    }
     return this.incrementalPhotoFeed(event, parsePhotoFeedCursor(event, after));
   }
 
   /**
    * The initial scan remains the compatibility path for photos created before
-   * the private arrival feed existed. Capture a feed waterline first, then
-   * omit any image committed after it so the immediate delta returns it once.
+   * the private arrival feed existed. Capture the sequence waterline first.
+   * A photo racing the public scan may also arrive in the immediate delta;
+   * clients already deduplicate exact keys, while omission would risk a miss.
    */
   private async initialPhotoFeed(event: string): Promise<PhotoFeed> {
     const waterline = await this.readPhotoFeedHead(event);
-    const objects = await this.listEventPhotoObjects(event);
-    const current = await this.readPhotoFeedHead(event);
-    const afterWaterline = new Set(
-      (await this.photoFeedNodesAfter(event, current.head.nodeKey, waterline.head.nodeKey))
-        .map((node) => node.entryKey)
-    );
-    const visible = objects
-      .filter((object) => !afterWaterline.has(photoFeedEntryKey(event, object.key)))
-      .sort(newestPublicObjectFirst);
+    const visible = (await this.listEventPhotoObjects(event)).sort(newestPublicObjectFirst);
 
     return {
       photos: visible.map((object) => this.toPhoto(object)),
-      cursor: encodePhotoFeedCursor(event, waterline.head.nodeKey),
+      cursor: encodePhotoFeedCursor(event, waterline.head.sequence),
       unchanged: visible.length === 0,
       truncated: false,
     };
   }
 
-  /** Deltas traverse only private arrival nodes and the exact public images. */
+  /** Deltas read a bounded contiguous sequence page and exact public images. */
   private async incrementalPhotoFeed(event: string, cursor: PhotoFeedCursor): Promise<PhotoFeed> {
     const current = await this.readPhotoFeedHead(event);
-    const nodes = await this.photoFeedNodesAfter(event, current.head.nodeKey, cursor.nodeKey);
+    if (cursor.sequence > current.head.sequence) throw new InvalidPhotoCursorError();
+    let previous = await this.validatePhotoFeedCursorProof(event, cursor.sequence, current.head);
+    let advancedSequence = cursor.sequence;
     const photos: Photo[] = [];
-    const seen = new Set<string>();
-    for (const node of nodes) {
-      const entry = await this.readPhotoFeedEntry(event, node.entryKey);
-      if (seen.has(entry.key)) continue;
-      seen.add(entry.key);
+    const upperSequence = Math.min(
+      current.head.sequence,
+      cursor.sequence + PHOTO_FEED_PAGE_SIZE
+    );
+
+    for (let sequence = cursor.sequence + 1; sequence <= upperSequence; sequence += 1) {
+      const committed = await this.readPhotoFeedCommitted(event, sequence);
+      // Head CAS happens before the exact committed record. Never advance
+      // across that short repair window or a later repair would be skipped.
+      if (!committed) break;
+      const { entry, node } = await this.validateCommittedArrival(event, committed);
+      if (
+        (previous === null && node.previousNodeKey !== null)
+        || (previous !== null && node.previousNodeKey !== previous.nodeKey)
+      ) {
+        throw new InvalidStoredPhotoFeedError(event);
+      }
       const object = await this.photos.get(entry.key);
-      // Exact-key deletion or a stale record must never resurrect an image.
-      if (!object || !isPhotoKey(event, object.key)) continue;
-      photos.push(this.toPhoto(object));
+      if (object && isPhotoKey(event, object.key)) photos.push(this.toPhoto(object));
+      advancedSequence = sequence;
+      previous = committed;
     }
+
+    photos.reverse();
     return {
       photos,
-      cursor: encodePhotoFeedCursor(event, current.head.nodeKey),
+      cursor: encodePhotoFeedCursor(event, advancedSequence),
       unchanged: photos.length === 0,
-      truncated: false,
+      truncated: advancedSequence < current.head.sequence,
     };
   }
 
@@ -635,9 +659,9 @@ export class EventStore {
 
   /**
    * Creates one immutable entry per public key, then atomically appends an
-   * immutable linked node by CASing the Event head. The normal lost-ack path
-   * reads the per-photo commit marker in O(1); a chain walk happens only when
-   * recovering a successful head CAS whose marker write was interrupted.
+   * immutable linked node by CASing the Event head. A sequence-derived exact
+   * committed record makes paging bounded. The per-photo marker is only an
+   * O(1) lookup hint and must prove itself against committed state.
    */
   private async ensurePhotoFeedRecord(
     event: string,
@@ -657,22 +681,21 @@ export class EventStore {
       if (existing.key !== key || !samePrivatePhotoMetadata(existing.metadata, metadata)) {
         throw new InvalidStoredPhotoFeedError(event);
       }
-      const committed = await this.readPhotoFeedCommit(event, key);
-      if (committed) return;
-      // A prior request might have advanced the head and then lost its marker
-      // write. Recover that exact node before ever attempting a new append.
-      const head = await this.readPhotoFeedHead(event);
-      const recovered = await this.findPhotoFeedEntryNode(event, head.head.nodeKey, entryKey);
-      if (recovered) {
-        await this.writePhotoFeedCommit(event, key, recovered);
-        return;
-      }
+    }
+
+    if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
+    if (!entryCreated && await this.recoverPhotoFeedRecord(event, key, entryKey)) {
+      return;
     }
 
     for (let attempt = 0; attempt < PHOTO_FEED_APPEND_ATTEMPTS; attempt += 1) {
-      const committed = await this.readPhotoFeedCommit(event, key);
-      if (committed) return;
+      if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
       const head = await this.readPhotoFeedHead(event);
+      await this.ensurePhotoFeedHeadCommitted(event, head.head);
+      // Another identical attempt may have advanced this exact entry before
+      // its marker became visible. Repairing the head above completes that
+      // proof, so recheck before appending the same entry a second time.
+      if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
       const nodeKey = photoFeedNodeKey(event);
       const node: PrivatePhotoFeedNode = {
         version: PHOTO_FEED_VERSION,
@@ -694,20 +717,13 @@ export class EventStore {
         jsonWriteOptions()
       );
       if (advanced) {
-        await this.writePhotoFeedCommit(event, key, nodeKey);
+        await this.writePhotoFeedCommitted(event, nodeKey, node, entry);
+        await this.writePhotoFeedMarker(event, key, node.sequence);
         return;
       }
 
-      // Another duplicate request may have won the head CAS. Its normal path
-      // records a marker; if that write was interrupted, recover by chain.
-      const racedCommit = await this.readPhotoFeedCommit(event, key);
-      if (racedCommit) return;
-      const current = await this.readPhotoFeedHead(event);
-      const recovered = await this.findPhotoFeedEntryNode(event, current.head.nodeKey, entryKey);
-      if (recovered) {
-        await this.writePhotoFeedCommit(event, key, recovered);
-        return;
-      }
+      if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
+      if (await this.recoverPhotoFeedRecord(event, key, entryKey)) return;
     }
     throw new Error("photo feed append contention exceeded retry budget");
   }
@@ -773,8 +789,8 @@ export class EventStore {
     return node;
   }
 
-  private async readPhotoFeedCommit(event: string, key: string): Promise<string | null> {
-    const object = await this.state.get(photoFeedCommitKey(event, key));
+  private async readPhotoFeedMarker(event: string, key: string): Promise<PrivatePhotoFeedMarker | null> {
+    const object = await this.state.get(photoFeedMarkerKey(event, key));
     if (!object) return null;
     let value: unknown;
     try {
@@ -782,54 +798,160 @@ export class EventStore {
     } catch {
       throw new InvalidStoredPhotoFeedError(event);
     }
-    const marker = parsePhotoFeedCommit(event, value);
+    const marker = parsePhotoFeedMarker(value);
     if (!marker) throw new InvalidStoredPhotoFeedError(event);
-    return marker.nodeKey;
+    return marker;
+  }
+
+  private async readPhotoFeedCommitted(
+    event: string,
+    sequence: number
+  ): Promise<PrivatePhotoFeedCommitted | null> {
+    const object = await this.state.get(photoFeedCommittedKey(event, sequence));
+    if (!object) return null;
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const committed = parsePhotoFeedCommitted(event, value);
+    if (!committed || committed.sequence !== sequence) throw new InvalidStoredPhotoFeedError(event);
+    return committed;
   }
 
-  private async writePhotoFeedCommit(event: string, key: string, nodeKey: string): Promise<void> {
+  private async writePhotoFeedMarker(event: string, key: string, sequence: number): Promise<void> {
     const created = await this.state.compareAndSwap(
-      photoFeedCommitKey(event, key),
+      photoFeedMarkerKey(event, key),
       null,
-      JSON.stringify({ version: PHOTO_FEED_VERSION, nodeKey }),
+      JSON.stringify({ version: PHOTO_FEED_VERSION, sequence }),
       jsonWriteOptions()
     );
     if (created) return;
-    const existing = await this.readPhotoFeedCommit(event, key);
-    if (existing !== nodeKey) throw new InvalidStoredPhotoFeedError(event);
+    const existing = await this.readPhotoFeedMarker(event, key);
+    if (existing?.sequence !== sequence) throw new InvalidStoredPhotoFeedError(event);
   }
 
-  private async photoFeedNodesAfter(
+  private async writePhotoFeedCommitted(
     event: string,
-    headNodeKey: string | null,
-    afterNodeKey: string | null
-  ): Promise<PrivatePhotoFeedNode[]> {
-    const nodes: PrivatePhotoFeedNode[] = [];
-    const visited = new Set<string>();
-    let nodeKey = headNodeKey;
-    while (nodeKey !== null && nodeKey !== afterNodeKey) {
-      if (visited.has(nodeKey)) throw new InvalidStoredPhotoFeedError(event);
-      visited.add(nodeKey);
-      const node = await this.readPhotoFeedNode(event, nodeKey);
-      nodes.push(node);
-      nodeKey = node.previousNodeKey;
+    nodeKey: string,
+    node: PrivatePhotoFeedNode,
+    entry: PrivatePhotoFeedEntry
+  ): Promise<PrivatePhotoFeedCommitted> {
+    const committed: PrivatePhotoFeedCommitted = {
+      version: PHOTO_FEED_VERSION,
+      sequence: node.sequence,
+      key: entry.key,
+      entryKey: node.entryKey,
+      nodeKey,
+    };
+    const created = await this.state.compareAndSwap(
+      photoFeedCommittedKey(event, node.sequence),
+      null,
+      JSON.stringify(committed),
+      jsonWriteOptions()
+    );
+    if (created) return committed;
+    const existing = await this.readPhotoFeedCommitted(event, node.sequence);
+    if (!existing || !samePhotoFeedCommitted(existing, committed)) {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    return existing;
+  }
+
+  private async validateCommittedArrival(
+    event: string,
+    committed: PrivatePhotoFeedCommitted
+  ): Promise<{ node: PrivatePhotoFeedNode; entry: PrivatePhotoFeedEntry }> {
+    if (committed.entryKey !== photoFeedEntryKey(event, committed.key)) {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const node = await this.readPhotoFeedNode(event, committed.nodeKey);
+    if (node.sequence !== committed.sequence || node.entryKey !== committed.entryKey) {
+      throw new InvalidStoredPhotoFeedError(event);
     }
-    if (afterNodeKey !== null && nodeKey !== afterNodeKey) throw new InvalidPhotoCursorError();
-    return nodes;
+    const entry = await this.readPhotoFeedEntry(event, committed.entryKey);
+    if (entry.key !== committed.key) throw new InvalidStoredPhotoFeedError(event);
+    return { node, entry };
+  }
+
+  private async validatePhotoFeedCursorProof(
+    event: string,
+    sequence: number,
+    head: PrivatePhotoFeedHead
+  ): Promise<PrivatePhotoFeedCommitted | null> {
+    if (sequence === 0) return null;
+    try {
+      const committed = await this.readPhotoFeedCommitted(event, sequence);
+      if (!committed) throw new InvalidPhotoCursorError();
+      await this.validateCommittedArrival(event, committed);
+      if (sequence === head.sequence) {
+        if (head.nodeKey !== committed.nodeKey) throw new InvalidPhotoCursorError();
+      } else {
+        const successor = await this.readPhotoFeedCommitted(event, sequence + 1);
+        // A head CAS may be visible just before its exact successor commit.
+        // The caller's prior committed record is still valid; paging below
+        // must stop at the gap without invalidating or advancing its cursor.
+        if (successor) {
+          const { node } = await this.validateCommittedArrival(event, successor);
+          if (node.previousNodeKey !== committed.nodeKey) throw new InvalidPhotoCursorError();
+        }
+      }
+      return committed;
+    } catch (error) {
+      if (error instanceof InvalidPhotoCursorError) throw error;
+      throw new InvalidPhotoCursorError();
+    }
+  }
+
+  private async hasValidPhotoFeedMarker(event: string, key: string, entryKey: string): Promise<boolean> {
+    const marker = await this.readPhotoFeedMarker(event, key);
+    if (!marker) return false;
+    const head = await this.readPhotoFeedHead(event);
+    if (marker.sequence > head.head.sequence) return false;
+    const committed = await this.readPhotoFeedCommitted(event, marker.sequence);
+    if (!committed || committed.key !== key || committed.entryKey !== entryKey) return false;
+    await this.validateCommittedArrival(event, committed);
+    if (marker.sequence === head.head.sequence) return head.head.nodeKey === committed.nodeKey;
+    const successor = await this.readPhotoFeedCommitted(event, marker.sequence + 1);
+    if (!successor) return false;
+    const { node: successorNode } = await this.validateCommittedArrival(event, successor);
+    return successorNode.previousNodeKey === committed.nodeKey;
+  }
+
+  private async ensurePhotoFeedHeadCommitted(event: string, head: PrivatePhotoFeedHead): Promise<void> {
+    if (head.sequence === 0) return;
+    if (!head.nodeKey) throw new InvalidStoredPhotoFeedError(event);
+    const node = await this.readPhotoFeedNode(event, head.nodeKey);
+    if (node.sequence !== head.sequence) throw new InvalidStoredPhotoFeedError(event);
+    const entry = await this.readPhotoFeedEntry(event, node.entryKey);
+    await this.writePhotoFeedCommitted(event, head.nodeKey, node, entry);
+    await this.writePhotoFeedMarker(event, entry.key, node.sequence);
+  }
+
+  private async recoverPhotoFeedRecord(event: string, key: string, entryKey: string): Promise<boolean> {
+    const head = await this.readPhotoFeedHead(event);
+    const recovered = await this.findPhotoFeedEntryNode(event, head.head.nodeKey, entryKey);
+    if (!recovered) return false;
+    const entry = await this.readPhotoFeedEntry(event, entryKey);
+    if (entry.key !== key) throw new InvalidStoredPhotoFeedError(event);
+    await this.writePhotoFeedCommitted(event, recovered.nodeKey, recovered.node, entry);
+    await this.writePhotoFeedMarker(event, key, recovered.node.sequence);
+    return true;
   }
 
   private async findPhotoFeedEntryNode(
     event: string,
     headNodeKey: string | null,
     entryKey: string
-  ): Promise<string | null> {
+  ): Promise<{ nodeKey: string; node: PrivatePhotoFeedNode } | null> {
     const visited = new Set<string>();
     let nodeKey = headNodeKey;
     while (nodeKey !== null) {
       if (visited.has(nodeKey)) throw new InvalidStoredPhotoFeedError(event);
       visited.add(nodeKey);
       const node = await this.readPhotoFeedNode(event, nodeKey);
-      if (node.entryKey === entryKey) return nodeKey;
+      if (node.entryKey === entryKey) return { nodeKey, node };
       nodeKey = node.previousNodeKey;
     }
     return null;
@@ -1225,15 +1347,23 @@ type PrivatePhotoFeedNode = {
   previousNodeKey: string | null;
 };
 
-type PrivatePhotoFeedCommit = {
+type PrivatePhotoFeedMarker = {
+  version: typeof PHOTO_FEED_VERSION;
+  sequence: number;
+};
+
+type PrivatePhotoFeedCommitted = {
   version: typeof PHOTO_FEED_VERSION;
+  sequence: number;
+  key: string;
+  entryKey: string;
   nodeKey: string;
 };
 
 type PhotoFeedCursor = {
   version: typeof PHOTO_FEED_VERSION;
   event: string;
-  nodeKey: string | null;
+  sequence: number;
 };
 
 type PrivatePhotoMetadata = {
@@ -1266,6 +1396,7 @@ function parsePhotoFeedHead(event: string, value: unknown): PrivatePhotoFeedHead
     || !Number.isSafeInteger(value.sequence)
     || value.sequence < 0
     || (value.nodeKey !== null && (typeof value.nodeKey !== "string" || !value.nodeKey.startsWith(photoFeedNodePrefix(event))))
+    || (value.sequence === 0) !== (value.nodeKey === null)
   ) {
     return null;
   }
@@ -1289,6 +1420,7 @@ function parsePhotoFeedNode(event: string, value: unknown): PrivatePhotoFeedNode
     || typeof value.entryKey !== "string"
     || !value.entryKey.startsWith(`events/${event}/photo-feed/v1/entries/`)
     || (value.previousNodeKey !== null && (typeof value.previousNodeKey !== "string" || !value.previousNodeKey.startsWith(photoFeedNodePrefix(event))))
+    || (value.sequence === 1) !== (value.previousNodeKey === null)
   ) {
     return null;
   }
@@ -1300,16 +1432,42 @@ function parsePhotoFeedNode(event: string, value: unknown): PrivatePhotoFeedNode
   };
 }
 
-function parsePhotoFeedCommit(event: string, value: unknown): PrivatePhotoFeedCommit | null {
+function parsePhotoFeedMarker(value: unknown): PrivatePhotoFeedMarker | null {
   if (
     !isRecord(value)
     || value.version !== PHOTO_FEED_VERSION
+    || typeof value.sequence !== "number"
+    || !Number.isSafeInteger(value.sequence)
+    || value.sequence < 1
+  ) {
+    return null;
+  }
+  return { version: PHOTO_FEED_VERSION, sequence: value.sequence };
+}
+
+function parsePhotoFeedCommitted(event: string, value: unknown): PrivatePhotoFeedCommitted | null {
+  if (
+    !isRecord(value)
+    || value.version !== PHOTO_FEED_VERSION
+    || typeof value.sequence !== "number"
+    || !Number.isSafeInteger(value.sequence)
+    || value.sequence < 1
+    || typeof value.key !== "string"
+    || !isPhotoKey(event, value.key)
+    || typeof value.entryKey !== "string"
+    || !value.entryKey.startsWith(`events/${event}/photo-feed/v1/entries/`)
     || typeof value.nodeKey !== "string"
     || !value.nodeKey.startsWith(photoFeedNodePrefix(event))
   ) {
     return null;
   }
-  return { version: PHOTO_FEED_VERSION, nodeKey: value.nodeKey };
+  return {
+    version: PHOTO_FEED_VERSION,
+    sequence: value.sequence,
+    key: value.key,
+    entryKey: value.entryKey,
+    nodeKey: value.nodeKey,
+  };
 }
 
 function parsePrivatePhotoMetadata(event: string, value: unknown): PrivatePhotoMetadata | null {
@@ -1355,8 +1513,19 @@ function isBoundedToken(value: unknown): value is string {
   return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value);
 }
 
-function encodePhotoFeedCursor(event: string, nodeKey: string | null): string {
-  return `pf1.${base64url(JSON.stringify({ version: PHOTO_FEED_VERSION, event, nodeKey }))}`;
+function samePhotoFeedCommitted(
+  left: PrivatePhotoFeedCommitted,
+  right: PrivatePhotoFeedCommitted
+): boolean {
+  return left.version === right.version
+    && left.sequence === right.sequence
+    && left.key === right.key
+    && left.entryKey === right.entryKey
+    && left.nodeKey === right.nodeKey;
+}
+
+function encodePhotoFeedCursor(event: string, sequence: number): string {
+  return `pf1.${base64url(JSON.stringify({ version: PHOTO_FEED_VERSION, event, sequence }))}`;
 }
 
 function parsePhotoFeedCursor(event: string, value: string): PhotoFeedCursor {
@@ -1367,16 +1536,20 @@ function parsePhotoFeedCursor(event: string, value: string): PhotoFeedCursor {
   } catch {
     throw new InvalidPhotoCursorError();
   }
-  if (!isRecord(decoded) || decoded.version !== PHOTO_FEED_VERSION || decoded.event !== event) {
-    throw new InvalidPhotoCursorError();
-  }
-  if (decoded.nodeKey !== null && (typeof decoded.nodeKey !== "string" || !decoded.nodeKey.startsWith(photoFeedNodePrefix(event)))) {
+  if (
+    !isRecord(decoded)
+    || decoded.version !== PHOTO_FEED_VERSION
+    || decoded.event !== event
+    || typeof decoded.sequence !== "number"
+    || !Number.isSafeInteger(decoded.sequence)
+    || decoded.sequence < 0
+  ) {
     throw new InvalidPhotoCursorError();
   }
   return {
     version: PHOTO_FEED_VERSION,
     event,
-    nodeKey: decoded.nodeKey as string | null,
+    sequence: decoded.sequence,
   };
 }
 

From 3256a988435596f7312172ff9f162cfe3d61d48e Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 16:18:27 +0800
Subject: [PATCH 032/105] fix: make photo feed recovery bounded

---
 app/event-store.test.ts | 162 ++++++++++++++++++++----
 app/event-store.ts      | 265 +++++++++++++++++++++++++++++++---------
 2 files changed, 346 insertions(+), 81 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index c16ea19..d983cc9 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -96,6 +96,27 @@ class InstrumentedStateStore extends InMemoryObjectStore {
   }
 }
 
+class CrashAfterSuccessfulCasStore extends InMemoryObjectStore {
+  private crashed = false;
+
+  constructor(private readonly crashPrefix: string) {
+    super();
+  }
+
+  override async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    const written = await super.compareAndSwap(key, expectedEtag, value);
+    if (written && !this.crashed && key.startsWith(this.crashPrefix)) {
+      this.crashed = true;
+      throw new Error(`simulated crash after durable CAS for ${key}`);
+    }
+    return written;
+  }
+}
+
 function decodePhotoFeedCursor(cursor: string): Record<string, unknown> {
   const encoded = cursor.slice("pf1.".length).replaceAll("-", "+").replaceAll("_", "/");
   const padded = encoded + "=".repeat((4 - encoded.length % 4) % 4);
@@ -1184,12 +1205,12 @@ describe("EventStore", () => {
     expect(delta.photos.map((photo) => photo.key)).toEqual([repaired.key]);
   });
 
-  test("a normal lost-ack retry validates its exact commit proof in bounded O(1) reads", async () => {
+  test("a missing-marker retry stays bounded after 50 intervening arrivals", async () => {
     const state = new InstrumentedStateStore();
     const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
     const upload = { captureId: "018f0000-0000-4000-8000-000000000111", capturedAt: 1753315200006 };
 
-    await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+    const first = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
     for (let index = 0; index < 50; index += 1) {
       await store.putPhoto("launch", new Uint8Array([index]).buffer, {
         upload: {
@@ -1198,10 +1219,79 @@ describe("EventStore", () => {
         },
       });
     }
+    await state.delete(photoFeedMarkerKey("launch", first.key));
     state.resetReads();
 
     await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload })).resolves.toMatchObject({ duplicate: true });
-    expect(state.reads).toBeLessThanOrEqual(10);
+    expect(state.reads).toBeLessThanOrEqual(15);
+  });
+
+  for (const crashPoint of ["claims/", "head.json", "committed/", "markers/"] as const) {
+    test(`an identical retry finalizes a lost acknowledgement after ${crashPoint}`, async () => {
+      const state = new CrashAfterSuccessfulCasStore(`events/launch/photo-feed/v1/${crashPoint}`);
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      const before = await store.listPhotos("launch");
+      const crashIndex = ["claims/", "head.json", "committed/", "markers/"].indexOf(crashPoint);
+      const upload = {
+        captureId: `018f0000-0000-4000-8000-${String(120 + crashIndex).padStart(12, "0")}`,
+        capturedAt: 1753315200020 + crashIndex,
+      };
+
+      await expect(store.putPhoto("launch", new Uint8Array([1]).buffer, { upload }))
+        .rejects.toBeInstanceOf(PhotoIndexWriteError);
+      const retry = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload });
+      const delta = await store.listPhotos("launch", before.cursor);
+
+      expect(retry).toMatchObject({ duplicate: true, indexStored: true });
+      expect(delta.photos.map((photo) => photo.key)).toEqual([retry.key]);
+      expect(decodePhotoFeedCursor(delta.cursor!).sequence).toBe(1);
+    });
+  }
+
+  test("replaces an exact stale claim after another arrival wins its sequence", async () => {
+    const state = new CrashAfterSuccessfulCasStore("events/launch/photo-feed/v1/claims/");
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const before = await store.listPhotos("launch");
+    const interruptedUpload = {
+      captureId: "018f0000-0000-4000-8000-000000000130",
+      capturedAt: 1753315200030,
+    };
+
+    await expect(store.putPhoto("launch", new Uint8Array([1]).buffer, { upload: interruptedUpload }))
+      .rejects.toBeInstanceOf(PhotoIndexWriteError);
+    const winner = await store.putPhoto("launch", new Uint8Array([2]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000131", capturedAt: 1753315200031 },
+    });
+    const recovered = await store.putPhoto("launch", new Uint8Array([3]).buffer, { upload: interruptedUpload });
+    const delta = await store.listPhotos("launch", before.cursor);
+
+    expect(delta.photos.map((photo) => photo.key)).toEqual([recovered.key, winner.key]);
+    expect(decodePhotoFeedCursor(delta.cursor!).sequence).toBe(2);
+  });
+
+  test("a corrupt exact claim fails closed without advancing the Event head", async () => {
+    const state = new CrashAfterSuccessfulCasStore("events/launch/photo-feed/v1/claims/");
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const upload = {
+      captureId: "018f0000-0000-4000-8000-000000000132",
+      capturedAt: 1753315200032,
+    };
+
+    await expect(store.putPhoto("launch", new Uint8Array([1]).buffer, { upload }))
+      .rejects.toBeInstanceOf(PhotoIndexWriteError);
+    const claimObject = (await state.list({
+      prefix: "events/launch/photo-feed/v1/claims/",
+    })).objects[0]!;
+    const claim = await (await state.get(claimObject.key))!.json<Record<string, unknown>>();
+    state.set(claimObject.key, JSON.stringify({
+      ...claim,
+      sequence: 2,
+      previousNodeKey: null,
+    }));
+
+    await expect(store.putPhoto("launch", new Uint8Array([2]).buffer, { upload }))
+      .rejects.toBeInstanceOf(PhotoIndexWriteError);
+    expect(state.has(photoFeedHeadKey("launch"))).toBe(false);
   });
 
   test("receipt failure is observable but does not reject an acknowledged stable photo", async () => {
@@ -1331,7 +1421,7 @@ describe("EventStore", () => {
     expect(decoded).not.toHaveProperty("nodeKey");
   });
 
-  test("bounds fabricated-head delta work and stops before a missing committed sequence", async () => {
+  test("fails closed on a fabricated head in bounded work", async () => {
     const state = new InstrumentedStateStore();
     const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
     const before = await store.listPhotos("launch");
@@ -1342,9 +1432,9 @@ describe("EventStore", () => {
     }));
     state.resetReads();
 
-    const delta = await store.listPhotos("launch", before.cursor);
-
-    expect(delta).toMatchObject({ photos: [], cursor: before.cursor, unchanged: true, truncated: true });
+    await expect(store.listPhotos("launch", before.cursor)).rejects.toThrow(
+      "photo feed state for launch is corrupt"
+    );
     expect(state.reads).toBeLessThanOrEqual(3);
   });
 
@@ -1376,7 +1466,7 @@ describe("EventStore", () => {
     expect(keys).toEqual([...uploaded.slice(0, 1000).reverse(), ...uploaded.slice(1000).reverse()]);
   });
 
-  test("does not advance past a missing committed sequence and retry repairs it", async () => {
+  test("a read repairs a stable head commit before it can advance the cursor", async () => {
     const photos = new InMemoryObjectStore();
     const state = new FailPrivatePhotoWriteStore("events/launch/photo-feed/v1/committed/");
     const store = new EventStore(photos, state, "https://photos.example");
@@ -1384,19 +1474,57 @@ describe("EventStore", () => {
     const upload = { captureId: "018f0000-0000-4000-8000-000000000113", capturedAt: 1753315200008 };
 
     await expect(store.putPhoto("launch", new Uint8Array([1]).buffer, { upload })).rejects.toBeInstanceOf(PhotoIndexWriteError);
-    const blocked = await store.listPhotos("launch", before.cursor);
-    expect(blocked).toMatchObject({ photos: [], cursor: before.cursor, truncated: true });
+    await expect(store.listPhotos("launch", before.cursor)).rejects.toThrow(
+      "simulated private write failure"
+    );
 
     state.allowWrites();
-    const repaired = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload });
     const delta = await store.listPhotos("launch", before.cursor);
+    const repaired = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload });
 
     expect(delta.photos.map((photo) => photo.key)).toEqual([repaired.key]);
     expect(decodePhotoFeedCursor(delta.cursor!).sequence).toBe(1);
     expect(delta.truncated).toBe(false);
   });
 
-  test("keeps a valid prior cursor usable while its successor commit is repaired", async () => {
+  test("an existing Gallery read repairs a legacy head left ahead of its commit", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new FailPrivatePhotoWriteStore("events/launch/photo-feed/v1/committed/");
+    const store = new EventStore(photos, state, "https://photos.example");
+    const before = await store.listPhotos("launch");
+
+    const legacy = await store.putPhoto("launch", new Uint8Array([1]).buffer);
+    expect(legacy).toMatchObject({ duplicate: false, indexStored: true });
+    expect(state.has(photoFeedHeadKey("launch"))).toBe(true);
+    expect(state.has(photoFeedCommittedKey("launch", 1))).toBe(false);
+
+    state.allowWrites();
+    const delta = await store.listPhotos("launch", before.cursor);
+
+    expect(delta.photos.map((photo) => photo.key)).toEqual([legacy.key]);
+    expect(decodePhotoFeedCursor(delta.cursor!).sequence).toBe(1);
+    expect(state.has(photoFeedCommittedKey("launch", 1))).toBe(true);
+    expect(state.has(photoFeedMarkerKey("launch", legacy.key))).toBe(true);
+  });
+
+  test("a fresh Gallery read repairs a legacy head left ahead of its commit", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new FailPrivatePhotoWriteStore("events/launch/photo-feed/v1/committed/");
+    const store = new EventStore(photos, state, "https://photos.example");
+
+    const legacy = await store.putPhoto("launch", new Uint8Array([1]).buffer);
+    expect(state.has(photoFeedCommittedKey("launch", 1))).toBe(false);
+
+    state.allowWrites();
+    const initial = await store.listPhotos("launch");
+
+    expect(initial.photos.map((photo) => photo.key)).toEqual([legacy.key]);
+    expect(decodePhotoFeedCursor(initial.cursor!).sequence).toBe(1);
+    expect(state.has(photoFeedCommittedKey("launch", 1))).toBe(true);
+    expect(state.has(photoFeedMarkerKey("launch", legacy.key))).toBe(true);
+  });
+
+  test("repairs a missing head commit before advancing a valid prior cursor", async () => {
     const state = new InMemoryObjectStore();
     const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
     const before = await store.listPhotos("launch");
@@ -1411,18 +1539,10 @@ describe("EventStore", () => {
     const second = await store.putPhoto("launch", new Uint8Array([2]).buffer, { upload: secondUpload });
     await state.delete(photoFeedCommittedKey("launch", 2));
 
-    const blocked = await store.listPhotos("launch", throughFirst.cursor);
-    expect(blocked).toMatchObject({
-      photos: [],
-      cursor: throughFirst.cursor,
-      unchanged: true,
-      truncated: true,
-    });
-
-    await store.putPhoto("launch", new Uint8Array([3]).buffer, { upload: secondUpload });
     const repaired = await store.listPhotos("launch", throughFirst.cursor);
     expect(repaired.photos.map((photo) => photo.key)).toEqual([second.key]);
     expect(decodePhotoFeedCursor(repaired.cursor!).sequence).toBe(2);
+    expect(state.has(photoFeedCommittedKey("launch", 2))).toBe(true);
   });
 
   test("fails closed on a corrupt per-photo sequence marker", async () => {
diff --git a/app/event-store.ts b/app/event-store.ts
index 914e033..fd77447 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -236,6 +236,8 @@ export const photoIndexKey = (event: string, key: string, sortTime: number) =>
 export const photoFeedHeadKey = (event: string) => `events/${event}/photo-feed/v1/head.json`;
 const photoFeedEntryKey = (event: string, key: string) =>
   `events/${event}/photo-feed/v1/entries/${base64url(key)}.json`;
+export const photoFeedClaimKey = (event: string, key: string) =>
+  `events/${event}/photo-feed/v1/claims/${base64url(key)}.json`;
 export const photoFeedMarkerKey = (event: string, key: string) =>
   `events/${event}/photo-feed/v1/markers/${base64url(key)}.json`;
 export const photoFeedCommittedKey = (event: string, sequence: number) =>
@@ -593,6 +595,7 @@ export class EventStore {
    */
   private async initialPhotoFeed(event: string): Promise<PhotoFeed> {
     const waterline = await this.readPhotoFeedHead(event);
+    await this.ensurePhotoFeedHeadCommitted(event, waterline.head);
     const visible = (await this.listEventPhotoObjects(event)).sort(newestPublicObjectFirst);
 
     return {
@@ -606,6 +609,7 @@ export class EventStore {
   /** Deltas read a bounded contiguous sequence page and exact public images. */
   private async incrementalPhotoFeed(event: string, cursor: PhotoFeedCursor): Promise<PhotoFeed> {
     const current = await this.readPhotoFeedHead(event);
+    await this.ensurePhotoFeedHeadCommitted(event, current.head);
     if (cursor.sequence > current.head.sequence) throw new InvalidPhotoCursorError();
     let previous = await this.validatePhotoFeedCursorProof(event, cursor.sequence, current.head);
     let advancedSequence = cursor.sequence;
@@ -658,10 +662,10 @@ export class EventStore {
   }
 
   /**
-   * Creates one immutable entry per public key, then atomically appends an
-   * immutable linked node by CASing the Event head. A sequence-derived exact
-   * committed record makes paging bounded. The per-photo marker is only an
-   * O(1) lookup hint and must prove itself against committed state.
+   * Creates one immutable entry per public key, then claims an exact candidate
+   * node before it can CAS the Event head. The mutable per-photo claim lets
+   * concurrent duplicates and crash retries finalize or replace that exact
+   * candidate without walking the linked history.
    */
   private async ensurePhotoFeedRecord(
     event: string,
@@ -684,48 +688,144 @@ export class EventStore {
     }
 
     if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
-    if (!entryCreated && await this.recoverPhotoFeedRecord(event, key, entryKey)) {
-      return;
-    }
 
     for (let attempt = 0; attempt < PHOTO_FEED_APPEND_ATTEMPTS; attempt += 1) {
-      if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
       const head = await this.readPhotoFeedHead(event);
       await this.ensurePhotoFeedHeadCommitted(event, head.head);
-      // Another identical attempt may have advanced this exact entry before
-      // its marker became visible. Repairing the head above completes that
-      // proof, so recheck before appending the same entry a second time.
       if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
-      const nodeKey = photoFeedNodeKey(event);
-      const node: PrivatePhotoFeedNode = {
-        version: PHOTO_FEED_VERSION,
-        sequence: head.head.sequence + 1,
-        entryKey,
-        previousNodeKey: head.head.nodeKey,
-      };
-      const nodeCreated = await this.state.compareAndSwap(
-        nodeKey,
-        null,
-        JSON.stringify(node),
+
+      const existingClaim = await this.readPhotoFeedClaim(event, key, entryKey);
+      if (!existingClaim) {
+        const candidate = this.photoFeedClaimForHead(event, entryKey, head.head);
+        const claimed = await this.state.compareAndSwap(
+          photoFeedClaimKey(event, key),
+          null,
+          JSON.stringify(candidate),
+          jsonWriteOptions()
+        );
+        if (!claimed) continue;
+        // The claim is durable before either its node or the Event head. A
+        // lost acknowledgement here is finalized by the next exact retry.
+        continue;
+      }
+
+      const outcome = await this.finalizePhotoFeedClaim(
+        event,
+        key,
+        entry,
+        existingClaim.claim
+      );
+      if (outcome === "committed") return;
+      if (outcome === "retry") continue;
+
+      const current = await this.readPhotoFeedHead(event);
+      await this.ensurePhotoFeedHeadCommitted(event, current.head);
+      if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
+      const replacement = this.photoFeedClaimForHead(event, entryKey, current.head);
+      await this.state.compareAndSwap(
+        photoFeedClaimKey(event, key),
+        existingClaim.etag,
+        JSON.stringify(replacement),
         jsonWriteOptions()
       );
-      if (!nodeCreated) continue;
+    }
+    throw new Error("photo feed append contention exceeded retry budget");
+  }
+
+  private photoFeedClaimForHead(
+    event: string,
+    entryKey: string,
+    head: PrivatePhotoFeedHead
+  ): PrivatePhotoFeedClaim {
+    return {
+      version: PHOTO_FEED_VERSION,
+      entryKey,
+      nodeKey: photoFeedNodeKey(event),
+      sequence: head.sequence + 1,
+      previousNodeKey: head.nodeKey,
+    };
+  }
+
+  private async finalizePhotoFeedClaim(
+    event: string,
+    key: string,
+    entry: PrivatePhotoFeedEntry,
+    claim: PrivatePhotoFeedClaim
+  ): Promise<"committed" | "stale" | "retry"> {
+    const head = await this.readPhotoFeedHead(event);
+
+    if (head.head.sequence === claim.sequence && head.head.nodeKey === claim.nodeKey) {
+      const node = await this.readClaimedPhotoFeedNode(event, claim);
+      await this.writePhotoFeedCommitted(event, claim.nodeKey, node, entry);
+      await this.writePhotoFeedMarker(event, key, claim.sequence);
+      return "committed";
+    }
+
+    if (
+      head.head.sequence === claim.sequence - 1
+      && head.head.nodeKey === claim.previousNodeKey
+    ) {
+      const node = await this.ensureClaimedPhotoFeedNode(event, claim);
       const advanced = await this.state.compareAndSwap(
         photoFeedHeadKey(event),
         head.etag,
-        JSON.stringify({ version: PHOTO_FEED_VERSION, sequence: node.sequence, nodeKey }),
+        JSON.stringify({
+          version: PHOTO_FEED_VERSION,
+          sequence: claim.sequence,
+          nodeKey: claim.nodeKey,
+        }),
         jsonWriteOptions()
       );
-      if (advanced) {
-        await this.writePhotoFeedCommitted(event, nodeKey, node, entry);
-        await this.writePhotoFeedMarker(event, key, node.sequence);
-        return;
-      }
+      if (!advanced) return "retry";
+      await this.writePhotoFeedCommitted(event, claim.nodeKey, node, entry);
+      await this.writePhotoFeedMarker(event, key, claim.sequence);
+      return "committed";
+    }
 
-      if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
-      if (await this.recoverPhotoFeedRecord(event, key, entryKey)) return;
+    if (head.head.sequence < claim.sequence) {
+      throw new InvalidStoredPhotoFeedError(event);
     }
-    throw new Error("photo feed append contention exceeded retry budget");
+
+    const committed = await this.readPhotoFeedCommitted(event, claim.sequence);
+    if (
+      committed
+      && committed.key === key
+      && committed.entryKey === claim.entryKey
+      && committed.nodeKey === claim.nodeKey
+    ) {
+      await this.validateCommittedArrival(event, committed);
+      await this.writePhotoFeedMarker(event, key, claim.sequence);
+      return "committed";
+    }
+    return "stale";
+  }
+
+  private async ensureClaimedPhotoFeedNode(
+    event: string,
+    claim: PrivatePhotoFeedClaim
+  ): Promise<PrivatePhotoFeedNode> {
+    const node = photoFeedNodeFromClaim(claim);
+    const created = await this.state.compareAndSwap(
+      claim.nodeKey,
+      null,
+      JSON.stringify(node),
+      jsonWriteOptions()
+    );
+    if (created) return node;
+    const existing = await this.readClaimedPhotoFeedNode(event, claim);
+    if (!samePhotoFeedNode(existing, node)) throw new InvalidStoredPhotoFeedError(event);
+    return existing;
+  }
+
+  private async readClaimedPhotoFeedNode(
+    event: string,
+    claim: PrivatePhotoFeedClaim
+  ): Promise<PrivatePhotoFeedNode> {
+    const node = await this.readPhotoFeedNode(event, claim.nodeKey);
+    if (!samePhotoFeedNode(node, photoFeedNodeFromClaim(claim))) {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    return node;
   }
 
   private async tryWritePhotoFeedRecord(
@@ -774,6 +874,24 @@ export class EventStore {
     return entry;
   }
 
+  private async readPhotoFeedClaim(
+    event: string,
+    key: string,
+    entryKey: string
+  ): Promise<{ claim: PrivatePhotoFeedClaim; etag: string } | null> {
+    const object = await this.state.get(photoFeedClaimKey(event, key));
+    if (!object) return null;
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredPhotoFeedError(event);
+    }
+    const claim = parsePhotoFeedClaim(event, value);
+    if (!claim || claim.entryKey !== entryKey) throw new InvalidStoredPhotoFeedError(event);
+    return { claim, etag: object.etag };
+  }
+
   private async readPhotoFeedNode(event: string, nodeKey: string): Promise<PrivatePhotoFeedNode> {
     if (!nodeKey.startsWith(photoFeedNodePrefix(event))) throw new InvalidStoredPhotoFeedError(event);
     const object = await this.state.get(nodeKey);
@@ -929,34 +1047,6 @@ export class EventStore {
     await this.writePhotoFeedMarker(event, entry.key, node.sequence);
   }
 
-  private async recoverPhotoFeedRecord(event: string, key: string, entryKey: string): Promise<boolean> {
-    const head = await this.readPhotoFeedHead(event);
-    const recovered = await this.findPhotoFeedEntryNode(event, head.head.nodeKey, entryKey);
-    if (!recovered) return false;
-    const entry = await this.readPhotoFeedEntry(event, entryKey);
-    if (entry.key !== key) throw new InvalidStoredPhotoFeedError(event);
-    await this.writePhotoFeedCommitted(event, recovered.nodeKey, recovered.node, entry);
-    await this.writePhotoFeedMarker(event, key, recovered.node.sequence);
-    return true;
-  }
-
-  private async findPhotoFeedEntryNode(
-    event: string,
-    headNodeKey: string | null,
-    entryKey: string
-  ): Promise<{ nodeKey: string; node: PrivatePhotoFeedNode } | null> {
-    const visited = new Set<string>();
-    let nodeKey = headNodeKey;
-    while (nodeKey !== null) {
-      if (visited.has(nodeKey)) throw new InvalidStoredPhotoFeedError(event);
-      visited.add(nodeKey);
-      const node = await this.readPhotoFeedNode(event, nodeKey);
-      if (node.entryKey === entryKey) return { nodeKey, node };
-      nodeKey = node.previousNodeKey;
-    }
-    return null;
-  }
-
   async *iteratePhotoObjects(event: string): AsyncGenerator<StoredObject> {
     let cursor: string | undefined;
     do {
@@ -1340,6 +1430,14 @@ type PrivatePhotoFeedEntry = {
   metadata: PrivatePhotoMetadata;
 };
 
+type PrivatePhotoFeedClaim = {
+  version: typeof PHOTO_FEED_VERSION;
+  entryKey: string;
+  nodeKey: string;
+  sequence: number;
+  previousNodeKey: string | null;
+};
+
 type PrivatePhotoFeedNode = {
   version: typeof PHOTO_FEED_VERSION;
   sequence: number;
@@ -1410,6 +1508,37 @@ function parsePhotoFeedEntry(event: string, value: unknown): PrivatePhotoFeedEnt
   return { version: PHOTO_FEED_VERSION, key: value.key, metadata };
 }
 
+function parsePhotoFeedClaim(event: string, value: unknown): PrivatePhotoFeedClaim | null {
+  if (!isRecord(value)) return null;
+  if (
+    value.version !== PHOTO_FEED_VERSION
+    || typeof value.sequence !== "number"
+    || !Number.isSafeInteger(value.sequence)
+    || value.sequence < 1
+    || typeof value.entryKey !== "string"
+    || !value.entryKey.startsWith(`events/${event}/photo-feed/v1/entries/`)
+    || typeof value.nodeKey !== "string"
+    || !value.nodeKey.startsWith(photoFeedNodePrefix(event))
+    || (
+      value.previousNodeKey !== null
+      && (
+        typeof value.previousNodeKey !== "string"
+        || !value.previousNodeKey.startsWith(photoFeedNodePrefix(event))
+      )
+    )
+    || (value.sequence === 1) !== (value.previousNodeKey === null)
+  ) {
+    return null;
+  }
+  return {
+    version: PHOTO_FEED_VERSION,
+    entryKey: value.entryKey,
+    nodeKey: value.nodeKey,
+    sequence: value.sequence,
+    previousNodeKey: value.previousNodeKey as string | null,
+  };
+}
+
 function parsePhotoFeedNode(event: string, value: unknown): PrivatePhotoFeedNode | null {
   if (!isRecord(value)) return null;
   if (
@@ -1524,6 +1653,22 @@ function samePhotoFeedCommitted(
     && left.nodeKey === right.nodeKey;
 }
 
+function photoFeedNodeFromClaim(claim: PrivatePhotoFeedClaim): PrivatePhotoFeedNode {
+  return {
+    version: PHOTO_FEED_VERSION,
+    sequence: claim.sequence,
+    entryKey: claim.entryKey,
+    previousNodeKey: claim.previousNodeKey,
+  };
+}
+
+function samePhotoFeedNode(left: PrivatePhotoFeedNode, right: PrivatePhotoFeedNode): boolean {
+  return left.version === right.version
+    && left.sequence === right.sequence
+    && left.entryKey === right.entryKey
+    && left.previousNodeKey === right.previousNodeKey;
+}
+
 function encodePhotoFeedCursor(event: string, sequence: number): string {
   return `pf1.${base64url(JSON.stringify({ version: PHOTO_FEED_VERSION, event, sequence }))}`;
 }

From 8dad75754c78af318ed335d68044fd8c274983bf Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 16:24:45 +0800
Subject: [PATCH 033/105] fix: preserve photo feed contention budget

---
 app/event-store.test.ts | 26 ++++++++++++++++++++++
 app/event-store.ts      | 49 +++++++++++++++++++++++++++++------------
 2 files changed, 61 insertions(+), 14 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index d983cc9..ad134fc 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -1387,6 +1387,32 @@ describe("EventStore", () => {
     expect(new Set(delta.photos.map((photo) => photo.key)).size).toBe(2);
   });
 
+  test("commits nine concurrent distinct arrivals without exhausting the append budget", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const before = await store.listPhotos("launch");
+
+    const uploads = await Promise.all(Array.from({ length: 9 }, (_, index) =>
+      store.putPhoto("launch", new Uint8Array([index]).buffer, {
+        upload: {
+          captureId: `018f0000-0000-4000-8000-${String(140 + index).padStart(12, "0")}`,
+          capturedAt: 1753315200040 + index,
+        },
+      })
+    ));
+    const delta = await store.listPhotos("launch", before.cursor);
+    const committed = await state.list({
+      prefix: "events/launch/photo-feed/v1/committed/",
+    });
+
+    expect(delta.photos).toHaveLength(9);
+    expect(new Set(delta.photos.map((photo) => photo.key))).toEqual(
+      new Set(uploads.map((photo) => photo.key))
+    );
+    expect(decodePhotoFeedCursor(delta.cursor!).sequence).toBe(9);
+    expect(committed.objects).toHaveLength(9);
+  });
+
   test("takes a feed-head waterline before the initial public scan", async () => {
     const photos = new WaterlinePhotoStore();
     const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
diff --git a/app/event-store.ts b/app/event-store.ts
index fd77447..466ba2f 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -694,7 +694,7 @@ export class EventStore {
       await this.ensurePhotoFeedHeadCommitted(event, head.head);
       if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
 
-      const existingClaim = await this.readPhotoFeedClaim(event, key, entryKey);
+      let existingClaim = await this.readPhotoFeedClaim(event, key, entryKey);
       if (!existingClaim) {
         const candidate = this.photoFeedClaimForHead(event, entryKey, head.head);
         const claimed = await this.state.compareAndSwap(
@@ -704,30 +704,43 @@ export class EventStore {
           jsonWriteOptions()
         );
         if (!claimed) continue;
-        // The claim is durable before either its node or the Event head. A
-        // lost acknowledgement here is finalized by the next exact retry.
-        continue;
+        // The claim is durable before either its node or the Event head.
+        // Finalize it in this same logical attempt; a crash after the claim
+        // remains recoverable by the next caller reading this exact record.
+        const outcome = await this.finalizePhotoFeedClaim(event, key, entry, candidate);
+        if (outcome === "committed") return;
+        if (outcome === "retry") continue;
+        existingClaim = await this.readPhotoFeedClaim(event, key, entryKey);
+        if (!existingClaim || !samePhotoFeedClaim(existingClaim.claim, candidate)) continue;
+      } else {
+        const outcome = await this.finalizePhotoFeedClaim(
+          event,
+          key,
+          entry,
+          existingClaim.claim
+        );
+        if (outcome === "committed") return;
+        if (outcome === "retry") continue;
       }
 
-      const outcome = await this.finalizePhotoFeedClaim(
-        event,
-        key,
-        entry,
-        existingClaim.claim
-      );
-      if (outcome === "committed") return;
-      if (outcome === "retry") continue;
-
       const current = await this.readPhotoFeedHead(event);
       await this.ensurePhotoFeedHeadCommitted(event, current.head);
       if (await this.hasValidPhotoFeedMarker(event, key, entryKey)) return;
       const replacement = this.photoFeedClaimForHead(event, entryKey, current.head);
-      await this.state.compareAndSwap(
+      const replaced = await this.state.compareAndSwap(
         photoFeedClaimKey(event, key),
         existingClaim.etag,
         JSON.stringify(replacement),
         jsonWriteOptions()
       );
+      if (!replaced) continue;
+      const replacementOutcome = await this.finalizePhotoFeedClaim(
+        event,
+        key,
+        entry,
+        replacement
+      );
+      if (replacementOutcome === "committed") return;
     }
     throw new Error("photo feed append contention exceeded retry budget");
   }
@@ -1669,6 +1682,14 @@ function samePhotoFeedNode(left: PrivatePhotoFeedNode, right: PrivatePhotoFeedNo
     && left.previousNodeKey === right.previousNodeKey;
 }
 
+function samePhotoFeedClaim(left: PrivatePhotoFeedClaim, right: PrivatePhotoFeedClaim): boolean {
+  return left.version === right.version
+    && left.entryKey === right.entryKey
+    && left.nodeKey === right.nodeKey
+    && left.sequence === right.sequence
+    && left.previousNodeKey === right.previousNodeKey;
+}
+
 function encodePhotoFeedCursor(event: string, sequence: number): string {
   return `pf1.${base64url(JSON.stringify({ version: PHOTO_FEED_VERSION, event, sequence }))}`;
 }

From b9467c772705b025d9f7807c74d5d7c03889b27b Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:01:19 +0800
Subject: [PATCH 034/105] feat: retry queued photos automatically

---
 app/[event]/booth-session/outbox.ts           |  98 +++-
 .../booth-session/retry-policy.test.ts        |  97 ++++
 app/[event]/booth-session/retry-policy.ts     |  78 +++
 app/[event]/booth-session/session.test.ts     | 501 ++++++++++++++++++
 app/[event]/booth-session/session.ts          | 237 ++++++++-
 app/[event]/page.tsx                          |  53 +-
 6 files changed, 1047 insertions(+), 17 deletions(-)
 create mode 100644 app/[event]/booth-session/retry-policy.test.ts
 create mode 100644 app/[event]/booth-session/retry-policy.ts

diff --git a/app/[event]/booth-session/outbox.ts b/app/[event]/booth-session/outbox.ts
index 95a023f..953c976 100644
--- a/app/[event]/booth-session/outbox.ts
+++ b/app/[event]/booth-session/outbox.ts
@@ -1,4 +1,5 @@
 import type { CaptureMetadata } from "../../upload-contract";
+import type { UploadErrorClass } from "./retry-policy";
 
 export type OutboxItem = {
   id: string;
@@ -8,6 +9,8 @@ export type OutboxItem = {
   attempts: number;
   lastError?: string;
   nextAttemptAt?: number;
+  failureKind?: "retryable" | "permanent" | "auth";
+  errorClass?: UploadErrorClass;
   /** Optional so rows saved by earlier Booth versions remain readable. */
   metadata?: CaptureMetadata;
   /** Reserved for the operator rehearsal flow; durable rows retain it verbatim. */
@@ -19,10 +22,14 @@ export interface OutboxStore {
   list(event: string): Promise<OutboxItem[]>;
   put(item: OutboxItem): Promise<void>;
   remove(id: string): Promise<void>;
+  acquireLease(event: string, ownerId: string, now: number, ttlMs: number): Promise<boolean>;
+  renewLease(event: string, ownerId: string, now: number, ttlMs: number): Promise<boolean>;
+  releaseLease(event: string, ownerId: string): Promise<void>;
 }
 
 export class MemoryOutboxStore implements OutboxStore {
   private readonly items = new Map<string, OutboxItem>();
+  private readonly leases = new Map<string, { ownerId: string; expiresAt: number }>();
 
   isDurable() {
     return false;
@@ -41,8 +48,32 @@ export class MemoryOutboxStore implements OutboxStore {
   async remove(id: string) {
     this.items.delete(id);
   }
+
+  async acquireLease(event: string, ownerId: string, now: number, ttlMs: number) {
+    const lease = this.leases.get(event);
+    if (lease && lease.ownerId !== ownerId && lease.expiresAt > now) return false;
+    this.leases.set(event, { ownerId, expiresAt: now + ttlMs });
+    return true;
+  }
+
+  async renewLease(event: string, ownerId: string, now: number, ttlMs: number) {
+    const lease = this.leases.get(event);
+    if (!lease || lease.ownerId !== ownerId) return false;
+    this.leases.set(event, { ownerId, expiresAt: now + ttlMs });
+    return true;
+  }
+
+  async releaseLease(event: string, ownerId: string) {
+    if (this.leases.get(event)?.ownerId === ownerId) this.leases.delete(event);
+  }
 }
 
+type LeaseRecord = {
+  event: string;
+  ownerId: string;
+  expiresAt: number;
+};
+
 class IndexedDbOutboxStore implements OutboxStore {
   private dbPromise: Promise<IDBDatabase>;
 
@@ -52,11 +83,14 @@ class IndexedDbOutboxStore implements OutboxStore {
 
   constructor(indexedDB: IDBFactory) {
     this.dbPromise = new Promise((resolve, reject) => {
-      const request = indexedDB.open("ipad-webbooth", 1);
+      const request = indexedDB.open("ipad-webbooth", 2);
       request.onupgradeneeded = () => {
         if (!request.result.objectStoreNames.contains("photo-outbox")) {
           request.result.createObjectStore("photo-outbox", { keyPath: "id" });
         }
+        if (!request.result.objectStoreNames.contains("photo-outbox-leases")) {
+          request.result.createObjectStore("photo-outbox-leases", { keyPath: "event" });
+        }
       };
       request.onsuccess = () => resolve(request.result);
       request.onerror = () => reject(request.error ?? new Error("Could not open photo outbox"));
@@ -92,6 +126,56 @@ class IndexedDbOutboxStore implements OutboxStore {
   async remove(id: string) {
     await this.request("readwrite", (store) => store.delete(id));
   }
+
+  private async leaseTransaction(
+    event: string,
+    update: (current: LeaseRecord | undefined, store: IDBObjectStore) => boolean
+  ) {
+    const db = await this.dbPromise;
+    return new Promise<boolean>((resolve, reject) => {
+      const transaction = db.transaction("photo-outbox-leases", "readwrite");
+      const store = transaction.objectStore("photo-outbox-leases");
+      const request = store.get(event);
+      let result = false;
+      request.onsuccess = () => {
+        result = update(request.result as LeaseRecord | undefined, store);
+      };
+      request.onerror = () => {
+        transaction.abort();
+        reject(request.error ?? new Error("Photo outbox lease request failed"));
+      };
+      transaction.oncomplete = () => resolve(result);
+      transaction.onerror = () => reject(
+        transaction.error ?? new Error("Photo outbox lease transaction failed")
+      );
+      transaction.onabort = () => reject(
+        transaction.error ?? new Error("Photo outbox lease transaction aborted")
+      );
+    });
+  }
+
+  acquireLease(event: string, ownerId: string, now: number, ttlMs: number) {
+    return this.leaseTransaction(event, (current, store) => {
+      if (current && current.ownerId !== ownerId && current.expiresAt > now) return false;
+      store.put({ event, ownerId, expiresAt: now + ttlMs } satisfies LeaseRecord);
+      return true;
+    });
+  }
+
+  renewLease(event: string, ownerId: string, now: number, ttlMs: number) {
+    return this.leaseTransaction(event, (current, store) => {
+      if (!current || current.ownerId !== ownerId) return false;
+      store.put({ event, ownerId, expiresAt: now + ttlMs } satisfies LeaseRecord);
+      return true;
+    });
+  }
+
+  async releaseLease(event: string, ownerId: string) {
+    await this.leaseTransaction(event, (current, store) => {
+      if (current?.ownerId === ownerId) store.delete(event);
+      return current?.ownerId === ownerId;
+    });
+  }
 }
 
 /** Uses IndexedDB when available, but keeps the booth usable in private/locked-down browsers. */
@@ -128,5 +212,17 @@ export function createOutboxStore(
       await memory.remove(id);
       await fallback(() => durable.remove(id), () => Promise.resolve());
     },
+    acquireLease: (event, ownerId, now, ttlMs) => fallback(
+      () => durable.acquireLease(event, ownerId, now, ttlMs),
+      () => memory.acquireLease(event, ownerId, now, ttlMs)
+    ),
+    renewLease: (event, ownerId, now, ttlMs) => fallback(
+      () => durable.renewLease(event, ownerId, now, ttlMs),
+      () => memory.renewLease(event, ownerId, now, ttlMs)
+    ),
+    releaseLease: (event, ownerId) => fallback(
+      () => durable.releaseLease(event, ownerId),
+      () => memory.releaseLease(event, ownerId)
+    ),
   };
 }
diff --git a/app/[event]/booth-session/retry-policy.test.ts b/app/[event]/booth-session/retry-policy.test.ts
new file mode 100644
index 0000000..3c6f929
--- /dev/null
+++ b/app/[event]/booth-session/retry-policy.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import { HttpUploadError, classifyUploadFailure } from "./retry-policy";
+
+describe("upload retry policy", () => {
+  test("retries network, timeout, throttling, and server failures", () => {
+    for (const status of [408, 425, 429, 500, 503]) {
+      expect(
+        classifyUploadFailure(
+          new HttpUploadError(status, null, status >= 500 ? "server" : "timeout"),
+          1,
+          1_000,
+          () => 0.5
+        ).kind
+      ).toBe("retryable");
+    }
+
+    expect(
+      classifyUploadFailure(new TypeError("fetch failed"), 1, 1_000, () => 0.5)
+    ).toEqual({ kind: "retryable", delayMs: 1_000, errorClass: "network" });
+  });
+
+  test("requires new auth for 401 and permanently blocks invalid requests", () => {
+    expect(
+      classifyUploadFailure(new HttpUploadError(401, null, "auth"), 1, 0, () => 0.5)
+    ).toEqual({ kind: "auth-required", errorClass: "auth" });
+
+    for (const status of [400, 403, 413, 415]) {
+      expect(
+        classifyUploadFailure(
+          new HttpUploadError(status, null, "payload"),
+          1,
+          0,
+          () => 0.5
+        )
+      ).toEqual({ kind: "permanent", errorClass: "payload" });
+    }
+  });
+
+  test("uses deterministic jittered exponential backoff", () => {
+    expect(
+      classifyUploadFailure(new TypeError("offline"), 1, 0, () => 0)
+    ).toMatchObject({ kind: "retryable", delayMs: 500 });
+    expect(
+      classifyUploadFailure(new TypeError("offline"), 3, 0, () => 0.5)
+    ).toMatchObject({ kind: "retryable", delayMs: 4_000 });
+    expect(
+      classifyUploadFailure(new TypeError("offline"), 10, 0, () => 1)
+    ).toMatchObject({ kind: "retryable", delayMs: 30_000 });
+  });
+
+  test("honors later Retry-After delta seconds and caps it", () => {
+    expect(
+      classifyUploadFailure(new HttpUploadError(429, "12", "timeout"), 1, 1_000, () => 0)
+    ).toMatchObject({ kind: "retryable", delayMs: 12_000 });
+    expect(
+      classifyUploadFailure(new HttpUploadError(503, "120", "server"), 1, 1_000, () => 0)
+    ).toMatchObject({ kind: "retryable", delayMs: 30_000 });
+  });
+
+  test("honors later Retry-After HTTP dates and ignores invalid or past dates", () => {
+    const now = Date.parse("2026-07-24T00:00:00.000Z");
+    expect(
+      classifyUploadFailure(
+        new HttpUploadError(503, "Fri, 24 Jul 2026 00:00:07 GMT", "server"),
+        1,
+        now,
+        () => 0
+      )
+    ).toMatchObject({ kind: "retryable", delayMs: 7_000 });
+    expect(
+      classifyUploadFailure(
+        new HttpUploadError(503, "not a date", "server"),
+        1,
+        now,
+        () => 0
+      )
+    ).toMatchObject({ kind: "retryable", delayMs: 500 });
+    expect(
+      classifyUploadFailure(
+        new HttpUploadError(503, "Thu, 23 Jul 2026 23:59:00 GMT", "server"),
+        1,
+        now,
+        () => 0
+      )
+    ).toMatchObject({ kind: "retryable", delayMs: 500 });
+  });
+
+  test("classifies unrecognized failures as permanently unknown", () => {
+    expect(classifyUploadFailure("broken", 1, 0, () => 0.5)).toEqual({
+      kind: "permanent",
+      errorClass: "unknown",
+    });
+    expect(
+      classifyUploadFailure(new HttpUploadError(409, null, "unknown"), 1, 0, () => 0.5)
+    ).toEqual({ kind: "permanent", errorClass: "unknown" });
+  });
+});
diff --git a/app/[event]/booth-session/retry-policy.ts b/app/[event]/booth-session/retry-policy.ts
new file mode 100644
index 0000000..9302c35
--- /dev/null
+++ b/app/[event]/booth-session/retry-policy.ts
@@ -0,0 +1,78 @@
+export type UploadErrorClass =
+  | "network"
+  | "timeout"
+  | "auth"
+  | "payload"
+  | "server"
+  | "unknown";
+
+export class HttpUploadError extends Error {
+  constructor(
+    readonly status: number,
+    readonly retryAfter: string | null,
+    readonly errorClass: UploadErrorClass
+  ) {
+    super(`upload failed with status ${status}`);
+    this.name = "HttpUploadError";
+  }
+}
+
+export type RetryDisposition =
+  | { kind: "retryable"; delayMs: number; errorClass: UploadErrorClass }
+  | { kind: "auth-required"; errorClass: "auth" }
+  | { kind: "permanent"; errorClass: UploadErrorClass };
+
+const MAX_RETRY_DELAY_MS = 30_000;
+
+function retryAfterDelay(value: string | null, now: number) {
+  if (value === null) return 0;
+  const trimmed = value.trim();
+  if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+    return Math.max(0, Number(trimmed) * 1_000);
+  }
+  const at = Date.parse(trimmed);
+  return Number.isFinite(at) ? Math.max(0, at - now) : 0;
+}
+
+function retryable(
+  errorClass: UploadErrorClass,
+  attempt: number,
+  now: number,
+  random: () => number,
+  retryAfter: string | null
+): RetryDisposition {
+  const exponent = Math.max(0, attempt - 1);
+  const jitter = 0.5 + Math.min(1, Math.max(0, random()));
+  const backoff = 1_000 * 2 ** exponent * jitter;
+  const delayMs = Math.min(
+    MAX_RETRY_DELAY_MS,
+    Math.max(backoff, retryAfterDelay(retryAfter, now))
+  );
+  return { kind: "retryable", delayMs, errorClass };
+}
+
+export function classifyUploadFailure(
+  error: unknown,
+  attempt: number,
+  now: number,
+  random: () => number = Math.random
+): RetryDisposition {
+  if (error instanceof TypeError) {
+    return retryable("network", attempt, now, random, null);
+  }
+  if (!(error instanceof HttpUploadError)) {
+    return { kind: "permanent", errorClass: "unknown" };
+  }
+  if (error.status === 401) {
+    return { kind: "auth-required", errorClass: "auth" };
+  }
+  if (
+    error.status === 408 ||
+    error.status === 425 ||
+    error.status === 429 ||
+    error.status >= 500
+  ) {
+    return retryable(error.errorClass, attempt, now, random, error.retryAfter);
+  }
+  return { kind: "permanent", errorClass: error.errorClass };
+}
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index bff439d..a8dfa8e 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -2,10 +2,115 @@ import { describe, expect, test } from "bun:test";
 import { createOutboxStore, MemoryOutboxStore, type OutboxItem } from "./outbox";
 import { BoothSession, runCaptureSequence } from "./session";
 import { outboxUploadHeaders } from "./upload";
+import { HttpUploadError } from "./retry-policy";
 
 const photo = (name: string) => new Blob([name], { type: "image/jpeg" });
 const text = (blob: Blob) => blob.text();
 
+class ManualScheduler {
+  private nextId = 0;
+  readonly timers = new Map<number, { callback: () => void; delayMs: number }>();
+
+  setTimer = (callback: () => void, delayMs: number) => {
+    const id = ++this.nextId;
+    this.timers.set(id, { callback, delayMs });
+    return id;
+  };
+
+  clearTimer = (id: unknown) => {
+    this.timers.delete(id as number);
+  };
+
+  runNext() {
+    const next = [...this.timers.entries()].sort((a, b) => a[0] - b[0])[0];
+    if (!next) throw new Error("No scheduled BoothSession wake");
+    this.timers.delete(next[0]);
+    next[1].callback();
+    return next[1].delayMs;
+  }
+}
+
+function versionOneIndexedDb(rows: OutboxItem[]) {
+  const names = new Set(["photo-outbox"]);
+  const openedVersions: number[] = [];
+  const createdStores: string[] = [];
+  const oldOutboxWrites: string[] = [];
+
+  type FakeRequest<T> = {
+    result: T;
+    error: Error | null;
+    onsuccess: ((event: Event) => void) | null;
+    onerror: ((event: Event) => void) | null;
+  };
+  type FakeTransaction = {
+    oncomplete: ((event: Event) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    onabort: ((event: Event) => void) | null;
+    objectStore: (name: string) => IDBObjectStore;
+  };
+
+  const transaction = (): IDBTransaction => {
+    const fake: FakeTransaction = {
+      oncomplete: null,
+      onerror: null,
+      onabort: null,
+      objectStore: () => ({
+        getAll: () => {
+          const request: FakeRequest<OutboxItem[]> = {
+            result: rows,
+            error: null,
+            onsuccess: null,
+            onerror: null,
+          };
+          queueMicrotask(() => {
+            request.onsuccess?.(new Event("success"));
+            queueMicrotask(() => fake.oncomplete?.(new Event("complete")));
+          });
+          return request as unknown as IDBRequest<OutboxItem[]>;
+        },
+        put: () => {
+          oldOutboxWrites.push("put");
+          throw new Error("v1 rows must not be rewritten during upgrade");
+        },
+        delete: () => {
+          oldOutboxWrites.push("delete");
+          throw new Error("v1 rows must not be deleted during upgrade");
+        },
+      } as unknown as IDBObjectStore),
+    };
+    return fake as unknown as IDBTransaction;
+  };
+  const database = {
+    objectStoreNames: { contains: (name: string) => names.has(name) },
+    createObjectStore: (name: string) => {
+      createdStores.push(name);
+      names.add(name);
+      return {} as IDBObjectStore;
+    },
+    transaction: () => transaction(),
+  } as unknown as IDBDatabase;
+  const factory = {
+    open: (_name: string, version?: number) => {
+      openedVersions.push(version ?? 0);
+      const request = {
+        result: database,
+        error: null as Error | null,
+        onupgradeneeded: null as ((event: Event) => void) | null,
+        onsuccess: null as ((event: Event) => void) | null,
+        onerror: null as ((event: Event) => void) | null,
+        onblocked: null as ((event: Event) => void) | null,
+      };
+      queueMicrotask(() => {
+        request.onupgradeneeded?.(new Event("upgradeneeded"));
+        queueMicrotask(() => request.onsuccess?.(new Event("success")));
+      });
+      return request as unknown as IDBOpenDBRequest;
+    },
+  } as unknown as IDBFactory;
+
+  return { factory, openedVersions, createdStores, oldOutboxWrites };
+}
+
 describe("BoothSession outbox", () => {
   test("reserves strictly increasing FIFO order across concurrent durable puts", async () => {
     let releasePuts!: () => void;
@@ -287,6 +392,402 @@ describe("BoothSession outbox", () => {
     await store.remove(item.id);
     expect(await store.list("party")).toEqual([]);
   });
+
+  test("upgrades IndexedDB v1 by adding only the lease store without rewriting old rows", async () => {
+    const legacy = {
+      id: "legacy",
+      event: "party",
+      blob: photo("legacy"),
+      createdAt: 1,
+      attempts: 2,
+      lastError: "offline",
+    };
+    const fake = versionOneIndexedDb([legacy]);
+    const store = createOutboxStore(fake.factory);
+
+    expect(await store.list("party")).toEqual([legacy]);
+    expect(fake.openedVersions).toEqual([2]);
+    expect(fake.createdStores).toEqual(["photo-outbox-leases"]);
+    expect(fake.oldOutboxWrites).toEqual([]);
+  });
+
+  test("persists retry eligibility and failure classification across Session reload", async () => {
+    const store = new MemoryOutboxStore();
+    let now = 10_000;
+    const first = new BoothSession(
+      "party",
+      store,
+      async () => {
+        throw new HttpUploadError(503, null, "server");
+      },
+      () => {},
+      () => "018f0000-0000-4000-8000-000000000001",
+      () => now,
+      { random: () => 0.5 }
+    );
+    await first.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+    await first.process();
+
+    expect(await store.list("party")).toMatchObject([{
+      attempts: 1,
+      failureKind: "retryable",
+      errorClass: "server",
+      nextAttemptAt: 11_000,
+    }]);
+
+    const states: string[] = [];
+    const reloaded = new BoothSession(
+      "party",
+      store,
+      async () => ({ url: "/photo" }),
+      () => {},
+      undefined,
+      () => now
+    );
+    reloaded.subscribe((state) => states.push(`${state.status}:${state.error ?? ""}`));
+    await reloaded.recover();
+
+    expect(states.at(-1)).toBe("failed:upload failed with status 503");
+    expect(await store.list("party")).toMatchObject([{
+      failureKind: "retryable",
+      errorClass: "server",
+      nextAttemptAt: 11_000,
+    }]);
+  });
+
+  test("the oldest blocked item prevents later uploads until manual retry", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "oldest",
+      event: "party",
+      blob: photo("oldest"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "invalid payload",
+      failureKind: "permanent",
+      errorClass: "payload",
+    });
+    await store.put({
+      id: "later",
+      event: "party",
+      blob: photo("later"),
+      createdAt: 2,
+      attempts: 0,
+    });
+    const uploads: string[] = [];
+    const session = new BoothSession("party", store, async (item) => {
+      uploads.push(await text(item.blob));
+      return { url: "/photo" };
+    });
+
+    await session.process();
+    expect(uploads).toEqual([]);
+    expect((await store.list("party")).map((item) => item.id)).toEqual(["oldest", "later"]);
+
+    await session.retry();
+    expect(uploads).toEqual(["oldest", "later"]);
+    expect(await store.list("party")).toEqual([]);
+  });
+
+  test("connectivity and foreground wakes immediately reconsider an oldest retryable item", async () => {
+    for (const reason of ["connectivity", "foreground"] as const) {
+      const store = new MemoryOutboxStore();
+      await store.put({
+        id: `oldest-${reason}`,
+        event: "party",
+        blob: photo(reason),
+        createdAt: 1,
+        attempts: 1,
+        lastError: "offline",
+        nextAttemptAt: 50_000,
+        failureKind: "retryable",
+        errorClass: "network",
+      });
+      const uploads: string[] = [];
+      const session = new BoothSession(
+        "party",
+        store,
+        async (item) => {
+          uploads.push(await text(item.blob));
+          return { url: "/photo" };
+        },
+        () => {},
+        undefined,
+        () => 10_000
+      );
+
+      await session.start();
+      expect(uploads).toEqual([]);
+      await session.reconsider(reason);
+      expect(uploads).toEqual([reason]);
+      await session.stop();
+    }
+  });
+
+  test("automatic wakes retry the oldest retryable item when it becomes eligible", async () => {
+    const store = new MemoryOutboxStore();
+    const scheduler = new ManualScheduler();
+    let now = 1_000;
+    let uploads = 0;
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploads++;
+        if (uploads === 1) throw new TypeError("offline");
+        return { url: "/photo" };
+      },
+      () => {},
+      () => "018f0000-0000-4000-8000-000000000001",
+      () => now,
+      {
+        random: () => 0.5,
+        setTimer: scheduler.setTimer,
+        clearTimer: scheduler.clearTimer,
+        leaseTtlMs: 60_000,
+      }
+    );
+    await session.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await session.start();
+    expect(uploads).toBe(1);
+    expect([...scheduler.timers.values()].map((timer) => timer.delayMs)).toContain(1_000);
+
+    now = 2_000;
+    scheduler.runNext();
+    await session.process();
+
+    expect(uploads).toBe(2);
+    expect(await store.list("party")).toEqual([]);
+    await session.stop();
+  });
+
+  test("permanent and auth failures do not automatically restart on environmental wakes", async () => {
+    for (const failureKind of ["permanent", "auth"] as const) {
+      const store = new MemoryOutboxStore();
+      await store.put({
+        id: failureKind,
+        event: "party",
+        blob: photo(failureKind),
+        createdAt: 1,
+        attempts: 1,
+        lastError: failureKind,
+        failureKind,
+        errorClass: failureKind === "auth" ? "auth" : "payload",
+      });
+      let uploads = 0;
+      const session = new BoothSession("party", store, async () => {
+        uploads++;
+        return { url: "/photo" };
+      });
+
+      await session.start();
+      await session.reconsider("connectivity");
+      await session.reconsider("foreground");
+      expect(uploads).toBe(0);
+      await session.stop();
+    }
+  });
+
+  test("persists auth failure before notifying the credential owner", async () => {
+    const store = new MemoryOutboxStore();
+    let persistedBeforeCallback = false;
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        throw new HttpUploadError(401, null, "auth");
+      },
+      () => {},
+      () => "018f0000-0000-4000-8000-000000000001",
+      () => 1_000,
+      {
+        onAuthRequired: async () => {
+          const [item] = await store.list("party");
+          persistedBeforeCallback =
+            item.failureKind === "auth" && item.errorClass === "auth";
+        },
+      }
+    );
+    await session.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await session.process();
+
+    expect(persistedBeforeCallback).toBe(true);
+    expect(await store.list("party")).toMatchObject([{
+      attempts: 1,
+      failureKind: "auth",
+      errorClass: "auth",
+    }]);
+  });
+
+  test("one Event lease prevents two Sessions from draining simultaneously", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "one",
+      event: "party",
+      blob: photo("one"),
+      createdAt: 1,
+      attempts: 0,
+    });
+    let releaseUpload!: () => void;
+    const uploadBarrier = new Promise<void>((resolve) => {
+      releaseUpload = resolve;
+    });
+    let firstUploads = 0;
+    let secondUploads = 0;
+    let firstStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      firstStarted = resolve;
+    });
+    const first = new BoothSession(
+      "party",
+      store,
+      async () => {
+        firstUploads++;
+        firstStarted();
+        await uploadBarrier;
+        return { url: "/photo" };
+      },
+      () => {},
+      undefined,
+      () => 1_000,
+      { ownerId: "first" }
+    );
+    const second = new BoothSession(
+      "party",
+      store,
+      async () => {
+        secondUploads++;
+        return { url: "/photo" };
+      },
+      () => {},
+      undefined,
+      () => 1_000,
+      { ownerId: "second" }
+    );
+
+    const firstDrain = first.process();
+    await started;
+    await second.process();
+    expect(firstUploads).toBe(1);
+    expect(secondUploads).toBe(0);
+
+    releaseUpload();
+    await firstDrain;
+    await Promise.all([first.stop(), second.stop()]);
+  });
+
+  test("renews a long-running direct drain lease before another owner can acquire it", async () => {
+    const store = new MemoryOutboxStore();
+    const scheduler = new ManualScheduler();
+    let now = 0;
+    let releaseUpload!: () => void;
+    const uploadBlocked = new Promise<void>((resolve) => {
+      releaseUpload = resolve;
+    });
+    let uploadStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      uploadStarted = resolve;
+    });
+    await store.put({
+      id: "one",
+      event: "party",
+      blob: photo("one"),
+      createdAt: 1,
+      attempts: 0,
+    });
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploadStarted();
+        await uploadBlocked;
+        return { url: "/photo" };
+      },
+      () => {},
+      undefined,
+      () => now,
+      {
+        ownerId: "first",
+        leaseTtlMs: 100,
+        setTimer: scheduler.setTimer,
+        clearTimer: scheduler.clearTimer,
+      }
+    );
+
+    const drain = session.process();
+    await started;
+    expect([...scheduler.timers.values()].map((timer) => timer.delayMs)).toContain(50);
+
+    now = 50;
+    scheduler.runNext();
+    await Promise.resolve();
+    await Promise.resolve();
+    now = 101;
+    expect(await store.acquireLease("party", "second", now, 100)).toBe(false);
+
+    releaseUpload();
+    await drain;
+  });
+
+  test("an expired lease can be acquired by another owner and Events stay independent", async () => {
+    const store = new MemoryOutboxStore();
+
+    expect(await store.acquireLease("party", "first", 1_000, 500)).toBe(true);
+    expect(await store.acquireLease("party", "second", 1_499, 500)).toBe(false);
+    expect(await store.acquireLease("other", "second", 1_499, 500)).toBe(true);
+    expect(await store.acquireLease("party", "second", 1_500, 500)).toBe(true);
+    expect(await store.renewLease("party", "first", 1_501, 500)).toBe(false);
+    await store.releaseLease("party", "first");
+    expect(await store.acquireLease("party", "third", 1_600, 500)).toBe(false);
+    await store.releaseLease("party", "second");
+    expect(await store.acquireLease("party", "third", 1_600, 500)).toBe(true);
+  });
+
+  test("stop clears scheduled work and releases only its own lease", async () => {
+    const store = new MemoryOutboxStore();
+    const scheduler = new ManualScheduler();
+    await store.put({
+      id: "one",
+      event: "party",
+      blob: photo("one"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "offline",
+      nextAttemptAt: 50_000,
+      failureKind: "retryable",
+      errorClass: "network",
+    });
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => ({ url: "/photo" }),
+      () => {},
+      undefined,
+      () => 1_000,
+      {
+        ownerId: "first",
+        setTimer: scheduler.setTimer,
+        clearTimer: scheduler.clearTimer,
+      }
+    );
+
+    await session.start();
+    expect(scheduler.timers.size).toBe(1);
+    expect(await store.acquireLease("party", "second", 1_000, 30_000)).toBe(false);
+
+    await session.stop();
+
+    expect(scheduler.timers.size).toBe(0);
+    expect(await store.acquireLease("party", "second", 1_000, 30_000)).toBe(true);
+  });
 });
 
 describe("runCaptureSequence", () => {
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index 020993e..3713537 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -1,5 +1,6 @@
 import type { OutboxItem, OutboxStore } from "./outbox";
 import type { CaptureMetadata } from "../../upload-contract";
+import { classifyUploadFailure } from "./retry-policy";
 
 export type UploadState = {
   status: "idle" | "uploading" | "failed";
@@ -17,11 +18,33 @@ export type EnqueueCaptureOptions = {
   rehearsalId?: string;
 };
 
+export type BoothSessionOptions = {
+  ownerId?: string;
+  leaseTtlMs?: number;
+  random?: () => number;
+  onAuthRequired?: () => void | Promise<void>;
+  setTimer?: (callback: () => void, delayMs: number) => unknown;
+  clearTimer?: (timer: unknown) => void;
+};
+
 export class BoothSession {
   private state: UploadState = { status: "idle", pendingCount: 0, error: null, durable: true };
   private processing: Promise<void> | null = null;
+  private wakeWork: Promise<void> | null = null;
   private lastCreatedAt = 0;
   private listeners = new Set<(state: UploadState) => void>();
+  private started = false;
+  private stopRequested = false;
+  private leaseHeld = false;
+  private leaseExpiresAt = 0;
+  private retryAt: number | null = null;
+  private timer: unknown = null;
+  private readonly ownerId: string;
+  private readonly leaseTtlMs: number;
+  private readonly random: () => number;
+  private readonly onAuthRequired: () => void | Promise<void>;
+  private readonly setTimer: (callback: () => void, delayMs: number) => unknown;
+  private readonly clearTimer: (timer: unknown) => void;
 
   constructor(
     private readonly event: string,
@@ -29,8 +52,16 @@ export class BoothSession {
     private readonly upload: Upload,
     private readonly onUploaded: (result: UploadResult) => void = () => {},
     private readonly makeId: () => string = () => crypto.randomUUID(),
-    private readonly now: () => number = Date.now
-  ) {}
+    private readonly now: () => number = Date.now,
+    options: BoothSessionOptions = {}
+  ) {
+    this.ownerId = options.ownerId ?? crypto.randomUUID();
+    this.leaseTtlMs = options.leaseTtlMs ?? 30_000;
+    this.random = options.random ?? Math.random;
+    this.onAuthRequired = options.onAuthRequired ?? (() => {});
+    this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+    this.clearTimer = options.clearTimer ?? ((timer) => clearTimeout(timer as ReturnType<typeof setTimeout>));
+  }
 
   subscribe(listener: (state: UploadState) => void) {
     this.listeners.add(listener);
@@ -60,6 +91,36 @@ export class BoothSession {
     });
   }
 
+  start() {
+    this.started = true;
+    this.stopRequested = false;
+    return this.process();
+  }
+
+  async stop() {
+    this.started = false;
+    this.stopRequested = true;
+    this.cancelTimer();
+    const wakeWork = this.wakeWork;
+    const processing = this.processing;
+    await Promise.allSettled([
+      ...(wakeWork ? [wakeWork] : []),
+      ...(processing ? [processing] : []),
+    ]);
+    await this.releaseLease();
+  }
+
+  async reconsider(_reason: "connectivity" | "foreground") {
+    if (!this.started || this.stopRequested) return;
+    const pending = await this.store.list(this.event);
+    const first = pending[0];
+    if (!first || first.failureKind !== "retryable") return;
+    await this.store.put({ ...first, nextAttemptAt: this.now() });
+    this.retryAt = this.now();
+    this.cancelTimer();
+    await this.process();
+  }
+
   /** The capture adapter owns camera/file decoding; the session owns durable handoff. */
   async enqueueCapture(
     capture: (signal?: AbortSignal) => Promise<Blob>,
@@ -90,26 +151,73 @@ export class BoothSession {
       error: this.state.status === "failed" ? this.state.error : null,
       durable: this.store.isDurable(),
     });
+    if (this.started && !this.stopRequested) void this.process();
     return item;
   }
 
   process() {
+    if (this.stopRequested) return Promise.resolve();
     if (!this.processing) {
-      this.processing = this.drain().finally(() => {
-        this.processing = null;
+      let run!: Promise<void>;
+      run = this.drain().finally(async () => {
+        if (!this.started) await this.releaseLease();
+        if (this.processing === run) this.processing = null;
       });
+      this.processing = run;
     }
     return this.processing;
   }
 
-  retry() {
-    return this.process();
+  async retry() {
+    if (this.stopRequested) return;
+    const pending = await this.store.list(this.event);
+    const first = pending[0];
+    if (first?.lastError || first?.failureKind) {
+      const {
+        lastError: _lastError,
+        nextAttemptAt: _nextAttemptAt,
+        failureKind: _failureKind,
+        errorClass: _errorClass,
+        ...ready
+      } = first;
+      await this.store.put(ready);
+    }
+    this.retryAt = null;
+    this.cancelTimer();
+    await this.process();
   }
 
   private async drain() {
+    if (!await this.ensureLease()) return;
     let pending = await this.store.list(this.event);
     while (pending.length > 0) {
       const item = pending[0];
+      if (item.failureKind === "retryable" && (item.nextAttemptAt ?? 0) > this.now()) {
+        this.retryAt = item.nextAttemptAt ?? null;
+        this.publish({
+          status: "failed",
+          pendingCount: pending.length,
+          error: item.lastError ?? null,
+          durable: this.store.isDurable(),
+        });
+        this.scheduleWake();
+        return;
+      }
+      if (
+        item.failureKind === "permanent" ||
+        item.failureKind === "auth" ||
+        (item.lastError && !item.failureKind)
+      ) {
+        this.retryAt = null;
+        this.publish({
+          status: "failed",
+          pendingCount: pending.length,
+          error: item.lastError ?? null,
+          durable: this.store.isDurable(),
+        });
+        this.scheduleWake();
+        return;
+      }
       this.publish({
         status: "uploading",
         pendingCount: pending.length,
@@ -122,13 +230,34 @@ export class BoothSession {
         await this.store.remove(item.id);
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        await this.store.put({ ...item, attempts: item.attempts + 1, lastError: message });
+        const attempt = item.attempts + 1;
+        const disposition = classifyUploadFailure(error, attempt, this.now(), this.random);
+        const failed: OutboxItem = {
+          ...item,
+          attempts: attempt,
+          lastError: message,
+          failureKind: disposition.kind === "auth-required" ? "auth" : disposition.kind,
+          errorClass: disposition.errorClass,
+          ...(disposition.kind === "retryable"
+            ? { nextAttemptAt: this.now() + disposition.delayMs }
+            : {}),
+        };
+        await this.store.put(failed);
+        this.retryAt = disposition.kind === "retryable" ? failed.nextAttemptAt ?? null : null;
         this.publish({
           status: "failed",
           pendingCount: pending.length,
           error: message,
           durable: this.store.isDurable(),
         });
+        if (disposition.kind === "auth-required") {
+          try {
+            await this.onAuthRequired();
+          } catch {
+            // Credential UI cannot affect the already-persisted queue state.
+          }
+        }
+        this.scheduleWake();
         return;
       }
 
@@ -141,6 +270,8 @@ export class BoothSession {
         // The next state publication still reconciles the Booth UI.
       }
 
+      if (this.stopRequested) return;
+
       try {
         pending = await this.store.list(this.event);
       } catch (error) {
@@ -159,6 +290,98 @@ export class BoothSession {
         durable: this.store.isDurable(),
       });
     }
+    this.retryAt = null;
+    this.scheduleWake();
+  }
+
+  private async ensureLease() {
+    if (this.leaseHeld) {
+      if (this.now() < this.leaseRenewAt()) return true;
+      if (await this.renewLease()) return true;
+      this.leaseHeld = false;
+    }
+    const acquired = await this.store.acquireLease(
+      this.event,
+      this.ownerId,
+      this.now(),
+      this.leaseTtlMs
+    );
+    if (!acquired) {
+      if (this.started) {
+        this.retryAt = this.now() + this.leaseTtlMs;
+        this.scheduleWake();
+      }
+      return false;
+    }
+    this.leaseHeld = true;
+    this.leaseExpiresAt = this.now() + this.leaseTtlMs;
+    this.scheduleWake();
+    return true;
+  }
+
+  private leaseRenewAt() {
+    return this.leaseExpiresAt - Math.max(1, Math.floor(this.leaseTtlMs / 2));
+  }
+
+  private async renewLease() {
+    if (!this.leaseHeld) return false;
+    const renewed = await this.store.renewLease(
+      this.event,
+      this.ownerId,
+      this.now(),
+      this.leaseTtlMs
+    );
+    if (renewed) this.leaseExpiresAt = this.now() + this.leaseTtlMs;
+    return renewed;
+  }
+
+  private async releaseLease() {
+    if (!this.leaseHeld) return;
+    this.leaseHeld = false;
+    this.leaseExpiresAt = 0;
+    if (!this.started) this.cancelTimer();
+    await this.store.releaseLease(this.event, this.ownerId);
+  }
+
+  private cancelTimer() {
+    if (this.timer === null) return;
+    this.clearTimer(this.timer);
+    this.timer = null;
+  }
+
+  private scheduleWake() {
+    if (this.stopRequested) return;
+    const targets = [
+      ...(this.leaseHeld ? [this.leaseRenewAt()] : []),
+      ...(this.started && this.retryAt !== null ? [this.retryAt] : []),
+    ];
+    if (targets.length === 0) return;
+    const wakeAt = Math.min(...targets);
+    this.cancelTimer();
+    this.timer = this.setTimer(() => {
+      this.timer = null;
+      let work!: Promise<void>;
+      work = this.handleWake().finally(() => {
+        if (this.wakeWork === work) this.wakeWork = null;
+      });
+      this.wakeWork = work;
+    }, Math.max(0, wakeAt - this.now()));
+  }
+
+  private async handleWake() {
+    if (this.stopRequested) return;
+    if (this.leaseHeld && this.now() >= this.leaseRenewAt()) {
+      if (!await this.renewLease()) this.leaseHeld = false;
+    }
+    if (!this.started || this.stopRequested) {
+      if (this.leaseHeld && this.processing) this.scheduleWake();
+      return;
+    }
+    if (!this.leaseHeld || (this.retryAt !== null && this.now() >= this.retryAt)) {
+      if (this.retryAt !== null && this.now() >= this.retryAt) this.retryAt = null;
+      await this.process();
+    }
+    this.scheduleWake();
   }
 }
 
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index dc84da0..4c63256 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -7,9 +7,18 @@ import { TEMPLATES, availableTemplates, composite } from "../templates";
 import { createOutboxStore, type OutboxItem } from "./booth-session/outbox";
 import { BoothSession, runCaptureSequence, type UploadState } from "./booth-session/session";
 import { outboxUploadHeaders } from "./booth-session/upload";
+import { HttpUploadError, type UploadErrorClass } from "./booth-session/retry-policy";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
 
+function uploadErrorClass(status: number): UploadErrorClass {
+  if (status === 401) return "auth";
+  if (status === 408 || status === 425 || status === 429) return "timeout";
+  if (status >= 500) return "server";
+  if (status === 400 || status === 403 || status === 413 || status === 415) return "payload";
+  return "unknown";
+}
+
 export default function Booth() {
   const { event } = useParams<{ event: string }>();
   const videoRef = useRef<HTMLVideoElement>(null);
@@ -123,32 +132,58 @@ export default function Booth() {
         },
         body: item.blob,
       });
-      if (res.status === 401) {
-        localStorage.removeItem(storageKey);
-        keyRef.current = "";
-        throw new Error("Wrong booth key — tap Retry to re-enter it");
+      if (!res.ok) {
+        throw new HttpUploadError(
+          res.status,
+          res.headers.get("retry-after"),
+          uploadErrorClass(res.status)
+        );
       }
-      if (!res.ok) throw new Error(`Upload failed (${res.status}) — tap Retry`);
       return res.json() as Promise<{ url: string; key?: string; duplicate?: boolean }>;
     },
-    [event, storageKey]
+    [event]
   );
 
   useEffect(() => {
+    let active = true;
     const session = new BoothSession(
       event,
       createOutboxStore(),
       uploadOne,
-      ({ url }) => setLastUrl(url)
+      ({ url }) => setLastUrl(url),
+      undefined,
+      undefined,
+      {
+        onAuthRequired: () => {
+          // Keep the existing credential lifecycle: clear the rejected Booth
+          // Key and let the retained manual Retry control prompt for a new one.
+          localStorage.removeItem(storageKey);
+          keyRef.current = "";
+        },
+      }
     );
     sessionRef.current = session;
     const unsubscribe = session.subscribe(setUploadState);
-    void session.recover().then(() => session.process());
+    const reconsiderConnectivity = () => void session.reconsider("connectivity");
+    const reconsiderForeground = () => {
+      if (document.visibilityState === "visible") void session.reconsider("foreground");
+    };
+    window.addEventListener("online", reconsiderConnectivity);
+    document.addEventListener("visibilitychange", reconsiderForeground);
+    // Task 4 will add strict preflight. Until then, recovery plus the existing
+    // Booth Key lifecycle is the only available start condition.
+    void session.recover().then(() => {
+      if (active) void session.start();
+    });
     return () => {
+      active = false;
       unsubscribe();
+      window.removeEventListener("online", reconsiderConnectivity);
+      document.removeEventListener("visibilitychange", reconsiderForeground);
       if (sessionRef.current === session) sessionRef.current = null;
+      void session.stop();
     };
-  }, [event, uploadOne]);
+  }, [event, storageKey, uploadOne]);
 
   const retryUpload = useCallback(() => {
     if (!uploadState.pendingCount) return;

From f8144e3702a1dfb8ba92051f147bc94446115dc4 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:13:16 +0800
Subject: [PATCH 035/105] fix: fence queued photo retries

---
 app/[event]/booth-session/outbox.ts       |  80 ++++++++
 app/[event]/booth-session/session.test.ts | 218 ++++++++++++++++++++++
 app/[event]/booth-session/session.ts      | 154 ++++++++++-----
 3 files changed, 403 insertions(+), 49 deletions(-)

diff --git a/app/[event]/booth-session/outbox.ts b/app/[event]/booth-session/outbox.ts
index 953c976..890c988 100644
--- a/app/[event]/booth-session/outbox.ts
+++ b/app/[event]/booth-session/outbox.ts
@@ -25,6 +25,7 @@ export interface OutboxStore {
   acquireLease(event: string, ownerId: string, now: number, ttlMs: number): Promise<boolean>;
   renewLease(event: string, ownerId: string, now: number, ttlMs: number): Promise<boolean>;
   releaseLease(event: string, ownerId: string): Promise<void>;
+  markFailure(item: OutboxItem, ownerId: string, now: number): Promise<boolean>;
 }
 
 export class MemoryOutboxStore implements OutboxStore {
@@ -66,6 +67,20 @@ export class MemoryOutboxStore implements OutboxStore {
   async releaseLease(event: string, ownerId: string) {
     if (this.leases.get(event)?.ownerId === ownerId) this.leases.delete(event);
   }
+
+  async markFailure(item: OutboxItem, ownerId: string, now: number) {
+    const lease = this.leases.get(item.event);
+    const current = this.items.get(item.id);
+    if (
+      !lease ||
+      lease.ownerId !== ownerId ||
+      lease.expiresAt <= now ||
+      !current ||
+      current.event !== item.event
+    ) return false;
+    this.items.set(item.id, item);
+    return true;
+  }
 }
 
 type LeaseRecord = {
@@ -176,6 +191,60 @@ class IndexedDbOutboxStore implements OutboxStore {
       return current?.ownerId === ownerId;
     });
   }
+
+  private async failureTransaction(item: OutboxItem, ownerId: string, now: number) {
+    const db = await this.dbPromise;
+    return new Promise<boolean>((resolve, reject) => {
+      const transaction = db.transaction(["photo-outbox", "photo-outbox-leases"], "readwrite");
+      const outbox = transaction.objectStore("photo-outbox");
+      const leases = transaction.objectStore("photo-outbox-leases");
+      const leaseRequest = leases.get(item.event);
+      const itemRequest = outbox.get(item.id);
+      let lease: LeaseRecord | undefined;
+      let current: OutboxItem | undefined;
+      let leaseRead = false;
+      let itemRead = false;
+      let result = false;
+      const replaceIfOwned = () => {
+        if (!leaseRead || !itemRead) return;
+        if (
+          lease?.ownerId !== ownerId ||
+          lease.expiresAt <= now ||
+          !current ||
+          current.event !== item.event
+        ) return;
+        outbox.put(item);
+        result = true;
+      };
+      leaseRequest.onsuccess = () => {
+        lease = leaseRequest.result as LeaseRecord | undefined;
+        leaseRead = true;
+        replaceIfOwned();
+      };
+      itemRequest.onsuccess = () => {
+        current = itemRequest.result as OutboxItem | undefined;
+        itemRead = true;
+        replaceIfOwned();
+      };
+      const fail = (error: DOMException | null, message: string) => {
+        transaction.abort();
+        reject(error ?? new Error(message));
+      };
+      leaseRequest.onerror = () => fail(leaseRequest.error, "Photo outbox lease read failed");
+      itemRequest.onerror = () => fail(itemRequest.error, "Photo outbox item read failed");
+      transaction.oncomplete = () => resolve(result);
+      transaction.onerror = () => reject(
+        transaction.error ?? new Error("Photo outbox failure transaction failed")
+      );
+      transaction.onabort = () => reject(
+        transaction.error ?? new Error("Photo outbox failure transaction aborted")
+      );
+    });
+  }
+
+  markFailure(item: OutboxItem, ownerId: string, now: number) {
+    return this.failureTransaction(item, ownerId, now);
+  }
 }
 
 /** Uses IndexedDB when available, but keeps the booth usable in private/locked-down browsers. */
@@ -224,5 +293,16 @@ export function createOutboxStore(
       () => durable.releaseLease(event, ownerId),
       () => memory.releaseLease(event, ownerId)
     ),
+    markFailure: async (item, ownerId, now) => {
+      if (usingMemory) return memory.markFailure(item, ownerId, now);
+      try {
+        const updated = await durable.markFailure(item, ownerId, now);
+        if (updated) await memory.put(item);
+        return updated;
+      } catch {
+        usingMemory = true;
+        return memory.markFailure(item, ownerId, now);
+      }
+    },
   };
 }
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index a8dfa8e..3f04d47 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -684,6 +684,224 @@ describe("BoothSession outbox", () => {
     await Promise.all([first.stop(), second.stop()]);
   });
 
+  test("keeps lease renewal scheduled while an automatic retry upload is running", async () => {
+    const store = new MemoryOutboxStore();
+    const scheduler = new ManualScheduler();
+    let now = 0;
+    let releaseUpload!: () => void;
+    const uploadBlocked = new Promise<void>((resolve) => {
+      releaseUpload = resolve;
+    });
+    let retryUploadStarted!: () => void;
+    const retryUpload = new Promise<void>((resolve) => {
+      retryUploadStarted = resolve;
+    });
+    let uploads = 0;
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploads++;
+        if (uploads === 1) throw new TypeError("offline");
+        retryUploadStarted();
+        await uploadBlocked;
+        return { url: "/photo" };
+      },
+      () => {},
+      undefined,
+      () => now,
+      {
+        ownerId: "first",
+        leaseTtlMs: 2_000,
+        random: () => 0,
+        setTimer: scheduler.setTimer,
+        clearTimer: scheduler.clearTimer,
+      }
+    );
+    await session.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+    await session.start();
+
+    try {
+      now = 500;
+      scheduler.runNext();
+      await retryUpload;
+      expect([...scheduler.timers.values()].map((timer) => timer.delayMs)).toContain(500);
+
+      now = 1_000;
+      scheduler.runNext();
+      await Promise.resolve();
+      await Promise.resolve();
+      now = 2_001;
+      expect(await store.acquireLease("party", "second", now, 2_000)).toBe(false);
+    } finally {
+      releaseUpload();
+      await session.stop();
+    }
+  });
+
+  test("continues renewing while stop waits for a long-running upload", async () => {
+    const store = new MemoryOutboxStore();
+    const scheduler = new ManualScheduler();
+    let now = 0;
+    let releaseUpload!: () => void;
+    const uploadBlocked = new Promise<void>((resolve) => {
+      releaseUpload = resolve;
+    });
+    let uploadStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      uploadStarted = resolve;
+    });
+    await store.put({ id: "one", event: "party", blob: photo("one"), createdAt: 1, attempts: 0 });
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploadStarted();
+        await uploadBlocked;
+        return { url: "/photo" };
+      },
+      () => {},
+      undefined,
+      () => now,
+      {
+        ownerId: "first",
+        leaseTtlMs: 100,
+        setTimer: scheduler.setTimer,
+        clearTimer: scheduler.clearTimer,
+      }
+    );
+
+    const drain = session.start();
+    await started;
+    const stopping = session.stop();
+    try {
+      expect([...scheduler.timers.values()].map((timer) => timer.delayMs)).toContain(50);
+      now = 50;
+      scheduler.runNext();
+      await Promise.resolve();
+      await Promise.resolve();
+      now = 101;
+      expect(await store.acquireLease("party", "second", now, 100)).toBe(false);
+    } finally {
+      releaseUpload();
+      await Promise.all([drain, stopping]);
+    }
+  });
+
+  test("does not resurrect an item removed between a manual retry read and lease acquisition", async () => {
+    class NoLeaseStore extends MemoryOutboxStore {
+      override async acquireLease() {
+        return false;
+      }
+    }
+
+    const store = new NoLeaseStore();
+    await store.put({
+      id: "oldest",
+      event: "party",
+      blob: photo("oldest"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "bad payload",
+      failureKind: "permanent",
+      errorClass: "payload",
+    });
+    const session = new BoothSession("party", store, async () => ({ url: "/photo" }));
+
+    const retry = session.retry();
+    await store.remove("oldest");
+    await retry;
+
+    expect(await store.list("party")).toEqual([]);
+  });
+
+  test("does not recreate a row when a stale owner fails after another owner takes over", async () => {
+    const store = new MemoryOutboxStore();
+    let now = 0;
+    let releaseFailure!: () => void;
+    const failureBlocked = new Promise<void>((resolve) => {
+      releaseFailure = resolve;
+    });
+    let uploadStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      uploadStarted = resolve;
+    });
+    await store.put({ id: "one", event: "party", blob: photo("one"), createdAt: 1, attempts: 0 });
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploadStarted();
+        await failureBlocked;
+        throw new TypeError("offline");
+      },
+      () => {},
+      undefined,
+      () => now,
+      { ownerId: "first", leaseTtlMs: 100, random: () => 0 }
+    );
+
+    const drain = session.process();
+    await started;
+    now = 101;
+    expect(await store.acquireLease("party", "second", now, 100)).toBe(true);
+    await store.remove("one");
+    releaseFailure();
+    await drain;
+
+    expect(await store.list("party")).toEqual([]);
+    await store.releaseLease("party", "second");
+  });
+
+  test("does not classify an acknowledged upload as failed when outbox cleanup fails", async () => {
+    class RemoveFailsStore extends MemoryOutboxStore {
+      override async remove() {
+        throw new Error("outbox cleanup failed");
+      }
+    }
+
+    const store = new RemoveFailsStore();
+    const session = new BoothSession("party", store, async () => ({ url: "/photo" }));
+    await session.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await session.process();
+
+    const [queued] = await store.list("party");
+    expect(queued.attempts).toBe(0);
+    expect(queued).not.toHaveProperty("lastError");
+    expect(queued).not.toHaveProperty("failureKind");
+    expect(queued).not.toHaveProperty("errorClass");
+  });
+
+  test("does not deadlock when auth recovery awaits stop", async () => {
+    const store = new MemoryOutboxStore();
+    let session!: BoothSession;
+    session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        throw new HttpUploadError(401, null, "auth");
+      },
+      () => {},
+      undefined,
+      () => 1_000,
+      { onAuthRequired: () => session.stop() }
+    );
+    await session.enqueueCapture(async () => photo("one"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await expect(Promise.race([
+      session.process(),
+      new Promise<void>((_, reject) => setTimeout(() => reject(new Error("auth deadlock")), 100)),
+    ])).resolves.toBeUndefined();
+    expect(await store.list("party")).toMatchObject([{ failureKind: "auth" }]);
+  });
+
   test("renews a long-running direct drain lease before another owner can acquire it", async () => {
     const store = new MemoryOutboxStore();
     const scheduler = new ManualScheduler();
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index 3713537..c1ee10c 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -38,6 +38,8 @@ export class BoothSession {
   private leaseHeld = false;
   private leaseExpiresAt = 0;
   private retryAt: number | null = null;
+  private manualRetryRequested = false;
+  private environmentalRetryRequested = false;
   private timer: unknown = null;
   private readonly ownerId: string;
   private readonly leaseTtlMs: number;
@@ -100,22 +102,27 @@ export class BoothSession {
   async stop() {
     this.started = false;
     this.stopRequested = true;
+    this.retryAt = null;
     this.cancelTimer();
-    const wakeWork = this.wakeWork;
     const processing = this.processing;
+    // A storage acknowledgement can outlive page teardown. Retain the lease
+    // until that drain settles so another tab cannot upload the same item.
+    if (processing && this.leaseHeld) this.scheduleWake();
+    const wakeWork = this.wakeWork;
     await Promise.allSettled([
       ...(wakeWork ? [wakeWork] : []),
       ...(processing ? [processing] : []),
     ]);
+    this.cancelTimer();
     await this.releaseLease();
   }
 
   async reconsider(_reason: "connectivity" | "foreground") {
     if (!this.started || this.stopRequested) return;
-    const pending = await this.store.list(this.event);
-    const first = pending[0];
-    if (!first || first.failureKind !== "retryable") return;
-    await this.store.put({ ...first, nextAttemptAt: this.now() });
+    // The oldest item is inspected and changed only after this session owns
+    // the Event lease; a stale pre-lease read could resurrect an acknowledged
+    // item from another tab.
+    this.environmentalRetryRequested = true;
     this.retryAt = this.now();
     this.cancelTimer();
     await this.process();
@@ -170,18 +177,7 @@ export class BoothSession {
 
   async retry() {
     if (this.stopRequested) return;
-    const pending = await this.store.list(this.event);
-    const first = pending[0];
-    if (first?.lastError || first?.failureKind) {
-      const {
-        lastError: _lastError,
-        nextAttemptAt: _nextAttemptAt,
-        failureKind: _failureKind,
-        errorClass: _errorClass,
-        ...ready
-      } = first;
-      await this.store.put(ready);
-    }
+    this.manualRetryRequested = true;
     this.retryAt = null;
     this.cancelTimer();
     await this.process();
@@ -191,7 +187,24 @@ export class BoothSession {
     if (!await this.ensureLease()) return;
     let pending = await this.store.list(this.event);
     while (pending.length > 0) {
-      const item = pending[0];
+      let item = pending[0];
+      const forceRetry =
+        this.manualRetryRequested ||
+        (this.environmentalRetryRequested && item.failureKind === "retryable");
+      this.manualRetryRequested = false;
+      this.environmentalRetryRequested = false;
+      if (forceRetry && (item.lastError || item.failureKind)) {
+        const {
+          lastError: _lastError,
+          nextAttemptAt: _nextAttemptAt,
+          failureKind: _failureKind,
+          errorClass: _errorClass,
+          ...ready
+        } = item;
+        await this.store.put(ready);
+        item = ready;
+        pending = [item, ...pending.slice(1)];
+      }
       if (item.failureKind === "retryable" && (item.nextAttemptAt ?? 0) > this.now()) {
         this.retryAt = item.nextAttemptAt ?? null;
         this.publish({
@@ -227,37 +240,24 @@ export class BoothSession {
       let result: UploadResult;
       try {
         result = await this.upload(item);
+      } catch (error) {
+        await this.recordUploadFailure(item, error, pending.length);
+        return;
+      }
+
+      try {
         await this.store.remove(item.id);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const attempt = item.attempts + 1;
-        const disposition = classifyUploadFailure(error, attempt, this.now(), this.random);
-        const failed: OutboxItem = {
-          ...item,
-          attempts: attempt,
-          lastError: message,
-          failureKind: disposition.kind === "auth-required" ? "auth" : disposition.kind,
-          errorClass: disposition.errorClass,
-          ...(disposition.kind === "retryable"
-            ? { nextAttemptAt: this.now() + disposition.delayMs }
-            : {}),
-        };
-        await this.store.put(failed);
-        this.retryAt = disposition.kind === "retryable" ? failed.nextAttemptAt ?? null : null;
+        // The Event store already acknowledged the upload. Do not classify or
+        // recreate this row if local outbox cleanup fails; a later manual retry
+        // uses the stable identity and receives the idempotent acknowledgement.
+        this.retryAt = null;
         this.publish({
           status: "failed",
           pendingCount: pending.length,
-          error: message,
+          error: error instanceof Error ? error.message : String(error),
           durable: this.store.isDurable(),
         });
-        if (disposition.kind === "auth-required") {
-          try {
-            await this.onAuthRequired();
-          } catch {
-            // Credential UI cannot affect the already-persisted queue state.
-          }
-        }
-        this.scheduleWake();
         return;
       }
 
@@ -290,14 +290,67 @@ export class BoothSession {
         durable: this.store.isDurable(),
       });
     }
+    this.manualRetryRequested = false;
+    this.environmentalRetryRequested = false;
     this.retryAt = null;
     this.scheduleWake();
   }
 
+  private async recordUploadFailure(item: OutboxItem, error: unknown, pendingCount: number) {
+    const message = error instanceof Error ? error.message : String(error);
+    const attempt = item.attempts + 1;
+    const now = this.now();
+    const disposition = classifyUploadFailure(error, attempt, now, this.random);
+    const failed: OutboxItem = {
+      ...item,
+      attempts: attempt,
+      lastError: message,
+      failureKind: disposition.kind === "auth-required" ? "auth" : disposition.kind,
+      errorClass: disposition.errorClass,
+      ...(disposition.kind === "retryable"
+        ? { nextAttemptAt: now + disposition.delayMs }
+        : {}),
+    };
+    if (!await this.store.markFailure(failed, this.ownerId, now)) {
+      this.leaseHeld = false;
+      this.leaseExpiresAt = 0;
+      if (this.started && !this.stopRequested) {
+        this.retryAt = now + this.leaseTtlMs;
+        this.scheduleWake();
+      }
+      return;
+    }
+    this.retryAt = disposition.kind === "retryable" ? failed.nextAttemptAt ?? null : null;
+    this.publish({
+      status: "failed",
+      pendingCount,
+      error: message,
+      durable: this.store.isDurable(),
+    });
+    if (disposition.kind === "auth-required") this.notifyAuthRequired();
+    this.scheduleWake();
+  }
+
+  private notifyAuthRequired() {
+    try {
+      void Promise.resolve(this.onAuthRequired()).catch(() => {
+        // Credential UI cannot affect the already-persisted queue state.
+      });
+    } catch {
+      // Synchronous credential UI failures are equally isolated from the queue.
+    }
+  }
+
   private async ensureLease() {
     if (this.leaseHeld) {
-      if (this.now() < this.leaseRenewAt()) return true;
-      if (await this.renewLease()) return true;
+      if (this.now() < this.leaseRenewAt()) {
+        this.scheduleWake();
+        return true;
+      }
+      if (await this.renewLease()) {
+        this.scheduleWake();
+        return true;
+      }
       this.leaseHeld = false;
     }
     const acquired = await this.store.acquireLease(
@@ -336,10 +389,10 @@ export class BoothSession {
   }
 
   private async releaseLease() {
+    this.cancelTimer();
     if (!this.leaseHeld) return;
     this.leaseHeld = false;
     this.leaseExpiresAt = 0;
-    if (!this.started) this.cancelTimer();
     await this.store.releaseLease(this.event, this.ownerId);
   }
 
@@ -350,9 +403,9 @@ export class BoothSession {
   }
 
   private scheduleWake() {
-    if (this.stopRequested) return;
+    const renewLease = this.leaseHeld && (!this.stopRequested || this.processing !== null);
     const targets = [
-      ...(this.leaseHeld ? [this.leaseRenewAt()] : []),
+      ...(renewLease ? [this.leaseRenewAt()] : []),
       ...(this.started && this.retryAt !== null ? [this.retryAt] : []),
     ];
     if (targets.length === 0) return;
@@ -369,11 +422,14 @@ export class BoothSession {
   }
 
   private async handleWake() {
-    if (this.stopRequested) return;
     if (this.leaseHeld && this.now() >= this.leaseRenewAt()) {
       if (!await this.renewLease()) this.leaseHeld = false;
     }
-    if (!this.started || this.stopRequested) {
+    if (this.stopRequested) {
+      if (this.leaseHeld && this.processing) this.scheduleWake();
+      return;
+    }
+    if (!this.started) {
       if (this.leaseHeld && this.processing) this.scheduleWake();
       return;
     }

From 183ea8bd8387210f5c477501a9dc01ff72b66e60 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:23:40 +0800
Subject: [PATCH 036/105] fix: preserve outbox lease renewal

---
 app/[event]/booth-session/session.test.ts | 147 +++++++++++++++++++++-
 app/[event]/booth-session/session.ts      |  28 ++++-
 2 files changed, 170 insertions(+), 5 deletions(-)

diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index 3f04d47..7f7c145 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createOutboxStore, MemoryOutboxStore, type OutboxItem } from "./outbox";
-import { BoothSession, runCaptureSequence } from "./session";
+import { BoothSession, runCaptureSequence, type UploadState } from "./session";
 import { outboxUploadHeaders } from "./upload";
 import { HttpUploadError } from "./retry-policy";
 
@@ -790,6 +790,106 @@ describe("BoothSession outbox", () => {
     }
   });
 
+  test("keeps renewing a blocked upload when manual retry coalesces", async () => {
+    const store = new MemoryOutboxStore();
+    const scheduler = new ManualScheduler();
+    let now = 0;
+    let releaseUpload!: () => void;
+    const uploadBlocked = new Promise<void>((resolve) => {
+      releaseUpload = resolve;
+    });
+    let uploadStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      uploadStarted = resolve;
+    });
+    await store.put({ id: "one", event: "party", blob: photo("one"), createdAt: 1, attempts: 0 });
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploadStarted();
+        await uploadBlocked;
+        return { url: "/photo" };
+      },
+      () => {},
+      undefined,
+      () => now,
+      {
+        ownerId: "first",
+        leaseTtlMs: 100,
+        setTimer: scheduler.setTimer,
+        clearTimer: scheduler.clearTimer,
+      }
+    );
+
+    const drain = session.start();
+    await started;
+    const retrying = session.retry();
+    try {
+      expect([...scheduler.timers.values()].map((timer) => timer.delayMs)).toContain(50);
+      now = 50;
+      scheduler.runNext();
+      await Promise.resolve();
+      await Promise.resolve();
+      now = 101;
+      expect(await store.acquireLease("party", "second", now, 100)).toBe(false);
+    } finally {
+      releaseUpload();
+      await Promise.all([drain, retrying]);
+      await session.stop();
+    }
+  });
+
+  test("keeps renewing a blocked upload when foreground reconsider coalesces", async () => {
+    const store = new MemoryOutboxStore();
+    const scheduler = new ManualScheduler();
+    let now = 0;
+    let releaseUpload!: () => void;
+    const uploadBlocked = new Promise<void>((resolve) => {
+      releaseUpload = resolve;
+    });
+    let uploadStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      uploadStarted = resolve;
+    });
+    await store.put({ id: "one", event: "party", blob: photo("one"), createdAt: 1, attempts: 0 });
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploadStarted();
+        await uploadBlocked;
+        return { url: "/photo" };
+      },
+      () => {},
+      undefined,
+      () => now,
+      {
+        ownerId: "first",
+        leaseTtlMs: 100,
+        setTimer: scheduler.setTimer,
+        clearTimer: scheduler.clearTimer,
+      }
+    );
+
+    const drain = session.start();
+    await started;
+    const reconsidering = session.reconsider("foreground");
+    try {
+      expect([...scheduler.timers.values()].map((timer) => timer.delayMs)).toContain(50);
+      now = 50;
+      scheduler.runNext();
+      await Promise.resolve();
+      await Promise.resolve();
+      now = 101;
+      expect(await store.acquireLease("party", "second", now, 100)).toBe(false);
+    } finally {
+      releaseUpload();
+      await Promise.all([drain, reconsidering]);
+      await session.stop();
+    }
+  });
+
   test("does not resurrect an item removed between a manual retry read and lease acquisition", async () => {
     class NoLeaseStore extends MemoryOutboxStore {
       override async acquireLease() {
@@ -855,6 +955,51 @@ describe("BoothSession outbox", () => {
     await store.releaseLease("party", "second");
   });
 
+  test("reconciles away from uploading after a stale failure loses its row", async () => {
+    const store = new MemoryOutboxStore();
+    let now = 0;
+    let releaseFailure!: () => void;
+    const failureBlocked = new Promise<void>((resolve) => {
+      releaseFailure = resolve;
+    });
+    let uploadStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      uploadStarted = resolve;
+    });
+    await store.put({ id: "one", event: "party", blob: photo("one"), createdAt: 1, attempts: 0 });
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => {
+        uploadStarted();
+        await failureBlocked;
+        throw new TypeError("offline");
+      },
+      () => {},
+      undefined,
+      () => now,
+      { ownerId: "first", leaseTtlMs: 100, random: () => 0 }
+    );
+    const states: UploadState[] = [];
+    session.subscribe((state) => states.push(state));
+
+    const drain = session.process();
+    await started;
+    now = 101;
+    expect(await store.acquireLease("party", "second", now, 100)).toBe(true);
+    await store.remove("one");
+    releaseFailure();
+    await drain;
+
+    expect(states.at(-1)).toEqual({
+      status: "idle",
+      pendingCount: 0,
+      error: null,
+      durable: false,
+    });
+    await store.releaseLease("party", "second");
+  });
+
   test("does not classify an acknowledged upload as failed when outbox cleanup fails", async () => {
     class RemoveFailsStore extends MemoryOutboxStore {
       override async remove() {
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index c1ee10c..2fcbb5b 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -123,8 +123,10 @@ export class BoothSession {
     // the Event lease; a stale pre-lease read could resurrect an acknowledged
     // item from another tab.
     this.environmentalRetryRequested = true;
-    this.retryAt = this.now();
-    this.cancelTimer();
+    if (!this.processing) {
+      this.retryAt = this.now();
+      this.cancelTimer();
+    }
     await this.process();
   }
 
@@ -178,8 +180,10 @@ export class BoothSession {
   async retry() {
     if (this.stopRequested) return;
     this.manualRetryRequested = true;
-    this.retryAt = null;
-    this.cancelTimer();
+    if (!this.processing) {
+      this.retryAt = null;
+      this.cancelTimer();
+    }
     await this.process();
   }
 
@@ -314,6 +318,22 @@ export class BoothSession {
     if (!await this.store.markFailure(failed, this.ownerId, now)) {
       this.leaseHeld = false;
       this.leaseExpiresAt = 0;
+      try {
+        const pending = await this.store.list(this.event);
+        this.publish({
+          status: pending.some((queued) => queued.lastError) ? "failed" : "idle",
+          pendingCount: pending.length,
+          error: pending.find((queued) => queued.lastError)?.lastError ?? null,
+          durable: this.store.isDurable(),
+        });
+      } catch (reconcileError) {
+        this.publish({
+          status: "failed",
+          pendingCount: 0,
+          error: reconcileError instanceof Error ? reconcileError.message : String(reconcileError),
+          durable: this.store.isDurable(),
+        });
+      }
       if (this.started && !this.stopRequested) {
         this.retryAt = now + this.leaseTtlMs;
         this.scheduleWake();

From 3215fa5d72ae0c1bd509a14d49501166d1b9a1b3 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:27:41 +0800
Subject: [PATCH 037/105] feat: store private booth operations

---
 app/booth-control.test.ts |  66 +++++++++++++
 app/booth-control.ts      | 197 ++++++++++++++++++++++++++++++++++++++
 app/event-store.test.ts   | 133 +++++++++++++++++++++++++
 app/event-store.ts        | 114 ++++++++++++++++++++++
 4 files changed, 510 insertions(+)
 create mode 100644 app/booth-control.test.ts
 create mode 100644 app/booth-control.ts

diff --git a/app/booth-control.test.ts b/app/booth-control.test.ts
new file mode 100644
index 0000000..4f87717
--- /dev/null
+++ b/app/booth-control.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import {
+  parseBoothHeartbeat,
+  parseBoothHeartbeatRecord,
+  parseBoothOperationalState,
+} from "./booth-control";
+
+const heartbeat = {
+  version: 1,
+  deviceId: "018f0000-0000-4000-8000-000000000001",
+  sessionStartedAt: 1753315200000,
+  pendingCount: 2,
+  durableStorage: true,
+  online: true,
+  installed: true,
+  camera: "ready",
+  upload: "retry-wait",
+  buildId: "release_1",
+} as const;
+
+describe("Booth control schemas", () => {
+  test("parses a bounded heartbeat without arbitrary error text", () => {
+    expect(parseBoothHeartbeat(heartbeat)).toEqual(heartbeat);
+    expect(parseBoothHeartbeat({
+      ...heartbeat,
+      pendingCount: 0,
+      installed: false,
+      upload: "idle",
+      error: "credential=x",
+    })).toBeNull();
+  });
+
+  test("rejects unknown, future, or unbounded heartbeat fields", () => {
+    expect(parseBoothHeartbeat({ ...heartbeat, version: 2 })).toBeNull();
+    expect(parseBoothHeartbeat({ ...heartbeat, deviceId: heartbeat.deviceId.toUpperCase() })).toBeNull();
+    expect(parseBoothHeartbeat({ ...heartbeat, sessionStartedAt: 1.5 })).toBeNull();
+    expect(parseBoothHeartbeat({ ...heartbeat, pendingCount: 10_001 })).toBeNull();
+    expect(parseBoothHeartbeat({ ...heartbeat, buildId: "x".repeat(129) })).toBeNull();
+    expect(parseBoothHeartbeat({ ...heartbeat, camera: "exception: credential=x" })).toBeNull();
+    expect(parseBoothHeartbeat({ ...heartbeat, unexpected: true })).toBeNull();
+  });
+
+  test("parses only server-timestamped stored heartbeat records", () => {
+    const stored = { ...heartbeat, lastSeenAt: "2026-07-24T00:00:00.000Z" };
+    expect(parseBoothHeartbeatRecord(stored)).toEqual(stored);
+    expect(parseBoothHeartbeatRecord({ ...stored, lastSeenAt: "not-a-date" })).toBeNull();
+    expect(parseBoothHeartbeatRecord({ ...stored, version: 2 })).toBeNull();
+  });
+
+  test("parses at most twenty bounded localized pause messages", () => {
+    const state = {
+      version: 1 as const,
+      paused: true,
+      messages: { en: "The Booth is briefly paused.", "zh-SG": "暂时暂停" },
+      updatedAt: "2026-07-24T00:00:00.000Z",
+    };
+    expect(parseBoothOperationalState(state)).toEqual(state);
+    expect(parseBoothOperationalState({ ...state, messages: { "en<script>": "unsafe" } })).toBeNull();
+    expect(parseBoothOperationalState({ ...state, messages: { en: "x".repeat(281) } })).toBeNull();
+    expect(parseBoothOperationalState({
+      ...state,
+      messages: Object.fromEntries(Array.from({ length: 21 }, (_, index) => [`l${index}`, "paused"])),
+    })).toBeNull();
+    expect(parseBoothOperationalState({ ...state, unknown: "credential=x" })).toBeNull();
+  });
+});
diff --git a/app/booth-control.ts b/app/booth-control.ts
new file mode 100644
index 0000000..a92862a
--- /dev/null
+++ b/app/booth-control.ts
@@ -0,0 +1,197 @@
+export const BOOTH_HEARTBEAT_INTERVAL_MS = 15_000;
+export const BOOTH_STALE_AFTER_MS = 45_000;
+
+const BOOTH_CONTROL_VERSION = 1 as const;
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+const CAMERA_STATES = ["stopped", "starting", "ready", "denied", "unavailable"] as const;
+const UPLOAD_STATES = ["idle", "uploading", "retry-wait", "blocked", "auth-required"] as const;
+const ERROR_CLASSES = [
+  "network",
+  "timeout",
+  "auth",
+  "payload",
+  "camera-permission",
+  "camera-unavailable",
+  "storage",
+  "server",
+  "unknown",
+] as const;
+
+export type BoothCameraState = typeof CAMERA_STATES[number];
+export type BoothUploadState = typeof UPLOAD_STATES[number];
+export type BoothErrorClass = typeof ERROR_CLASSES[number];
+
+export type BoothHeartbeatInput = {
+  version: 1;
+  deviceId: string;
+  sessionStartedAt: number;
+  pendingCount: number;
+  durableStorage: boolean;
+  online: boolean;
+  installed: boolean;
+  camera: BoothCameraState;
+  upload: BoothUploadState;
+  lastSuccessfulUploadAt?: number;
+  errorClass?: BoothErrorClass;
+  buildId: string;
+};
+
+export type BoothHeartbeatRecord = BoothHeartbeatInput & { lastSeenAt: string };
+export type AdminBoothRecord = BoothHeartbeatRecord & { stale: boolean };
+
+export type BoothOperationalState = {
+  version: 1;
+  paused: boolean;
+  messages?: Record<string, string>;
+  updatedAt: string;
+};
+
+export type BoothOperationalStateInput = Pick<BoothOperationalState, "paused" | "messages">;
+
+export function parseBoothHeartbeat(value: unknown): BoothHeartbeatInput | null {
+  const record = parseRecord(value, [
+    "version",
+    "deviceId",
+    "sessionStartedAt",
+    "pendingCount",
+    "durableStorage",
+    "online",
+    "installed",
+    "camera",
+    "upload",
+    "lastSuccessfulUploadAt",
+    "errorClass",
+    "buildId",
+  ]);
+  if (!record) return null;
+  return parseHeartbeatFields(record);
+}
+
+export function parseBoothHeartbeatRecord(value: unknown): BoothHeartbeatRecord | null {
+  const record = parseRecord(value, [
+    "version",
+    "deviceId",
+    "sessionStartedAt",
+    "pendingCount",
+    "durableStorage",
+    "online",
+    "installed",
+    "camera",
+    "upload",
+    "lastSuccessfulUploadAt",
+    "errorClass",
+    "buildId",
+    "lastSeenAt",
+  ]);
+  if (!record || !isIsoTimestamp(record.lastSeenAt)) return null;
+  const heartbeat = parseHeartbeatFields(record);
+  return heartbeat ? { ...heartbeat, lastSeenAt: record.lastSeenAt } : null;
+}
+
+export function parseBoothOperationalStateInput(value: unknown): BoothOperationalStateInput | null {
+  const record = parseRecord(value, ["paused", "messages"]);
+  if (!record || typeof record.paused !== "boolean") return null;
+  const messages = parseMessages(record.messages);
+  if (messages === null) return null;
+  return {
+    paused: record.paused,
+    ...(messages ? { messages } : {}),
+  };
+}
+
+export function parseBoothOperationalState(value: unknown): BoothOperationalState | null {
+  const record = parseRecord(value, ["version", "paused", "messages", "updatedAt"]);
+  if (
+    !record
+    || record.version !== BOOTH_CONTROL_VERSION
+    || typeof record.paused !== "boolean"
+    || !isIsoTimestamp(record.updatedAt)
+  ) return null;
+  const messages = parseMessages(record.messages);
+  if (messages === null) return null;
+  return {
+    version: BOOTH_CONTROL_VERSION,
+    paused: record.paused,
+    ...(messages ? { messages } : {}),
+    updatedAt: record.updatedAt,
+  };
+}
+
+function parseHeartbeatFields(record: Record<string, unknown>): BoothHeartbeatInput | null {
+  if (
+    record.version !== BOOTH_CONTROL_VERSION
+    || typeof record.deviceId !== "string"
+    || !UUID_V4.test(record.deviceId)
+    || !isMilliseconds(record.sessionStartedAt)
+    || !isPendingCount(record.pendingCount)
+    || typeof record.durableStorage !== "boolean"
+    || typeof record.online !== "boolean"
+    || typeof record.installed !== "boolean"
+    || !isOneOf(CAMERA_STATES, record.camera)
+    || !isOneOf(UPLOAD_STATES, record.upload)
+    || (record.lastSuccessfulUploadAt !== undefined && !isMilliseconds(record.lastSuccessfulUploadAt))
+    || (record.errorClass !== undefined && !isOneOf(ERROR_CLASSES, record.errorClass))
+    || typeof record.buildId !== "string"
+    || !TOKEN.test(record.buildId)
+  ) return null;
+
+  return {
+    version: BOOTH_CONTROL_VERSION,
+    deviceId: record.deviceId,
+    sessionStartedAt: record.sessionStartedAt,
+    pendingCount: record.pendingCount,
+    durableStorage: record.durableStorage,
+    online: record.online,
+    installed: record.installed,
+    camera: record.camera,
+    upload: record.upload,
+    ...(typeof record.lastSuccessfulUploadAt === "number"
+      ? { lastSuccessfulUploadAt: record.lastSuccessfulUploadAt }
+      : {}),
+    ...(typeof record.errorClass === "string" ? { errorClass: record.errorClass } : {}),
+    buildId: record.buildId,
+  };
+}
+
+function parseMessages(value: unknown): Record<string, string> | null | undefined {
+  if (value === undefined) return undefined;
+  if (!isPlainRecord(value)) return null;
+  const entries = Object.entries(value);
+  if (
+    entries.length > 20
+    || entries.some(([locale, message]) => !TOKEN.test(locale) || typeof message !== "string" || message.length > 280)
+  ) return null;
+  return Object.fromEntries(entries as [string, string][]);
+}
+
+function parseRecord(value: unknown, allowedKeys: readonly string[]): Record<string, unknown> | null {
+  if (!isPlainRecord(value) || Object.keys(value).some((key) => !allowedKeys.includes(key))) return null;
+  return value;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isMilliseconds(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isPendingCount(value: unknown): value is number {
+  return isMilliseconds(value) && value <= 10_000;
+}
+
+function isIsoTimestamp(value: unknown): value is string {
+  if (typeof value !== "string" || !ISO_TIMESTAMP.test(value)) return false;
+  const milliseconds = Date.parse(value);
+  return Number.isFinite(milliseconds) && new Date(milliseconds).toISOString() === value;
+}
+
+function isOneOf<T extends readonly string[]>(values: T, value: unknown): value is T[number] {
+  return typeof value === "string" && values.includes(value as T[number]);
+}
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index ad134fc..2405534 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -11,6 +11,8 @@ import {
   eventConfigKey,
   eventConfigMutationKey,
   eventConfigRevisionKey,
+  boothHeartbeatKey,
+  boothOperationalStateKey,
   legacyEventConfigKey,
   PhotoIndexWriteError,
   photoFeedCommittedKey,
@@ -22,6 +24,7 @@ import {
   type ListResult,
   type StoredObjectBody,
 } from "./event-store";
+import type { BoothHeartbeatInput } from "./booth-control";
 
 class FailPrivatePhotoWriteStore extends InMemoryObjectStore {
   private writesFail = true;
@@ -241,6 +244,25 @@ async function saveSameContentHistory(
   return { first, second };
 }
 
+function boothHeartbeat(
+  deviceId: string,
+  changes: Partial<BoothHeartbeatInput> = {}
+): BoothHeartbeatInput {
+  return {
+    version: 1,
+    deviceId,
+    sessionStartedAt: 1753315200000,
+    pendingCount: 0,
+    durableStorage: true,
+    online: true,
+    installed: true,
+    camera: "ready",
+    upload: "idle",
+    buildId: "release_1",
+    ...changes,
+  };
+}
+
 describe("ObjectStore", () => {
   test("compareAndSwap rejects a stale etag", async () => {
     const state = new InMemoryObjectStore();
@@ -1703,4 +1725,115 @@ describe("EventStore", () => {
     expect(photos.has("launch/0000000001000-a.jpg")).toBe(false);
     expect(photos.has("other/0000000001000-b.jpg")).toBe(true);
   });
+
+  test("writes an exact private heartbeat with a server-controlled timestamp", async () => {
+    const now = new Date("2026-07-24T00:00:00.000Z");
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example", () => now);
+    const input = boothHeartbeat("018f0000-0000-4000-8000-000000000001", {
+      pendingCount: 2,
+      upload: "retry-wait",
+    });
+
+    const record = await store.writeBoothHeartbeat("launch", input);
+
+    expect(record).toEqual({ ...input, lastSeenAt: now.toISOString() });
+    const stored = await state.get(boothHeartbeatKey("launch", input.deviceId));
+    expect(await stored!.json<unknown>()).toEqual(record);
+    expect((await photos.list()).objects).toHaveLength(0);
+    await expect(store.writeBoothHeartbeat("launch", {
+      ...input,
+      lastSeenAt: "2099-01-01T00:00:00.000Z",
+    } as unknown as BoothHeartbeatInput)).rejects.toBeInstanceOf(TypeError);
+  });
+
+  test("pages bounded private heartbeats, derives stale records, and overwrites exact devices", async () => {
+    let now = new Date("2026-07-24T00:00:00.000Z");
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example", () => now);
+    const firstDevice = "018f0000-0000-4000-8000-000000000001";
+    const secondDevice = "018f0000-0000-4000-8000-000000000002";
+    const thirdDevice = "018f0000-0000-4000-8000-000000000003";
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(firstDevice));
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(secondDevice));
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(thirdDevice));
+    now = new Date("2026-07-24T00:00:45.001Z");
+
+    const firstPage = await store.listBoothHeartbeats("launch", { limit: 2 });
+    const secondPage = await store.listBoothHeartbeats("launch", { limit: 2, cursor: firstPage.cursor });
+
+    expect(firstPage.booths.map((record) => record.deviceId)).toEqual([firstDevice, secondDevice]);
+    expect(firstPage.booths.every((record) => record.stale)).toBe(true);
+    expect(firstPage.cursor).not.toBeNull();
+    expect(secondPage.booths.map((record) => record.deviceId)).toEqual([thirdDevice]);
+    expect(secondPage.cursor).toBeNull();
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(firstDevice, { pendingCount: 3 }));
+    const refreshed = await store.listBoothHeartbeats("launch", { limit: 100 });
+    expect(refreshed.booths).toHaveLength(3);
+    expect(refreshed.booths.find((record) => record.deviceId === firstDevice)).toMatchObject({
+      pendingCount: 3,
+      stale: false,
+      lastSeenAt: now.toISOString(),
+    });
+    await expect(store.listBoothHeartbeats("launch", { limit: 101 })).rejects.toBeInstanceOf(TypeError);
+    expect((await photos.list()).objects).toHaveLength(0);
+  });
+
+  test("isolates heartbeats by Event and fails closed on malformed or future private records", async () => {
+    const deviceId = "018f0000-0000-4000-8000-000000000001";
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example", () => new Date("2026-07-24T00:00:00.000Z"));
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(deviceId));
+    await store.writeBoothHeartbeat("other", boothHeartbeat(deviceId, { pendingCount: 9 }));
+
+    expect((await store.listBoothHeartbeats("launch", {})).booths).toMatchObject([{ deviceId, pendingCount: 0 }]);
+    expect((await store.listBoothHeartbeats("other", {})).booths).toMatchObject([{ deviceId, pendingCount: 9 }]);
+    expect(state.has(boothHeartbeatKey("launch", deviceId))).toBe(true);
+    expect(state.has(boothHeartbeatKey("other", deviceId))).toBe(true);
+    state.set(boothHeartbeatKey("launch", "018f0000-0000-4000-8000-000000000004"), "not json");
+    await expect(store.listBoothHeartbeats("launch", {})).rejects.toThrow("booth heartbeat");
+
+    const futureState = new InMemoryObjectStore({
+      [boothHeartbeatKey("launch", deviceId)]: JSON.stringify({
+        ...boothHeartbeat(deviceId),
+        version: 2,
+        lastSeenAt: "2026-07-24T00:00:00.000Z",
+      }),
+    });
+    const futureStore = new EventStore(photos, futureState, "https://photos.example");
+    await expect(futureStore.listBoothHeartbeats("launch", {})).rejects.toThrow("booth heartbeat");
+    expect((await photos.list()).objects).toHaveLength(0);
+  });
+
+  test("returns an unpaused default without writing and stores bounded localized pause state privately", async () => {
+    const now = new Date("2026-07-24T00:00:00.000Z");
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example", () => now);
+
+    expect(await store.readBoothOperationalState("launch")).toEqual({
+      version: 1,
+      paused: false,
+      updatedAt: now.toISOString(),
+    });
+    expect(state.has(boothOperationalStateKey("launch"))).toBe(false);
+    const written = await store.writeBoothOperationalState("launch", {
+      paused: true,
+      messages: { en: "The Booth is briefly paused.", "zh-SG": "暂时暂停" },
+    });
+    expect(written).toEqual({
+      version: 1,
+      paused: true,
+      messages: { en: "The Booth is briefly paused.", "zh-SG": "暂时暂停" },
+      updatedAt: now.toISOString(),
+    });
+    expect(await store.readBoothOperationalState("launch")).toEqual(written);
+    expect((await photos.list()).objects).toHaveLength(0);
+
+    state.set(boothOperationalStateKey("other"), JSON.stringify({ version: 2, paused: false, updatedAt: now.toISOString() }));
+    await expect(store.readBoothOperationalState("other")).rejects.toThrow("booth operational state");
+  });
 });
diff --git a/app/event-store.ts b/app/event-store.ts
index 466ba2f..726c2c7 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -13,6 +13,18 @@ import {
   type EventConfig,
   type EventExperience,
 } from "./event-config";
+import {
+  BOOTH_STALE_AFTER_MS,
+  parseBoothHeartbeat,
+  parseBoothHeartbeatRecord,
+  parseBoothOperationalState,
+  parseBoothOperationalStateInput,
+  type AdminBoothRecord,
+  type BoothHeartbeatInput,
+  type BoothHeartbeatRecord,
+  type BoothOperationalState,
+  type BoothOperationalStateInput,
+} from "./booth-control";
 import type { StableCaptureIdentity, StableUpload } from "./upload-contract";
 export { canonicalEvent, InvalidEventSlugError, slugifyEvent } from "./event-identity";
 export { EVENT_CONFIG_VERSION };
@@ -225,6 +237,11 @@ export const eventConfigRevisionKey = (event: string, id: string) =>
   `${eventConfigRevisionPrefix(event)}${id}.json`;
 export const eventConfigMutationKey = (event: string, mutationId: string) =>
   `events/${event}/config-mutations/${mutationId}.json`;
+export const boothHeartbeatKey = (event: string, deviceId: string) =>
+  `events/${event}/booths/${deviceId}.json`;
+export const boothHeartbeatPrefix = (event: string) => `events/${event}/booths/`;
+export const boothOperationalStateKey = (event: string) =>
+  `events/${event}/booth-state.json`;
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
 export const stablePhotoKey = (event: string, id: StableCaptureIdentity) =>
@@ -273,6 +290,8 @@ export type ConfigHistory = {
   currentRevisionId: string | null;
   revisions: ConfigRevision[];
 };
+export type BoothHeartbeatListOptions = { cursor?: string | null; limit?: number };
+export type BoothHeartbeatPage = { booths: AdminBoothRecord[]; cursor: string | null };
 
 export class ConfigConflictError extends Error {
   constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
@@ -320,6 +339,18 @@ export class InvalidPhotoCursorError extends Error {
   }
 }
 
+export class InvalidStoredBoothHeartbeatError extends Error {
+  constructor(readonly event: string) {
+    super(`stored booth heartbeat for ${event} is corrupt or uses an unsupported version`);
+  }
+}
+
+export class InvalidStoredBoothOperationalStateError extends Error {
+  constructor(readonly event: string) {
+    super(`stored booth operational state for ${event} is corrupt or uses an unsupported version`);
+  }
+}
+
 class InvalidStoredPhotoFeedError extends Error {
   constructor(readonly event: string) {
     super(`photo feed state for ${event} is corrupt or uses an unsupported version`);
@@ -574,6 +605,73 @@ export class EventStore {
     return { ...photo, indexStored, receiptStored };
   }
 
+  async writeBoothHeartbeat(event: string, input: BoothHeartbeatInput): Promise<BoothHeartbeatRecord> {
+    const heartbeat = parseBoothHeartbeat(input);
+    if (!heartbeat) throw new TypeError("invalid booth heartbeat");
+    const record: BoothHeartbeatRecord = { ...heartbeat, lastSeenAt: this.now().toISOString() };
+    await this.state.put(boothHeartbeatKey(event, record.deviceId), JSON.stringify(record), jsonWriteOptions());
+    return record;
+  }
+
+  async listBoothHeartbeats(
+    event: string,
+    options: BoothHeartbeatListOptions = {}
+  ): Promise<BoothHeartbeatPage> {
+    const limit = options.limit ?? 50;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw new TypeError("booth heartbeat limit must be an integer from 1 to 100");
+    }
+    const cursor = options.cursor ?? undefined;
+    if (cursor !== undefined && (typeof cursor !== "string" || cursor.length === 0 || cursor.length > 2048)) {
+      throw new TypeError("booth heartbeat cursor is invalid");
+    }
+    const page = await this.state.list({
+      prefix: boothHeartbeatPrefix(event),
+      ...(cursor !== undefined ? { cursor } : {}),
+      limit,
+    });
+    const now = this.now().getTime();
+    const booths = await Promise.all(page.objects.map(async (object): Promise<AdminBoothRecord> => {
+      const record = await this.readBoothHeartbeat(event, object.key);
+      return {
+        ...record,
+        stale: now - Date.parse(record.lastSeenAt) >= BOOTH_STALE_AFTER_MS,
+      };
+    }));
+    return { booths, cursor: page.truncated ? page.cursor ?? null : null };
+  }
+
+  async readBoothOperationalState(event: string): Promise<BoothOperationalState> {
+    const object = await this.state.get(boothOperationalStateKey(event));
+    if (!object) {
+      return { version: 1, paused: false, updatedAt: this.now().toISOString() };
+    }
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredBoothOperationalStateError(event);
+    }
+    const state = parseBoothOperationalState(value);
+    if (!state) throw new InvalidStoredBoothOperationalStateError(event);
+    return state;
+  }
+
+  async writeBoothOperationalState(
+    event: string,
+    input: BoothOperationalStateInput
+  ): Promise<BoothOperationalState> {
+    const operational = parseBoothOperationalStateInput(input);
+    if (!operational) throw new TypeError("invalid booth operational state");
+    const state: BoothOperationalState = {
+      version: 1,
+      ...operational,
+      updatedAt: this.now().toISOString(),
+    };
+    await this.state.put(boothOperationalStateKey(event), JSON.stringify(state), jsonWriteOptions());
+    return state;
+  }
+
   async listPhotos(event: string, after: string | null = null): Promise<PhotoFeed> {
     if (after === null) return this.initialPhotoFeed(event);
     if (isPhotoKey(event, after)) {
@@ -1125,6 +1223,22 @@ export class EventStore {
     }
   }
 
+  private async readBoothHeartbeat(event: string, key: string): Promise<BoothHeartbeatRecord> {
+    const object = await this.state.get(key);
+    if (!object) throw new InvalidStoredBoothHeartbeatError(event);
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredBoothHeartbeatError(event);
+    }
+    const record = parseBoothHeartbeatRecord(value);
+    if (!record || key !== boothHeartbeatKey(event, record.deviceId)) {
+      throw new InvalidStoredBoothHeartbeatError(event);
+    }
+    return record;
+  }
+
   private async readJson(store: ObjectStore, key: string): Promise<unknown | null> {
     const object = await store.get(key);
     if (!object) return null;

From efb67f3b96c7649775e0eb68f51d3363fc80f8a0 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:37:42 +0800
Subject: [PATCH 038/105] fix: harden private booth operations

---
 app/booth-control.test.ts |  28 +++++++++
 app/booth-control.ts      |  50 ++++++---------
 app/event-store.test.ts   | 125 ++++++++++++++++++++++++++++++++++++++
 app/event-store.ts        |  23 ++++---
 4 files changed, 187 insertions(+), 39 deletions(-)

diff --git a/app/booth-control.test.ts b/app/booth-control.test.ts
index 4f87717..bb9665c 100644
--- a/app/booth-control.test.ts
+++ b/app/booth-control.test.ts
@@ -63,4 +63,32 @@ describe("Booth control schemas", () => {
     })).toBeNull();
     expect(parseBoothOperationalState({ ...state, unknown: "credential=x" })).toBeNull();
   });
+
+  test("returns locale messages with own-property lookup semantics", () => {
+    const parsed = parseBoothOperationalState({
+      version: 1,
+      paused: true,
+      messages: {
+        en: "Paused",
+        constructor: "Constructor locale",
+        prototype: "Prototype locale",
+        toString: "String locale",
+      },
+      updatedAt: "2026-07-24T00:00:00.000Z",
+    });
+
+    expect(Object.getPrototypeOf(parsed!.messages!)).toBeNull();
+    expect(Object.hasOwn(parsed!.messages!, "en")).toBe(true);
+    expect(Object.hasOwn(parsed!.messages!, "constructor")).toBe(true);
+    expect(Object.hasOwn(parsed!.messages!, "prototype")).toBe(true);
+    expect(Object.hasOwn(parsed!.messages!, "toString")).toBe(true);
+
+    const onlyEnglish = parseBoothOperationalState({
+      version: 1,
+      paused: true,
+      messages: { en: "Paused" },
+      updatedAt: "2026-07-24T00:00:00.000Z",
+    });
+    expect(onlyEnglish!.messages!["toString"]).toBeUndefined();
+  });
 });
diff --git a/app/booth-control.ts b/app/booth-control.ts
index a92862a..babbdcc 100644
--- a/app/booth-control.ts
+++ b/app/booth-control.ts
@@ -19,6 +19,21 @@ const ERROR_CLASSES = [
   "server",
   "unknown",
 ] as const;
+const HEARTBEAT_INPUT_KEYS = [
+  "version",
+  "deviceId",
+  "sessionStartedAt",
+  "pendingCount",
+  "durableStorage",
+  "online",
+  "installed",
+  "camera",
+  "upload",
+  "lastSuccessfulUploadAt",
+  "errorClass",
+  "buildId",
+] as const;
+const HEARTBEAT_RECORD_KEYS = [...HEARTBEAT_INPUT_KEYS, "lastSeenAt"] as const;
 
 export type BoothCameraState = typeof CAMERA_STATES[number];
 export type BoothUploadState = typeof UPLOAD_STATES[number];
@@ -52,40 +67,13 @@ export type BoothOperationalState = {
 export type BoothOperationalStateInput = Pick<BoothOperationalState, "paused" | "messages">;
 
 export function parseBoothHeartbeat(value: unknown): BoothHeartbeatInput | null {
-  const record = parseRecord(value, [
-    "version",
-    "deviceId",
-    "sessionStartedAt",
-    "pendingCount",
-    "durableStorage",
-    "online",
-    "installed",
-    "camera",
-    "upload",
-    "lastSuccessfulUploadAt",
-    "errorClass",
-    "buildId",
-  ]);
+  const record = parseRecord(value, HEARTBEAT_INPUT_KEYS);
   if (!record) return null;
   return parseHeartbeatFields(record);
 }
 
 export function parseBoothHeartbeatRecord(value: unknown): BoothHeartbeatRecord | null {
-  const record = parseRecord(value, [
-    "version",
-    "deviceId",
-    "sessionStartedAt",
-    "pendingCount",
-    "durableStorage",
-    "online",
-    "installed",
-    "camera",
-    "upload",
-    "lastSuccessfulUploadAt",
-    "errorClass",
-    "buildId",
-    "lastSeenAt",
-  ]);
+  const record = parseRecord(value, HEARTBEAT_RECORD_KEYS);
   if (!record || !isIsoTimestamp(record.lastSeenAt)) return null;
   const heartbeat = parseHeartbeatFields(record);
   return heartbeat ? { ...heartbeat, lastSeenAt: record.lastSeenAt } : null;
@@ -164,7 +152,9 @@ function parseMessages(value: unknown): Record<string, string> | null | undefine
     entries.length > 20
     || entries.some(([locale, message]) => !TOKEN.test(locale) || typeof message !== "string" || message.length > 280)
   ) return null;
-  return Object.fromEntries(entries as [string, string][]);
+  const messages = Object.create(null) as Record<string, string>;
+  for (const [locale, message] of entries) messages[locale] = message as string;
+  return messages;
 }
 
 function parseRecord(value: unknown, allowedKeys: readonly string[]): Record<string, unknown> | null {
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 2405534..43dab66 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -6,6 +6,7 @@ import {
   ConfigRevisionNotFoundError,
   EventStore,
   InMemoryObjectStore,
+  InvalidEventSlugError,
   InvalidPhotoCursorError,
   InvalidStoredConfigRevisionError,
   eventConfigKey,
@@ -99,6 +100,55 @@ class InstrumentedStateStore extends InMemoryObjectStore {
   }
 }
 
+class BoothStateAccessStore extends InMemoryObjectStore {
+  readonly reads: string[] = [];
+  readonly writes: string[] = [];
+  readonly lists: ListOptions[] = [];
+
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    this.reads.push(key);
+    return super.get(key);
+  }
+
+  override async put(
+    key: string,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<void> {
+    this.writes.push(key);
+    return super.put(key, value);
+  }
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    this.lists.push({ ...options });
+    return super.list(options);
+  }
+}
+
+class LongBoothCursorStore extends InMemoryObjectStore {
+  readonly opaqueCursor = `r2:${"x".repeat(3_000)}`;
+
+  constructor(
+    private readonly boothPrefix: string,
+    private readonly firstKey: string
+  ) {
+    super();
+  }
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    if (options.prefix !== this.boothPrefix) return super.list(options);
+    if (options.cursor === undefined) {
+      const page = await super.list({ ...options, limit: 1 });
+      return { objects: page.objects, truncated: true, cursor: this.opaqueCursor };
+    }
+    if (options.cursor !== this.opaqueCursor) throw new Error("opaque cursor changed");
+    return super.list({
+      prefix: options.prefix,
+      startAfter: this.firstKey,
+      limit: options.limit,
+    });
+  }
+}
+
 class CrashAfterSuccessfulCasStore extends InMemoryObjectStore {
   private crashed = false;
 
@@ -1781,6 +1831,26 @@ describe("EventStore", () => {
     expect((await photos.list()).objects).toHaveLength(0);
   });
 
+  test("passes a long opaque storage cursor through unchanged", async () => {
+    const firstDevice = "018f0000-0000-4000-8000-000000000001";
+    const secondDevice = "018f0000-0000-4000-8000-000000000002";
+    const prefix = "events/launch/booths/";
+    const state = new LongBoothCursorStore(prefix, boothHeartbeatKey("launch", firstDevice));
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(firstDevice));
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(secondDevice));
+
+    const firstPage = await store.listBoothHeartbeats("launch", { limit: 1 });
+    expect(firstPage.cursor).toBe(state.opaqueCursor);
+    expect(firstPage.cursor!.length).toBeGreaterThan(2_048);
+
+    const secondPage = await store.listBoothHeartbeats("launch", {
+      limit: 1,
+      cursor: firstPage.cursor,
+    });
+    expect(secondPage.booths.map((record) => record.deviceId)).toEqual([secondDevice]);
+  });
+
   test("isolates heartbeats by Event and fails closed on malformed or future private records", async () => {
     const deviceId = "018f0000-0000-4000-8000-000000000001";
     const photos = new InMemoryObjectStore();
@@ -1836,4 +1906,59 @@ describe("EventStore", () => {
     state.set(boothOperationalStateKey("other"), JSON.stringify({ version: 2, paused: false, updatedAt: now.toISOString() }));
     await expect(store.readBoothOperationalState("other")).rejects.toThrow("booth operational state");
   });
+
+  test("rejects non-canonical Events before any Booth STATE access", async () => {
+    const input = boothHeartbeat("018f0000-0000-4000-8000-000000000001");
+
+    for (const event of ["Launch 2026", "launch--2026", "launch/nested"]) {
+      const state = new BoothStateAccessStore();
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      const results = await Promise.allSettled([
+        store.writeBoothHeartbeat(event, input),
+        store.listBoothHeartbeats(event, {}),
+        store.readBoothOperationalState(event),
+        store.writeBoothOperationalState(event, { paused: true }),
+      ]);
+
+      expect(results.map((result) => result.status)).toEqual([
+        "rejected",
+        "rejected",
+        "rejected",
+        "rejected",
+      ]);
+      for (const result of results) {
+        if (result.status === "rejected") {
+          expect(result.reason).toBeInstanceOf(InvalidEventSlugError);
+        }
+      }
+      expect(state.reads).toEqual([]);
+      expect(state.writes).toEqual([]);
+      expect(state.lists).toEqual([]);
+    }
+  });
+
+  test("round-trips sensitive locale names with own-property semantics", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    const messages = {
+      constructor: "Constructor locale",
+      prototype: "Prototype locale",
+      toString: "String locale",
+    };
+
+    const written = await store.writeBoothOperationalState("launch", { paused: true, messages });
+    expect(Object.getPrototypeOf(written.messages!)).toBeNull();
+    expect(Object.keys(written.messages!)).toEqual(Object.keys(messages));
+    const stored = await (await state.get(boothOperationalStateKey("launch")))!.json<{
+      messages: Record<string, string>;
+    }>();
+    expect(stored.messages).toEqual(messages);
+
+    const roundTripped = await store.readBoothOperationalState("launch");
+    expect(Object.getPrototypeOf(roundTripped.messages!)).toBeNull();
+    for (const key of Object.keys(messages)) {
+      expect(Object.hasOwn(roundTripped.messages!, key)).toBe(true);
+      expect(roundTripped.messages![key]).toBe(messages[key as keyof typeof messages]);
+    }
+  });
 });
diff --git a/app/event-store.ts b/app/event-store.ts
index 726c2c7..39b8ed9 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -25,8 +25,9 @@ import {
   type BoothOperationalState,
   type BoothOperationalStateInput,
 } from "./booth-control";
+import { canonicalEvent, InvalidEventSlugError, slugifyEvent } from "./event-identity";
 import type { StableCaptureIdentity, StableUpload } from "./upload-contract";
-export { canonicalEvent, InvalidEventSlugError, slugifyEvent } from "./event-identity";
+export { canonicalEvent, InvalidEventSlugError, slugifyEvent };
 export { EVENT_CONFIG_VERSION };
 export type { EventConfig } from "./event-config";
 export const HEALTH_CANARY_KEY = "_health/canary";
@@ -606,10 +607,11 @@ export class EventStore {
   }
 
   async writeBoothHeartbeat(event: string, input: BoothHeartbeatInput): Promise<BoothHeartbeatRecord> {
+    const canonical = canonicalEvent(event);
     const heartbeat = parseBoothHeartbeat(input);
     if (!heartbeat) throw new TypeError("invalid booth heartbeat");
     const record: BoothHeartbeatRecord = { ...heartbeat, lastSeenAt: this.now().toISOString() };
-    await this.state.put(boothHeartbeatKey(event, record.deviceId), JSON.stringify(record), jsonWriteOptions());
+    await this.state.put(boothHeartbeatKey(canonical, record.deviceId), JSON.stringify(record), jsonWriteOptions());
     return record;
   }
 
@@ -617,22 +619,23 @@ export class EventStore {
     event: string,
     options: BoothHeartbeatListOptions = {}
   ): Promise<BoothHeartbeatPage> {
+    const canonical = canonicalEvent(event);
     const limit = options.limit ?? 50;
     if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
       throw new TypeError("booth heartbeat limit must be an integer from 1 to 100");
     }
     const cursor = options.cursor ?? undefined;
-    if (cursor !== undefined && (typeof cursor !== "string" || cursor.length === 0 || cursor.length > 2048)) {
+    if (cursor !== undefined && (typeof cursor !== "string" || cursor.trim().length === 0)) {
       throw new TypeError("booth heartbeat cursor is invalid");
     }
     const page = await this.state.list({
-      prefix: boothHeartbeatPrefix(event),
+      prefix: boothHeartbeatPrefix(canonical),
       ...(cursor !== undefined ? { cursor } : {}),
       limit,
     });
     const now = this.now().getTime();
     const booths = await Promise.all(page.objects.map(async (object): Promise<AdminBoothRecord> => {
-      const record = await this.readBoothHeartbeat(event, object.key);
+      const record = await this.readBoothHeartbeat(canonical, object.key);
       return {
         ...record,
         stale: now - Date.parse(record.lastSeenAt) >= BOOTH_STALE_AFTER_MS,
@@ -642,7 +645,8 @@ export class EventStore {
   }
 
   async readBoothOperationalState(event: string): Promise<BoothOperationalState> {
-    const object = await this.state.get(boothOperationalStateKey(event));
+    const canonical = canonicalEvent(event);
+    const object = await this.state.get(boothOperationalStateKey(canonical));
     if (!object) {
       return { version: 1, paused: false, updatedAt: this.now().toISOString() };
     }
@@ -650,10 +654,10 @@ export class EventStore {
     try {
       value = await object.json<unknown>();
     } catch {
-      throw new InvalidStoredBoothOperationalStateError(event);
+      throw new InvalidStoredBoothOperationalStateError(canonical);
     }
     const state = parseBoothOperationalState(value);
-    if (!state) throw new InvalidStoredBoothOperationalStateError(event);
+    if (!state) throw new InvalidStoredBoothOperationalStateError(canonical);
     return state;
   }
 
@@ -661,6 +665,7 @@ export class EventStore {
     event: string,
     input: BoothOperationalStateInput
   ): Promise<BoothOperationalState> {
+    const canonical = canonicalEvent(event);
     const operational = parseBoothOperationalStateInput(input);
     if (!operational) throw new TypeError("invalid booth operational state");
     const state: BoothOperationalState = {
@@ -668,7 +673,7 @@ export class EventStore {
       ...operational,
       updatedAt: this.now().toISOString(),
     };
-    await this.state.put(boothOperationalStateKey(event), JSON.stringify(state), jsonWriteOptions());
+    await this.state.put(boothOperationalStateKey(canonical), JSON.stringify(state), jsonWriteOptions());
     return state;
   }
 

From e64481dbd55c1827bc4f32c9c1c463b23c4cae14 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:41:30 +0800
Subject: [PATCH 039/105] fix: preserve opaque booth cursors

---
 app/event-store.test.ts | 30 ++++++++++++++++++++++++++++--
 app/event-store.ts      |  2 +-
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 43dab66..fc25a48 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -125,13 +125,15 @@ class BoothStateAccessStore extends InMemoryObjectStore {
 }
 
 class LongBoothCursorStore extends InMemoryObjectStore {
-  readonly opaqueCursor = `r2:${"x".repeat(3_000)}`;
+  readonly opaqueCursor: string;
 
   constructor(
     private readonly boothPrefix: string,
-    private readonly firstKey: string
+    private readonly firstKey: string,
+    opaqueCursor = `r2:${"x".repeat(3_000)}`
   ) {
     super();
+    this.opaqueCursor = opaqueCursor;
   }
 
   override async list(options: ListOptions = {}): Promise<ListResult> {
@@ -1851,6 +1853,30 @@ describe("EventStore", () => {
     expect(secondPage.booths.map((record) => record.deviceId)).toEqual([secondDevice]);
   });
 
+  test("passes a whitespace-only opaque storage cursor through unchanged", async () => {
+    const firstDevice = "018f0000-0000-4000-8000-000000000001";
+    const secondDevice = "018f0000-0000-4000-8000-000000000002";
+    const prefix = "events/launch/booths/";
+    const whitespaceCursor = " \t\n ";
+    const state = new LongBoothCursorStore(
+      prefix,
+      boothHeartbeatKey("launch", firstDevice),
+      whitespaceCursor
+    );
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(firstDevice));
+    await store.writeBoothHeartbeat("launch", boothHeartbeat(secondDevice));
+
+    const firstPage = await store.listBoothHeartbeats("launch", { limit: 1 });
+    expect(firstPage.cursor).toBe(whitespaceCursor);
+
+    const secondPage = await store.listBoothHeartbeats("launch", {
+      limit: 1,
+      cursor: firstPage.cursor,
+    });
+    expect(secondPage.booths.map((record) => record.deviceId)).toEqual([secondDevice]);
+  });
+
   test("isolates heartbeats by Event and fails closed on malformed or future private records", async () => {
     const deviceId = "018f0000-0000-4000-8000-000000000001";
     const photos = new InMemoryObjectStore();
diff --git a/app/event-store.ts b/app/event-store.ts
index 39b8ed9..98a05ec 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -625,7 +625,7 @@ export class EventStore {
       throw new TypeError("booth heartbeat limit must be an integer from 1 to 100");
     }
     const cursor = options.cursor ?? undefined;
-    if (cursor !== undefined && (typeof cursor !== "string" || cursor.trim().length === 0)) {
+    if (cursor !== undefined && (typeof cursor !== "string" || cursor.length === 0)) {
       throw new TypeError("booth heartbeat cursor is invalid");
     }
     const page = await this.state.list({

From b704a6f0cc7e34d5cd5b156d9b8ff86f027b8170 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:37:27 +0800
Subject: [PATCH 040/105] feat: expose booth control APIs

---
 app/api/booth-state/route.ts     |  22 +++
 app/api/booth/handlers.test.ts   | 308 +++++++++++++++++++++++++++++++
 app/api/booth/handlers.ts        | 226 +++++++++++++++++++++++
 app/api/booth/preflight/route.ts |  14 ++
 app/api/booths/route.ts          |  22 +++
 app/event-config.test.ts         |  13 ++
 app/event-config.ts              |  16 ++
 7 files changed, 621 insertions(+)
 create mode 100644 app/api/booth-state/route.ts
 create mode 100644 app/api/booth/handlers.test.ts
 create mode 100644 app/api/booth/handlers.ts
 create mode 100644 app/api/booth/preflight/route.ts
 create mode 100644 app/api/booths/route.ts

diff --git a/app/api/booth-state/route.ts b/app/api/booth-state/route.ts
new file mode 100644
index 0000000..18103b5
--- /dev/null
+++ b/app/api/booth-state/route.ts
@@ -0,0 +1,22 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { getBoothState, putBoothState } from "../booth/handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return getBoothState(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
+
+export async function PUT(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return putBoothState(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/booth/handlers.test.ts b/app/api/booth/handlers.test.ts
new file mode 100644
index 0000000..5405ca1
--- /dev/null
+++ b/app/api/booth/handlers.test.ts
@@ -0,0 +1,308 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import {
+  EventStore,
+  InMemoryObjectStore,
+  type BoothHeartbeatListOptions,
+  type BoothHeartbeatPage,
+} from "@/app/event-store";
+import { hashBoothKey } from "@/app/upload-auth";
+import {
+  getBoothHeartbeats,
+  getBoothState,
+  postBoothHeartbeat,
+  postBoothPreflight,
+  putBoothState,
+  type BoothControlHandlerDeps,
+} from "./handlers";
+
+const ADMIN_KEY = "admin-secret";
+const BOOTH_KEY = "event-key-123";
+const NOW = "2026-07-24T00:00:00.000Z";
+
+const heartbeat = {
+  version: 1,
+  deviceId: "018f0000-0000-4000-8000-000000000001",
+  sessionStartedAt: 1753315200000,
+  pendingCount: 2,
+  durableStorage: true,
+  online: true,
+  installed: true,
+  camera: "ready",
+  upload: "retry-wait",
+  buildId: "release_1",
+} as const;
+
+type RequestOptions = {
+  method?: string;
+  headers?: HeadersInit;
+  body?: unknown;
+};
+
+function request(path: string, init: RequestOptions = {}): NextRequest {
+  const { body, headers, method } = init;
+  return new NextRequest(`https://app.test${path}`, {
+    ...(method ? { method } : {}),
+    headers: {
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+      ...headers,
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+}
+
+function controlDeps(options: { adminKey?: string } = {}) {
+  const state = new InMemoryObjectStore();
+  const store = new EventStore(
+    new InMemoryObjectStore(),
+    state,
+    "https://photos.example",
+    () => new Date(NOW)
+  );
+  return {
+    state,
+    deps: {
+      store,
+      adminKey: "adminKey" in options ? options.adminKey : ADMIN_KEY,
+    } satisfies BoothControlHandlerDeps,
+  };
+}
+
+async function configuredDeps() {
+  const controls = controlDeps();
+  await controls.deps.store.writeConfig("launch", {
+    frames: ["square"],
+    boothKeyHash: await hashBoothKey(BOOTH_KEY),
+    currentRevisionId: "018f0000-0000-4000-8000-000000000001",
+  });
+  return controls;
+}
+
+class OpaqueCursorStore extends EventStore {
+  receivedOptions: BoothHeartbeatListOptions | undefined;
+
+  override async listBoothHeartbeats(
+    _event: string,
+    options: BoothHeartbeatListOptions = {}
+  ): Promise<BoothHeartbeatPage> {
+    this.receivedOptions = options;
+    return { booths: [], cursor: "store-issued" };
+  }
+}
+
+describe("Booth control handlers", () => {
+  test("preflight accepts a matching Booth Key or the Admin Key", async () => {
+    const controls = await configuredDeps();
+    await controls.deps.store.writeBoothOperationalState("launch", {
+      paused: true,
+      messages: { en: "A brief pause" },
+    });
+
+    const booth = await postBoothPreflight(request("/api/booth/preflight?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": BOOTH_KEY },
+    }), controls.deps);
+    const admin = await postBoothPreflight(request("/api/booth/preflight?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+    }), controls.deps);
+
+    const boothBody = await booth.json() as {
+      experience: unknown;
+      operationalState: unknown;
+      serverTime: string;
+    };
+    expect(booth.status).toBe(200);
+    expect(boothBody).toMatchObject({
+      experience: { frames: ["square"] },
+      operationalState: {
+        version: 1,
+        paused: true,
+        messages: { en: "A brief pause" },
+        updatedAt: NOW,
+      },
+    });
+    expect(boothBody.serverTime).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    expect(admin.status).toBe(200);
+  });
+
+  test("preflight fails closed when the Admin Key is unavailable", async () => {
+    const previous = process.env.ALLOW_KEYLESS;
+    delete process.env.ALLOW_KEYLESS;
+    try {
+      const controls = controlDeps({ adminKey: undefined });
+      await controls.deps.store.writeConfig("launch", {
+        frames: ["square"],
+        boothKeyHash: await hashBoothKey(BOOTH_KEY),
+      });
+
+      const response = await postBoothPreflight(request("/api/booth/preflight?event=launch", {
+        method: "POST",
+        headers: { "x-booth-key": BOOTH_KEY },
+      }), controls.deps);
+
+      expect(response.status).toBe(503);
+    } finally {
+      if (previous === undefined) delete process.env.ALLOW_KEYLESS;
+      else process.env.ALLOW_KEYLESS = previous;
+    }
+  });
+
+  test("preflight rejects an incorrect credential", async () => {
+    const controls = await configuredDeps();
+
+    const response = await postBoothPreflight(request("/api/booth/preflight?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": "wrong-key" },
+    }), controls.deps);
+
+    expect(response.status).toBe(401);
+  });
+
+  test("preflight reports Events without an enabled experience as unavailable", async () => {
+    const missing = controlDeps();
+    const zeroFrames = controlDeps();
+    await zeroFrames.deps.store.writeConfig("launch", { frames: [] });
+
+    expect((await postBoothPreflight(request("/api/booth/preflight?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+    }), missing.deps)).status).toBe(409);
+    expect((await postBoothPreflight(request("/api/booth/preflight?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+    }), zeroFrames.deps)).status).toBe(409);
+  });
+
+  test("preflight exposes no private configuration fields", async () => {
+    const controls = await configuredDeps();
+    const response = await postBoothPreflight(request("/api/booth/preflight?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+    }), controls.deps);
+    const body = await response.json();
+
+    expect(Object.keys(body)).toEqual(["experience", "operationalState", "serverTime"]);
+    expect(JSON.stringify(body)).not.toContain("boothKeyHash");
+    expect(JSON.stringify(body)).not.toContain("currentRevisionId");
+  });
+
+  test("heartbeat rejects unknown or unbounded fields before writing", async () => {
+    const controls = controlDeps();
+    const unknown = await postBoothHeartbeat(request("/api/booths?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+      body: { ...heartbeat, unexpected: true },
+    }), controls.deps);
+    const unbounded = await postBoothHeartbeat(request("/api/booths?event=launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+      body: { ...heartbeat, buildId: "x".repeat(129) },
+    }), controls.deps);
+
+    expect(unknown.status).toBe(400);
+    expect(unbounded.status).toBe(400);
+    expect((await controls.state.list()).objects).toEqual([]);
+  });
+
+  test("a Booth Key cannot write a heartbeat for another Event", async () => {
+    const controls = await configuredDeps();
+    const response = await postBoothHeartbeat(request("/api/booths?event=other", {
+      method: "POST",
+      headers: { "x-booth-key": BOOTH_KEY },
+      body: heartbeat,
+    }), controls.deps);
+
+    expect(response.status).toBe(401);
+    expect((await controls.state.list({ prefix: "events/other/" })).objects).toEqual([]);
+  });
+
+  test("device listing and pause mutation require the Admin Key", async () => {
+    const controls = await configuredDeps();
+    await controls.deps.store.writeBoothHeartbeat("launch", heartbeat);
+
+    const list = await getBoothHeartbeats(request("/api/booths?event=launch", {
+      headers: { "x-booth-key": BOOTH_KEY },
+    }), controls.deps);
+    const pause = await putBoothState(request("/api/booth-state?event=launch", {
+      method: "PUT",
+      headers: { "x-booth-key": BOOTH_KEY },
+      body: { paused: true },
+    }), controls.deps);
+
+    expect(list.status).toBe(401);
+    expect(pause.status).toBe(401);
+    expect(await controls.deps.store.readBoothOperationalState("launch")).toEqual({
+      version: 1,
+      paused: false,
+      updatedAt: NOW,
+    });
+  });
+
+  test("device listing preserves a long opaque store cursor", async () => {
+    const opaqueCursor = `opaque.${"x".repeat(2049)}`;
+    const store = new OpaqueCursorStore(
+      new InMemoryObjectStore(),
+      new InMemoryObjectStore(),
+      "https://photos.example"
+    );
+    const response = await getBoothHeartbeats(request(
+      `/api/booths?event=launch&cursor=${encodeURIComponent(opaqueCursor)}`,
+      { headers: { "x-booth-key": ADMIN_KEY } }
+    ), { store, adminKey: ADMIN_KEY });
+
+    expect(response.status).toBe(200);
+    expect(store.receivedOptions).toEqual({ cursor: opaqueCursor });
+    expect(await response.json()).toEqual({ booths: [], cursor: "store-issued" });
+  });
+
+  test("public pause reads are no-store and contain no device or configuration data", async () => {
+    const controls = await configuredDeps();
+    await controls.deps.store.writeBoothHeartbeat("launch", heartbeat);
+    await controls.deps.store.writeBoothOperationalState("launch", {
+      paused: true,
+      messages: { en: "A brief pause" },
+    });
+
+    const response = await getBoothState(request("/api/booth-state?event=launch"), controls.deps);
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Cache-Control")).toBe("no-store");
+    expect(body).toEqual({
+      version: 1,
+      paused: true,
+      messages: { en: "A brief pause" },
+      updatedAt: NOW,
+    });
+    expect(JSON.stringify(body)).not.toContain("deviceId");
+    expect(JSON.stringify(body)).not.toContain("boothKeyHash");
+    expect(JSON.stringify(body)).not.toContain("currentRevisionId");
+  });
+
+  test("all Booth control handlers reject canonical Event aliases", async () => {
+    const controls = controlDeps();
+    const preflight = await postBoothPreflight(request("/api/booth/preflight?event=Launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+    }), controls.deps);
+    const heartbeatResponse = await postBoothHeartbeat(request("/api/booths?event=Launch", {
+      method: "POST",
+      headers: { "x-booth-key": ADMIN_KEY },
+      body: heartbeat,
+    }), controls.deps);
+    const list = await getBoothHeartbeats(request("/api/booths?event=Launch", {
+      headers: { "x-booth-key": ADMIN_KEY },
+    }), controls.deps);
+    const state = await getBoothState(request("/api/booth-state?event=Launch"), controls.deps);
+    const put = await putBoothState(request("/api/booth-state?event=Launch", {
+      method: "PUT",
+      headers: { "x-booth-key": ADMIN_KEY },
+      body: { paused: true },
+    }), controls.deps);
+
+    expect([preflight, heartbeatResponse, list, state, put].map((response) => response.status)).toEqual([
+      400, 400, 400, 400, 400,
+    ]);
+  });
+});
diff --git a/app/api/booth/handlers.ts b/app/api/booth/handlers.ts
new file mode 100644
index 0000000..e4afc8a
--- /dev/null
+++ b/app/api/booth/handlers.ts
@@ -0,0 +1,226 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  EventStore,
+  InvalidEventSlugError,
+} from "@/app/event-store";
+import {
+  parseBoothHeartbeat,
+  parseBoothOperationalStateInput,
+} from "@/app/booth-control";
+import { projectEventExperience } from "@/app/event-config";
+import { adminOk, boothOrAdminOk } from "@/app/upload-auth";
+
+export type BoothControlHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+};
+
+const MAX_EVENT_LENGTH = 128;
+const MAX_BODY_BYTES = 16 * 1024;
+
+type BoothListQuery = { event: string; cursor?: string; limit?: number };
+type JsonBody = { value: unknown } | { response: NextResponse };
+
+const jsonError = (error: string, status: number) =>
+  NextResponse.json({ error }, { status });
+
+function hasOnlyQueryKeys(params: URLSearchParams, allowed: readonly string[]): boolean {
+  return Array.from(params.keys()).every((key) => allowed.includes(key))
+    && allowed.every((key) => params.getAll(key).length <= 1);
+}
+
+function eventFrom(req: NextRequest, allowedQueryKeys: readonly string[]): string | NextResponse {
+  const params = req.nextUrl.searchParams;
+  if (!hasOnlyQueryKeys(params, allowedQueryKeys)) {
+    return jsonError("invalid Booth control query", 400);
+  }
+
+  const raw = params.get("event");
+  if (raw !== null && raw.length > MAX_EVENT_LENGTH) {
+    return jsonError("invalid Booth control Event", 400);
+  }
+  try {
+    return canonicalEvent(raw);
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) return jsonError(error.message, 400);
+    throw error;
+  }
+}
+
+function listQueryFrom(req: NextRequest): BoothListQuery | NextResponse {
+  const event = eventFrom(req, ["event", "cursor", "limit"]);
+  if (event instanceof NextResponse) return event;
+  const { searchParams } = req.nextUrl;
+  const rawCursor = searchParams.get("cursor");
+  const rawLimit = searchParams.get("limit");
+  if (rawCursor !== null && rawCursor.length === 0) {
+    return jsonError("invalid Booth heartbeat cursor", 400);
+  }
+  if (rawLimit !== null && !/^(?:[1-9]|[1-9][0-9]|100)$/.test(rawLimit)) {
+    return jsonError("invalid Booth heartbeat limit", 400);
+  }
+  return {
+    event,
+    ...(rawCursor !== null ? { cursor: rawCursor } : {}),
+    ...(rawLimit !== null ? { limit: Number(rawLimit) } : {}),
+  };
+}
+
+function requireConfiguredAdmin(req: NextRequest, deps: BoothControlHandlerDeps): NextResponse | null {
+  // Unlike local upload convenience, control-plane mutations and unlock
+  // preflight never become keyless. A missing Worker secret is unavailable.
+  if (!deps.adminKey) return jsonError("Booth control disabled: no key configured", 503);
+  return adminOk(req.headers.get("x-booth-key") ?? "", deps.adminKey) === "ok"
+    ? null
+    : jsonError("unauthorized", 401);
+}
+
+async function parseJsonBody(req: NextRequest): Promise<JsonBody> {
+  const contentLength = req.headers.get("content-length");
+  if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > MAX_BODY_BYTES)) {
+    return { response: jsonError("Booth control body is too large", 413) };
+  }
+  const text = await req.text();
+  if (new TextEncoder().encode(text).byteLength > MAX_BODY_BYTES) {
+    return { response: jsonError("Booth control body is too large", 413) };
+  }
+  try {
+    return { value: JSON.parse(text) };
+  } catch {
+    return { response: jsonError("invalid Booth control request", 400) };
+  }
+}
+
+async function requireEmptyBody(req: NextRequest): Promise<NextResponse | null> {
+  const contentLength = req.headers.get("content-length");
+  if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > MAX_BODY_BYTES)) {
+    return jsonError("Booth control body is too large", 413);
+  }
+  const text = await req.text();
+  if (new TextEncoder().encode(text).byteLength > MAX_BODY_BYTES) {
+    return jsonError("Booth control body is too large", 413);
+  }
+  return text.length === 0 ? null : jsonError("Booth control request body is not allowed", 400);
+}
+
+async function authorizeBooth(
+  req: NextRequest,
+  deps: BoothControlHandlerDeps,
+  boothKeyHash?: string
+): Promise<NextResponse | null> {
+  if (!deps.adminKey) return jsonError("Booth control disabled: no key configured", 503);
+  const auth = await boothOrAdminOk(
+    req.headers.get("x-booth-key") ?? "",
+    deps.adminKey,
+    boothKeyHash
+  );
+  if (auth === "ok") return null;
+  if (auth === "disabled") return jsonError("Booth control disabled: no key configured", 503);
+  return jsonError("unauthorized", 401);
+}
+
+/** Authenticated, safe readiness contract for a Booth before it starts capture. */
+export async function postBoothPreflight(
+  req: NextRequest,
+  deps: BoothControlHandlerDeps
+): Promise<NextResponse> {
+  const event = eventFrom(req, ["event"]);
+  if (event instanceof NextResponse) return event;
+  const bodyError = await requireEmptyBody(req);
+  if (bodyError) return bodyError;
+
+  if (!deps.adminKey) return jsonError("Booth control disabled: no key configured", 503);
+  const config = await deps.store.readConfig(event);
+  const authError = await authorizeBooth(req, deps, config?.boothKeyHash);
+  if (authError) return authError;
+  if (!config || config.frames.length === 0) {
+    return jsonError("Booth Event has no enabled Frames", 409);
+  }
+
+  const operationalState = await deps.store.readBoothOperationalState(event);
+  return NextResponse.json({
+    experience: projectEventExperience(config),
+    operationalState,
+    serverTime: new Date().toISOString(),
+  });
+}
+
+/** Accepts the tightly allowlisted private status snapshot from one Booth. */
+export async function postBoothHeartbeat(
+  req: NextRequest,
+  deps: BoothControlHandlerDeps
+): Promise<NextResponse> {
+  const event = eventFrom(req, ["event"]);
+  if (event instanceof NextResponse) return event;
+  if (!deps.adminKey) return jsonError("Booth control disabled: no key configured", 503);
+
+  // Validate before resolving an Event Booth Key: readConfig() can perform a
+  // lazy legacy migration, so invalid input must not cause a STATE write.
+  const body = await parseJsonBody(req);
+  if ("response" in body) return body.response;
+  const heartbeat = parseBoothHeartbeat(body.value);
+  if (!heartbeat) return jsonError("invalid Booth heartbeat", 400);
+
+  let authError = await authorizeBooth(req, deps);
+  if (authError && authError.status === 401) {
+    const config = await deps.store.readConfig(event);
+    authError = await authorizeBooth(req, deps, config?.boothKeyHash);
+  }
+  if (authError) return authError;
+
+  return NextResponse.json(await deps.store.writeBoothHeartbeat(event, heartbeat));
+}
+
+/** Admin-only paginated view of private Booth heartbeat records. */
+export async function getBoothHeartbeats(
+  req: NextRequest,
+  deps: BoothControlHandlerDeps
+): Promise<NextResponse> {
+  const query = listQueryFrom(req);
+  if (query instanceof NextResponse) return query;
+  const bodyError = await requireEmptyBody(req);
+  if (bodyError) return bodyError;
+  const adminError = requireConfiguredAdmin(req, deps);
+  if (adminError) return adminError;
+
+  return NextResponse.json(await deps.store.listBoothHeartbeats(query.event, {
+    ...(query.cursor !== undefined ? { cursor: query.cursor } : {}),
+    ...(query.limit !== undefined ? { limit: query.limit } : {}),
+  }));
+}
+
+/** Public pause/message state only; device and configuration state remain private. */
+export async function getBoothState(
+  req: NextRequest,
+  deps: BoothControlHandlerDeps
+): Promise<NextResponse> {
+  const event = eventFrom(req, ["event"]);
+  if (event instanceof NextResponse) return event;
+  const bodyError = await requireEmptyBody(req);
+  if (bodyError) return bodyError;
+
+  return NextResponse.json(await deps.store.readBoothOperationalState(event), {
+    headers: { "Cache-Control": "no-store" },
+  });
+}
+
+/** Admin-only replacement of the safe, bounded public operational state. */
+export async function putBoothState(
+  req: NextRequest,
+  deps: BoothControlHandlerDeps
+): Promise<NextResponse> {
+  const event = eventFrom(req, ["event"]);
+  if (event instanceof NextResponse) return event;
+  const adminError = requireConfiguredAdmin(req, deps);
+  if (adminError) return adminError;
+
+  const body = await parseJsonBody(req);
+  if ("response" in body) return body.response;
+  const operationalState = parseBoothOperationalStateInput(body.value);
+  if (!operationalState) return jsonError("invalid Booth operational state", 400);
+
+  return NextResponse.json(await deps.store.writeBoothOperationalState(event, operationalState), {
+    headers: { "Cache-Control": "no-store" },
+  });
+}
diff --git a/app/api/booth/preflight/route.ts b/app/api/booth/preflight/route.ts
new file mode 100644
index 0000000..aa84db1
--- /dev/null
+++ b/app/api/booth/preflight/route.ts
@@ -0,0 +1,14 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { postBoothPreflight } from "../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return postBoothPreflight(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/booths/route.ts b/app/api/booths/route.ts
new file mode 100644
index 0000000..96a4575
--- /dev/null
+++ b/app/api/booths/route.ts
@@ -0,0 +1,22 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { getBoothHeartbeats, postBoothHeartbeat } from "../booth/handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return postBoothHeartbeat(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
+
+export async function GET(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return getBoothHeartbeats(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/event-config.test.ts b/app/event-config.test.ts
index 97397dd..ca8814d 100644
--- a/app/event-config.test.ts
+++ b/app/event-config.test.ts
@@ -3,6 +3,7 @@ import {
   isRevisionId,
   parseConfigRevision,
   parseEventConfig,
+  projectEventExperience,
   projectPublicConfig,
 } from "./event-config";
 
@@ -56,6 +57,18 @@ describe("event config schema", () => {
     expect(projectPublicConfig(null)).toEqual({ frames: null, hasBoothKey: false });
   });
 
+  test("projects a Booth experience without private configuration fields", () => {
+    const projected = projectEventExperience({
+      frames: ["square"],
+      boothKeyHash: "salt:hash",
+      currentRevisionId: "018f0000-0000-4000-8000-000000000001",
+    });
+
+    expect(projected).toEqual({ frames: ["square"] });
+    expect(JSON.stringify(projected)).not.toContain("boothKeyHash");
+    expect(JSON.stringify(projected)).not.toContain("currentRevisionId");
+  });
+
   test("revision parsing rejects credentials inside experience", () => {
     const base = {
       version: 1,
diff --git a/app/event-config.ts b/app/event-config.ts
index 4e80049..085d831 100644
--- a/app/event-config.ts
+++ b/app/event-config.ts
@@ -141,3 +141,19 @@ export function projectPublicConfig(config: EventConfig | null): PublicEventConf
     ...(gallery ? { gallery } : {}),
   };
 }
+
+/**
+ * The Booth preflight contract intentionally has a smaller projection than
+ * operator-facing config: credentials and revision bookkeeping never leave
+ * private Event state.
+ */
+export function projectEventExperience(config: EventConfig): EventExperience {
+  return {
+    frames: [...config.frames],
+    ...(config.locales ? { locales: [...config.locales] } : {}),
+    ...(config.defaultLocale ? { defaultLocale: config.defaultLocale } : {}),
+    ...(config.timeZone ? { timeZone: config.timeZone } : {}),
+    ...(config.capture ? { capture: { ...config.capture } } : {}),
+    ...(config.gallery ? { gallery: { ...config.gallery } } : {}),
+  };
+}

From df1a15872820b2357a48ab36819ab1e1db64ba58 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:43:41 +0800
Subject: [PATCH 041/105] test: cover booth control boundaries

---
 app/api/booth/handlers.test.ts | 199 +++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)

diff --git a/app/api/booth/handlers.test.ts b/app/api/booth/handlers.test.ts
index 5405ca1..8893ad9 100644
--- a/app/api/booth/handlers.test.ts
+++ b/app/api/booth/handlers.test.ts
@@ -51,6 +51,22 @@ function request(path: string, init: RequestOptions = {}): NextRequest {
   });
 }
 
+function rawJsonRequest(
+  path: string,
+  method: "POST" | "PUT",
+  body: string,
+  key = ADMIN_KEY
+): NextRequest {
+  return new NextRequest(`https://app.test${path}`, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      "x-booth-key": key,
+    },
+    body,
+  });
+}
+
 function controlDeps(options: { adminKey?: string } = {}) {
   const state = new InMemoryObjectStore();
   const store = new EventStore(
@@ -90,7 +106,190 @@ class OpaqueCursorStore extends EventStore {
   }
 }
 
+type QueryHandlerCase = {
+  name: string;
+  missingAdminRegression?: boolean;
+  wrongCredentialRegression?: boolean;
+  invoke: (
+    query: string,
+    deps: BoothControlHandlerDeps,
+    key?: string
+  ) => Promise<Response>;
+};
+
+const queryHandlerCases: QueryHandlerCase[] = [
+  {
+    name: "preflight",
+    wrongCredentialRegression: true,
+    invoke: (query, deps, key = ADMIN_KEY) => postBoothPreflight(request(
+      `/api/booth/preflight?${query}`,
+      { method: "POST", headers: { "x-booth-key": key } }
+    ), deps),
+  },
+  {
+    name: "heartbeat",
+    missingAdminRegression: true,
+    wrongCredentialRegression: true,
+    invoke: (query, deps, key = ADMIN_KEY) => postBoothHeartbeat(request(
+      `/api/booths?${query}`,
+      { method: "POST", headers: { "x-booth-key": key }, body: heartbeat }
+    ), deps),
+  },
+  {
+    name: "Booth list",
+    missingAdminRegression: true,
+    wrongCredentialRegression: true,
+    invoke: (query, deps, key = ADMIN_KEY) => getBoothHeartbeats(request(
+      `/api/booths?${query}`,
+      { headers: { "x-booth-key": key } }
+    ), deps),
+  },
+  {
+    name: "public pause read",
+    invoke: (query, deps) => getBoothState(request(`/api/booth-state?${query}`), deps),
+  },
+  {
+    name: "pause mutation",
+    missingAdminRegression: true,
+    wrongCredentialRegression: true,
+    invoke: (query, deps, key = ADMIN_KEY) => putBoothState(request(
+      `/api/booth-state?${query}`,
+      { method: "PUT", headers: { "x-booth-key": key }, body: { paused: true } }
+    ), deps),
+  },
+];
+
+type JsonHandlerCase = {
+  name: string;
+  invoke: (req: NextRequest, deps: BoothControlHandlerDeps) => Promise<Response>;
+  method: "POST" | "PUT";
+  path: string;
+  oversizedBody: unknown;
+};
+
+const jsonHandlerCases: JsonHandlerCase[] = [
+  {
+    name: "heartbeat",
+    invoke: postBoothHeartbeat,
+    method: "POST",
+    path: "/api/booths?event=launch",
+    oversizedBody: { ...heartbeat, buildId: "x".repeat(16 * 1024) },
+  },
+  {
+    name: "pause mutation",
+    invoke: putBoothState,
+    method: "PUT",
+    path: "/api/booth-state?event=launch",
+    oversizedBody: { paused: true, messages: { en: "x".repeat(16 * 1024) } },
+  },
+];
+
 describe("Booth control handlers", () => {
+  for (const handlerCase of queryHandlerCases) {
+    test(`${handlerCase.name} rejects duplicate and unknown query keys`, async () => {
+      const controls = controlDeps();
+      const queries = [
+        "event=launch&event=launch",
+        "event=launch&unknown=value",
+      ];
+
+      for (const query of queries) {
+        expect((await handlerCase.invoke(query, controls.deps)).status).toBe(400);
+      }
+    });
+  }
+
+  test("Booth list rejects duplicate cursor and limit query keys", async () => {
+    const controls = controlDeps();
+    const queries = [
+      "event=launch&cursor=first&cursor=second",
+      "event=launch&limit=1&limit=100",
+    ];
+
+    for (const query of queries) {
+      expect((await getBoothHeartbeats(request(`/api/booths?${query}`, {
+        headers: { "x-booth-key": ADMIN_KEY },
+      }), controls.deps)).status).toBe(400);
+    }
+  });
+
+  for (const limit of [1, 100]) {
+    test(`Booth list accepts the exact ${limit} limit boundary`, async () => {
+      const store = new OpaqueCursorStore(
+        new InMemoryObjectStore(),
+        new InMemoryObjectStore(),
+        "https://photos.example"
+      );
+      const response = await getBoothHeartbeats(request(
+        `/api/booths?event=launch&limit=${limit}`,
+        { headers: { "x-booth-key": ADMIN_KEY } }
+      ), { store, adminKey: ADMIN_KEY });
+
+      expect(response.status).toBe(200);
+      expect(store.receivedOptions).toEqual({ limit });
+    });
+  }
+
+  for (const limit of ["0", "101", "-1", "1.5", "01", "invalid"]) {
+    test(`Booth list rejects out-of-range limit ${limit}`, async () => {
+      const controls = controlDeps();
+      const response = await getBoothHeartbeats(request(
+        `/api/booths?event=launch&limit=${encodeURIComponent(limit)}`,
+        { headers: { "x-booth-key": ADMIN_KEY } }
+      ), controls.deps);
+
+      expect(response.status).toBe(400);
+    });
+  }
+
+  for (const handlerCase of jsonHandlerCases) {
+    test(`${handlerCase.name} rejects malformed JSON with 400`, async () => {
+      const controls = controlDeps();
+      const response = await handlerCase.invoke(
+        rawJsonRequest(handlerCase.path, handlerCase.method, "{"),
+        controls.deps
+      );
+
+      expect(response.status).toBe(400);
+    });
+
+    test(`${handlerCase.name} rejects oversized JSON with 413`, async () => {
+      const controls = controlDeps();
+      const response = await handlerCase.invoke(request(handlerCase.path, {
+        method: handlerCase.method,
+        headers: { "x-booth-key": ADMIN_KEY },
+        body: handlerCase.oversizedBody,
+      }), controls.deps);
+
+      expect(response.status).toBe(413);
+    });
+  }
+
+  test("authenticated Booth handlers consistently fail closed without the Admin secret", async () => {
+    const previous = process.env.ALLOW_KEYLESS;
+    process.env.ALLOW_KEYLESS = "1";
+    try {
+      const controls = controlDeps({ adminKey: undefined });
+      const cases = queryHandlerCases.filter(({ missingAdminRegression }) => missingAdminRegression);
+
+      for (const handlerCase of cases) {
+        expect((await handlerCase.invoke("event=launch", controls.deps)).status).toBe(503);
+      }
+    } finally {
+      if (previous === undefined) delete process.env.ALLOW_KEYLESS;
+      else process.env.ALLOW_KEYLESS = previous;
+    }
+  });
+
+  test("authenticated Booth handlers reject wrong credentials", async () => {
+    const controls = await configuredDeps();
+    const cases = queryHandlerCases.filter(({ wrongCredentialRegression }) => wrongCredentialRegression);
+
+    for (const handlerCase of cases) {
+      expect((await handlerCase.invoke("event=launch", controls.deps, "wrong-key")).status).toBe(401);
+    }
+  });
+
   test("preflight accepts a matching Booth Key or the Admin Key", async () => {
     const controls = await configuredDeps();
     await controls.deps.store.writeBoothOperationalState("launch", {

From ef8a7d3316a84347ad084c0f2672835db2465615 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:56:28 +0800
Subject: [PATCH 042/105] feat: monitor booth operations in Admin

---
 app/[event]/admin/admin.module.css            |   8 +-
 .../admin/booth-operations-panel.test.tsx     | 163 +++++++++++++++
 app/[event]/admin/booth-operations-panel.tsx  | 145 +++++++++++++
 app/[event]/admin/booth-operations.test.ts    |  50 +++++
 app/[event]/admin/booth-operations.ts         |  40 ++++
 app/[event]/admin/page.tsx                    | 197 +++++++++++++++++-
 6 files changed, 593 insertions(+), 10 deletions(-)
 create mode 100644 app/[event]/admin/booth-operations-panel.test.tsx
 create mode 100644 app/[event]/admin/booth-operations-panel.tsx
 create mode 100644 app/[event]/admin/booth-operations.test.ts
 create mode 100644 app/[event]/admin/booth-operations.ts

diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index 538b265..f7d48fb 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -57,8 +57,10 @@
 .linkCard { display: grid; grid-template-columns: minmax(0, 1fr) 94px; gap: 12px; background: var(--ink); color: #fff; }.linkCard > div > span { color: var(--amber); font: 800 9px/1 ui-monospace, monospace; text-transform: uppercase; }.linkCard h2 { font-size: 25px; margin: 6px 0 10px; }.linkCard code { display: block; color: #d3cec4; font: 10px/1.35 ui-monospace, monospace; word-break: break-all; }.linkCard img { width: 94px; height: 94px; background: #fff; padding: 5px; }.linkActions { display: flex; gap: 5px; margin-top: 12px; }.linkActions a, .linkActions button { flex: 1; padding: 8px; text-align: center; background: transparent; color: #fff; border-color: #777; }.saveButton, .exportButton { width: 100%; padding: 14px; background: var(--pink); color: #fff; border: 0; }.exportButton { margin-top: 8px; color: var(--ink); background: var(--amber); }.saveButton:disabled, .exportButton:disabled { opacity: .5; cursor: wait; }
 .contactSheet { display: grid; grid-template-columns: repeat(auto-fill, minmax(155px, 1fr)); gap: 8px; padding-top: 15px; }.contactPhoto { position: relative; min-width: 0; padding: 7px; background: #fff; border: 1px solid #b2aea5; }.contactPhoto > img { display: block; width: 100%; aspect-ratio: 1; object-fit: cover; background: #ccc; }.contactPhoto > div:not(.deleteConfirm) { display: flex; justify-content: space-between; gap: 8px; padding-top: 7px; }.contactPhoto time { font: 800 10px/1 ui-monospace, monospace; }.contactPhoto code { overflow: hidden; text-overflow: ellipsis; font: 9px/1 ui-monospace, monospace; color: #777; }.removePhoto { width: 100%; margin-top: 7px; border: 0; padding: 6px; background: transparent; color: #b3154a; font: 700 10px/1 system-ui, sans-serif; cursor: pointer; }.deleteConfirm { position: absolute; inset: 7px; z-index: 3; display: flex; flex-direction: column; justify-content: center; gap: 7px; padding: 12px; color: #fff; background: rgba(16,16,16,.96); }.deleteConfirm span { font: 800 12px/1.3 system-ui, sans-serif; }.deleteConfirm button { padding: 7px; border: 1px solid #777; color: #fff; background: transparent; cursor: pointer; }.deleteConfirm button:first-of-type { color: #fff; background: #c51651; border-color: #c51651; }
 .failure, .emptySheet { padding: 28px; margin-top: 15px; border: 2px dashed #8c8880; background: rgba(255,255,255,.5); }.failure strong, .emptySheet strong { font: 900 22px/1 Impact, sans-serif; text-transform: uppercase; }.failure p, .emptySheet p { margin: 8px 0 14px; font-size: 13px; }.failure button { background: var(--amber); }
+.boothOperations { border-block: 2px solid var(--ink); padding-block: 18px; }.boothOperationsHead { display: flex; align-items: flex-end; justify-content: space-between; gap: 18px; }.boothOperationsHead h2 { margin-top: 8px; font: 900 clamp(30px, 4vw, 52px)/.9 Impact, "Arial Narrow", sans-serif; letter-spacing: -.02em; text-transform: uppercase; }.boothOperationsHead p { max-width: 52ch; margin-top: 8px; font-size: 13px; line-height: 1.4; }.boothControlState { flex: 0 0 auto; border: 2px solid var(--ink); padding: 10px 12px; color: var(--ink); background: var(--green); text-align: end; }.boothControlState[data-paused="true"] { color: #fff; background: #be124e; }.boothControlState span { display: block; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlState strong { display: block; margin-top: 4px; font: 900 19px/1 "Arial Narrow", Arial, sans-serif; text-transform: uppercase; }.boothControlBar { display: grid; grid-template-columns: minmax(0, 1fr) auto; column-gap: 12px; row-gap: 7px; margin-top: 18px; padding: 13px; color: #fff; background: var(--ink); }.boothControlBar label { grid-column: 1 / -1; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlBar textarea { min-height: 44px; width: 100%; resize: vertical; border: 1px solid #777; padding: 10px; color: #fff; background: #1a1a19; font: 13px/1.25 system-ui, sans-serif; }.boothActions { display: flex; align-items: stretch; gap: 7px; }.boothActions button, .boothLoadMore { min-height: 44px; border: 1px solid #777; padding: 10px 12px; color: #fff; background: transparent; font: 800 11px/1.1 system-ui, sans-serif; cursor: pointer; }.boothActions .boothPauseButton { border-color: var(--pink); color: var(--ink); background: var(--pink); }.boothActions button:disabled, .boothLoadMore:disabled, .boothControlBar textarea:disabled { cursor: wait; opacity: .58; }.boothStatusError { margin-top: 9px; border-inline-start: 5px solid #be124e; padding: 10px 12px; color: #8f1239; background: #ffe4e6; font: 800 12px/1.3 system-ui, sans-serif; }.boothRoster { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 295px), 1fr)); gap: 9px; margin: 14px 0 0; padding: 0; list-style: none; }.boothRow { min-width: 0; border: 2px solid var(--ink); padding: 11px; background: #fff; }.boothRow[data-stale="true"] { border-color: #be124e; background: #fff1f2; }.boothRowHead { display: flex; align-items: center; justify-content: space-between; gap: 9px; padding-bottom: 9px; border-bottom: 1px solid var(--ink); }.boothRowHead > code { min-width: 0; overflow: hidden; font: 800 13px/1 ui-monospace, monospace; text-overflow: ellipsis; white-space: nowrap; }.boothPresence { flex: 0 0 auto; padding: 4px 6px; color: #fff; background: #be124e; font: 900 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothPresence[data-live="true"] { color: var(--ink); background: var(--green); }.boothFacts { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 9px 12px; margin-top: 10px; }.boothFacts div { min-width: 0; }.boothFacts dt { color: #635f57; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .06em; text-transform: uppercase; }.boothFacts dd { overflow: hidden; margin-top: 3px; font: 800 12px/1.2 system-ui, sans-serif; text-overflow: ellipsis; white-space: nowrap; }.boothFacts dd code { font: 800 11px/1.2 ui-monospace, monospace; }.boothEmpty { margin-top: 14px; border: 2px dashed #8c8880; padding: 20px; background: rgba(255,255,255,.5); }.boothEmpty strong { font: 900 20px/1 Impact, sans-serif; text-transform: uppercase; }.boothEmpty p { margin-top: 7px; font-size: 13px; }.boothLoadMore { display: block; width: 100%; margin-top: 9px; border-color: var(--ink); color: var(--ink); background: var(--amber); }
 .authPage { display: grid; place-items: center; padding: 20px; background: var(--ink); color: #fff; }.authCard { width: min(500px, 100%); border-top: 8px solid var(--pink); padding: clamp(25px, 5vw, 55px); background: #1a1a19; }.authCard h1 { margin: 25px 0; font: 900 clamp(58px, 10vw, 90px)/.78 Impact, sans-serif; text-transform: uppercase; }.authCard > p:not(.kicker) { color: #bbb; line-height: 1.4; margin-bottom: 28px; }.authCard label { display: block; margin-bottom: 8px; font: 800 11px/1 ui-monospace, monospace; text-transform: uppercase; }.authCard input { width: 100%; padding: 14px; border: 1px solid #777; background: #080808; color: #fff; font: 16px/1 ui-monospace, monospace; }.authCard button { width: 100%; margin-top: 10px; padding: 15px; border: 0; color: #fff; background: var(--pink); font-weight: 900; cursor: pointer; }
-.console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
-@media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; } }
-@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; } }
+.console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
+@media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; } }
+@media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; }.boothOperationsHead { align-items: start; flex-direction: column; }.boothControlState { text-align: start; } }
+@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; }.boothControlBar { grid-template-columns: 1fr; }.boothActions { display: grid; grid-template-columns: 1fr 1fr; }.boothRoster { grid-template-columns: 1fr; } }
 @media (prefers-reduced-motion: reduce) { .console *, .console *::before, .console *::after, .authPage *, .authPage *::before, .authPage *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; } }
diff --git a/app/[event]/admin/booth-operations-panel.test.tsx b/app/[event]/admin/booth-operations-panel.test.tsx
new file mode 100644
index 0000000..c090586
--- /dev/null
+++ b/app/[event]/admin/booth-operations-panel.test.tsx
@@ -0,0 +1,163 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { AdminBoothRecord, BoothOperationalState } from "../../booth-control";
+import { BoothOperationsPanel } from "./booth-operations-panel";
+
+const record: AdminBoothRecord = {
+  version: 1,
+  deviceId: "50d5cf8a-9aa3-4e55-a60f-b3a58d3cc7d5",
+  lastSeenAt: "2026-07-24T00:01:00.000Z",
+  sessionStartedAt: 1_753_408_000_000,
+  pendingCount: 3,
+  durableStorage: false,
+  online: false,
+  installed: true,
+  camera: "denied",
+  upload: "retry-wait",
+  lastSuccessfulUploadAt: 1_753_407_940_000,
+  errorClass: "network",
+  buildId: "release-1",
+  stale: true,
+};
+
+const operationalState: BoothOperationalState = {
+  version: 1,
+  paused: true,
+  messages: { en: "Hold for lighting", ar: "انتظر الإضاءة" },
+  updatedAt: "2026-07-24T00:01:00.000Z",
+};
+
+const liveRecord: AdminBoothRecord = {
+  ...record,
+  deviceId: "30b0c3cf-b0f5-4ce0-8e2a-5460d0e6658f",
+  pendingCount: 0,
+  durableStorage: true,
+  online: true,
+  installed: false,
+  camera: "ready",
+  upload: "idle",
+  stale: false,
+};
+
+test("renders scannable safe booth state and no credentials or raw errors", () => {
+  const html = renderToStaticMarkup(
+    <BoothOperationsPanel
+      records={[record, liveRecord]}
+      cursor="next-page"
+      operationalState={operationalState}
+      loading={false}
+      loadingMore={false}
+      mutationBusy={false}
+      hasError={false}
+      englishMessageDraft="Hold for lighting"
+      onEnglishMessageChange={() => {}}
+      onRefresh={() => {}}
+      onLoadMore={() => {}}
+      onPause={() => {}}
+      onResume={() => {}}
+    />
+  );
+
+  expect(html).toContain("Stale");
+  expect(html).toContain("Live");
+  expect(html).toContain("Pending 3");
+  expect(html).toContain("Storage durable");
+  expect(html).toContain("Storage degraded");
+  expect(html).toContain("Installed");
+  expect(html).toContain("Camera denied");
+  expect(html).toContain("Upload retry-wait");
+  expect(html).toContain("Build release-1");
+  expect(html).toContain("Resume capture");
+  expect(html).toContain('maxLength="280"');
+  expect(html).not.toContain("boothKey");
+  expect(html).not.toContain("hash");
+  expect(html).not.toContain("upstream secret failure");
+});
+
+test("makes pause and resume unavailable during a mutation", () => {
+  const html = renderToStaticMarkup(
+    <BoothOperationsPanel
+      records={[]}
+      cursor={null}
+      operationalState={{ ...operationalState, paused: false }}
+      loading={false}
+      loadingMore={false}
+      mutationBusy
+      hasError
+      englishMessageDraft=""
+      onEnglishMessageChange={() => {}}
+      onRefresh={() => {}}
+      onLoadMore={() => {}}
+      onPause={() => {}}
+      onResume={() => {}}
+    />
+  );
+
+  expect(html).toContain("Pausing capture…");
+  expect(html).toContain("disabled");
+  expect(html).toContain("Booth status needs a refresh.");
+
+  const resumeHtml = renderToStaticMarkup(
+    <BoothOperationsPanel
+      records={[]}
+      cursor={null}
+      operationalState={operationalState}
+      loading={false}
+      loadingMore={false}
+      mutationBusy
+      hasError={false}
+      englishMessageDraft=""
+      onEnglishMessageChange={() => {}}
+      onRefresh={() => {}}
+      onLoadMore={() => {}}
+      onPause={() => {}}
+      onResume={() => {}}
+    />
+  );
+
+  expect(resumeHtml).toContain("Resuming capture…");
+});
+
+test("keeps opaque pagination unavailable while the first page is refreshing", () => {
+  const html = renderToStaticMarkup(
+    <BoothOperationsPanel
+      records={[]}
+      cursor={" \t\n "}
+      operationalState={operationalState}
+      loading
+      loadingMore={false}
+      mutationBusy={false}
+      hasError={false}
+      englishMessageDraft=""
+      onEnglishMessageChange={() => {}}
+      onRefresh={() => {}}
+      onLoadMore={() => {}}
+      onPause={() => {}}
+      onResume={() => {}}
+    />
+  );
+
+  expect(html).toMatch(/<button[^>]*disabled=""[^>]*>Load more stations<\/button>/);
+});
+
+test("keeps a malformed timestamp from breaking the operator roster", () => {
+  const html = renderToStaticMarkup(
+    <BoothOperationsPanel
+      records={[{ ...record, sessionStartedAt: Number.MAX_SAFE_INTEGER }]}
+      cursor={null}
+      operationalState={operationalState}
+      loading={false}
+      loadingMore={false}
+      mutationBusy={false}
+      hasError={false}
+      englishMessageDraft=""
+      onEnglishMessageChange={() => {}}
+      onRefresh={() => {}}
+      onLoadMore={() => {}}
+      onPause={() => {}}
+      onResume={() => {}}
+    />
+  );
+
+  expect(html).toContain("Unavailable");
+});
diff --git a/app/[event]/admin/booth-operations-panel.tsx b/app/[event]/admin/booth-operations-panel.tsx
new file mode 100644
index 0000000..0bb467d
--- /dev/null
+++ b/app/[event]/admin/booth-operations-panel.tsx
@@ -0,0 +1,145 @@
+"use client";
+
+import type { AdminBoothRecord, BoothOperationalState } from "../../booth-control";
+import styles from "./admin.module.css";
+
+type BoothOperationsPanelProps = {
+  records: readonly AdminBoothRecord[];
+  cursor: string | null;
+  operationalState: BoothOperationalState | null;
+  loading: boolean;
+  loadingMore: boolean;
+  mutationBusy: boolean;
+  hasError: boolean;
+  englishMessageDraft: string;
+  onEnglishMessageChange: (message: string) => void;
+  onRefresh: () => void;
+  onLoadMore: () => void;
+  onPause: () => void;
+  onResume: () => void;
+};
+
+function abbreviatedDeviceId(deviceId: string) {
+  return `${deviceId.slice(0, 8)}…${deviceId.slice(-4)}`;
+}
+
+function formatTimestamp(timestamp: number | string) {
+  const date = new Date(timestamp);
+  return Number.isNaN(date.getTime())
+    ? "Unavailable"
+    : date.toLocaleString([], { dateStyle: "medium", timeStyle: "short" });
+}
+
+function dateTimeValue(timestamp: number | string) {
+  const date = new Date(timestamp);
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+
+function BoothRow({ record }: { record: AdminBoothRecord }) {
+  const lastUpload = record.lastSuccessfulUploadAt === undefined
+    ? "No upload yet"
+    : formatTimestamp(record.lastSuccessfulUploadAt);
+  const sessionDateTime = dateTimeValue(record.sessionStartedAt);
+
+  return (
+    <li className={styles.boothRow} data-stale={record.stale}>
+      <div className={styles.boothRowHead}>
+        <code title={record.deviceId}>{abbreviatedDeviceId(record.deviceId)}</code>
+        <span className={styles.boothPresence} data-live={!record.stale}>{record.stale ? "Stale" : "Live"}</span>
+      </div>
+      <dl className={styles.boothFacts}>
+        <div><dt>Last seen</dt><dd><time dateTime={record.lastSeenAt}>{formatTimestamp(record.lastSeenAt)}</time></dd></div>
+        <div><dt>Session</dt><dd><time dateTime={sessionDateTime}>{formatTimestamp(record.sessionStartedAt)}</time></dd></div>
+        <div aria-label={`Pending ${record.pendingCount}`}><dt>Pending</dt><dd>{record.pendingCount}</dd></div>
+        <div aria-label={`Storage ${record.durableStorage ? "durable" : "degraded"}`}><dt>Storage</dt><dd>{record.durableStorage ? "Durable" : "Degraded"}</dd></div>
+        <div aria-label={record.online ? "Online" : "Offline"}><dt>Network</dt><dd>{record.online ? "Online" : "Offline"}</dd></div>
+        <div aria-label={record.installed ? "Installed" : "Browser mode"}><dt>Mode</dt><dd>{record.installed ? "Installed" : "Browser"}</dd></div>
+        <div aria-label={`Camera ${record.camera}`}><dt>Camera</dt><dd>{record.camera}</dd></div>
+        <div aria-label={`Upload ${record.upload}`}><dt>Upload</dt><dd>{record.upload}</dd></div>
+        <div><dt>Last upload</dt><dd>{lastUpload}</dd></div>
+        <div aria-label={record.errorClass ? `Error ${record.errorClass}` : "No classified error"}><dt>Error</dt><dd>{record.errorClass ?? "None"}</dd></div>
+        <div aria-label={`Build ${record.buildId}`}><dt>Build</dt><dd><code>{record.buildId}</code></dd></div>
+      </dl>
+    </li>
+  );
+}
+
+export function BoothOperationsPanel({
+  records,
+  cursor,
+  operationalState,
+  loading,
+  loadingMore,
+  mutationBusy,
+  hasError,
+  englishMessageDraft,
+  onEnglishMessageChange,
+  onRefresh,
+  onLoadMore,
+  onPause,
+  onResume,
+}: BoothOperationsPanelProps) {
+  const paused = operationalState?.paused ?? false;
+  const controlsUnavailable = mutationBusy || operationalState === null;
+  const actionLabel = mutationBusy
+    ? paused ? "Resuming capture…" : "Pausing capture…"
+    : paused ? "Resume capture" : "Pause capture";
+
+  return (
+    <section className={styles.boothOperations} aria-labelledby="booth-operations-heading">
+      <div className={styles.boothOperationsHead}>
+        <div>
+          <span className={styles.cardNumber}>03</span>
+          <h2 id="booth-operations-heading">Booth operations</h2>
+          <p>Watch each iPad and stop capture before a problem spreads across the room.</p>
+        </div>
+        <div className={styles.boothControlState} data-paused={paused}>
+          <span>Capture</span>
+          <strong>{operationalState === null ? "Checking" : paused ? "Paused" : "Running"}</strong>
+        </div>
+      </div>
+
+      <div className={styles.boothControlBar}>
+        <label htmlFor="booth-english-message">English booth message</label>
+        <textarea
+          id="booth-english-message"
+          value={englishMessageDraft}
+          onChange={(event) => onEnglishMessageChange(event.target.value)}
+          disabled={controlsUnavailable}
+          placeholder="Optional note for booth screens"
+          maxLength={280}
+          rows={2}
+        />
+        <div className={styles.boothActions}>
+          <button type="button" onClick={onRefresh} disabled={loading || mutationBusy}>
+            {loading ? "Refreshing…" : "Refresh stations"}
+          </button>
+          <button
+            className={styles.boothPauseButton}
+            type="button"
+            onClick={paused ? onResume : onPause}
+            disabled={controlsUnavailable}
+          >
+            {actionLabel}
+          </button>
+        </div>
+      </div>
+
+      {hasError && <p className={styles.boothStatusError} role="status">Booth status needs a refresh.</p>}
+
+      {records.length === 0 && !loading ? (
+        <div className={styles.boothEmpty}><strong>No stations have checked in.</strong><p>Open the booth on each iPad to see it here.</p></div>
+      ) : (
+        <ol className={styles.boothRoster} aria-label="Booth station status">
+          {records.map((record) => <BoothRow key={record.deviceId} record={record} />)}
+        </ol>
+      )}
+
+      {cursor !== null && (
+        <button className={styles.boothLoadMore} type="button" onClick={onLoadMore} disabled={loading || loadingMore || mutationBusy}>
+          {loadingMore ? "Loading stations…" : "Load more stations"}
+        </button>
+      )}
+    </section>
+  );
+}
diff --git a/app/[event]/admin/booth-operations.test.ts b/app/[event]/admin/booth-operations.test.ts
new file mode 100644
index 0000000..8019c23
--- /dev/null
+++ b/app/[event]/admin/booth-operations.test.ts
@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import type { AdminBoothRecord } from "../../booth-control";
+import { boothOperationalStateInput, mergeBoothPages } from "./booth-operations";
+
+function booth(deviceId: string, lastSeenAt: string): AdminBoothRecord {
+  return {
+    version: 1,
+    deviceId,
+    lastSeenAt,
+    sessionStartedAt: 1_753_408_000_000,
+    pendingCount: 0,
+    durableStorage: true,
+    online: true,
+    installed: true,
+    camera: "ready",
+    upload: "idle",
+    buildId: "r1",
+    stale: false,
+  };
+}
+
+test("mergeBoothPages retains each exact device ID at its newest last-seen time", () => {
+  const merged = mergeBoothPages(
+    [booth("a", "2026-07-24T00:00:00.000Z")],
+    [
+      booth("a", "2026-07-24T00:01:00.000Z"),
+      booth("b", "2026-07-24T00:00:30.000Z"),
+    ]
+  );
+
+  expect(merged.map((record) => record.deviceId)).toEqual(["a", "b"]);
+  expect(merged[0]?.lastSeenAt).toBe("2026-07-24T00:01:00.000Z");
+});
+
+test("mergeBoothPages ignores an older snapshot for the same exact device ID", () => {
+  const merged = mergeBoothPages(
+    [booth("a", "2026-07-24T00:01:00.000Z")],
+    [booth("a", "2026-07-24T00:00:00.000Z")]
+  );
+
+  expect(merged).toHaveLength(1);
+  expect(merged[0]?.lastSeenAt).toBe("2026-07-24T00:01:00.000Z");
+});
+
+test("boothOperationalStateInput updates English without dropping other locale messages", () => {
+  expect(boothOperationalStateInput({ en: "Original", ar: "انتظر" }, "Hold for lighting", true)).toEqual({
+    paused: true,
+    messages: { en: "Hold for lighting", ar: "انتظر" },
+  });
+});
diff --git a/app/[event]/admin/booth-operations.ts b/app/[event]/admin/booth-operations.ts
new file mode 100644
index 0000000..98fb41b
--- /dev/null
+++ b/app/[event]/admin/booth-operations.ts
@@ -0,0 +1,40 @@
+import type { AdminBoothRecord, BoothOperationalStateInput } from "../../booth-control";
+
+/**
+ * Reconcile overlapping opaque pages without ever treating a shortened device
+ * identifier as an identity. A refreshed record wins only when it is newer.
+ */
+export function mergeBoothPages(
+  ...pages: ReadonlyArray<readonly AdminBoothRecord[]>
+): AdminBoothRecord[] {
+  const byDeviceId = new Map<string, AdminBoothRecord>();
+
+  for (const page of pages) {
+    for (const record of page) {
+      const current = byDeviceId.get(record.deviceId);
+      if (!current || Date.parse(record.lastSeenAt) > Date.parse(current.lastSeenAt)) {
+        byDeviceId.set(record.deviceId, record);
+      }
+    }
+  }
+
+  return [...byDeviceId.values()].sort(
+    (left, right) => Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt)
+  );
+}
+
+/** Keep translated operator messages intact while the Admin only edits English. */
+export function boothOperationalStateInput(
+  currentMessages: Record<string, string> | undefined,
+  englishMessage: string,
+  paused: boolean
+): BoothOperationalStateInput {
+  const messages = { ...currentMessages };
+  if (englishMessage) messages.en = englishMessage;
+  else delete messages.en;
+
+  return {
+    paused,
+    ...(Object.keys(messages).length > 0 ? { messages } : {}),
+  };
+}
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index bc69058..9916eef 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -5,11 +5,14 @@ import { useParams } from "next/navigation";
 import QRCode from "qrcode";
 import { TEMPLATES } from "../../templates";
 import type { ConfigRevision, PublicEventConfig } from "../../event-config";
+import type { AdminBoothRecord, BoothOperationalState } from "../../booth-control";
 import {
   BoothKeyControls,
   FrameProgrammeControls,
   SaveConfigurationButton,
 } from "./admin-config-controls";
+import { boothOperationalStateInput, mergeBoothPages } from "./booth-operations";
+import { BoothOperationsPanel } from "./booth-operations-panel";
 import { ConfigHistoryPanel } from "./config-history-panel";
 import {
   clearRestoreRequestAfterReconciliation,
@@ -25,6 +28,7 @@ type Photo = { key: string; url: string; uploadedAt: string };
 type AuthState = "missing" | "ready" | "invalid";
 type Probe = { status: "up" | "degraded" | "down"; detail: string };
 type Health = { upload: Probe; live: Probe };
+type BoothPage = { booths: AdminBoothRecord[]; cursor: string | null };
 type FilePickerWindow = Window & { showSaveFilePicker?: (options: { suggestedName: string; types: { description: string; accept: Record<string, string[]> }[] }) => Promise<{ createWritable(): Promise<WritableStream<Uint8Array>> }> };
 const CONFIG_CONFLICT_MESSAGE = "Configuration changed; review the latest version before saving.";
 
@@ -56,7 +60,18 @@ export default function Admin() {
   const [copied, setCopied] = useState("");
   const [health, setHealth] = useState<Health | null>(null);
   const [checkingHealth, setCheckingHealth] = useState(false);
+  const [boothRecords, setBoothRecords] = useState<AdminBoothRecord[]>([]);
+  const [boothCursor, setBoothCursor] = useState<string | null>(null);
+  const [boothOperationalState, setBoothOperationalState] = useState<BoothOperationalState | null>(null);
+  const [boothStatusLoading, setBoothStatusLoading] = useState(false);
+  const [boothLoadingMore, setBoothLoadingMore] = useState(false);
+  const [boothMutationBusy, setBoothMutationBusy] = useState(false);
+  const [boothStatusError, setBoothStatusError] = useState(false);
+  const [boothMessageDraft, setBoothMessageDraft] = useState("");
   const photoCursor = useRef<string | null>(null);
+  const boothCursorRef = useRef<string | null>(null);
+  const boothRequestBusy = useRef(false);
+  const boothMessageEditing = useRef(false);
   const configMutationBusy = useRef(false);
   const pendingSaveMutationId = useRef<string | null>(null);
   const pendingRestoreRequests = useRef(new Map<string, RestoreRequest>());
@@ -70,6 +85,11 @@ export default function Admin() {
     setError((current) => current === CONFIG_CONFLICT_MESSAGE ? "" : current);
   };
 
+  const invalidateAuth = () => {
+    sessionStorage.removeItem("adminKey");
+    setAuth("invalid");
+  };
+
   const runHealth = useCallback(async (key = adminKey) => {
     setCheckingHealth(true); setError("");
     try {
@@ -159,6 +179,134 @@ export default function Admin() {
     }
   }, [event]);
 
+  const loadBoothStatus = useCallback(async () => {
+    if (boothRequestBusy.current) return;
+    boothRequestBusy.current = true;
+    setBoothStatusLoading(true);
+    setBoothStatusError(false);
+    try {
+      const stateUrl = `/api/booth-state?event=${encodeURIComponent(event)}`;
+      const devicesUrl = `/api/booths?event=${encodeURIComponent(event)}`;
+      const headers = { "x-booth-key": adminKey };
+      const [stateResult, devicesResult] = await Promise.allSettled([
+        fetch(stateUrl, { cache: "no-store", headers }),
+        fetch(devicesUrl, { cache: "no-store", headers }),
+      ]);
+
+      let failed = false;
+      if (stateResult.status === "rejected") {
+        failed = true;
+      } else if (stateResult.value.status === 401) {
+        invalidateAuth();
+        failed = true;
+      } else if (!stateResult.value.ok) {
+        failed = true;
+      } else {
+        const nextState = await stateResult.value.json() as BoothOperationalState;
+        setBoothOperationalState(nextState);
+        setBoothMessageDraft((current) => boothMessageEditing.current
+          ? current
+          : nextState.messages?.en ?? "");
+      }
+
+      if (devicesResult.status === "rejected") {
+        failed = true;
+      } else if (devicesResult.value.status === 401) {
+        invalidateAuth();
+        failed = true;
+      } else if (!devicesResult.value.ok) {
+        failed = true;
+      } else {
+        const page = await devicesResult.value.json() as BoothPage;
+        if (!Array.isArray(page.booths) || (page.cursor !== null && typeof page.cursor !== "string")) {
+          failed = true;
+        } else {
+          setBoothRecords((current) => mergeBoothPages(current, page.booths));
+          boothCursorRef.current = page.cursor;
+          setBoothCursor(page.cursor);
+        }
+      }
+      setBoothStatusError(failed);
+    } catch {
+      setBoothStatusError(true);
+    } finally {
+      boothRequestBusy.current = false;
+      setBoothStatusLoading(false);
+    }
+  }, [adminKey, event]);
+
+  const loadMoreBooths = useCallback(async () => {
+    const cursor = boothCursorRef.current;
+    if (cursor === null || boothRequestBusy.current) return;
+    boothRequestBusy.current = true;
+    setBoothLoadingMore(true);
+    setBoothStatusError(false);
+    try {
+      const query = new URLSearchParams({ event, cursor });
+      const response = await fetch(`/api/booths?${query}`, {
+        cache: "no-store",
+        headers: { "x-booth-key": adminKey },
+      });
+      if (response.status === 401) {
+        invalidateAuth();
+        setBoothStatusError(true);
+        return;
+      }
+      if (!response.ok) {
+        setBoothStatusError(true);
+        return;
+      }
+      const page = await response.json() as BoothPage;
+      if (!Array.isArray(page.booths) || (page.cursor !== null && typeof page.cursor !== "string")) {
+        setBoothStatusError(true);
+        return;
+      }
+      setBoothRecords((current) => mergeBoothPages(current, page.booths));
+      boothCursorRef.current = page.cursor;
+      setBoothCursor(page.cursor);
+    } catch {
+      setBoothStatusError(true);
+    } finally {
+      boothRequestBusy.current = false;
+      setBoothLoadingMore(false);
+    }
+  }, [adminKey, event]);
+
+  const updateBoothOperationalState = useCallback(async (paused: boolean) => {
+    if (boothMutationBusy || !boothOperationalState) return;
+    setBoothMutationBusy(true);
+    setBoothStatusError(false);
+    try {
+      const response = await fetch(`/api/booth-state?event=${encodeURIComponent(event)}`, {
+        method: "PUT",
+        cache: "no-store",
+        headers: { "x-booth-key": adminKey, "content-type": "application/json" },
+        body: JSON.stringify(boothOperationalStateInput(
+          boothOperationalState.messages,
+          boothMessageDraft,
+          paused
+        )),
+      });
+      if (response.status === 401) {
+        invalidateAuth();
+        setBoothStatusError(true);
+        return;
+      }
+      if (!response.ok) {
+        setBoothStatusError(true);
+        return;
+      }
+      const nextState = await response.json() as BoothOperationalState;
+      setBoothOperationalState(nextState);
+      boothMessageEditing.current = false;
+      setBoothMessageDraft(nextState.messages?.en ?? "");
+    } catch {
+      setBoothStatusError(true);
+    } finally {
+      setBoothMutationBusy(false);
+    }
+  }, [adminKey, boothMessageDraft, boothMutationBusy, boothOperationalState, event]);
+
   useEffect(() => {
     photoCursor.current = null;
     void loadPhotos(true);
@@ -171,6 +319,27 @@ export default function Admin() {
     void loadConfig();
   }, [adminKey, auth, loadConfig]);
 
+  useEffect(() => {
+    if (auth !== "ready" || !adminKey) return;
+    boothCursorRef.current = null;
+    boothMessageEditing.current = false;
+    setBoothRecords([]);
+    setBoothCursor(null);
+    setBoothOperationalState(null);
+    setBoothStatusError(false);
+    let cancelled = false;
+    let nextPoll: number | undefined;
+    const poll = async () => {
+      await loadBoothStatus();
+      if (!cancelled) nextPoll = window.setTimeout(() => void poll(), 15_000);
+    };
+    void poll();
+    return () => {
+      cancelled = true;
+      if (nextPoll !== undefined) window.clearTimeout(nextPoll);
+    };
+  }, [adminKey, auth, event, loadBoothStatus]);
+
   const authenticate = (submitEvent: FormEvent) => {
     submitEvent.preventDefault();
     const next = adminKey.trim();
@@ -182,11 +351,6 @@ export default function Admin() {
     void runHealth(next);
   };
 
-  const invalidateAuth = () => {
-    sessionStorage.removeItem("adminKey");
-    setAuth("invalid");
-  };
-
   const toggle = (key: string) => {
     if (configMutationBusy.current) return;
     clearPendingSave();
@@ -443,8 +607,27 @@ export default function Admin() {
             onRestore={(revisionId) => void restoreRevision(revisionId)}
           />
 
+          <BoothOperationsPanel
+            records={boothRecords}
+            cursor={boothCursor}
+            operationalState={boothOperationalState}
+            loading={boothStatusLoading}
+            loadingMore={boothLoadingMore}
+            mutationBusy={boothMutationBusy}
+            hasError={boothStatusError}
+            englishMessageDraft={boothMessageDraft}
+            onEnglishMessageChange={(message) => {
+              boothMessageEditing.current = true;
+              setBoothMessageDraft(message);
+            }}
+            onRefresh={() => void loadBoothStatus()}
+            onLoadMore={() => void loadMoreBooths()}
+            onPause={() => void updateBoothOperationalState(true)}
+            onResume={() => void updateBoothOperationalState(false)}
+          />
+
           <section className={styles.section}>
-            <div className={styles.sectionHead}><div><span>03</span><h2>Recent contact sheet</h2></div><p>{photos.length} photograph{photos.length === 1 ? "" : "s"} currently in this event.</p></div>
+            <div className={styles.sectionHead}><div><span>04</span><h2>Recent contact sheet</h2></div><p>{photos.length} photograph{photos.length === 1 ? "" : "s"} currently in this event.</p></div>
             {photosError && photos.length === 0 ? <div className={styles.failure}><strong>Photo feed unavailable</strong><p>{photosError}</p><button onClick={() => void loadPhotos(true)}>Retry photos</button></div> : photosLoaded && photos.length === 0 ?
               <div className={styles.emptySheet}><strong>No exposures yet.</strong><p>Open the booth link and take a test photo before doors open.</p></div> :
               <div className={styles.contactSheet}>{photos.slice(0, 16).map((photo) => <article key={photo.key} className={styles.contactPhoto}>
@@ -457,7 +640,7 @@ export default function Admin() {
 
         <aside className={styles.sideColumn}>
           <section className={styles.sideCard}>
-            <span className={styles.cardNumber}>04</span><h2>Booth credential</h2>
+            <span className={styles.cardNumber}>05</span><h2>Booth credential</h2>
             <p>{hasBoothKey ? "A booth key is installed. Generate a replacement only when rotating iPad access." : "No booth key yet. Generate one before the booth can upload."}</p>
             <BoothKeyControls
               value={boothKey}

From e6e2143c3f968aef28c6e9af870cc9421d34fabe Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:09:07 +0800
Subject: [PATCH 043/105] fix: harden Admin booth operations polling

---
 app/[event]/admin/booth-operations.test.ts | 193 +++++++++++++++++-
 app/[event]/admin/booth-operations.ts      | 223 ++++++++++++++++++++-
 app/[event]/admin/page.tsx                 | 155 ++++++++++----
 3 files changed, 523 insertions(+), 48 deletions(-)

diff --git a/app/[event]/admin/booth-operations.test.ts b/app/[event]/admin/booth-operations.test.ts
index 8019c23..da7cefd 100644
--- a/app/[event]/admin/booth-operations.test.ts
+++ b/app/[event]/admin/booth-operations.test.ts
@@ -1,6 +1,20 @@
 import { expect, test } from "bun:test";
-import type { AdminBoothRecord } from "../../booth-control";
-import { boothOperationalStateInput, mergeBoothPages } from "./booth-operations";
+import type { AdminBoothRecord, BoothOperationalState } from "../../booth-control";
+import {
+  BoothOperationsCoordinator,
+  boothOperationalStateInput,
+  mergeBoothPages,
+  parseAdminBoothPage,
+  parseBoothOperationalStateResponse,
+} from "./booth-operations";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
 
 function booth(deviceId: string, lastSeenAt: string): AdminBoothRecord {
   return {
@@ -19,6 +33,16 @@ function booth(deviceId: string, lastSeenAt: string): AdminBoothRecord {
   };
 }
 
+function safeBooth(overrides: Partial<AdminBoothRecord> = {}): AdminBoothRecord {
+  return {
+    ...booth(
+      "018f0000-0000-4000-8000-000000000001",
+      "2026-07-24T00:01:00.000Z"
+    ),
+    ...overrides,
+  };
+}
+
 test("mergeBoothPages retains each exact device ID at its newest last-seen time", () => {
   const merged = mergeBoothPages(
     [booth("a", "2026-07-24T00:00:00.000Z")],
@@ -42,9 +66,174 @@ test("mergeBoothPages ignores an older snapshot for the same exact device ID", (
   expect(merged[0]?.lastSeenAt).toBe("2026-07-24T00:01:00.000Z");
 });
 
+test("mergeBoothPages replaces an invalid timestamp with a valid record for the same device", () => {
+  const merged = mergeBoothPages(
+    [booth("a", "not-a-timestamp")],
+    [booth("a", "2026-07-24T00:01:00.000Z")]
+  );
+
+  expect(merged).toHaveLength(1);
+  expect(merged[0]?.lastSeenAt).toBe("2026-07-24T00:01:00.000Z");
+});
+
+test("mergeBoothPages sorts invalid timestamps after valid records in stable input order", () => {
+  const merged = mergeBoothPages(
+    [
+      booth("invalid-a", "not-a-timestamp"),
+      booth("valid", "2026-07-24T00:01:00.000Z"),
+      booth("invalid-b", "also-not-a-timestamp"),
+    ]
+  );
+
+  expect(merged.map((record) => record.deviceId)).toEqual([
+    "valid",
+    "invalid-a",
+    "invalid-b",
+  ]);
+});
+
 test("boothOperationalStateInput updates English without dropping other locale messages", () => {
   expect(boothOperationalStateInput({ en: "Original", ar: "انتظر" }, "Hold for lighting", true)).toEqual({
     paused: true,
     messages: { en: "Hold for lighting", ar: "انتظر" },
   });
 });
+
+test("parseBoothOperationalStateResponse rejects malformed or expanded state", () => {
+  const valid: BoothOperationalState = {
+    version: 1,
+    paused: false,
+    messages: { en: "Ready" },
+    updatedAt: "2026-07-24T00:01:00.000Z",
+  };
+
+  expect(parseBoothOperationalStateResponse(valid)).toEqual(valid);
+  expect(parseBoothOperationalStateResponse({ ...valid, updatedAt: "not-a-date" })).toBeNull();
+  expect(parseBoothOperationalStateResponse({ ...valid, rawError: "private failure" })).toBeNull();
+});
+
+test("parseAdminBoothPage strictly rejects malformed records and cursors", () => {
+  const validRecord = safeBooth();
+  const valid = { booths: [validRecord], cursor: " \t\n " };
+
+  expect(parseAdminBoothPage(valid)).toEqual(valid);
+  expect(parseAdminBoothPage({
+    booths: [{ ...validRecord, camera: "raw camera exception" }],
+    cursor: null,
+  })).toBeNull();
+  expect(parseAdminBoothPage({
+    booths: [{ ...validRecord, buildId: "not a bounded token" }],
+    cursor: null,
+  })).toBeNull();
+  expect(parseAdminBoothPage({
+    booths: [{ ...validRecord, errorClass: "private storage exception" }],
+    cursor: null,
+  })).toBeNull();
+  expect(parseAdminBoothPage({
+    booths: [{ ...validRecord, lastSeenAt: "not-a-date" }],
+    cursor: null,
+  })).toBeNull();
+  expect(parseAdminBoothPage({ booths: [validRecord], cursor: 7 })).toBeNull();
+  expect(parseAdminBoothPage({ ...valid, boothKey: "must-not-pass" })).toBeNull();
+});
+
+test("an old Event response cannot write or block the new Event initial request", async () => {
+  const coordinator = new BoothOperationsCoordinator();
+  coordinator.activateScope("old-event", "admin-one");
+  const oldRead = coordinator.beginRead("old-event", "admin-one");
+  expect(oldRead).not.toBeNull();
+  const oldResponse = deferred<string>();
+  const writes: string[] = [];
+  const completion = oldResponse.promise.then((value) => {
+    if (oldRead && coordinator.isReadCurrent(oldRead)) writes.push(value);
+  });
+
+  coordinator.activateScope("new-event", "admin-one");
+  expect(oldRead?.signal.aborted).toBe(true);
+  const newRead = coordinator.beginRead("new-event", "admin-one");
+  expect(newRead).not.toBeNull();
+
+  oldResponse.resolve("stale old Event state");
+  await completion;
+  expect(writes).toEqual([]);
+  expect(oldRead && coordinator.finishRead(oldRead)).toBe(false);
+  expect(newRead && coordinator.isReadCurrent(newRead)).toBe(true);
+});
+
+test("disposing a scope aborts in-flight work and prevents another request", () => {
+  const coordinator = new BoothOperationsCoordinator();
+  coordinator.activateScope("event", "admin");
+  const read = coordinator.beginRead("event", "admin");
+  expect(read).not.toBeNull();
+
+  coordinator.disposeScope();
+
+  expect(read?.signal.aborted).toBe(true);
+  expect(coordinator.beginRead("event", "admin")).toBeNull();
+});
+
+test("requests cannot borrow a different Event or Admin scope before activation", () => {
+  const coordinator = new BoothOperationsCoordinator();
+  coordinator.activateScope("old-event", "admin-one");
+
+  expect(coordinator.beginRead("new-event", "admin-one")).toBeNull();
+  expect(coordinator.beginMutation("old-event", "admin-two")).toBeNull();
+});
+
+test("a first-page refresh never rewinds the loaded tail cursor", () => {
+  const coordinator = new BoothOperationsCoordinator();
+  coordinator.activateScope("event", "admin");
+  const initial = coordinator.beginRead("event", "admin");
+  expect(initial).not.toBeNull();
+  expect(initial && coordinator.acceptFirstPage(initial, "cursor-1")).toBe("cursor-1");
+  expect(initial && coordinator.finishRead(initial)).toBe(true);
+
+  const laterPage = coordinator.beginRead("event", "admin");
+  expect(laterPage).not.toBeNull();
+  expect(coordinator.tailCursor()).toBe("cursor-1");
+  expect(laterPage && coordinator.advanceTail(laterPage, "cursor-2")).toBe("cursor-2");
+  expect(laterPage && coordinator.finishRead(laterPage)).toBe(true);
+
+  const refresh = coordinator.beginRead("event", "admin");
+  expect(refresh).not.toBeNull();
+  expect(refresh && coordinator.acceptFirstPage(refresh, "cursor-1")).toBe("cursor-2");
+  expect(refresh && coordinator.finishRead(refresh)).toBe(true);
+  expect(coordinator.tailCursor()).toBe("cursor-2");
+});
+
+test("a first-page refresh does not reopen pagination after the loaded tail ends", () => {
+  const coordinator = new BoothOperationsCoordinator();
+  coordinator.activateScope("event", "admin");
+  const initial = coordinator.beginRead("event", "admin");
+  expect(initial && coordinator.acceptFirstPage(initial, "cursor-1")).toBe("cursor-1");
+  expect(initial && coordinator.advanceTail(initial, null)).toBeNull();
+  expect(initial && coordinator.finishRead(initial)).toBe(true);
+
+  const refresh = coordinator.beginRead("event", "admin");
+  expect(refresh && coordinator.acceptFirstPage(refresh, "cursor-1")).toBeNull();
+  expect(coordinator.tailCursor()).toBeNull();
+});
+
+test("a stale GET completion after a successful mutation cannot overwrite state", async () => {
+  const coordinator = new BoothOperationsCoordinator();
+  coordinator.activateScope("event", "admin");
+  const staleRead = coordinator.beginRead("event", "admin");
+  expect(staleRead).not.toBeNull();
+  const staleResponse = deferred<string>();
+  let displayedState = "running";
+  const completion = staleResponse.promise.then((value) => {
+    if (staleRead && coordinator.isReadCurrent(staleRead)) displayedState = value;
+  });
+
+  const mutation = coordinator.beginMutation("event", "admin");
+  expect(mutation).not.toBeNull();
+  expect(mutation?.abortedRead).toBe(true);
+  expect(staleRead?.signal.aborted).toBe(true);
+  expect(coordinator.beginRead("event", "admin")).toBeNull();
+  displayedState = "paused";
+  expect(mutation && coordinator.finishMutation(mutation.ticket)).toBe(true);
+
+  staleResponse.resolve("running");
+  await completion;
+  expect(displayedState).toBe("paused");
+});
diff --git a/app/[event]/admin/booth-operations.ts b/app/[event]/admin/booth-operations.ts
index 98fb41b..ef26682 100644
--- a/app/[event]/admin/booth-operations.ts
+++ b/app/[event]/admin/booth-operations.ts
@@ -1,4 +1,205 @@
-import type { AdminBoothRecord, BoothOperationalStateInput } from "../../booth-control";
+import {
+  parseBoothHeartbeatRecord,
+  parseBoothOperationalState,
+  type AdminBoothRecord,
+  type BoothOperationalState,
+  type BoothOperationalStateInput,
+} from "../../booth-control";
+
+export type AdminBoothPage = {
+  booths: AdminBoothRecord[];
+  cursor: string | null;
+};
+
+export type BoothRequestTicket = Readonly<{
+  generation: number;
+  mutationEpoch: number;
+  kind: "read" | "mutation";
+  signal: AbortSignal;
+}>;
+
+type ActiveBoothRequest = BoothRequestTicket & {
+  controller: AbortController;
+};
+
+export class BoothOperationsCoordinator {
+  private generation = 0;
+  private mutationEpoch = 0;
+  private active = false;
+  private scopeEvent: string | null = null;
+  private scopeAdminKey: string | null = null;
+  private activeRead: ActiveBoothRequest | null = null;
+  private activeMutation: ActiveBoothRequest | null = null;
+  private tailInitialized = false;
+  private loadedTailCursor: string | null = null;
+
+  activateScope(event: string, adminKey: string): void {
+    this.abortActiveRequests();
+    this.generation += 1;
+    this.mutationEpoch = 0;
+    this.active = true;
+    this.scopeEvent = event;
+    this.scopeAdminKey = adminKey;
+    this.tailInitialized = false;
+    this.loadedTailCursor = null;
+  }
+
+  disposeScope(): void {
+    this.abortActiveRequests();
+    this.generation += 1;
+    this.active = false;
+    this.scopeEvent = null;
+    this.scopeAdminKey = null;
+    this.tailInitialized = false;
+    this.loadedTailCursor = null;
+  }
+
+  beginRead(event: string, adminKey: string): BoothRequestTicket | null {
+    if (
+      !this.matchesScope(event, adminKey)
+      || this.activeRead
+      || this.activeMutation
+    ) return null;
+    const request = this.newRequest("read");
+    this.activeRead = request;
+    return request;
+  }
+
+  isReadCurrent(ticket: BoothRequestTicket): boolean {
+    return (
+      ticket.kind === "read"
+      && ticket === this.activeRead
+      && ticket.generation === this.generation
+      && ticket.mutationEpoch === this.mutationEpoch
+      && !ticket.signal.aborted
+    );
+  }
+
+  finishRead(ticket: BoothRequestTicket): boolean {
+    const current = this.isReadCurrent(ticket);
+    if (ticket === this.activeRead) this.activeRead = null;
+    return current;
+  }
+
+  beginMutation(
+    event: string,
+    adminKey: string
+  ): { ticket: BoothRequestTicket; abortedRead: boolean } | null {
+    if (!this.matchesScope(event, adminKey) || this.activeMutation) return null;
+    const abortedRead = this.activeRead !== null;
+    this.activeRead?.controller.abort();
+    this.activeRead = null;
+    this.mutationEpoch += 1;
+    const ticket = this.newRequest("mutation");
+    this.activeMutation = ticket;
+    return { ticket, abortedRead };
+  }
+
+  isMutationCurrent(ticket: BoothRequestTicket): boolean {
+    return (
+      ticket.kind === "mutation"
+      && ticket === this.activeMutation
+      && ticket.generation === this.generation
+      && ticket.mutationEpoch === this.mutationEpoch
+      && !ticket.signal.aborted
+    );
+  }
+
+  finishMutation(ticket: BoothRequestTicket): boolean {
+    const current = this.isMutationCurrent(ticket);
+    if (ticket === this.activeMutation) this.activeMutation = null;
+    return current;
+  }
+
+  acceptFirstPage(ticket: BoothRequestTicket, cursor: string | null): string | null {
+    if (this.isReadCurrent(ticket) && !this.tailInitialized) {
+      this.tailInitialized = true;
+      this.loadedTailCursor = cursor;
+    }
+    return this.loadedTailCursor;
+  }
+
+  advanceTail(ticket: BoothRequestTicket, cursor: string | null): string | null {
+    if (this.isReadCurrent(ticket)) {
+      this.tailInitialized = true;
+      this.loadedTailCursor = cursor;
+    }
+    return this.loadedTailCursor;
+  }
+
+  tailCursor(): string | null {
+    return this.loadedTailCursor;
+  }
+
+  private newRequest(kind: "read" | "mutation"): ActiveBoothRequest {
+    const controller = new AbortController();
+    return {
+      generation: this.generation,
+      mutationEpoch: this.mutationEpoch,
+      kind,
+      signal: controller.signal,
+      controller,
+    };
+  }
+
+  private abortActiveRequests(): void {
+    this.activeRead?.controller.abort();
+    this.activeMutation?.controller.abort();
+    this.activeRead = null;
+    this.activeMutation = null;
+  }
+
+  private matchesScope(event: string, adminKey: string): boolean {
+    return (
+      this.active
+      && event === this.scopeEvent
+      && adminKey === this.scopeAdminKey
+    );
+  }
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function parseBoothOperationalStateResponse(
+  value: unknown
+): BoothOperationalState | null {
+  return parseBoothOperationalState(value);
+}
+
+function parseAdminBoothRecord(value: unknown): AdminBoothRecord | null {
+  if (!isPlainRecord(value) || typeof value.stale !== "boolean") return null;
+  const { stale, ...heartbeatValue } = value;
+  const heartbeat = parseBoothHeartbeatRecord(heartbeatValue);
+  return heartbeat ? { ...heartbeat, stale } : null;
+}
+
+export function parseAdminBoothPage(value: unknown): AdminBoothPage | null {
+  if (
+    !isPlainRecord(value)
+    || Object.keys(value).some((key) => key !== "booths" && key !== "cursor")
+    || !Object.hasOwn(value, "booths")
+    || !Object.hasOwn(value, "cursor")
+    || !Array.isArray(value.booths)
+    || (value.cursor !== null && typeof value.cursor !== "string")
+  ) return null;
+
+  const booths: AdminBoothRecord[] = [];
+  for (const candidate of value.booths) {
+    const booth = parseAdminBoothRecord(candidate);
+    if (!booth) return null;
+    booths.push(booth);
+  }
+  return { booths, cursor: value.cursor };
+}
+
+function parsedLastSeenAt(record: AdminBoothRecord): number | null {
+  const timestamp = Date.parse(record.lastSeenAt);
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
 
 /**
  * Reconcile overlapping opaque pages without ever treating a shortened device
@@ -12,15 +213,27 @@ export function mergeBoothPages(
   for (const page of pages) {
     for (const record of page) {
       const current = byDeviceId.get(record.deviceId);
-      if (!current || Date.parse(record.lastSeenAt) > Date.parse(current.lastSeenAt)) {
+      const incomingTimestamp = parsedLastSeenAt(record);
+      const currentTimestamp = current ? parsedLastSeenAt(current) : null;
+      if (
+        !current
+        || (
+          incomingTimestamp !== null
+          && (currentTimestamp === null || incomingTimestamp > currentTimestamp)
+        )
+      ) {
         byDeviceId.set(record.deviceId, record);
       }
     }
   }
 
-  return [...byDeviceId.values()].sort(
-    (left, right) => Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt)
-  );
+  return [...byDeviceId.values()].sort((left, right) => {
+    const leftTimestamp = parsedLastSeenAt(left);
+    const rightTimestamp = parsedLastSeenAt(right);
+    if (leftTimestamp === null) return rightTimestamp === null ? 0 : 1;
+    if (rightTimestamp === null) return -1;
+    return rightTimestamp - leftTimestamp;
+  });
 }
 
 /** Keep translated operator messages intact while the Admin only edits English. */
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index 9916eef..b92aff5 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -11,7 +11,13 @@ import {
   FrameProgrammeControls,
   SaveConfigurationButton,
 } from "./admin-config-controls";
-import { boothOperationalStateInput, mergeBoothPages } from "./booth-operations";
+import {
+  BoothOperationsCoordinator,
+  boothOperationalStateInput,
+  mergeBoothPages,
+  parseAdminBoothPage,
+  parseBoothOperationalStateResponse,
+} from "./booth-operations";
 import { BoothOperationsPanel } from "./booth-operations-panel";
 import { ConfigHistoryPanel } from "./config-history-panel";
 import {
@@ -28,7 +34,6 @@ type Photo = { key: string; url: string; uploadedAt: string };
 type AuthState = "missing" | "ready" | "invalid";
 type Probe = { status: "up" | "degraded" | "down"; detail: string };
 type Health = { upload: Probe; live: Probe };
-type BoothPage = { booths: AdminBoothRecord[]; cursor: string | null };
 type FilePickerWindow = Window & { showSaveFilePicker?: (options: { suggestedName: string; types: { description: string; accept: Record<string, string[]> }[] }) => Promise<{ createWritable(): Promise<WritableStream<Uint8Array>> }> };
 const CONFIG_CONFLICT_MESSAGE = "Configuration changed; review the latest version before saving.";
 
@@ -69,8 +74,7 @@ export default function Admin() {
   const [boothStatusError, setBoothStatusError] = useState(false);
   const [boothMessageDraft, setBoothMessageDraft] = useState("");
   const photoCursor = useRef<string | null>(null);
-  const boothCursorRef = useRef<string | null>(null);
-  const boothRequestBusy = useRef(false);
+  const boothCoordinator = useRef(new BoothOperationsCoordinator());
   const boothMessageEditing = useRef(false);
   const configMutationBusy = useRef(false);
   const pendingSaveMutationId = useRef<string | null>(null);
@@ -180,8 +184,9 @@ export default function Admin() {
   }, [event]);
 
   const loadBoothStatus = useCallback(async () => {
-    if (boothRequestBusy.current) return;
-    boothRequestBusy.current = true;
+    const coordinator = boothCoordinator.current;
+    const ticket = coordinator.beginRead(event, adminKey);
+    if (!ticket) return;
     setBoothStatusLoading(true);
     setBoothStatusError(false);
     try {
@@ -189,56 +194,81 @@ export default function Admin() {
       const devicesUrl = `/api/booths?event=${encodeURIComponent(event)}`;
       const headers = { "x-booth-key": adminKey };
       const [stateResult, devicesResult] = await Promise.allSettled([
-        fetch(stateUrl, { cache: "no-store", headers }),
-        fetch(devicesUrl, { cache: "no-store", headers }),
+        fetch(stateUrl, { cache: "no-store", headers, signal: ticket.signal }),
+        fetch(devicesUrl, { cache: "no-store", headers, signal: ticket.signal }),
       ]);
+      if (!coordinator.isReadCurrent(ticket)) return;
 
       let failed = false;
       if (stateResult.status === "rejected") {
         failed = true;
       } else if (stateResult.value.status === 401) {
+        coordinator.disposeScope();
         invalidateAuth();
-        failed = true;
+        return;
       } else if (!stateResult.value.ok) {
         failed = true;
       } else {
-        const nextState = await stateResult.value.json() as BoothOperationalState;
-        setBoothOperationalState(nextState);
-        setBoothMessageDraft((current) => boothMessageEditing.current
-          ? current
-          : nextState.messages?.en ?? "");
+        let nextState: BoothOperationalState | null = null;
+        try {
+          nextState = parseBoothOperationalStateResponse(await stateResult.value.json());
+        } catch {
+          // Invalid JSON is handled through the same fixed panel error.
+        }
+        if (!coordinator.isReadCurrent(ticket)) return;
+        if (!nextState) {
+          failed = true;
+        } else {
+          if (!coordinator.isReadCurrent(ticket)) return;
+          setBoothOperationalState(nextState);
+          if (!coordinator.isReadCurrent(ticket)) return;
+          if (!boothMessageEditing.current) {
+            setBoothMessageDraft(nextState.messages?.en ?? "");
+          }
+        }
       }
 
       if (devicesResult.status === "rejected") {
         failed = true;
       } else if (devicesResult.value.status === 401) {
+        coordinator.disposeScope();
         invalidateAuth();
-        failed = true;
+        return;
       } else if (!devicesResult.value.ok) {
         failed = true;
       } else {
-        const page = await devicesResult.value.json() as BoothPage;
-        if (!Array.isArray(page.booths) || (page.cursor !== null && typeof page.cursor !== "string")) {
+        let page = null;
+        try {
+          page = parseAdminBoothPage(await devicesResult.value.json());
+        } catch {
+          // Invalid JSON is handled through the same fixed panel error.
+        }
+        if (!coordinator.isReadCurrent(ticket)) return;
+        if (!page) {
           failed = true;
         } else {
+          if (!coordinator.isReadCurrent(ticket)) return;
           setBoothRecords((current) => mergeBoothPages(current, page.booths));
-          boothCursorRef.current = page.cursor;
-          setBoothCursor(page.cursor);
+          const tailCursor = coordinator.acceptFirstPage(ticket, page.cursor);
+          if (!coordinator.isReadCurrent(ticket)) return;
+          setBoothCursor(tailCursor);
         }
       }
+      if (!coordinator.isReadCurrent(ticket)) return;
       setBoothStatusError(failed);
     } catch {
-      setBoothStatusError(true);
+      if (coordinator.isReadCurrent(ticket)) setBoothStatusError(true);
     } finally {
-      boothRequestBusy.current = false;
-      setBoothStatusLoading(false);
+      if (coordinator.finishRead(ticket)) setBoothStatusLoading(false);
     }
   }, [adminKey, event]);
 
   const loadMoreBooths = useCallback(async () => {
-    const cursor = boothCursorRef.current;
-    if (cursor === null || boothRequestBusy.current) return;
-    boothRequestBusy.current = true;
+    const coordinator = boothCoordinator.current;
+    const cursor = coordinator.tailCursor();
+    if (cursor === null) return;
+    const ticket = coordinator.beginRead(event, adminKey);
+    if (!ticket) return;
     setBoothLoadingMore(true);
     setBoothStatusError(false);
     try {
@@ -246,34 +276,52 @@ export default function Admin() {
       const response = await fetch(`/api/booths?${query}`, {
         cache: "no-store",
         headers: { "x-booth-key": adminKey },
+        signal: ticket.signal,
       });
+      if (!coordinator.isReadCurrent(ticket)) return;
       if (response.status === 401) {
+        coordinator.disposeScope();
         invalidateAuth();
-        setBoothStatusError(true);
         return;
       }
       if (!response.ok) {
+        if (!coordinator.isReadCurrent(ticket)) return;
         setBoothStatusError(true);
         return;
       }
-      const page = await response.json() as BoothPage;
-      if (!Array.isArray(page.booths) || (page.cursor !== null && typeof page.cursor !== "string")) {
+      let page = null;
+      try {
+        page = parseAdminBoothPage(await response.json());
+      } catch {
+        // Invalid JSON is handled through the same fixed panel error.
+      }
+      if (!coordinator.isReadCurrent(ticket)) return;
+      if (!page) {
         setBoothStatusError(true);
         return;
       }
+      if (!coordinator.isReadCurrent(ticket)) return;
       setBoothRecords((current) => mergeBoothPages(current, page.booths));
-      boothCursorRef.current = page.cursor;
-      setBoothCursor(page.cursor);
+      const tailCursor = coordinator.advanceTail(ticket, page.cursor);
+      if (!coordinator.isReadCurrent(ticket)) return;
+      setBoothCursor(tailCursor);
     } catch {
-      setBoothStatusError(true);
+      if (coordinator.isReadCurrent(ticket)) setBoothStatusError(true);
     } finally {
-      boothRequestBusy.current = false;
-      setBoothLoadingMore(false);
+      if (coordinator.finishRead(ticket)) setBoothLoadingMore(false);
     }
   }, [adminKey, event]);
 
   const updateBoothOperationalState = useCallback(async (paused: boolean) => {
-    if (boothMutationBusy || !boothOperationalState) return;
+    if (!boothOperationalState) return;
+    const coordinator = boothCoordinator.current;
+    const mutation = coordinator.beginMutation(event, adminKey);
+    if (!mutation) return;
+    const { ticket, abortedRead } = mutation;
+    if (abortedRead) {
+      setBoothStatusLoading(false);
+      setBoothLoadingMore(false);
+    }
     setBoothMutationBusy(true);
     setBoothStatusError(false);
     try {
@@ -281,31 +329,47 @@ export default function Admin() {
         method: "PUT",
         cache: "no-store",
         headers: { "x-booth-key": adminKey, "content-type": "application/json" },
+        signal: ticket.signal,
         body: JSON.stringify(boothOperationalStateInput(
           boothOperationalState.messages,
           boothMessageDraft,
           paused
         )),
       });
+      if (!coordinator.isMutationCurrent(ticket)) return;
       if (response.status === 401) {
+        coordinator.disposeScope();
         invalidateAuth();
-        setBoothStatusError(true);
         return;
       }
       if (!response.ok) {
+        if (!coordinator.isMutationCurrent(ticket)) return;
+        setBoothStatusError(true);
+        return;
+      }
+      let nextState: BoothOperationalState | null = null;
+      try {
+        nextState = parseBoothOperationalStateResponse(await response.json());
+      } catch {
+        // Invalid JSON is handled through the same fixed panel error.
+      }
+      if (!coordinator.isMutationCurrent(ticket)) return;
+      if (!nextState) {
         setBoothStatusError(true);
         return;
       }
-      const nextState = await response.json() as BoothOperationalState;
+      if (!coordinator.isMutationCurrent(ticket)) return;
       setBoothOperationalState(nextState);
+      if (!coordinator.isMutationCurrent(ticket)) return;
       boothMessageEditing.current = false;
+      if (!coordinator.isMutationCurrent(ticket)) return;
       setBoothMessageDraft(nextState.messages?.en ?? "");
     } catch {
-      setBoothStatusError(true);
+      if (coordinator.isMutationCurrent(ticket)) setBoothStatusError(true);
     } finally {
-      setBoothMutationBusy(false);
+      if (coordinator.finishMutation(ticket)) setBoothMutationBusy(false);
     }
-  }, [adminKey, boothMessageDraft, boothMutationBusy, boothOperationalState, event]);
+  }, [adminKey, boothMessageDraft, boothOperationalState, event]);
 
   useEffect(() => {
     photoCursor.current = null;
@@ -320,12 +384,20 @@ export default function Admin() {
   }, [adminKey, auth, loadConfig]);
 
   useEffect(() => {
-    if (auth !== "ready" || !adminKey) return;
-    boothCursorRef.current = null;
+    const coordinator = boothCoordinator.current;
+    if (auth !== "ready" || !adminKey) {
+      coordinator.disposeScope();
+      return;
+    }
+    coordinator.activateScope(event, adminKey);
     boothMessageEditing.current = false;
     setBoothRecords([]);
     setBoothCursor(null);
     setBoothOperationalState(null);
+    setBoothMessageDraft("");
+    setBoothStatusLoading(false);
+    setBoothLoadingMore(false);
+    setBoothMutationBusy(false);
     setBoothStatusError(false);
     let cancelled = false;
     let nextPoll: number | undefined;
@@ -337,6 +409,7 @@ export default function Admin() {
     return () => {
       cancelled = true;
       if (nextPoll !== undefined) window.clearTimeout(nextPoll);
+      coordinator.disposeScope();
     };
   }, [adminKey, auth, event, loadBoothStatus]);
 

From 7a8858368bcfdcc8b982b28fb388c2a8c2f9fa2d Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 20:58:21 +0800
Subject: [PATCH 044/105] feat: unlock booths with authenticated preflight

---
 app/[event]/booth-session/access.test.ts     |  61 ++++
 app/[event]/booth-session/access.ts          |  40 +++
 app/[event]/booth-session/credential.test.ts | 112 +++++++
 app/[event]/booth-session/credential.ts      |  66 ++++
 app/[event]/booth-unlock.test.tsx            | 115 +++++++
 app/[event]/booth-unlock.tsx                 | 146 +++++++++
 app/[event]/booth.module.css                 | 313 +++++++++++++++++++
 app/[event]/page.tsx                         | 263 ++++++++++++----
 8 files changed, 1056 insertions(+), 60 deletions(-)
 create mode 100644 app/[event]/booth-session/access.test.ts
 create mode 100644 app/[event]/booth-session/access.ts
 create mode 100644 app/[event]/booth-session/credential.test.ts
 create mode 100644 app/[event]/booth-session/credential.ts
 create mode 100644 app/[event]/booth-unlock.test.tsx
 create mode 100644 app/[event]/booth-unlock.tsx

diff --git a/app/[event]/booth-session/access.test.ts b/app/[event]/booth-session/access.test.ts
new file mode 100644
index 0000000..06423a7
--- /dev/null
+++ b/app/[event]/booth-session/access.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { transitionBoothAccess, type BoothAccessState } from "./access";
+
+describe("Booth access state", () => {
+  test("a valid online preflight moves locked through checking to ready", () => {
+    const checking = transitionBoothAccess("locked", { type: "check" });
+    const ready = transitionBoothAccess(checking, { type: "preflight-ready" });
+
+    expect(checking).toBe("checking");
+    expect(ready).toBe("ready");
+  });
+
+  test("a preflight network failure enters recovery-only", () => {
+    expect(
+      transitionBoothAccess("checking", { type: "preflight-network-failed" })
+    ).toBe("recovery-only");
+  });
+
+  test.each([409, 503] as const)(
+    "preflight status %s enters unavailable",
+    (status) => {
+      expect(
+        transitionBoothAccess("checking", {
+          type: "preflight-unavailable",
+          status,
+        })
+      ).toBe("unavailable");
+    }
+  );
+
+  test.each([
+    "checking",
+    "ready",
+    "recovery-only",
+    "unavailable",
+  ] satisfies BoothAccessState[])(
+    "a 401 relocks from %s",
+    (state) => {
+      expect(transitionBoothAccess(state, { type: "unauthorized" })).toBe("locked");
+    }
+  );
+
+  test.each([
+    "locked",
+    "checking",
+    "ready",
+    "recovery-only",
+    "unavailable",
+  ] satisfies BoothAccessState[])(
+    "operator exit moves %s to exited",
+    (state) => {
+      expect(transitionBoothAccess(state, { type: "exit" })).toBe("exited");
+    }
+  );
+
+  test("retry checks again only from a recoverable access state", () => {
+    expect(transitionBoothAccess("recovery-only", { type: "retry" })).toBe("checking");
+    expect(transitionBoothAccess("unavailable", { type: "retry" })).toBe("checking");
+    expect(transitionBoothAccess("ready", { type: "retry" })).toBe("ready");
+  });
+});
diff --git a/app/[event]/booth-session/access.ts b/app/[event]/booth-session/access.ts
new file mode 100644
index 0000000..d35a6f0
--- /dev/null
+++ b/app/[event]/booth-session/access.ts
@@ -0,0 +1,40 @@
+export type BoothAccessState =
+  | "locked"
+  | "checking"
+  | "ready"
+  | "recovery-only"
+  | "unavailable"
+  | "exited";
+
+export type BoothAccessEvent =
+  | { type: "check" }
+  | { type: "preflight-ready" }
+  | { type: "preflight-network-failed" }
+  | { type: "preflight-unavailable"; status: 409 | 503 }
+  | { type: "retry" }
+  | { type: "unauthorized" }
+  | { type: "exit" };
+
+export function transitionBoothAccess(
+  state: BoothAccessState,
+  event: BoothAccessEvent
+): BoothAccessState {
+  if (state === "exited") return state;
+  if (event.type === "exit") return "exited";
+  if (event.type === "unauthorized") return "locked";
+
+  if (event.type === "check") {
+    return state === "locked" ? "checking" : state;
+  }
+  if (event.type === "retry") {
+    return state === "recovery-only" || state === "unavailable"
+      ? "checking"
+      : state;
+  }
+  if (state !== "checking") return state;
+
+  if (event.type === "preflight-ready") return "ready";
+  if (event.type === "preflight-network-failed") return "recovery-only";
+  if (event.type === "preflight-unavailable") return "unavailable";
+  return state;
+}
diff --git a/app/[event]/booth-session/credential.test.ts b/app/[event]/booth-session/credential.test.ts
new file mode 100644
index 0000000..085191b
--- /dev/null
+++ b/app/[event]/booth-session/credential.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+import {
+  clearBoothCredential,
+  loadBoothCredential,
+  saveBoothCredential,
+} from "./credential";
+
+class MemoryStorage implements Storage {
+  private readonly values = new Map<string, string>();
+
+  get length() {
+    return this.values.size;
+  }
+
+  clear() {
+    this.values.clear();
+  }
+
+  getItem(key: string) {
+    return this.values.get(key) ?? null;
+  }
+
+  key(index: number) {
+    return [...this.values.keys()][index] ?? null;
+  }
+
+  removeItem(key: string) {
+    this.values.delete(key);
+  }
+
+  setItem(key: string, value: string) {
+    this.values.set(key, value);
+  }
+}
+
+class FailingStorage extends MemoryStorage {
+  override getItem(_key: string): string | null {
+    throw new DOMException("Storage unavailable", "SecurityError");
+  }
+
+  override removeItem(_key: string): void {
+    throw new DOMException("Storage unavailable", "SecurityError");
+  }
+
+  override setItem(_key: string, _value: string): void {
+    throw new DOMException("Storage unavailable", "SecurityError");
+  }
+}
+
+describe("Booth credential persistence", () => {
+  test("loads the session credential before a remembered credential", () => {
+    const session = new MemoryStorage();
+    const local = new MemoryStorage();
+    session.setItem("webbooth:launch:booth-key", "session-key");
+    local.setItem("webbooth:launch:booth-key", "remembered-key");
+
+    expect(loadBoothCredential("launch", session, local)).toEqual({
+      key: "session-key",
+      persistence: "session",
+    });
+  });
+
+  test("remembering a credential moves it from session to local storage", () => {
+    const session = new MemoryStorage();
+    const local = new MemoryStorage();
+    session.setItem("webbooth:launch:booth-key", "old-session-key");
+
+    saveBoothCredential("launch", "remembered-key", true, session, local);
+
+    expect(session.getItem("webbooth:launch:booth-key")).toBeNull();
+    expect(local.getItem("webbooth:launch:booth-key")).toBe("remembered-key");
+  });
+
+  test("the default credential moves from local to session storage", () => {
+    const session = new MemoryStorage();
+    const local = new MemoryStorage();
+    local.setItem("webbooth:launch:booth-key", "old-remembered-key");
+
+    saveBoothCredential("launch", "session-key", false, session, local);
+
+    expect(session.getItem("webbooth:launch:booth-key")).toBe("session-key");
+    expect(local.getItem("webbooth:launch:booth-key")).toBeNull();
+  });
+
+  test("clears both persistence choices for only the intended Event", () => {
+    const session = new MemoryStorage();
+    const local = new MemoryStorage();
+    session.setItem("webbooth:launch:booth-key", "session-key");
+    local.setItem("webbooth:launch:booth-key", "remembered-key");
+    session.setItem("webbooth:other:booth-key", "other-session-key");
+    local.setItem("unrelated", "keep-me");
+
+    clearBoothCredential("launch", session, local);
+
+    expect(session.getItem("webbooth:launch:booth-key")).toBeNull();
+    expect(local.getItem("webbooth:launch:booth-key")).toBeNull();
+    expect(session.getItem("webbooth:other:booth-key")).toBe("other-session-key");
+    expect(local.getItem("unrelated")).toBe("keep-me");
+  });
+
+  test("storage failures do not discard the caller's active in-memory credential", () => {
+    const active = { key: "current-page-key" };
+    const broken = new FailingStorage();
+
+    expect(() => {
+      saveBoothCredential("launch", active.key, true, broken, broken);
+      clearBoothCredential("launch", broken, broken);
+    }).not.toThrow();
+    expect(loadBoothCredential("launch", broken, broken)).toBeNull();
+    expect(active.key).toBe("current-page-key");
+  });
+});
diff --git a/app/[event]/booth-session/credential.ts b/app/[event]/booth-session/credential.ts
new file mode 100644
index 0000000..dcea3c8
--- /dev/null
+++ b/app/[event]/booth-session/credential.ts
@@ -0,0 +1,66 @@
+export type StoredCredential = {
+  key: string;
+  persistence: "session" | "local";
+};
+
+type CredentialStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+
+function credentialKey(event: string) {
+  return `webbooth:${event}:booth-key`;
+}
+
+function read(storage: CredentialStorage, key: string) {
+  try {
+    return storage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function remove(storage: CredentialStorage, key: string) {
+  try {
+    storage.removeItem(key);
+  } catch {
+    // The active page keeps its in-memory key even when persistence is blocked.
+  }
+}
+
+export function loadBoothCredential(
+  event: string,
+  session: CredentialStorage,
+  local: CredentialStorage
+): StoredCredential | null {
+  const storageKey = credentialKey(event);
+  const sessionKey = read(session, storageKey);
+  if (sessionKey) return { key: sessionKey, persistence: "session" };
+  const localKey = read(local, storageKey);
+  return localKey ? { key: localKey, persistence: "local" } : null;
+}
+
+export function saveBoothCredential(
+  event: string,
+  key: string,
+  remember: boolean,
+  session: CredentialStorage,
+  local: CredentialStorage
+): void {
+  const storageKey = credentialKey(event);
+  const target = remember ? local : session;
+  const previous = remember ? session : local;
+  try {
+    target.setItem(storageKey, key);
+    remove(previous, storageKey);
+  } catch {
+    // Callers retain the submitted key in memory without claiming persistence.
+  }
+}
+
+export function clearBoothCredential(
+  event: string,
+  session: CredentialStorage,
+  local: CredentialStorage
+): void {
+  const storageKey = credentialKey(event);
+  remove(session, storageKey);
+  remove(local, storageKey);
+}
diff --git a/app/[event]/booth-unlock.test.tsx b/app/[event]/booth-unlock.test.tsx
new file mode 100644
index 0000000..02ec085
--- /dev/null
+++ b/app/[event]/booth-unlock.test.tsx
@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { BoothUnlock } from "./booth-unlock";
+
+const secret = "never-render-this-booth-key";
+
+function render(
+  state: "locked" | "checking" | "recovery-only" | "unavailable",
+  pendingCount = 0
+) {
+  return renderToStaticMarkup(
+    <BoothUnlock
+      event="launch"
+      state={state}
+      pendingCount={pendingCount}
+      durable
+      onUnlock={(key) => {
+        if (key === secret) throw new Error("not called during static render");
+      }}
+      onRetry={() => {}}
+    />
+  );
+}
+
+describe("Booth unlock", () => {
+  test("locked markup has labeled password and remember controls", () => {
+    const html = render("locked");
+
+    expect(html).toMatch(/<h1[^>]*>Unlock Booth<\/h1>/);
+    expect(html).toMatch(/<label[^>]*for="booth-key"/);
+    expect(html).toMatch(/<input[^>]*id="booth-key"[^>]*type="password"/);
+    expect(html).toContain("Remember on this iPad");
+    expect(html).toMatch(/<input[^>]*type="checkbox"/);
+    expect(html).toContain('role="status"');
+  });
+
+  test("a supplied key remains only in the callback and never enters markup", () => {
+    const html = render("locked");
+
+    expect(html).not.toContain(secret);
+  });
+
+  test("checking is explicit and prevents duplicate unlock attempts", () => {
+    const html = render("checking", 2);
+
+    expect(html).toContain("Checking Booth access");
+    expect(html).toContain("2 photos waiting safely");
+    expect(html).toContain("disabled");
+    expect(html).not.toContain(secret);
+  });
+
+  test("recovery-only explains that pending photos remain without enabling capture", () => {
+    const html = render("recovery-only", 1);
+
+    expect(html).toContain("Connection needed");
+    expect(html).toContain("1 photo waiting safely");
+    expect(html).toContain(">Try again</button>");
+    expect(html).not.toContain("<input");
+  });
+
+  test("unavailable gives the operator a plain retry action", () => {
+    const html = render("unavailable");
+
+    expect(html).toContain("Booth unavailable");
+    expect(html).toContain("Check the Event setup, then try again.");
+    expect(html).toContain(">Try again</button>");
+  });
+});
+
+describe("Booth startup integration", () => {
+  test("recovers the Outbox before credential access and uses authenticated preflight", async () => {
+    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
+    const recoverAt = source.indexOf("await session.recover()");
+    const credentialAt = source.indexOf("const stored = loadBoothCredential(");
+
+    expect(recoverAt).toBeGreaterThan(-1);
+    expect(credentialAt).toBeGreaterThan(recoverAt);
+    expect(source).toContain("/api/booth/preflight?event=");
+    expect(source).toContain('"x-booth-key": key');
+    expect(source).not.toContain("window.prompt");
+    expect(source).not.toContain("/api/config?event=");
+  });
+
+  test("gates retry and camera start on successful preflight and relocks on 401", async () => {
+    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
+    const successfulPreflight = source.indexOf("if (response.ok)");
+    const readyBranch = source.slice(successfulPreflight, source.indexOf("} catch", successfulPreflight));
+
+    expect(successfulPreflight).toBeGreaterThan(-1);
+    expect(readyBranch).toContain("session.start()");
+    expect(readyBranch).toContain("startCamera()");
+    expect(source).toContain(
+      "clearBoothCredential(event, window.sessionStorage, window.localStorage)"
+    );
+    expect(source).toContain('accessState !== "ready"');
+    expect(source).toContain("request !== cameraRequestRef.current");
+  });
+});
+
+describe("Booth unlock presentation", () => {
+  test("keeps touch controls large and keyboard focus visible in forced colors", async () => {
+    const css = await Bun.file(`${import.meta.dir}/booth.module.css`).text();
+
+    expect(css).toContain("min-height: 44px");
+    expect(css).toContain("@media (forced-colors: active)");
+    expect(css).toContain("outline:");
+  });
+
+  test("removes unlock motion when reduced motion is requested", async () => {
+    const css = await Bun.file(`${import.meta.dir}/booth.module.css`).text();
+
+    expect(css).toContain("@media (prefers-reduced-motion: reduce)");
+    expect(css).toContain("animation: none");
+  });
+});
diff --git a/app/[event]/booth-unlock.tsx b/app/[event]/booth-unlock.tsx
new file mode 100644
index 0000000..d33b5ab
--- /dev/null
+++ b/app/[event]/booth-unlock.tsx
@@ -0,0 +1,146 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+import type { BoothAccessState } from "./booth-session/access";
+import styles from "./booth.module.css";
+
+type UnlockState = Extract<
+  BoothAccessState,
+  "locked" | "checking" | "recovery-only" | "unavailable"
+>;
+
+export type BoothUnlockProps = {
+  event: string;
+  state: UnlockState;
+  pendingCount: number;
+  durable: boolean;
+  outboxRecovered?: boolean;
+  onUnlock: (key: string, remember: boolean) => void;
+  onRetry: () => void;
+};
+
+function pendingLabel(pendingCount: number) {
+  if (pendingCount === 0) return "No photos waiting";
+  return `${pendingCount} photo${pendingCount === 1 ? "" : "s"} waiting safely`;
+}
+
+export function BoothUnlock({
+  event,
+  state,
+  pendingCount,
+  durable,
+  outboxRecovered = true,
+  onUnlock,
+  onRetry,
+}: BoothUnlockProps) {
+  const [key, setKey] = useState("");
+  const [remember, setRemember] = useState(false);
+  const checking = state === "checking" || !outboxRecovered;
+
+  const submit = (submitEvent: FormEvent<HTMLFormElement>) => {
+    submitEvent.preventDefault();
+    const submittedKey = key;
+    setKey("");
+    if (submittedKey) onUnlock(submittedKey, remember);
+  };
+
+  const title = !outboxRecovered
+    ? "Recovering saved photos"
+    : state === "checking"
+      ? "Checking Booth access"
+      : state === "recovery-only"
+        ? "Connection needed"
+        : state === "unavailable"
+          ? "Booth unavailable"
+          : "Unlock Booth";
+
+  return (
+    <section className={styles.unlock} aria-labelledby="booth-unlock-title">
+      <div className={styles.unlockPanel}>
+        <header className={styles.unlockHeader}>
+          <p className={styles.unlockEyebrow}>Event operator · {event}</p>
+          <h1 id="booth-unlock-title">{title}</h1>
+          <p className={styles.unlockLead}>
+            {!outboxRecovered
+              ? "Checking this iPad for photos that still need to upload."
+              : state === "locked"
+                ? "Enter the Booth Key to prepare this iPad for guests."
+                : state === "checking"
+                  ? "Confirming the Event and enabled Frames."
+                  : state === "recovery-only"
+                    ? "Connect this iPad to the internet before taking new photos."
+                    : "Check the Event setup, then try again."}
+          </p>
+        </header>
+
+        <div className={styles.readinessRail} aria-label="Booth readiness">
+          <div data-ready={outboxRecovered}>
+            <span>Photo Outbox</span>
+            <strong>{outboxRecovered ? pendingLabel(pendingCount) : "Recovering"}</strong>
+          </div>
+          <div data-ready={false}>
+            <span>Booth access</span>
+            <strong>
+              {state === "checking"
+                ? "Checking"
+                : state === "locked"
+                  ? "Locked"
+                  : state === "recovery-only"
+                    ? "Offline"
+                    : "Unavailable"}
+            </strong>
+          </div>
+          <div data-ready={false}>
+            <span>Camera</span>
+            <strong>Waiting</strong>
+          </div>
+        </div>
+
+        <div className={styles.unlockStatus} role="status" aria-live="polite">
+          <strong>{pendingLabel(pendingCount)}</strong>
+          <span>
+            {durable
+              ? "Saved photos stay on this iPad until upload succeeds."
+              : "Keep this page open. Reload recovery is unavailable on this iPad."}
+          </span>
+        </div>
+
+        {state === "locked" ? (
+          <form className={styles.unlockForm} onSubmit={submit}>
+            <label htmlFor="booth-key">Booth Key</label>
+            <input
+              id="booth-key"
+              name="booth-key"
+              type="password"
+              autoComplete="current-password"
+              required
+              disabled={checking}
+              value={key}
+              onChange={(inputEvent) => setKey(inputEvent.target.value)}
+            />
+            <label className={styles.remember}>
+              <input
+                type="checkbox"
+                checked={remember}
+                disabled={checking}
+                onChange={(inputEvent) => setRemember(inputEvent.target.checked)}
+              />
+              <span>Remember on this iPad</span>
+            </label>
+            <button type="submit" disabled={checking || key.length === 0}>
+              Unlock Booth
+            </button>
+          </form>
+        ) : state === "recovery-only" || state === "unavailable" ? (
+          <button className={styles.unlockRetry} type="button" onClick={onRetry}>
+            Try again
+          </button>
+        ) : (
+          <button className={styles.unlockRetry} type="button" disabled>
+            Checking…
+          </button>
+        )}
+      </div>
+    </section>
+  );
+}
diff --git a/app/[event]/booth.module.css b/app/[event]/booth.module.css
index ecf6123..f269c65 100644
--- a/app/[event]/booth.module.css
+++ b/app/[event]/booth.module.css
@@ -256,3 +256,316 @@
   font-weight: 650;
   z-index: 6;
 }
+
+/* Operator unlock: one calm, explicit path from recovered Outbox to camera. */
+.unlock {
+  --unlock-surface: #111119;
+  --unlock-raised: #191924;
+  --unlock-line: #353543;
+  --unlock-muted: #b9b8c6;
+  --unlock-signal: #ff2d8b;
+  --unlock-safe: #70e0bb;
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  display: grid;
+  place-items: center;
+  overflow: auto;
+  padding:
+    max(28px, env(safe-area-inset-top, 0px))
+    max(28px, env(safe-area-inset-right, 0px))
+    max(28px, env(safe-area-inset-bottom, 0px))
+    max(28px, env(safe-area-inset-left, 0px));
+  background: #07070c;
+  color: #fff;
+}
+
+.unlockPanel {
+  width: min(760px, 100%);
+  padding: clamp(28px, 5vw, 54px);
+  border: 1px solid var(--unlock-line);
+  border-radius: 28px;
+  background: var(--unlock-surface);
+  box-shadow: 0 26px 80px rgba(0, 0, 0, 0.5);
+  animation: unlock-arrive 180ms ease-out both;
+}
+
+@keyframes unlock-arrive {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.unlockHeader {
+  max-width: 610px;
+}
+
+.unlockEyebrow {
+  margin: 0 0 12px;
+  color: #ff8fc2;
+  font: 800 12px/1.3 ui-monospace, "SFMono-Regular", Menlo, monospace;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.unlockHeader h1 {
+  margin: 0;
+  font: 850 clamp(38px, 7vw, 64px)/0.98 ui-rounded, "Arial Rounded MT Bold", system-ui, sans-serif;
+  letter-spacing: -0.045em;
+}
+
+.unlockLead {
+  max-width: 560px;
+  margin: 18px 0 0;
+  color: var(--unlock-muted);
+  font-size: clamp(17px, 2.4vw, 21px);
+  line-height: 1.45;
+}
+
+.readinessRail {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  margin: 32px 0 22px;
+  overflow: hidden;
+  border: 1px solid var(--unlock-line);
+  border-radius: 16px;
+  background: #0b0b11;
+}
+
+.readinessRail > div {
+  position: relative;
+  min-width: 0;
+  min-height: 82px;
+  padding: 16px 18px 15px 21px;
+  border-right: 1px solid var(--unlock-line);
+}
+
+.readinessRail > div:last-child {
+  border-right: 0;
+}
+
+.readinessRail > div::before {
+  position: absolute;
+  top: 17px;
+  left: 10px;
+  width: 4px;
+  height: 34px;
+  border-radius: 4px;
+  background: #686779;
+  content: "";
+}
+
+.readinessRail > div[data-ready="true"]::before {
+  background: var(--unlock-safe);
+}
+
+.readinessRail span,
+.readinessRail strong {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.readinessRail span {
+  margin-bottom: 7px;
+  color: #8e8d9d;
+  font: 750 10px/1.2 ui-monospace, "SFMono-Regular", Menlo, monospace;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.readinessRail strong {
+  color: #f4f3f8;
+  font-size: 14px;
+  line-height: 1.25;
+  white-space: nowrap;
+}
+
+.readinessRail > div[data-ready="true"] strong {
+  color: var(--unlock-safe);
+}
+
+.unlockStatus {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 18px;
+  margin-bottom: 24px;
+  color: var(--unlock-muted);
+  font-size: 13px;
+  line-height: 1.4;
+}
+
+.unlockStatus strong {
+  flex: 0 0 auto;
+  color: #fff;
+}
+
+.unlockStatus span {
+  text-align: right;
+}
+
+.unlockForm {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 10px 14px;
+}
+
+.unlockForm > label:first-child {
+  grid-column: 1 / -1;
+  color: #f4f3f8;
+  font-size: 14px;
+  font-weight: 750;
+}
+
+.unlockForm > input {
+  width: 100%;
+  min-height: 56px;
+  padding: 0 16px;
+  border: 2px solid #4a4959;
+  border-radius: 14px;
+  outline: none;
+  background: #09090e;
+  color: #fff;
+  font-size: 20px;
+}
+
+.unlockForm > input:focus-visible {
+  border-color: #fff;
+  outline: 3px solid var(--unlock-signal);
+  outline-offset: 3px;
+}
+
+.unlockForm button,
+.unlockRetry {
+  min-width: 168px;
+  min-height: 56px;
+  padding: 0 24px;
+  border: 0;
+  border-radius: 14px;
+  background: var(--unlock-signal);
+  color: #fff;
+  font-size: 17px;
+  font-weight: 800;
+  cursor: pointer;
+}
+
+.unlockForm button:disabled,
+.unlockRetry:disabled {
+  cursor: wait;
+  opacity: 0.55;
+}
+
+.unlockForm button:focus-visible,
+.unlockRetry:focus-visible,
+.remember:focus-within {
+  outline: 3px solid #fff;
+  outline-offset: 4px;
+}
+
+.remember {
+  grid-column: 1 / -1;
+  display: inline-flex;
+  width: fit-content;
+  min-height: 44px;
+  align-items: center;
+  gap: 11px;
+  border-radius: 8px;
+  color: var(--unlock-muted);
+  font-size: 15px;
+  cursor: pointer;
+}
+
+.remember input {
+  width: 24px;
+  height: 24px;
+  accent-color: var(--unlock-signal);
+}
+
+.unlockRetry {
+  display: block;
+  margin-left: auto;
+}
+
+@media (max-width: 620px) {
+  .unlock {
+    place-items: start center;
+    padding: 18px;
+  }
+
+  .unlockPanel {
+    padding: 26px 22px;
+    border-radius: 22px;
+  }
+
+  .readinessRail {
+    grid-template-columns: 1fr;
+  }
+
+  .readinessRail > div {
+    min-height: 67px;
+    border-right: 0;
+    border-bottom: 1px solid var(--unlock-line);
+  }
+
+  .readinessRail > div:last-child {
+    border-bottom: 0;
+  }
+
+  .unlockStatus {
+    align-items: flex-start;
+    flex-direction: column;
+    gap: 5px;
+  }
+
+  .unlockStatus span {
+    text-align: left;
+  }
+
+  .unlockForm {
+    grid-template-columns: 1fr;
+  }
+
+  .unlockForm button,
+  .unlockRetry {
+    width: 100%;
+  }
+}
+
+@media (forced-colors: active) {
+  .unlock,
+  .unlockPanel,
+  .readinessRail,
+  .readinessRail > div,
+  .unlockForm > input {
+    border-color: CanvasText;
+    background: Canvas;
+    color: CanvasText;
+    forced-color-adjust: auto;
+  }
+
+  .unlockForm button:focus-visible,
+  .unlockRetry:focus-visible,
+  .unlockForm > input:focus-visible,
+  .remember:focus-within {
+    outline: 3px solid Highlight;
+    outline-offset: 4px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .unlockPanel,
+  .flash {
+    animation: none;
+  }
+
+  .choice:active,
+  .shutter:active {
+    transform: none;
+  }
+}
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 4c63256..935e982 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -8,6 +8,16 @@ import { createOutboxStore, type OutboxItem } from "./booth-session/outbox";
 import { BoothSession, runCaptureSequence, type UploadState } from "./booth-session/session";
 import { outboxUploadHeaders } from "./booth-session/upload";
 import { HttpUploadError, type UploadErrorClass } from "./booth-session/retry-policy";
+import {
+  transitionBoothAccess,
+  type BoothAccessState,
+} from "./booth-session/access";
+import {
+  clearBoothCredential,
+  loadBoothCredential,
+  saveBoothCredential,
+} from "./booth-session/credential";
+import { BoothUnlock } from "./booth-unlock";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
 
@@ -25,8 +35,13 @@ export default function Booth() {
   const streamRef = useRef<MediaStream | null>(null);
   const sessionRef = useRef<BoothSession | null>(null);
   const captureRef = useRef<AbortController | null>(null);
+  const preflightRef = useRef<AbortController | null>(null);
+  const cameraRequestRef = useRef(0);
   const unmountedRef = useRef(false);
+  const keyRef = useRef("");
   const [status, setStatus] = useState<Status>("starting");
+  const [accessState, setAccessState] = useState<BoothAccessState>("locked");
+  const [outboxRecovered, setOutboxRecovered] = useState(false);
   const [mode, setMode] = useState<keyof typeof TEMPLATES | null>(null);
   const [count, setCount] = useState(0);
   const [shot, setShot] = useState(0); // e.g. 2 of 3
@@ -39,38 +54,12 @@ export default function Booth() {
     error: null,
     durable: true,
   });
-  // per-event frame allowlist from /api/config; null (no config / not loaded
-  // yet / fetch failed) degrades to defaults-only, never to all frames
+  // Frames remain unavailable until authenticated preflight returns the safe
+  // Event experience. `null` is never shown while the Booth is locked.
   const [enabled, setEnabled] = useState<string[] | null>(null);
-  const [configRevisionId, setConfigRevisionId] = useState<string | undefined>();
-
-  useEffect(() => {
-    fetch(`/api/config?event=${encodeURIComponent(event)}`)
-      .then((r) => r.json())
-      .then((d) => {
-        setEnabled(Array.isArray(d.frames) ? d.frames : null);
-        setConfigRevisionId(typeof d.currentRevisionId === "string" ? d.currentRevisionId : undefined);
-      })
-      .catch(() => {});
-  }, [event]);
-
-  // this event's booth key (set per event in /{event}/admin) — asked once,
-  // kept in localStorage namespaced by event, cleared + re-asked on 401
-  const keyRef = useRef<string>("");
-  const storageKey = `boothKey:${event}`;
-  const promptKey = useCallback(() => {
-    const k = window.prompt("Enter this event's booth key") ?? "";
-    if (k) localStorage.setItem(storageKey, k);
-    else localStorage.removeItem(storageKey);
-    keyRef.current = k;
-  }, [storageKey]);
-  useEffect(() => {
-    const k = localStorage.getItem(storageKey);
-    if (k) keyRef.current = k;
-    else promptKey();
-  }, [storageKey, promptKey]);
 
   const startCamera = useCallback(async () => {
+    const request = ++cameraRequestRef.current;
     setStatus("starting");
     setError(null);
     try {
@@ -80,7 +69,7 @@ export default function Booth() {
       });
       // unmounted while getUserMedia was pending: stop the tracks now or the
       // camera light stays on with nothing to clean it up
-      if (unmountedRef.current) {
+      if (unmountedRef.current || request !== cameraRequestRef.current) {
         stream.getTracks().forEach((t) => t.stop());
         return;
       }
@@ -90,8 +79,14 @@ export default function Booth() {
         videoRef.current.srcObject = stream;
         await videoRef.current.play();
       }
+      if (unmountedRef.current || request !== cameraRequestRef.current) {
+        stream.getTracks().forEach((track) => track.stop());
+        if (streamRef.current === stream) streamRef.current = null;
+        return;
+      }
       setStatus("picking");
     } catch (e) {
+      if (unmountedRef.current || request !== cameraRequestRef.current) return;
       setStatus("denied");
       setError(e instanceof Error ? e.message : String(e));
     }
@@ -99,14 +94,15 @@ export default function Booth() {
 
   useEffect(() => {
     unmountedRef.current = false;
-    startCamera();
     return () => {
       unmountedRef.current = true;
+      cameraRequestRef.current++;
+      preflightRef.current?.abort();
       captureRef.current?.abort();
       streamRef.current?.getTracks().forEach((t) => t.stop());
       streamRef.current = null;
     };
-  }, [startCamera]);
+  }, []);
 
   // grab the current video frame, mirrored to match the preview, at full res
   const grabFrame = useCallback((): HTMLCanvasElement => {
@@ -144,9 +140,102 @@ export default function Booth() {
     [event]
   );
 
+  const relockAfterUnauthorized = useCallback(() => {
+    clearBoothCredential(event, window.sessionStorage, window.localStorage);
+    keyRef.current = "";
+    preflightRef.current?.abort();
+    cameraRequestRef.current++;
+    captureRef.current?.abort();
+    streamRef.current?.getTracks().forEach((track) => track.stop());
+    streamRef.current = null;
+    setEnabled(null);
+    setMode(null);
+    setStatus("starting");
+    setAccessState((current) =>
+      transitionBoothAccess(current, { type: "unauthorized" })
+    );
+    void sessionRef.current?.stop();
+  }, [event]);
+
+  const attemptPreflight = useCallback(async (key: string) => {
+    const session = sessionRef.current;
+    if (!session || !key) return;
+
+    preflightRef.current?.abort();
+    const controller = new AbortController();
+    preflightRef.current = controller;
+    setAccessState((current) =>
+      current === "locked"
+        ? transitionBoothAccess(current, { type: "check" })
+        : transitionBoothAccess(current, { type: "retry" })
+    );
+
+    try {
+      const response = await fetch(
+        `/api/booth/preflight?event=${encodeURIComponent(event)}`,
+        {
+          method: "POST",
+          headers: { "x-booth-key": key },
+          signal: controller.signal,
+        }
+      );
+      if (controller.signal.aborted) return;
+
+      if (response.status === 401) {
+        relockAfterUnauthorized();
+        return;
+      }
+      if (response.status === 409 || response.status === 503) {
+        const unavailableStatus = response.status === 409 ? 409 : 503;
+        setAccessState((current) =>
+          transitionBoothAccess(current, {
+            type: "preflight-unavailable",
+            status: unavailableStatus,
+          })
+        );
+        return;
+      }
+      if (response.ok) {
+        const payload = await response.json() as {
+          experience?: { frames?: unknown };
+        };
+        if (
+          !Array.isArray(payload.experience?.frames) ||
+          payload.experience.frames.some((frame) => typeof frame !== "string")
+        ) {
+          setAccessState((current) =>
+            transitionBoothAccess(current, { type: "preflight-network-failed" })
+          );
+          return;
+        }
+        setEnabled([...payload.experience.frames] as string[]);
+        setAccessState((current) =>
+          transitionBoothAccess(current, { type: "preflight-ready" })
+        );
+        void session.start();
+        void startCamera();
+        return;
+      }
+
+      setAccessState((current) =>
+        transitionBoothAccess(current, { type: "preflight-network-failed" })
+      );
+    } catch {
+      if (controller.signal.aborted) return;
+      setAccessState((current) =>
+        transitionBoothAccess(current, { type: "preflight-network-failed" })
+      );
+    }
+  }, [event, relockAfterUnauthorized, startCamera]);
+
   useEffect(() => {
     let active = true;
-    const session = new BoothSession(
+    setAccessState("locked");
+    setOutboxRecovered(false);
+    setEnabled(null);
+    keyRef.current = "";
+    let session!: BoothSession;
+    session = new BoothSession(
       event,
       createOutboxStore(),
       uploadOne,
@@ -155,10 +244,7 @@ export default function Booth() {
       undefined,
       {
         onAuthRequired: () => {
-          // Keep the existing credential lifecycle: clear the rejected Booth
-          // Key and let the retained manual Retry control prompt for a new one.
-          localStorage.removeItem(storageKey);
-          keyRef.current = "";
+          if (sessionRef.current === session) relockAfterUnauthorized();
         },
       }
     );
@@ -170,30 +256,62 @@ export default function Booth() {
     };
     window.addEventListener("online", reconsiderConnectivity);
     document.addEventListener("visibilitychange", reconsiderForeground);
-    // Task 4 will add strict preflight. Until then, recovery plus the existing
-    // Booth Key lifecycle is the only available start condition.
-    void session.recover().then(() => {
-      if (active) void session.start();
-    });
+    void (async () => {
+      await session.recover();
+      if (!active) return;
+      setOutboxRecovered(true);
+      const stored = loadBoothCredential(
+        event,
+        window.sessionStorage,
+        window.localStorage
+      );
+      if (!stored) return;
+      keyRef.current = stored.key;
+      await attemptPreflight(stored.key);
+    })();
     return () => {
       active = false;
+      cameraRequestRef.current++;
+      preflightRef.current?.abort();
+      captureRef.current?.abort();
+      streamRef.current?.getTracks().forEach((track) => track.stop());
+      streamRef.current = null;
       unsubscribe();
       window.removeEventListener("online", reconsiderConnectivity);
       document.removeEventListener("visibilitychange", reconsiderForeground);
       if (sessionRef.current === session) sessionRef.current = null;
       void session.stop();
     };
-  }, [event, storageKey, uploadOne]);
+  }, [attemptPreflight, event, relockAfterUnauthorized, uploadOne]);
+
+  const unlock = useCallback((key: string, remember: boolean) => {
+    keyRef.current = key;
+    saveBoothCredential(
+      event,
+      key,
+      remember,
+      window.sessionStorage,
+      window.localStorage
+    );
+    void attemptPreflight(key);
+  }, [attemptPreflight, event]);
+
+  const retryPreflight = useCallback(() => {
+    if (!keyRef.current) {
+      relockAfterUnauthorized();
+      return;
+    }
+    void attemptPreflight(keyRef.current);
+  }, [attemptPreflight, relockAfterUnauthorized]);
 
   const retryUpload = useCallback(() => {
-    if (!uploadState.pendingCount) return;
-    if (!keyRef.current) promptKey();
+    if (accessState !== "ready" || !uploadState.pendingCount) return;
     void sessionRef.current?.retry();
-  }, [uploadState.pendingCount, promptKey]);
+  }, [accessState, uploadState.pendingCount]);
 
   // take the whole sequence for the chosen mode, composite, upload
   const run = useCallback(async () => {
-    if (status !== "ready" || !mode) return;
+    if (accessState !== "ready" || status !== "ready" || !mode) return;
     const t = TEMPLATES[mode];
     setStatus("running");
     const controller = new AbortController();
@@ -221,7 +339,6 @@ export default function Booth() {
           metadata: {
             source: "framed",
             frameKey: mode,
-            ...(configRevisionId ? { configRevisionId } : {}),
           },
         }
       );
@@ -243,7 +360,7 @@ export default function Booth() {
     } finally {
       if (captureRef.current === controller) captureRef.current = null;
     }
-  }, [status, mode, grabFrame]);
+  }, [accessState, status, mode, grabFrame]);
 
   // fallback: native file input (camera) when getUserMedia is blocked.
   // Re-encode to a real JPEG first — iPhones hand back HEIC, and the stored
@@ -251,6 +368,10 @@ export default function Booth() {
   // ponytail: fallback photos stay frameless; compositing needs the live capture flow.
   const onFile = useCallback(
     async (e: React.ChangeEvent<HTMLInputElement>) => {
+      if (accessState !== "ready") {
+        e.target.value = "";
+        return;
+      }
       const file = e.target.files?.[0];
       e.target.value = "";
       if (!file) return;
@@ -275,7 +396,6 @@ export default function Booth() {
         }, {
           metadata: {
             source: "camera-fallback",
-            ...(configRevisionId ? { configRevisionId } : {}),
           },
         });
         setError(null);
@@ -284,10 +404,11 @@ export default function Booth() {
         setError(uploadError instanceof Error ? uploadError.message : String(uploadError));
       }
     },
-    [configRevisionId]
+    [accessState]
   );
 
   const pick = (m: keyof typeof TEMPLATES) => {
+    if (accessState !== "ready") return;
     setMode(m);
     setStatus("ready");
   };
@@ -320,7 +441,7 @@ export default function Booth() {
         </div>
       )}
 
-      {status === "picking" && (
+      {accessState === "ready" && status === "picking" && (
         <div className={styles.picker}>
           {lastUrl && (
             // eslint-disable-next-line @next/next/no-img-element
@@ -350,17 +471,24 @@ export default function Booth() {
         </div>
       )}
 
-      {status === "denied" && (
+      {accessState === "ready" && status === "denied" && (
         <div className={styles.picker}>
           <p>Camera unavailable. Use your device camera instead:</p>
           <label className={styles.fileBtn}>
             Take a photo
-            <input type="file" accept="image/*" capture="user" onChange={onFile} hidden />
+            <input
+              type="file"
+              accept="image/*"
+              capture="user"
+              onChange={onFile}
+              disabled={accessState !== "ready"}
+              hidden
+            />
           </label>
         </div>
       )}
 
-      {(status === "ready" || status === "running") && (
+      {accessState === "ready" && (status === "ready" || status === "running") && (
         <div className={styles.bottom}>
           {lastUrl && (
             // eslint-disable-next-line @next/next/no-img-element
@@ -369,12 +497,16 @@ export default function Booth() {
           <button
             className={styles.shutter}
             onClick={run}
-            disabled={status !== "ready"}
+            disabled={accessState !== "ready" || status !== "ready"}
             aria-label="Start"
           >
             {status === "running" ? "" : mode && TEMPLATES[mode].shots > 1 ? "▶" : ""}
           </button>
-          <button className={styles.change} onClick={() => setStatus("picking")} disabled={status !== "ready"}>
+          <button
+            className={styles.change}
+            onClick={() => setStatus("picking")}
+            disabled={accessState !== "ready" || status !== "ready"}
+          >
             {mode && TEMPLATES[mode].label} · change
           </button>
           <a className={styles.liveLink} href={`/${event}/live`} target="_blank" rel="noreferrer">
@@ -383,7 +515,7 @@ export default function Booth() {
         </div>
       )}
 
-      {uploadState.pendingCount > 0 && status !== "running" && (
+      {accessState === "ready" && uploadState.pendingCount > 0 && status !== "running" && (
         <button
           className={styles.retry}
           onClick={retryUpload}
@@ -395,12 +527,23 @@ export default function Booth() {
             : `⟳ Retry ${uploadState.pendingCount} pending`}
         </button>
       )}
-      {(error || uploadState.error) && (
+      {accessState !== "ready" && accessState !== "exited" && (
+        <BoothUnlock
+          event={event}
+          state={accessState}
+          pendingCount={uploadState.pendingCount}
+          durable={uploadState.durable}
+          outboxRecovered={outboxRecovered}
+          onUnlock={unlock}
+          onRetry={retryPreflight}
+        />
+      )}
+      {accessState === "ready" && (error || uploadState.error) && (
         <div className={styles.error} onClick={() => setError(null)}>
           {error || uploadState.error}
         </div>
       )}
-      {!uploadState.durable && (
+      {accessState === "ready" && !uploadState.durable && (
         <div className={styles.storageWarning} role="status">
           Offline photo storage is unavailable. Pending photos may be lost if this page reloads.
         </div>

From bf2422baeb4250df07d33d91e70881c0b3136b01 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:13:34 +0800
Subject: [PATCH 045/105] fix: fence booth unlock lifecycle

---
 app/[event]/booth-session/lifecycle.test.ts | 248 +++++++++++++++++
 app/[event]/booth-session/lifecycle.ts      | 228 +++++++++++++++
 app/[event]/booth-unlock.test.tsx           |  68 +++--
 app/[event]/booth-unlock.tsx                |  94 ++++++-
 app/[event]/page.tsx                        | 289 ++++++++++----------
 5 files changed, 740 insertions(+), 187 deletions(-)
 create mode 100644 app/[event]/booth-session/lifecycle.test.ts
 create mode 100644 app/[event]/booth-session/lifecycle.ts

diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
new file mode 100644
index 0000000..8e19f30
--- /dev/null
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -0,0 +1,248 @@
+import { describe, expect, test } from "bun:test";
+import {
+  BoothLifecycleCoordinator,
+  usablePreflightFrames,
+  type BoothLifecycleSession,
+  type BoothPreflightResult,
+} from "./lifecycle";
+
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  const promise = new Promise<T>((next) => {
+    resolve = next;
+  });
+  return { promise, resolve };
+}
+
+class FakeSession implements BoothLifecycleSession {
+  readonly actions: string[] = [];
+  recoverWork: Promise<void> = Promise.resolve();
+  stopWork: Promise<void> = Promise.resolve();
+  onRetry: () => void = () => {};
+
+  async recover() {
+    this.actions.push("recover");
+    await this.recoverWork;
+    this.actions.push("recovered");
+  }
+
+  start() {
+    this.actions.push("start");
+    return Promise.resolve();
+  }
+
+  async retry() {
+    this.actions.push("retry");
+    this.onRetry();
+  }
+
+  async stop() {
+    this.actions.push("stop");
+    await this.stopWork;
+    this.actions.push("stopped");
+  }
+}
+
+function harness(options: {
+  stored?: Record<string, string>;
+  preflight?: (
+    event: string,
+    key: string,
+    signal: AbortSignal
+  ) => Promise<BoothPreflightResult>;
+} = {}) {
+  const events: string[] = [];
+  const access: string[] = [];
+  const frames: Array<string[] | null> = [];
+  const credentials: string[] = [];
+  const uploaded: string[] = [];
+  const cleared: string[] = [];
+  let cameraStarts = 0;
+  let cameraStops = 0;
+  let loads = 0;
+  const coordinator = new BoothLifecycleCoordinator<{ url: string }>({
+    preflight: options.preflight ?? (async () => ({ kind: "ready", frames: ["square"] })),
+    loadCredential: (event) => {
+      loads++;
+      const key = options.stored?.[event];
+      return key ? { key } : null;
+    },
+    clearCredential: (event) => cleared.push(event),
+    onReset: (event) => events.push(event),
+    onOutboxRecovered: () => events.push("outbox-recovered"),
+    onAccess: (state, feedback) => access.push(`${state}:${feedback}`),
+    onFrames: (next) => frames.push(next),
+    onCredential: (key) => credentials.push(key),
+    onCameraStart: () => {
+      cameraStarts++;
+    },
+    onCameraStop: () => {
+      cameraStops++;
+    },
+    onUploaded: ({ url }) => uploaded.push(url),
+  });
+  return {
+    coordinator,
+    events,
+    access,
+    frames,
+    credentials,
+    uploaded,
+    cleared,
+    cameraStarts: () => cameraStarts,
+    cameraStops: () => cameraStops,
+    loads: () => loads,
+  };
+}
+
+describe("Booth lifecycle coordination", () => {
+  test("completes Outbox recovery before reading a stored credential or preflighting", async () => {
+    const recovery = deferred<void>();
+    const calls: string[] = [];
+    const session = new FakeSession();
+    session.recoverWork = recovery.promise;
+    const h = harness({
+      stored: { launch: "stored-key" },
+      preflight: async () => {
+        calls.push("preflight");
+        return { kind: "ready", frames: ["square"] };
+      },
+    });
+
+    const entering = h.coordinator.beginEvent("launch", session);
+    expect(session.actions).toEqual(["recover"]);
+    expect(h.loads()).toBe(0);
+    expect(calls).toEqual([]);
+    expect(h.cameraStarts()).toBe(0);
+
+    recovery.resolve();
+    await entering;
+
+    expect(h.loads()).toBe(1);
+    expect(calls).toEqual(["preflight"]);
+    expect(session.actions).toEqual(["recover", "recovered", "start"]);
+    expect(h.cameraStarts()).toBe(1);
+  });
+
+  test("awaits the owning stop, then automatically retries an auth-blocked photo", async () => {
+    const stopping = deferred<void>();
+    const session = new FakeSession();
+    session.stopWork = stopping.promise;
+    const h = harness({ stored: { launch: "first-key" } });
+    session.onRetry = () => h.coordinator.acceptUploaded(session, { url: "/acked" });
+    await h.coordinator.beginEvent("launch", session);
+
+    void h.coordinator.authRequired(session);
+    expect(h.cleared).toEqual(["launch"]);
+    expect(h.access.at(-1)).toBe("locked:rejected-key");
+    expect(session.actions).toContain("stop");
+
+    const unlocking = h.coordinator.unlock("correct-key");
+    await Promise.resolve();
+    expect(session.actions.filter((action) => action === "start")).toHaveLength(1);
+    expect(session.actions).not.toContain("retry");
+    expect(h.uploaded).toEqual([]);
+
+    stopping.resolve();
+    await unlocking;
+
+    expect(session.actions.filter((action) => action === "start")).toHaveLength(2);
+    expect(session.actions.at(-1)).toBe("retry");
+    expect(h.uploaded).toEqual(["/acked"]);
+    expect(h.cameraStarts()).toBe(2);
+  });
+
+  test("ignores an out-of-order rejected preflight after a newer success", async () => {
+    const first = deferred<BoothPreflightResult>();
+    const second = deferred<BoothPreflightResult>();
+    let attempts = 0;
+    const h = harness({
+      preflight: async () => (++attempts === 1 ? first.promise : second.promise),
+    });
+    const session = new FakeSession();
+    await h.coordinator.beginEvent("launch", session);
+
+    const stale = h.coordinator.unlock("old-key");
+    const current = h.coordinator.unlock("new-key");
+    second.resolve({ kind: "ready", frames: ["square"] });
+    await current;
+    first.resolve({ kind: "unauthorized" });
+    await stale;
+
+    expect(h.access.at(-1)).toBe("ready:ready");
+    expect(h.cleared).toEqual([]);
+    expect(session.actions.filter((action) => action === "start")).toHaveLength(1);
+    expect(h.cameraStarts()).toBe(1);
+  });
+
+  test("StrictMode-style cleanup prevents deferred recovery from starting old work", async () => {
+    const recovery = deferred<void>();
+    const oldSession = new FakeSession();
+    oldSession.recoverWork = recovery.promise;
+    const h = harness({ stored: { launch: "stored-key" } });
+
+    const entering = h.coordinator.beginEvent("launch", oldSession);
+    await h.coordinator.leaveEvent(oldSession);
+    recovery.resolve();
+    await entering;
+
+    expect(h.loads()).toBe(0);
+    expect(oldSession.actions).toEqual(["recover", "stop", "stopped", "recovered"]);
+    expect(h.cameraStarts()).toBe(0);
+  });
+
+  test("Event switch fences stale upload callbacks and starts with a full reset", async () => {
+    const h = harness();
+    const first = new FakeSession();
+    const second = new FakeSession();
+    await h.coordinator.beginEvent("first", first);
+    h.coordinator.acceptUploaded(first, { url: "/first-before-switch" });
+
+    await h.coordinator.beginEvent("second", second);
+    h.coordinator.acceptUploaded(first, { url: "/stale" });
+    h.coordinator.acceptUploaded(second, { url: "/second" });
+
+    expect(h.events.filter((event) => event !== "outbox-recovered")).toEqual([
+      "first",
+      "second",
+    ]);
+    expect(h.uploaded).toEqual(["/first-before-switch", "/second"]);
+    expect(h.credentials.at(-1)).toBe("");
+    expect(h.frames.at(-1)).toBeNull();
+    expect(h.cameraStops()).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe("preflight Frame validation", () => {
+  test("keeps only current usable Frames", () => {
+    expect(usablePreflightFrames(["unknown", "square"])).toEqual(["square"]);
+  });
+
+  test.each([
+    { value: null },
+    { value: {} },
+    { value: [] },
+    { value: ["unknown"] },
+    { value: ["square", 42] },
+  ])("rejects malformed, empty, or unknown-only Frames: $value", ({ value }) => {
+    expect(usablePreflightFrames(value)).toBeNull();
+  });
+
+  test.each([
+    { kind: "ready", frames: [] },
+    { kind: "ready", frames: ["unknown"] },
+    { kind: "ready", frames: { square: true } },
+  ] satisfies BoothPreflightResult[])(
+    "does not start Session or camera for unusable successful preflight %#",
+    async (reply) => {
+      const h = harness({ preflight: async () => reply });
+      const session = new FakeSession();
+      await h.coordinator.beginEvent("launch", session);
+      await h.coordinator.unlock("key");
+
+      expect(h.access.at(-1)).toBe("unavailable:unavailable");
+      expect(session.actions).not.toContain("start");
+      expect(h.cameraStarts()).toBe(0);
+    }
+  );
+});
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
new file mode 100644
index 0000000..3db2675
--- /dev/null
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -0,0 +1,228 @@
+import { availableTemplates } from "../../templates";
+import type { BoothAccessState } from "./access";
+
+export type BoothAccessFeedback =
+  | "recovering"
+  | "locked"
+  | "checking"
+  | "network"
+  | "unavailable"
+  | "rejected-key"
+  | "ready";
+
+export type BoothPreflightResult =
+  | { kind: "ready"; frames: unknown }
+  | { kind: "unauthorized" }
+  | { kind: "unavailable" }
+  | { kind: "recovery-only" };
+
+export interface BoothLifecycleSession {
+  recover(): Promise<void>;
+  start(): Promise<void> | void;
+  retry(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+type ActiveSession = {
+  id: number;
+  event: string;
+  session: BoothLifecycleSession;
+  key: string;
+  authBlocked: boolean;
+  stopPromise?: Promise<void>;
+};
+
+type BoothLifecycleDependencies<Result> = {
+  preflight: (
+    event: string,
+    key: string,
+    signal: AbortSignal
+  ) => Promise<BoothPreflightResult>;
+  loadCredential: (event: string) => { key: string } | null;
+  clearCredential: (event: string) => void;
+  onReset: (event: string) => void;
+  onOutboxRecovered: () => void;
+  onAccess: (state: BoothAccessState, feedback: BoothAccessFeedback) => void;
+  onFrames: (frames: string[] | null) => void;
+  onCredential: (key: string) => void;
+  onCameraStart: () => void;
+  onCameraStop: () => void;
+  onUploaded: (result: Result) => void;
+};
+
+export function usablePreflightFrames(value: unknown): string[] | null {
+  if (!Array.isArray(value) || !value.every((frame) => typeof frame === "string")) {
+    return null;
+  }
+  const usable = availableTemplates(value);
+  return usable.length > 0 ? usable : null;
+}
+
+export class BoothLifecycleCoordinator<Result> {
+  private active: ActiveSession | null = null;
+  private nextSessionId = 0;
+  private nextPreflightId = 0;
+  private preflightController: AbortController | null = null;
+
+  constructor(private readonly deps: BoothLifecycleDependencies<Result>) {}
+
+  isActive(session: BoothLifecycleSession) {
+    return this.active?.session === session;
+  }
+
+  async beginEvent(event: string, session: BoothLifecycleSession) {
+    const previous = this.active;
+    this.preflightController?.abort();
+    if (previous) void this.ensureStopped(previous);
+    this.deps.onCameraStop();
+
+    const active: ActiveSession = {
+      id: ++this.nextSessionId,
+      event,
+      session,
+      key: "",
+      authBlocked: false,
+    };
+    this.active = active;
+    this.deps.onReset(event);
+    this.deps.onCredential("");
+    this.deps.onFrames(null);
+    this.deps.onAccess("locked", "recovering");
+
+    try {
+      await session.recover();
+    } catch {
+      if (!this.isCurrent(active)) return;
+      this.deps.onOutboxRecovered();
+      this.deps.onAccess("recovery-only", "network");
+      return;
+    }
+    if (!this.isCurrent(active)) return;
+
+    this.deps.onOutboxRecovered();
+    this.deps.onAccess("locked", "locked");
+    const stored = this.deps.loadCredential(event);
+    if (!stored) return;
+    active.key = stored.key;
+    this.deps.onCredential(stored.key);
+    await this.checkCredential(active, stored.key);
+  }
+
+  async leaveEvent(session: BoothLifecycleSession) {
+    const active = this.active;
+    if (!active || active.session !== session) return;
+    this.active = null;
+    this.preflightController?.abort();
+    this.deps.onCameraStop();
+    await this.ensureStopped(active);
+  }
+
+  unlock(key: string) {
+    const active = this.active;
+    if (!active || !key) return Promise.resolve();
+    active.key = key;
+    this.deps.onCredential(key);
+    return this.checkCredential(active, key);
+  }
+
+  retryPreflight() {
+    const active = this.active;
+    if (!active || !active.key) return Promise.resolve();
+    return this.checkCredential(active, active.key);
+  }
+
+  authRequired(session: BoothLifecycleSession) {
+    const active = this.active;
+    if (!active || active.session !== session) return Promise.resolve();
+    active.authBlocked = true;
+    return this.relock(active);
+  }
+
+  acceptUploaded(session: BoothLifecycleSession, result: Result) {
+    if (this.active?.session === session) this.deps.onUploaded(result);
+  }
+
+  private isCurrent(active: ActiveSession, preflightId?: number) {
+    return this.active === active
+      && (preflightId === undefined || preflightId === this.nextPreflightId);
+  }
+
+  private ensureStopped(active: ActiveSession) {
+    if (!active.stopPromise) {
+      try {
+        active.stopPromise = Promise.resolve(active.session.stop()).catch(() => {
+          // A stopped Session cannot mutate the active Event. A later
+          // authenticated start remains the only path back to capture.
+        });
+      } catch {
+        active.stopPromise = Promise.resolve();
+      }
+    }
+    return active.stopPromise;
+  }
+
+  private relock(active: ActiveSession) {
+    if (!this.isCurrent(active)) return Promise.resolve();
+    this.preflightController?.abort();
+    active.key = "";
+    this.deps.onCredential("");
+    this.deps.clearCredential(active.event);
+    this.deps.onFrames(null);
+    this.deps.onCameraStop();
+    this.deps.onAccess("locked", "rejected-key");
+    return this.ensureStopped(active);
+  }
+
+  private async checkCredential(active: ActiveSession, key: string) {
+    if (!this.isCurrent(active)) return;
+    this.preflightController?.abort();
+    const controller = new AbortController();
+    this.preflightController = controller;
+    const preflightId = ++this.nextPreflightId;
+    this.deps.onAccess("checking", "checking");
+
+    let result: BoothPreflightResult;
+    try {
+      result = await this.deps.preflight(active.event, key, controller.signal);
+    } catch {
+      if (controller.signal.aborted || !this.isCurrent(active, preflightId)) return;
+      this.deps.onAccess("recovery-only", "network");
+      return;
+    }
+    if (controller.signal.aborted || !this.isCurrent(active, preflightId)) return;
+
+    if (result.kind === "unauthorized") {
+      void this.relock(active);
+      return;
+    }
+    if (result.kind === "unavailable") {
+      this.deps.onAccess("unavailable", "unavailable");
+      return;
+    }
+    if (result.kind === "recovery-only") {
+      this.deps.onAccess("recovery-only", "network");
+      return;
+    }
+
+    const frames = usablePreflightFrames(result.frames);
+    if (!frames) {
+      this.deps.onFrames(null);
+      this.deps.onAccess("unavailable", "unavailable");
+      return;
+    }
+
+    if (active.stopPromise) await active.stopPromise;
+    if (!this.isCurrent(active, preflightId)) return;
+
+    this.deps.onFrames(frames);
+    this.deps.onAccess("ready", "ready");
+    void Promise.resolve(active.session.start()).catch(() => {
+      // Session state reports upload failures without invalidating preflight.
+    });
+    this.deps.onCameraStart();
+    if (active.authBlocked) {
+      active.authBlocked = false;
+      await active.session.retry();
+    }
+  }
+}
diff --git a/app/[event]/booth-unlock.test.tsx b/app/[event]/booth-unlock.test.tsx
index 02ec085..73b2d54 100644
--- a/app/[event]/booth-unlock.test.tsx
+++ b/app/[event]/booth-unlock.test.tsx
@@ -1,12 +1,18 @@
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
-import { BoothUnlock } from "./booth-unlock";
+import {
+  BoothUnlock,
+  createUnlockFormState,
+  unlockFormReducer,
+} from "./booth-unlock";
+import type { BoothAccessFeedback } from "./booth-session/lifecycle";
 
 const secret = "never-render-this-booth-key";
 
 function render(
   state: "locked" | "checking" | "recovery-only" | "unavailable",
-  pendingCount = 0
+  pendingCount = 0,
+  feedback?: BoothAccessFeedback
 ) {
   return renderToStaticMarkup(
     <BoothUnlock
@@ -14,6 +20,7 @@ function render(
       state={state}
       pendingCount={pendingCount}
       durable
+      feedback={feedback}
       onUnlock={(key) => {
         if (key === secret) throw new Error("not called during static render");
       }}
@@ -65,35 +72,48 @@ describe("Booth unlock", () => {
     expect(html).toContain("Check the Event setup, then try again.");
     expect(html).toContain(">Try again</button>");
   });
+
+  test("announces rejected credentials with fixed non-secret copy", () => {
+    const html = render("locked", 2, "rejected-key");
+
+    expect(html).toContain('role="alert"');
+    expect(html).toContain("Booth Key rejected. Enter the current key and try again.");
+    expect(html).not.toContain(secret);
+  });
+
+  test.each([
+    ["checking", "Checking Booth access online."],
+    ["network", "Could not reach Booth service. Pending photos are still safe."],
+    ["unavailable", "This Event is not ready for Booth capture."],
+  ] satisfies Array<[BoothAccessFeedback, string]>)(
+    "announces %s feedback in the live region",
+    (feedback, message) => {
+      expect(render(
+        feedback === "network" ? "recovery-only" : feedback === "unavailable" ? "unavailable" : "checking",
+        0,
+        feedback
+      )).toContain(message);
+    }
+  );
+
+  test("changing Event identity clears typed key and remember state", () => {
+    let form = createUnlockFormState("first");
+    form = unlockFormReducer(form, { type: "key-changed", key: secret });
+    form = unlockFormReducer(form, { type: "remember-changed", remember: true });
+    form = unlockFormReducer(form, { type: "event-changed", event: "second" });
+
+    expect(form).toEqual({ event: "second", key: "", remember: false });
+  });
 });
 
-describe("Booth startup integration", () => {
-  test("recovers the Outbox before credential access and uses authenticated preflight", async () => {
+describe("Booth page safety wiring", () => {
+  test("uses authenticated preflight without prompt or public config startup", async () => {
     const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
-    const recoverAt = source.indexOf("await session.recover()");
-    const credentialAt = source.indexOf("const stored = loadBoothCredential(");
 
-    expect(recoverAt).toBeGreaterThan(-1);
-    expect(credentialAt).toBeGreaterThan(recoverAt);
     expect(source).toContain("/api/booth/preflight?event=");
-    expect(source).toContain('"x-booth-key": key');
     expect(source).not.toContain("window.prompt");
     expect(source).not.toContain("/api/config?event=");
-  });
-
-  test("gates retry and camera start on successful preflight and relocks on 401", async () => {
-    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
-    const successfulPreflight = source.indexOf("if (response.ok)");
-    const readyBranch = source.slice(successfulPreflight, source.indexOf("} catch", successfulPreflight));
-
-    expect(successfulPreflight).toBeGreaterThan(-1);
-    expect(readyBranch).toContain("session.start()");
-    expect(readyBranch).toContain("startCamera()");
-    expect(source).toContain(
-      "clearBoothCredential(event, window.sessionStorage, window.localStorage)"
-    );
-    expect(source).toContain('accessState !== "ready"');
-    expect(source).toContain("request !== cameraRequestRef.current");
+    expect(source).toContain("key={event}");
   });
 });
 
diff --git a/app/[event]/booth-unlock.tsx b/app/[event]/booth-unlock.tsx
index d33b5ab..90e4668 100644
--- a/app/[event]/booth-unlock.tsx
+++ b/app/[event]/booth-unlock.tsx
@@ -1,7 +1,8 @@
 "use client";
 
-import { useState, type FormEvent } from "react";
+import { useEffect, useReducer, type FormEvent } from "react";
 import type { BoothAccessState } from "./booth-session/access";
+import type { BoothAccessFeedback } from "./booth-session/lifecycle";
 import styles from "./booth.module.css";
 
 type UnlockState = Extract<
@@ -12,6 +13,7 @@ type UnlockState = Extract<
 export type BoothUnlockProps = {
   event: string;
   state: UnlockState;
+  feedback?: BoothAccessFeedback;
   pendingCount: number;
   durable: boolean;
   outboxRecovered?: boolean;
@@ -19,6 +21,36 @@ export type BoothUnlockProps = {
   onRetry: () => void;
 };
 
+export type UnlockFormState = {
+  event: string;
+  key: string;
+  remember: boolean;
+};
+
+export type UnlockFormEvent =
+  | { type: "event-changed"; event: string }
+  | { type: "key-changed"; key: string }
+  | { type: "remember-changed"; remember: boolean }
+  | { type: "submitted" };
+
+export function createUnlockFormState(event: string): UnlockFormState {
+  return { event, key: "", remember: false };
+}
+
+export function unlockFormReducer(
+  state: UnlockFormState,
+  event: UnlockFormEvent
+): UnlockFormState {
+  if (event.type === "event-changed") {
+    return event.event === state.event ? state : createUnlockFormState(event.event);
+  }
+  if (event.type === "key-changed") return { ...state, key: event.key };
+  if (event.type === "remember-changed") {
+    return { ...state, remember: event.remember };
+  }
+  return { ...state, key: "" };
+}
+
 function pendingLabel(pendingCount: number) {
   if (pendingCount === 0) return "No photos waiting";
   return `${pendingCount} photo${pendingCount === 1 ? "" : "s"} waiting safely`;
@@ -27,23 +59,49 @@ function pendingLabel(pendingCount: number) {
 export function BoothUnlock({
   event,
   state,
+  feedback = state === "checking"
+    ? "checking"
+    : state === "recovery-only"
+      ? "network"
+      : state === "unavailable"
+        ? "unavailable"
+        : "locked",
   pendingCount,
   durable,
   outboxRecovered = true,
   onUnlock,
   onRetry,
 }: BoothUnlockProps) {
-  const [key, setKey] = useState("");
-  const [remember, setRemember] = useState(false);
+  const [form, dispatch] = useReducer(
+    unlockFormReducer,
+    event,
+    createUnlockFormState
+  );
   const checking = state === "checking" || !outboxRecovered;
 
+  useEffect(() => {
+    dispatch({ type: "event-changed", event });
+  }, [event]);
+
   const submit = (submitEvent: FormEvent<HTMLFormElement>) => {
     submitEvent.preventDefault();
-    const submittedKey = key;
-    setKey("");
-    if (submittedKey) onUnlock(submittedKey, remember);
+    const submittedKey = form.key;
+    dispatch({ type: "submitted" });
+    if (submittedKey) onUnlock(submittedKey, form.remember);
   };
 
+  const accessMessage = feedback === "rejected-key"
+    ? "Booth Key rejected. Enter the current key and try again."
+    : feedback === "checking"
+      ? "Checking Booth access online."
+      : feedback === "network"
+        ? "Could not reach Booth service. Pending photos are still safe."
+        : feedback === "unavailable"
+          ? "This Event is not ready for Booth capture."
+          : feedback === "recovering"
+            ? "Recovering photos saved on this iPad."
+            : "Booth is locked.";
+
   const title = !outboxRecovered
     ? "Recovering saved photos"
     : state === "checking"
@@ -96,8 +154,13 @@ export function BoothUnlock({
           </div>
         </div>
 
-        <div className={styles.unlockStatus} role="status" aria-live="polite">
+        <div
+          className={styles.unlockStatus}
+          role={feedback === "rejected-key" ? "alert" : "status"}
+          aria-live={feedback === "rejected-key" ? "assertive" : "polite"}
+        >
           <strong>{pendingLabel(pendingCount)}</strong>
+          <span>{accessMessage}</span>
           <span>
             {durable
               ? "Saved photos stay on this iPad until upload succeeds."
@@ -115,19 +178,26 @@ export function BoothUnlock({
               autoComplete="current-password"
               required
               disabled={checking}
-              value={key}
-              onChange={(inputEvent) => setKey(inputEvent.target.value)}
+              value={form.key}
+              onChange={(inputEvent) =>
+                dispatch({ type: "key-changed", key: inputEvent.target.value })
+              }
             />
             <label className={styles.remember}>
               <input
                 type="checkbox"
-                checked={remember}
+                checked={form.remember}
                 disabled={checking}
-                onChange={(inputEvent) => setRemember(inputEvent.target.checked)}
+                onChange={(inputEvent) =>
+                  dispatch({
+                    type: "remember-changed",
+                    remember: inputEvent.target.checked,
+                  })
+                }
               />
               <span>Remember on this iPad</span>
             </label>
-            <button type="submit" disabled={checking || key.length === 0}>
+            <button type="submit" disabled={checking || form.key.length === 0}>
               Unlock Booth
             </button>
           </form>
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 935e982..a8d28f1 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -1,26 +1,40 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useParams } from "next/navigation";
 import styles from "./booth.module.css";
 import { TEMPLATES, availableTemplates, composite } from "../templates";
 import { createOutboxStore, type OutboxItem } from "./booth-session/outbox";
-import { BoothSession, runCaptureSequence, type UploadState } from "./booth-session/session";
+import {
+  BoothSession,
+  runCaptureSequence,
+  type UploadResult,
+  type UploadState,
+} from "./booth-session/session";
 import { outboxUploadHeaders } from "./booth-session/upload";
 import { HttpUploadError, type UploadErrorClass } from "./booth-session/retry-policy";
-import {
-  transitionBoothAccess,
-  type BoothAccessState,
-} from "./booth-session/access";
+import type { BoothAccessState } from "./booth-session/access";
 import {
   clearBoothCredential,
   loadBoothCredential,
   saveBoothCredential,
 } from "./booth-session/credential";
+import {
+  BoothLifecycleCoordinator,
+  type BoothAccessFeedback,
+  type BoothPreflightResult,
+} from "./booth-session/lifecycle";
 import { BoothUnlock } from "./booth-unlock";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
 
+const INITIAL_UPLOAD_STATE: UploadState = {
+  status: "idle",
+  pendingCount: 0,
+  error: null,
+  durable: true,
+};
+
 function uploadErrorClass(status: number): UploadErrorClass {
   if (status === 401) return "auth";
   if (status === 408 || status === 425 || status === 429) return "timeout";
@@ -29,18 +43,41 @@ function uploadErrorClass(status: number): UploadErrorClass {
   return "unknown";
 }
 
+async function requestBoothPreflight(
+  event: string,
+  key: string,
+  signal: AbortSignal
+): Promise<BoothPreflightResult> {
+  const response = await fetch(
+    `/api/booth/preflight?event=${encodeURIComponent(event)}`,
+    {
+      method: "POST",
+      headers: { "x-booth-key": key },
+      signal,
+    }
+  );
+  if (response.status === 401) return { kind: "unauthorized" };
+  if (response.status === 409 || response.status === 503) {
+    return { kind: "unavailable" };
+  }
+  if (!response.ok) return { kind: "recovery-only" };
+  const payload = await response.json() as { experience?: { frames?: unknown } };
+  return { kind: "ready", frames: payload.experience?.frames };
+}
+
 export default function Booth() {
   const { event } = useParams<{ event: string }>();
   const videoRef = useRef<HTMLVideoElement>(null);
   const streamRef = useRef<MediaStream | null>(null);
   const sessionRef = useRef<BoothSession | null>(null);
   const captureRef = useRef<AbortController | null>(null);
-  const preflightRef = useRef<AbortController | null>(null);
   const cameraRequestRef = useRef(0);
   const unmountedRef = useRef(false);
   const keyRef = useRef("");
   const [status, setStatus] = useState<Status>("starting");
   const [accessState, setAccessState] = useState<BoothAccessState>("locked");
+  const [accessFeedback, setAccessFeedback] =
+    useState<BoothAccessFeedback>("recovering");
   const [outboxRecovered, setOutboxRecovered] = useState(false);
   const [mode, setMode] = useState<keyof typeof TEMPLATES | null>(null);
   const [count, setCount] = useState(0);
@@ -48,12 +85,8 @@ export default function Booth() {
   const [flash, setFlash] = useState(false);
   const [lastUrl, setLastUrl] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
-  const [uploadState, setUploadState] = useState<UploadState>({
-    status: "idle",
-    pendingCount: 0,
-    error: null,
-    durable: true,
-  });
+  const [uploadState, setUploadState] =
+    useState<UploadState>(INITIAL_UPLOAD_STATE);
   // Frames remain unavailable until authenticated preflight returns the safe
   // Event experience. `null` is never shown while the Booth is locked.
   const [enabled, setEnabled] = useState<string[] | null>(null);
@@ -92,17 +125,75 @@ export default function Booth() {
     }
   }, []);
 
+  const stopCamera = useCallback(() => {
+    cameraRequestRef.current++;
+    captureRef.current?.abort();
+    captureRef.current = null;
+    streamRef.current?.getTracks().forEach((track) => track.stop());
+    streamRef.current = null;
+    if (videoRef.current) videoRef.current.srcObject = null;
+  }, []);
+
+  const lifecycle = useMemo(
+    () => new BoothLifecycleCoordinator<UploadResult>({
+      preflight: requestBoothPreflight,
+      loadCredential: (nextEvent) =>
+        loadBoothCredential(
+          nextEvent,
+          window.sessionStorage,
+          window.localStorage
+        ),
+      clearCredential: (nextEvent) =>
+        clearBoothCredential(
+          nextEvent,
+          window.sessionStorage,
+          window.localStorage
+        ),
+      onReset: () => {
+        setStatus("starting");
+        setMode(null);
+        setLastUrl(null);
+        setError(null);
+        setCount(0);
+        setShot(0);
+        setFlash(false);
+        setEnabled(null);
+        setOutboxRecovered(false);
+        setUploadState(INITIAL_UPLOAD_STATE);
+      },
+      onOutboxRecovered: () => setOutboxRecovered(true),
+      onAccess: (state, feedback) => {
+        if (state === "locked" && feedback === "rejected-key") {
+          setStatus("starting");
+          setMode(null);
+          setError(null);
+          setCount(0);
+          setShot(0);
+          setFlash(false);
+        }
+        setAccessState(state);
+        setAccessFeedback(feedback);
+      },
+      onFrames: setEnabled,
+      onCredential: (key) => {
+        keyRef.current = key;
+      },
+      onCameraStart: () => {
+        void startCamera();
+      },
+      onCameraStop: stopCamera,
+      onUploaded: ({ url }) => setLastUrl(url),
+    }),
+    [startCamera, stopCamera]
+  );
+
   useEffect(() => {
     unmountedRef.current = false;
     return () => {
       unmountedRef.current = true;
-      cameraRequestRef.current++;
-      preflightRef.current?.abort();
-      captureRef.current?.abort();
-      streamRef.current?.getTracks().forEach((t) => t.stop());
-      streamRef.current = null;
+      stopCamera();
     };
-  }, []);
+  }, [stopCamera]);
 
   // grab the current video frame, mirrored to match the preview, at full res
   const grabFrame = useCallback((): HTMLCanvasElement => {
@@ -140,152 +231,41 @@ export default function Booth() {
     [event]
   );
 
-  const relockAfterUnauthorized = useCallback(() => {
-    clearBoothCredential(event, window.sessionStorage, window.localStorage);
-    keyRef.current = "";
-    preflightRef.current?.abort();
-    cameraRequestRef.current++;
-    captureRef.current?.abort();
-    streamRef.current?.getTracks().forEach((track) => track.stop());
-    streamRef.current = null;
-    setEnabled(null);
-    setMode(null);
-    setStatus("starting");
-    setAccessState((current) =>
-      transitionBoothAccess(current, { type: "unauthorized" })
-    );
-    void sessionRef.current?.stop();
-  }, [event]);
-
-  const attemptPreflight = useCallback(async (key: string) => {
-    const session = sessionRef.current;
-    if (!session || !key) return;
-
-    preflightRef.current?.abort();
-    const controller = new AbortController();
-    preflightRef.current = controller;
-    setAccessState((current) =>
-      current === "locked"
-        ? transitionBoothAccess(current, { type: "check" })
-        : transitionBoothAccess(current, { type: "retry" })
-    );
-
-    try {
-      const response = await fetch(
-        `/api/booth/preflight?event=${encodeURIComponent(event)}`,
-        {
-          method: "POST",
-          headers: { "x-booth-key": key },
-          signal: controller.signal,
-        }
-      );
-      if (controller.signal.aborted) return;
-
-      if (response.status === 401) {
-        relockAfterUnauthorized();
-        return;
-      }
-      if (response.status === 409 || response.status === 503) {
-        const unavailableStatus = response.status === 409 ? 409 : 503;
-        setAccessState((current) =>
-          transitionBoothAccess(current, {
-            type: "preflight-unavailable",
-            status: unavailableStatus,
-          })
-        );
-        return;
-      }
-      if (response.ok) {
-        const payload = await response.json() as {
-          experience?: { frames?: unknown };
-        };
-        if (
-          !Array.isArray(payload.experience?.frames) ||
-          payload.experience.frames.some((frame) => typeof frame !== "string")
-        ) {
-          setAccessState((current) =>
-            transitionBoothAccess(current, { type: "preflight-network-failed" })
-          );
-          return;
-        }
-        setEnabled([...payload.experience.frames] as string[]);
-        setAccessState((current) =>
-          transitionBoothAccess(current, { type: "preflight-ready" })
-        );
-        void session.start();
-        void startCamera();
-        return;
-      }
-
-      setAccessState((current) =>
-        transitionBoothAccess(current, { type: "preflight-network-failed" })
-      );
-    } catch {
-      if (controller.signal.aborted) return;
-      setAccessState((current) =>
-        transitionBoothAccess(current, { type: "preflight-network-failed" })
-      );
-    }
-  }, [event, relockAfterUnauthorized, startCamera]);
-
   useEffect(() => {
-    let active = true;
-    setAccessState("locked");
-    setOutboxRecovered(false);
-    setEnabled(null);
-    keyRef.current = "";
     let session!: BoothSession;
     session = new BoothSession(
       event,
       createOutboxStore(),
       uploadOne,
-      ({ url }) => setLastUrl(url),
+      (result) => lifecycle.acceptUploaded(session, result),
       undefined,
       undefined,
       {
-        onAuthRequired: () => {
-          if (sessionRef.current === session) relockAfterUnauthorized();
-        },
+        onAuthRequired: () => lifecycle.authRequired(session),
       }
     );
     sessionRef.current = session;
-    const unsubscribe = session.subscribe(setUploadState);
+    const entering = lifecycle.beginEvent(event, session);
+    const unsubscribe = session.subscribe((next) => {
+      if (lifecycle.isActive(session)) setUploadState(next);
+    });
     const reconsiderConnectivity = () => void session.reconsider("connectivity");
     const reconsiderForeground = () => {
       if (document.visibilityState === "visible") void session.reconsider("foreground");
     };
     window.addEventListener("online", reconsiderConnectivity);
     document.addEventListener("visibilitychange", reconsiderForeground);
-    void (async () => {
-      await session.recover();
-      if (!active) return;
-      setOutboxRecovered(true);
-      const stored = loadBoothCredential(
-        event,
-        window.sessionStorage,
-        window.localStorage
-      );
-      if (!stored) return;
-      keyRef.current = stored.key;
-      await attemptPreflight(stored.key);
-    })();
+    void entering;
     return () => {
-      active = false;
-      cameraRequestRef.current++;
-      preflightRef.current?.abort();
-      captureRef.current?.abort();
-      streamRef.current?.getTracks().forEach((track) => track.stop());
-      streamRef.current = null;
       unsubscribe();
       window.removeEventListener("online", reconsiderConnectivity);
       document.removeEventListener("visibilitychange", reconsiderForeground);
       if (sessionRef.current === session) sessionRef.current = null;
-      void session.stop();
+      void lifecycle.leaveEvent(session);
     };
-  }, [attemptPreflight, event, relockAfterUnauthorized, uploadOne]);
+  }, [event, lifecycle, uploadOne]);
 
   const unlock = useCallback((key: string, remember: boolean) => {
-    keyRef.current = key;
     saveBoothCredential(
       event,
       key,
@@ -293,16 +273,12 @@ export default function Booth() {
       window.sessionStorage,
       window.localStorage
     );
-    void attemptPreflight(key);
-  }, [attemptPreflight, event]);
+    void lifecycle.unlock(key);
+  }, [event, lifecycle]);
 
   const retryPreflight = useCallback(() => {
-    if (!keyRef.current) {
-      relockAfterUnauthorized();
-      return;
-    }
-    void attemptPreflight(keyRef.current);
-  }, [attemptPreflight, relockAfterUnauthorized]);
+    void lifecycle.retryPreflight();
+  }, [lifecycle]);
 
   const retryUpload = useCallback(() => {
     if (accessState !== "ready" || !uploadState.pendingCount) return;
@@ -316,8 +292,8 @@ export default function Booth() {
     setStatus("running");
     const controller = new AbortController();
     captureRef.current = controller;
+    const session = sessionRef.current;
     try {
-      const session = sessionRef.current;
       if (!session) throw new Error("Photo queue is still starting — please try again");
       await session.enqueueCapture(
         async (signal) => {
@@ -342,6 +318,7 @@ export default function Booth() {
           },
         }
       );
+      if (controller.signal.aborted || !lifecycle.isActive(session)) return;
       // Durable handoff is complete. Return to the picker before uploading so
       // the next guest is never trapped on the previous guest's frame.
       setError(null);
@@ -349,6 +326,7 @@ export default function Booth() {
       setStatus("picking");
       void session.process();
     } catch (e) {
+      if (controller.signal.aborted || !session || !lifecycle.isActive(session)) return;
       // composite (frame art fetch, toBlob) failed — surface it and recover
       // instead of leaving the booth stuck in "running" until a reload
       setError(e instanceof Error ? e.message : String(e));
@@ -360,7 +338,7 @@ export default function Booth() {
     } finally {
       if (captureRef.current === controller) captureRef.current = null;
     }
-  }, [accessState, status, mode, grabFrame]);
+  }, [accessState, status, mode, grabFrame, lifecycle]);
 
   // fallback: native file input (camera) when getUserMedia is blocked.
   // Re-encode to a real JPEG first — iPhones hand back HEIC, and the stored
@@ -375,8 +353,10 @@ export default function Booth() {
       const file = e.target.files?.[0];
       e.target.value = "";
       if (!file) return;
+      const controller = new AbortController();
+      captureRef.current = controller;
+      const session = sessionRef.current;
       try {
-        const session = sessionRef.current;
         if (!session) throw new Error("Photo queue is still starting — please try again");
         await session.enqueueCapture(async () => {
           let blob: Blob = file;
@@ -394,17 +374,22 @@ export default function Booth() {
           }
           return blob;
         }, {
+          signal: controller.signal,
           metadata: {
             source: "camera-fallback",
           },
         });
+        if (controller.signal.aborted || !lifecycle.isActive(session)) return;
         setError(null);
         void session.process();
       } catch (uploadError) {
+        if (controller.signal.aborted || !session || !lifecycle.isActive(session)) return;
         setError(uploadError instanceof Error ? uploadError.message : String(uploadError));
+      } finally {
+        if (captureRef.current === controller) captureRef.current = null;
       }
     },
-    [accessState]
+    [accessState, lifecycle]
   );
 
   const pick = (m: keyof typeof TEMPLATES) => {
@@ -529,8 +514,10 @@ export default function Booth() {
       )}
       {accessState !== "ready" && accessState !== "exited" && (
         <BoothUnlock
+          key={event}
           event={event}
           state={accessState}
+          feedback={accessFeedback}
           pendingCount={uploadState.pendingCount}
           durable={uploadState.durable}
           outboxRecovered={outboxRecovered}

From 7cb98823314b91068e7cf397d2018f096dc0c0b5 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:26:55 +0800
Subject: [PATCH 046/105] fix: bind booth recovery to exact session state

---
 .superpowers/sdd/task-4-report.md           | 294 ++++++++++++++++++++
 app/[event]/booth-session/lifecycle.test.ts | 112 ++++++--
 app/[event]/booth-session/lifecycle.ts      |  59 ++--
 app/[event]/booth-session/session.test.ts   |  82 +++++-
 app/[event]/booth-session/session.ts        |  31 ++-
 app/[event]/booth-unlock.test.tsx           |  16 +-
 app/[event]/booth-unlock.tsx                |  15 +-
 app/[event]/page.tsx                        |  24 +-
 8 files changed, 569 insertions(+), 64 deletions(-)
 create mode 100644 .superpowers/sdd/task-4-report.md

diff --git a/.superpowers/sdd/task-4-report.md b/.superpowers/sdd/task-4-report.md
new file mode 100644
index 0000000..e884827
--- /dev/null
+++ b/.superpowers/sdd/task-4-report.md
@@ -0,0 +1,294 @@
+# Release 1 Task 4 report
+
+## Outcome
+
+Implemented Booth credential persistence, the pure Booth access state machine,
+the operator unlock surface, and authenticated online preflight gating in the
+Task 4 worktree.
+
+- The Photo Outbox is constructed and `await`-recovered before stored
+  credentials are read.
+- Startup no longer uses `window.prompt` or public `/api/config`.
+- A stored or newly entered Booth Key is sent only in the
+  `x-booth-key` header of `POST /api/booth/preflight`.
+- Enabled Frames, automatic Session retry, and camera startup are installed
+  only after a successful authenticated preflight.
+- Network/preflight parsing failures enter `recovery-only`; `409` and `503`
+  enter `unavailable`.
+- Preflight or upload `401` clears both Event credential stores, stops/invalidates
+  camera work, stops Session retry, preserves the Outbox, and relocks.
+- Camera capture and the native file fallback are both gated by `ready`.
+- Task 5 pause/heartbeat and Task 7 installed/exit UI were not added.
+
+## Strict TDD record
+
+### RED 1 — new Task 4 modules
+
+Command:
+
+```bash
+bun test 'app/[event]/booth-session/credential.test.ts' \
+  'app/[event]/booth-session/access.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Observed: `0 pass`, `3 fail`, with the expected missing-module errors for
+`credential`, `access`, and `booth-unlock`.
+
+### GREEN 1 — persistence, reducer, and static unlock markup
+
+After the minimal implementations, the focused suite reached `24 pass`,
+`0 fail`. It covers:
+
+- session-first load precedence;
+- remembered and session-default moves;
+- exact per-Event clearing without broad storage deletion;
+- blocked-storage behavior that leaves the caller's active in-memory key intact;
+- locked → checking → ready, recovery-only, unavailable, 401 relock, retry,
+  and exited transitions;
+- labeled password and remember controls;
+- fixed status copy that cannot render the submitted secret.
+
+### RED 2 — page integration and accessibility
+
+The next test additions failed `4` integration/presentation checks against the
+old page and CSS:
+
+- no completed Outbox recovery before credential read;
+- no authenticated successful-preflight start branch;
+- no 44px/forced-colors focus contract;
+- no reduced-motion override.
+
+### GREEN 2 — authenticated preflight gate
+
+After page and CSS integration, the focused suite reached `28 pass`, `0 fail`.
+The ordering regression checks require the source to complete
+`await session.recover()` before `loadBoothCredential()`, and require both
+`session.start()` and `startCamera()` to live in the `response.ok` branch.
+
+### RED/GREEN 3 — late camera result after relock
+
+Lifecycle review found that `getUserMedia()` cannot be aborted. A new regression
+failed until the page used a camera request generation. Relock, Event teardown,
+and unmount now invalidate pending camera work; a late stream has all tracks
+stopped and is never attached after access is lost.
+
+The Session auth callback is also fenced to its owning Session so a stale
+Session cannot relock or stop a newer Event Session.
+
+## Design plan and self-critique
+
+Subject: a real event operator unlocking a dedicated iPad Booth under pressure.
+Single job: reach a trustworthy camera-ready state without risking queued
+photos.
+
+Tokens reuse the existing Booth language:
+
+- Booth black `#07070c`
+- raised ink `#111119`
+- signal pink `#ff2d8b`
+- safe mint `#70e0bb`
+- muted lavender-gray `#b9b8c6`
+- white `#ffffff`
+
+Typography keeps the existing system stack, using a restrained rounded display
+role for the state title and monospace only for operational labels. The
+signature element is the three-part readiness rail: Photo Outbox, Booth access,
+Camera. It encodes actual startup order rather than acting as decoration.
+
+Self-critique:
+
+- Kept the panel to one primary action and plain verbs: “Unlock Booth” and
+  “Try again.”
+- Removed decorative pressure: solid surfaces only, no generic gradient, and
+  no competing illustration.
+- Pending-photo safety is visible before authentication and does not expose raw
+  server errors or secrets.
+- Controls provide at least 44px hit areas; focus stays visible in forced-color
+  mode; the one short panel entrance is removed under reduced motion.
+- The rail stacks on narrow screens and the panel respects safe-area insets.
+- An in-app browser backend was not attached to this Codex session, so no
+  screenshot is claimed as evidence. A real iPad camera/permission pass remains
+  required by repository policy.
+
+## Final verification
+
+After reinstalling the documented iCloud-evicted dependency tree with
+`bun install`:
+
+```text
+focused Task 4 tests: 28 pass, 0 fail, 64 expectations
+bun run typecheck: exit 0
+bun run typecheck:tests: exit 0
+full bun test: 290 pass, 0 fail, 936 expectations across 25 files
+bun run build: exit 0; /[event] production route compiled
+git diff --check: clean
+```
+
+One pre-reinstall final build failed because the local `next` package was
+missing its own internal files. The repository runbook explicitly identifies
+iCloud-evicted `node_modules`; `bun install` restored 370 packages, changed no
+tracked dependency files, and the fresh production build then passed.
+
+## Remaining concerns
+
+- Browser simulation is not evidence for a real iPad camera. Validate the
+  unlocked → permission → picker path, rotation, password-manager behavior, and
+  file fallback on the event iPad over HTTPS/localhost.
+- Task 5 will own pause/heartbeat behavior and Task 7 will own installed mode
+  and operator exit integration; the pure `exited` transition is present now
+  without prematurely adding either feature.
+
+## Review follow-up — async lifecycle ownership
+
+### RED
+
+Added behavioral tests for the review findings before implementation:
+
+```bash
+bun test 'app/[event]/booth-session/lifecycle.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Observed: `0 pass`, `2 fail`, with the expected missing
+`booth-session/lifecycle` module and missing unlock-form reducer export.
+
+The new tests drive deferred Session recovery and stop promises, out-of-order
+preflight responses, StrictMode-style cleanup, Event switches, stale uploaded
+callbacks, 401 relock/re-unlock/automatic acknowledgement, current Frame
+validation, fixed non-secret announcements, and typed-key Event reset.
+
+### GREEN
+
+Minimal coordinator behavior first:
+
+```bash
+bun test 'app/[event]/booth-session/lifecycle.test.ts'
+```
+
+Observed: `14 pass`, `0 fail`, `45` expectations.
+
+After page integration and capture/file fencing:
+
+```bash
+bun test 'app/[event]/booth-session/credential.test.ts' \
+  'app/[event]/booth-session/access.test.ts' \
+  'app/[event]/booth-session/lifecycle.test.ts' \
+  'app/[event]/booth-unlock.test.tsx' \
+  'app/[event]/booth-session/session.test.ts'
+```
+
+Observed: `78 pass`, `0 fail`, `200` expectations.
+
+Source-text checks are no longer the primary lifecycle evidence. The remaining
+small page-source assertion checks only safety wiring: authenticated preflight,
+no prompt/public-config startup, and Event-keyed unlock remounting.
+
+### Review fixes
+
+- `BoothLifecycleCoordinator` owns the active Event, Session, preflight
+  generation, abort controller, auth-blocked flag, and one retained stop
+  promise per Session.
+- Upload `401` clears credentials and relocks immediately, but a successful
+  new preflight awaits the exact owning stop promise before `start()` and an
+  automatic `retry()` of the auth-blocked oldest item.
+- Stale preflight results, deferred old recovery, old Session uploads, state
+  subscriptions, capture tails, and file-decode tails cannot mutate the new
+  Event.
+- A successful response is filtered through the current Frame catalog using
+  `availableTemplates`; malformed, empty, or unknown-only Frames never enter
+  `ready`, start Session work, or start the camera.
+- Event reset now clears status, mode, last URL, errors, countdown, shot,
+  flash, capture/camera work, enabled Frames, access feedback, and current
+  credential. `BoothUnlock` is Event-keyed and its tested form reducer also
+  clears key/remember state on Event identity changes.
+- Checking, network failure, Event unavailable, and rejected-key states have
+  fixed non-secret live-region copy. Rejected credentials use an assertive
+  alert without echoing the key.
+
+### Fresh review verification
+
+```text
+focused review suite: 78 pass, 0 fail, 200 expectations
+bun run typecheck: exit 0
+bun run typecheck:tests: exit 0
+full bun test: 308 pass, 0 fail, 980 expectations across 26 files
+bun run build: exit 0; /[event] production route compiled
+git diff --check: clean
+```
+
+## Second review follow-up — credential and auth retry identity
+
+### RED
+
+The repository shell did not have Bun on `PATH`, so the first literal command
+confirmed the environment issue:
+
+```bash
+bun test 'app/[event]/booth-session/lifecycle.test.ts' \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Observed: exit `127`, `zsh:1: command not found: bun`.
+
+The same focused RED suite was then run with the installed Bun executable:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun test \
+  'app/[event]/booth-session/lifecycle.test.ts' \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Observed: exit `1`, `50 pass`, `14 fail`, `134` expectations. The failures
+showed the missing per-Session credential holder, missing exact-ID auth resume,
+reused stop promise, missing auth callback ID, and unsafe memory-outbox copy.
+
+### GREEN
+
+After the fixes, the focused lifecycle, Session, and unlock suite:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun test \
+  'app/[event]/booth-session/lifecycle.test.ts' \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Observed: exit `0`, `64 pass`, `0 fail`, `200` expectations.
+
+Application and test type checks:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun run typecheck && \
+  /Users/limboenedmund/.bun/bin/bun run typecheck:tests
+```
+
+Observed: exit `0`; both TypeScript checks passed.
+
+Full test and production build:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun test && \
+  /Users/limboenedmund/.bun/bin/bun run build
+```
+
+Observed: exit `0`; `313 pass`, `0 fail`, `1009` expectations across `26`
+test files, followed by a successful Next.js production build including the
+dynamic `/[event]` route.
+
+### Second review fixes
+
+- Every Booth Session upload closure now owns a distinct mutable credential
+  holder. Only the current successful preflight populates it; Event switch,
+  cleanup, and relock blank the old holder before deferred work can continue.
+- Auth-required callbacks expose only the exact persisted outbox item ID.
+  `resumeAuth(id)` may clear failure state only while holding the Event lease
+  and only when that exact ID is still the auth-failed oldest row. Manual
+  `retry()` remains a separate operator override.
+- A completed stop promise is cleared only for its exact epoch after the same
+  active Session restarts, so consecutive 401 recovery cycles each stop before
+  resuming.
+- Memory-only outbox copy says photos are waiting in the open page and that
+  reload recovery is unavailable; it never describes those photos as safe.
diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
index 8e19f30..a93b4d7 100644
--- a/app/[event]/booth-session/lifecycle.test.ts
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -3,6 +3,7 @@ import {
   BoothLifecycleCoordinator,
   usablePreflightFrames,
   type BoothLifecycleSession,
+  type BoothCredentialHolder,
   type BoothPreflightResult,
 } from "./lifecycle";
 
@@ -18,7 +19,7 @@ class FakeSession implements BoothLifecycleSession {
   readonly actions: string[] = [];
   recoverWork: Promise<void> = Promise.resolve();
   stopWork: Promise<void> = Promise.resolve();
-  onRetry: () => void = () => {};
+  onResumeAuth: (itemId: string) => void = () => {};
 
   async recover() {
     this.actions.push("recover");
@@ -31,9 +32,9 @@ class FakeSession implements BoothLifecycleSession {
     return Promise.resolve();
   }
 
-  async retry() {
-    this.actions.push("retry");
-    this.onRetry();
+  async resumeAuth(itemId: string) {
+    this.actions.push(`resume-auth:${itemId}`);
+    this.onResumeAuth(itemId);
   }
 
   async stop() {
@@ -54,7 +55,6 @@ function harness(options: {
   const events: string[] = [];
   const access: string[] = [];
   const frames: Array<string[] | null> = [];
-  const credentials: string[] = [];
   const uploaded: string[] = [];
   const cleared: string[] = [];
   let cameraStarts = 0;
@@ -72,7 +72,6 @@ function harness(options: {
     onOutboxRecovered: () => events.push("outbox-recovered"),
     onAccess: (state, feedback) => access.push(`${state}:${feedback}`),
     onFrames: (next) => frames.push(next),
-    onCredential: (key) => credentials.push(key),
     onCameraStart: () => {
       cameraStarts++;
     },
@@ -86,7 +85,6 @@ function harness(options: {
     events,
     access,
     frames,
-    credentials,
     uploaded,
     cleared,
     cameraStarts: () => cameraStarts,
@@ -95,6 +93,10 @@ function harness(options: {
   };
 }
 
+function credential(): BoothCredentialHolder {
+  return { key: "" };
+}
+
 describe("Booth lifecycle coordination", () => {
   test("completes Outbox recovery before reading a stored credential or preflighting", async () => {
     const recovery = deferred<void>();
@@ -109,7 +111,7 @@ describe("Booth lifecycle coordination", () => {
       },
     });
 
-    const entering = h.coordinator.beginEvent("launch", session);
+    const entering = h.coordinator.beginEvent("launch", session, credential());
     expect(session.actions).toEqual(["recover"]);
     expect(h.loads()).toBe(0);
     expect(calls).toEqual([]);
@@ -129,25 +131,30 @@ describe("Booth lifecycle coordination", () => {
     const session = new FakeSession();
     session.stopWork = stopping.promise;
     const h = harness({ stored: { launch: "first-key" } });
-    session.onRetry = () => h.coordinator.acceptUploaded(session, { url: "/acked" });
-    await h.coordinator.beginEvent("launch", session);
+    const sessionCredential = credential();
+    session.onResumeAuth = () => h.coordinator.acceptUploaded(session, { url: "/acked" });
+    await h.coordinator.beginEvent("launch", session, sessionCredential);
+    expect(sessionCredential.key).toBe("first-key");
 
-    void h.coordinator.authRequired(session);
+    void h.coordinator.authRequired(session, "auth-photo");
+    expect(sessionCredential.key).toBe("");
     expect(h.cleared).toEqual(["launch"]);
     expect(h.access.at(-1)).toBe("locked:rejected-key");
     expect(session.actions).toContain("stop");
 
     const unlocking = h.coordinator.unlock("correct-key");
     await Promise.resolve();
+    expect(sessionCredential.key).toBe("");
     expect(session.actions.filter((action) => action === "start")).toHaveLength(1);
-    expect(session.actions).not.toContain("retry");
+    expect(session.actions).not.toContain("resume-auth:auth-photo");
     expect(h.uploaded).toEqual([]);
 
     stopping.resolve();
     await unlocking;
 
+    expect(sessionCredential.key).toBe("correct-key");
     expect(session.actions.filter((action) => action === "start")).toHaveLength(2);
-    expect(session.actions.at(-1)).toBe("retry");
+    expect(session.actions.at(-1)).toBe("resume-auth:auth-photo");
     expect(h.uploaded).toEqual(["/acked"]);
     expect(h.cameraStarts()).toBe(2);
   });
@@ -160,12 +167,15 @@ describe("Booth lifecycle coordination", () => {
       preflight: async () => (++attempts === 1 ? first.promise : second.promise),
     });
     const session = new FakeSession();
-    await h.coordinator.beginEvent("launch", session);
+    const sessionCredential = credential();
+    await h.coordinator.beginEvent("launch", session, sessionCredential);
 
     const stale = h.coordinator.unlock("old-key");
     const current = h.coordinator.unlock("new-key");
+    expect(sessionCredential.key).toBe("");
     second.resolve({ kind: "ready", frames: ["square"] });
     await current;
+    expect(sessionCredential.key).toBe("new-key");
     first.resolve({ kind: "unauthorized" });
     await stale;
 
@@ -181,7 +191,7 @@ describe("Booth lifecycle coordination", () => {
     oldSession.recoverWork = recovery.promise;
     const h = harness({ stored: { launch: "stored-key" } });
 
-    const entering = h.coordinator.beginEvent("launch", oldSession);
+    const entering = h.coordinator.beginEvent("launch", oldSession, credential());
     await h.coordinator.leaveEvent(oldSession);
     recovery.resolve();
     await entering;
@@ -195,10 +205,12 @@ describe("Booth lifecycle coordination", () => {
     const h = harness();
     const first = new FakeSession();
     const second = new FakeSession();
-    await h.coordinator.beginEvent("first", first);
+    const firstCredential = credential();
+    await h.coordinator.beginEvent("first", first, firstCredential);
     h.coordinator.acceptUploaded(first, { url: "/first-before-switch" });
 
-    await h.coordinator.beginEvent("second", second);
+    const secondCredential = credential();
+    await h.coordinator.beginEvent("second", second, secondCredential);
     h.coordinator.acceptUploaded(first, { url: "/stale" });
     h.coordinator.acceptUploaded(second, { url: "/second" });
 
@@ -207,10 +219,72 @@ describe("Booth lifecycle coordination", () => {
       "second",
     ]);
     expect(h.uploaded).toEqual(["/first-before-switch", "/second"]);
-    expect(h.credentials.at(-1)).toBe("");
+    expect(firstCredential.key).toBe("");
+    expect(secondCredential.key).toBe("");
     expect(h.frames.at(-1)).toBeNull();
     expect(h.cameraStops()).toBeGreaterThanOrEqual(2);
   });
+
+  test("an old deferred upload can never observe the next Event credential", async () => {
+    const uploadGate = deferred<void>();
+    const sent: Array<{ event: string; key: string }> = [];
+    const firstCredential = credential();
+    const secondCredential = credential();
+    const h = harness();
+    const first = new FakeSession();
+    const second = new FakeSession();
+
+    await h.coordinator.beginEvent("first", first, firstCredential);
+    await h.coordinator.unlock("first-key");
+    const oldUpload = (async () => {
+      await uploadGate.promise;
+      sent.push({ event: "first", key: firstCredential.key });
+    })();
+
+    await h.coordinator.beginEvent("second", second, secondCredential);
+    await h.coordinator.unlock("second-key");
+    uploadGate.resolve();
+    await oldUpload;
+
+    expect(firstCredential.key).toBe("");
+    expect(secondCredential.key).toBe("second-key");
+    expect(sent).toEqual([{ event: "first", key: "" }]);
+    expect(sent.some(({ key }) => key === "second-key")).toBe(false);
+  });
+
+  test("uses a fresh stop epoch for each auth failure and serializes each resume", async () => {
+    const firstStop = deferred<void>();
+    const secondStop = deferred<void>();
+    const session = new FakeSession();
+    const h = harness();
+    await h.coordinator.beginEvent("launch", session, credential());
+    await h.coordinator.unlock("initial-key");
+
+    session.stopWork = firstStop.promise;
+    void h.coordinator.authRequired(session, "first-auth");
+    const firstUnlock = h.coordinator.unlock("first-replacement");
+    await Promise.resolve();
+    expect(session.actions.filter((action) => action === "stop")).toHaveLength(1);
+    expect(session.actions).not.toContain("resume-auth:first-auth");
+    firstStop.resolve();
+    await firstUnlock;
+    expect(session.actions.at(-1)).toBe("resume-auth:first-auth");
+
+    session.stopWork = secondStop.promise;
+    void h.coordinator.authRequired(session, "second-auth");
+    const secondUnlock = h.coordinator.unlock("second-replacement");
+    await Promise.resolve();
+    expect(session.actions.filter((action) => action === "stop")).toHaveLength(2);
+    expect(session.actions).not.toContain("resume-auth:second-auth");
+    secondStop.resolve();
+    await secondUnlock;
+
+    expect(session.actions.at(-1)).toBe("resume-auth:second-auth");
+    expect(session.actions.filter((action) => action.startsWith("resume-auth:"))).toEqual([
+      "resume-auth:first-auth",
+      "resume-auth:second-auth",
+    ]);
+  });
 });
 
 describe("preflight Frame validation", () => {
@@ -237,7 +311,7 @@ describe("preflight Frame validation", () => {
     async (reply) => {
       const h = harness({ preflight: async () => reply });
       const session = new FakeSession();
-      await h.coordinator.beginEvent("launch", session);
+      await h.coordinator.beginEvent("launch", session, credential());
       await h.coordinator.unlock("key");
 
       expect(h.access.at(-1)).toBe("unavailable:unavailable");
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
index 3db2675..aa139ef 100644
--- a/app/[event]/booth-session/lifecycle.ts
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -19,16 +19,21 @@ export type BoothPreflightResult =
 export interface BoothLifecycleSession {
   recover(): Promise<void>;
   start(): Promise<void> | void;
-  retry(): Promise<void>;
+  resumeAuth(itemId: string): Promise<void>;
   stop(): Promise<void>;
 }
 
+export type BoothCredentialHolder = {
+  key: string;
+};
+
 type ActiveSession = {
   id: number;
   event: string;
   session: BoothLifecycleSession;
+  credential: BoothCredentialHolder;
   key: string;
-  authBlocked: boolean;
+  authBlockedItemId: string | null;
   stopPromise?: Promise<void>;
 };
 
@@ -44,7 +49,6 @@ type BoothLifecycleDependencies<Result> = {
   onOutboxRecovered: () => void;
   onAccess: (state: BoothAccessState, feedback: BoothAccessFeedback) => void;
   onFrames: (frames: string[] | null) => void;
-  onCredential: (key: string) => void;
   onCameraStart: () => void;
   onCameraStop: () => void;
   onUploaded: (result: Result) => void;
@@ -70,22 +74,30 @@ export class BoothLifecycleCoordinator<Result> {
     return this.active?.session === session;
   }
 
-  async beginEvent(event: string, session: BoothLifecycleSession) {
+  async beginEvent(
+    event: string,
+    session: BoothLifecycleSession,
+    credential: BoothCredentialHolder
+  ) {
     const previous = this.active;
     this.preflightController?.abort();
-    if (previous) void this.ensureStopped(previous);
+    if (previous) {
+      previous.credential.key = "";
+      void this.ensureStopped(previous);
+    }
     this.deps.onCameraStop();
+    credential.key = "";
 
     const active: ActiveSession = {
       id: ++this.nextSessionId,
       event,
       session,
+      credential,
       key: "",
-      authBlocked: false,
+      authBlockedItemId: null,
     };
     this.active = active;
     this.deps.onReset(event);
-    this.deps.onCredential("");
     this.deps.onFrames(null);
     this.deps.onAccess("locked", "recovering");
 
@@ -104,7 +116,6 @@ export class BoothLifecycleCoordinator<Result> {
     const stored = this.deps.loadCredential(event);
     if (!stored) return;
     active.key = stored.key;
-    this.deps.onCredential(stored.key);
     await this.checkCredential(active, stored.key);
   }
 
@@ -113,6 +124,7 @@ export class BoothLifecycleCoordinator<Result> {
     if (!active || active.session !== session) return;
     this.active = null;
     this.preflightController?.abort();
+    active.credential.key = "";
     this.deps.onCameraStop();
     await this.ensureStopped(active);
   }
@@ -121,7 +133,6 @@ export class BoothLifecycleCoordinator<Result> {
     const active = this.active;
     if (!active || !key) return Promise.resolve();
     active.key = key;
-    this.deps.onCredential(key);
     return this.checkCredential(active, key);
   }
 
@@ -131,10 +142,10 @@ export class BoothLifecycleCoordinator<Result> {
     return this.checkCredential(active, active.key);
   }
 
-  authRequired(session: BoothLifecycleSession) {
+  authRequired(session: BoothLifecycleSession, itemId: string) {
     const active = this.active;
     if (!active || active.session !== session) return Promise.resolve();
-    active.authBlocked = true;
+    active.authBlockedItemId = itemId;
     return this.relock(active);
   }
 
@@ -165,7 +176,7 @@ export class BoothLifecycleCoordinator<Result> {
     if (!this.isCurrent(active)) return Promise.resolve();
     this.preflightController?.abort();
     active.key = "";
-    this.deps.onCredential("");
+    active.credential.key = "";
     this.deps.clearCredential(active.event);
     this.deps.onFrames(null);
     this.deps.onCameraStop();
@@ -211,18 +222,32 @@ export class BoothLifecycleCoordinator<Result> {
       return;
     }
 
-    if (active.stopPromise) await active.stopPromise;
+    const stopPromise = active.stopPromise;
+    if (stopPromise) {
+      await stopPromise;
+    }
     if (!this.isCurrent(active, preflightId)) return;
 
+    active.credential.key = key;
     this.deps.onFrames(frames);
     this.deps.onAccess("ready", "ready");
-    void Promise.resolve(active.session.start()).catch(() => {
+    let startWork: Promise<void> | void;
+    try {
+      startWork = active.session.start();
+    } catch {
+      return;
+    }
+    if (stopPromise && active.stopPromise === stopPromise) {
+      active.stopPromise = undefined;
+    }
+    void Promise.resolve(startWork).catch(() => {
       // Session state reports upload failures without invalidating preflight.
     });
     this.deps.onCameraStart();
-    if (active.authBlocked) {
-      active.authBlocked = false;
-      await active.session.retry();
+    const authBlockedItemId = active.authBlockedItemId;
+    if (authBlockedItemId) {
+      active.authBlockedItemId = null;
+      await active.session.resumeAuth(authBlockedItemId);
     }
   }
 }
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index 7f7c145..4c5f6f5 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -596,6 +596,7 @@ describe("BoothSession outbox", () => {
   test("persists auth failure before notifying the credential owner", async () => {
     const store = new MemoryOutboxStore();
     let persistedBeforeCallback = false;
+    const notifiedItemIds: string[] = [];
     const session = new BoothSession(
       "party",
       store,
@@ -606,10 +607,11 @@ describe("BoothSession outbox", () => {
       () => "018f0000-0000-4000-8000-000000000001",
       () => 1_000,
       {
-        onAuthRequired: async () => {
+        onAuthRequired: async (itemId) => {
           const [item] = await store.list("party");
           persistedBeforeCallback =
             item.failureKind === "auth" && item.errorClass === "auth";
+          notifiedItemIds.push(itemId);
         },
       }
     );
@@ -620,6 +622,7 @@ describe("BoothSession outbox", () => {
     await session.process();
 
     expect(persistedBeforeCallback).toBe(true);
+    expect(notifiedItemIds).toEqual(["018f0000-0000-4000-8000-000000000001"]);
     expect(await store.list("party")).toMatchObject([{
       attempts: 1,
       failureKind: "auth",
@@ -627,6 +630,83 @@ describe("BoothSession outbox", () => {
     }]);
   });
 
+  test("resumes only the exact auth-blocked oldest item and preserves FIFO under concurrent calls", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "auth-oldest",
+      event: "party",
+      blob: photo("auth"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "expired key",
+      failureKind: "auth",
+      errorClass: "auth",
+    });
+    await store.put({
+      id: "ready-next",
+      event: "party",
+      blob: photo("next"),
+      createdAt: 2,
+      attempts: 0,
+    });
+    const uploads: string[] = [];
+    const session = new BoothSession("party", store, async (item) => {
+      uploads.push(item.id);
+      return { url: `/${item.id}` };
+    });
+
+    await session.start();
+    await Promise.all([
+      session.resumeAuth("auth-oldest"),
+      session.resumeAuth("auth-oldest"),
+    ]);
+
+    expect(uploads).toEqual(["auth-oldest", "ready-next"]);
+    expect(await store.list("party")).toEqual([]);
+    await session.stop();
+  });
+
+  test("does not override a permanent oldest item when the expected auth row was removed", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "auth-row",
+      event: "party",
+      blob: photo("auth"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "expired key",
+      failureKind: "auth",
+      errorClass: "auth",
+    });
+    let uploads = 0;
+    const session = new BoothSession("party", store, async () => {
+      uploads++;
+      return { url: "/unexpected" };
+    });
+
+    await session.start();
+    await store.remove("auth-row");
+    await store.put({
+      id: "permanent-next",
+      event: "party",
+      blob: photo("permanent"),
+      createdAt: 2,
+      attempts: 1,
+      lastError: "invalid photo",
+      failureKind: "permanent",
+      errorClass: "payload",
+    });
+    await session.resumeAuth("auth-row");
+
+    expect(uploads).toBe(0);
+    expect(await store.list("party")).toMatchObject([{
+      id: "permanent-next",
+      failureKind: "permanent",
+      lastError: "invalid photo",
+    }]);
+    await session.stop();
+  });
+
   test("one Event lease prevents two Sessions from draining simultaneously", async () => {
     const store = new MemoryOutboxStore();
     await store.put({
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index 2fcbb5b..d65d991 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -22,7 +22,7 @@ export type BoothSessionOptions = {
   ownerId?: string;
   leaseTtlMs?: number;
   random?: () => number;
-  onAuthRequired?: () => void | Promise<void>;
+  onAuthRequired?: (itemId: string) => void | Promise<void>;
   setTimer?: (callback: () => void, delayMs: number) => unknown;
   clearTimer?: (timer: unknown) => void;
 };
@@ -40,11 +40,13 @@ export class BoothSession {
   private retryAt: number | null = null;
   private manualRetryRequested = false;
   private environmentalRetryRequested = false;
+  private authRetryItemId: string | null = null;
+  private authRetryInFlightId: string | null = null;
   private timer: unknown = null;
   private readonly ownerId: string;
   private readonly leaseTtlMs: number;
   private readonly random: () => number;
-  private readonly onAuthRequired: () => void | Promise<void>;
+  private readonly onAuthRequired: (itemId: string) => void | Promise<void>;
   private readonly setTimer: (callback: () => void, delayMs: number) => unknown;
   private readonly clearTimer: (timer: unknown) => void;
 
@@ -187,13 +189,28 @@ export class BoothSession {
     await this.process();
   }
 
+  async resumeAuth(itemId: string) {
+    if (this.stopRequested) return;
+    if (this.authRetryInFlightId !== itemId) this.authRetryItemId = itemId;
+    if (!this.processing) {
+      this.retryAt = null;
+      this.cancelTimer();
+    }
+    await this.process();
+  }
+
   private async drain() {
     if (!await this.ensureLease()) return;
     let pending = await this.store.list(this.event);
     while (pending.length > 0) {
       let item = pending[0];
+      const expectedAuthItemId = this.authRetryItemId;
+      this.authRetryItemId = null;
+      const forceAuthRetry =
+        expectedAuthItemId === item.id && item.failureKind === "auth";
       const forceRetry =
         this.manualRetryRequested ||
+        forceAuthRetry ||
         (this.environmentalRetryRequested && item.failureKind === "retryable");
       this.manualRetryRequested = false;
       this.environmentalRetryRequested = false;
@@ -209,6 +226,7 @@ export class BoothSession {
         item = ready;
         pending = [item, ...pending.slice(1)];
       }
+      if (forceAuthRetry) this.authRetryInFlightId = item.id;
       if (item.failureKind === "retryable" && (item.nextAttemptAt ?? 0) > this.now()) {
         this.retryAt = item.nextAttemptAt ?? null;
         this.publish({
@@ -246,12 +264,14 @@ export class BoothSession {
         result = await this.upload(item);
       } catch (error) {
         await this.recordUploadFailure(item, error, pending.length);
+        if (this.authRetryInFlightId === item.id) this.authRetryInFlightId = null;
         return;
       }
 
       try {
         await this.store.remove(item.id);
       } catch (error) {
+        if (this.authRetryInFlightId === item.id) this.authRetryInFlightId = null;
         // The Event store already acknowledged the upload. Do not classify or
         // recreate this row if local outbox cleanup fails; a later manual retry
         // uses the stable identity and receives the idempotent acknowledgement.
@@ -264,6 +284,7 @@ export class BoothSession {
         });
         return;
       }
+      if (this.authRetryInFlightId === item.id) this.authRetryInFlightId = null;
 
       // Everything below runs after the upload was acknowledged and the exact
       // item was removed. Post-ack failures may pause reconciliation, but can
@@ -347,13 +368,13 @@ export class BoothSession {
       error: message,
       durable: this.store.isDurable(),
     });
-    if (disposition.kind === "auth-required") this.notifyAuthRequired();
+    if (disposition.kind === "auth-required") this.notifyAuthRequired(failed.id);
     this.scheduleWake();
   }
 
-  private notifyAuthRequired() {
+  private notifyAuthRequired(itemId: string) {
     try {
-      void Promise.resolve(this.onAuthRequired()).catch(() => {
+      void Promise.resolve(this.onAuthRequired(itemId)).catch(() => {
         // Credential UI cannot affect the already-persisted queue state.
       });
     } catch {
diff --git a/app/[event]/booth-unlock.test.tsx b/app/[event]/booth-unlock.test.tsx
index 73b2d54..1d06b7a 100644
--- a/app/[event]/booth-unlock.test.tsx
+++ b/app/[event]/booth-unlock.test.tsx
@@ -12,14 +12,15 @@ const secret = "never-render-this-booth-key";
 function render(
   state: "locked" | "checking" | "recovery-only" | "unavailable",
   pendingCount = 0,
-  feedback?: BoothAccessFeedback
+  feedback?: BoothAccessFeedback,
+  durable = true
 ) {
   return renderToStaticMarkup(
     <BoothUnlock
       event="launch"
       state={state}
       pendingCount={pendingCount}
-      durable
+      durable={durable}
       feedback={feedback}
       onUnlock={(key) => {
         if (key === secret) throw new Error("not called during static render");
@@ -96,6 +97,14 @@ describe("Booth unlock", () => {
     }
   );
 
+  test("never describes memory-only pending photos as safe", () => {
+    const html = render("recovery-only", 2, "network", false);
+
+    expect(html).toContain("2 photos waiting in this open page");
+    expect(html).toContain("reload recovery is unavailable");
+    expect(html.toLowerCase()).not.toContain("safe");
+  });
+
   test("changing Event identity clears typed key and remember state", () => {
     let form = createUnlockFormState("first");
     form = unlockFormReducer(form, { type: "key-changed", key: secret });
@@ -114,6 +123,9 @@ describe("Booth page safety wiring", () => {
     expect(source).not.toContain("window.prompt");
     expect(source).not.toContain("/api/config?event=");
     expect(source).toContain("key={event}");
+    expect(source).toContain('const credential: BoothCredentialHolder = { key: "" }');
+    expect(source).toContain('"x-booth-key": credential.key');
+    expect(source).not.toContain("keyRef");
   });
 });
 
diff --git a/app/[event]/booth-unlock.tsx b/app/[event]/booth-unlock.tsx
index 90e4668..f1c453d 100644
--- a/app/[event]/booth-unlock.tsx
+++ b/app/[event]/booth-unlock.tsx
@@ -51,9 +51,12 @@ export function unlockFormReducer(
   return { ...state, key: "" };
 }
 
-function pendingLabel(pendingCount: number) {
+function pendingLabel(pendingCount: number, durable: boolean) {
   if (pendingCount === 0) return "No photos waiting";
-  return `${pendingCount} photo${pendingCount === 1 ? "" : "s"} waiting safely`;
+  const photos = `${pendingCount} photo${pendingCount === 1 ? "" : "s"}`;
+  return durable
+    ? `${photos} waiting safely`
+    : `${photos} waiting in this open page`;
 }
 
 export function BoothUnlock({
@@ -95,7 +98,9 @@ export function BoothUnlock({
     : feedback === "checking"
       ? "Checking Booth access online."
       : feedback === "network"
-        ? "Could not reach Booth service. Pending photos are still safe."
+        ? durable
+          ? "Could not reach Booth service. Pending photos are still safe."
+          : "Could not reach Booth service. Keep this page open; reload recovery is unavailable."
         : feedback === "unavailable"
           ? "This Event is not ready for Booth capture."
           : feedback === "recovering"
@@ -134,7 +139,7 @@ export function BoothUnlock({
         <div className={styles.readinessRail} aria-label="Booth readiness">
           <div data-ready={outboxRecovered}>
             <span>Photo Outbox</span>
-            <strong>{outboxRecovered ? pendingLabel(pendingCount) : "Recovering"}</strong>
+            <strong>{outboxRecovered ? pendingLabel(pendingCount, durable) : "Recovering"}</strong>
           </div>
           <div data-ready={false}>
             <span>Booth access</span>
@@ -159,7 +164,7 @@ export function BoothUnlock({
           role={feedback === "rejected-key" ? "alert" : "status"}
           aria-live={feedback === "rejected-key" ? "assertive" : "polite"}
         >
-          <strong>{pendingLabel(pendingCount)}</strong>
+          <strong>{pendingLabel(pendingCount, durable)}</strong>
           <span>{accessMessage}</span>
           <span>
             {durable
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index a8d28f1..3ccb22d 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -22,6 +22,7 @@ import {
 import {
   BoothLifecycleCoordinator,
   type BoothAccessFeedback,
+  type BoothCredentialHolder,
   type BoothPreflightResult,
 } from "./booth-session/lifecycle";
 import { BoothUnlock } from "./booth-unlock";
@@ -73,7 +74,6 @@ export default function Booth() {
   const captureRef = useRef<AbortController | null>(null);
   const cameraRequestRef = useRef(0);
   const unmountedRef = useRef(false);
-  const keyRef = useRef("");
   const [status, setStatus] = useState<Status>("starting");
   const [accessState, setAccessState] = useState<BoothAccessState>("locked");
   const [accessFeedback, setAccessFeedback] =
@@ -175,9 +175,6 @@ export default function Booth() {
         setAccessFeedback(feedback);
       },
       onFrames: setEnabled,
-      onCredential: (key) => {
-        keyRef.current = key;
-      },
       onCameraStart: () => {
         void startCamera();
       },
@@ -208,12 +205,13 @@ export default function Booth() {
     return c;
   }, []);
 
-  const uploadOne = useCallback(
-    async (item: OutboxItem) => {
+  useEffect(() => {
+    const credential: BoothCredentialHolder = { key: "" };
+    const uploadOne = async (item: OutboxItem) => {
       const res = await fetch(`/api/upload?event=${encodeURIComponent(event)}`, {
         method: "POST",
         headers: {
-          "x-booth-key": keyRef.current,
+          "x-booth-key": credential.key,
           "content-type": "image/jpeg",
           ...outboxUploadHeaders(item),
         },
@@ -227,11 +225,7 @@ export default function Booth() {
         );
       }
       return res.json() as Promise<{ url: string; key?: string; duplicate?: boolean }>;
-    },
-    [event]
-  );
-
-  useEffect(() => {
+    };
     let session!: BoothSession;
     session = new BoothSession(
       event,
@@ -241,11 +235,11 @@ export default function Booth() {
       undefined,
       undefined,
       {
-        onAuthRequired: () => lifecycle.authRequired(session),
+        onAuthRequired: (itemId) => lifecycle.authRequired(session, itemId),
       }
     );
     sessionRef.current = session;
-    const entering = lifecycle.beginEvent(event, session);
+    const entering = lifecycle.beginEvent(event, session, credential);
     const unsubscribe = session.subscribe((next) => {
       if (lifecycle.isActive(session)) setUploadState(next);
     });
@@ -263,7 +257,7 @@ export default function Booth() {
       if (sessionRef.current === session) sessionRef.current = null;
       void lifecycle.leaveEvent(session);
     };
-  }, [event, lifecycle, uploadOne]);
+  }, [event, lifecycle]);
 
   const unlock = useCallback((key: string, remember: boolean) => {
     saveBoothCredential(

From f995a5a06d946b4faa6ef5ec255a3bae9c4c6e1a Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:32:18 +0800
Subject: [PATCH 047/105] fix: resume recovered booth auth item

---
 .superpowers/sdd/task-4-report.md           |  62 +++++++++++
 app/[event]/booth-session/lifecycle.test.ts | 117 ++++++++++++++++++++
 app/[event]/booth-session/lifecycle.ts      |  12 +-
 app/[event]/booth-session/session.test.ts   |  59 ++++++++++
 app/[event]/booth-session/session.ts        |   4 +
 5 files changed, 252 insertions(+), 2 deletions(-)

diff --git a/.superpowers/sdd/task-4-report.md b/.superpowers/sdd/task-4-report.md
index e884827..a41c767 100644
--- a/.superpowers/sdd/task-4-report.md
+++ b/.superpowers/sdd/task-4-report.md
@@ -292,3 +292,65 @@ dynamic `/[event]` route.
   resuming.
 - Memory-only outbox copy says photos are waiting in the open page and that
   reload recovery is unavailable; it never describes those photos as safe.
+
+## Final review follow-up — reload auth recovery
+
+### RED
+
+Added Session recovery-contract tests, real fresh-page coordinator/Session
+tests, and synchronous candidate-key zeroing tests before implementation:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun test \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-session/lifecycle.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Observed: exit `1`, `65 pass`, `5 fail`, `209` expectations. The expected
+failures showed that `recover()` returned no auth identity, a fresh coordinator
+did not resume the persisted auth row, and candidate keys survived replacement
+and leave until after the security boundary.
+
+### GREEN
+
+The same focused suite after the minimal recovery contract and zeroing changes:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun test \
+  'app/[event]/booth-session/session.test.ts' \
+  'app/[event]/booth-session/lifecycle.test.ts' \
+  'app/[event]/booth-unlock.test.tsx'
+```
+
+Observed: exit `0`, `70 pass`, `0 fail`, `212` expectations.
+
+Both TypeScript checks:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun run typecheck && \
+  /Users/limboenedmund/.bun/bin/bun run typecheck:tests
+```
+
+Observed: exit `0`; both checks passed.
+
+Full test suite:
+
+```bash
+/Users/limboenedmund/.bun/bin/bun test
+```
+
+Observed: exit `0`, `319 pass`, `0 fail`, `1021` expectations across `26`
+test files.
+
+### Final review fixes
+
+- `BoothSession.recover()` reports the exact oldest persisted auth-failed item
+  ID without changing or removing any outbox row.
+- Fresh coordinator recovery retains that ID through credential preflight and
+  invokes the existing lease-gated `resumeAuth(id)` path only after successful
+  authentication. The auth row and following rows drain in FIFO order.
+- A recovered permanent oldest row exposes no auth-resume identity and remains
+  paused.
+- Event replacement and leave synchronously blank both the upload credential
+  holder and the coordinator's candidate key before any deferred stop work.
diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
index a93b4d7..d041e2e 100644
--- a/app/[event]/booth-session/lifecycle.test.ts
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -6,6 +6,8 @@ import {
   type BoothCredentialHolder,
   type BoothPreflightResult,
 } from "./lifecycle";
+import { MemoryOutboxStore } from "./outbox";
+import { BoothSession } from "./session";
 
 function deferred<T>() {
   let resolve!: (value: T | PromiseLike<T>) => void;
@@ -19,12 +21,14 @@ class FakeSession implements BoothLifecycleSession {
   readonly actions: string[] = [];
   recoverWork: Promise<void> = Promise.resolve();
   stopWork: Promise<void> = Promise.resolve();
+  recoverResult = { authBlockedItemId: null as string | null };
   onResumeAuth: (itemId: string) => void = () => {};
 
   async recover() {
     this.actions.push("recover");
     await this.recoverWork;
     this.actions.push("recovered");
+    return this.recoverResult;
   }
 
   start() {
@@ -97,6 +101,16 @@ function credential(): BoothCredentialHolder {
   return { key: "" };
 }
 
+function activeCandidate(
+  coordinator: BoothLifecycleCoordinator<{ url: string }>
+) {
+  return (coordinator as unknown as {
+    active: { key: string } | null;
+  }).active;
+}
+
+const photo = (name: string) => new Blob([name], { type: "image/jpeg" });
+
 describe("Booth lifecycle coordination", () => {
   test("completes Outbox recovery before reading a stored credential or preflighting", async () => {
     const recovery = deferred<void>();
@@ -285,6 +299,109 @@ describe("Booth lifecycle coordination", () => {
       "resume-auth:second-auth",
     ]);
   });
+
+  test("fresh-page recovery resumes a persisted auth oldest item and drains FIFO", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "persisted-auth",
+      event: "launch",
+      blob: photo("auth"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "expired key",
+      failureKind: "auth",
+      errorClass: "auth",
+    });
+    await store.put({
+      id: "ready-next",
+      event: "launch",
+      blob: photo("next"),
+      createdAt: 2,
+      attempts: 0,
+    });
+    const uploads: string[] = [];
+    const session = new BoothSession("launch", store, async (item) => {
+      uploads.push(item.id);
+      return { url: `/${item.id}` };
+    });
+    const h = harness({ stored: { launch: "restored-key" } });
+
+    await h.coordinator.beginEvent("launch", session, credential());
+
+    expect(uploads).toEqual(["persisted-auth", "ready-next"]);
+    expect(await store.list("launch")).toEqual([]);
+    await session.stop();
+  });
+
+  test("fresh-page recovery leaves a persisted permanent oldest item paused", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "persisted-permanent",
+      event: "launch",
+      blob: photo("permanent"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "invalid photo",
+      failureKind: "permanent",
+      errorClass: "payload",
+    });
+    await store.put({
+      id: "ready-next",
+      event: "launch",
+      blob: photo("next"),
+      createdAt: 2,
+      attempts: 0,
+    });
+    const uploads: string[] = [];
+    const session = new BoothSession("launch", store, async (item) => {
+      uploads.push(item.id);
+      return { url: `/${item.id}` };
+    });
+    const h = harness({ stored: { launch: "restored-key" } });
+
+    await h.coordinator.beginEvent("launch", session, credential());
+    await session.process();
+
+    expect(uploads).toEqual([]);
+    expect(await store.list("launch")).toMatchObject([
+      { id: "persisted-permanent", failureKind: "permanent" },
+      { id: "ready-next" },
+    ]);
+    await session.stop();
+  });
+
+  test("zeros the previous candidate key immediately when replacing an Event", async () => {
+    const nextRecovery = deferred<void>();
+    const first = new FakeSession();
+    const second = new FakeSession();
+    second.recoverWork = nextRecovery.promise;
+    const h = harness({ stored: { first: "first-key" } });
+    await h.coordinator.beginEvent("first", first, credential());
+    const previous = activeCandidate(h.coordinator);
+    expect(previous?.key).toBe("first-key");
+
+    const switching = h.coordinator.beginEvent("second", second, credential());
+
+    expect(previous?.key).toBe("");
+    nextRecovery.resolve();
+    await switching;
+  });
+
+  test("zeros the active candidate key immediately when leaving an Event", async () => {
+    const stopping = deferred<void>();
+    const session = new FakeSession();
+    session.stopWork = stopping.promise;
+    const h = harness({ stored: { launch: "stored-key" } });
+    await h.coordinator.beginEvent("launch", session, credential());
+    const leavingActive = activeCandidate(h.coordinator);
+    expect(leavingActive?.key).toBe("stored-key");
+
+    const leaving = h.coordinator.leaveEvent(session);
+
+    expect(leavingActive?.key).toBe("");
+    stopping.resolve();
+    await leaving;
+  });
 });
 
 describe("preflight Frame validation", () => {
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
index aa139ef..1403c13 100644
--- a/app/[event]/booth-session/lifecycle.ts
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -16,8 +16,12 @@ export type BoothPreflightResult =
   | { kind: "unavailable" }
   | { kind: "recovery-only" };
 
+export type BoothSessionRecovery = {
+  authBlockedItemId: string | null;
+};
+
 export interface BoothLifecycleSession {
-  recover(): Promise<void>;
+  recover(): Promise<BoothSessionRecovery>;
   start(): Promise<void> | void;
   resumeAuth(itemId: string): Promise<void>;
   stop(): Promise<void>;
@@ -82,6 +86,7 @@ export class BoothLifecycleCoordinator<Result> {
     const previous = this.active;
     this.preflightController?.abort();
     if (previous) {
+      previous.key = "";
       previous.credential.key = "";
       void this.ensureStopped(previous);
     }
@@ -101,8 +106,9 @@ export class BoothLifecycleCoordinator<Result> {
     this.deps.onFrames(null);
     this.deps.onAccess("locked", "recovering");
 
+    let recovery: BoothSessionRecovery;
     try {
-      await session.recover();
+      recovery = await session.recover();
     } catch {
       if (!this.isCurrent(active)) return;
       this.deps.onOutboxRecovered();
@@ -110,6 +116,7 @@ export class BoothLifecycleCoordinator<Result> {
       return;
     }
     if (!this.isCurrent(active)) return;
+    active.authBlockedItemId = recovery.authBlockedItemId;
 
     this.deps.onOutboxRecovered();
     this.deps.onAccess("locked", "locked");
@@ -124,6 +131,7 @@ export class BoothLifecycleCoordinator<Result> {
     if (!active || active.session !== session) return;
     this.active = null;
     this.preflightController?.abort();
+    active.key = "";
     active.credential.key = "";
     this.deps.onCameraStop();
     await this.ensureStopped(active);
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index 4c5f6f5..4fc9dca 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -593,6 +593,65 @@ describe("BoothSession outbox", () => {
     }
   });
 
+  test("recover exposes the exact oldest persisted auth item without changing the row", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "persisted-auth",
+      event: "party",
+      blob: photo("auth"),
+      createdAt: 1,
+      attempts: 3,
+      lastError: "expired key",
+      failureKind: "auth",
+      errorClass: "auth",
+    });
+    await store.put({
+      id: "ready-next",
+      event: "party",
+      blob: photo("next"),
+      createdAt: 2,
+      attempts: 0,
+    });
+    const before = await store.list("party");
+    const session = new BoothSession("party", store, async () => ({ url: "/unused" }));
+
+    const recovery = await session.recover();
+
+    expect(recovery).toEqual({ authBlockedItemId: "persisted-auth" });
+    expect(await store.list("party")).toEqual(before);
+  });
+
+  test("recover does not expose a later auth row when the persisted oldest is permanent", async () => {
+    const store = new MemoryOutboxStore();
+    await store.put({
+      id: "permanent-oldest",
+      event: "party",
+      blob: photo("permanent"),
+      createdAt: 1,
+      attempts: 1,
+      lastError: "invalid photo",
+      failureKind: "permanent",
+      errorClass: "payload",
+    });
+    await store.put({
+      id: "auth-next",
+      event: "party",
+      blob: photo("auth"),
+      createdAt: 2,
+      attempts: 1,
+      lastError: "expired key",
+      failureKind: "auth",
+      errorClass: "auth",
+    });
+    const before = await store.list("party");
+    const session = new BoothSession("party", store, async () => ({ url: "/unused" }));
+
+    const recovery = await session.recover();
+
+    expect(recovery).toEqual({ authBlockedItemId: null });
+    expect(await store.list("party")).toEqual(before);
+  });
+
   test("persists auth failure before notifying the credential owner", async () => {
     const store = new MemoryOutboxStore();
     let persistedBeforeCallback = false;
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index d65d991..9787592 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -93,6 +93,10 @@ export class BoothSession {
       error: pending.find((item) => item.lastError)?.lastError ?? null,
       durable: this.store.isDurable(),
     });
+    return {
+      authBlockedItemId:
+        pending[0]?.failureKind === "auth" ? pending[0].id : null,
+    };
   }
 
   start() {

From 4e39ecbab378887848b65b4d7743c5d7640dd067 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:34:30 +0800
Subject: [PATCH 048/105] chore: remove task report artifact

---
 .superpowers/sdd/task-4-report.md | 356 ------------------------------
 1 file changed, 356 deletions(-)
 delete mode 100644 .superpowers/sdd/task-4-report.md

diff --git a/.superpowers/sdd/task-4-report.md b/.superpowers/sdd/task-4-report.md
deleted file mode 100644
index a41c767..0000000
--- a/.superpowers/sdd/task-4-report.md
+++ /dev/null
@@ -1,356 +0,0 @@
-# Release 1 Task 4 report
-
-## Outcome
-
-Implemented Booth credential persistence, the pure Booth access state machine,
-the operator unlock surface, and authenticated online preflight gating in the
-Task 4 worktree.
-
-- The Photo Outbox is constructed and `await`-recovered before stored
-  credentials are read.
-- Startup no longer uses `window.prompt` or public `/api/config`.
-- A stored or newly entered Booth Key is sent only in the
-  `x-booth-key` header of `POST /api/booth/preflight`.
-- Enabled Frames, automatic Session retry, and camera startup are installed
-  only after a successful authenticated preflight.
-- Network/preflight parsing failures enter `recovery-only`; `409` and `503`
-  enter `unavailable`.
-- Preflight or upload `401` clears both Event credential stores, stops/invalidates
-  camera work, stops Session retry, preserves the Outbox, and relocks.
-- Camera capture and the native file fallback are both gated by `ready`.
-- Task 5 pause/heartbeat and Task 7 installed/exit UI were not added.
-
-## Strict TDD record
-
-### RED 1 — new Task 4 modules
-
-Command:
-
-```bash
-bun test 'app/[event]/booth-session/credential.test.ts' \
-  'app/[event]/booth-session/access.test.ts' \
-  'app/[event]/booth-unlock.test.tsx'
-```
-
-Observed: `0 pass`, `3 fail`, with the expected missing-module errors for
-`credential`, `access`, and `booth-unlock`.
-
-### GREEN 1 — persistence, reducer, and static unlock markup
-
-After the minimal implementations, the focused suite reached `24 pass`,
-`0 fail`. It covers:
-
-- session-first load precedence;
-- remembered and session-default moves;
-- exact per-Event clearing without broad storage deletion;
-- blocked-storage behavior that leaves the caller's active in-memory key intact;
-- locked → checking → ready, recovery-only, unavailable, 401 relock, retry,
-  and exited transitions;
-- labeled password and remember controls;
-- fixed status copy that cannot render the submitted secret.
-
-### RED 2 — page integration and accessibility
-
-The next test additions failed `4` integration/presentation checks against the
-old page and CSS:
-
-- no completed Outbox recovery before credential read;
-- no authenticated successful-preflight start branch;
-- no 44px/forced-colors focus contract;
-- no reduced-motion override.
-
-### GREEN 2 — authenticated preflight gate
-
-After page and CSS integration, the focused suite reached `28 pass`, `0 fail`.
-The ordering regression checks require the source to complete
-`await session.recover()` before `loadBoothCredential()`, and require both
-`session.start()` and `startCamera()` to live in the `response.ok` branch.
-
-### RED/GREEN 3 — late camera result after relock
-
-Lifecycle review found that `getUserMedia()` cannot be aborted. A new regression
-failed until the page used a camera request generation. Relock, Event teardown,
-and unmount now invalidate pending camera work; a late stream has all tracks
-stopped and is never attached after access is lost.
-
-The Session auth callback is also fenced to its owning Session so a stale
-Session cannot relock or stop a newer Event Session.
-
-## Design plan and self-critique
-
-Subject: a real event operator unlocking a dedicated iPad Booth under pressure.
-Single job: reach a trustworthy camera-ready state without risking queued
-photos.
-
-Tokens reuse the existing Booth language:
-
-- Booth black `#07070c`
-- raised ink `#111119`
-- signal pink `#ff2d8b`
-- safe mint `#70e0bb`
-- muted lavender-gray `#b9b8c6`
-- white `#ffffff`
-
-Typography keeps the existing system stack, using a restrained rounded display
-role for the state title and monospace only for operational labels. The
-signature element is the three-part readiness rail: Photo Outbox, Booth access,
-Camera. It encodes actual startup order rather than acting as decoration.
-
-Self-critique:
-
-- Kept the panel to one primary action and plain verbs: “Unlock Booth” and
-  “Try again.”
-- Removed decorative pressure: solid surfaces only, no generic gradient, and
-  no competing illustration.
-- Pending-photo safety is visible before authentication and does not expose raw
-  server errors or secrets.
-- Controls provide at least 44px hit areas; focus stays visible in forced-color
-  mode; the one short panel entrance is removed under reduced motion.
-- The rail stacks on narrow screens and the panel respects safe-area insets.
-- An in-app browser backend was not attached to this Codex session, so no
-  screenshot is claimed as evidence. A real iPad camera/permission pass remains
-  required by repository policy.
-
-## Final verification
-
-After reinstalling the documented iCloud-evicted dependency tree with
-`bun install`:
-
-```text
-focused Task 4 tests: 28 pass, 0 fail, 64 expectations
-bun run typecheck: exit 0
-bun run typecheck:tests: exit 0
-full bun test: 290 pass, 0 fail, 936 expectations across 25 files
-bun run build: exit 0; /[event] production route compiled
-git diff --check: clean
-```
-
-One pre-reinstall final build failed because the local `next` package was
-missing its own internal files. The repository runbook explicitly identifies
-iCloud-evicted `node_modules`; `bun install` restored 370 packages, changed no
-tracked dependency files, and the fresh production build then passed.
-
-## Remaining concerns
-
-- Browser simulation is not evidence for a real iPad camera. Validate the
-  unlocked → permission → picker path, rotation, password-manager behavior, and
-  file fallback on the event iPad over HTTPS/localhost.
-- Task 5 will own pause/heartbeat behavior and Task 7 will own installed mode
-  and operator exit integration; the pure `exited` transition is present now
-  without prematurely adding either feature.
-
-## Review follow-up — async lifecycle ownership
-
-### RED
-
-Added behavioral tests for the review findings before implementation:
-
-```bash
-bun test 'app/[event]/booth-session/lifecycle.test.ts' \
-  'app/[event]/booth-unlock.test.tsx'
-```
-
-Observed: `0 pass`, `2 fail`, with the expected missing
-`booth-session/lifecycle` module and missing unlock-form reducer export.
-
-The new tests drive deferred Session recovery and stop promises, out-of-order
-preflight responses, StrictMode-style cleanup, Event switches, stale uploaded
-callbacks, 401 relock/re-unlock/automatic acknowledgement, current Frame
-validation, fixed non-secret announcements, and typed-key Event reset.
-
-### GREEN
-
-Minimal coordinator behavior first:
-
-```bash
-bun test 'app/[event]/booth-session/lifecycle.test.ts'
-```
-
-Observed: `14 pass`, `0 fail`, `45` expectations.
-
-After page integration and capture/file fencing:
-
-```bash
-bun test 'app/[event]/booth-session/credential.test.ts' \
-  'app/[event]/booth-session/access.test.ts' \
-  'app/[event]/booth-session/lifecycle.test.ts' \
-  'app/[event]/booth-unlock.test.tsx' \
-  'app/[event]/booth-session/session.test.ts'
-```
-
-Observed: `78 pass`, `0 fail`, `200` expectations.
-
-Source-text checks are no longer the primary lifecycle evidence. The remaining
-small page-source assertion checks only safety wiring: authenticated preflight,
-no prompt/public-config startup, and Event-keyed unlock remounting.
-
-### Review fixes
-
-- `BoothLifecycleCoordinator` owns the active Event, Session, preflight
-  generation, abort controller, auth-blocked flag, and one retained stop
-  promise per Session.
-- Upload `401` clears credentials and relocks immediately, but a successful
-  new preflight awaits the exact owning stop promise before `start()` and an
-  automatic `retry()` of the auth-blocked oldest item.
-- Stale preflight results, deferred old recovery, old Session uploads, state
-  subscriptions, capture tails, and file-decode tails cannot mutate the new
-  Event.
-- A successful response is filtered through the current Frame catalog using
-  `availableTemplates`; malformed, empty, or unknown-only Frames never enter
-  `ready`, start Session work, or start the camera.
-- Event reset now clears status, mode, last URL, errors, countdown, shot,
-  flash, capture/camera work, enabled Frames, access feedback, and current
-  credential. `BoothUnlock` is Event-keyed and its tested form reducer also
-  clears key/remember state on Event identity changes.
-- Checking, network failure, Event unavailable, and rejected-key states have
-  fixed non-secret live-region copy. Rejected credentials use an assertive
-  alert without echoing the key.
-
-### Fresh review verification
-
-```text
-focused review suite: 78 pass, 0 fail, 200 expectations
-bun run typecheck: exit 0
-bun run typecheck:tests: exit 0
-full bun test: 308 pass, 0 fail, 980 expectations across 26 files
-bun run build: exit 0; /[event] production route compiled
-git diff --check: clean
-```
-
-## Second review follow-up — credential and auth retry identity
-
-### RED
-
-The repository shell did not have Bun on `PATH`, so the first literal command
-confirmed the environment issue:
-
-```bash
-bun test 'app/[event]/booth-session/lifecycle.test.ts' \
-  'app/[event]/booth-session/session.test.ts' \
-  'app/[event]/booth-unlock.test.tsx'
-```
-
-Observed: exit `127`, `zsh:1: command not found: bun`.
-
-The same focused RED suite was then run with the installed Bun executable:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun test \
-  'app/[event]/booth-session/lifecycle.test.ts' \
-  'app/[event]/booth-session/session.test.ts' \
-  'app/[event]/booth-unlock.test.tsx'
-```
-
-Observed: exit `1`, `50 pass`, `14 fail`, `134` expectations. The failures
-showed the missing per-Session credential holder, missing exact-ID auth resume,
-reused stop promise, missing auth callback ID, and unsafe memory-outbox copy.
-
-### GREEN
-
-After the fixes, the focused lifecycle, Session, and unlock suite:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun test \
-  'app/[event]/booth-session/lifecycle.test.ts' \
-  'app/[event]/booth-session/session.test.ts' \
-  'app/[event]/booth-unlock.test.tsx'
-```
-
-Observed: exit `0`, `64 pass`, `0 fail`, `200` expectations.
-
-Application and test type checks:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun run typecheck && \
-  /Users/limboenedmund/.bun/bin/bun run typecheck:tests
-```
-
-Observed: exit `0`; both TypeScript checks passed.
-
-Full test and production build:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun test && \
-  /Users/limboenedmund/.bun/bin/bun run build
-```
-
-Observed: exit `0`; `313 pass`, `0 fail`, `1009` expectations across `26`
-test files, followed by a successful Next.js production build including the
-dynamic `/[event]` route.
-
-### Second review fixes
-
-- Every Booth Session upload closure now owns a distinct mutable credential
-  holder. Only the current successful preflight populates it; Event switch,
-  cleanup, and relock blank the old holder before deferred work can continue.
-- Auth-required callbacks expose only the exact persisted outbox item ID.
-  `resumeAuth(id)` may clear failure state only while holding the Event lease
-  and only when that exact ID is still the auth-failed oldest row. Manual
-  `retry()` remains a separate operator override.
-- A completed stop promise is cleared only for its exact epoch after the same
-  active Session restarts, so consecutive 401 recovery cycles each stop before
-  resuming.
-- Memory-only outbox copy says photos are waiting in the open page and that
-  reload recovery is unavailable; it never describes those photos as safe.
-
-## Final review follow-up — reload auth recovery
-
-### RED
-
-Added Session recovery-contract tests, real fresh-page coordinator/Session
-tests, and synchronous candidate-key zeroing tests before implementation:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun test \
-  'app/[event]/booth-session/session.test.ts' \
-  'app/[event]/booth-session/lifecycle.test.ts' \
-  'app/[event]/booth-unlock.test.tsx'
-```
-
-Observed: exit `1`, `65 pass`, `5 fail`, `209` expectations. The expected
-failures showed that `recover()` returned no auth identity, a fresh coordinator
-did not resume the persisted auth row, and candidate keys survived replacement
-and leave until after the security boundary.
-
-### GREEN
-
-The same focused suite after the minimal recovery contract and zeroing changes:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun test \
-  'app/[event]/booth-session/session.test.ts' \
-  'app/[event]/booth-session/lifecycle.test.ts' \
-  'app/[event]/booth-unlock.test.tsx'
-```
-
-Observed: exit `0`, `70 pass`, `0 fail`, `212` expectations.
-
-Both TypeScript checks:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun run typecheck && \
-  /Users/limboenedmund/.bun/bin/bun run typecheck:tests
-```
-
-Observed: exit `0`; both checks passed.
-
-Full test suite:
-
-```bash
-/Users/limboenedmund/.bun/bin/bun test
-```
-
-Observed: exit `0`, `319 pass`, `0 fail`, `1021` expectations across `26`
-test files.
-
-### Final review fixes
-
-- `BoothSession.recover()` reports the exact oldest persisted auth-failed item
-  ID without changing or removing any outbox row.
-- Fresh coordinator recovery retains that ID through credential preflight and
-  invokes the existing lease-gated `resumeAuth(id)` path only after successful
-  authentication. The auth row and following rows drain in FIFO order.
-- A recovered permanent oldest row exposes no auth-resume identity and remains
-  paused.
-- Event replacement and leave synchronously blank both the upload credential
-  holder and the coordinator's candidate key before any deferred stop work.

From 1790fd5595c05040b7b87c4e7ce2262a60558686 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:09:54 +0800
Subject: [PATCH 049/105] feat: pause and monitor booth sessions

---
 .../booth-session/device-identity.test.ts     |  85 +++++
 app/[event]/booth-session/device-identity.ts  |  28 ++
 app/[event]/booth-session/lifecycle.test.ts   |  31 ++
 app/[event]/booth-session/lifecycle.ts        |   6 +-
 .../booth-session/operational-client.test.ts  | 285 +++++++++++++++
 .../booth-session/operational-client.ts       | 251 ++++++++++++++
 app/[event]/booth-unlock.test.tsx             |  29 ++
 app/[event]/booth.module.css                  | 100 ++++++
 app/[event]/page.tsx                          | 326 ++++++++++++++++--
 9 files changed, 1115 insertions(+), 26 deletions(-)
 create mode 100644 app/[event]/booth-session/device-identity.test.ts
 create mode 100644 app/[event]/booth-session/device-identity.ts
 create mode 100644 app/[event]/booth-session/operational-client.test.ts
 create mode 100644 app/[event]/booth-session/operational-client.ts

diff --git a/app/[event]/booth-session/device-identity.test.ts b/app/[event]/booth-session/device-identity.test.ts
new file mode 100644
index 0000000..aa8b84f
--- /dev/null
+++ b/app/[event]/booth-session/device-identity.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { clearBoothCredential } from "./credential";
+import { loadOrCreateDeviceId } from "./device-identity";
+
+const DEVICE_ID_KEY = "webbooth:device-id";
+const DEVICE_ID = "0f9c4f16-2f58-4ea3-88c0-c7a3f2c2b81a";
+
+class MemoryStorage implements Storage {
+  private readonly values = new Map<string, string>();
+
+  get length() { return this.values.size; }
+  clear() { this.values.clear(); }
+  getItem(key: string) { return this.values.get(key) ?? null; }
+  key(index: number) { return [...this.values.keys()][index] ?? null; }
+  removeItem(key: string) { this.values.delete(key); }
+  setItem(key: string, value: string) { this.values.set(key, value); }
+}
+
+class FailingStorage extends MemoryStorage {
+  override getItem(_key: string): string | null {
+    throw new DOMException("Storage unavailable", "SecurityError");
+  }
+
+  override setItem(_key: string, _value: string): void {
+    throw new DOMException("Storage unavailable", "SecurityError");
+  }
+}
+
+class WriteFailingStorage extends MemoryStorage {
+  override setItem(_key: string, _value: string): void {
+    throw new DOMException("Storage unavailable", "SecurityError");
+  }
+}
+
+describe("Booth device identity", () => {
+  test("returns the stored lowercase UUID-v4", () => {
+    const storage = new MemoryStorage();
+    storage.setItem(DEVICE_ID_KEY, DEVICE_ID);
+
+    expect(loadOrCreateDeviceId(storage, () => "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"))
+      .toBe(DEVICE_ID);
+  });
+
+  test("creates and stores a lowercase UUID-v4 when missing", () => {
+    const storage = new MemoryStorage();
+
+    expect(loadOrCreateDeviceId(storage, () => DEVICE_ID.toUpperCase())).toBe(DEVICE_ID);
+    expect(storage.getItem(DEVICE_ID_KEY)).toBe(DEVICE_ID);
+  });
+
+  test("uses one session-only ID when local storage throws", () => {
+    const storage = new FailingStorage();
+    let made = 0;
+    const makeId = () => {
+      made++;
+      return DEVICE_ID;
+    };
+
+    expect(loadOrCreateDeviceId(storage, makeId)).toBe(DEVICE_ID);
+    expect(loadOrCreateDeviceId(storage, makeId)).toBe(DEVICE_ID);
+    expect(made).toBe(1);
+  });
+
+  test("keeps the generated ID when storage fails while writing it", () => {
+    const storage = new WriteFailingStorage();
+    const first = DEVICE_ID;
+    const second = "2e29bd33-8750-4f58-b23c-f4ebf0d8267e";
+    let made = 0;
+
+    expect(loadOrCreateDeviceId(storage, () => (++made === 1 ? first : second))).toBe(first);
+    expect(made).toBe(1);
+  });
+
+  test("clearing Booth credentials leaves the device ID untouched", () => {
+    const session = new MemoryStorage();
+    const local = new MemoryStorage();
+    local.setItem(DEVICE_ID_KEY, DEVICE_ID);
+    local.setItem("webbooth:launch:booth-key", "secret");
+
+    clearBoothCredential("launch", session, local);
+
+    expect(local.getItem(DEVICE_ID_KEY)).toBe(DEVICE_ID);
+    expect(loadOrCreateDeviceId(local)).toBe(DEVICE_ID);
+  });
+});
diff --git a/app/[event]/booth-session/device-identity.ts b/app/[event]/booth-session/device-identity.ts
new file mode 100644
index 0000000..d4fc372
--- /dev/null
+++ b/app/[event]/booth-session/device-identity.ts
@@ -0,0 +1,28 @@
+const DEVICE_ID_KEY = "webbooth:device-id";
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+// A blocked localStorage implementation cannot persist across a reload, but it
+// can still keep one stable identity for this page's browser session.
+const sessionOnlyIds = new WeakMap<object, string>();
+
+export function loadOrCreateDeviceId(
+  storage: Pick<Storage, "getItem" | "setItem">,
+  makeId: () => string = () => crypto.randomUUID()
+): string {
+  const sessionOnly = sessionOnlyIds.get(storage);
+  if (sessionOnly) return sessionOnly;
+
+  let generated: string | null = null;
+  try {
+    const stored = storage.getItem(DEVICE_ID_KEY);
+    if (stored && UUID_V4.test(stored)) return stored;
+
+    generated = makeId().toLowerCase();
+    storage.setItem(DEVICE_ID_KEY, generated);
+    return generated;
+  } catch {
+    const deviceId = generated ?? makeId().toLowerCase();
+    sessionOnlyIds.set(storage, deviceId);
+    return deviceId;
+  }
+}
diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
index d041e2e..ba376d2 100644
--- a/app/[event]/booth-session/lifecycle.test.ts
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -60,6 +60,7 @@ function harness(options: {
   const access: string[] = [];
   const frames: Array<string[] | null> = [];
   const uploaded: string[] = [];
+  const operational: unknown[] = [];
   const cleared: string[] = [];
   let cameraStarts = 0;
   let cameraStops = 0;
@@ -76,6 +77,7 @@ function harness(options: {
     onOutboxRecovered: () => events.push("outbox-recovered"),
     onAccess: (state, feedback) => access.push(`${state}:${feedback}`),
     onFrames: (next) => frames.push(next),
+    onOperationalState: (state) => operational.push(state),
     onCameraStart: () => {
       cameraStarts++;
     },
@@ -90,6 +92,7 @@ function harness(options: {
     access,
     frames,
     uploaded,
+    operational,
     cleared,
     cameraStarts: () => cameraStarts,
     cameraStops: () => cameraStops,
@@ -199,6 +202,34 @@ describe("Booth lifecycle coordination", () => {
     expect(h.cameraStarts()).toBe(1);
   });
 
+  test("applies operational state only from the current successful preflight", async () => {
+    const first = deferred<BoothPreflightResult>();
+    const second = deferred<BoothPreflightResult>();
+    let attempts = 0;
+    const h = harness({
+      preflight: async () => (++attempts === 1 ? first.promise : second.promise),
+    });
+    const session = new FakeSession();
+    await h.coordinator.beginEvent("launch", session, credential());
+
+    const stale = h.coordinator.unlock("old-key");
+    const current = h.coordinator.unlock("new-key");
+    second.resolve({
+      kind: "ready",
+      frames: ["square"],
+      operationalState: { version: 1, paused: true },
+    });
+    await current;
+    first.resolve({
+      kind: "ready",
+      frames: ["square"],
+      operationalState: { version: 1, paused: false },
+    });
+    await stale;
+
+    expect(h.operational).toEqual([{ version: 1, paused: true }]);
+  });
+
   test("StrictMode-style cleanup prevents deferred recovery from starting old work", async () => {
     const recovery = deferred<void>();
     const oldSession = new FakeSession();
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
index 1403c13..661d25b 100644
--- a/app/[event]/booth-session/lifecycle.ts
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -11,7 +11,7 @@ export type BoothAccessFeedback =
   | "ready";
 
 export type BoothPreflightResult =
-  | { kind: "ready"; frames: unknown }
+  | { kind: "ready"; frames: unknown; operationalState?: unknown }
   | { kind: "unauthorized" }
   | { kind: "unavailable" }
   | { kind: "recovery-only" };
@@ -53,6 +53,7 @@ type BoothLifecycleDependencies<Result> = {
   onOutboxRecovered: () => void;
   onAccess: (state: BoothAccessState, feedback: BoothAccessFeedback) => void;
   onFrames: (frames: string[] | null) => void;
+  onOperationalState: (state: unknown) => void;
   onCameraStart: () => void;
   onCameraStop: () => void;
   onUploaded: (result: Result) => void;
@@ -237,6 +238,9 @@ export class BoothLifecycleCoordinator<Result> {
     if (!this.isCurrent(active, preflightId)) return;
 
     active.credential.key = key;
+    if (result.operationalState !== undefined) {
+      this.deps.onOperationalState(result.operationalState);
+    }
     this.deps.onFrames(frames);
     this.deps.onAccess("ready", "ready");
     let startWork: Promise<void> | void;
diff --git a/app/[event]/booth-session/operational-client.test.ts b/app/[event]/booth-session/operational-client.test.ts
new file mode 100644
index 0000000..7c2f66a
--- /dev/null
+++ b/app/[event]/booth-session/operational-client.test.ts
@@ -0,0 +1,285 @@
+import { describe, expect, test } from "bun:test";
+import type { BoothHeartbeatInput } from "../../booth-control";
+import {
+  BoothHeartbeatReporter,
+  BoothStatePoller,
+  type FetchLike,
+} from "./operational-client";
+
+const EVENT = "launch";
+const DEVICE_ID = "0f9c4f16-2f58-4ea3-88c0-c7a3f2c2b81a";
+
+type Deferred<T> = {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+};
+
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((nextResolve, nextReject) => {
+    resolve = nextResolve;
+    reject = nextReject;
+  });
+  return { promise, resolve, reject };
+}
+
+async function settle() {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+class Timers {
+  private nextId = 0;
+  readonly pending = new Map<number, { callback: () => void; delayMs: number }>();
+
+  set = (callback: () => void, delayMs: number) => {
+    const id = ++this.nextId;
+    this.pending.set(id, { callback, delayMs });
+    return id;
+  };
+
+  clear = (timer: unknown) => {
+    this.pending.delete(timer as number);
+  };
+
+  delays() {
+    return [...this.pending.values()].map(({ delayMs }) => delayMs);
+  }
+
+  runNext() {
+    const [id, timer] = this.pending.entries().next().value as [
+      number,
+      { callback: () => void; delayMs: number },
+    ];
+    this.pending.delete(id);
+    timer.callback();
+  }
+}
+
+function heartbeat(changes: Partial<BoothHeartbeatInput> = {}): BoothHeartbeatInput {
+  return {
+    version: 1,
+    deviceId: DEVICE_ID,
+    sessionStartedAt: 100,
+    pendingCount: 0,
+    durableStorage: true,
+    online: true,
+    installed: false,
+    camera: "ready",
+    upload: "idle",
+    buildId: "development",
+    ...changes,
+  };
+}
+
+function response(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("BoothStatePoller", () => {
+  test("polls immediately and schedules the next poll only after completion", async () => {
+    const timers = new Timers();
+    const calls: string[] = [];
+    const states: Array<{ paused: boolean; connected: boolean }> = [];
+    const fetch: FetchLike = async (input) => {
+      calls.push(String(input));
+      return response({ version: 1, paused: false, updatedAt: "2026-01-01T00:00:00.000Z" });
+    };
+    const poller = new BoothStatePoller({
+      event: EVENT,
+      fetch,
+      onState: (state) => states.push({ paused: state.paused, connected: state.connected }),
+      setTimer: timers.set,
+      clearTimer: timers.clear,
+    });
+
+    poller.start();
+    await settle();
+
+    expect(calls).toEqual(["/api/booth-state?event=launch"]);
+    expect(states.at(-1)).toEqual({ paused: false, connected: true });
+    expect(timers.delays()).toEqual([5_000]);
+
+    timers.runNext();
+    await settle();
+    expect(calls).toHaveLength(2);
+  });
+
+  test("shares an in-flight request instead of overlapping state polls", async () => {
+    const pending = deferred<Response>();
+    let calls = 0;
+    const poller = new BoothStatePoller({
+      event: EVENT,
+      fetch: () => {
+        calls++;
+        return pending.promise;
+      },
+    });
+
+    const first = poller.refresh();
+    const second = poller.refresh();
+    expect(second).toBe(first);
+    expect(calls).toBe(1);
+
+    pending.resolve(response({ version: 1, paused: true, updatedAt: "2026-01-01T00:00:00.000Z" }));
+    await first;
+  });
+
+  test("retains the last pause value and reports disconnected after a poll failure", async () => {
+    const states: Array<{ paused: boolean; connected: boolean }> = [];
+    let attempt = 0;
+    const poller = new BoothStatePoller({
+      event: EVENT,
+      fetch: async () => {
+        attempt++;
+        if (attempt === 1) return response({ version: 1, paused: true, updatedAt: "2026-01-01T00:00:00.000Z" });
+        throw new TypeError("offline");
+      },
+      onState: (state) => states.push({ paused: state.paused, connected: state.connected }),
+    });
+
+    await poller.refresh();
+    await poller.refresh();
+
+    expect(states.at(-1)).toEqual({ paused: true, connected: false });
+  });
+});
+
+describe("BoothHeartbeatReporter", () => {
+  test("sends immediately and schedules every heartbeat after the previous request settles", async () => {
+    const timers = new Timers();
+    const requests: RequestInit[] = [];
+    const reporter = new BoothHeartbeatReporter({
+      event: EVENT,
+      boothKey: () => "operator-key",
+      fetch: async (_input, init) => {
+        requests.push(init ?? {});
+        return response({ ok: true });
+      },
+      setTimer: timers.set,
+      clearTimer: timers.clear,
+    });
+    reporter.update(heartbeat());
+
+    reporter.start();
+    await settle();
+
+    expect(requests).toHaveLength(1);
+    expect(requests[0]).toMatchObject({
+      method: "POST",
+      headers: { "x-booth-key": "operator-key" },
+    });
+    expect(JSON.parse(String(requests[0].body))).toEqual(heartbeat());
+    expect(timers.delays()).toEqual([15_000]);
+
+    timers.runNext();
+    await settle();
+    expect(requests).toHaveLength(2);
+  });
+
+  test("coalesces state changes that occur during a heartbeat into one fresh report", async () => {
+    const first = deferred<Response>();
+    const sent: BoothHeartbeatInput[] = [];
+    let calls = 0;
+    const reporter = new BoothHeartbeatReporter({
+      event: EVENT,
+      boothKey: () => "operator-key",
+      fetch: async (_input, init) => {
+        sent.push(JSON.parse(String(init?.body)) as BoothHeartbeatInput);
+        calls++;
+        return calls === 1 ? first.promise : response({ ok: true });
+      },
+    });
+    reporter.update(heartbeat({ pendingCount: 1 }));
+    reporter.start();
+    reporter.update(heartbeat({ pendingCount: 2 }));
+    reporter.update(heartbeat({ pendingCount: 3, upload: "uploading" }));
+
+    first.resolve(response({ ok: true }));
+    await settle();
+
+    expect(sent).toEqual([
+      heartbeat({ pendingCount: 1 }),
+      heartbeat({ pendingCount: 3, upload: "uploading" }),
+    ]);
+  });
+
+  test("contains heartbeat failures so session work never rejects", async () => {
+    const reporter = new BoothHeartbeatReporter({
+      event: EVENT,
+      boothKey: () => "operator-key",
+      fetch: async () => { throw new TypeError("offline"); },
+    });
+    reporter.update(heartbeat());
+
+    await expect(reporter.flush()).resolves.toBeUndefined();
+  });
+
+  test("relocks through the auth callback when a heartbeat receives 401", async () => {
+    let authRequired = 0;
+    const reporter = new BoothHeartbeatReporter({
+      event: EVENT,
+      boothKey: () => "operator-key",
+      fetch: async () => response({ error: "unauthorized" }, 401),
+      onAuthRequired: () => { authRequired++; },
+    });
+    reporter.update(heartbeat());
+
+    await reporter.flush();
+
+    expect(authRequired).toBe(1);
+  });
+
+  test("stop aborts in-flight requests and clears completion timers", async () => {
+    const timers = new Timers();
+    let signal: AbortSignal | undefined;
+    const pending = deferred<Response>();
+    const reporter = new BoothHeartbeatReporter({
+      event: EVENT,
+      boothKey: () => "operator-key",
+      fetch: (_input, init) => {
+        signal = init?.signal ?? undefined;
+        return pending.promise;
+      },
+      setTimer: timers.set,
+      clearTimer: timers.clear,
+    });
+    reporter.update(heartbeat());
+    reporter.start();
+    await settle();
+    reporter.stop();
+
+    expect(signal?.aborted).toBe(true);
+    pending.resolve(response({ ok: true }));
+    await settle();
+    expect(timers.pending).toHaveLength(0);
+  });
+
+  test("stops an in-flight state poll and its timer", async () => {
+    const timers = new Timers();
+    let signal: AbortSignal | undefined;
+    const pending = deferred<Response>();
+    const poller = new BoothStatePoller({
+      event: EVENT,
+      fetch: (_input, init) => {
+        signal = init?.signal ?? undefined;
+        return pending.promise;
+      },
+      setTimer: timers.set,
+      clearTimer: timers.clear,
+    });
+    poller.start();
+    await settle();
+    poller.stop();
+
+    expect(signal?.aborted).toBe(true);
+    pending.resolve(response({ version: 1, paused: false, updatedAt: "2026-01-01T00:00:00.000Z" }));
+    await settle();
+    expect(timers.pending).toHaveLength(0);
+  });
+});
diff --git a/app/[event]/booth-session/operational-client.ts b/app/[event]/booth-session/operational-client.ts
new file mode 100644
index 0000000..c445d49
--- /dev/null
+++ b/app/[event]/booth-session/operational-client.ts
@@ -0,0 +1,251 @@
+import type { BoothHeartbeatInput } from "../../booth-control";
+
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+type Timer = unknown;
+type SetTimer = (callback: () => void, delayMs: number) => Timer;
+type ClearTimer = (timer: Timer) => void;
+
+export type BoothOperationalClientState = {
+  paused: boolean;
+  connected: boolean;
+};
+
+export type BoothStatePollerOptions = {
+  event: string;
+  fetch?: FetchLike;
+  onState?: (state: BoothOperationalClientState) => void;
+  setTimer?: SetTimer;
+  clearTimer?: ClearTimer;
+};
+
+export type BoothHeartbeatReporterOptions = {
+  event: string;
+  boothKey: () => string;
+  fetch?: FetchLike;
+  onAuthRequired?: () => void | Promise<void>;
+  setTimer?: SetTimer;
+  clearTimer?: ClearTimer;
+};
+
+const POLL_INTERVAL_MS = 5_000;
+const HEARTBEAT_INTERVAL_MS = 15_000;
+
+const defaultSetTimer: SetTimer = (callback, delayMs) => setTimeout(callback, delayMs);
+const defaultClearTimer: ClearTimer = (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>);
+
+/** Polls public pause state, never replacing a known state with a failed fetch. */
+export class BoothStatePoller {
+  private readonly fetch: FetchLike;
+  private readonly onState: (state: BoothOperationalClientState) => void;
+  private readonly setTimer: SetTimer;
+  private readonly clearTimer: ClearTimer;
+  private inFlight: Promise<void> | null = null;
+  private controller: AbortController | null = null;
+  private timer: Timer | null = null;
+  private started = false;
+  private stopped = false;
+  private paused = false;
+
+  constructor(private readonly options: BoothStatePollerOptions) {
+    this.fetch = options.fetch ?? fetch;
+    this.onState = options.onState ?? (() => {});
+    this.setTimer = options.setTimer ?? defaultSetTimer;
+    this.clearTimer = options.clearTimer ?? defaultClearTimer;
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.stopped = false;
+    void this.refresh();
+  }
+
+  refresh(): Promise<void> {
+    if (this.stopped) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+
+    const controller = new AbortController();
+    this.controller = controller;
+    let work!: Promise<void>;
+    work = (async () => {
+      try {
+        const response = await this.fetch(
+          `/api/booth-state?event=${encodeURIComponent(this.options.event)}`,
+          { signal: controller.signal, cache: "no-store" }
+        );
+        if (!response.ok) throw new TypeError("Booth state request failed");
+        const body: unknown = await response.json();
+        if (!isOperationalState(body)) throw new TypeError("Invalid Booth state response");
+        this.paused = body.paused;
+        if (!this.stopped) this.onState({ paused: this.paused, connected: true });
+      } catch {
+        if (!this.stopped) this.onState({ paused: this.paused, connected: false });
+      } finally {
+        if (this.controller === controller) this.controller = null;
+        if (this.inFlight === work) this.inFlight = null;
+        if (this.started && !this.stopped) this.schedule();
+      }
+    })();
+    this.inFlight = work;
+    return work;
+  }
+
+  stop(): void {
+    this.started = false;
+    this.stopped = true;
+    this.controller?.abort();
+    this.controller = null;
+    this.cancelTimer();
+  }
+
+  private schedule() {
+    this.cancelTimer();
+    this.timer = this.setTimer(() => {
+      this.timer = null;
+      void this.refresh();
+    }, POLL_INTERVAL_MS);
+  }
+
+  private cancelTimer() {
+    if (this.timer === null) return;
+    this.clearTimer(this.timer);
+    this.timer = null;
+  }
+}
+
+/** Reports one bounded private Booth snapshot without affecting capture or uploads. */
+export class BoothHeartbeatReporter {
+  private readonly fetch: FetchLike;
+  private readonly onAuthRequired: () => void | Promise<void>;
+  private readonly setTimer: SetTimer;
+  private readonly clearTimer: ClearTimer;
+  private snapshot: BoothHeartbeatInput | null = null;
+  private inFlight: Promise<void> | null = null;
+  private controller: AbortController | null = null;
+  private timer: Timer | null = null;
+  private started = false;
+  private stopped = false;
+  private dirty = false;
+
+  constructor(private readonly options: BoothHeartbeatReporterOptions) {
+    this.fetch = options.fetch ?? fetch;
+    this.onAuthRequired = options.onAuthRequired ?? (() => {});
+    this.setTimer = options.setTimer ?? defaultSetTimer;
+    this.clearTimer = options.clearTimer ?? defaultClearTimer;
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.stopped = false;
+    void this.flush();
+  }
+
+  update(snapshot: BoothHeartbeatInput): void {
+    this.snapshot = copySnapshot(snapshot);
+    if (this.inFlight) {
+      this.dirty = true;
+      return;
+    }
+    if (this.started && !this.stopped) void this.flush();
+  }
+
+  flush(): Promise<void> {
+    if (this.stopped || !this.snapshot) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+
+    const snapshot = this.snapshot;
+    this.dirty = false;
+    const controller = new AbortController();
+    this.controller = controller;
+    let work!: Promise<void>;
+    work = (async () => {
+      try {
+        const response = await this.fetch(
+          `/api/booths?event=${encodeURIComponent(this.options.event)}`,
+          {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "x-booth-key": this.options.boothKey(),
+            },
+            body: JSON.stringify(copySnapshot(snapshot)),
+            signal: controller.signal,
+          }
+        );
+        if (response.status === 401) {
+          try {
+            await this.onAuthRequired();
+          } catch {
+            // Relocking is a UI concern; its failure cannot affect the Session.
+          }
+        }
+      } catch {
+        // Heartbeats are observational. Network and server failures stay out of capture.
+      } finally {
+        if (this.controller === controller) this.controller = null;
+        if (this.inFlight === work) this.inFlight = null;
+        if (!this.started || this.stopped) return;
+        if (this.dirty) {
+          this.dirty = false;
+          void this.flush();
+          return;
+        }
+        this.schedule();
+      }
+    })();
+    this.inFlight = work;
+    return work;
+  }
+
+  stop(): void {
+    this.started = false;
+    this.stopped = true;
+    this.dirty = false;
+    this.controller?.abort();
+    this.controller = null;
+    this.cancelTimer();
+  }
+
+  private schedule() {
+    this.cancelTimer();
+    this.timer = this.setTimer(() => {
+      this.timer = null;
+      void this.flush();
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  private cancelTimer() {
+    if (this.timer === null) return;
+    this.clearTimer(this.timer);
+    this.timer = null;
+  }
+}
+
+function isOperationalState(value: unknown): value is { paused: boolean } {
+  return Boolean(value)
+    && typeof value === "object"
+    && typeof (value as { paused?: unknown }).paused === "boolean";
+}
+
+// Enumerating these fields prevents browser details, arbitrary exception
+// messages, and credentials from entering the private heartbeat payload.
+function copySnapshot(snapshot: BoothHeartbeatInput): BoothHeartbeatInput {
+  return {
+    version: 1,
+    deviceId: snapshot.deviceId,
+    sessionStartedAt: snapshot.sessionStartedAt,
+    pendingCount: snapshot.pendingCount,
+    durableStorage: snapshot.durableStorage,
+    online: snapshot.online,
+    installed: snapshot.installed,
+    camera: snapshot.camera,
+    upload: snapshot.upload,
+    ...(snapshot.lastSuccessfulUploadAt === undefined
+      ? {}
+      : { lastSuccessfulUploadAt: snapshot.lastSuccessfulUploadAt }),
+    ...(snapshot.errorClass === undefined ? {} : { errorClass: snapshot.errorClass }),
+    buildId: snapshot.buildId,
+  };
+}
diff --git a/app/[event]/booth-unlock.test.tsx b/app/[event]/booth-unlock.test.tsx
index 1d06b7a..72e8c31 100644
--- a/app/[event]/booth-unlock.test.tsx
+++ b/app/[event]/booth-unlock.test.tsx
@@ -145,3 +145,32 @@ describe("Booth unlock presentation", () => {
     expect(css).toContain("animation: none");
   });
 });
+
+describe("Booth operational integration", () => {
+  test("keeps polling, heartbeat, and paused capture boundaries separate from the Outbox", async () => {
+    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
+
+    expect(source).toContain('from "./booth-session/device-identity"');
+    expect(source).toContain('from "./booth-session/operational-client"');
+    expect(source).toContain("loadOrCreateDeviceId(window.localStorage)");
+    expect(source).toContain("new BoothStatePoller");
+    expect(source).toContain("new BoothHeartbeatReporter");
+    expect(source).toContain("operational.paused");
+    expect(source).toContain("pauseAfterCaptureRef");
+    expect(source).toContain("resumeAfterCaptureRef");
+    expect(source).toContain("void session.process()");
+    expect(source).toContain("statePollerRef.current?.stop()");
+    expect(source).toContain("heartbeatReporterRef.current?.stop()");
+    expect(source).toContain('process.env.NEXT_PUBLIC_BUILD_ID ?? "development"');
+    expect(source).not.toContain("navigator.userAgent");
+  });
+
+  test("shows pause and connectivity states with touch-safe focus treatment", async () => {
+    const css = await Bun.file(`${import.meta.dir}/booth.module.css`).text();
+
+    expect(css).toContain(".operationalPause");
+    expect(css).toContain(".connectivity");
+    expect(css).toContain(".choice:focus-visible");
+    expect(css).toContain("min-height: 44px");
+  });
+});
diff --git a/app/[event]/booth.module.css b/app/[event]/booth.module.css
index f269c65..ebb33e8 100644
--- a/app/[event]/booth.module.css
+++ b/app/[event]/booth.module.css
@@ -98,6 +98,14 @@
 }
 
 .choice:active { transform: scale(0.96); }
+.choice:focus-visible,
+.shutter:focus-visible,
+.change:focus-visible,
+.liveLink:focus-visible,
+.fileBtn:focus-within {
+  outline: 3px solid #fff;
+  outline-offset: 4px;
+}
 .choice small { font-weight: 500; color: #ffb3d9; font-size: 13px; }
 
 .icon {
@@ -128,6 +136,7 @@
   font-weight: 600;
   backdrop-filter: blur(8px);
   cursor: pointer;
+  min-height: 44px;
 }
 .change:disabled { opacity: 0.5; }
 
@@ -187,6 +196,9 @@
   background: rgba(0, 0, 0, 0.4);
   border-radius: 20px;
   backdrop-filter: blur(8px);
+  min-height: 44px;
+  display: inline-flex;
+  align-items: center;
 }
 
 .overlay {
@@ -203,6 +215,9 @@
 }
 
 .fileBtn {
+  display: inline-flex;
+  min-height: 56px;
+  align-items: center;
   padding: 16px 28px;
   background: #fff;
   color: #000;
@@ -257,6 +272,83 @@
   z-index: 6;
 }
 
+/* Public operational state is deliberately simple: paused/disconnected only.
+   Device identity, credentials, and heartbeat detail stay private. */
+.connectivity {
+  position: absolute;
+  top: calc(16px + env(safe-area-inset-top, 0px));
+  left: 16px;
+  max-width: min(360px, 70vw);
+  padding: 10px 14px;
+  border-radius: 12px;
+  background: rgba(67, 88, 125, 0.96);
+  color: #fff;
+  font-size: 13px;
+  font-weight: 650;
+  line-height: 1.35;
+  z-index: 6;
+}
+
+.operationalPause {
+  position: absolute;
+  inset: 0;
+  z-index: 15;
+  display: grid;
+  place-items: center;
+  padding:
+    max(28px, env(safe-area-inset-top, 0px))
+    max(28px, env(safe-area-inset-right, 0px))
+    max(28px, env(safe-area-inset-bottom, 0px))
+    max(28px, env(safe-area-inset-left, 0px));
+  background: rgba(7, 7, 12, 0.88);
+  color: #fff;
+  backdrop-filter: blur(10px);
+}
+
+.operationalPausePanel {
+  width: min(620px, 100%);
+  padding: clamp(28px, 5vw, 48px);
+  border: 1px solid #5b596a;
+  border-radius: 28px;
+  background: #111119;
+  box-shadow: 0 26px 80px rgba(0, 0, 0, 0.5);
+  text-align: center;
+  animation: pause-arrive 180ms ease-out both;
+}
+
+.operationalEyebrow {
+  margin: 0 0 12px;
+  color: #ff8fc2;
+  font: 800 12px/1.3 ui-monospace, "SFMono-Regular", Menlo, monospace;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.operationalPausePanel h1 {
+  margin: 0;
+  font: 850 clamp(38px, 7vw, 58px)/0.98 ui-rounded, "Arial Rounded MT Bold", system-ui, sans-serif;
+  letter-spacing: -0.045em;
+}
+
+.operationalPausePanel > p:last-child {
+  margin: 18px auto 0;
+  max-width: 460px;
+  color: #b9b8c6;
+  font-size: clamp(17px, 2.4vw, 21px);
+  line-height: 1.45;
+}
+
+@keyframes pause-arrive {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
 /* Operator unlock: one calm, explicit path from recovered Outbox to camera. */
 .unlock {
   --unlock-surface: #111119;
@@ -540,6 +632,9 @@
 @media (forced-colors: active) {
   .unlock,
   .unlockPanel,
+  .operationalPause,
+  .operationalPausePanel,
+  .connectivity,
   .readinessRail,
   .readinessRail > div,
   .unlockForm > input {
@@ -552,6 +647,10 @@
   .unlockForm button:focus-visible,
   .unlockRetry:focus-visible,
   .unlockForm > input:focus-visible,
+  .choice:focus-visible,
+  .shutter:focus-visible,
+  .change:focus-visible,
+  .liveLink:focus-visible,
   .remember:focus-within {
     outline: 3px solid Highlight;
     outline-offset: 4px;
@@ -560,6 +659,7 @@
 
 @media (prefers-reduced-motion: reduce) {
   .unlockPanel,
+  .operationalPausePanel,
   .flash {
     animation: none;
   }
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 3ccb22d..b28e6c2 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -13,6 +13,13 @@ import {
 } from "./booth-session/session";
 import { outboxUploadHeaders } from "./booth-session/upload";
 import { HttpUploadError, type UploadErrorClass } from "./booth-session/retry-policy";
+import { loadOrCreateDeviceId } from "./booth-session/device-identity";
+import {
+  BoothHeartbeatReporter,
+  BoothStatePoller,
+  type BoothOperationalClientState,
+} from "./booth-session/operational-client";
+import type { BoothErrorClass, BoothHeartbeatInput } from "../booth-control";
 import type { BoothAccessState } from "./booth-session/access";
 import {
   clearBoothCredential,
@@ -28,6 +35,7 @@ import {
 import { BoothUnlock } from "./booth-unlock";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
+type OperationalState = BoothOperationalClientState;
 
 const INITIAL_UPLOAD_STATE: UploadState = {
   status: "idle",
@@ -44,6 +52,44 @@ function uploadErrorClass(status: number): UploadErrorClass {
   return "unknown";
 }
 
+function isPreflightOperationalState(value: unknown): value is { version: 1; paused: boolean } {
+  return Boolean(value)
+    && typeof value === "object"
+    && (value as { version?: unknown }).version === 1
+    && typeof (value as { paused?: unknown }).paused === "boolean";
+}
+
+function isInstalled() {
+  if (typeof window === "undefined") return false;
+  const navigatorWithStandalone = navigator as Navigator & { standalone?: boolean };
+  return window.matchMedia("(display-mode: standalone)").matches
+    || navigatorWithStandalone.standalone === true;
+}
+
+function heartbeatCamera(status: Status, paused: boolean): BoothHeartbeatInput["camera"] {
+  if (paused) return "stopped";
+  if (status === "starting") return "starting";
+  if (status === "denied") return "denied";
+  if (status === "picking" || status === "ready" || status === "running") return "ready";
+  return "stopped";
+}
+
+function heartbeatUpload(upload: UploadState): BoothHeartbeatInput["upload"] {
+  if (upload.status === "uploading") return "uploading";
+  if (upload.status === "failed") return "blocked";
+  return "idle";
+}
+
+function heartbeatError(
+  status: Status,
+  cameraError: Extract<BoothErrorClass, "camera-permission" | "camera-unavailable"> | null,
+  upload: UploadState
+): BoothErrorClass | undefined {
+  if (status === "denied") return cameraError ?? "camera-unavailable";
+  if (upload.status === "failed") return "unknown";
+  return undefined;
+}
+
 async function requestBoothPreflight(
   event: string,
   key: string,
@@ -62,8 +108,18 @@ async function requestBoothPreflight(
     return { kind: "unavailable" };
   }
   if (!response.ok) return { kind: "recovery-only" };
-  const payload = await response.json() as { experience?: { frames?: unknown } };
-  return { kind: "ready", frames: payload.experience?.frames };
+  const payload = await response.json() as {
+    experience?: { frames?: unknown };
+    operationalState?: unknown;
+  };
+  if (!isPreflightOperationalState(payload.operationalState)) {
+    return { kind: "recovery-only" };
+  }
+  return {
+    kind: "ready",
+    frames: payload.experience?.frames,
+    operationalState: payload.operationalState,
+  };
 }
 
 export default function Booth() {
@@ -71,9 +127,17 @@ export default function Booth() {
   const videoRef = useRef<HTMLVideoElement>(null);
   const streamRef = useRef<MediaStream | null>(null);
   const sessionRef = useRef<BoothSession | null>(null);
+  const statePollerRef = useRef<BoothStatePoller | null>(null);
+  const heartbeatReporterRef = useRef<BoothHeartbeatReporter | null>(null);
   const captureRef = useRef<AbortController | null>(null);
   const cameraRequestRef = useRef(0);
   const unmountedRef = useRef(false);
+  const deviceIdRef = useRef("");
+  const sessionStartedAtRef = useRef(0);
+  const pauseAfterCaptureRef = useRef(false);
+  const resumeAfterCaptureRef = useRef(false);
+  const operationalRef = useRef<OperationalState>({ paused: false, connected: false });
+  const uploadStateRef = useRef<UploadState>(INITIAL_UPLOAD_STATE);
   const [status, setStatus] = useState<Status>("starting");
   const [accessState, setAccessState] = useState<BoothAccessState>("locked");
   const [accessFeedback, setAccessFeedback] =
@@ -84,7 +148,16 @@ export default function Booth() {
   const [shot, setShot] = useState(0); // e.g. 2 of 3
   const [flash, setFlash] = useState(false);
   const [lastUrl, setLastUrl] = useState<string | null>(null);
+  const [lastSuccessfulUploadAt, setLastSuccessfulUploadAt] = useState<number | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [cameraErrorClass, setCameraErrorClass] = useState<
+    Extract<BoothErrorClass, "camera-permission" | "camera-unavailable"> | null
+  >(null);
+  const [operational, setOperational] = useState<OperationalState>({
+    paused: false,
+    connected: false,
+  });
+  const [online, setOnline] = useState(false);
   const [uploadState, setUploadState] =
     useState<UploadState>(INITIAL_UPLOAD_STATE);
   // Frames remain unavailable until authenticated preflight returns the safe
@@ -92,9 +165,11 @@ export default function Booth() {
   const [enabled, setEnabled] = useState<string[] | null>(null);
 
   const startCamera = useCallback(async () => {
+    if (operationalRef.current.paused || unmountedRef.current) return;
     const request = ++cameraRequestRef.current;
     setStatus("starting");
     setError(null);
+    setCameraErrorClass(null);
     try {
       const stream = await navigator.mediaDevices.getUserMedia({
         video: { facingMode: "user", width: { ideal: 1920 }, height: { ideal: 1080 } },
@@ -102,7 +177,11 @@ export default function Booth() {
       });
       // unmounted while getUserMedia was pending: stop the tracks now or the
       // camera light stays on with nothing to clean it up
-      if (unmountedRef.current || request !== cameraRequestRef.current) {
+      if (
+        unmountedRef.current
+        || operationalRef.current.paused
+        || request !== cameraRequestRef.current
+      ) {
         stream.getTracks().forEach((t) => t.stop());
         return;
       }
@@ -112,7 +191,11 @@ export default function Booth() {
         videoRef.current.srcObject = stream;
         await videoRef.current.play();
       }
-      if (unmountedRef.current || request !== cameraRequestRef.current) {
+      if (
+        unmountedRef.current
+        || operationalRef.current.paused
+        || request !== cameraRequestRef.current
+      ) {
         stream.getTracks().forEach((track) => track.stop());
         if (streamRef.current === stream) streamRef.current = null;
         return;
@@ -121,6 +204,11 @@ export default function Booth() {
     } catch (e) {
       if (unmountedRef.current || request !== cameraRequestRef.current) return;
       setStatus("denied");
+      setCameraErrorClass(
+        e instanceof DOMException && (e.name === "NotAllowedError" || e.name === "SecurityError")
+          ? "camera-permission"
+          : "camera-unavailable"
+      );
       setError(e instanceof Error ? e.message : String(e));
     }
   }, []);
@@ -134,6 +222,38 @@ export default function Booth() {
     if (videoRef.current) videoRef.current.srcObject = null;
   }, []);
 
+  const pauseAtSafeBoundary = useCallback(() => {
+    setMode(null);
+    setShot(0);
+    setCount(0);
+    setFlash(false);
+    setStatus("picking");
+    stopCamera();
+  }, [stopCamera]);
+
+  const applyOperationalState = useCallback((next: OperationalState) => {
+    const previous = operationalRef.current;
+    operationalRef.current = next;
+    setOperational(next);
+    if (next.paused) {
+      if (captureRef.current) {
+        pauseAfterCaptureRef.current = true;
+        resumeAfterCaptureRef.current = false;
+        return;
+      }
+      pauseAtSafeBoundary();
+      return;
+    }
+    if (previous.paused) {
+      pauseAfterCaptureRef.current = false;
+      if (captureRef.current) {
+        resumeAfterCaptureRef.current = true;
+        return;
+      }
+      void startCamera();
+    }
+  }, [pauseAtSafeBoundary, startCamera]);
+
   const lifecycle = useMemo(
     () => new BoothLifecycleCoordinator<UploadResult>({
       preflight: requestBoothPreflight,
@@ -150,6 +270,12 @@ export default function Booth() {
           window.localStorage
         ),
       onReset: () => {
+        pauseAfterCaptureRef.current = false;
+        resumeAfterCaptureRef.current = false;
+        operationalRef.current = { paused: false, connected: false };
+        uploadStateRef.current = INITIAL_UPLOAD_STATE;
+        deviceIdRef.current = loadOrCreateDeviceId(window.localStorage);
+        sessionStartedAtRef.current = Date.now();
         setStatus("starting");
         setMode(null);
         setLastUrl(null);
@@ -159,6 +285,9 @@ export default function Booth() {
         setFlash(false);
         setEnabled(null);
         setOutboxRecovered(false);
+        setCameraErrorClass(null);
+        setOperational(operationalRef.current);
+        setOnline(navigator.onLine);
         setUploadState(INITIAL_UPLOAD_STATE);
       },
       onOutboxRecovered: () => setOutboxRecovered(true),
@@ -175,13 +304,46 @@ export default function Booth() {
         setAccessFeedback(feedback);
       },
       onFrames: setEnabled,
+      onOperationalState: (value) => {
+        if (isPreflightOperationalState(value)) {
+          applyOperationalState({ paused: value.paused, connected: true });
+        }
+      },
       onCameraStart: () => {
-        void startCamera();
+        const reporter = heartbeatReporterRef.current;
+        if (reporter && deviceIdRef.current && sessionStartedAtRef.current) {
+          const upload = uploadStateRef.current;
+          reporter.update({
+            version: 1,
+            deviceId: deviceIdRef.current,
+            sessionStartedAt: sessionStartedAtRef.current,
+            pendingCount: upload.pendingCount,
+            durableStorage: upload.durable,
+            online: navigator.onLine,
+            installed: isInstalled(),
+            camera: operationalRef.current.paused ? "stopped" : "starting",
+            upload: heartbeatUpload(upload),
+            ...(heartbeatError("starting", null, upload) === undefined
+              ? {}
+              : { errorClass: heartbeatError("starting", null, upload) }),
+            buildId: process.env.NEXT_PUBLIC_BUILD_ID ?? "development",
+          });
+          reporter.start();
+        }
+        statePollerRef.current?.start();
+        if (!operationalRef.current.paused) void startCamera();
+      },
+      onCameraStop: () => {
+        statePollerRef.current?.stop();
+        heartbeatReporterRef.current?.stop();
+        stopCamera();
+      },
+      onUploaded: ({ url }) => {
+        setLastUrl(url);
+        setLastSuccessfulUploadAt(Date.now());
       },
-      onCameraStop: stopCamera,
-      onUploaded: ({ url }) => setLastUrl(url),
     }),
-    [startCamera, stopCamera]
+    [applyOperationalState, startCamera, stopCamera]
   );
 
   useEffect(() => {
@@ -239,25 +401,73 @@ export default function Booth() {
       }
     );
     sessionRef.current = session;
+    const poller = new BoothStatePoller({
+      event,
+      onState: applyOperationalState,
+    });
+    statePollerRef.current = poller;
+    const reporter = new BoothHeartbeatReporter({
+      event,
+      boothKey: () => credential.key,
+      onAuthRequired: () => lifecycle.authRequired(session, ""),
+    });
+    heartbeatReporterRef.current = reporter;
     const entering = lifecycle.beginEvent(event, session, credential);
     const unsubscribe = session.subscribe((next) => {
-      if (lifecycle.isActive(session)) setUploadState(next);
+      if (lifecycle.isActive(session)) {
+        uploadStateRef.current = next;
+        setUploadState(next);
+      }
     });
-    const reconsiderConnectivity = () => void session.reconsider("connectivity");
+    const reconsiderConnectivity = () => {
+      setOnline(navigator.onLine);
+      void session.reconsider("connectivity");
+    };
     const reconsiderForeground = () => {
       if (document.visibilityState === "visible") void session.reconsider("foreground");
     };
     window.addEventListener("online", reconsiderConnectivity);
+    window.addEventListener("offline", reconsiderConnectivity);
     document.addEventListener("visibilitychange", reconsiderForeground);
     void entering;
     return () => {
       unsubscribe();
       window.removeEventListener("online", reconsiderConnectivity);
+      window.removeEventListener("offline", reconsiderConnectivity);
       document.removeEventListener("visibilitychange", reconsiderForeground);
       if (sessionRef.current === session) sessionRef.current = null;
+      if (statePollerRef.current === poller) statePollerRef.current = null;
+      if (heartbeatReporterRef.current === reporter) heartbeatReporterRef.current = null;
       void lifecycle.leaveEvent(session);
     };
-  }, [event, lifecycle]);
+  }, [applyOperationalState, event, lifecycle]);
+
+  useEffect(() => {
+    const reporter = heartbeatReporterRef.current;
+    if (!reporter || !deviceIdRef.current || !sessionStartedAtRef.current) return;
+    const errorClass = heartbeatError(status, cameraErrorClass, uploadState);
+    reporter.update({
+      version: 1,
+      deviceId: deviceIdRef.current,
+      sessionStartedAt: sessionStartedAtRef.current,
+      pendingCount: uploadState.pendingCount,
+      durableStorage: uploadState.durable,
+      online,
+      installed: isInstalled(),
+      camera: heartbeatCamera(status, operational.paused),
+      upload: heartbeatUpload(uploadState),
+      ...(lastSuccessfulUploadAt === null ? {} : { lastSuccessfulUploadAt }),
+      ...(errorClass === undefined ? {} : { errorClass }),
+      buildId: process.env.NEXT_PUBLIC_BUILD_ID ?? "development",
+    });
+  }, [
+    cameraErrorClass,
+    lastSuccessfulUploadAt,
+    online,
+    operational.paused,
+    status,
+    uploadState,
+  ]);
 
   const unlock = useCallback((key: string, remember: boolean) => {
     saveBoothCredential(
@@ -281,7 +491,12 @@ export default function Booth() {
 
   // take the whole sequence for the chosen mode, composite, upload
   const run = useCallback(async () => {
-    if (accessState !== "ready" || status !== "ready" || !mode) return;
+    if (
+      accessState !== "ready"
+      || operationalRef.current.paused
+      || status !== "ready"
+      || !mode
+    ) return;
     const t = TEMPLATES[mode];
     setStatus("running");
     const controller = new AbortController();
@@ -316,8 +531,18 @@ export default function Booth() {
       // Durable handoff is complete. Return to the picker before uploading so
       // the next guest is never trapped on the previous guest's frame.
       setError(null);
-      setMode(null);
-      setStatus("picking");
+      if (operationalRef.current.paused) {
+        pauseAfterCaptureRef.current = false;
+        pauseAtSafeBoundary();
+      } else {
+        setMode(null);
+        setStatus("picking");
+        if (resumeAfterCaptureRef.current) {
+          resumeAfterCaptureRef.current = false;
+          void startCamera();
+        }
+      }
+      // Pause gates new capture only. It never interrupts the ordered Outbox.
       void session.process();
     } catch (e) {
       if (controller.signal.aborted || !session || !lifecycle.isActive(session)) return;
@@ -327,12 +552,29 @@ export default function Booth() {
       setShot(0);
       setCount(0);
       setFlash(false);
-      setMode(null);
-      setStatus(streamRef.current ? "picking" : "denied");
+      if (operationalRef.current.paused) {
+        pauseAfterCaptureRef.current = false;
+        pauseAtSafeBoundary();
+      } else {
+        setMode(null);
+        setStatus(streamRef.current ? "picking" : "denied");
+        if (resumeAfterCaptureRef.current) {
+          resumeAfterCaptureRef.current = false;
+          void startCamera();
+        }
+      }
     } finally {
       if (captureRef.current === controller) captureRef.current = null;
     }
-  }, [accessState, status, mode, grabFrame, lifecycle]);
+  }, [
+    accessState,
+    status,
+    mode,
+    grabFrame,
+    lifecycle,
+    pauseAtSafeBoundary,
+    startCamera,
+  ]);
 
   // fallback: native file input (camera) when getUserMedia is blocked.
   // Re-encode to a real JPEG first — iPhones hand back HEIC, and the stored
@@ -340,7 +582,7 @@ export default function Booth() {
   // ponytail: fallback photos stay frameless; compositing needs the live capture flow.
   const onFile = useCallback(
     async (e: React.ChangeEvent<HTMLInputElement>) => {
-      if (accessState !== "ready") {
+      if (accessState !== "ready" || operationalRef.current.paused) {
         e.target.value = "";
         return;
       }
@@ -352,7 +594,8 @@ export default function Booth() {
       const session = sessionRef.current;
       try {
         if (!session) throw new Error("Photo queue is still starting — please try again");
-        await session.enqueueCapture(async () => {
+        await session.enqueueCapture(async (signal) => {
+          if (signal?.aborted) throw new DOMException("Capture aborted", "AbortError");
           let blob: Blob = file;
           try {
             const bmp = await createImageBitmap(file);
@@ -375,19 +618,33 @@ export default function Booth() {
         });
         if (controller.signal.aborted || !lifecycle.isActive(session)) return;
         setError(null);
+        if (operationalRef.current.paused) {
+          pauseAfterCaptureRef.current = false;
+          pauseAtSafeBoundary();
+        } else if (resumeAfterCaptureRef.current) {
+          resumeAfterCaptureRef.current = false;
+          void startCamera();
+        }
         void session.process();
       } catch (uploadError) {
         if (controller.signal.aborted || !session || !lifecycle.isActive(session)) return;
         setError(uploadError instanceof Error ? uploadError.message : String(uploadError));
+        if (operationalRef.current.paused) {
+          pauseAfterCaptureRef.current = false;
+          pauseAtSafeBoundary();
+        } else if (resumeAfterCaptureRef.current) {
+          resumeAfterCaptureRef.current = false;
+          void startCamera();
+        }
       } finally {
         if (captureRef.current === controller) captureRef.current = null;
       }
     },
-    [accessState, lifecycle]
+    [accessState, lifecycle, pauseAtSafeBoundary, startCamera]
   );
 
   const pick = (m: keyof typeof TEMPLATES) => {
-    if (accessState !== "ready") return;
+    if (accessState !== "ready" || operationalRef.current.paused) return;
     setMode(m);
     setStatus("ready");
   };
@@ -434,7 +691,12 @@ export default function Booth() {
             {availableTemplates(enabled).map((k) => {
               const t = TEMPLATES[k];
               return (
-                <button key={k} className={styles.choice} onClick={() => pick(k)}>
+                <button
+                  key={k}
+                  className={styles.choice}
+                  onClick={() => pick(k)}
+                  disabled={operational.paused}
+                >
                   {t.bgImage ? (
                     // eslint-disable-next-line @next/next/no-img-element
                     <img src={t.bgImage} alt="" className={styles.iconFrame} />
@@ -460,7 +722,7 @@ export default function Booth() {
               accept="image/*"
               capture="user"
               onChange={onFile}
-              disabled={accessState !== "ready"}
+              disabled={accessState !== "ready" || operational.paused}
               hidden
             />
           </label>
@@ -476,7 +738,7 @@ export default function Booth() {
           <button
             className={styles.shutter}
             onClick={run}
-            disabled={accessState !== "ready" || status !== "ready"}
+            disabled={accessState !== "ready" || operational.paused || status !== "ready"}
             aria-label="Start"
           >
             {status === "running" ? "" : mode && TEMPLATES[mode].shots > 1 ? "▶" : ""}
@@ -484,7 +746,7 @@ export default function Booth() {
           <button
             className={styles.change}
             onClick={() => setStatus("picking")}
-            disabled={accessState !== "ready" || status !== "ready"}
+            disabled={accessState !== "ready" || operational.paused || status !== "ready"}
           >
             {mode && TEMPLATES[mode].label} · change
           </button>
@@ -529,6 +791,20 @@ export default function Booth() {
           Offline photo storage is unavailable. Pending photos may be lost if this page reloads.
         </div>
       )}
+      {accessState === "ready" && !operational.connected && (
+        <div className={styles.connectivity} role="status" aria-live="polite">
+          Checking Event connection. The last pause state stays in effect.
+        </div>
+      )}
+      {accessState === "ready" && operational.paused && (
+        <section className={styles.operationalPause} aria-labelledby="booth-paused-title">
+          <div className={styles.operationalPausePanel} role="status" aria-live="polite">
+            <p className={styles.operationalEyebrow}>Event operator</p>
+            <h1 id="booth-paused-title">Booth paused</h1>
+            <p>Finishing any photo already in progress. This Booth will resume when the Event is ready.</p>
+          </div>
+        </section>
+      )}
     </main>
   );
 }

From acd5d2e8b2abaf8796718cfd4accaa43e86bac74 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:26:12 +0800
Subject: [PATCH 050/105] fix: harden booth operational lifecycle

---
 app/[event]/booth-session/lifecycle.test.ts   |  50 ++++++
 app/[event]/booth-session/lifecycle.ts        |  18 +++
 .../booth-session/operational-client.test.ts  | 151 +++++++++++++++++-
 .../booth-session/operational-client.ts       |  67 ++++++--
 .../booth-session/pause-boundary.test.ts      |  79 +++++++++
 app/[event]/booth-session/pause-boundary.ts   |  60 +++++++
 app/[event]/booth-unlock.test.tsx             |  18 ---
 app/[event]/page.tsx                          | 133 +++++----------
 8 files changed, 451 insertions(+), 125 deletions(-)
 create mode 100644 app/[event]/booth-session/pause-boundary.test.ts
 create mode 100644 app/[event]/booth-session/pause-boundary.ts

diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
index ba376d2..95b9f4f 100644
--- a/app/[event]/booth-session/lifecycle.test.ts
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import {
+  boothPreflightResultFromPayload,
   BoothLifecycleCoordinator,
   usablePreflightFrames,
   type BoothLifecycleSession,
@@ -468,3 +469,52 @@ describe("preflight Frame validation", () => {
     }
   );
 });
+
+describe("preflight operational-state validation", () => {
+  const validState = {
+    version: 1,
+    paused: true,
+    messages: { en: "Hold for setup" },
+    updatedAt: "2026-01-01T00:00:00.000Z",
+  };
+
+  test("accepts a full strict v1 state alongside the raw Frame list", () => {
+    expect(boothPreflightResultFromPayload({
+      experience: { frames: ["square"] },
+      operationalState: validState,
+    })).toEqual({
+      kind: "ready",
+      frames: ["square"],
+      operationalState: validState,
+    });
+  });
+
+  test.each([
+    { paused: false },
+    { ...validState, version: 2 },
+    { ...validState, unexpected: true },
+  ])("rejects malformed or incompatible operational state: $value", (value) => {
+    expect(boothPreflightResultFromPayload({
+      experience: { frames: ["square"] },
+      operationalState: value,
+    })).toEqual({ kind: "recovery-only" });
+  });
+
+  test("malformed preflight cannot clear pause or become ready", async () => {
+    const h = harness({
+      stored: { launch: "stored-key" },
+      preflight: async () => boothPreflightResultFromPayload({
+        experience: { frames: ["square"] },
+        operationalState: { paused: false },
+      }),
+    });
+    const session = new FakeSession();
+
+    await h.coordinator.beginEvent("launch", session, credential());
+
+    expect(h.operational).toEqual([]);
+    expect(h.access.at(-1)).toBe("recovery-only:network");
+    expect(session.actions).not.toContain("start");
+    expect(h.cameraStarts()).toBe(0);
+  });
+});
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
index 661d25b..9a93fca 100644
--- a/app/[event]/booth-session/lifecycle.ts
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -1,4 +1,5 @@
 import { availableTemplates } from "../../templates";
+import { parseBoothOperationalState } from "../../booth-control";
 import type { BoothAccessState } from "./access";
 
 export type BoothAccessFeedback =
@@ -67,6 +68,23 @@ export function usablePreflightFrames(value: unknown): string[] | null {
   return usable.length > 0 ? usable : null;
 }
 
+export function boothPreflightResultFromPayload(value: unknown): BoothPreflightResult {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { kind: "recovery-only" };
+  }
+  const payload = value as {
+    experience?: unknown;
+    operationalState?: unknown;
+  };
+  const operationalState = parseBoothOperationalState(payload.operationalState);
+  if (!operationalState) return { kind: "recovery-only" };
+  const experience = payload.experience;
+  const frames = experience && typeof experience === "object" && !Array.isArray(experience)
+    ? (experience as { frames?: unknown }).frames
+    : undefined;
+  return { kind: "ready", frames, operationalState };
+}
+
 export class BoothLifecycleCoordinator<Result> {
   private active: ActiveSession | null = null;
   private nextSessionId = 0;
diff --git a/app/[event]/booth-session/operational-client.test.ts b/app/[event]/booth-session/operational-client.test.ts
index 7c2f66a..17da1ea 100644
--- a/app/[event]/booth-session/operational-client.test.ts
+++ b/app/[event]/booth-session/operational-client.test.ts
@@ -3,6 +3,7 @@ import type { BoothHeartbeatInput } from "../../booth-control";
 import {
   BoothHeartbeatReporter,
   BoothStatePoller,
+  createBoothOperationalSessionState,
   type FetchLike,
 } from "./operational-client";
 
@@ -81,6 +82,14 @@ function response(body: unknown, status = 200) {
   });
 }
 
+function operationalState(paused: boolean) {
+  return {
+    version: 1,
+    paused,
+    updatedAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
 describe("BoothStatePoller", () => {
   test("polls immediately and schedules the next poll only after completion", async () => {
     const timers = new Timers();
@@ -88,7 +97,7 @@ describe("BoothStatePoller", () => {
     const states: Array<{ paused: boolean; connected: boolean }> = [];
     const fetch: FetchLike = async (input) => {
       calls.push(String(input));
-      return response({ version: 1, paused: false, updatedAt: "2026-01-01T00:00:00.000Z" });
+      return response(operationalState(false));
     };
     const poller = new BoothStatePoller({
       event: EVENT,
@@ -126,7 +135,7 @@ describe("BoothStatePoller", () => {
     expect(second).toBe(first);
     expect(calls).toBe(1);
 
-    pending.resolve(response({ version: 1, paused: true, updatedAt: "2026-01-01T00:00:00.000Z" }));
+    pending.resolve(response(operationalState(true)));
     await first;
   });
 
@@ -137,7 +146,7 @@ describe("BoothStatePoller", () => {
       event: EVENT,
       fetch: async () => {
         attempt++;
-        if (attempt === 1) return response({ version: 1, paused: true, updatedAt: "2026-01-01T00:00:00.000Z" });
+        if (attempt === 1) return response(operationalState(true));
         throw new TypeError("offline");
       },
       onState: (state) => states.push({ paused: state.paused, connected: state.connected }),
@@ -148,6 +157,65 @@ describe("BoothStatePoller", () => {
 
     expect(states.at(-1)).toEqual({ paused: true, connected: false });
   });
+
+  test("rejects partial, incompatible, and unknown state fields without clearing pause", async () => {
+    const states: Array<{ paused: boolean; connected: boolean }> = [];
+    const replies = [
+      operationalState(true),
+      { paused: false },
+      { ...operationalState(false), version: 2 },
+      { ...operationalState(false), unexpected: true },
+    ];
+    const poller = new BoothStatePoller({
+      event: EVENT,
+      fetch: async () => response(replies.shift()),
+      onState: (state) => states.push(state),
+    });
+
+    await poller.refresh();
+    await poller.refresh();
+    await poller.refresh();
+    await poller.refresh();
+
+    expect(states).toEqual([
+      { paused: true, connected: true },
+      { paused: true, connected: false },
+      { paused: true, connected: false },
+      { paused: true, connected: false },
+    ]);
+  });
+
+  test.each(["success", "error"] as const)(
+    "stop then start immediately polls a new generation and ignores delayed old %s",
+    async (outcome) => {
+      const timers = new Timers();
+      const old = deferred<Response>();
+      const current = deferred<Response>();
+      const requests = [old, current];
+      const states: Array<{ paused: boolean; connected: boolean }> = [];
+      const poller = new BoothStatePoller({
+        event: EVENT,
+        fetch: () => requests.shift()!.promise,
+        onState: (state) => states.push(state),
+        setTimer: timers.set,
+        clearTimer: timers.clear,
+      });
+
+      poller.start();
+      poller.stop();
+      poller.start();
+
+      expect(requests).toHaveLength(0);
+      current.resolve(response(operationalState(false)));
+      await settle();
+      if (outcome === "success") old.resolve(response(operationalState(true)));
+      else old.reject(new TypeError("delayed offline"));
+      await settle();
+
+      expect(states).toEqual([{ paused: false, connected: true }]);
+      expect(timers.delays()).toEqual([5_000]);
+    }
+  );
 });
 
 describe("BoothHeartbeatReporter", () => {
@@ -278,8 +346,83 @@ describe("BoothHeartbeatReporter", () => {
     poller.stop();
 
     expect(signal?.aborted).toBe(true);
-    pending.resolve(response({ version: 1, paused: false, updatedAt: "2026-01-01T00:00:00.000Z" }));
+    pending.resolve(response(operationalState(false)));
     await settle();
     expect(timers.pending).toHaveLength(0);
   });
+
+  test.each(["success", "error"] as const)(
+    "stop then start sends a new generation and ignores delayed old %s",
+    async (outcome) => {
+      const timers = new Timers();
+      const old = deferred<Response>();
+      const current = deferred<Response>();
+      const requests = [old, current];
+      const reporter = new BoothHeartbeatReporter({
+        event: EVENT,
+        boothKey: () => "operator-key",
+        fetch: () => requests.shift()!.promise,
+        setTimer: timers.set,
+        clearTimer: timers.clear,
+      });
+      reporter.update(heartbeat({ pendingCount: 1 }));
+      reporter.start();
+      reporter.stop();
+      reporter.update(heartbeat({ pendingCount: 2 }));
+      reporter.start();
+
+      expect(requests).toHaveLength(0);
+      current.resolve(response({ ok: true }));
+      await settle();
+      if (outcome === "success") old.resolve(response({ ok: true }));
+      else old.reject(new TypeError("delayed offline"));
+      await settle();
+
+      expect(timers.delays()).toEqual([15_000]);
+    }
+  );
+
+  test("a delayed old 401 cannot relock a restarted reporter", async () => {
+    const old = deferred<Response>();
+    const current = deferred<Response>();
+    const requests = [old, current];
+    let authRequired = 0;
+    const reporter = new BoothHeartbeatReporter({
+      event: EVENT,
+      boothKey: () => "operator-key",
+      fetch: () => requests.shift()!.promise,
+      onAuthRequired: () => { authRequired++; },
+    });
+    reporter.update(heartbeat({ pendingCount: 1 }));
+    reporter.start();
+    reporter.stop();
+    reporter.update(heartbeat({ pendingCount: 2 }));
+    reporter.start();
+
+    expect(requests).toHaveLength(0);
+    old.resolve(response({ error: "unauthorized" }, 401));
+    current.resolve(response({ ok: true }));
+    await settle();
+
+    expect(authRequired).toBe(0);
+  });
+});
+
+describe("Booth operational Event reset", () => {
+  test("navigation cannot carry Event A upload or pause state into Event B", () => {
+    const eventA = createBoothOperationalSessionState(100);
+    eventA.lastSuccessfulUploadAt = 150;
+    eventA.operational = { paused: true, connected: true };
+    eventA.cameraErrorClass = "camera-unavailable";
+
+    const eventB = createBoothOperationalSessionState(200);
+
+    expect(eventB).toEqual({
+      sessionStartedAt: 200,
+      lastSuccessfulUploadAt: null,
+      operational: { paused: false, connected: false },
+      cameraErrorClass: null,
+    });
+    expect(eventB).not.toEqual(eventA);
+  });
 });
diff --git a/app/[event]/booth-session/operational-client.ts b/app/[event]/booth-session/operational-client.ts
index c445d49..700c34e 100644
--- a/app/[event]/booth-session/operational-client.ts
+++ b/app/[event]/booth-session/operational-client.ts
@@ -1,4 +1,7 @@
-import type { BoothHeartbeatInput } from "../../booth-control";
+import {
+  parseBoothOperationalState,
+  type BoothHeartbeatInput,
+} from "../../booth-control";
 
 export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
@@ -11,6 +14,24 @@ export type BoothOperationalClientState = {
   connected: boolean;
 };
 
+export type BoothOperationalSessionState = {
+  sessionStartedAt: number;
+  lastSuccessfulUploadAt: number | null;
+  operational: BoothOperationalClientState;
+  cameraErrorClass: "camera-permission" | "camera-unavailable" | null;
+};
+
+export function createBoothOperationalSessionState(
+  sessionStartedAt: number
+): BoothOperationalSessionState {
+  return {
+    sessionStartedAt,
+    lastSuccessfulUploadAt: null,
+    operational: { paused: false, connected: false },
+    cameraErrorClass: null,
+  };
+}
+
 export type BoothStatePollerOptions = {
   event: string;
   fetch?: FetchLike;
@@ -46,6 +67,7 @@ export class BoothStatePoller {
   private started = false;
   private stopped = false;
   private paused = false;
+  private runEpoch = 0;
 
   constructor(private readonly options: BoothStatePollerOptions) {
     this.fetch = options.fetch ?? fetch;
@@ -58,6 +80,8 @@ export class BoothStatePoller {
     if (this.started) return;
     this.started = true;
     this.stopped = false;
+    this.runEpoch++;
+    this.inFlight = null;
     void this.refresh();
   }
 
@@ -67,6 +91,7 @@ export class BoothStatePoller {
 
     const controller = new AbortController();
     this.controller = controller;
+    const epoch = this.runEpoch;
     let work!: Promise<void>;
     work = (async () => {
       try {
@@ -76,15 +101,19 @@ export class BoothStatePoller {
         );
         if (!response.ok) throw new TypeError("Booth state request failed");
         const body: unknown = await response.json();
-        if (!isOperationalState(body)) throw new TypeError("Invalid Booth state response");
-        this.paused = body.paused;
-        if (!this.stopped) this.onState({ paused: this.paused, connected: true });
+        const state = parseBoothOperationalState(body);
+        if (!state) throw new TypeError("Invalid Booth state response");
+        if (!this.isCurrent(epoch)) return;
+        this.paused = state.paused;
+        this.onState({ paused: this.paused, connected: true });
       } catch {
-        if (!this.stopped) this.onState({ paused: this.paused, connected: false });
+        if (this.isCurrent(epoch)) {
+          this.onState({ paused: this.paused, connected: false });
+        }
       } finally {
         if (this.controller === controller) this.controller = null;
         if (this.inFlight === work) this.inFlight = null;
-        if (this.started && !this.stopped) this.schedule();
+        if (this.started && this.isCurrent(epoch)) this.schedule();
       }
     })();
     this.inFlight = work;
@@ -94,11 +123,17 @@ export class BoothStatePoller {
   stop(): void {
     this.started = false;
     this.stopped = true;
+    this.runEpoch++;
     this.controller?.abort();
     this.controller = null;
+    this.inFlight = null;
     this.cancelTimer();
   }
 
+  private isCurrent(epoch: number) {
+    return !this.stopped && epoch === this.runEpoch;
+  }
+
   private schedule() {
     this.cancelTimer();
     this.timer = this.setTimer(() => {
@@ -127,6 +162,7 @@ export class BoothHeartbeatReporter {
   private started = false;
   private stopped = false;
   private dirty = false;
+  private runEpoch = 0;
 
   constructor(private readonly options: BoothHeartbeatReporterOptions) {
     this.fetch = options.fetch ?? fetch;
@@ -139,6 +175,8 @@ export class BoothHeartbeatReporter {
     if (this.started) return;
     this.started = true;
     this.stopped = false;
+    this.runEpoch++;
+    this.inFlight = null;
     void this.flush();
   }
 
@@ -159,6 +197,7 @@ export class BoothHeartbeatReporter {
     this.dirty = false;
     const controller = new AbortController();
     this.controller = controller;
+    const epoch = this.runEpoch;
     let work!: Promise<void>;
     work = (async () => {
       try {
@@ -174,7 +213,7 @@ export class BoothHeartbeatReporter {
             signal: controller.signal,
           }
         );
-        if (response.status === 401) {
+        if (response.status === 401 && this.isCurrent(epoch)) {
           try {
             await this.onAuthRequired();
           } catch {
@@ -186,7 +225,7 @@ export class BoothHeartbeatReporter {
       } finally {
         if (this.controller === controller) this.controller = null;
         if (this.inFlight === work) this.inFlight = null;
-        if (!this.started || this.stopped) return;
+        if (!this.started || !this.isCurrent(epoch)) return;
         if (this.dirty) {
           this.dirty = false;
           void this.flush();
@@ -202,12 +241,18 @@ export class BoothHeartbeatReporter {
   stop(): void {
     this.started = false;
     this.stopped = true;
+    this.runEpoch++;
     this.dirty = false;
     this.controller?.abort();
     this.controller = null;
+    this.inFlight = null;
     this.cancelTimer();
   }
 
+  private isCurrent(epoch: number) {
+    return !this.stopped && epoch === this.runEpoch;
+  }
+
   private schedule() {
     this.cancelTimer();
     this.timer = this.setTimer(() => {
@@ -223,12 +268,6 @@ export class BoothHeartbeatReporter {
   }
 }
 
-function isOperationalState(value: unknown): value is { paused: boolean } {
-  return Boolean(value)
-    && typeof value === "object"
-    && typeof (value as { paused?: unknown }).paused === "boolean";
-}
-
 // Enumerating these fields prevents browser details, arbitrary exception
 // messages, and credentials from entering the private heartbeat payload.
 function copySnapshot(snapshot: BoothHeartbeatInput): BoothHeartbeatInput {
diff --git a/app/[event]/booth-session/pause-boundary.test.ts b/app/[event]/booth-session/pause-boundary.test.ts
new file mode 100644
index 0000000..3d5b3e6
--- /dev/null
+++ b/app/[event]/booth-session/pause-boundary.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { BoothPauseBoundary } from "./pause-boundary";
+
+function harness() {
+  const actions: string[] = [];
+  const boundary = new BoothPauseBoundary({
+    clearFrame: () => actions.push("clear-frame"),
+    stopCamera: () => actions.push("stop-old-tracks"),
+    startCamera: () => actions.push("get-user-media"),
+  });
+  return { actions, boundary };
+}
+
+function pauseThenResumeDuringOperation(boundary: BoothPauseBoundary) {
+  expect(boundary.beginOperation()).toBe(true);
+  boundary.observe(false);
+  boundary.observe(true);
+  boundary.observe(false);
+}
+
+describe("Booth pause boundary", () => {
+  test("framed success enforces the observed stop boundary before a fresh camera", () => {
+    const { actions, boundary } = harness();
+    pauseThenResumeDuringOperation(boundary);
+
+    boundary.completeOperation();
+
+    expect(actions).toEqual(["clear-frame", "stop-old-tracks", "get-user-media"]);
+  });
+
+  test("framed failure/catch enforces the observed stop boundary before a fresh camera", () => {
+    const { actions, boundary } = harness();
+    pauseThenResumeDuringOperation(boundary);
+
+    boundary.completeOperation();
+
+    expect(actions.indexOf("stop-old-tracks")).toBeLessThan(actions.indexOf("get-user-media"));
+    expect(actions).toEqual(["clear-frame", "stop-old-tracks", "get-user-media"]);
+  });
+
+  test("file fallback enforces the observed stop boundary before a fresh camera", () => {
+    const { actions, boundary } = harness();
+    pauseThenResumeDuringOperation(boundary);
+
+    boundary.completeOperation();
+
+    expect(actions).toEqual(["clear-frame", "stop-old-tracks", "get-user-media"]);
+  });
+
+  test("pause at an idle picker clears and stops immediately, then resumes fresh", () => {
+    const { actions, boundary } = harness();
+
+    boundary.observe(true);
+    boundary.observe(false);
+
+    expect(actions).toEqual(["clear-frame", "stop-old-tracks", "get-user-media"]);
+  });
+
+  test("remaining paused after completion clears and stops without restarting", () => {
+    const { actions, boundary } = harness();
+    expect(boundary.beginOperation()).toBe(true);
+    boundary.observe(true);
+
+    boundary.completeOperation();
+
+    expect(actions).toEqual(["clear-frame", "stop-old-tracks"]);
+  });
+
+  test("reset discards an old Event operation without mutating the new Event", () => {
+    const { actions, boundary } = harness();
+    expect(boundary.beginOperation()).toBe(true);
+    boundary.observe(true);
+
+    boundary.reset();
+    boundary.completeOperation();
+
+    expect(actions).toEqual([]);
+  });
+});
diff --git a/app/[event]/booth-session/pause-boundary.ts b/app/[event]/booth-session/pause-boundary.ts
new file mode 100644
index 0000000..c46c1db
--- /dev/null
+++ b/app/[event]/booth-session/pause-boundary.ts
@@ -0,0 +1,60 @@
+export type BoothPauseBoundaryDependencies = {
+  clearFrame: () => void;
+  stopCamera: () => void;
+  startCamera: () => void;
+};
+
+/**
+ * Latches an observed pause until the current capture/handoff reaches a safe
+ * boundary. A quick server resume cannot bypass stopping the old camera first.
+ */
+export class BoothPauseBoundary {
+  private paused = false;
+  private operationActive = false;
+  private boundaryRequired = false;
+
+  constructor(private readonly deps: BoothPauseBoundaryDependencies) {}
+
+  beginOperation(): boolean {
+    if (this.paused || this.operationActive) return false;
+    this.operationActive = true;
+    return true;
+  }
+
+  observe(paused: boolean): void {
+    const wasPaused = this.paused;
+    this.paused = paused;
+
+    if (paused) {
+      if (this.operationActive) {
+        this.boundaryRequired = true;
+        return;
+      }
+      if (!wasPaused) {
+        this.deps.clearFrame();
+        this.deps.stopCamera();
+      }
+      return;
+    }
+
+    if (wasPaused && !this.operationActive) this.deps.startCamera();
+  }
+
+  completeOperation(): boolean {
+    if (!this.operationActive) return false;
+    this.operationActive = false;
+    if (!this.boundaryRequired) return false;
+
+    this.boundaryRequired = false;
+    this.deps.clearFrame();
+    this.deps.stopCamera();
+    if (!this.paused) this.deps.startCamera();
+    return true;
+  }
+
+  reset(): void {
+    this.paused = false;
+    this.operationActive = false;
+    this.boundaryRequired = false;
+  }
+}
diff --git a/app/[event]/booth-unlock.test.tsx b/app/[event]/booth-unlock.test.tsx
index 72e8c31..fbdd6d5 100644
--- a/app/[event]/booth-unlock.test.tsx
+++ b/app/[event]/booth-unlock.test.tsx
@@ -147,24 +147,6 @@ describe("Booth unlock presentation", () => {
 });
 
 describe("Booth operational integration", () => {
-  test("keeps polling, heartbeat, and paused capture boundaries separate from the Outbox", async () => {
-    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
-
-    expect(source).toContain('from "./booth-session/device-identity"');
-    expect(source).toContain('from "./booth-session/operational-client"');
-    expect(source).toContain("loadOrCreateDeviceId(window.localStorage)");
-    expect(source).toContain("new BoothStatePoller");
-    expect(source).toContain("new BoothHeartbeatReporter");
-    expect(source).toContain("operational.paused");
-    expect(source).toContain("pauseAfterCaptureRef");
-    expect(source).toContain("resumeAfterCaptureRef");
-    expect(source).toContain("void session.process()");
-    expect(source).toContain("statePollerRef.current?.stop()");
-    expect(source).toContain("heartbeatReporterRef.current?.stop()");
-    expect(source).toContain('process.env.NEXT_PUBLIC_BUILD_ID ?? "development"');
-    expect(source).not.toContain("navigator.userAgent");
-  });
-
   test("shows pause and connectivity states with touch-safe focus treatment", async () => {
     const css = await Bun.file(`${import.meta.dir}/booth.module.css`).text();
 
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index b28e6c2..0bf0bb2 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -17,9 +17,15 @@ import { loadOrCreateDeviceId } from "./booth-session/device-identity";
 import {
   BoothHeartbeatReporter,
   BoothStatePoller,
+  createBoothOperationalSessionState,
   type BoothOperationalClientState,
 } from "./booth-session/operational-client";
-import type { BoothErrorClass, BoothHeartbeatInput } from "../booth-control";
+import {
+  parseBoothOperationalState,
+  type BoothErrorClass,
+  type BoothHeartbeatInput,
+} from "../booth-control";
+import { BoothPauseBoundary } from "./booth-session/pause-boundary";
 import type { BoothAccessState } from "./booth-session/access";
 import {
   clearBoothCredential,
@@ -27,6 +33,7 @@ import {
   saveBoothCredential,
 } from "./booth-session/credential";
 import {
+  boothPreflightResultFromPayload,
   BoothLifecycleCoordinator,
   type BoothAccessFeedback,
   type BoothCredentialHolder,
@@ -52,13 +59,6 @@ function uploadErrorClass(status: number): UploadErrorClass {
   return "unknown";
 }
 
-function isPreflightOperationalState(value: unknown): value is { version: 1; paused: boolean } {
-  return Boolean(value)
-    && typeof value === "object"
-    && (value as { version?: unknown }).version === 1
-    && typeof (value as { paused?: unknown }).paused === "boolean";
-}
-
 function isInstalled() {
   if (typeof window === "undefined") return false;
   const navigatorWithStandalone = navigator as Navigator & { standalone?: boolean };
@@ -108,18 +108,7 @@ async function requestBoothPreflight(
     return { kind: "unavailable" };
   }
   if (!response.ok) return { kind: "recovery-only" };
-  const payload = await response.json() as {
-    experience?: { frames?: unknown };
-    operationalState?: unknown;
-  };
-  if (!isPreflightOperationalState(payload.operationalState)) {
-    return { kind: "recovery-only" };
-  }
-  return {
-    kind: "ready",
-    frames: payload.experience?.frames,
-    operationalState: payload.operationalState,
-  };
+  return boothPreflightResultFromPayload(await response.json());
 }
 
 export default function Booth() {
@@ -134,8 +123,6 @@ export default function Booth() {
   const unmountedRef = useRef(false);
   const deviceIdRef = useRef("");
   const sessionStartedAtRef = useRef(0);
-  const pauseAfterCaptureRef = useRef(false);
-  const resumeAfterCaptureRef = useRef(false);
   const operationalRef = useRef<OperationalState>({ paused: false, connected: false });
   const uploadStateRef = useRef<UploadState>(INITIAL_UPLOAD_STATE);
   const [status, setStatus] = useState<Status>("starting");
@@ -222,37 +209,30 @@ export default function Booth() {
     if (videoRef.current) videoRef.current.srcObject = null;
   }, []);
 
-  const pauseAtSafeBoundary = useCallback(() => {
+  const clearFrame = useCallback(() => {
     setMode(null);
     setShot(0);
     setCount(0);
     setFlash(false);
     setStatus("picking");
-    stopCamera();
-  }, [stopCamera]);
+  }, []);
+
+  const pauseBoundary = useMemo(
+    () => new BoothPauseBoundary({
+      clearFrame,
+      stopCamera,
+      startCamera: () => {
+        void startCamera();
+      },
+    }),
+    [clearFrame, startCamera, stopCamera]
+  );
 
   const applyOperationalState = useCallback((next: OperationalState) => {
-    const previous = operationalRef.current;
     operationalRef.current = next;
     setOperational(next);
-    if (next.paused) {
-      if (captureRef.current) {
-        pauseAfterCaptureRef.current = true;
-        resumeAfterCaptureRef.current = false;
-        return;
-      }
-      pauseAtSafeBoundary();
-      return;
-    }
-    if (previous.paused) {
-      pauseAfterCaptureRef.current = false;
-      if (captureRef.current) {
-        resumeAfterCaptureRef.current = true;
-        return;
-      }
-      void startCamera();
-    }
-  }, [pauseAtSafeBoundary, startCamera]);
+    pauseBoundary.observe(next.paused);
+  }, [pauseBoundary]);
 
   const lifecycle = useMemo(
     () => new BoothLifecycleCoordinator<UploadResult>({
@@ -270,12 +250,12 @@ export default function Booth() {
           window.localStorage
         ),
       onReset: () => {
-        pauseAfterCaptureRef.current = false;
-        resumeAfterCaptureRef.current = false;
-        operationalRef.current = { paused: false, connected: false };
+        const initial = createBoothOperationalSessionState(Date.now());
+        pauseBoundary.reset();
+        operationalRef.current = initial.operational;
         uploadStateRef.current = INITIAL_UPLOAD_STATE;
         deviceIdRef.current = loadOrCreateDeviceId(window.localStorage);
-        sessionStartedAtRef.current = Date.now();
+        sessionStartedAtRef.current = initial.sessionStartedAt;
         setStatus("starting");
         setMode(null);
         setLastUrl(null);
@@ -285,7 +265,8 @@ export default function Booth() {
         setFlash(false);
         setEnabled(null);
         setOutboxRecovered(false);
-        setCameraErrorClass(null);
+        setLastSuccessfulUploadAt(initial.lastSuccessfulUploadAt);
+        setCameraErrorClass(initial.cameraErrorClass);
         setOperational(operationalRef.current);
         setOnline(navigator.onLine);
         setUploadState(INITIAL_UPLOAD_STATE);
@@ -305,8 +286,9 @@ export default function Booth() {
       },
       onFrames: setEnabled,
       onOperationalState: (value) => {
-        if (isPreflightOperationalState(value)) {
-          applyOperationalState({ paused: value.paused, connected: true });
+        const state = parseBoothOperationalState(value);
+        if (state) {
+          applyOperationalState({ paused: state.paused, connected: true });
         }
       },
       onCameraStart: () => {
@@ -336,6 +318,7 @@ export default function Booth() {
       onCameraStop: () => {
         statePollerRef.current?.stop();
         heartbeatReporterRef.current?.stop();
+        pauseBoundary.reset();
         stopCamera();
       },
       onUploaded: ({ url }) => {
@@ -343,7 +326,7 @@ export default function Booth() {
         setLastSuccessfulUploadAt(Date.now());
       },
     }),
-    [applyOperationalState, startCamera, stopCamera]
+    [applyOperationalState, pauseBoundary, startCamera, stopCamera]
   );
 
   useEffect(() => {
@@ -496,6 +479,7 @@ export default function Booth() {
       || operationalRef.current.paused
       || status !== "ready"
       || !mode
+      || !pauseBoundary.beginOperation()
     ) return;
     const t = TEMPLATES[mode];
     setStatus("running");
@@ -531,17 +515,7 @@ export default function Booth() {
       // Durable handoff is complete. Return to the picker before uploading so
       // the next guest is never trapped on the previous guest's frame.
       setError(null);
-      if (operationalRef.current.paused) {
-        pauseAfterCaptureRef.current = false;
-        pauseAtSafeBoundary();
-      } else {
-        setMode(null);
-        setStatus("picking");
-        if (resumeAfterCaptureRef.current) {
-          resumeAfterCaptureRef.current = false;
-          void startCamera();
-        }
-      }
+      if (!pauseBoundary.completeOperation()) clearFrame();
       // Pause gates new capture only. It never interrupts the ordered Outbox.
       void session.process();
     } catch (e) {
@@ -552,16 +526,9 @@ export default function Booth() {
       setShot(0);
       setCount(0);
       setFlash(false);
-      if (operationalRef.current.paused) {
-        pauseAfterCaptureRef.current = false;
-        pauseAtSafeBoundary();
-      } else {
+      if (!pauseBoundary.completeOperation()) {
         setMode(null);
         setStatus(streamRef.current ? "picking" : "denied");
-        if (resumeAfterCaptureRef.current) {
-          resumeAfterCaptureRef.current = false;
-          void startCamera();
-        }
       }
     } finally {
       if (captureRef.current === controller) captureRef.current = null;
@@ -572,8 +539,8 @@ export default function Booth() {
     mode,
     grabFrame,
     lifecycle,
-    pauseAtSafeBoundary,
-    startCamera,
+    clearFrame,
+    pauseBoundary,
   ]);
 
   // fallback: native file input (camera) when getUserMedia is blocked.
@@ -588,7 +555,7 @@ export default function Booth() {
       }
       const file = e.target.files?.[0];
       e.target.value = "";
-      if (!file) return;
+      if (!file || !pauseBoundary.beginOperation()) return;
       const controller = new AbortController();
       captureRef.current = controller;
       const session = sessionRef.current;
@@ -618,29 +585,17 @@ export default function Booth() {
         });
         if (controller.signal.aborted || !lifecycle.isActive(session)) return;
         setError(null);
-        if (operationalRef.current.paused) {
-          pauseAfterCaptureRef.current = false;
-          pauseAtSafeBoundary();
-        } else if (resumeAfterCaptureRef.current) {
-          resumeAfterCaptureRef.current = false;
-          void startCamera();
-        }
+        pauseBoundary.completeOperation();
         void session.process();
       } catch (uploadError) {
         if (controller.signal.aborted || !session || !lifecycle.isActive(session)) return;
         setError(uploadError instanceof Error ? uploadError.message : String(uploadError));
-        if (operationalRef.current.paused) {
-          pauseAfterCaptureRef.current = false;
-          pauseAtSafeBoundary();
-        } else if (resumeAfterCaptureRef.current) {
-          resumeAfterCaptureRef.current = false;
-          void startCamera();
-        }
+        pauseBoundary.completeOperation();
       } finally {
         if (captureRef.current === controller) captureRef.current = null;
       }
     },
-    [accessState, lifecycle, pauseAtSafeBoundary, startCamera]
+    [accessState, lifecycle, pauseBoundary]
   );
 
   const pick = (m: keyof typeof TEMPLATES) => {

From 74eb5b29117384c7cc367e3f89cbd17dec5a21a5 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:31:13 +0800
Subject: [PATCH 051/105] fix: preserve preflight pause on poll failure

---
 app/[event]/booth-session/lifecycle.test.ts   | 56 ++++++++++++++++++-
 .../booth-session/operational-client.ts       |  2 +
 app/[event]/page.tsx                          |  1 +
 3 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
index 95b9f4f..266afd2 100644
--- a/app/[event]/booth-session/lifecycle.test.ts
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { parseBoothOperationalState } from "../../booth-control";
 import {
   boothPreflightResultFromPayload,
   BoothLifecycleCoordinator,
@@ -9,13 +10,16 @@ import {
 } from "./lifecycle";
 import { MemoryOutboxStore } from "./outbox";
 import { BoothSession } from "./session";
+import { BoothStatePoller } from "./operational-client";
 
 function deferred<T>() {
   let resolve!: (value: T | PromiseLike<T>) => void;
-  const promise = new Promise<T>((next) => {
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((next, fail) => {
     resolve = next;
+    reject = fail;
   });
-  return { promise, resolve };
+  return { promise, resolve, reject };
 }
 
 class FakeSession implements BoothLifecycleSession {
@@ -56,6 +60,8 @@ function harness(options: {
     key: string,
     signal: AbortSignal
   ) => Promise<BoothPreflightResult>;
+  onOperationalState?: (state: unknown) => void;
+  onCameraStart?: () => void;
 } = {}) {
   const events: string[] = [];
   const access: string[] = [];
@@ -78,9 +84,13 @@ function harness(options: {
     onOutboxRecovered: () => events.push("outbox-recovered"),
     onAccess: (state, feedback) => access.push(`${state}:${feedback}`),
     onFrames: (next) => frames.push(next),
-    onOperationalState: (state) => operational.push(state),
+    onOperationalState: (state) => {
+      operational.push(state);
+      options.onOperationalState?.(state);
+    },
     onCameraStart: () => {
       cameraStarts++;
+      options.onCameraStart?.();
     },
     onCameraStop: () => {
       cameraStops++;
@@ -517,4 +527,44 @@ describe("preflight operational-state validation", () => {
     expect(session.actions).not.toContain("start");
     expect(h.cameraStarts()).toBe(0);
   });
+
+  test.each(["failed", "malformed"] as const)(
+    "paused preflight remains paused when the immediate first poll is %s",
+    async (outcome) => {
+      const firstPoll = deferred<Response>();
+      const polledStates: Array<{ paused: boolean; connected: boolean }> = [];
+      let preflightPaused = false;
+      const poller = new BoothStatePoller({
+        event: "launch",
+        initialPaused: () => preflightPaused,
+        fetch: () => firstPoll.promise,
+        onState: (state) => polledStates.push(state),
+      });
+      const h = harness({
+        stored: { launch: "stored-key" },
+        preflight: async () => boothPreflightResultFromPayload({
+          experience: { frames: ["square"] },
+          operationalState: validState,
+        }),
+        onOperationalState: (value) => {
+          const state = parseBoothOperationalState(value);
+          if (!state) throw new Error("expected strict preflight state");
+          preflightPaused = state.paused;
+        },
+        onCameraStart: () => poller.start(),
+      });
+
+      await h.coordinator.beginEvent("launch", new FakeSession(), credential());
+      const completion = poller.refresh();
+      if (outcome === "failed") {
+        firstPoll.reject(new TypeError("offline"));
+      } else {
+        firstPoll.resolve(new Response(JSON.stringify({ paused: false })));
+      }
+      await completion;
+      poller.stop();
+
+      expect(polledStates).toEqual([{ paused: true, connected: false }]);
+    }
+  );
 });
diff --git a/app/[event]/booth-session/operational-client.ts b/app/[event]/booth-session/operational-client.ts
index 700c34e..fac8303 100644
--- a/app/[event]/booth-session/operational-client.ts
+++ b/app/[event]/booth-session/operational-client.ts
@@ -34,6 +34,7 @@ export function createBoothOperationalSessionState(
 
 export type BoothStatePollerOptions = {
   event: string;
+  initialPaused?: () => boolean;
   fetch?: FetchLike;
   onState?: (state: BoothOperationalClientState) => void;
   setTimer?: SetTimer;
@@ -78,6 +79,7 @@ export class BoothStatePoller {
 
   start(): void {
     if (this.started) return;
+    this.paused = this.options.initialPaused?.() ?? this.paused;
     this.started = true;
     this.stopped = false;
     this.runEpoch++;
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 0bf0bb2..b2a81b3 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -386,6 +386,7 @@ export default function Booth() {
     sessionRef.current = session;
     const poller = new BoothStatePoller({
       event,
+      initialPaused: () => operationalRef.current.paused,
       onState: applyOperationalState,
     });
     statePollerRef.current = poller;

From 18ec4074a570182a6d50291b0b01be85949474b4 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:39:20 +0800
Subject: [PATCH 052/105] fix: preserve exact auth recovery across heartbeat

---
 app/[event]/booth-session/lifecycle.test.ts | 19 +++++++++++++++++++
 app/[event]/booth-session/lifecycle.ts      |  4 ++--
 app/[event]/page.tsx                        |  2 +-
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
index 266afd2..e1f84d4 100644
--- a/app/[event]/booth-session/lifecycle.test.ts
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -342,6 +342,25 @@ describe("Booth lifecycle coordination", () => {
     ]);
   });
 
+  test("credential-only rejection preserves the exact Outbox auth item for resume", async () => {
+    const stopping = deferred<void>();
+    const session = new FakeSession();
+    session.stopWork = stopping.promise;
+    const h = harness({ stored: { launch: "initial-key" } });
+    await h.coordinator.beginEvent("launch", session, credential());
+
+    void h.coordinator.authRequired(session, "auth-photo");
+    void h.coordinator.authRequired(session);
+    const unlocking = h.coordinator.unlock("replacement-key");
+    await Promise.resolve();
+    expect(session.actions).not.toContain("resume-auth:auth-photo");
+
+    stopping.resolve();
+    await unlocking;
+
+    expect(session.actions.at(-1)).toBe("resume-auth:auth-photo");
+  });
+
   test("fresh-page recovery resumes a persisted auth oldest item and drains FIFO", async () => {
     const store = new MemoryOutboxStore();
     await store.put({
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
index 9a93fca..03eff96 100644
--- a/app/[event]/booth-session/lifecycle.ts
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -169,10 +169,10 @@ export class BoothLifecycleCoordinator<Result> {
     return this.checkCredential(active, active.key);
   }
 
-  authRequired(session: BoothLifecycleSession, itemId: string) {
+  authRequired(session: BoothLifecycleSession, itemId?: string) {
     const active = this.active;
     if (!active || active.session !== session) return Promise.resolve();
-    active.authBlockedItemId = itemId;
+    if (itemId !== undefined) active.authBlockedItemId = itemId;
     return this.relock(active);
   }
 
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index b2a81b3..28d83f2 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -393,7 +393,7 @@ export default function Booth() {
     const reporter = new BoothHeartbeatReporter({
       event,
       boothKey: () => credential.key,
-      onAuthRequired: () => lifecycle.authRequired(session, ""),
+      onAuthRequired: () => lifecycle.authRequired(session),
     });
     heartbeatReporterRef.current = reporter;
     const entering = lifecycle.beginEvent(event, session, credential);

From e431c267234b83b8e806ee774ef1ae600f84a87b Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:43:43 +0800
Subject: [PATCH 053/105] fix: stop booth controllers on event cleanup

---
 .../booth-session/operational-client.test.ts  | 77 +++++++++++++++++++
 .../booth-session/operational-client.ts       |  8 ++
 app/[event]/page.tsx                          |  2 +
 3 files changed, 87 insertions(+)

diff --git a/app/[event]/booth-session/operational-client.test.ts b/app/[event]/booth-session/operational-client.test.ts
index 17da1ea..6945567 100644
--- a/app/[event]/booth-session/operational-client.test.ts
+++ b/app/[event]/booth-session/operational-client.test.ts
@@ -4,6 +4,7 @@ import {
   BoothHeartbeatReporter,
   BoothStatePoller,
   createBoothOperationalSessionState,
+  stopBoothOperationalClients,
   type FetchLike,
 } from "./operational-client";
 
@@ -425,4 +426,80 @@ describe("Booth operational Event reset", () => {
     });
     expect(eventB).not.toEqual(eventA);
   });
+
+  test("navigation stops captured Event A controllers before callbacks can update Event B", async () => {
+    const oldPoll = deferred<Response>();
+    const oldHeartbeat = deferred<Response>();
+    const oldPollTimers = new Timers();
+    const oldHeartbeatTimers = new Timers();
+    let oldPollSignal: AbortSignal | undefined;
+    let oldHeartbeatSignal: AbortSignal | undefined;
+    let visibleEvent = "event-a";
+    const stateUpdates: Array<{ event: string; paused: boolean; connected: boolean }> = [];
+    const relocks: string[] = [];
+    const onState = (state: { paused: boolean; connected: boolean }) => {
+      stateUpdates.push({ event: visibleEvent, ...state });
+    };
+    const onAuthRequired = () => {
+      relocks.push(visibleEvent);
+    };
+    const oldPoller = new BoothStatePoller({
+      event: "event-a",
+      fetch: (_input, init) => {
+        oldPollSignal = init?.signal ?? undefined;
+        return oldPoll.promise;
+      },
+      onState,
+      setTimer: oldPollTimers.set,
+      clearTimer: oldPollTimers.clear,
+    });
+    const oldReporter = new BoothHeartbeatReporter({
+      event: "event-a",
+      boothKey: () => "event-a-key",
+      fetch: (_input, init) => {
+        oldHeartbeatSignal = init?.signal ?? undefined;
+        return oldHeartbeat.promise;
+      },
+      onAuthRequired,
+      setTimer: oldHeartbeatTimers.set,
+      clearTimer: oldHeartbeatTimers.clear,
+    });
+    oldReporter.update(heartbeat());
+    oldPoller.start();
+    oldReporter.start();
+
+    stopBoothOperationalClients(oldPoller, oldReporter);
+
+    visibleEvent = "event-b";
+    const eventBPoller = new BoothStatePoller({
+      event: "event-b",
+      fetch: async () => response(operationalState(false)),
+      onState,
+    });
+    const eventBReporter = new BoothHeartbeatReporter({
+      event: "event-b",
+      boothKey: () => "event-b-key",
+      fetch: async () => response({ ok: true }),
+      onAuthRequired,
+    });
+    eventBReporter.update(heartbeat({ sessionStartedAt: 200 }));
+    eventBPoller.start();
+    eventBReporter.start();
+    await settle();
+
+    oldPoll.resolve(response(operationalState(true)));
+    oldHeartbeat.resolve(response({ error: "unauthorized" }, 401));
+    await settle();
+    eventBPoller.stop();
+    eventBReporter.stop();
+
+    expect(stateUpdates).toEqual([
+      { event: "event-b", paused: false, connected: true },
+    ]);
+    expect(relocks).toEqual([]);
+    expect(oldPollSignal?.aborted).toBe(true);
+    expect(oldHeartbeatSignal?.aborted).toBe(true);
+    expect(oldPollTimers.pending).toHaveLength(0);
+    expect(oldHeartbeatTimers.pending).toHaveLength(0);
+  });
 });
diff --git a/app/[event]/booth-session/operational-client.ts b/app/[event]/booth-session/operational-client.ts
index fac8303..678bfb7 100644
--- a/app/[event]/booth-session/operational-client.ts
+++ b/app/[event]/booth-session/operational-client.ts
@@ -270,6 +270,14 @@ export class BoothHeartbeatReporter {
   }
 }
 
+export function stopBoothOperationalClients(
+  poller: BoothStatePoller,
+  reporter: BoothHeartbeatReporter
+): void {
+  poller.stop();
+  reporter.stop();
+}
+
 // Enumerating these fields prevents browser details, arbitrary exception
 // messages, and credentials from entering the private heartbeat payload.
 function copySnapshot(snapshot: BoothHeartbeatInput): BoothHeartbeatInput {
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 28d83f2..61b0d2f 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -18,6 +18,7 @@ import {
   BoothHeartbeatReporter,
   BoothStatePoller,
   createBoothOperationalSessionState,
+  stopBoothOperationalClients,
   type BoothOperationalClientState,
 } from "./booth-session/operational-client";
 import {
@@ -420,6 +421,7 @@ export default function Booth() {
       window.removeEventListener("offline", reconsiderConnectivity);
       document.removeEventListener("visibilitychange", reconsiderForeground);
       if (sessionRef.current === session) sessionRef.current = null;
+      stopBoothOperationalClients(poller, reporter);
       if (statePollerRef.current === poller) statePollerRef.current = null;
       if (heartbeatReporterRef.current === reporter) heartbeatReporterRef.current = null;
       void lifecycle.leaveEvent(session);

From e69a1a06ba7dbf202a15876b26f58f6a22f5ca30 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:33:22 +0800
Subject: [PATCH 054/105] feat: configure localized guest capture

---
 .../admin/admin-config-controls.test.tsx      |  53 ++++++
 app/[event]/admin/admin-config-controls.tsx   | 112 +++++++++++
 app/[event]/admin/admin.module.css            |  23 ++-
 .../admin/config-history-panel.test.tsx       |  52 +++++
 app/[event]/admin/config-history-panel.tsx    |  47 ++++-
 app/[event]/admin/config-mutation.test.ts     |  77 ++++++++
 app/[event]/admin/config-mutation.ts          |  80 +++++++-
 app/[event]/admin/page.tsx                    | 137 ++++++++++++--
 app/api/config/handlers.test.ts               |  88 +++++++++
 app/api/config/handlers.ts                    | 178 ++++++++++++++++--
 app/event-config.test.ts                      |  13 ++
 app/frame-packs/catalog.ts                    |   9 +
 app/frame-packs/types.ts                      |   3 +
 app/frame-packs/validate.test.ts              |  70 ++++++-
 app/frame-packs/validate.ts                   |  21 +++
 app/i18n/catalog.test.ts                      |  63 +++++++
 app/i18n/catalog.ts                           | 123 ++++++++++++
 app/i18n/locale.test.ts                       |  75 ++++++++
 app/i18n/locale.ts                            |  75 ++++++++
 19 files changed, 1265 insertions(+), 34 deletions(-)
 create mode 100644 app/i18n/catalog.test.ts
 create mode 100644 app/i18n/catalog.ts
 create mode 100644 app/i18n/locale.test.ts
 create mode 100644 app/i18n/locale.ts

diff --git a/app/[event]/admin/admin-config-controls.test.tsx b/app/[event]/admin/admin-config-controls.test.tsx
index 17fab6d..0bcf196 100644
--- a/app/[event]/admin/admin-config-controls.test.tsx
+++ b/app/[event]/admin/admin-config-controls.test.tsx
@@ -3,6 +3,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { GROUPS, TEMPLATES } from "../../templates";
 import {
   BoothKeyControls,
+  CaptureExperienceControls,
   FrameProgrammeControls,
   SaveConfigurationButton,
 } from "./admin-config-controls";
@@ -54,3 +55,55 @@ test("Save is disabled while a configuration mutation is busy", () => {
   expect(html).toContain("disabled");
   expect(html).toContain(">Save configuration</button>");
 });
+
+test("capture experience controls expose supported locales and plain capture settings", () => {
+  const html = renderToStaticMarkup(
+    <CaptureExperienceControls
+      enabledLocales={new Set(["en", "ar"])}
+      defaultLocale="ar"
+      reviewEnabled
+      autoAcceptSeconds={5}
+      countdownAudioDefault={false}
+      disabled={false}
+      onToggleLocale={() => {}}
+      onDefaultLocaleChange={() => {}}
+      onReviewEnabledChange={() => {}}
+      onAutoAcceptSecondsChange={() => {}}
+      onCountdownAudioDefaultChange={() => {}}
+    />
+  );
+
+  expect(html).toContain("Enabled guest languages");
+  expect(html).toContain("English");
+  expect(html).toContain("简体中文");
+  expect(html).toContain("العربية");
+  expect(html).toContain('dir="rtl"');
+  expect(html).toContain("Default guest language");
+  expect(html).toContain("Show photo review");
+  expect(html).toContain("Auto-accept after");
+  expect(html).toContain("Countdown sounds on by default");
+  expect(html).toContain('min="1"');
+  expect(html).toContain('max="30"');
+});
+
+test("configuration mutation guard disables every locale and capture control", () => {
+  const html = renderToStaticMarkup(
+    <CaptureExperienceControls
+      enabledLocales={new Set(["en"])}
+      defaultLocale="en"
+      reviewEnabled
+      autoAcceptSeconds={5}
+      countdownAudioDefault={false}
+      disabled
+      onToggleLocale={() => {}}
+      onDefaultLocaleChange={() => {}}
+      onReviewEnabledChange={() => {}}
+      onAutoAcceptSecondsChange={() => {}}
+      onCountdownAudioDefaultChange={() => {}}
+    />
+  );
+
+  const controls = html.match(/<(?:input|select)\b/g) ?? [];
+  expect(controls).toHaveLength(7);
+  expect((html.match(/disabled=""/g) ?? [])).toHaveLength(controls.length);
+});
diff --git a/app/[event]/admin/admin-config-controls.tsx b/app/[event]/admin/admin-config-controls.tsx
index e250c8f..a920f59 100644
--- a/app/[event]/admin/admin-config-controls.tsx
+++ b/app/[event]/admin/admin-config-controls.tsx
@@ -2,6 +2,10 @@
 
 import { GROUPS, TEMPLATES } from "../../templates";
 import type { Template } from "../../frame-packs/types";
+import {
+  SUPPORTED_LOCALES,
+  type SupportedLocale,
+} from "../../i18n/catalog";
 import styles from "./admin.module.css";
 
 type FrameProgrammeControlsProps = {
@@ -24,6 +28,26 @@ type BoothKeyControlsProps = {
   onClear: () => void;
 };
 
+type CaptureExperienceControlsProps = {
+  enabledLocales: ReadonlySet<SupportedLocale>;
+  defaultLocale: SupportedLocale;
+  reviewEnabled: boolean;
+  autoAcceptSeconds: number;
+  countdownAudioDefault: boolean;
+  disabled: boolean;
+  onToggleLocale: (locale: SupportedLocale) => void;
+  onDefaultLocaleChange: (locale: SupportedLocale) => void;
+  onReviewEnabledChange: (enabled: boolean) => void;
+  onAutoAcceptSecondsChange: (seconds: number) => void;
+  onCountdownAudioDefaultChange: (enabled: boolean) => void;
+};
+
+const localeNames: Record<SupportedLocale, string> = {
+  en: "English",
+  "zh-SG": "简体中文",
+  ar: "العربية",
+};
+
 function FramePreview({ frame }: { frame: Template }) {
   return (
     <span className={styles.framePreview} style={{ aspectRatio: `${frame.canvas.w}/${frame.canvas.h}`, backgroundColor: frame.background || "#d8d5cc" }}>
@@ -169,6 +193,94 @@ export function BoothKeyControls({
   );
 }
 
+export function CaptureExperienceControls({
+  enabledLocales,
+  defaultLocale,
+  reviewEnabled,
+  autoAcceptSeconds,
+  countdownAudioDefault,
+  disabled,
+  onToggleLocale,
+  onDefaultLocaleChange,
+  onReviewEnabledChange,
+  onAutoAcceptSecondsChange,
+  onCountdownAudioDefaultChange,
+}: CaptureExperienceControlsProps) {
+  return (
+    <div className={styles.experienceControls}>
+      <fieldset>
+        <legend>Enabled guest languages</legend>
+        <div className={styles.localeOptions}>
+          {SUPPORTED_LOCALES.map((locale) => (
+            <label key={locale}>
+              <input
+                type="checkbox"
+                checked={enabledLocales.has(locale)}
+                disabled={disabled}
+                onChange={() => onToggleLocale(locale)}
+              />
+              <span lang={locale} dir={locale === "ar" ? "rtl" : "ltr"}>
+                {localeNames[locale]}
+              </span>
+            </label>
+          ))}
+        </div>
+      </fieldset>
+
+      <label className={styles.experienceField}>
+        <span>Default guest language</span>
+        <select
+          value={defaultLocale}
+          disabled={disabled}
+          onChange={(event) => onDefaultLocaleChange(event.target.value as SupportedLocale)}
+        >
+          {SUPPORTED_LOCALES.filter((locale) => enabledLocales.has(locale)).map((locale) => (
+            <option key={locale} value={locale} lang={locale} dir={locale === "ar" ? "rtl" : "ltr"}>
+              {localeNames[locale]}
+            </option>
+          ))}
+        </select>
+      </label>
+
+      <label className={styles.experienceToggle}>
+        <input
+          type="checkbox"
+          checked={reviewEnabled}
+          disabled={disabled}
+          onChange={(event) => onReviewEnabledChange(event.target.checked)}
+        />
+        <span>Show photo review</span>
+      </label>
+
+      <label className={styles.experienceField}>
+        <span>Auto-accept after</span>
+        <span className={styles.secondsInput}>
+          <input
+            type="number"
+            min={1}
+            max={30}
+            step={1}
+            value={autoAcceptSeconds}
+            disabled={disabled}
+            onChange={(event) => onAutoAcceptSecondsChange(Number(event.target.value))}
+          />
+          <span>seconds</span>
+        </span>
+      </label>
+
+      <label className={styles.experienceToggle}>
+        <input
+          type="checkbox"
+          checked={countdownAudioDefault}
+          disabled={disabled}
+          onChange={(event) => onCountdownAudioDefaultChange(event.target.checked)}
+        />
+        <span>Countdown sounds on by default</span>
+      </label>
+    </div>
+  );
+}
+
 export function SaveConfigurationButton({
   disabled,
   saving,
diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index f7d48fb..2c56b7f 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -25,6 +25,24 @@
 .frameGroups { display: flex; flex-direction: column; gap: 25px; padding-top: 20px; }.groupHead { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }.groupHead h3 { font: 900 14px/1 ui-monospace, monospace; text-transform: uppercase; }.filmRail { display: grid; grid-template-columns: repeat(auto-fill, minmax(145px, 1fr)); gap: 8px; }
 .frameCard { position: relative; display: flex; flex-direction: column; min-width: 0; padding: 8px; border: 2px solid #b7b2a8; background: #e3dfd5; cursor: pointer; }.frameCard[data-enabled="true"] { border-color: var(--ink); background: #fff; box-shadow: inset 0 -6px var(--pink); }.frameCard[data-disabled="true"] { cursor: wait; opacity: .62; }.frameCard input { position: absolute; opacity: 0; }.frameCard:focus-within { outline: 4px solid var(--amber); outline-offset: 2px; }
 .framePreview { position: relative; display: block; width: 100%; max-height: 220px; overflow: hidden; isolation: isolate; }.frameLayer, .overlayLayer { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: fill; }.frameLayer { z-index: 1; }.photoSlot { position: absolute; z-index: 2; background: linear-gradient(135deg, #53504d 0 35%, #d8d0c2 35% 55%, #79736d 55%); box-shadow: inset 0 0 0 1px rgba(255,255,255,.4); }.overlayLayer { z-index: 3; }.frameMeta { display: flex; flex-direction: column; gap: 3px; padding: 9px 0 5px; }.frameMeta strong { font: 900 14px/1 system-ui, sans-serif; }.frameMeta small { font: 10px/1.2 ui-monospace, monospace; color: #666159; }.frameCheck { position: absolute; z-index: 4; right: 12px; top: 12px; background: var(--ink); color: #fff; padding: 5px; font: 900 9px/1 ui-monospace, monospace; }
+.experiencePanel { display: grid; grid-template-columns: minmax(180px, .65fr) minmax(0, 1fr); gap: 24px; margin-top: 28px; border-block: 2px solid var(--ink); padding-block: 20px; }
+.experiencePanel > div:first-child > span { color: var(--pink); font: 900 10px/1 ui-monospace, monospace; letter-spacing: .1em; text-transform: uppercase; }
+.experiencePanel h3 { margin-top: 8px; font: 900 28px/.9 Impact, "Arial Narrow", sans-serif; text-transform: uppercase; }
+.experiencePanel p { margin-top: 10px; font-size: 13px; line-height: 1.4; }
+.experienceControls { display: grid; gap: 10px; }
+.experienceControls fieldset { min-width: 0; border: 0; padding: 0; }
+.experienceControls legend, .experienceField > span:first-child { display: block; margin-bottom: 7px; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .06em; text-transform: uppercase; }
+.localeOptions { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px; }
+.localeOptions label, .experienceToggle { display: flex; min-height: 44px; align-items: center; gap: 9px; border: 1px solid var(--ink); padding: 8px 10px; background: #fff; cursor: pointer; }
+.localeOptions label:has(input:checked), .experienceToggle:has(input:checked) { box-shadow: inset 5px 0 var(--green); }
+.localeOptions input, .experienceToggle input { inline-size: 20px; block-size: 20px; flex: 0 0 auto; accent-color: var(--pink); }
+.localeOptions span[dir="rtl"] { direction: rtl; unicode-bidi: isolate; }
+.experienceField { display: grid; grid-template-columns: minmax(145px, .7fr) minmax(0, 1fr); align-items: center; gap: 12px; }
+.experienceField > span:first-child { margin: 0; }
+.experienceField select, .secondsInput input { min-height: 44px; width: 100%; border: 1px solid var(--ink); padding: 9px 10px; color: var(--ink); background: #fff; font: 700 13px/1 system-ui, sans-serif; }
+.secondsInput { display: grid; grid-template-columns: minmax(80px, 120px) auto; align-items: center; gap: 8px; }
+.secondsInput > span { font: 700 12px/1 system-ui, sans-serif; }
+.experienceControls :disabled { cursor: wait; opacity: .58; }
 .historySection { min-width: 0; }
 .historyLoading { margin-top: 15px; padding: 28px; color: var(--paper); background: var(--ink); font: 800 12px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; }
 .revisionRail { position: relative; display: flex; flex-direction: row; gap: 8px; margin-top: 15px; padding: 22px 12px; overflow-x: auto; overflow-y: hidden; overscroll-behavior-inline: contain; list-style: none; background: var(--ink); background-image: repeating-linear-gradient(90deg, var(--paper) 0 12px, transparent 12px 22px), repeating-linear-gradient(90deg, var(--paper) 0 12px, transparent 12px 22px); background-position: top 6px left 12px, bottom 6px left 12px; background-repeat: repeat-x; background-size: auto 6px; scroll-padding-inline: 12px; scroll-snap-type: x proximity; scrollbar-color: var(--amber) var(--ink); -webkit-overflow-scrolling: touch; }
@@ -59,8 +77,9 @@
 .failure, .emptySheet { padding: 28px; margin-top: 15px; border: 2px dashed #8c8880; background: rgba(255,255,255,.5); }.failure strong, .emptySheet strong { font: 900 22px/1 Impact, sans-serif; text-transform: uppercase; }.failure p, .emptySheet p { margin: 8px 0 14px; font-size: 13px; }.failure button { background: var(--amber); }
 .boothOperations { border-block: 2px solid var(--ink); padding-block: 18px; }.boothOperationsHead { display: flex; align-items: flex-end; justify-content: space-between; gap: 18px; }.boothOperationsHead h2 { margin-top: 8px; font: 900 clamp(30px, 4vw, 52px)/.9 Impact, "Arial Narrow", sans-serif; letter-spacing: -.02em; text-transform: uppercase; }.boothOperationsHead p { max-width: 52ch; margin-top: 8px; font-size: 13px; line-height: 1.4; }.boothControlState { flex: 0 0 auto; border: 2px solid var(--ink); padding: 10px 12px; color: var(--ink); background: var(--green); text-align: end; }.boothControlState[data-paused="true"] { color: #fff; background: #be124e; }.boothControlState span { display: block; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlState strong { display: block; margin-top: 4px; font: 900 19px/1 "Arial Narrow", Arial, sans-serif; text-transform: uppercase; }.boothControlBar { display: grid; grid-template-columns: minmax(0, 1fr) auto; column-gap: 12px; row-gap: 7px; margin-top: 18px; padding: 13px; color: #fff; background: var(--ink); }.boothControlBar label { grid-column: 1 / -1; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlBar textarea { min-height: 44px; width: 100%; resize: vertical; border: 1px solid #777; padding: 10px; color: #fff; background: #1a1a19; font: 13px/1.25 system-ui, sans-serif; }.boothActions { display: flex; align-items: stretch; gap: 7px; }.boothActions button, .boothLoadMore { min-height: 44px; border: 1px solid #777; padding: 10px 12px; color: #fff; background: transparent; font: 800 11px/1.1 system-ui, sans-serif; cursor: pointer; }.boothActions .boothPauseButton { border-color: var(--pink); color: var(--ink); background: var(--pink); }.boothActions button:disabled, .boothLoadMore:disabled, .boothControlBar textarea:disabled { cursor: wait; opacity: .58; }.boothStatusError { margin-top: 9px; border-inline-start: 5px solid #be124e; padding: 10px 12px; color: #8f1239; background: #ffe4e6; font: 800 12px/1.3 system-ui, sans-serif; }.boothRoster { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 295px), 1fr)); gap: 9px; margin: 14px 0 0; padding: 0; list-style: none; }.boothRow { min-width: 0; border: 2px solid var(--ink); padding: 11px; background: #fff; }.boothRow[data-stale="true"] { border-color: #be124e; background: #fff1f2; }.boothRowHead { display: flex; align-items: center; justify-content: space-between; gap: 9px; padding-bottom: 9px; border-bottom: 1px solid var(--ink); }.boothRowHead > code { min-width: 0; overflow: hidden; font: 800 13px/1 ui-monospace, monospace; text-overflow: ellipsis; white-space: nowrap; }.boothPresence { flex: 0 0 auto; padding: 4px 6px; color: #fff; background: #be124e; font: 900 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothPresence[data-live="true"] { color: var(--ink); background: var(--green); }.boothFacts { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 9px 12px; margin-top: 10px; }.boothFacts div { min-width: 0; }.boothFacts dt { color: #635f57; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .06em; text-transform: uppercase; }.boothFacts dd { overflow: hidden; margin-top: 3px; font: 800 12px/1.2 system-ui, sans-serif; text-overflow: ellipsis; white-space: nowrap; }.boothFacts dd code { font: 800 11px/1.2 ui-monospace, monospace; }.boothEmpty { margin-top: 14px; border: 2px dashed #8c8880; padding: 20px; background: rgba(255,255,255,.5); }.boothEmpty strong { font: 900 20px/1 Impact, sans-serif; text-transform: uppercase; }.boothEmpty p { margin-top: 7px; font-size: 13px; }.boothLoadMore { display: block; width: 100%; margin-top: 9px; border-color: var(--ink); color: var(--ink); background: var(--amber); }
 .authPage { display: grid; place-items: center; padding: 20px; background: var(--ink); color: #fff; }.authCard { width: min(500px, 100%); border-top: 8px solid var(--pink); padding: clamp(25px, 5vw, 55px); background: #1a1a19; }.authCard h1 { margin: 25px 0; font: 900 clamp(58px, 10vw, 90px)/.78 Impact, sans-serif; text-transform: uppercase; }.authCard > p:not(.kicker) { color: #bbb; line-height: 1.4; margin-bottom: 28px; }.authCard label { display: block; margin-bottom: 8px; font: 800 11px/1 ui-monospace, monospace; text-transform: uppercase; }.authCard input { width: 100%; padding: 14px; border: 1px solid #777; background: #080808; color: #fff; font: 16px/1 ui-monospace, monospace; }.authCard button { width: 100%; margin-top: 10px; padding: 15px; border: 0; color: #fff; background: var(--pink); font-weight: 900; cursor: pointer; }
-.console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
-@media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; } }
+.console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
+@media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; }.localeOptions label:has(input:checked), .experienceToggle:has(input:checked) { border: 2px solid Highlight; box-shadow: none; } }
 @media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; }.boothOperationsHead { align-items: start; flex-direction: column; }.boothControlState { text-align: start; } }
 @media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; }.boothControlBar { grid-template-columns: 1fr; }.boothActions { display: grid; grid-template-columns: 1fr 1fr; }.boothRoster { grid-template-columns: 1fr; } }
+@media (max-width: 600px) { .experiencePanel { grid-template-columns: 1fr; }.localeOptions { grid-template-columns: 1fr; }.experienceField { grid-template-columns: 1fr; gap: 6px; } }
 @media (prefers-reduced-motion: reduce) { .console *, .console *::before, .console *::after, .authPage *, .authPage *::before, .authPage *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; } }
diff --git a/app/[event]/admin/config-history-panel.test.tsx b/app/[event]/admin/config-history-panel.test.tsx
index bd9cf6c..eae0ca4 100644
--- a/app/[event]/admin/config-history-panel.test.tsx
+++ b/app/[event]/admin/config-history-panel.test.tsx
@@ -13,6 +13,7 @@ test("history renders reasons and disables restoring the current revision", () =
   const html = renderToStaticMarkup(
     <ConfigHistoryPanel
       currentFrames={["one"]}
+      currentExperience={{ frames: ["one"], locales: ["en"], defaultLocale: "en" }}
       currentRevisionId="018f0000-0000-7000-8000-000000000030"
       revisions={[{
         version: 1,
@@ -61,6 +62,7 @@ test("the active restore control says exactly Restoring after confirmation close
   const html = renderToStaticMarkup(
     <ConfigHistoryPanel
       currentFrames={["one"]}
+      currentExperience={{ frames: ["one"], locales: ["en"], defaultLocale: "en" }}
       currentRevisionId={revisions[0].id}
       revisions={revisions}
       loading={false}
@@ -81,6 +83,7 @@ test("saving disables every restore control", () => {
   const html = renderToStaticMarkup(
     <ConfigHistoryPanel
       currentFrames={["one"]}
+      currentExperience={{ frames: ["one"], locales: ["en"], defaultLocale: "en" }}
       currentRevisionId={revisions[0].id}
       revisions={revisions}
       loading={false}
@@ -94,3 +97,52 @@ test("saving disables every restore control", () => {
 
   expect((html.match(/disabled=""/g) ?? []).length).toBe(2);
 });
+
+test("history summaries make locale and capture settings visible", () => {
+  const html = renderToStaticMarkup(
+    <ConfigHistoryPanel
+      currentFrames={["one"]}
+      currentExperience={{
+        frames: ["one"],
+        locales: ["en"],
+        defaultLocale: "en",
+        capture: {
+          reviewEnabled: true,
+          autoAcceptSeconds: 5,
+          countdownAudioDefault: false,
+        },
+      }}
+      currentRevisionId={null}
+      revisions={[{
+        version: 1,
+        id: "018f0000-0000-7000-8000-000000000030",
+        createdAt: "2026-07-24T00:00:00.000Z",
+        parentRevisionId: null,
+        reason: "save",
+        config: {
+          frames: ["one"],
+          locales: ["en", "ar"],
+          defaultLocale: "ar",
+          capture: {
+            reviewEnabled: false,
+            autoAcceptSeconds: 9,
+            countdownAudioDefault: true,
+          },
+        },
+      }]}
+      loading={false}
+      restoringRevisionId={null}
+      mutationBusy={false}
+      error=""
+      onReload={() => {}}
+      onRestore={() => {}}
+    />
+  );
+
+  expect(html).toContain("Languages: English, العربية");
+  expect(html).toContain("Default: العربية");
+  expect(html).toContain("Review: off");
+  expect(html).toContain("Auto-accept: 9s");
+  expect(html).toContain("Countdown audio: on");
+  expect(html).toContain('data-experience-changed="true"');
+});
diff --git a/app/[event]/admin/config-history-panel.tsx b/app/[event]/admin/config-history-panel.tsx
index 7708ad9..3fcee86 100644
--- a/app/[event]/admin/config-history-panel.tsx
+++ b/app/[event]/admin/config-history-panel.tsx
@@ -1,11 +1,17 @@
 "use client";
 
 import { useState } from "react";
-import type { ConfigRevision } from "../../event-config";
+import type { ConfigRevision, EventExperience } from "../../event-config";
+import { resolveEnabledLocales } from "../../i18n/locale";
+import {
+  isSupportedLocale,
+  type SupportedLocale,
+} from "../../i18n/catalog";
 import styles from "./admin.module.css";
 
 export type ConfigHistoryPanelProps = {
   currentFrames: readonly string[];
+  currentExperience: EventExperience;
   currentRevisionId: string | null;
   revisions: readonly ConfigRevision[];
   loading: boolean;
@@ -16,6 +22,26 @@ export type ConfigHistoryPanelProps = {
   onRestore: (revisionId: string) => void;
 };
 
+const localeNames: Record<SupportedLocale, string> = {
+  en: "English",
+  "zh-SG": "简体中文",
+  ar: "العربية",
+};
+
+function experienceSettings(experience: EventExperience) {
+  const locales = resolveEnabledLocales(experience.locales);
+  return {
+    locales,
+    defaultLocale:
+      isSupportedLocale(experience.defaultLocale) && locales.includes(experience.defaultLocale)
+        ? experience.defaultLocale
+        : "en",
+    reviewEnabled: experience.capture?.reviewEnabled ?? true,
+    autoAcceptSeconds: experience.capture?.autoAcceptSeconds ?? 5,
+    countdownAudioDefault: experience.capture?.countdownAudioDefault ?? false,
+  };
+}
+
 export function diffFrameKeys(
   current: readonly string[],
   historical: readonly string[]
@@ -35,6 +61,7 @@ const reasonLabel: Record<ConfigRevision["reason"], string> = {
 
 export function ConfigHistoryPanel({
   currentFrames,
+  currentExperience,
   currentRevisionId,
   revisions,
   loading,
@@ -45,12 +72,13 @@ export function ConfigHistoryPanel({
   onRestore,
 }: ConfigHistoryPanelProps) {
   const [confirmRevisionId, setConfirmRevisionId] = useState<string | null>(null);
+  const currentSettings = experienceSettings(currentExperience);
 
   return (
     <section className={styles.historySection} aria-labelledby="configuration-history-title">
       <div className={styles.sectionHead}>
         <div><span>02</span><h2 id="configuration-history-title">Configuration history</h2></div>
-        <p>Review each recorded exposure, or restore an earlier Frame selection.</p>
+        <p>Review each recorded exposure, or restore an earlier guest experience.</p>
       </div>
 
       {error ? (
@@ -73,6 +101,9 @@ export function ConfigHistoryPanel({
             const isRestoring = revision.id === restoringRevisionId;
             const isConfirming = revision.id === confirmRevisionId;
             const frameDiff = diffFrameKeys(currentFrames, revision.config.frames);
+            const settings = experienceSettings(revision.config);
+            const experienceChanged =
+              JSON.stringify(settings) !== JSON.stringify(currentSettings);
             const timestamp = new Date(revision.createdAt);
             const readableTime = timestamp.toLocaleString([], {
               dateStyle: "medium",
@@ -80,7 +111,12 @@ export function ConfigHistoryPanel({
             });
 
             return (
-              <li className={styles.revisionRecord} key={revision.id} data-current={isCurrent}>
+              <li
+                className={styles.revisionRecord}
+                key={revision.id}
+                data-current={isCurrent}
+                data-experience-changed={experienceChanged}
+              >
                 <div className={styles.revisionIndex} aria-hidden="true">
                   <span>R{String(revisions.length - index).padStart(2, "0")}</span>
                 </div>
@@ -98,6 +134,11 @@ export function ConfigHistoryPanel({
                     {!isCurrent && frameDiff.added.length === 0 && frameDiff.removed.length === 0 && (
                       <span data-delta="same">Same Frames</span>
                     )}
+                    <span>Languages: {settings.locales.map((locale) => localeNames[locale]).join(", ")}</span>
+                    <span>Default: {localeNames[settings.defaultLocale]}</span>
+                    <span>Review: {settings.reviewEnabled ? "on" : "off"}</span>
+                    <span>Auto-accept: {settings.autoAcceptSeconds}s</span>
+                    <span>Countdown audio: {settings.countdownAudioDefault ? "on" : "off"}</span>
                   </div>
                 </div>
                 <div className={styles.revisionAction}>
diff --git a/app/[event]/admin/config-mutation.test.ts b/app/[event]/admin/config-mutation.test.ts
index 700ad31..be3b1d2 100644
--- a/app/[event]/admin/config-mutation.test.ts
+++ b/app/[event]/admin/config-mutation.test.ts
@@ -1,5 +1,6 @@
 import { expect, test } from "bun:test";
 import {
+  buildConfigSaveBody,
   clearRestoreRequestAfterReconciliation,
   getOrCreateRestoreRequest,
   rebaseConfigHistory,
@@ -83,9 +84,85 @@ test("a successful history rebase clears an ambiguous Save mutation ID", () => {
   expect(rebased.frames).toEqual(["one"]);
   expect(rebased.hasBoothKey).toBe(true);
   expect(rebased.currentRevisionId).toBe(LATER_BASE);
+  expect(rebased.locales).toEqual(["en"]);
+  expect(rebased.defaultLocale).toBe("en");
+  expect(rebased.reviewEnabled).toBe(true);
+  expect(rebased.autoAcceptSeconds).toBe(5);
+  expect(rebased.countdownAudioDefault).toBe(false);
   expect(pendingSave.current).toBeNull();
 });
 
+test("history rebase restores the complete safe editable experience", () => {
+  const pendingSave = { current: MUTATION_ID as string | null };
+  const gallery = { title: "Launch Night", accentColor: "#ff3366" };
+
+  const rebased = rebaseConfigHistory(
+    {
+      config: {
+        frames: ["one"],
+        hasBoothKey: true,
+        locales: ["zh-SG", "ar"],
+        defaultLocale: "ar",
+        timeZone: "Asia/Singapore",
+        capture: {
+          reviewEnabled: false,
+          autoAcceptSeconds: 12,
+          countdownAudioDefault: true,
+        },
+        gallery,
+      },
+      currentRevisionId: LATER_BASE,
+      revisions: [],
+    },
+    ["fallback"],
+    pendingSave
+  );
+
+  expect(rebased).toMatchObject({
+    frames: ["one"],
+    hasBoothKey: true,
+    locales: ["zh-SG", "ar", "en"],
+    defaultLocale: "ar",
+    timeZone: "Asia/Singapore",
+    reviewEnabled: false,
+    autoAcceptSeconds: 12,
+    countdownAudioDefault: true,
+    gallery,
+  });
+  expect(rebased.gallery).not.toBe(gallery);
+});
+
+test("save input carries the complete safe experience without unchanged Booth credentials", () => {
+  const body = buildConfigSaveBody({
+    frames: ["one"],
+    locales: ["en", "ar"],
+    defaultLocale: "ar",
+    timeZone: "Asia/Singapore",
+    reviewEnabled: false,
+    autoAcceptSeconds: 8,
+    countdownAudioDefault: true,
+    gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    mutationId: MUTATION_ID,
+    baseRevisionId: FIRST_BASE,
+  });
+
+  expect(body).toEqual({
+    frames: ["one"],
+    locales: ["en", "ar"],
+    defaultLocale: "ar",
+    timeZone: "Asia/Singapore",
+    capture: {
+      reviewEnabled: false,
+      autoAcceptSeconds: 8,
+      countdownAudioDefault: true,
+    },
+    gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    mutationId: MUTATION_ID,
+    baseRevisionId: FIRST_BASE,
+  });
+  expect(JSON.stringify(body)).not.toContain("boothKey");
+});
+
 test("a 2xx restore retains its exact tuple until parsing, apply, and history reload finish", async () => {
   const pending = new Map<string, RestoreRequest>();
   const request = getOrCreateRestoreRequest(
diff --git a/app/[event]/admin/config-mutation.ts b/app/[event]/admin/config-mutation.ts
index aaee785..c64a1c3 100644
--- a/app/[event]/admin/config-mutation.ts
+++ b/app/[event]/admin/config-mutation.ts
@@ -1,4 +1,13 @@
-import type { ConfigRevision, PublicEventConfig } from "../../event-config";
+import type {
+  ConfigRevision,
+  EventExperience,
+  PublicEventConfig,
+} from "../../event-config";
+import {
+  isSupportedLocale,
+  type SupportedLocale,
+} from "../../i18n/catalog";
+import { resolveEnabledLocales } from "../../i18n/locale";
 
 export type RestoreRequest = Readonly<{
   revisionId: string;
@@ -12,15 +21,78 @@ export type ConfigHistoryResponse = {
   revisions: ConfigRevision[];
 };
 
+export type EditableEventExperience = {
+  frames: string[];
+  locales: SupportedLocale[];
+  defaultLocale: SupportedLocale;
+  timeZone?: string;
+  reviewEnabled: boolean;
+  autoAcceptSeconds: number;
+  countdownAudioDefault: boolean;
+  gallery?: EventExperience["gallery"];
+};
+
+export type ConfigSaveInput = EditableEventExperience & {
+  mutationId: string;
+  baseRevisionId: string | null;
+  boothKey?: string;
+};
+
+export function editableExperienceFromConfig(
+  config: PublicEventConfig,
+  defaultFrames: readonly string[]
+): EditableEventExperience {
+  const locales = resolveEnabledLocales(config.locales);
+  return {
+    frames: Array.isArray(config.frames) ? [...config.frames] : [...defaultFrames],
+    locales,
+    defaultLocale:
+      isSupportedLocale(config.defaultLocale) && locales.includes(config.defaultLocale)
+        ? config.defaultLocale
+        : "en",
+    ...(config.timeZone ? { timeZone: config.timeZone } : {}),
+    reviewEnabled: config.capture?.reviewEnabled ?? true,
+    autoAcceptSeconds: config.capture?.autoAcceptSeconds ?? 5,
+    countdownAudioDefault: config.capture?.countdownAudioDefault ?? false,
+    ...(config.gallery ? { gallery: { ...config.gallery } } : {}),
+  };
+}
+
+export function buildConfigSaveBody(input: ConfigSaveInput) {
+  return {
+    frames: [...input.frames],
+    locales: [...input.locales],
+    defaultLocale: input.defaultLocale,
+    ...(input.timeZone ? { timeZone: input.timeZone } : {}),
+    capture: {
+      reviewEnabled: input.reviewEnabled,
+      autoAcceptSeconds: input.autoAcceptSeconds,
+      countdownAudioDefault: input.countdownAudioDefault,
+    },
+    ...(input.gallery
+      ? {
+        gallery: {
+          ...(input.gallery.title !== undefined ? { title: input.gallery.title } : {}),
+          ...(input.gallery.accentColor !== undefined
+            ? { accentColor: input.gallery.accentColor }
+            : {}),
+        },
+      }
+      : {}),
+    ...(input.boothKey ? { boothKey: input.boothKey } : {}),
+    mutationId: input.mutationId,
+    baseRevisionId: input.baseRevisionId,
+  };
+}
+
 export function rebaseConfigHistory(
   history: ConfigHistoryResponse,
   defaultFrames: readonly string[],
   pendingSaveMutationId: { current: string | null }
 ) {
+  const experience = editableExperienceFromConfig(history.config, defaultFrames);
   const rebased = {
-    frames: Array.isArray(history.config.frames)
-      ? [...history.config.frames]
-      : [...defaultFrames],
+    ...experience,
     hasBoothKey: Boolean(history.config.hasBoothKey),
     currentRevisionId: history.currentRevisionId,
     revisions: history.revisions,
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index b92aff5..b66712e 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -5,9 +5,11 @@ import { useParams } from "next/navigation";
 import QRCode from "qrcode";
 import { TEMPLATES } from "../../templates";
 import type { ConfigRevision, PublicEventConfig } from "../../event-config";
+import type { SupportedLocale } from "../../i18n/catalog";
 import type { AdminBoothRecord, BoothOperationalState } from "../../booth-control";
 import {
   BoothKeyControls,
+  CaptureExperienceControls,
   FrameProgrammeControls,
   SaveConfigurationButton,
 } from "./admin-config-controls";
@@ -21,7 +23,9 @@ import {
 import { BoothOperationsPanel } from "./booth-operations-panel";
 import { ConfigHistoryPanel } from "./config-history-panel";
 import {
+  buildConfigSaveBody,
   clearRestoreRequestAfterReconciliation,
+  editableExperienceFromConfig,
   getOrCreateRestoreRequest,
   rebaseConfigHistory,
   shouldClearRestoreRequest,
@@ -42,6 +46,13 @@ export default function Admin() {
   const [adminKey, setAdminKey] = useState("");
   const [auth, setAuth] = useState<AuthState>("missing");
   const [frames, setFrames] = useState<Set<string>>(new Set());
+  const [locales, setLocales] = useState<Set<SupportedLocale>>(new Set(["en"]));
+  const [defaultLocale, setDefaultLocale] = useState<SupportedLocale>("en");
+  const [timeZone, setTimeZone] = useState<string | undefined>();
+  const [reviewEnabled, setReviewEnabled] = useState(true);
+  const [autoAcceptSeconds, setAutoAcceptSeconds] = useState(5);
+  const [countdownAudioDefault, setCountdownAudioDefault] = useState(false);
+  const [gallery, setGallery] = useState<PublicEventConfig["gallery"]>();
   const [configLoaded, setConfigLoaded] = useState(false);
   const [configError, setConfigError] = useState("");
   const [currentRevisionId, setCurrentRevisionId] = useState<string | null>(null);
@@ -150,6 +161,13 @@ export default function Admin() {
       }
       const rebased = rebaseConfigHistory(data, defaults, pendingSaveMutationId);
       setFrames(new Set(rebased.frames));
+      setLocales(new Set(rebased.locales));
+      setDefaultLocale(rebased.defaultLocale);
+      setTimeZone(rebased.timeZone);
+      setReviewEnabled(rebased.reviewEnabled);
+      setAutoAcceptSeconds(rebased.autoAcceptSeconds);
+      setCountdownAudioDefault(rebased.countdownAudioDefault);
+      setGallery(rebased.gallery);
       setHasBoothKey(rebased.hasBoothKey);
       setCurrentRevisionId(rebased.currentRevisionId);
       setRevisions(rebased.revisions);
@@ -446,6 +464,53 @@ export default function Admin() {
     });
   };
 
+  const toggleLocale = (locale: SupportedLocale) => {
+    if (configMutationBusy.current) return;
+    clearPendingSave();
+    setLocales((current) => {
+      const next = new Set(current);
+      if (next.has(locale)) {
+        if (next.size === 1) return current;
+        next.delete(locale);
+        if (defaultLocale === locale) {
+          setDefaultLocale(next.values().next().value ?? "en");
+        }
+      } else {
+        next.add(locale);
+      }
+      return next;
+    });
+    setNotice("");
+  };
+
+  const changeDefaultLocale = (locale: SupportedLocale) => {
+    if (configMutationBusy.current || !locales.has(locale)) return;
+    clearPendingSave();
+    setDefaultLocale(locale);
+    setNotice("");
+  };
+
+  const changeReviewEnabled = (enabled: boolean) => {
+    if (configMutationBusy.current) return;
+    clearPendingSave();
+    setReviewEnabled(enabled);
+    setNotice("");
+  };
+
+  const changeAutoAcceptSeconds = (seconds: number) => {
+    if (configMutationBusy.current || !Number.isFinite(seconds)) return;
+    clearPendingSave();
+    setAutoAcceptSeconds(Math.min(30, Math.max(1, Math.round(seconds))));
+    setNotice("");
+  };
+
+  const changeCountdownAudioDefault = (enabled: boolean) => {
+    if (configMutationBusy.current) return;
+    clearPendingSave();
+    setCountdownAudioDefault(enabled);
+    setNotice("");
+  };
+
   const generateBoothKey = () => {
     if (configMutationBusy.current) return;
     clearPendingSave();
@@ -494,12 +559,19 @@ export default function Admin() {
       const response = await fetch(`/api/config?event=${encodeURIComponent(event)}`, {
         method: "PUT",
         headers: { "x-booth-key": adminKey, "content-type": "application/json" },
-        body: JSON.stringify({
+        body: JSON.stringify(buildConfigSaveBody({
           frames: [...frames],
+          locales: [...locales],
+          defaultLocale,
+          ...(timeZone ? { timeZone } : {}),
+          reviewEnabled,
+          autoAcceptSeconds,
+          countdownAudioDefault,
+          ...(gallery ? { gallery } : {}),
           ...(boothKey ? { boothKey } : {}),
           mutationId,
           baseRevisionId: currentRevisionId,
-        }),
+        })),
       });
       if ([400, 401, 409].includes(response.status)) pendingSaveMutationId.current = null;
       if (response.status === 401) { invalidateAuth(); throw new Error("That admin key was rejected."); }
@@ -552,7 +624,15 @@ export default function Admin() {
       if (!response.ok) throw new Error(`Restore failed (${response.status})`);
       await clearRestoreRequestAfterReconciliation(pending, request, async () => {
         const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
-        setFrames(new Set(Array.isArray(data.frames) ? data.frames : defaults));
+        const restored = editableExperienceFromConfig(data, defaults);
+        setFrames(new Set(restored.frames));
+        setLocales(new Set(restored.locales));
+        setDefaultLocale(restored.defaultLocale);
+        setTimeZone(restored.timeZone);
+        setReviewEnabled(restored.reviewEnabled);
+        setAutoAcceptSeconds(restored.autoAcceptSeconds);
+        setCountdownAudioDefault(restored.countdownAudioDefault);
+        setGallery(restored.gallery);
         setHasBoothKey(Boolean(data.hasBoothKey));
         setCurrentRevisionId(data.currentRevisionId);
         setBoothKey("");
@@ -658,18 +738,53 @@ export default function Admin() {
         <div className={styles.mainColumn}>
           <section className={styles.section}>
             <div className={styles.sectionHead}><div><span>01</span><h2>Frame programme</h2></div><p>Choose what guests see at the booth. Previews follow the real background → photo → overlay composition.</p></div>
-            {configError ? <div className={styles.failure}><strong>Config unavailable</strong><p>{configError}</p><button onClick={() => void loadConfig()}>Retry config</button></div> :
-            <FrameProgrammeControls
-              frames={frames}
-              defaults={defaults}
-              disabled={configBusy}
-              onToggle={toggle}
-              onSetGroup={setGroup}
-            />}
+            {configError ? <div className={styles.failure}><strong>Config unavailable</strong><p>{configError}</p><button onClick={() => void loadConfig()}>Retry config</button></div> : (
+              <>
+                <FrameProgrammeControls
+                  frames={frames}
+                  defaults={defaults}
+                  disabled={configBusy}
+                  onToggle={toggle}
+                  onSetGroup={setGroup}
+                />
+                <div className={styles.experiencePanel}>
+                  <div>
+                    <span>Guest capture</span>
+                    <h3>Language &amp; review</h3>
+                    <p>Set the languages guests can choose and the handoff after each exposure.</p>
+                  </div>
+                  <CaptureExperienceControls
+                    enabledLocales={locales}
+                    defaultLocale={defaultLocale}
+                    reviewEnabled={reviewEnabled}
+                    autoAcceptSeconds={autoAcceptSeconds}
+                    countdownAudioDefault={countdownAudioDefault}
+                    disabled={configBusy}
+                    onToggleLocale={toggleLocale}
+                    onDefaultLocaleChange={changeDefaultLocale}
+                    onReviewEnabledChange={changeReviewEnabled}
+                    onAutoAcceptSecondsChange={changeAutoAcceptSeconds}
+                    onCountdownAudioDefaultChange={changeCountdownAudioDefault}
+                  />
+                </div>
+              </>
+            )}
           </section>
 
           <ConfigHistoryPanel
             currentFrames={[...frames]}
+            currentExperience={{
+              frames: [...frames],
+              locales: [...locales],
+              defaultLocale,
+              ...(timeZone ? { timeZone } : {}),
+              capture: {
+                reviewEnabled,
+                autoAcceptSeconds,
+                countdownAudioDefault,
+              },
+              ...(gallery ? { gallery } : {}),
+            }}
             currentRevisionId={currentRevisionId}
             revisions={revisions}
             loading={!configLoaded && !configError}
diff --git a/app/api/config/handlers.test.ts b/app/api/config/handlers.test.ts
index 8e75223..b0d15c3 100644
--- a/app/api/config/handlers.test.ts
+++ b/app/api/config/handlers.test.ts
@@ -207,6 +207,94 @@ describe("config handlers", () => {
     expect(JSON.stringify(history.revisions)).not.toContain("existing-private-hash");
   });
 
+  test("a complete Admin save updates supported locale and capture settings while preserving other safe experience", async () => {
+    const d = deps();
+    await d.deps.store.writeConfig("launch", {
+      frames: ["birthday"],
+      boothKeyHash: "existing-private-hash",
+      locales: ["en"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    });
+
+    const response = await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody({
+        locales: ["en", "zh-SG", "ar"],
+        defaultLocale: "ar",
+        timeZone: "Asia/Singapore",
+        capture: {
+          reviewEnabled: false,
+          autoAcceptSeconds: 9,
+          countdownAudioDefault: true,
+        },
+        gallery: { title: "Launch Night", accentColor: "#ff3366" },
+      })),
+      d.deps
+    );
+    const config = await d.deps.store.readConfig("launch");
+
+    expect(response.status).toBe(200);
+    expect(config).toEqual(expect.objectContaining({
+      frames: ["square"],
+      boothKeyHash: "existing-private-hash",
+      locales: ["en", "zh-SG", "ar"],
+      defaultLocale: "ar",
+      timeZone: "Asia/Singapore",
+      capture: {
+        reviewEnabled: false,
+        autoAcceptSeconds: 9,
+        countdownAudioDefault: true,
+      },
+      gallery: { title: "Launch Night", accentColor: "#ff3366" },
+    }));
+    expect(credentialFields(await response.json())).toEqual([]);
+  });
+
+  test("new saves reject unsupported or inconsistent locale and capture settings", async () => {
+    const invalidExperiences = [
+      { locales: [] },
+      { locales: ["en", "fr"], defaultLocale: "en" },
+      { locales: ["en"], defaultLocale: "ar" },
+      { locales: ["en"], defaultLocale: "en", capture: { reviewEnabled: "yes", autoAcceptSeconds: 5, countdownAudioDefault: false } },
+      { locales: ["en"], defaultLocale: "en", capture: { reviewEnabled: true, autoAcceptSeconds: 0, countdownAudioDefault: false } },
+      { locales: ["en"], defaultLocale: "en", capture: { reviewEnabled: true, autoAcceptSeconds: 31, countdownAudioDefault: false } },
+      { locales: ["en"], defaultLocale: "en", capture: { reviewEnabled: true, autoAcceptSeconds: 2.5, countdownAudioDefault: false } },
+      { locales: ["en"], defaultLocale: "en", capture: { reviewEnabled: true, autoAcceptSeconds: 5, countdownAudioDefault: false, boothKeyHash: "leak" } },
+    ];
+
+    for (const experience of invalidExperiences) {
+      const d = deps();
+      const response = await putConfig(
+        adminRequest("/api/config?event=launch", "PUT", saveBody(experience)),
+        d.deps
+      );
+      expect(response.status).toBe(400);
+      expect(await d.deps.store.readConfig("launch")).toBeNull();
+    }
+  });
+
+  test("complete saves construct only allowlisted safe experience fields", async () => {
+    const d = deps();
+    const response = await putConfig(
+      adminRequest("/api/config?event=launch", "PUT", saveBody({
+        locales: ["en"],
+        defaultLocale: "en",
+        capture: {
+          reviewEnabled: true,
+          autoAcceptSeconds: 5,
+          countdownAudioDefault: false,
+        },
+        boothKeyHash: "injected",
+      })),
+      d.deps
+    );
+
+    expect(response.status).toBe(400);
+    expect(await d.deps.store.readConfig("launch")).toBeNull();
+  });
+
   test("a stale normal Frames save conflicts without discarding preserved experience fields", async () => {
     const d = deps();
     await d.deps.store.writeConfig("launch", {
diff --git a/app/api/config/handlers.ts b/app/api/config/handlers.ts
index 3ee095e..1b705e3 100644
--- a/app/api/config/handlers.ts
+++ b/app/api/config/handlers.ts
@@ -14,10 +14,23 @@ import {
   type EventConfig,
 } from "@/app/event-config";
 import { TEMPLATES } from "@/app/templates";
+import { isSupportedLocale } from "@/app/i18n/catalog";
 import { adminOk } from "@/app/upload-auth";
 
 type SaveBody = {
   frames: string[];
+  locales?: string[];
+  defaultLocale?: string;
+  timeZone?: string;
+  capture?: {
+    reviewEnabled?: boolean;
+    autoAcceptSeconds?: number;
+    countdownAudioDefault?: boolean;
+  };
+  gallery?: {
+    title?: string;
+    accentColor?: string;
+  };
   boothKey?: string;
   mutationId: string;
   baseRevisionId: string | null;
@@ -92,6 +105,11 @@ function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[])
 function parseSaveBody(value: unknown): SaveBody | null {
   if (!isObject(value) || !hasOnlyKeys(value, [
     "frames",
+    "locales",
+    "defaultLocale",
+    "timeZone",
+    "capture",
+    "gallery",
     "boothKey",
     "mutationId",
     "baseRevisionId",
@@ -108,6 +126,82 @@ function parseSaveBody(value: unknown): SaveBody | null {
   ) {
     return null;
   }
+  if (
+    value.locales !== undefined
+    && (
+      !Array.isArray(value.locales)
+      || value.locales.length === 0
+      || !value.locales.every(isSupportedLocale)
+      || new Set(value.locales).size !== value.locales.length
+    )
+  ) {
+    return null;
+  }
+  if (
+    value.defaultLocale !== undefined
+    && (
+      !isSupportedLocale(value.defaultLocale)
+      || !Array.isArray(value.locales)
+      || !value.locales.includes(value.defaultLocale)
+    )
+  ) {
+    return null;
+  }
+  if (value.locales !== undefined && value.defaultLocale === undefined) return null;
+  if (
+    value.timeZone !== undefined
+    && (typeof value.timeZone !== "string" || value.timeZone.length > 128)
+  ) {
+    return null;
+  }
+  if (value.capture !== undefined) {
+    if (
+      !isObject(value.capture)
+      || !hasOnlyKeys(value.capture, [
+        "reviewEnabled",
+        "autoAcceptSeconds",
+        "countdownAudioDefault",
+      ])
+      || (
+        value.capture.reviewEnabled !== undefined
+        && typeof value.capture.reviewEnabled !== "boolean"
+      )
+      || (
+        value.capture.autoAcceptSeconds !== undefined
+        && (
+          typeof value.capture.autoAcceptSeconds !== "number"
+          || !Number.isInteger(value.capture.autoAcceptSeconds)
+          || value.capture.autoAcceptSeconds < 1
+          || value.capture.autoAcceptSeconds > 30
+        )
+      )
+      || (
+        value.capture.countdownAudioDefault !== undefined
+        && typeof value.capture.countdownAudioDefault !== "boolean"
+      )
+    ) {
+      return null;
+    }
+  }
+  if (value.gallery !== undefined) {
+    if (
+      !isObject(value.gallery)
+      || !hasOnlyKeys(value.gallery, ["title", "accentColor"])
+      || (
+        value.gallery.title !== undefined
+        && (typeof value.gallery.title !== "string" || value.gallery.title.length > 120)
+      )
+      || (
+        value.gallery.accentColor !== undefined
+        && (
+          typeof value.gallery.accentColor !== "string"
+          || !/^#[0-9a-f]{6}$/i.test(value.gallery.accentColor)
+        )
+      )
+    ) {
+      return null;
+    }
+  }
   if (
     value.boothKey !== undefined
     && (
@@ -120,6 +214,38 @@ function parseSaveBody(value: unknown): SaveBody | null {
   }
   return {
     frames: [...value.frames],
+    ...(Array.isArray(value.locales) ? { locales: [...value.locales] } : {}),
+    ...(typeof value.defaultLocale === "string"
+      ? { defaultLocale: value.defaultLocale }
+      : {}),
+    ...(typeof value.timeZone === "string" ? { timeZone: value.timeZone } : {}),
+    ...(isObject(value.capture)
+      ? {
+        capture: {
+          ...(typeof value.capture.reviewEnabled === "boolean"
+            ? { reviewEnabled: value.capture.reviewEnabled }
+            : {}),
+          ...(typeof value.capture.autoAcceptSeconds === "number"
+            ? { autoAcceptSeconds: value.capture.autoAcceptSeconds }
+            : {}),
+          ...(typeof value.capture.countdownAudioDefault === "boolean"
+            ? { countdownAudioDefault: value.capture.countdownAudioDefault }
+            : {}),
+        },
+      }
+      : {}),
+    ...(isObject(value.gallery)
+      ? {
+        gallery: {
+          ...(typeof value.gallery.title === "string"
+            ? { title: value.gallery.title }
+            : {}),
+          ...(typeof value.gallery.accentColor === "string"
+            ? { accentColor: value.gallery.accentColor }
+            : {}),
+        },
+      }
+      : {}),
     ...(typeof value.boothKey === "string" ? { boothKey: value.boothKey } : {}),
     mutationId: value.mutationId,
     baseRevisionId: value.baseRevisionId,
@@ -160,29 +286,55 @@ function configForSave(
 ): EventConfig {
   return {
     frames: [...body.frames],
-    ...(current?.locales ? { locales: [...current.locales] } : {}),
-    ...(current?.defaultLocale ? { defaultLocale: current.defaultLocale } : {}),
-    ...(current?.timeZone ? { timeZone: current.timeZone } : {}),
-    ...(current?.capture
+    ...(body.locales
+      ? { locales: [...body.locales] }
+      : current?.locales
+        ? { locales: [...current.locales] }
+        : {}),
+    ...(body.defaultLocale
+      ? { defaultLocale: body.defaultLocale }
+      : current?.defaultLocale
+        ? { defaultLocale: current.defaultLocale }
+        : {}),
+    ...(body.timeZone
+      ? { timeZone: body.timeZone }
+      : current?.timeZone
+        ? { timeZone: current.timeZone }
+        : {}),
+    ...(body.capture || current?.capture
       ? {
         capture: {
-          ...(current.capture.reviewEnabled !== undefined
-            ? { reviewEnabled: current.capture.reviewEnabled }
+          ...(body.capture?.reviewEnabled !== undefined
+            ? { reviewEnabled: body.capture.reviewEnabled }
+            : current?.capture?.reviewEnabled !== undefined
+              ? { reviewEnabled: current.capture.reviewEnabled }
             : {}),
-          ...(current.capture.autoAcceptSeconds !== undefined
-            ? { autoAcceptSeconds: current.capture.autoAcceptSeconds }
+          ...(body.capture?.autoAcceptSeconds !== undefined
+            ? { autoAcceptSeconds: body.capture.autoAcceptSeconds }
+            : current?.capture?.autoAcceptSeconds !== undefined
+              ? { autoAcceptSeconds: current.capture.autoAcceptSeconds }
             : {}),
-          ...(current.capture.countdownAudioDefault !== undefined
-            ? { countdownAudioDefault: current.capture.countdownAudioDefault }
+          ...(body.capture?.countdownAudioDefault !== undefined
+            ? { countdownAudioDefault: body.capture.countdownAudioDefault }
+            : current?.capture?.countdownAudioDefault !== undefined
+              ? { countdownAudioDefault: current.capture.countdownAudioDefault }
             : {}),
         },
       }
       : {}),
-    ...(current?.gallery
+    ...(body.gallery || current?.gallery
       ? {
         gallery: {
-          ...(current.gallery.title !== undefined ? { title: current.gallery.title } : {}),
-          ...(current.gallery.accentColor !== undefined ? { accentColor: current.gallery.accentColor } : {}),
+          ...(body.gallery?.title !== undefined
+            ? { title: body.gallery.title }
+            : current?.gallery?.title !== undefined
+              ? { title: current.gallery.title }
+              : {}),
+          ...(body.gallery?.accentColor !== undefined
+            ? { accentColor: body.gallery.accentColor }
+            : current?.gallery?.accentColor !== undefined
+              ? { accentColor: current.gallery.accentColor }
+              : {}),
         },
       }
       : {}),
diff --git a/app/event-config.test.ts b/app/event-config.test.ts
index ca8814d..c69d800 100644
--- a/app/event-config.test.ts
+++ b/app/event-config.test.ts
@@ -37,6 +37,19 @@ describe("event config schema", () => {
     expect(parseEventConfig({ version: 1, frames: [], gallery: { accentColor: "red<script>" } })).toBeNull();
   });
 
+  test("keeps legacy stored LocaleCode values readable", () => {
+    expect(parseEventConfig({
+      version: 1,
+      frames: ["square"],
+      locales: ["en", "future-locale"],
+      defaultLocale: "future-locale",
+    })).toEqual({
+      frames: ["square"],
+      locales: ["en", "future-locale"],
+      defaultLocale: "future-locale",
+    });
+  });
+
   test("projects only public allowlisted fields", () => {
     const projected = projectPublicConfig({
       frames: ["square"],
diff --git a/app/frame-packs/catalog.ts b/app/frame-packs/catalog.ts
index ed1ffb2..6e0bb22 100644
--- a/app/frame-packs/catalog.ts
+++ b/app/frame-packs/catalog.ts
@@ -1,6 +1,7 @@
 import defaultPackJson from "../../public/templates/default/manifest.json";
 import talentBeaconJson from "../../public/templates/talent-beacon-9-anniversary/manifest.json";
 import type { FrameDefinition, FramePackManifest, Template } from "./types";
+import type { SupportedLocale } from "../i18n/catalog";
 
 export const FRAME_PACKS = [defaultPackJson, talentBeaconJson] as FramePackManifest[];
 
@@ -24,6 +25,14 @@ export function assetUrl(packKey: string, asset: string): string {
   return `/templates/${packKey}/${asset}`;
 }
 
+export function frameLabel(
+  frame: Pick<FrameDefinition, "label" | "labels">,
+  locale: SupportedLocale
+): string {
+  const localized = frame.labels?.[locale];
+  return localized?.trim() ? localized : frame.label;
+}
+
 function toRuntimeTemplate(packKey: string, frame: FrameDefinition): Template {
   const { preview: _preview, bgImage, overlay, ...rest } = frame;
   return {
diff --git a/app/frame-packs/types.ts b/app/frame-packs/types.ts
index 323632c..5744600 100644
--- a/app/frame-packs/types.ts
+++ b/app/frame-packs/types.ts
@@ -1,9 +1,12 @@
+import type { SupportedLocale } from "../i18n/catalog";
+
 export type Fit = "cover" | "contain";
 
 export type Slot = { x: number; y: number; w: number; h: number; fit?: Fit };
 
 export type FrameDefinition = {
   label: string;
+  labels?: Partial<Record<SupportedLocale, string>>;
   shots: number;
   intervalMs: number;
   canvas: { w: number; h: number };
diff --git a/app/frame-packs/validate.test.ts b/app/frame-packs/validate.test.ts
index d81174f..f2a54ec 100644
--- a/app/frame-packs/validate.test.ts
+++ b/app/frame-packs/validate.test.ts
@@ -1,5 +1,5 @@
 import { expect, test } from "bun:test";
-import { FRAME_PACKS } from "./catalog";
+import { FRAME_PACKS, frameLabel } from "./catalog";
 import type { FramePackManifest } from "./types";
 import { validateFramePacks } from "./validate";
 
@@ -72,3 +72,71 @@ test("requires a usable visual source and known local assets", () => {
   expect(messages).toContain("frame has no usable preview source");
   expect(messages).toContain("asset does not exist: preview.png");
 });
+
+test("localized Frame labels fall back to the required default label", () => {
+  const frame = {
+    label: "Square",
+    labels: { "zh-SG": "方形" },
+  };
+
+  expect(frameLabel(frame, "zh-SG")).toBe("方形");
+  expect(frameLabel(frame, "ar")).toBe("Square");
+});
+
+test("rejects unsupported, blank, and overlong localized Frame labels", () => {
+  const broken: FramePackManifest = {
+    version: 1,
+    pack: { key: "party", label: "Party" },
+    templates: {
+      bad: {
+        label: "Bad",
+        labels: {
+          ar: " ",
+          "zh-SG": "好".repeat(81),
+          fr: "Mauvais",
+        },
+        shots: 1,
+        intervalMs: 3000,
+        canvas: { w: 100, h: 100 },
+        background: "#fff",
+        slots: [{ x: 0, y: 0, w: 100, h: 100 }],
+      },
+    },
+  } as FramePackManifest;
+
+  const issues = validateFramePacks([broken]);
+  expect(issues).toContainEqual({
+    path: "party.templates.bad.labels.ar",
+    message: "localized label is required",
+  });
+  expect(issues).toContainEqual({
+    path: "party.templates.bad.labels.zh-SG",
+    message: "localized label must be at most 80 characters",
+  });
+  expect(issues).toContainEqual({
+    path: "party.templates.bad.labels.fr",
+    message: "localized label locale is unsupported",
+  });
+});
+
+test("rejects a default Frame label longer than 80 characters", () => {
+  const broken: FramePackManifest = {
+    version: 1,
+    pack: { key: "party", label: "Party" },
+    templates: {
+      bad: {
+        label: "B".repeat(81),
+        shots: 1,
+        intervalMs: 3000,
+        canvas: { w: 100, h: 100 },
+        background: "#fff",
+        slots: [{ x: 0, y: 0, w: 100, h: 100 }],
+      },
+    },
+  };
+
+  expect(validateFramePacks([broken])).toContainEqual({
+    path: "party.templates.bad.label",
+    message: "label must be at most 80 characters",
+  });
+});
diff --git a/app/frame-packs/validate.ts b/app/frame-packs/validate.ts
index 6fa7887..b974e86 100644
--- a/app/frame-packs/validate.ts
+++ b/app/frame-packs/validate.ts
@@ -1,4 +1,5 @@
 import type { AssetInfo, FramePackManifest, ValidationIssue } from "./types";
+import { isSupportedLocale } from "../i18n/catalog";
 
 const KEY = /^[a-z][a-zA-Z0-9-]*$/;
 const IMAGE_FIELDS = ["bgImage", "overlay", "preview"] as const;
@@ -25,6 +26,26 @@ export function validateFramePacks(
       if (templateKeys.has(key)) issues.push({ path, message: "template key is duplicated across packs" });
       templateKeys.add(key);
       if (!frame.label?.trim()) issues.push({ path: `${path}.label`, message: "label is required" });
+      else if (frame.label.length > 80) {
+        issues.push({ path: `${path}.label`, message: "label must be at most 80 characters" });
+      }
+      if (frame.labels !== undefined) {
+        if (!frame.labels || typeof frame.labels !== "object" || Array.isArray(frame.labels)) {
+          issues.push({ path: `${path}.labels`, message: "localized labels must be an object" });
+        } else {
+          for (const [locale, label] of Object.entries(frame.labels)) {
+            const labelPath = `${path}.labels.${locale}`;
+            if (!isSupportedLocale(locale)) {
+              issues.push({ path: labelPath, message: "localized label locale is unsupported" });
+            }
+            if (typeof label !== "string" || !label.trim()) {
+              issues.push({ path: labelPath, message: "localized label is required" });
+            } else if (label.length > 80) {
+              issues.push({ path: labelPath, message: "localized label must be at most 80 characters" });
+            }
+          }
+        }
+      }
       if (!positive(frame.canvas?.w) || !positive(frame.canvas?.h)) {
         issues.push({ path: `${path}.canvas`, message: "canvas dimensions must be positive integers" });
       }
diff --git a/app/i18n/catalog.test.ts b/app/i18n/catalog.test.ts
new file mode 100644
index 0000000..2779cc0
--- /dev/null
+++ b/app/i18n/catalog.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import {
+  arabicMessages,
+  chineseSingaporeMessages,
+  englishMessages,
+  isSupportedLocale,
+  localeDirection,
+  message,
+  SUPPORTED_LOCALES,
+} from "./catalog";
+
+function placeholders(value: string): string[] {
+  return [...value.matchAll(/\{([A-Za-z][A-Za-z0-9]*)\}/g)]
+    .map((match) => match[1])
+    .sort();
+}
+
+describe("guest message catalogs", () => {
+  test("publishes the fixed supported locale contract", () => {
+    expect(SUPPORTED_LOCALES).toEqual(["en", "zh-SG", "ar"]);
+    expect(isSupportedLocale("en")).toBe(true);
+    expect(isSupportedLocale("zh-SG")).toBe(true);
+    expect(isSupportedLocale("ar")).toBe(true);
+    expect(isSupportedLocale("zh")).toBe(false);
+    expect(isSupportedLocale({ locale: "en" })).toBe(false);
+  });
+
+  test("every translation has exactly the English keys and placeholders", () => {
+    const englishKeys = Object.keys(englishMessages).sort();
+
+    for (const catalog of [chineseSingaporeMessages, arabicMessages]) {
+      expect(Object.keys(catalog).sort()).toEqual(englishKeys);
+      for (const key of englishKeys) {
+        expect(placeholders(catalog[key as keyof typeof catalog])).toEqual(
+          placeholders(englishMessages[key as keyof typeof englishMessages])
+        );
+      }
+    }
+  });
+
+  test("interpolates values without disturbing unknown placeholders", () => {
+    expect(message("zh-SG", "photoCount", { count: 3 })).toBe("3 张照片");
+    expect(message("ar", "uploading", { count: 2 })).toContain("2");
+    expect(message("en", "photoCount")).toBe("{count} photos");
+  });
+
+  test("falls back to English when a runtime catalog entry is unavailable", () => {
+    const key = "pickStyle";
+    const original = chineseSingaporeMessages[key];
+    Reflect.deleteProperty(chineseSingaporeMessages, key);
+    try {
+      expect(message("zh-SG", key)).toBe(englishMessages[key]);
+    } finally {
+      chineseSingaporeMessages[key] = original;
+    }
+  });
+
+  test("marks Arabic as RTL and the other catalogs as LTR", () => {
+    expect(localeDirection("ar")).toBe("rtl");
+    expect(localeDirection("en")).toBe("ltr");
+    expect(localeDirection("zh-SG")).toBe("ltr");
+  });
+});
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
new file mode 100644
index 0000000..332e1cc
--- /dev/null
+++ b/app/i18n/catalog.ts
@@ -0,0 +1,123 @@
+export const SUPPORTED_LOCALES = ["en", "zh-SG", "ar"] as const;
+
+export type SupportedLocale = typeof SUPPORTED_LOCALES[number];
+
+export const englishMessages = {
+  boothKeyPrompt: "Enter this event's booth key",
+  queueStarting: "Photo queue is still starting — please try again",
+  lastPhoto: "Last photo",
+  pickStyle: "Pick a style",
+  noFrames: "No frames are enabled for this event yet.",
+  onePhoto: "1 photo",
+  photoCount: "{count} photos",
+  cameraUnavailable: "Camera unavailable. Use your device camera instead:",
+  takePhoto: "Take a photo",
+  startCapture: "Start",
+  changeFrame: "{frame} · change",
+  liveGallery: "Live",
+  uploading: "Uploading {count}…",
+  retryPending: "Retry {count} pending",
+  offlineStorageUnavailable:
+    "Offline photo storage is unavailable. Pending photos may be lost if this page reloads.",
+  usePhoto: "Use Photo",
+  retake: "Retake",
+  moreTime: "More Time",
+  accepting: "Saving photo…",
+  preview: "Photo preview",
+  queued: "Photo safely queued.",
+  handoffTitle: "Your photo is ready",
+  handoffBody: "Scan to open this photo on your phone.",
+  viewPhoto: "View photo",
+  nextGuest: "Next guest",
+  pausedTitle: "Booth paused",
+  countdownShot: "Photo {shot} of {total}",
+} satisfies Record<string, string>;
+
+export type MessageKey = keyof typeof englishMessages;
+
+export const chineseSingaporeMessages: Record<MessageKey, string> = {
+  boothKeyPrompt: "请输入此活动的拍照亭密钥",
+  queueStarting: "照片队列仍在启动，请重试",
+  lastPhoto: "上一张照片",
+  pickStyle: "选择相框",
+  noFrames: "此活动尚未启用任何相框。",
+  onePhoto: "1 张照片",
+  photoCount: "{count} 张照片",
+  cameraUnavailable: "无法使用相机。请改用设备相机：",
+  takePhoto: "拍照",
+  startCapture: "开始",
+  changeFrame: "{frame} · 更换",
+  liveGallery: "现场相册",
+  uploading: "正在上传 {count} 张…",
+  retryPending: "重试 {count} 张待上传照片",
+  offlineStorageUnavailable: "无法使用离线照片存储。重新加载此页面可能会丢失待上传照片。",
+  usePhoto: "使用照片",
+  retake: "重拍",
+  moreTime: "需要更多时间",
+  accepting: "正在保存照片…",
+  preview: "照片预览",
+  queued: "照片已安全加入队列。",
+  handoffTitle: "您的照片已准备好",
+  handoffBody: "扫描二维码，在手机上打开此照片。",
+  viewPhoto: "查看照片",
+  nextGuest: "下一位来宾",
+  pausedTitle: "拍照亭已暂停",
+  countdownShot: "第 {shot} 张，共 {total} 张",
+};
+
+export const arabicMessages: Record<MessageKey, string> = {
+  boothKeyPrompt: "أدخل مفتاح كشك التصوير لهذا الحدث",
+  queueStarting: "لا تزال قائمة انتظار الصور قيد البدء — حاول مرة أخرى",
+  lastPhoto: "الصورة السابقة",
+  pickStyle: "اختر إطارًا",
+  noFrames: "لم يتم تفعيل أي إطارات لهذا الحدث بعد.",
+  onePhoto: "صورة واحدة",
+  photoCount: "{count} صور",
+  cameraUnavailable: "الكاميرا غير متاحة. استخدم كاميرا جهازك بدلًا منها:",
+  takePhoto: "التقط صورة",
+  startCapture: "ابدأ",
+  changeFrame: "تغيير · {frame}",
+  liveGallery: "المعرض المباشر",
+  uploading: "جارٍ رفع {count}…",
+  retryPending: "أعد محاولة رفع {count} معلّقة",
+  offlineStorageUnavailable:
+    "تخزين الصور دون اتصال غير متاح. قد تُفقد الصور المعلّقة إذا أُعيد تحميل هذه الصفحة.",
+  usePhoto: "استخدم الصورة",
+  retake: "أعد الالتقاط",
+  moreTime: "وقت إضافي",
+  accepting: "جارٍ حفظ الصورة…",
+  preview: "معاينة الصورة",
+  queued: "أُضيفت الصورة إلى قائمة الانتظار بأمان.",
+  handoffTitle: "صورتك جاهزة",
+  handoffBody: "امسح الرمز لفتح هذه الصورة على هاتفك.",
+  viewPhoto: "اعرض الصورة",
+  nextGuest: "الضيف التالي",
+  pausedTitle: "كشك التصوير متوقف مؤقتًا",
+  countdownShot: "الصورة {shot} من {total}",
+};
+
+const catalogs: Record<SupportedLocale, Record<MessageKey, string>> = {
+  en: englishMessages,
+  "zh-SG": chineseSingaporeMessages,
+  ar: arabicMessages,
+};
+
+export function isSupportedLocale(value: unknown): value is SupportedLocale {
+  return typeof value === "string"
+    && (SUPPORTED_LOCALES as readonly string[]).includes(value);
+}
+
+export function message(
+  locale: SupportedLocale,
+  key: MessageKey,
+  values: Record<string, string | number> = {}
+): string {
+  const template = catalogs[locale]?.[key] ?? englishMessages[key];
+  return template.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/g, (placeholder, name: string) =>
+    Object.hasOwn(values, name) ? String(values[name]) : placeholder
+  );
+}
+
+export function localeDirection(locale: SupportedLocale): "ltr" | "rtl" {
+  return locale === "ar" ? "rtl" : "ltr";
+}
diff --git a/app/i18n/locale.test.ts b/app/i18n/locale.test.ts
new file mode 100644
index 0000000..b49647d
--- /dev/null
+++ b/app/i18n/locale.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import {
+  applyDocumentLocale,
+  deviceLocaleStorageKey,
+  resolveDeviceLocale,
+  resolveEnabledLocales,
+  saveDeviceLocale,
+} from "./locale";
+
+describe("guest locale resolution", () => {
+  test("intersects configured locales with catalogs, deduplicates, and retains English", () => {
+    expect(resolveEnabledLocales(undefined)).toEqual(["en"]);
+    expect(resolveEnabledLocales(["ar", "legacy", "ar", "zh-SG"])).toEqual([
+      "ar",
+      "zh-SG",
+      "en",
+    ]);
+  });
+
+  test("uses an enabled stored locale before the configured default and browser", () => {
+    expect(resolveDeviceLocale({
+      event: "launch",
+      configured: ["en", "zh-SG", "ar"],
+      defaultLocale: "en",
+      storedLocale: "ar",
+      navigatorLanguages: ["zh-SG"],
+    })).toBe("ar");
+  });
+
+  test("falls back through configured default, browser language, and English", () => {
+    expect(resolveDeviceLocale({
+      event: "launch",
+      configured: ["en", "zh-SG"],
+      defaultLocale: "zh-SG",
+      storedLocale: "ar",
+      navigatorLanguages: ["en-SG"],
+    })).toBe("zh-SG");
+    expect(resolveDeviceLocale({
+      event: "launch",
+      configured: ["en", "ar"],
+      defaultLocale: "legacy",
+      navigatorLanguages: ["ar-SG", "en-SG"],
+    })).toBe("ar");
+    expect(resolveDeviceLocale({
+      event: "launch",
+      configured: ["legacy"],
+      defaultLocale: "legacy",
+      navigatorLanguages: ["fr-FR"],
+    })).toBe("en");
+  });
+
+  test("persists locale under an Event-isolated device key", () => {
+    const values = new Map<string, string>();
+    const storage = {
+      setItem(key: string, value: string) {
+        values.set(key, value);
+      },
+    };
+
+    saveDeviceLocale("launch", "ar", storage);
+    saveDeviceLocale("wedding", "zh-SG", storage);
+
+    expect(deviceLocaleStorageKey("launch")).not.toBe(deviceLocaleStorageKey("wedding"));
+    expect(values.get(deviceLocaleStorageKey("launch"))).toBe("ar");
+    expect(values.get(deviceLocaleStorageKey("wedding"))).toBe("zh-SG");
+  });
+
+  test("applies real language direction to the document root", () => {
+    const root = { lang: "", dir: "" };
+    applyDocumentLocale(root, "ar");
+    expect(root).toEqual({ lang: "ar", dir: "rtl" });
+    applyDocumentLocale(root, "zh-SG");
+    expect(root).toEqual({ lang: "zh-SG", dir: "ltr" });
+  });
+});
diff --git a/app/i18n/locale.ts b/app/i18n/locale.ts
new file mode 100644
index 0000000..a203e96
--- /dev/null
+++ b/app/i18n/locale.ts
@@ -0,0 +1,75 @@
+import {
+  isSupportedLocale,
+  localeDirection,
+  SUPPORTED_LOCALES,
+  type SupportedLocale,
+} from "./catalog";
+
+const STORAGE_PREFIX = "boothLocale:";
+
+export function deviceLocaleStorageKey(event: string): string {
+  return `${STORAGE_PREFIX}${event}`;
+}
+
+export function resolveEnabledLocales(
+  configured: readonly string[] | undefined
+): SupportedLocale[] {
+  const enabled = (configured ?? [])
+    .filter(isSupportedLocale)
+    .filter((locale, index, locales) => locales.indexOf(locale) === index);
+  if (!enabled.includes("en")) enabled.push("en");
+  return enabled;
+}
+
+function matchBrowserLocale(
+  language: string,
+  enabled: readonly SupportedLocale[]
+): SupportedLocale | null {
+  if (isSupportedLocale(language) && enabled.includes(language)) return language;
+  const normalized = language.toLowerCase();
+  const candidate = SUPPORTED_LOCALES.find((locale) => {
+    if (!enabled.includes(locale)) return false;
+    const supported = locale.toLowerCase();
+    if (supported.startsWith("zh-")) return normalized === "zh" || normalized.startsWith("zh-");
+    return normalized === supported || normalized.startsWith(`${supported}-`);
+  });
+  return candidate ?? null;
+}
+
+export function resolveDeviceLocale(input: {
+  event: string;
+  configured: readonly string[] | undefined;
+  defaultLocale?: string;
+  storedLocale?: string | null;
+  navigatorLanguages?: readonly string[];
+}): SupportedLocale {
+  void input.event;
+  const enabled = resolveEnabledLocales(input.configured);
+  if (isSupportedLocale(input.storedLocale) && enabled.includes(input.storedLocale)) {
+    return input.storedLocale;
+  }
+  if (isSupportedLocale(input.defaultLocale) && enabled.includes(input.defaultLocale)) {
+    return input.defaultLocale;
+  }
+  for (const language of input.navigatorLanguages ?? []) {
+    const matched = matchBrowserLocale(language, enabled);
+    if (matched) return matched;
+  }
+  return "en";
+}
+
+export function saveDeviceLocale(
+  event: string,
+  locale: SupportedLocale,
+  storage: Pick<Storage, "setItem">
+): void {
+  storage.setItem(deviceLocaleStorageKey(event), locale);
+}
+
+export function applyDocumentLocale(
+  documentElement: Pick<HTMLElement, "lang" | "dir">,
+  locale: SupportedLocale
+): void {
+  documentElement.lang = locale;
+  documentElement.dir = localeDirection(locale);
+}

From 0728106432c0738255b7e593ebf96203a497ed8b Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:44:46 +0800
Subject: [PATCH 055/105] fix: harden localized capture config

---
 .../admin/admin-config-controls.test.tsx      |   7 +
 app/[event]/admin/admin-config-controls.tsx   |   5 +-
 app/[event]/admin/config-mutation.test.ts     | 107 +++++++++++-
 app/[event]/admin/config-mutation.ts          | 164 +++++++++++++++++-
 app/[event]/admin/page.tsx                    |  19 +-
 app/api/config/handlers.test.ts               |   1 +
 app/api/config/handlers.ts                    |   1 +
 app/frame-packs/validate.test.ts              |  32 ++++
 app/frame-packs/validate.ts                   |   8 +-
 app/i18n/locale.test.ts                       |  60 ++++++-
 app/i18n/locale.ts                            |  26 ++-
 11 files changed, 402 insertions(+), 28 deletions(-)

diff --git a/app/[event]/admin/admin-config-controls.test.tsx b/app/[event]/admin/admin-config-controls.test.tsx
index 0bcf196..988c58a 100644
--- a/app/[event]/admin/admin-config-controls.test.tsx
+++ b/app/[event]/admin/admin-config-controls.test.tsx
@@ -84,6 +84,13 @@ test("capture experience controls expose supported locales and plain capture set
   expect(html).toContain("Countdown sounds on by default");
   expect(html).toContain('min="1"');
   expect(html).toContain('max="30"');
+  const englishInput = html.match(/<input[^>]*><span lang="en"/)?.[0] ?? "";
+  const arabicInput = html.match(/<input[^>]*><span lang="ar"/)?.[0] ?? "";
+  expect(englishInput).toContain('checked=""');
+  expect(englishInput).toContain('disabled=""');
+  expect(englishInput).toContain('required=""');
+  expect(arabicInput).toContain('checked=""');
+  expect(arabicInput).not.toContain("disabled");
 });
 
 test("configuration mutation guard disables every locale and capture control", () => {
diff --git a/app/[event]/admin/admin-config-controls.tsx b/app/[event]/admin/admin-config-controls.tsx
index a920f59..e23b328 100644
--- a/app/[event]/admin/admin-config-controls.tsx
+++ b/app/[event]/admin/admin-config-controls.tsx
@@ -215,8 +215,9 @@ export function CaptureExperienceControls({
             <label key={locale}>
               <input
                 type="checkbox"
-                checked={enabledLocales.has(locale)}
-                disabled={disabled}
+                checked={locale === "en" || enabledLocales.has(locale)}
+                disabled={disabled || locale === "en"}
+                required={locale === "en"}
                 onChange={() => onToggleLocale(locale)}
               />
               <span lang={locale} dir={locale === "ar" ? "rtl" : "ltr"}>
diff --git a/app/[event]/admin/config-mutation.test.ts b/app/[event]/admin/config-mutation.test.ts
index be3b1d2..a7250b0 100644
--- a/app/[event]/admin/config-mutation.test.ts
+++ b/app/[event]/admin/config-mutation.test.ts
@@ -3,6 +3,8 @@ import {
   buildConfigSaveBody,
   clearRestoreRequestAfterReconciliation,
   getOrCreateRestoreRequest,
+  parseConfigHistoryResponse,
+  parseConfigMutationResponse,
   rebaseConfigHistory,
   shouldClearRestoreRequest,
   type RestoreRequest,
@@ -121,7 +123,7 @@ test("history rebase restores the complete safe editable experience", () => {
   expect(rebased).toMatchObject({
     frames: ["one"],
     hasBoothKey: true,
-    locales: ["zh-SG", "ar", "en"],
+    locales: ["en", "zh-SG", "ar"],
     defaultLocale: "ar",
     timeZone: "Asia/Singapore",
     reviewEnabled: false,
@@ -184,3 +186,106 @@ test("a 2xx restore retains its exact tuple until parsing, apply, and history re
   await clearRestoreRequestAfterReconciliation(pending, request, async () => {});
   expect(pending.has(SOURCE_REVISION)).toBe(false);
 });
+
+test("strictly parses a complete Admin configuration history response", () => {
+  expect(parseConfigHistoryResponse({
+    config: {
+      frames: ["one"],
+      hasBoothKey: true,
+      locales: ["en", "ar"],
+      defaultLocale: "ar",
+      capture: {
+        reviewEnabled: false,
+        autoAcceptSeconds: 9,
+        countdownAudioDefault: true,
+      },
+    },
+    currentRevisionId: SOURCE_REVISION,
+    revisions: [{
+      version: 1,
+      id: SOURCE_REVISION,
+      createdAt: "2026-07-24T00:00:00.000Z",
+      parentRevisionId: null,
+      reason: "save",
+      config: {
+        frames: ["one"],
+        locales: ["en", "ar"],
+        defaultLocale: "ar",
+        capture: {
+          reviewEnabled: false,
+          autoAcceptSeconds: 9,
+          countdownAudioDefault: true,
+        },
+      },
+    }],
+  })).toMatchObject({
+    config: {
+      frames: ["one"],
+      hasBoothKey: true,
+      locales: ["en", "ar"],
+      defaultLocale: "ar",
+    },
+    currentRevisionId: SOURCE_REVISION,
+    revisions: [{ id: SOURCE_REVISION }],
+  });
+});
+
+test("rejects malformed nested config and revision data before rebase", () => {
+  const base = {
+    config: { frames: ["one"], hasBoothKey: false },
+    currentRevisionId: null,
+    revisions: [],
+  };
+  const malformed = [
+    { ...base, config: { ...base.config, locales: [null] } },
+    { ...base, config: { ...base.config, capture: { autoAcceptSeconds: 0 } } },
+    { ...base, currentRevisionId: "../revision" },
+    { ...base, revisions: [null] },
+    {
+      ...base,
+      revisions: [{
+        version: 1,
+        id: SOURCE_REVISION,
+        createdAt: "2026-07-24T00:00:00.000Z",
+        parentRevisionId: null,
+        reason: "save",
+        config: { frames: ["one"], capture: { reviewEnabled: "yes" } },
+      }],
+    },
+  ];
+
+  for (const response of malformed) {
+    expect(() => parseConfigHistoryResponse(response)).not.toThrow();
+    expect(parseConfigHistoryResponse(response)).toBeNull();
+  }
+});
+
+test("strictly parses mutation responses before applying restored settings", () => {
+  expect(parseConfigMutationResponse({
+    frames: ["one"],
+    hasBoothKey: true,
+    locales: ["en"],
+    defaultLocale: "en",
+    capture: {
+      reviewEnabled: true,
+      autoAcceptSeconds: 5,
+      countdownAudioDefault: false,
+    },
+    currentRevisionId: SOURCE_REVISION,
+    idempotent: false,
+  })).toMatchObject({
+    frames: ["one"],
+    currentRevisionId: SOURCE_REVISION,
+    idempotent: false,
+  });
+
+  expect(parseConfigMutationResponse({
+    frames: ["one"],
+    hasBoothKey: true,
+    locales: ["en"],
+    defaultLocale: "en",
+    capture: { autoAcceptSeconds: "soon" },
+    currentRevisionId: SOURCE_REVISION,
+    idempotent: false,
+  })).toBeNull();
+});
diff --git a/app/[event]/admin/config-mutation.ts b/app/[event]/admin/config-mutation.ts
index c64a1c3..66157b2 100644
--- a/app/[event]/admin/config-mutation.ts
+++ b/app/[event]/admin/config-mutation.ts
@@ -1,8 +1,16 @@
-import type {
-  ConfigRevision,
-  EventExperience,
-  PublicEventConfig,
+import {
+  isRevisionId,
+  parseConfigRevision,
+  parseEventConfig,
+  projectEventExperience,
+  type ConfigRevision,
+  type EventExperience,
+  type PublicEventConfig,
 } from "../../event-config";
+/*
+ * Keep the runtime parsers in this client-safe helper: Admin responses cross
+ * a network trust boundary even though their TypeScript interfaces are local.
+ */
 import {
   isSupportedLocale,
   type SupportedLocale,
@@ -21,6 +29,154 @@ export type ConfigHistoryResponse = {
   revisions: ConfigRevision[];
 };
 
+export type ConfigMutationResponse = PublicEventConfig & {
+  currentRevisionId: string;
+  idempotent: boolean;
+};
+
+const EXPERIENCE_KEYS = [
+  "frames",
+  "locales",
+  "defaultLocale",
+  "timeZone",
+  "capture",
+  "gallery",
+] as const;
+const PUBLIC_CONFIG_KEYS = [...EXPERIENCE_KEYS, "hasBoothKey"] as const;
+const REVISION_KEYS = [
+  "version",
+  "id",
+  "createdAt",
+  "parentRevisionId",
+  "reason",
+  "sourceRevisionId",
+  "sourcePresetId",
+  "config",
+] as const;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOnlyKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[]
+): boolean {
+  const keys = new Set(allowed);
+  return Object.keys(value).every((key) => keys.has(key));
+}
+
+function hasStrictExperienceShape(
+  value: Record<string, unknown>,
+  allowed: readonly string[]
+): boolean {
+  if (!hasOnlyKeys(value, allowed)) return false;
+  if (
+    value.capture !== undefined
+    && (
+      !isObject(value.capture)
+      || !hasOnlyKeys(value.capture, [
+        "reviewEnabled",
+        "autoAcceptSeconds",
+        "countdownAudioDefault",
+      ])
+    )
+  ) {
+    return false;
+  }
+  return value.gallery === undefined
+    || (
+      isObject(value.gallery)
+      && hasOnlyKeys(value.gallery, ["title", "accentColor"])
+    );
+}
+
+function parsePublicConfigResponse(value: unknown): PublicEventConfig | null {
+  if (
+    !isObject(value)
+    || !hasStrictExperienceShape(value, PUBLIC_CONFIG_KEYS)
+    || typeof value.hasBoothKey !== "boolean"
+  ) {
+    return null;
+  }
+  if (value.frames === null) {
+    return Object.keys(value).every((key) => ["frames", "hasBoothKey"].includes(key))
+      ? { frames: null, hasBoothKey: value.hasBoothKey }
+      : null;
+  }
+  const parsed = parseEventConfig({ ...value, version: 1 });
+  if (!parsed) return null;
+  return {
+    ...projectEventExperience(parsed),
+    hasBoothKey: value.hasBoothKey,
+  };
+}
+
+function parseStrictRevision(value: unknown): ConfigRevision | null {
+  if (
+    !isObject(value)
+    || !hasOnlyKeys(value, REVISION_KEYS)
+    || !isObject(value.config)
+    || !hasStrictExperienceShape(value.config, EXPERIENCE_KEYS)
+  ) {
+    return null;
+  }
+  return parseConfigRevision(value);
+}
+
+export function parseConfigHistoryResponse(
+  value: unknown
+): ConfigHistoryResponse | null {
+  if (
+    !isObject(value)
+    || !hasOnlyKeys(value, ["config", "currentRevisionId", "revisions"])
+    || (
+      value.currentRevisionId !== null
+      && !isRevisionId(value.currentRevisionId)
+    )
+    || !Array.isArray(value.revisions)
+  ) {
+    return null;
+  }
+  const config = parsePublicConfigResponse(value.config);
+  const revisions = value.revisions.map(parseStrictRevision);
+  if (!config || revisions.some((revision) => revision === null)) return null;
+  return {
+    config,
+    currentRevisionId: value.currentRevisionId,
+    revisions: revisions as ConfigRevision[],
+  };
+}
+
+export function parseConfigMutationResponse(
+  value: unknown
+): ConfigMutationResponse | null {
+  if (
+    !isObject(value)
+    || !hasOnlyKeys(value, [
+      ...PUBLIC_CONFIG_KEYS,
+      "currentRevisionId",
+      "idempotent",
+    ])
+    || !isRevisionId(value.currentRevisionId)
+    || typeof value.idempotent !== "boolean"
+  ) {
+    return null;
+  }
+  const {
+    currentRevisionId,
+    idempotent,
+    ...configValue
+  } = value;
+  const config = parsePublicConfigResponse(configValue);
+  if (!config || config.frames === null) return null;
+  return {
+    ...config,
+    currentRevisionId,
+    idempotent,
+  };
+}
+
 export type EditableEventExperience = {
   frames: string[];
   locales: SupportedLocale[];
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index b66712e..b5a45fc 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -27,9 +27,10 @@ import {
   clearRestoreRequestAfterReconciliation,
   editableExperienceFromConfig,
   getOrCreateRestoreRequest,
+  parseConfigHistoryResponse,
+  parseConfigMutationResponse,
   rebaseConfigHistory,
   shouldClearRestoreRequest,
-  type ConfigHistoryResponse,
   type RestoreRequest,
 } from "./config-mutation";
 import styles from "./admin.module.css";
@@ -151,12 +152,8 @@ export default function Admin() {
         throw new Error("That admin key was rejected.");
       }
       if (!response.ok) throw new Error(`Configuration history returned ${response.status}`);
-      const data = await response.json() as ConfigHistoryResponse;
-      if (
-        !data.config
-        || !Array.isArray(data.revisions)
-        || (data.currentRevisionId !== null && typeof data.currentRevisionId !== "string")
-      ) {
+      const data = parseConfigHistoryResponse(await response.json());
+      if (!data) {
         throw new Error("Configuration history had an unexpected shape");
       }
       const rebased = rebaseConfigHistory(data, defaults, pendingSaveMutationId);
@@ -465,7 +462,7 @@ export default function Admin() {
   };
 
   const toggleLocale = (locale: SupportedLocale) => {
-    if (configMutationBusy.current) return;
+    if (configMutationBusy.current || locale === "en") return;
     clearPendingSave();
     setLocales((current) => {
       const next = new Set(current);
@@ -581,7 +578,8 @@ export default function Admin() {
         return;
       }
       if (!response.ok) throw new Error(`Save failed (${response.status})`);
-      const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
+      const data = parseConfigMutationResponse(await response.json());
+      if (!data) throw new Error("Configuration response had an unexpected shape");
       pendingSaveMutationId.current = null;
       setCurrentRevisionId(data.currentRevisionId);
       if (boothKey) { setHasBoothKey(true); setBoothKeySaved(true); }
@@ -623,7 +621,8 @@ export default function Admin() {
       }
       if (!response.ok) throw new Error(`Restore failed (${response.status})`);
       await clearRestoreRequestAfterReconciliation(pending, request, async () => {
-        const data = await response.json() as PublicEventConfig & { currentRevisionId: string };
+        const data = parseConfigMutationResponse(await response.json());
+        if (!data) throw new Error("Configuration response had an unexpected shape");
         const restored = editableExperienceFromConfig(data, defaults);
         setFrames(new Set(restored.frames));
         setLocales(new Set(restored.locales));
diff --git a/app/api/config/handlers.test.ts b/app/api/config/handlers.test.ts
index b0d15c3..db000ea 100644
--- a/app/api/config/handlers.test.ts
+++ b/app/api/config/handlers.test.ts
@@ -255,6 +255,7 @@ describe("config handlers", () => {
   test("new saves reject unsupported or inconsistent locale and capture settings", async () => {
     const invalidExperiences = [
       { locales: [] },
+      { locales: ["ar"], defaultLocale: "ar" },
       { locales: ["en", "fr"], defaultLocale: "en" },
       { locales: ["en"], defaultLocale: "ar" },
       { locales: ["en"], defaultLocale: "en", capture: { reviewEnabled: "yes", autoAcceptSeconds: 5, countdownAudioDefault: false } },
diff --git a/app/api/config/handlers.ts b/app/api/config/handlers.ts
index 1b705e3..f20b9e2 100644
--- a/app/api/config/handlers.ts
+++ b/app/api/config/handlers.ts
@@ -133,6 +133,7 @@ function parseSaveBody(value: unknown): SaveBody | null {
       || value.locales.length === 0
       || !value.locales.every(isSupportedLocale)
       || new Set(value.locales).size !== value.locales.length
+      || !value.locales.includes("en")
     )
   ) {
     return null;
diff --git a/app/frame-packs/validate.test.ts b/app/frame-packs/validate.test.ts
index f2a54ec..fd6cea2 100644
--- a/app/frame-packs/validate.test.ts
+++ b/app/frame-packs/validate.test.ts
@@ -140,3 +140,35 @@ test("rejects a default Frame label longer than 80 characters", () => {
     message: "label must be at most 80 characters",
   });
 });
+
+test("counts non-BMP Frame label limits by Unicode code point", () => {
+  const manifest = (defaultLabel: string, localizedLabel: string): FramePackManifest => ({
+    version: 1,
+    pack: { key: "party", label: "Party" },
+    templates: {
+      frame: {
+        label: defaultLabel,
+        labels: { ar: localizedLabel },
+        shots: 1,
+        intervalMs: 3000,
+        canvas: { w: 100, h: 100 },
+        background: "#fff",
+        slots: [{ x: 0, y: 0, w: 100, h: 100 }],
+      },
+    },
+  });
+
+  expect(validateFramePacks([manifest("😀".repeat(80), "🎉".repeat(80))])).toEqual([]);
+  expect(validateFramePacks([manifest("😀".repeat(81), "🎉".repeat(81))])).toEqual(
+    expect.arrayContaining([
+      {
+        path: "party.templates.frame.label",
+        message: "label must be at most 80 characters",
+      },
+      {
+        path: "party.templates.frame.labels.ar",
+        message: "localized label must be at most 80 characters",
+      },
+    ])
+  );
+});
diff --git a/app/frame-packs/validate.ts b/app/frame-packs/validate.ts
index b974e86..43b27d7 100644
--- a/app/frame-packs/validate.ts
+++ b/app/frame-packs/validate.ts
@@ -26,7 +26,7 @@ export function validateFramePacks(
       if (templateKeys.has(key)) issues.push({ path, message: "template key is duplicated across packs" });
       templateKeys.add(key);
       if (!frame.label?.trim()) issues.push({ path: `${path}.label`, message: "label is required" });
-      else if (frame.label.length > 80) {
+      else if (unicodeCodePointLength(frame.label) > 80) {
         issues.push({ path: `${path}.label`, message: "label must be at most 80 characters" });
       }
       if (frame.labels !== undefined) {
@@ -40,7 +40,7 @@ export function validateFramePacks(
             }
             if (typeof label !== "string" || !label.trim()) {
               issues.push({ path: labelPath, message: "localized label is required" });
-            } else if (label.length > 80) {
+            } else if (unicodeCodePointLength(label) > 80) {
               issues.push({ path: labelPath, message: "localized label must be at most 80 characters" });
             }
           }
@@ -116,3 +116,7 @@ function nonNegative(value: unknown): value is number {
 function validColor(value: string): boolean {
   return /^#[0-9a-f]{3}([0-9a-f]{3})?([0-9a-f]{2})?$/i.test(value);
 }
+
+function unicodeCodePointLength(value: string): number {
+  return Array.from(value).length;
+}
diff --git a/app/i18n/locale.test.ts b/app/i18n/locale.test.ts
index b49647d..3849a77 100644
--- a/app/i18n/locale.test.ts
+++ b/app/i18n/locale.test.ts
@@ -11,9 +11,9 @@ describe("guest locale resolution", () => {
   test("intersects configured locales with catalogs, deduplicates, and retains English", () => {
     expect(resolveEnabledLocales(undefined)).toEqual(["en"]);
     expect(resolveEnabledLocales(["ar", "legacy", "ar", "zh-SG"])).toEqual([
-      "ar",
-      "zh-SG",
       "en",
+      "zh-SG",
+      "ar",
     ]);
   });
 
@@ -49,6 +49,52 @@ describe("guest locale resolution", () => {
     })).toBe("en");
   });
 
+  test("maps only compatible Simplified Chinese browser tags to zh-SG", () => {
+    for (const language of [
+      "zh-SG",
+      "zh-CN",
+      "zh-Hans",
+      "zh-Hans-SG",
+      "zh-Hans-CN",
+      "ZH-cn",
+    ]) {
+      expect(resolveDeviceLocale({
+        event: "launch",
+        configured: ["en", "zh-SG"],
+        defaultLocale: "legacy",
+        navigatorLanguages: [language],
+      })).toBe("zh-SG");
+    }
+  });
+
+  test("does not map bare or Traditional Chinese browser tags to zh-SG", () => {
+    for (const language of [
+      "zh",
+      "zh-TW",
+      "zh-HK",
+      "zh-MO",
+      "zh-Hant",
+      "zh-Hant-HK",
+      "zh-Hans-TW",
+    ]) {
+      expect(resolveDeviceLocale({
+        event: "launch",
+        configured: ["en", "zh-SG"],
+        defaultLocale: "legacy",
+        navigatorLanguages: [language],
+      })).toBe("en");
+    }
+  });
+
+  test("a Traditional Chinese browser tag falls through to a configured default", () => {
+    expect(resolveDeviceLocale({
+      event: "launch",
+      configured: ["en", "zh-SG", "ar"],
+      defaultLocale: "ar",
+      navigatorLanguages: ["zh-TW"],
+    })).toBe("ar");
+  });
+
   test("persists locale under an Event-isolated device key", () => {
     const values = new Map<string, string>();
     const storage = {
@@ -65,6 +111,16 @@ describe("guest locale resolution", () => {
     expect(values.get(deviceLocaleStorageKey("wedding"))).toBe("zh-SG");
   });
 
+  test("locale persistence is best-effort when browser storage is denied", () => {
+    const deniedStorage = {
+      setItem() {
+        throw new DOMException("denied", "SecurityError");
+      },
+    };
+
+    expect(() => saveDeviceLocale("launch", "ar", deniedStorage)).not.toThrow();
+  });
+
   test("applies real language direction to the document root", () => {
     const root = { lang: "", dir: "" };
     applyDocumentLocale(root, "ar");
diff --git a/app/i18n/locale.ts b/app/i18n/locale.ts
index a203e96..a6f4c59 100644
--- a/app/i18n/locale.ts
+++ b/app/i18n/locale.ts
@@ -14,11 +14,9 @@ export function deviceLocaleStorageKey(event: string): string {
 export function resolveEnabledLocales(
   configured: readonly string[] | undefined
 ): SupportedLocale[] {
-  const enabled = (configured ?? [])
-    .filter(isSupportedLocale)
-    .filter((locale, index, locales) => locales.indexOf(locale) === index);
-  if (!enabled.includes("en")) enabled.push("en");
-  return enabled;
+  const configuredLocales = new Set((configured ?? []).filter(isSupportedLocale));
+  configuredLocales.add("en");
+  return SUPPORTED_LOCALES.filter((locale) => configuredLocales.has(locale));
 }
 
 function matchBrowserLocale(
@@ -27,10 +25,19 @@ function matchBrowserLocale(
 ): SupportedLocale | null {
   if (isSupportedLocale(language) && enabled.includes(language)) return language;
   const normalized = language.toLowerCase();
+  const subtags = normalized.split("-");
+  if (subtags[0] === "zh") {
+    if (!enabled.includes("zh-SG")) return null;
+    if (subtags.some((subtag) => ["hant", "tw", "hk", "mo"].includes(subtag))) {
+      return null;
+    }
+    return subtags.some((subtag) => ["hans", "sg", "cn"].includes(subtag))
+      ? "zh-SG"
+      : null;
+  }
   const candidate = SUPPORTED_LOCALES.find((locale) => {
     if (!enabled.includes(locale)) return false;
     const supported = locale.toLowerCase();
-    if (supported.startsWith("zh-")) return normalized === "zh" || normalized.startsWith("zh-");
     return normalized === supported || normalized.startsWith(`${supported}-`);
   });
   return candidate ?? null;
@@ -63,7 +70,12 @@ export function saveDeviceLocale(
   locale: SupportedLocale,
   storage: Pick<Storage, "setItem">
 ): void {
-  storage.setItem(deviceLocaleStorageKey(event), locale);
+  try {
+    storage.setItem(deviceLocaleStorageKey(event), locale);
+  } catch {
+    // Locale preference is an enhancement; denied/quota-limited storage must
+    // never block the guest experience.
+  }
 }
 
 export function applyDocumentLocale(

From 7980587e6a84dc5358bf256c3e53d8876cfd38e6 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:55:30 +0800
Subject: [PATCH 056/105] feat: share adaptive photo feed polling

---
 app/photo-feed/controller.test.ts     | 212 +++++++++++++++++++++
 app/photo-feed/controller.ts          | 223 ++++++++++++++++++++++
 app/photo-feed/types.ts               |  59 ++++++
 app/photo-feed/use-photo-feed.test.ts | 149 +++++++++++++++
 app/photo-feed/use-photo-feed.ts      | 255 ++++++++++++++++++++++++++
 5 files changed, 898 insertions(+)
 create mode 100644 app/photo-feed/controller.test.ts
 create mode 100644 app/photo-feed/controller.ts
 create mode 100644 app/photo-feed/types.ts
 create mode 100644 app/photo-feed/use-photo-feed.test.ts
 create mode 100644 app/photo-feed/use-photo-feed.ts

diff --git a/app/photo-feed/controller.test.ts b/app/photo-feed/controller.test.ts
new file mode 100644
index 0000000..ee702f0
--- /dev/null
+++ b/app/photo-feed/controller.test.ts
@@ -0,0 +1,212 @@
+import { describe, expect, test } from "bun:test";
+import {
+  BROWSE_FEED_PROFILE,
+  PROJECTOR_FEED_PROFILE,
+  initialPhotoFeedState,
+  mergePhotoFeed,
+  reducePhotoFeed,
+} from "./controller";
+import type { FeedPhoto } from "./types";
+
+const a: FeedPhoto = { key: "events/show/a.jpg", url: "/a-old", uploadedAt: "2026-07-24T01:00:00Z" };
+const b: FeedPhoto = { key: "events/show/b.jpg", url: "/b", uploadedAt: "2026-07-24T00:00:00Z" };
+const c: FeedPhoto = { key: "events/show/c.jpg", url: "/c", uploadedAt: "2026-07-24T02:00:00Z" };
+
+describe("mergePhotoFeed", () => {
+  test("deduplicates exact keys, replaces stale copies, and keeps server order", () => {
+    const freshA = { ...a, url: "/a-fresh", uploadedAt: "2026-07-24T03:00:00Z" };
+    const result = mergePhotoFeed([a, b], [c, freshA, c]);
+
+    expect(result.photos).toEqual([c, freshA, b]);
+    expect(result.inserted).toEqual([c]);
+  });
+
+  test("an empty delta preserves the existing array", () => {
+    const current = [a, b];
+    expect(mergePhotoFeed(current, [])).toEqual({ photos: current, inserted: [] });
+  });
+});
+
+describe("reducePhotoFeed", () => {
+  test("starts one request and retains cursor for an empty or invalid-cursor delta", () => {
+    const started = reducePhotoFeed(initialPhotoFeedState("show"), { type: "start" });
+    expect(started.effects).toEqual([
+      { type: "request", requestId: 1, generation: 0, after: null },
+    ]);
+
+    const succeeded = reducePhotoFeed(started.state, {
+      type: "request-success",
+      requestId: 1,
+      generation: 0,
+      photos: [],
+      cursor: "",
+      profile: PROJECTOR_FEED_PROFILE,
+      random: 0,
+    });
+    expect(succeeded.state.cursor).toBeNull();
+    expect(succeeded.state.photos).toEqual([]);
+    expect(succeeded.state.status).toBe("ready");
+  });
+
+  test("changes Event by aborting, clearing state, and incrementing generation", () => {
+    let state = initialPhotoFeedState("show");
+    state = reducePhotoFeed(state, { type: "start" }).state;
+    state = { ...state, photos: [a], cursor: "cursor", error: "old" };
+
+    const changed = reducePhotoFeed(state, { type: "event-change", event: "other" });
+    expect(changed.state).toMatchObject({
+      event: "other",
+      photos: [],
+      cursor: null,
+      error: null,
+      generation: 1,
+    });
+    expect(changed.effects).toEqual([
+      { type: "abort", requestId: 1 },
+      { type: "cancel-schedule" },
+      { type: "request", requestId: 2, generation: 1, after: null },
+    ]);
+  });
+
+  test("ignores stale success, errors, and abort completions", () => {
+    const active = reducePhotoFeed(initialPhotoFeedState("show"), { type: "start" }).state;
+    for (const event of [
+      {
+        type: "request-success" as const,
+        requestId: 99,
+        generation: 0,
+        photos: [a],
+        cursor: "new",
+        profile: PROJECTOR_FEED_PROFILE,
+        random: 0,
+      },
+      { type: "request-error" as const, requestId: 99, generation: 0, error: "bad", profile: PROJECTOR_FEED_PROFILE, random: 0 },
+      { type: "request-aborted" as const, requestId: 99, generation: 0 },
+    ]) {
+      expect(reducePhotoFeed(active, event)).toEqual({ state: active, effects: [] });
+    }
+  });
+
+  test("serializes refresh by aborting the active request and requesting after settlement", () => {
+    const active = reducePhotoFeed(initialPhotoFeedState("show"), { type: "start" }).state;
+    const refreshed = reducePhotoFeed(active, { type: "refresh" });
+    expect(refreshed.state.refreshPending).toBeTrue();
+    expect(refreshed.effects).toEqual([{ type: "abort", requestId: 1 }]);
+
+    const settled = reducePhotoFeed(refreshed.state, {
+      type: "request-aborted",
+      requestId: 1,
+      generation: 0,
+    });
+    expect(settled.effects).toEqual([
+      { type: "request", requestId: 2, generation: 0, after: null },
+    ]);
+  });
+
+  test("refreshes immediately while idle", () => {
+    const result = reducePhotoFeed(initialPhotoFeedState("show"), { type: "refresh" });
+    expect(result.effects[0]).toEqual({
+      type: "request",
+      requestId: 1,
+      generation: 0,
+      after: null,
+    });
+  });
+
+  test("hidden aborts and retains photos; visible refreshes immediately", () => {
+    const active = {
+      ...reducePhotoFeed(initialPhotoFeedState("show"), { type: "start" }).state,
+      photos: [a],
+    };
+    const hidden = reducePhotoFeed(active, { type: "visibility", visible: false });
+    expect(hidden.state.photos).toEqual([a]);
+    expect(hidden.effects).toEqual([
+      { type: "abort", requestId: 1 },
+      { type: "cancel-schedule" },
+    ]);
+
+    const settled = reducePhotoFeed(hidden.state, {
+      type: "request-aborted",
+      requestId: 1,
+      generation: 0,
+    });
+    const visible = reducePhotoFeed(settled.state, { type: "visibility", visible: true });
+    expect(visible.effects).toEqual([
+      { type: "request", requestId: 2, generation: 0, after: null },
+    ]);
+  });
+
+  test("retains photos on failure, backs off with a cap, and success resets failures", () => {
+    const active = {
+      ...reducePhotoFeed(initialPhotoFeedState("show"), { type: "start" }).state,
+      photos: [a],
+    };
+    const failed = reducePhotoFeed(active, {
+      type: "request-error",
+      requestId: 1,
+      generation: 0,
+      error: "offline",
+      profile: PROJECTOR_FEED_PROFILE,
+      random: 1,
+    });
+    expect(failed.state.photos).toEqual([a]);
+    expect(failed.state.failureCount).toBe(1);
+    expect(failed.effects).toEqual([{ type: "schedule", delayMs: 4_000 }]);
+
+    const retry = reducePhotoFeed(failed.state, { type: "timer" }).state;
+    const success = reducePhotoFeed(retry, {
+      type: "request-success",
+      requestId: 2,
+      generation: 0,
+      photos: [c],
+      cursor: "next",
+      profile: PROJECTOR_FEED_PROFILE,
+      random: 0,
+    });
+    expect(success.state.failureCount).toBe(0);
+    expect(success.state.error).toBeNull();
+  });
+
+  test("uses exact active, quiet, and capped error cadence from injected random", () => {
+    expect(PROJECTOR_FEED_PROFILE.activeMs).toBe(2_000);
+    expect(BROWSE_FEED_PROFILE.activeMs).toBe(3_500);
+
+    let state = reducePhotoFeed(initialPhotoFeedState("show"), { type: "start" }).state;
+    let result = reducePhotoFeed(state, {
+      type: "request-success",
+      requestId: 1,
+      generation: 0,
+      photos: [a],
+      cursor: "one",
+      profile: PROJECTOR_FEED_PROFILE,
+      random: 0.5,
+    });
+    expect(result.effects).toEqual([{ type: "schedule", delayMs: 2_000 }]);
+
+    state = reducePhotoFeed(result.state, { type: "timer" }).state;
+    result = reducePhotoFeed(state, {
+      type: "request-success",
+      requestId: 2,
+      generation: 0,
+      photos: [],
+      cursor: null,
+      profile: PROJECTOR_FEED_PROFILE,
+      random: 1,
+    });
+    expect(result.effects).toEqual([{ type: "schedule", delayMs: 20_000 }]);
+
+    state = {
+      ...reducePhotoFeed(result.state, { type: "timer" }).state,
+      failureCount: 20,
+    };
+    result = reducePhotoFeed(state, {
+      type: "request-error",
+      requestId: 3,
+      generation: 0,
+      error: "still offline",
+      profile: PROJECTOR_FEED_PROFILE,
+      random: 1,
+    });
+    expect(result.effects).toEqual([{ type: "schedule", delayMs: 60_000 }]);
+  });
+});
diff --git a/app/photo-feed/controller.ts b/app/photo-feed/controller.ts
new file mode 100644
index 0000000..979360b
--- /dev/null
+++ b/app/photo-feed/controller.ts
@@ -0,0 +1,223 @@
+import type {
+  FeedPhoto,
+  FeedProfile,
+  PhotoFeedEffect,
+  PhotoFeedEvent,
+  PhotoFeedState,
+} from "./types";
+
+export const PROJECTOR_FEED_PROFILE: FeedProfile = {
+  activeMs: 2_000,
+  quietMinMs: 10_000,
+  quietMaxMs: 20_000,
+  errorBaseMs: 4_000,
+  errorMaxMs: 60_000,
+};
+
+export const BROWSE_FEED_PROFILE: FeedProfile = {
+  activeMs: 3_500,
+  quietMinMs: 10_000,
+  quietMaxMs: 20_000,
+  errorBaseMs: 4_000,
+  errorMaxMs: 60_000,
+};
+
+export function initialPhotoFeedState(event: string, visible = true): PhotoFeedState {
+  return {
+    event,
+    photos: [],
+    cursor: null,
+    status: "loading",
+    visible,
+    request: null,
+    refreshPending: false,
+    quietCount: 0,
+    failureCount: 0,
+    error: null,
+    generation: 0,
+    nextRequestId: 1,
+  };
+}
+
+export function mergePhotoFeed(
+  current: readonly FeedPhoto[],
+  incoming: readonly FeedPhoto[],
+): { photos: FeedPhoto[]; inserted: FeedPhoto[] } {
+  if (incoming.length === 0) return { photos: current as FeedPhoto[], inserted: [] };
+
+  const currentKeys = new Set(current.map((photo) => photo.key));
+  const incomingKeys = new Set<string>();
+  const uniqueIncoming: FeedPhoto[] = [];
+  for (const photo of incoming) {
+    if (incomingKeys.has(photo.key)) continue;
+    incomingKeys.add(photo.key);
+    uniqueIncoming.push(photo);
+  }
+
+  const photos = [
+    ...uniqueIncoming,
+    ...current.filter((photo) => !incomingKeys.has(photo.key)),
+  ];
+  return {
+    photos,
+    inserted: uniqueIncoming.filter((photo) => !currentKeys.has(photo.key)),
+  };
+}
+
+function startRequest(
+  state: PhotoFeedState,
+): { state: PhotoFeedState; effects: PhotoFeedEffect[] } {
+  if (!state.visible || state.request) return { state, effects: [] };
+  const id = state.nextRequestId;
+  const request = { id, after: state.cursor };
+  return {
+    state: {
+      ...state,
+      request,
+      nextRequestId: id + 1,
+      refreshPending: false,
+      status: state.photos.length === 0 ? "loading" : state.status,
+    },
+    effects: [
+      {
+        type: "request",
+        requestId: id,
+        generation: state.generation,
+        after: state.cursor,
+      },
+    ],
+  };
+}
+
+function matchesRequest(
+  state: PhotoFeedState,
+  requestId: number,
+  generation: number,
+): boolean {
+  return state.generation === generation && state.request?.id === requestId;
+}
+
+function unitRandom(value: number): number {
+  return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+
+function quietDelay(profile: FeedProfile, random: number): number {
+  const range = Math.max(0, profile.quietMaxMs - profile.quietMinMs);
+  return Math.round(profile.quietMinMs + range * unitRandom(random));
+}
+
+function errorDelay(profile: FeedProfile, failures: number, random: number): number {
+  const exponential = profile.errorBaseMs * 2 ** Math.max(0, failures - 1);
+  const jittered = exponential * (0.5 + unitRandom(random) * 0.5);
+  return Math.min(profile.errorMaxMs, Math.round(jittered));
+}
+
+export function reducePhotoFeed(
+  state: PhotoFeedState,
+  event: PhotoFeedEvent,
+): { state: PhotoFeedState; effects: PhotoFeedEffect[] } {
+  switch (event.type) {
+    case "start":
+    case "timer":
+      return startRequest(state);
+
+    case "event-change": {
+      if (event.event === state.event) return { state, effects: [] };
+      const effects: PhotoFeedEffect[] = [];
+      if (state.request) effects.push({ type: "abort", requestId: state.request.id });
+      effects.push({ type: "cancel-schedule" });
+      const reset: PhotoFeedState = {
+        ...initialPhotoFeedState(event.event, state.visible),
+        generation: state.generation + 1,
+        nextRequestId: state.nextRequestId,
+      };
+      const started = startRequest(reset);
+      return { state: started.state, effects: [...effects, ...started.effects] };
+    }
+
+    case "visibility": {
+      if (event.visible === state.visible) return { state, effects: [] };
+      if (!event.visible) {
+        const effects: PhotoFeedEffect[] = [];
+        if (state.request) effects.push({ type: "abort", requestId: state.request.id });
+        effects.push({ type: "cancel-schedule" });
+        return { state: { ...state, visible: false, refreshPending: false }, effects };
+      }
+      const visible = { ...state, visible: true };
+      if (visible.request) return { state: { ...visible, refreshPending: true }, effects: [] };
+      return startRequest(visible);
+    }
+
+    case "refresh":
+      if (state.request) {
+        if (state.refreshPending) return { state, effects: [] };
+        return {
+          state: { ...state, refreshPending: true },
+          effects: [{ type: "abort", requestId: state.request.id }],
+        };
+      }
+      return startRequest(state);
+
+    case "request-aborted": {
+      if (!matchesRequest(state, event.requestId, event.generation)) {
+        return { state, effects: [] };
+      }
+      const settled = { ...state, request: null };
+      if (settled.visible && settled.refreshPending) {
+        return startRequest({ ...settled, refreshPending: false });
+      }
+      return { state: { ...settled, refreshPending: false }, effects: [] };
+    }
+
+    case "request-success": {
+      if (!matchesRequest(state, event.requestId, event.generation)) {
+        return { state, effects: [] };
+      }
+      const merged = mergePhotoFeed(state.photos, event.photos);
+      const quietCount = merged.inserted.length === 0 ? state.quietCount + 1 : 0;
+      const next: PhotoFeedState = {
+        ...state,
+        photos: merged.photos,
+        cursor:
+          typeof event.cursor === "string" && event.cursor.length > 0
+            ? event.cursor
+            : state.cursor,
+        status: "ready",
+        request: null,
+        refreshPending: false,
+        quietCount,
+        failureCount: 0,
+        error: null,
+      };
+      const delayMs =
+        merged.inserted.length > 0
+          ? event.profile.activeMs
+          : quietDelay(event.profile, event.random);
+      return {
+        state: next,
+        effects: next.visible ? [{ type: "schedule", delayMs }] : [],
+      };
+    }
+
+    case "request-error": {
+      if (!matchesRequest(state, event.requestId, event.generation)) {
+        return { state, effects: [] };
+      }
+      const failureCount = state.failureCount + 1;
+      const next: PhotoFeedState = {
+        ...state,
+        status: "error",
+        request: null,
+        refreshPending: false,
+        failureCount,
+        error: event.error,
+      };
+      return {
+        state: next,
+        effects: next.visible
+          ? [{ type: "schedule", delayMs: errorDelay(event.profile, failureCount, event.random) }]
+          : [],
+      };
+    }
+  }
+}
diff --git a/app/photo-feed/types.ts b/app/photo-feed/types.ts
new file mode 100644
index 0000000..6dc9cbd
--- /dev/null
+++ b/app/photo-feed/types.ts
@@ -0,0 +1,59 @@
+export type FeedPhoto = {
+  key: string;
+  url: string;
+  uploadedAt: string;
+};
+
+export type FeedProfile = {
+  activeMs: number;
+  quietMinMs: number;
+  quietMaxMs: number;
+  errorBaseMs: number;
+  errorMaxMs: number;
+};
+
+export type PhotoFeedState = {
+  event: string;
+  photos: FeedPhoto[];
+  cursor: string | null;
+  status: "loading" | "ready" | "error";
+  visible: boolean;
+  request: { id: number; after: string | null } | null;
+  refreshPending: boolean;
+  quietCount: number;
+  failureCount: number;
+  error: string | null;
+  generation: number;
+  nextRequestId: number;
+};
+
+export type PhotoFeedEvent =
+  | { type: "start" }
+  | { type: "event-change"; event: string }
+  | { type: "visibility"; visible: boolean }
+  | { type: "refresh" }
+  | { type: "timer" }
+  | {
+      type: "request-success";
+      requestId: number;
+      generation: number;
+      photos: FeedPhoto[];
+      cursor: string | null;
+      profile: FeedProfile;
+      random: number;
+    }
+  | {
+      type: "request-error";
+      requestId: number;
+      generation: number;
+      error: string;
+      profile: FeedProfile;
+      random: number;
+    }
+  | { type: "request-aborted"; requestId: number; generation: number };
+
+export type PhotoFeedEffect =
+  | { type: "request"; requestId: number; generation: number; after: string | null }
+  | { type: "abort"; requestId: number }
+  | { type: "schedule"; delayMs: number }
+  | { type: "cancel-schedule" };
diff --git a/app/photo-feed/use-photo-feed.test.ts b/app/photo-feed/use-photo-feed.test.ts
new file mode 100644
index 0000000..8a2d9ba
--- /dev/null
+++ b/app/photo-feed/use-photo-feed.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test";
+import { PhotoFeedRuntime, type PhotoFeedRuntimeProviders } from "./use-photo-feed";
+import { PROJECTOR_FEED_PROFILE } from "./controller";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+
+function harness() {
+  const requests: Array<{
+    url: string;
+    signal: AbortSignal;
+    response: ReturnType<typeof deferred<unknown>>;
+  }> = [];
+  const timers = new Map<number, () => void>();
+  let nextTimer = 1;
+  let visible = true;
+  const visibilityListeners = new Set<() => void>();
+  const providers: PhotoFeedRuntimeProviders = {
+    fetch: (url, init) => {
+      const response = deferred<unknown>();
+      requests.push({ url, signal: init.signal, response });
+      return response.promise;
+    },
+    random: () => 0,
+    timer: {
+      setTimeout(callback) {
+        const id = nextTimer++;
+        timers.set(id, callback);
+        return id;
+      },
+      clearTimeout(handle) {
+        timers.delete(handle as number);
+      },
+    },
+    visibility: {
+      isVisible: () => visible,
+      subscribe(listener) {
+        visibilityListeners.add(listener);
+        return () => visibilityListeners.delete(listener);
+      },
+    },
+  };
+  return {
+    providers,
+    requests,
+    timers,
+    setVisible(value: boolean) {
+      visible = value;
+      visibilityListeners.forEach((listener) => listener());
+    },
+  };
+}
+
+describe("PhotoFeedRuntime", () => {
+  test("validates a response and exposes latest inserted photos", async () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    expect(h.requests[0]?.url).toBe("/api/photos?event=show");
+
+    h.requests[0]!.response.resolve({
+      photos: [{ key: "events/show/a.jpg", url: "/a", uploadedAt: "2026-07-24T00:00:00Z" }],
+      cursor: "opaque",
+      ignored: true,
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(runtime.snapshot().photos).toHaveLength(1);
+    expect(runtime.snapshot().inserted.map((photo) => photo.key)).toEqual(["events/show/a.jpg"]);
+    expect(h.timers.size).toBe(1);
+  });
+
+  test("malformed responses retain photos and enter retryable error state", async () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    h.requests[0]!.response.resolve({ photos: [{ key: 1 }], cursor: "bad" });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(runtime.snapshot()).toMatchObject({ photos: [], status: "error" });
+    expect(h.timers.size).toBe(1);
+  });
+
+  test("awaits abort settlement before starting a queued refresh", async () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    runtime.refresh();
+
+    expect(h.requests).toHaveLength(1);
+    expect(h.requests[0]!.signal.aborted).toBeTrue();
+    h.requests[0]!.response.reject(new DOMException("Aborted", "AbortError"));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(h.requests).toHaveLength(2);
+  });
+
+  test("an aborted request that resolves cannot apply stale photos or consume the refresh", async () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    runtime.refresh();
+    h.requests[0]!.response.resolve({
+      photos: [{ key: "events/show/stale.jpg", url: "/stale", uploadedAt: "2026-07-24T00:00:00Z" }],
+      cursor: "stale",
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(runtime.snapshot().photos).toEqual([]);
+    expect(h.requests).toHaveLength(2);
+  });
+
+  test("cancels timers while hidden and refreshes on foreground", async () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    h.requests[0]!.response.resolve({ photos: [], cursor: null });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(h.timers.size).toBe(1);
+
+    h.setVisible(false);
+    expect(h.timers.size).toBe(0);
+    h.setVisible(true);
+    expect(h.requests).toHaveLength(2);
+  });
+
+  test("event change and disposal abort active work and reset state", () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    runtime.setEvent("other");
+    expect(h.requests[0]!.signal.aborted).toBeTrue();
+    expect(runtime.snapshot()).toMatchObject({ event: "other", photos: [], cursor: null });
+
+    runtime.dispose();
+    expect(h.requests.at(-1)!.signal.aborted).toBeTrue();
+  });
+});
diff --git a/app/photo-feed/use-photo-feed.ts b/app/photo-feed/use-photo-feed.ts
new file mode 100644
index 0000000..65b9010
--- /dev/null
+++ b/app/photo-feed/use-photo-feed.ts
@@ -0,0 +1,255 @@
+"use client";
+
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { initialPhotoFeedState, reducePhotoFeed } from "./controller";
+import type {
+  FeedPhoto,
+  FeedProfile,
+  PhotoFeedEffect,
+  PhotoFeedEvent,
+  PhotoFeedState,
+} from "./types";
+
+export type PhotoFeedSnapshot = PhotoFeedState & { inserted: FeedPhoto[] };
+
+export type PhotoFeedRuntimeProviders = {
+  fetch(url: string, init: { signal: AbortSignal }): Promise<unknown>;
+  random(): number;
+  timer: {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+  };
+  visibility: {
+    isVisible(): boolean;
+    subscribe(listener: () => void): () => void;
+  };
+};
+
+function parsePhoto(value: unknown): FeedPhoto | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  if (
+    typeof record.key !== "string" ||
+    record.key.length === 0 ||
+    typeof record.url !== "string" ||
+    record.url.length === 0 ||
+    typeof record.uploadedAt !== "string" ||
+    record.uploadedAt.length === 0 ||
+    Number.isNaN(Date.parse(record.uploadedAt))
+  ) {
+    return null;
+  }
+  return { key: record.key, url: record.url, uploadedAt: record.uploadedAt };
+}
+
+export function parsePhotoFeedResponse(
+  value: unknown,
+): { photos: FeedPhoto[]; cursor: string | null } {
+  if (!value || typeof value !== "object") throw new Error("Invalid photo feed response");
+  const record = value as Record<string, unknown>;
+  if (!Array.isArray(record.photos)) throw new Error("Invalid photo feed photos");
+  if (record.cursor !== null && (typeof record.cursor !== "string" || record.cursor.length === 0)) {
+    throw new Error("Invalid photo feed cursor");
+  }
+  const photos = record.photos.map(parsePhoto);
+  if (photos.some((photo) => photo === null)) throw new Error("Invalid photo feed photo");
+  return { photos: photos as FeedPhoto[], cursor: record.cursor as string | null };
+}
+
+function browserProviders(): PhotoFeedRuntimeProviders {
+  return {
+    async fetch(url, init) {
+      const response = await fetch(url, { signal: init.signal, cache: "no-store" });
+      if (!response.ok) throw new Error(`Photo feed request failed (${response.status})`);
+      return response.json();
+    },
+    random: Math.random,
+    timer: {
+      setTimeout: (callback, ms) => window.setTimeout(callback, ms),
+      clearTimeout: (handle) => window.clearTimeout(handle as number),
+    },
+    visibility: {
+      isVisible: () => document.visibilityState !== "hidden",
+      subscribe(listener) {
+        document.addEventListener("visibilitychange", listener);
+        return () => document.removeEventListener("visibilitychange", listener);
+      },
+    },
+  };
+}
+
+export class PhotoFeedRuntime {
+  private state: PhotoFeedState;
+  private currentSnapshot: PhotoFeedSnapshot;
+  private readonly listeners = new Set<() => void>();
+  private controller: AbortController | null = null;
+  private timer: unknown = null;
+  private unsubscribeVisibility: (() => void) | null = null;
+  private started = false;
+  private disposed = false;
+
+  constructor(
+    event: string,
+    private readonly profile: FeedProfile,
+    private readonly providers: PhotoFeedRuntimeProviders,
+  ) {
+    this.state = initialPhotoFeedState(event, providers.visibility.isVisible());
+    this.currentSnapshot = { ...this.state, inserted: [] };
+  }
+
+  snapshot = (): PhotoFeedSnapshot => this.currentSnapshot;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  start(): void {
+    if (this.started || this.disposed) return;
+    this.started = true;
+    this.unsubscribeVisibility = this.providers.visibility.subscribe(() => {
+      this.dispatch({
+        type: "visibility",
+        visible: this.providers.visibility.isVisible(),
+      });
+    });
+    this.dispatch({ type: "start" });
+  }
+
+  refresh = (): void => {
+    this.dispatch({ type: "refresh" });
+  };
+
+  setEvent(event: string): void {
+    this.dispatch({ type: "event-change", event });
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.controller?.abort();
+    this.controller = null;
+    this.clearTimer();
+    this.unsubscribeVisibility?.();
+    this.unsubscribeVisibility = null;
+    this.listeners.clear();
+  }
+
+  private dispatch(event: PhotoFeedEvent): void {
+    if (this.disposed) return;
+    const result = reducePhotoFeed(this.state, event);
+    const changed = result.state !== this.state;
+    this.state = result.state;
+    const inserted =
+      event.type === "request-success" && changed
+        ? this.state.photos.filter(
+            (photo) =>
+              event.photos.some((candidate) => candidate.key === photo.key) &&
+              !this.currentSnapshot.photos.some((prior) => prior.key === photo.key),
+          )
+        : [];
+    if (changed) {
+      this.currentSnapshot = { ...this.state, inserted };
+      this.listeners.forEach((listener) => listener());
+    }
+    result.effects.forEach((effect) => this.execute(effect));
+  }
+
+  private execute(effect: PhotoFeedEffect): void {
+    if (this.disposed) return;
+    switch (effect.type) {
+      case "abort":
+        this.controller?.abort();
+        return;
+      case "cancel-schedule":
+        this.clearTimer();
+        return;
+      case "schedule":
+        this.clearTimer();
+        this.timer = this.providers.timer.setTimeout(() => {
+          this.timer = null;
+          this.dispatch({ type: "timer" });
+        }, effect.delayMs);
+        return;
+      case "request":
+        this.request(effect);
+        return;
+    }
+  }
+
+  private request(
+    effect: Extract<PhotoFeedEffect, { type: "request" }>,
+  ): void {
+    this.clearTimer();
+    const controller = new AbortController();
+    this.controller = controller;
+    const search = new URLSearchParams({ event: this.state.event });
+    if (effect.after !== null) search.set("after", effect.after);
+    void this.providers
+      .fetch(`/api/photos?${search.toString()}`, { signal: controller.signal })
+      .then((raw) => {
+        if (controller.signal.aborted) {
+          this.dispatch({
+            type: "request-aborted",
+            requestId: effect.requestId,
+            generation: effect.generation,
+          });
+          return;
+        }
+        const response = parsePhotoFeedResponse(raw);
+        this.dispatch({
+          type: "request-success",
+          requestId: effect.requestId,
+          generation: effect.generation,
+          photos: response.photos,
+          cursor: response.cursor,
+          profile: this.profile,
+          random: this.providers.random(),
+        });
+      })
+      .catch((error: unknown) => {
+        if (controller.signal.aborted) {
+          this.dispatch({
+            type: "request-aborted",
+            requestId: effect.requestId,
+            generation: effect.generation,
+          });
+          return;
+        }
+        this.dispatch({
+          type: "request-error",
+          requestId: effect.requestId,
+          generation: effect.generation,
+          error: error instanceof Error ? error.message : "Photo feed request failed",
+          profile: this.profile,
+          random: this.providers.random(),
+        });
+      })
+      .finally(() => {
+        if (this.controller === controller) this.controller = null;
+      });
+  }
+
+  private clearTimer(): void {
+    if (this.timer === null) return;
+    this.providers.timer.clearTimeout(this.timer);
+    this.timer = null;
+  }
+}
+
+export function usePhotoFeed(
+  event: string,
+  profile: FeedProfile,
+  providers?: PhotoFeedRuntimeProviders,
+): PhotoFeedSnapshot & { refresh(): void } {
+  const runtime = useMemo(
+    () => new PhotoFeedRuntime(event, profile, providers ?? browserProviders()),
+    [event, profile, providers],
+  );
+  useEffect(() => {
+    runtime.start();
+    return () => runtime.dispose();
+  }, [runtime]);
+  const snapshot = useSyncExternalStore(runtime.subscribe, runtime.snapshot, runtime.snapshot);
+  return { ...snapshot, refresh: runtime.refresh };
+}

From 03ecc111ecf5d0f124a415213cdfdd32beae6fd8 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:57:19 +0800
Subject: [PATCH 057/105] fix: serialize photo feed event changes

---
 app/photo-feed/use-photo-feed.test.ts | 36 +++++++++++++++++++--------
 app/photo-feed/use-photo-feed.ts      | 30 +++++++++++++++++++---
 2 files changed, 53 insertions(+), 13 deletions(-)

diff --git a/app/photo-feed/use-photo-feed.test.ts b/app/photo-feed/use-photo-feed.test.ts
index 8a2d9ba..4bf8075 100644
--- a/app/photo-feed/use-photo-feed.test.ts
+++ b/app/photo-feed/use-photo-feed.test.ts
@@ -12,6 +12,13 @@ function deferred<T>() {
   return { promise, resolve, reject };
 }
 
+async function flushPromises() {
+  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
 function harness() {
   const requests: Array<{
     url: string;
@@ -70,8 +77,7 @@ describe("PhotoFeedRuntime", () => {
       cursor: "opaque",
       ignored: true,
     });
-    await Promise.resolve();
-    await Promise.resolve();
+    await flushPromises();
 
     expect(runtime.snapshot().photos).toHaveLength(1);
     expect(runtime.snapshot().inserted.map((photo) => photo.key)).toEqual(["events/show/a.jpg"]);
@@ -83,8 +89,7 @@ describe("PhotoFeedRuntime", () => {
     const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
     runtime.start();
     h.requests[0]!.response.resolve({ photos: [{ key: 1 }], cursor: "bad" });
-    await Promise.resolve();
-    await Promise.resolve();
+    await flushPromises();
 
     expect(runtime.snapshot()).toMatchObject({ photos: [], status: "error" });
     expect(h.timers.size).toBe(1);
@@ -99,8 +104,7 @@ describe("PhotoFeedRuntime", () => {
     expect(h.requests).toHaveLength(1);
     expect(h.requests[0]!.signal.aborted).toBeTrue();
     h.requests[0]!.response.reject(new DOMException("Aborted", "AbortError"));
-    await Promise.resolve();
-    await Promise.resolve();
+    await flushPromises();
     expect(h.requests).toHaveLength(2);
   });
 
@@ -113,8 +117,7 @@ describe("PhotoFeedRuntime", () => {
       photos: [{ key: "events/show/stale.jpg", url: "/stale", uploadedAt: "2026-07-24T00:00:00Z" }],
       cursor: "stale",
     });
-    await Promise.resolve();
-    await Promise.resolve();
+    await flushPromises();
 
     expect(runtime.snapshot().photos).toEqual([]);
     expect(h.requests).toHaveLength(2);
@@ -125,8 +128,7 @@ describe("PhotoFeedRuntime", () => {
     const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
     runtime.start();
     h.requests[0]!.response.resolve({ photos: [], cursor: null });
-    await Promise.resolve();
-    await Promise.resolve();
+    await flushPromises();
     expect(h.timers.size).toBe(1);
 
     h.setVisible(false);
@@ -146,4 +148,18 @@ describe("PhotoFeedRuntime", () => {
     runtime.dispose();
     expect(h.requests.at(-1)!.signal.aborted).toBeTrue();
   });
+
+  test("event change queues the new Event until the aborted request settles", async () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    runtime.setEvent("other");
+
+    expect(h.requests).toHaveLength(1);
+    h.requests[0]!.response.resolve({ photos: [], cursor: null });
+    await flushPromises();
+
+    expect(h.requests).toHaveLength(2);
+    expect(h.requests[1]!.url).toBe("/api/photos?event=other");
+  });
 });
diff --git a/app/photo-feed/use-photo-feed.ts b/app/photo-feed/use-photo-feed.ts
index 65b9010..15c49f7 100644
--- a/app/photo-feed/use-photo-feed.ts
+++ b/app/photo-feed/use-photo-feed.ts
@@ -83,6 +83,8 @@ export class PhotoFeedRuntime {
   private currentSnapshot: PhotoFeedSnapshot;
   private readonly listeners = new Set<() => void>();
   private controller: AbortController | null = null;
+  private activeRequest: Extract<PhotoFeedEffect, { type: "request" }> | null = null;
+  private queuedRequest: Extract<PhotoFeedEffect, { type: "request" }> | null = null;
   private timer: unknown = null;
   private unsubscribeVisibility: (() => void) | null = null;
   private started = false;
@@ -129,6 +131,8 @@ export class PhotoFeedRuntime {
     this.disposed = true;
     this.controller?.abort();
     this.controller = null;
+    this.activeRequest = null;
+    this.queuedRequest = null;
     this.clearTimer();
     this.unsubscribeVisibility?.();
     this.unsubscribeVisibility = null;
@@ -158,9 +162,19 @@ export class PhotoFeedRuntime {
   private execute(effect: PhotoFeedEffect): void {
     if (this.disposed) return;
     switch (effect.type) {
-      case "abort":
-        this.controller?.abort();
+      case "abort": {
+        if (this.queuedRequest?.requestId === effect.requestId) {
+          const queued = this.queuedRequest;
+          this.queuedRequest = null;
+          this.dispatch({
+            type: "request-aborted",
+            requestId: queued.requestId,
+            generation: queued.generation,
+          });
+        }
+        if (this.activeRequest?.requestId === effect.requestId) this.controller?.abort();
         return;
+      }
       case "cancel-schedule":
         this.clearTimer();
         return;
@@ -181,8 +195,13 @@ export class PhotoFeedRuntime {
     effect: Extract<PhotoFeedEffect, { type: "request" }>,
   ): void {
     this.clearTimer();
+    if (this.activeRequest) {
+      this.queuedRequest = effect;
+      return;
+    }
     const controller = new AbortController();
     this.controller = controller;
+    this.activeRequest = effect;
     const search = new URLSearchParams({ event: this.state.event });
     if (effect.after !== null) search.set("after", effect.after);
     void this.providers
@@ -226,7 +245,12 @@ export class PhotoFeedRuntime {
         });
       })
       .finally(() => {
-        if (this.controller === controller) this.controller = null;
+        if (this.controller !== controller) return;
+        this.controller = null;
+        this.activeRequest = null;
+        const queued = this.queuedRequest;
+        this.queuedRequest = null;
+        if (queued) this.request(queued);
       });
   }
 

From 71efef9aa11636ec34817e2d61c3ad786aaa125e Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:13:00 +0800
Subject: [PATCH 058/105] fix: harden adaptive photo feed lifecycle

---
 app/photo-feed/controller.test.ts     | 30 ++++++++++++++++-----------
 app/photo-feed/controller.ts          | 12 ++++++++---
 app/photo-feed/use-photo-feed.test.ts | 17 ++++++++++++++-
 app/photo-feed/use-photo-feed.ts      | 15 +++++++++++---
 4 files changed, 55 insertions(+), 19 deletions(-)

diff --git a/app/photo-feed/controller.test.ts b/app/photo-feed/controller.test.ts
index ee702f0..a819755 100644
--- a/app/photo-feed/controller.test.ts
+++ b/app/photo-feed/controller.test.ts
@@ -183,17 +183,23 @@ describe("reducePhotoFeed", () => {
     });
     expect(result.effects).toEqual([{ type: "schedule", delayMs: 2_000 }]);
 
-    state = reducePhotoFeed(result.state, { type: "timer" }).state;
-    result = reducePhotoFeed(state, {
-      type: "request-success",
-      requestId: 2,
-      generation: 0,
-      photos: [],
-      cursor: null,
-      profile: PROJECTOR_FEED_PROFILE,
-      random: 1,
-    });
-    expect(result.effects).toEqual([{ type: "schedule", delayMs: 20_000 }]);
+    const quietDelays: number[] = [];
+    for (let requestId = 2; requestId <= 5; requestId += 1) {
+      state = reducePhotoFeed(result.state, { type: "timer" }).state;
+      result = reducePhotoFeed(state, {
+        type: "request-success",
+        requestId,
+        generation: 0,
+        photos: [],
+        cursor: null,
+        profile: PROJECTOR_FEED_PROFILE,
+        random: 0,
+      });
+      quietDelays.push(
+        (result.effects[0] as { type: "schedule"; delayMs: number }).delayMs,
+      );
+    }
+    expect(quietDelays).toEqual([10_000, 13_333, 16_667, 20_000]);
 
     state = {
       ...reducePhotoFeed(result.state, { type: "timer" }).state,
@@ -201,7 +207,7 @@ describe("reducePhotoFeed", () => {
     };
     result = reducePhotoFeed(state, {
       type: "request-error",
-      requestId: 3,
+      requestId: 6,
       generation: 0,
       error: "still offline",
       profile: PROJECTOR_FEED_PROFILE,
diff --git a/app/photo-feed/controller.ts b/app/photo-feed/controller.ts
index 979360b..4e3d47f 100644
--- a/app/photo-feed/controller.ts
+++ b/app/photo-feed/controller.ts
@@ -101,9 +101,15 @@ function unitRandom(value: number): number {
   return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
 }
 
-function quietDelay(profile: FeedProfile, random: number): number {
+function quietDelay(profile: FeedProfile, quietCount: number, random: number): number {
   const range = Math.max(0, profile.quietMaxMs - profile.quietMinMs);
-  return Math.round(profile.quietMinMs + range * unitRandom(random));
+  const step = range / 3;
+  const floor = Math.min(
+    profile.quietMaxMs,
+    profile.quietMinMs + step * Math.max(0, quietCount - 1),
+  );
+  const ceiling = Math.min(profile.quietMaxMs, floor + step);
+  return Math.round(floor + (ceiling - floor) * unitRandom(random));
 }
 
 function errorDelay(profile: FeedProfile, failures: number, random: number): number {
@@ -192,7 +198,7 @@ export function reducePhotoFeed(
       const delayMs =
         merged.inserted.length > 0
           ? event.profile.activeMs
-          : quietDelay(event.profile, event.random);
+          : quietDelay(event.profile, quietCount, event.random);
       return {
         state: next,
         effects: next.visible ? [{ type: "schedule", delayMs }] : [],
diff --git a/app/photo-feed/use-photo-feed.test.ts b/app/photo-feed/use-photo-feed.test.ts
index 4bf8075..e3edb9d 100644
--- a/app/photo-feed/use-photo-feed.test.ts
+++ b/app/photo-feed/use-photo-feed.test.ts
@@ -1,5 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { PhotoFeedRuntime, type PhotoFeedRuntimeProviders } from "./use-photo-feed";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+  PhotoFeedRuntime,
+  usePhotoFeed,
+  type PhotoFeedRuntimeProviders,
+} from "./use-photo-feed";
 import { PROJECTOR_FEED_PROFILE } from "./controller";
 
 function deferred<T>() {
@@ -66,6 +72,15 @@ function harness() {
 }
 
 describe("PhotoFeedRuntime", () => {
+  test("the production hook is safe during Next server rendering", () => {
+    function Probe() {
+      const feed = usePhotoFeed("show", PROJECTOR_FEED_PROFILE);
+      return createElement("span", null, feed.status);
+    }
+
+    expect(() => renderToString(createElement(Probe))).not.toThrow();
+  });
+
   test("validates a response and exposes latest inserted photos", async () => {
     const h = harness();
     const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
diff --git a/app/photo-feed/use-photo-feed.ts b/app/photo-feed/use-photo-feed.ts
index 15c49f7..646e36c 100644
--- a/app/photo-feed/use-photo-feed.ts
+++ b/app/photo-feed/use-photo-feed.ts
@@ -69,8 +69,10 @@ function browserProviders(): PhotoFeedRuntimeProviders {
       clearTimeout: (handle) => window.clearTimeout(handle as number),
     },
     visibility: {
-      isVisible: () => document.visibilityState !== "hidden",
+      isVisible: () =>
+        typeof document === "undefined" || document.visibilityState !== "hidden",
       subscribe(listener) {
+        if (typeof document === "undefined") return () => {};
         document.addEventListener("visibilitychange", listener);
         return () => document.removeEventListener("visibilitychange", listener);
       },
@@ -266,14 +268,21 @@ export function usePhotoFeed(
   profile: FeedProfile,
   providers?: PhotoFeedRuntimeProviders,
 ): PhotoFeedSnapshot & { refresh(): void } {
+  const resolvedProviders = useMemo(
+    () => providers ?? browserProviders(),
+    [providers],
+  );
   const runtime = useMemo(
-    () => new PhotoFeedRuntime(event, profile, providers ?? browserProviders()),
-    [event, profile, providers],
+    () => new PhotoFeedRuntime(event, profile, resolvedProviders),
+    [profile, resolvedProviders],
   );
   useEffect(() => {
     runtime.start();
     return () => runtime.dispose();
   }, [runtime]);
+  useEffect(() => {
+    runtime.setEvent(event);
+  }, [event, runtime]);
   const snapshot = useSyncExternalStore(runtime.subscribe, runtime.snapshot, runtime.snapshot);
   return { ...snapshot, refresh: runtime.refresh };
 }

From eebbd5c0fe9093411f47bdfa4f5e63ac517459be Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:18:37 +0800
Subject: [PATCH 059/105] fix: restart photo feed under strict mode

---
 app/photo-feed/use-photo-feed.test.ts | 16 ++++++++++++++++
 app/photo-feed/use-photo-feed.ts      | 26 +++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/app/photo-feed/use-photo-feed.test.ts b/app/photo-feed/use-photo-feed.test.ts
index e3edb9d..041e4bf 100644
--- a/app/photo-feed/use-photo-feed.test.ts
+++ b/app/photo-feed/use-photo-feed.test.ts
@@ -177,4 +177,20 @@ describe("PhotoFeedRuntime", () => {
     expect(h.requests).toHaveLength(2);
     expect(h.requests[1]!.url).toBe("/api/photos?event=other");
   });
+
+  test("StrictMode-style suspend and restart waits for abort then requests again", async () => {
+    const h = harness();
+    const runtime = new PhotoFeedRuntime("show", PROJECTOR_FEED_PROFILE, h.providers);
+    runtime.start();
+    runtime.suspend();
+    runtime.start();
+
+    expect(h.requests).toHaveLength(1);
+    expect(h.requests[0]!.signal.aborted).toBeTrue();
+    h.requests[0]!.response.reject(new DOMException("Aborted", "AbortError"));
+    await flushPromises();
+
+    expect(h.requests).toHaveLength(2);
+    expect(h.requests[1]!.url).toBe("/api/photos?event=show");
+  });
 });
diff --git a/app/photo-feed/use-photo-feed.ts b/app/photo-feed/use-photo-feed.ts
index 646e36c..d925d78 100644
--- a/app/photo-feed/use-photo-feed.ts
+++ b/app/photo-feed/use-photo-feed.ts
@@ -117,6 +117,10 @@ export class PhotoFeedRuntime {
         visible: this.providers.visibility.isVisible(),
       });
     });
+    this.dispatch({
+      type: "visibility",
+      visible: this.providers.visibility.isVisible(),
+    });
     this.dispatch({ type: "start" });
   }
 
@@ -128,9 +132,29 @@ export class PhotoFeedRuntime {
     this.dispatch({ type: "event-change", event });
   }
 
+  suspend(): void {
+    if (!this.started || this.disposed) return;
+    this.started = false;
+    this.clearTimer();
+    this.unsubscribeVisibility?.();
+    this.unsubscribeVisibility = null;
+    this.queuedRequest = null;
+    this.controller?.abort();
+
+    this.state = {
+      ...this.state,
+      request: null,
+      refreshPending: false,
+      generation: this.state.generation + 1,
+    };
+    this.currentSnapshot = { ...this.state, inserted: [] };
+    this.listeners.forEach((listener) => listener());
+  }
+
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;
+    this.started = false;
     this.controller?.abort();
     this.controller = null;
     this.activeRequest = null;
@@ -278,7 +302,7 @@ export function usePhotoFeed(
   );
   useEffect(() => {
     runtime.start();
-    return () => runtime.dispose();
+    return () => runtime.suspend();
   }, [runtime]);
   useEffect(() => {
     runtime.setEvent(event);

From 58c742d08f39c4a28cf5b00f08b9ecacc404498b Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:46:37 +0800
Subject: [PATCH 060/105] feat: support installed booth operation

---
 .../booth-session/installed-mode.test.ts      |  93 ++++++++++
 app/[event]/booth-session/installed-mode.ts   |  82 +++++++++
 app/[event]/booth.module.css                  | 161 +++++++++++++++++
 app/[event]/manifest.test.ts                  |  68 ++++++++
 app/[event]/manifest.ts                       |  33 ++++
 app/[event]/manifest.webmanifest/route.ts     |  24 +++
 app/[event]/operator-controls.test.tsx        |  73 ++++++++
 app/[event]/operator-controls.tsx             | 136 +++++++++++++++
 app/[event]/page.tsx                          | 164 ++++++++++++++++--
 app/layout.tsx                                |   5 +
 public/booth-icon.svg                         |   8 +
 11 files changed, 834 insertions(+), 13 deletions(-)
 create mode 100644 app/[event]/booth-session/installed-mode.test.ts
 create mode 100644 app/[event]/booth-session/installed-mode.ts
 create mode 100644 app/[event]/manifest.test.ts
 create mode 100644 app/[event]/manifest.ts
 create mode 100644 app/[event]/manifest.webmanifest/route.ts
 create mode 100644 app/[event]/operator-controls.test.tsx
 create mode 100644 app/[event]/operator-controls.tsx
 create mode 100644 public/booth-icon.svg

diff --git a/app/[event]/booth-session/installed-mode.test.ts b/app/[event]/booth-session/installed-mode.test.ts
new file mode 100644
index 0000000..25b9a81
--- /dev/null
+++ b/app/[event]/booth-session/installed-mode.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ScreenWakeController,
+  isStandalone,
+  shouldWarnBeforeUnload,
+  type WakeLockSentinelLike,
+} from "./installed-mode";
+
+class FakeSentinel implements WakeLockSentinelLike {
+  released = false;
+  releaseCalls = 0;
+
+  async release() {
+    this.releaseCalls++;
+    this.released = true;
+  }
+}
+
+describe("installed Booth mode", () => {
+  test("detects standards-based and iOS standalone modes", () => {
+    expect(isStandalone(() => ({ matches: true }), false)).toBe(true);
+    expect(isStandalone(() => ({ matches: false }), true)).toBe(true);
+    expect(isStandalone(() => ({ matches: false }), false)).toBe(false);
+  });
+
+  test("warns only while capture, durable handoff, or pending work exists", () => {
+    expect(shouldWarnBeforeUnload({
+      captureActive: false,
+      durableHandoffActive: false,
+      pendingCount: 0,
+    })).toBe(false);
+    expect(shouldWarnBeforeUnload({
+      captureActive: false,
+      durableHandoffActive: false,
+      pendingCount: 1,
+    })).toBe(true);
+    expect(shouldWarnBeforeUnload({
+      captureActive: true,
+      durableHandoffActive: false,
+      pendingCount: 0,
+    })).toBe(true);
+    expect(shouldWarnBeforeUnload({
+      captureActive: false,
+      durableHandoffActive: true,
+      pendingCount: 0,
+    })).toBe(true);
+  });
+});
+
+describe("ScreenWakeController", () => {
+  test("acquires one wake lock and releases that exact sentinel", async () => {
+    const sentinel = new FakeSentinel();
+    let requests = 0;
+    const controller = new ScreenWakeController({
+      request: async () => {
+        requests++;
+        return sentinel;
+      },
+    });
+
+    expect(await controller.request()).toBe("active");
+    expect(await controller.request()).toBe("active");
+    expect(requests).toBe(1);
+
+    await controller.release();
+    expect(sentinel.releaseCalls).toBe(1);
+  });
+
+  test("reports unsupported and denied providers without throwing", async () => {
+    expect(await new ScreenWakeController().request()).toBe("unsupported");
+    expect(await new ScreenWakeController({
+      request: async () => {
+        throw new DOMException("not allowed", "NotAllowedError");
+      },
+    }).request()).toBe("denied");
+  });
+
+  test("reacquires after a visible-page return when the old lock was released", async () => {
+    const sentinels = [new FakeSentinel(), new FakeSentinel()];
+    let requests = 0;
+    const controller = new ScreenWakeController({
+      request: async () => sentinels[requests++],
+    });
+
+    await controller.request();
+    sentinels[0].released = true;
+    expect(await controller.handleVisibilityChange("hidden")).toBeUndefined();
+    expect(requests).toBe(1);
+
+    expect(await controller.handleVisibilityChange("visible")).toBe("active");
+    expect(requests).toBe(2);
+  });
+});
diff --git a/app/[event]/booth-session/installed-mode.ts b/app/[event]/booth-session/installed-mode.ts
new file mode 100644
index 0000000..e5e3523
--- /dev/null
+++ b/app/[event]/booth-session/installed-mode.ts
@@ -0,0 +1,82 @@
+export type WakeLockSentinelLike = {
+  readonly released: boolean;
+  release(): Promise<void>;
+  addEventListener?(
+    type: "release",
+    listener: () => void,
+    options?: { once?: boolean }
+  ): void;
+};
+
+export type WakeLockProviderLike = {
+  request(type: "screen"): Promise<WakeLockSentinelLike>;
+};
+
+export type WakeRequestState = "active" | "unsupported" | "denied";
+
+export function isStandalone(
+  matchMedia: (query: string) => { matches: boolean },
+  navigatorStandalone = false
+): boolean {
+  return matchMedia("(display-mode: standalone)").matches
+    || navigatorStandalone === true;
+}
+
+export function shouldWarnBeforeUnload(input: {
+  captureActive: boolean;
+  durableHandoffActive: boolean;
+  pendingCount: number;
+}): boolean {
+  return input.captureActive
+    || input.durableHandoffActive
+    || input.pendingCount > 0;
+}
+
+export class ScreenWakeController {
+  private sentinel: WakeLockSentinelLike | null = null;
+  private requesting: Promise<WakeRequestState> | null = null;
+
+  constructor(private readonly provider?: WakeLockProviderLike) {}
+
+  request(): Promise<WakeRequestState> {
+    if (!this.provider) return Promise.resolve("unsupported");
+    if (this.sentinel && !this.sentinel.released) return Promise.resolve("active");
+    if (this.requesting) return this.requesting;
+
+    const work = this.provider.request("screen")
+      .then((sentinel) => {
+        this.sentinel = sentinel;
+        sentinel.addEventListener?.("release", () => {
+          if (this.sentinel === sentinel) this.sentinel = null;
+        }, { once: true });
+        return "active" as const;
+      })
+      .catch(() => "denied" as const)
+      .finally(() => {
+        if (this.requesting === work) this.requesting = null;
+      });
+    this.requesting = work;
+    return work;
+  }
+
+  async release(): Promise<void> {
+    const requesting = this.requesting;
+    if (requesting) await requesting;
+    const sentinel = this.sentinel;
+    this.sentinel = null;
+    if (!sentinel || sentinel.released) return;
+    try {
+      await sentinel.release();
+    } catch {
+      // Releasing wake is best-effort during teardown. The controller forgets
+      // the old sentinel so a later explicit request cannot reuse stale state.
+    }
+  }
+
+  handleVisibilityChange(
+    visibilityState: DocumentVisibilityState
+  ): Promise<WakeRequestState | undefined> {
+    if (visibilityState !== "visible") return Promise.resolve(undefined);
+    return this.request();
+  }
+}
diff --git a/app/[event]/booth.module.css b/app/[event]/booth.module.css
index ebb33e8..fb43b0b 100644
--- a/app/[event]/booth.module.css
+++ b/app/[event]/booth.module.css
@@ -316,6 +316,163 @@
   animation: pause-arrive 180ms ease-out both;
 }
 
+.operatorControls {
+  position: absolute;
+  top: calc(16px + env(safe-area-inset-top, 0px));
+  right: calc(16px + env(safe-area-inset-right, 0px));
+  z-index: 20;
+}
+
+.operatorToggle {
+  min-width: 96px;
+  min-height: 44px;
+  padding: 10px 16px;
+  border: 1px solid rgba(255, 255, 255, 0.45);
+  border-radius: 999px;
+  background: rgba(0, 0, 0, 0.72);
+  color: #fff;
+  font: 750 14px/1 system-ui, sans-serif;
+  cursor: pointer;
+}
+
+.operatorPanel {
+  width: min(430px, calc(100vw - 32px));
+  margin-top: 10px;
+  padding: 24px;
+  border: 1px solid #565563;
+  border-radius: 22px;
+  background: #111119;
+  color: #fff;
+  box-shadow: 0 24px 70px rgba(0, 0, 0, 0.58);
+}
+
+.operatorPanel[hidden] {
+  display: none;
+}
+
+.operatorPanel h2 {
+  margin: 4px 0 10px;
+  font-size: 28px;
+}
+
+.operatorPanel p {
+  margin: 0 0 16px;
+  color: #c9c8d2;
+  line-height: 1.45;
+}
+
+.operatorEyebrow {
+  color: #ff7db7 !important;
+  font: 800 11px/1.3 ui-monospace, "SFMono-Regular", Menlo, monospace;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.operatorPanel label {
+  display: block;
+  margin-bottom: 7px;
+  font-size: 14px;
+  font-weight: 750;
+}
+
+.operatorPanel input {
+  width: 100%;
+  min-height: 52px;
+  padding: 0 14px;
+  border: 2px solid #4a4959;
+  border-radius: 13px;
+  background: #09090e;
+  color: #fff;
+  font-size: 18px;
+}
+
+.operatorError {
+  margin-top: 12px !important;
+  color: #ffb3cb !important;
+  font-weight: 700;
+}
+
+.operatorActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  margin-top: 18px;
+}
+
+.operatorActions button {
+  min-height: 44px;
+  padding: 10px 16px;
+  border: 0;
+  border-radius: 12px;
+  background: #34333e;
+  color: #fff;
+  font-weight: 750;
+  cursor: pointer;
+}
+
+.operatorActions button[type="submit"] {
+  background: #d41454;
+}
+
+.operatorActions button:disabled {
+  cursor: wait;
+  opacity: 0.55;
+}
+
+.operatorToggle:focus-visible,
+.operatorPanel input:focus-visible,
+.operatorActions button:focus-visible {
+  outline: 3px solid #fff;
+  outline-offset: 4px;
+}
+
+.wakeFallback {
+  position: absolute;
+  left: 16px;
+  bottom: calc(16px + env(safe-area-inset-bottom, 0px));
+  z-index: 8;
+  max-width: min(520px, calc(100vw - 32px));
+  padding: 12px 16px;
+  border-radius: 13px;
+  background: rgba(145, 90, 0, 0.96);
+  color: #fff;
+  font-size: 13px;
+  font-weight: 650;
+  line-height: 1.4;
+}
+
+.exited {
+  position: absolute;
+  inset: 0;
+  z-index: 30;
+  display: grid;
+  place-items: center;
+  padding: 28px;
+  background: #08080d;
+  color: #fff;
+  text-align: center;
+}
+
+.exited > div {
+  width: min(620px, 100%);
+  padding: clamp(30px, 6vw, 52px);
+  border: 1px solid #4c4b58;
+  border-radius: 28px;
+  background: #111119;
+}
+
+.exited h1 {
+  margin: 10px 0 18px;
+  font-size: clamp(38px, 7vw, 72px);
+}
+
+.exited p,
+.exited strong {
+  display: block;
+  margin: 10px 0;
+  line-height: 1.5;
+}
+
 .operationalEyebrow {
   margin: 0 0 12px;
   color: #ff8fc2;
@@ -647,6 +804,9 @@
   .unlockForm button:focus-visible,
   .unlockRetry:focus-visible,
   .unlockForm > input:focus-visible,
+  .operatorToggle:focus-visible,
+  .operatorPanel input:focus-visible,
+  .operatorActions button:focus-visible,
   .choice:focus-visible,
   .shutter:focus-visible,
   .change:focus-visible,
@@ -660,6 +820,7 @@
 @media (prefers-reduced-motion: reduce) {
   .unlockPanel,
   .operationalPausePanel,
+  .operatorPanel,
   .flash {
     animation: none;
   }
diff --git a/app/[event]/manifest.test.ts b/app/[event]/manifest.test.ts
new file mode 100644
index 0000000..6d62793
--- /dev/null
+++ b/app/[event]/manifest.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import manifest from "./manifest";
+import { GET } from "./manifest.webmanifest/route";
+
+describe("per-Event Booth manifest", () => {
+  test("uses the canonical Event path as its installed identity and scope", async () => {
+    const value = await manifest({
+      params: Promise.resolve({ event: "launch-night" }),
+    });
+
+    expect(value).toMatchObject({
+      id: "/launch-night",
+      start_url: "/launch-night",
+      scope: "/launch-night",
+      display: "standalone",
+      orientation: "landscape",
+      background_color: "#000000",
+      theme_color: "#000000",
+    });
+    expect(JSON.parse(JSON.stringify(value.icons))).toEqual([
+      {
+        src: "/booth-icon.svg",
+        sizes: "any",
+        type: "image/svg+xml",
+        purpose: "any maskable",
+      },
+    ]);
+  });
+
+  test("never serializes a query string or credential-shaped data", async () => {
+    const serialized = JSON.stringify(await manifest({
+      params: Promise.resolve({ event: "launch-night" }),
+    }));
+
+    expect(serialized).not.toContain("?");
+    expect(serialized).not.toContain("boothKey");
+    expect(serialized).not.toContain("credential");
+    expect(serialized).not.toContain("hash");
+  });
+
+  test("rejects a non-canonical Event instead of silently slugging it", async () => {
+    await expect(manifest({
+      params: Promise.resolve({ event: "Launch Night" }),
+    })).rejects.toThrow("canonical lowercase slug");
+  });
+
+  test("serves the Event manifest without caching credential-bearing state", async () => {
+    const response = await GET(new Request(
+      "https://booth.invalid/launch-night/manifest.webmanifest"
+    ), {
+      params: Promise.resolve({ event: "launch-night" }),
+    });
+    const body = await response.text();
+
+    expect(response.headers.get("content-type")).toContain("application/manifest+json");
+    expect(response.headers.get("cache-control")).toBe("public, max-age=300");
+    expect(JSON.parse(body).start_url).toBe("/launch-night");
+    expect(body).not.toContain("boothKey");
+    expect(body).not.toContain("credential");
+  });
+
+  test("the Booth document links only its canonical Event manifest", async () => {
+    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
+
+    expect(source).toContain('rel="manifest"');
+    expect(source).toContain('href={`/${event}/manifest.webmanifest`}');
+  });
+});
diff --git a/app/[event]/manifest.ts b/app/[event]/manifest.ts
new file mode 100644
index 0000000..9a23adf
--- /dev/null
+++ b/app/[event]/manifest.ts
@@ -0,0 +1,33 @@
+import type { MetadataRoute } from "next";
+import { canonicalEvent } from "../event-identity";
+
+export default async function manifest({
+  params,
+}: {
+  params: Promise<{ event: string }>;
+}): Promise<MetadataRoute.Manifest> {
+  const event = canonicalEvent((await params).event);
+  const eventPath = `/${event}`;
+
+  return {
+    id: eventPath,
+    name: `${event} Photo Booth`,
+    short_name: "Photo Booth",
+    start_url: eventPath,
+    scope: eventPath,
+    display: "standalone",
+    orientation: "landscape",
+    background_color: "#000000",
+    theme_color: "#000000",
+    icons: [
+      {
+        src: "/booth-icon.svg",
+        sizes: "any",
+        type: "image/svg+xml",
+        // Web App Manifest allows a space-separated purpose list. Next's
+        // MetadataRoute type currently narrows this valid value to one token.
+        purpose: "any maskable" as "any",
+      },
+    ],
+  };
+}
diff --git a/app/[event]/manifest.webmanifest/route.ts b/app/[event]/manifest.webmanifest/route.ts
new file mode 100644
index 0000000..69fe041
--- /dev/null
+++ b/app/[event]/manifest.webmanifest/route.ts
@@ -0,0 +1,24 @@
+import { InvalidEventSlugError } from "../../event-identity";
+import eventManifest from "../manifest";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(
+  _request: Request,
+  context: { params: Promise<{ event: string }> }
+) {
+  try {
+    const body = await eventManifest(context);
+    return new Response(JSON.stringify(body), {
+      headers: {
+        "Cache-Control": "public, max-age=300",
+        "Content-Type": "application/manifest+json; charset=utf-8",
+      },
+    });
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) {
+      return Response.json({ error: error.message }, { status: 400 });
+    }
+    throw error;
+  }
+}
diff --git a/app/[event]/operator-controls.test.tsx b/app/[event]/operator-controls.test.tsx
new file mode 100644
index 0000000..efc8454
--- /dev/null
+++ b/app/[event]/operator-controls.test.tsx
@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  OperatorControls,
+  performVerifiedOperatorExit,
+} from "./operator-controls";
+
+function exitHarness(verified: boolean) {
+  const actions: string[] = [];
+  const result = performVerifiedOperatorExit("fresh-key", {
+    verify: async (key) => {
+      actions.push(`verify:${key}`);
+      return verified;
+    },
+    stopCamera: () => actions.push("stop-camera"),
+    releaseWake: async () => {
+      actions.push("release-wake");
+    },
+    stopHeartbeat: () => actions.push("stop-heartbeat"),
+    stopPoller: () => actions.push("stop-poller"),
+    stopSession: async () => {
+      actions.push("stop-session");
+    },
+    clearCredentials: () => actions.push("clear-credentials"),
+    clearActiveCredential: () => actions.push("clear-active-credential"),
+    markExited: () => actions.push("mark-exited"),
+  });
+  return { actions, result };
+}
+
+describe("authenticated operator exit", () => {
+  test("failed fresh verification changes no resources or credentials", async () => {
+    const { actions, result } = exitHarness(false);
+
+    expect(await result).toBe("rejected");
+    expect(actions).toEqual(["verify:fresh-key"]);
+  });
+
+  test("verified exit stops runtime resources before clearing exact credentials", async () => {
+    const { actions, result } = exitHarness(true);
+
+    expect(await result).toBe("exited");
+    expect(actions).toEqual([
+      "verify:fresh-key",
+      "stop-camera",
+      "release-wake",
+      "stop-heartbeat",
+      "stop-poller",
+      "stop-session",
+      "clear-credentials",
+      "clear-active-credential",
+      "mark-exited",
+    ]);
+  });
+
+  test("renders a discoverable fresh-key control without exposing a key", () => {
+    const secret = "never-render-this-key";
+    const html = renderToStaticMarkup(
+      <OperatorControls
+        event="launch-night"
+        pendingCount={2}
+        onOperatorGesture={() => {}}
+        onExit={async (key) => key === secret ? "exited" : "rejected"}
+      />
+    );
+
+    expect(html).toContain("Operator");
+    expect(html).toContain("Exit Booth");
+    expect(html).toContain('type="password"');
+    expect(html).toContain("2 pending photos will stay in the Photo Outbox.");
+    expect(html).not.toContain(secret);
+  });
+});
diff --git a/app/[event]/operator-controls.tsx b/app/[event]/operator-controls.tsx
new file mode 100644
index 0000000..074a3ac
--- /dev/null
+++ b/app/[event]/operator-controls.tsx
@@ -0,0 +1,136 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+import styles from "./booth.module.css";
+
+export type OperatorExitResult = "exited" | "rejected";
+
+export type VerifiedOperatorExitDependencies = {
+  verify: (key: string) => Promise<boolean>;
+  stopCamera: () => void;
+  releaseWake: () => Promise<void>;
+  stopHeartbeat: () => void;
+  stopPoller: () => void;
+  stopSession: () => Promise<void>;
+  clearCredentials: () => void;
+  clearActiveCredential: () => void;
+  markExited: () => void;
+};
+
+async function settle(action: () => void | Promise<void>) {
+  try {
+    await action();
+  } catch {
+    // A failed resource adapter must not prevent the remaining verified exit
+    // teardown or leave credentials resident.
+  }
+}
+
+export async function performVerifiedOperatorExit(
+  key: string,
+  deps: VerifiedOperatorExitDependencies
+): Promise<OperatorExitResult> {
+  let verified = false;
+  try {
+    verified = await deps.verify(key);
+  } catch {
+    return "rejected";
+  }
+  if (!verified) return "rejected";
+
+  await settle(deps.stopCamera);
+  await settle(deps.releaseWake);
+  await settle(deps.stopHeartbeat);
+  await settle(deps.stopPoller);
+  await settle(deps.stopSession);
+  await settle(deps.clearCredentials);
+  await settle(deps.clearActiveCredential);
+  await settle(deps.markExited);
+  return "exited";
+}
+
+export type OperatorControlsProps = {
+  event: string;
+  pendingCount: number;
+  onOperatorGesture: () => void;
+  onExit: (freshKey: string) => Promise<OperatorExitResult>;
+};
+
+export function OperatorControls({
+  event,
+  pendingCount,
+  onOperatorGesture,
+  onExit,
+}: OperatorControlsProps) {
+  const [open, setOpen] = useState(false);
+  const [key, setKey] = useState("");
+  const [checking, setChecking] = useState(false);
+  const [rejected, setRejected] = useState(false);
+
+  const toggle = () => {
+    onOperatorGesture();
+    setRejected(false);
+    setOpen((value) => !value);
+  };
+
+  const submit = async (submitEvent: FormEvent<HTMLFormElement>) => {
+    submitEvent.preventDefault();
+    if (!key || checking) return;
+    const submittedKey = key;
+    setKey("");
+    setChecking(true);
+    setRejected(false);
+    const result = await onExit(submittedKey);
+    setChecking(false);
+    if (result === "rejected") setRejected(true);
+  };
+
+  return (
+    <aside className={styles.operatorControls}>
+      <button
+        type="button"
+        className={styles.operatorToggle}
+        aria-expanded={open}
+        aria-controls="operator-exit-panel"
+        onClick={toggle}
+      >
+        Operator
+      </button>
+      <form
+        id="operator-exit-panel"
+        className={styles.operatorPanel}
+        onSubmit={submit}
+        hidden={!open}
+      >
+          <p className={styles.operatorEyebrow}>Event operator · {event}</p>
+          <h2>Exit Booth</h2>
+          <p>
+            Enter a fresh Booth or Admin Key. {pendingCount} pending photo
+            {pendingCount === 1 ? "" : "s"} will stay in the Photo Outbox.
+          </p>
+          <label htmlFor="operator-exit-key">Booth or Admin Key</label>
+          <input
+            id="operator-exit-key"
+            type="password"
+            autoComplete="current-password"
+            value={key}
+            disabled={checking}
+            onChange={(event) => setKey(event.target.value)}
+          />
+          {rejected && (
+            <p className={styles.operatorError} role="alert">
+              Key rejected. Booth operation has not changed.
+            </p>
+          )}
+          <div className={styles.operatorActions}>
+            <button type="button" onClick={toggle} disabled={checking}>
+              Cancel
+            </button>
+            <button type="submit" disabled={checking || key.length === 0}>
+              {checking ? "Verifying…" : "Verify and exit"}
+            </button>
+          </div>
+      </form>
+    </aside>
+  );
+}
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 61b0d2f..58af5cc 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -41,6 +41,18 @@ import {
   type BoothPreflightResult,
 } from "./booth-session/lifecycle";
 import { BoothUnlock } from "./booth-unlock";
+import {
+  ScreenWakeController,
+  isStandalone,
+  shouldWarnBeforeUnload,
+  type WakeLockProviderLike,
+  type WakeRequestState,
+} from "./booth-session/installed-mode";
+import {
+  OperatorControls,
+  performVerifiedOperatorExit,
+  type OperatorExitResult,
+} from "./operator-controls";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
 type OperationalState = BoothOperationalClientState;
@@ -60,13 +72,6 @@ function uploadErrorClass(status: number): UploadErrorClass {
   return "unknown";
 }
 
-function isInstalled() {
-  if (typeof window === "undefined") return false;
-  const navigatorWithStandalone = navigator as Navigator & { standalone?: boolean };
-  return window.matchMedia("(display-mode: standalone)").matches
-    || navigatorWithStandalone.standalone === true;
-}
-
 function heartbeatCamera(status: Status, paused: boolean): BoothHeartbeatInput["camera"] {
   if (paused) return "stopped";
   if (status === "starting") return "starting";
@@ -123,9 +128,17 @@ export default function Booth() {
   const cameraRequestRef = useRef(0);
   const unmountedRef = useRef(false);
   const deviceIdRef = useRef("");
+  const credentialRef = useRef<BoothCredentialHolder | null>(null);
   const sessionStartedAtRef = useRef(0);
   const operationalRef = useRef<OperationalState>({ paused: false, connected: false });
   const uploadStateRef = useRef<UploadState>(INITIAL_UPLOAD_STATE);
+  const wakeController = useMemo(() => {
+    if (typeof navigator === "undefined") return new ScreenWakeController();
+    const provider = (navigator as Navigator & {
+      wakeLock?: WakeLockProviderLike;
+    }).wakeLock;
+    return new ScreenWakeController(provider);
+  }, []);
   const [status, setStatus] = useState<Status>("starting");
   const [accessState, setAccessState] = useState<BoothAccessState>("locked");
   const [accessFeedback, setAccessFeedback] =
@@ -148,6 +161,9 @@ export default function Booth() {
   const [online, setOnline] = useState(false);
   const [uploadState, setUploadState] =
     useState<UploadState>(INITIAL_UPLOAD_STATE);
+  const [wakeState, setWakeState] =
+    useState<WakeRequestState | "idle">("idle");
+  const [durableHandoffActive, setDurableHandoffActive] = useState(false);
   // Frames remain unavailable until authenticated preflight returns the safe
   // Event experience. `null` is never shown while the Booth is locked.
   const [enabled, setEnabled] = useState<string[] | null>(null);
@@ -210,6 +226,12 @@ export default function Booth() {
     if (videoRef.current) videoRef.current.srcObject = null;
   }, []);
 
+  const requestWake = useCallback(async () => {
+    const next = await wakeController.request();
+    setWakeState(next);
+    return next;
+  }, [wakeController]);
+
   const clearFrame = useCallback(() => {
     setMode(null);
     setShot(0);
@@ -303,7 +325,10 @@ export default function Booth() {
             pendingCount: upload.pendingCount,
             durableStorage: upload.durable,
             online: navigator.onLine,
-            installed: isInstalled(),
+            installed: isStandalone(
+              window.matchMedia.bind(window),
+              (navigator as Navigator & { standalone?: boolean }).standalone
+            ),
             camera: operationalRef.current.paused ? "stopped" : "starting",
             upload: heartbeatUpload(upload),
             ...(heartbeatError("starting", null, upload) === undefined
@@ -321,13 +346,14 @@ export default function Booth() {
         heartbeatReporterRef.current?.stop();
         pauseBoundary.reset();
         stopCamera();
+        void wakeController.release().then(() => setWakeState("idle"));
       },
       onUploaded: ({ url }) => {
         setLastUrl(url);
         setLastSuccessfulUploadAt(Date.now());
       },
     }),
-    [applyOperationalState, pauseBoundary, startCamera, stopCamera]
+    [applyOperationalState, pauseBoundary, startCamera, stopCamera, wakeController]
   );
 
   useEffect(() => {
@@ -338,6 +364,32 @@ export default function Booth() {
     };
   }, [stopCamera]);
 
+  useEffect(() => {
+    const onVisibilityChange = () => {
+      if (accessState !== "ready") return;
+      void wakeController.handleVisibilityChange(document.visibilityState)
+        .then((next) => {
+          if (next) setWakeState(next);
+        });
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => document.removeEventListener("visibilitychange", onVisibilityChange);
+  }, [accessState, wakeController]);
+
+  useEffect(() => {
+    if (!shouldWarnBeforeUnload({
+      captureActive: status === "running",
+      durableHandoffActive,
+      pendingCount: uploadState.pendingCount,
+    })) return;
+    const warn = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      event.returnValue = "";
+    };
+    window.addEventListener("beforeunload", warn);
+    return () => window.removeEventListener("beforeunload", warn);
+  }, [durableHandoffActive, status, uploadState.pendingCount]);
+
   // grab the current video frame, mirrored to match the preview, at full res
   const grabFrame = useCallback((): HTMLCanvasElement => {
     const video = videoRef.current!;
@@ -353,6 +405,7 @@ export default function Booth() {
 
   useEffect(() => {
     const credential: BoothCredentialHolder = { key: "" };
+    credentialRef.current = credential;
     const uploadOne = async (item: OutboxItem) => {
       const res = await fetch(`/api/upload?event=${encodeURIComponent(event)}`, {
         method: "POST",
@@ -422,6 +475,7 @@ export default function Booth() {
       document.removeEventListener("visibilitychange", reconsiderForeground);
       if (sessionRef.current === session) sessionRef.current = null;
       stopBoothOperationalClients(poller, reporter);
+      if (credentialRef.current === credential) credentialRef.current = null;
       if (statePollerRef.current === poller) statePollerRef.current = null;
       if (heartbeatReporterRef.current === reporter) heartbeatReporterRef.current = null;
       void lifecycle.leaveEvent(session);
@@ -439,7 +493,10 @@ export default function Booth() {
       pendingCount: uploadState.pendingCount,
       durableStorage: uploadState.durable,
       online,
-      installed: isInstalled(),
+      installed: isStandalone(
+        window.matchMedia.bind(window),
+        (navigator as Navigator & { standalone?: boolean }).standalone
+      ),
       camera: heartbeatCamera(status, operational.paused),
       upload: heartbeatUpload(uploadState),
       ...(lastSuccessfulUploadAt === null ? {} : { lastSuccessfulUploadAt }),
@@ -456,6 +513,7 @@ export default function Booth() {
   ]);
 
   const unlock = useCallback((key: string, remember: boolean) => {
+    void requestWake();
     saveBoothCredential(
       event,
       key,
@@ -464,7 +522,7 @@ export default function Booth() {
       window.localStorage
     );
     void lifecycle.unlock(key);
-  }, [event, lifecycle]);
+  }, [event, lifecycle, requestWake]);
 
   const retryPreflight = useCallback(() => {
     void lifecycle.retryPreflight();
@@ -491,6 +549,7 @@ export default function Booth() {
     const session = sessionRef.current;
     try {
       if (!session) throw new Error("Photo queue is still starting — please try again");
+      setDurableHandoffActive(true);
       await session.enqueueCapture(
         async (signal) => {
           const frames = await runCaptureSequence({
@@ -514,6 +573,7 @@ export default function Booth() {
           },
         }
       );
+      setDurableHandoffActive(false);
       if (controller.signal.aborted || !lifecycle.isActive(session)) return;
       // Durable handoff is complete. Return to the picker before uploading so
       // the next guest is never trapped on the previous guest's frame.
@@ -534,6 +594,7 @@ export default function Booth() {
         setStatus(streamRef.current ? "picking" : "denied");
       }
     } finally {
+      setDurableHandoffActive(false);
       if (captureRef.current === controller) captureRef.current = null;
     }
   }, [
@@ -564,6 +625,7 @@ export default function Booth() {
       const session = sessionRef.current;
       try {
         if (!session) throw new Error("Photo queue is still starting — please try again");
+        setDurableHandoffActive(true);
         await session.enqueueCapture(async (signal) => {
           if (signal?.aborted) throw new DOMException("Capture aborted", "AbortError");
           let blob: Blob = file;
@@ -586,6 +648,7 @@ export default function Booth() {
             source: "camera-fallback",
           },
         });
+        setDurableHandoffActive(false);
         if (controller.signal.aborted || !lifecycle.isActive(session)) return;
         setError(null);
         pauseBoundary.completeOperation();
@@ -595,6 +658,7 @@ export default function Booth() {
         setError(uploadError instanceof Error ? uploadError.message : String(uploadError));
         pauseBoundary.completeOperation();
       } finally {
+        setDurableHandoffActive(false);
         if (captureRef.current === controller) captureRef.current = null;
       }
     },
@@ -607,13 +671,55 @@ export default function Booth() {
     setStatus("ready");
   };
 
+  const operatorExit = useCallback(async (
+    freshKey: string
+  ): Promise<OperatorExitResult> => performVerifiedOperatorExit(freshKey, {
+    verify: async (key) => {
+      const result = await requestBoothPreflight(
+        event,
+        key,
+        new AbortController().signal
+      );
+      return result.kind === "ready";
+    },
+    stopCamera,
+    releaseWake: async () => {
+      await wakeController.release();
+      setWakeState("idle");
+    },
+    stopHeartbeat: () => heartbeatReporterRef.current?.stop(),
+    stopPoller: () => statePollerRef.current?.stop(),
+    stopSession: async () => {
+      await sessionRef.current?.stop();
+    },
+    clearCredentials: () => clearBoothCredential(
+      event,
+      window.sessionStorage,
+      window.localStorage
+    ),
+    clearActiveCredential: () => {
+      if (credentialRef.current) credentialRef.current.key = "";
+    },
+    markExited: () => {
+      pauseBoundary.reset();
+      setDurableHandoffActive(false);
+      setEnabled(null);
+      setMode(null);
+      setStatus("starting");
+      setAccessFeedback("locked");
+      setAccessState("exited");
+    },
+  }), [event, pauseBoundary, stopCamera, wakeController]);
+
   // preview crops to the chosen frame's photo aspect (w/h of its first slot),
   // so guests see exactly what will be captured. Fullscreen until a mode is set.
   const previewAspect = mode ? TEMPLATES[mode].slots[0].w / TEMPLATES[mode].slots[0].h : null;
   const framed = mode !== null && status !== "picking";
 
   return (
-    <main className={styles.booth}>
+    <>
+      <link rel="manifest" href={`/${event}/manifest.webmanifest`} />
+      <main className={styles.booth}>
       {/* framed box is exactly the slot's aspect at the largest size that fits,
           so the cover-cropped preview is edge-to-edge what composite() captures */}
       <video
@@ -763,6 +869,38 @@ export default function Booth() {
           </div>
         </section>
       )}
-    </main>
+      {accessState === "ready" && (
+        <OperatorControls
+          event={event}
+          pendingCount={uploadState.pendingCount}
+          onOperatorGesture={() => {
+            void requestWake();
+          }}
+          onExit={operatorExit}
+        />
+      )}
+      {accessState === "ready"
+        && (wakeState === "unsupported" || wakeState === "denied") && (
+        <div className={styles.wakeFallback} role="status">
+          Screen Wake Lock is unavailable. In iPad Settings, set Display &amp;
+          Brightness → Auto-Lock to Never for Booth operation.
+        </div>
+      )}
+      {accessState === "exited" && (
+        <section className={styles.exited} aria-labelledby="booth-exited-title">
+          <div>
+            <p className={styles.operatorEyebrow}>Event operator · {event}</p>
+            <h1 id="booth-exited-title">Booth exited</h1>
+            <p>Camera and Booth activity are stopped.</p>
+            <strong>
+              {uploadState.pendingCount} pending photo
+              {uploadState.pendingCount === 1 ? "" : "s"} remain in the Photo Outbox.
+            </strong>
+            <p>Reload this canonical Event address to unlock the Booth again.</p>
+          </div>
+        </section>
+      )}
+      </main>
+    </>
   );
 }
diff --git a/app/layout.tsx b/app/layout.tsx
index a9d7680..ee00981 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -3,6 +3,11 @@ import "./globals.css";
 
 export const metadata: Metadata = {
   title: "Photo Booth",
+  appleWebApp: {
+    capable: true,
+    statusBarStyle: "black-translucent",
+    title: "Photo Booth",
+  },
 };
 
 // pinch-zoom stays enabled (accessibility; phone viewers zoom gallery photos)
diff --git a/public/booth-icon.svg b/public/booth-icon.svg
new file mode 100644
index 0000000..eb7d020
--- /dev/null
+++ b/public/booth-icon.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="112" fill="#000"/>
+  <rect x="72" y="132" width="368" height="248" rx="54" fill="#fff"/>
+  <path d="M164 132l34-54h116l34 54" fill="#ff2d8b"/>
+  <circle cx="256" cy="256" r="82" fill="#000"/>
+  <circle cx="256" cy="256" r="52" fill="#ff2d8b"/>
+  <circle cx="386" cy="181" r="18" fill="#ff2d8b"/>
+</svg>

From 8c4dbc662375513ca8b0d368ba6eaeac56ce4da4 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:04:21 +0800
Subject: [PATCH 061/105] test: verify reliable booth control

---
 .github/workflows/verify.yml         |   2 +
 .gitignore                           |   2 +
 bun.lock                             |   9 +
 bunfig.toml                          |   2 +
 docs/runbooks/deployment.md          |  17 +-
 docs/runbooks/pre-event-readiness.md |  32 +-
 package.json                         |   2 +
 playwright.config.ts                 |  31 ++
 tests/booth-control.spec.ts          | 424 +++++++++++++++++++++++++++
 9 files changed, 511 insertions(+), 10 deletions(-)
 create mode 100644 bunfig.toml
 create mode 100644 playwright.config.ts
 create mode 100644 tests/booth-control.spec.ts

diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml
index 6959c45..2a50be2 100644
--- a/.github/workflows/verify.yml
+++ b/.github/workflows/verify.yml
@@ -23,3 +23,5 @@ jobs:
       - run: bun test
       - run: bun run validate:frames
       - run: bun run build
+      - run: bunx playwright install --with-deps webkit
+      - run: bun run test:browser
diff --git a/.gitignore b/.gitignore
index 0dba8bf..7706835 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,8 @@ next-env.d.ts
 .gstack/
 .open-next/
 .wrangler/
+/test-results/
+/playwright-report/
 scripts/.migrated.json
 .claude/
 .worktrees/
diff --git a/bun.lock b/bun.lock
index c80673b..d388e70 100644
--- a/bun.lock
+++ b/bun.lock
@@ -13,6 +13,7 @@
       },
       "devDependencies": {
         "@cloudflare/workers-types": "^5.20260705.1",
+        "@playwright/test": "^1.61.1",
         "@types/bun": "^1.2.19",
         "@types/node": "^22",
         "@types/qrcode": "^1.5.6",
@@ -309,6 +310,8 @@
 
     "@opennextjs/cloudflare": ["@opennextjs/cloudflare@1.20.1", "", { "dependencies": { "@ast-grep/napi": "^0.40.5", "@dotenvx/dotenvx": "1.31.0", "@opennextjs/aws": "4.0.2", "ci-info": "^4.2.0", "cloudflare": "^4.4.1", "comment-json": "^4.5.1", "enquirer": "^2.4.1", "glob": "^12.0.0", "ts-tqdm": "^0.8.6", "yargs": "^18.0.0" }, "peerDependencies": { "next": ">=15.5.18 <16 || >=16.2.6", "rclone.js": "^0.6.6", "wrangler": "^4.86.0" }, "optionalPeers": ["rclone.js"], "bin": { "opennextjs-cloudflare": "dist/cli/index.js" } }, "sha512-T7yRoEmIdDQada0itRQmQ3cb9o9tWVg1193MviPWRX7XJulOQ6adz45ZgrJuzEPiwi+kMGnj9kozlNBlRNQZcw=="],
 
+    "@playwright/test": ["@playwright/test@1.61.1", "", { "dependencies": { "playwright": "1.61.1" }, "bin": { "playwright": "cli.js" } }, "sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig=="],
+
     "@poppinss/colors": ["@poppinss/colors@4.1.6", "", { "dependencies": { "kleur": "^4.1.5" } }, "sha512-H9xkIdFswbS8n1d6vmRd8+c10t2Qe+rZITbbDHHkQixH5+2x1FDGmi/0K+WgWiqQFKPSlIYB7jlH6Kpfn6Fleg=="],
 
     "@poppinss/dumper": ["@poppinss/dumper@0.6.5", "", { "dependencies": { "@poppinss/colors": "^4.1.5", "@sindresorhus/is": "^7.0.2", "supports-color": "^10.0.0" } }, "sha512-NBdYIb90J7LfOI32dOewKI1r7wnkiH6m920puQ3qHUeZkxNkQiFnXVWoE6YtFSv6QOiPPf7ys6i+HWWecDz7sw=="],
@@ -697,6 +700,10 @@
 
     "picomatch": ["picomatch@4.0.5", "", {}, "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A=="],
 
+    "playwright": ["playwright@1.61.1", "", { "dependencies": { "playwright-core": "1.61.1" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ=="],
+
+    "playwright-core": ["playwright-core@1.61.1", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg=="],
+
     "pngjs": ["pngjs@5.0.0", "", {}, "sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw=="],
 
     "postcss": ["postcss@8.4.31", "", { "dependencies": { "nanoid": "^3.3.6", "picocolors": "^1.0.0", "source-map-js": "^1.0.2" } }, "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ=="],
@@ -865,6 +872,8 @@
 
     "miniflare/undici": ["undici@7.28.0", "", {}, "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA=="],
 
+    "playwright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
     "qrcode/yargs": ["yargs@15.4.1", "", { "dependencies": { "cliui": "^6.0.0", "decamelize": "^1.2.0", "find-up": "^4.1.0", "get-caller-file": "^2.0.1", "require-directory": "^2.1.1", "require-main-filename": "^2.0.0", "set-blocking": "^2.0.0", "string-width": "^4.2.0", "which-module": "^2.0.0", "y18n": "^4.0.0", "yargs-parser": "^18.1.2" } }, "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A=="],
 
     "router/path-to-regexp": ["path-to-regexp@8.4.2", "", {}, "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA=="],
diff --git a/bunfig.toml b/bunfig.toml
new file mode 100644
index 0000000..c381aab
--- /dev/null
+++ b/bunfig.toml
@@ -0,0 +1,2 @@
+[test]
+pathIgnorePatterns = ["tests/**"]
diff --git a/docs/runbooks/deployment.md b/docs/runbooks/deployment.md
index 0c8fe23..5516bcc 100644
--- a/docs/runbooks/deployment.md
+++ b/docs/runbooks/deployment.md
@@ -37,10 +37,25 @@ bun run typecheck:tests
 bun test
 bun run validate:frames
 bun run build
+bunx playwright install webkit
+bun run test:browser
 bun run deploy:staging
 ```
 
-Run the pre-event readiness smoke checks with a throwaway staging Event. Confirm staging photos do not appear in production and staging config does not affect production. Then promote explicitly:
+Run the complete real-iPad section in `pre-event-readiness.md` with a
+throwaway canonical staging Event that is distinct from production. The
+automated WebKit journey does not prove real Safari camera permission,
+orientation/crop, camera-indicator shutdown, Add-to-Home-Screen launch,
+standalone background/foreground behavior, Screen Wake Lock, IndexedDB
+survival across relaunch, Safari cross-tab leases, venue-network reconnect
+timing, real multi-shot pause timing, or camera/wake release during Operator
+exit.
+
+Confirm staging photos do not appear in production and staging config does not
+affect production. For smoke-test moderation, delete only one complete
+Event-owned throwaway image key. Stop promotion on any failed real-device
+check. Only after recording a passing iPad rehearsal should you promote
+explicitly:
 
 ```bash
 bun run deploy:production
diff --git a/docs/runbooks/pre-event-readiness.md b/docs/runbooks/pre-event-readiness.md
index e3f70b2..653dc7a 100644
--- a/docs/runbooks/pre-event-readiness.md
+++ b/docs/runbooks/pre-event-readiness.md
@@ -12,15 +12,29 @@ Use this checklist first on staging and then on production. Never reuse the prod
 
 ## End-to-end device test
 
-1. On the actual iPad over HTTPS, allow camera access and enter the Booth Key.
-2. Capture one photo with every enabled Frame. Check crop, draw order, orientation, color, and final resolution.
-3. Disable the network, finish two captures, and confirm both appear as pending in order.
-4. Reload once and confirm durable queued photos recover. If the Booth reports degraded persistence, stop: IndexedDB is unavailable and reload recovery is not guaranteed.
-5. Restore the network, retry, and wait until the pending count reaches zero.
-6. Confirm each new photo appears once in the Live Gallery without a full-page refresh.
-7. Open a photo on a phone and exercise Save/Share.
-8. In Admin, upload a throwaway photo, verify its exact Event/key, delete that exact object, and ensure adjacent photos remain.
-9. Export the Event and verify the zip opens.
+Use a throwaway canonical Event on staging that is different from every
+production Event. Perform this entire section on the actual target iPad over
+staging HTTPS before production promotion:
+
+1. Open the canonical Event URL, verify the Photo Outbox recovery status is visible before unlock, enter a valid Booth Key, and confirm camera readiness. A rejected key must not start the camera or remove pending photos.
+2. Unlock once without **Remember on this iPad**, close the tab, and confirm a new Safari session asks for a key. Unlock with Remember enabled, relaunch, and confirm the Event is still authenticated without putting the key in the URL.
+3. Capture a photo, interrupt its upload, reload, and confirm the same durable IndexedDB Photo Outbox item recovers. If the Booth reports memory-only persistence, stop: reload recovery is unavailable.
+4. Disable the venue network, finish at least two captures, and confirm ordered pending state. Restore the network and verify automatic drain. Simulate a lost upload acknowledgement and confirm the acknowledged capture appears exactly once with the same stable identity.
+5. Open the same Event in a second tab and confirm the Event lease permits only one ordered drain. Close the owner tab and confirm the other tab can take over only after the lease boundary.
+6. Pause from Admin while the Booth is at the Frame picker and confirm the camera indicator turns off. Resume, start a real multi-shot Frame, pause during capture, and confirm the current composite reaches durable handoff before the camera stops; no new capture may start while paused.
+7. In Admin, confirm the Booth heartbeat moves through live and stale states using its server timestamp, and that pause/connectivity detail contains no credential.
+8. Add the canonical Event to the Home Screen. Launch it without a query string and confirm landscape standalone mode, the correct Event scope, icon, and no credential in the URL or manifest.
+9. Confirm Screen Wake Lock remains active across foreground return. If the target iPadOS denies or lacks it, follow the displayed instructions and set **Settings → Display & Brightness → Auto-Lock → Never** for the event.
+10. Queue one pending photo, use the discoverable Operator control, reject one wrong fresh key, then exit with a valid fresh Booth or Admin Key. Confirm the camera and wake lock release, heartbeat/poller/session activity stops, stored credentials clear, and the pending count remains intact after relaunch.
+
+Then capture one photo with every enabled Frame and check crop, draw order,
+orientation, color, and final resolution. Confirm each photo appears once in
+the Live Gallery without a full-page refresh, exercise Save/Share on a phone,
+and verify the Event export opens.
+
+For moderation cleanup, first copy the complete throwaway image key and verify
+that it belongs to the staging Event. Delete only that exact key; never use a
+prefix, filename fragment, or production Event.
 
 ## Operational checks
 
diff --git a/package.json b/package.json
index 99e4fec..9d14296 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
     "build": "next build",
     "start": "next start",
     "test": "bun test",
+    "test:browser": "playwright test --project=webkit",
     "typecheck": "tsc --noEmit --incremental false",
     "typecheck:tests": "tsc -p tsconfig.test.json",
     "validate:frames": "bun scripts/frame-packs.ts validate",
@@ -27,6 +28,7 @@
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^5.20260705.1",
+    "@playwright/test": "^1.61.1",
     "@types/bun": "^1.2.19",
     "@types/node": "^22",
     "@types/qrcode": "^1.5.6",
diff --git a/playwright.config.ts b/playwright.config.ts
new file mode 100644
index 0000000..3f0d347
--- /dev/null
+++ b/playwright.config.ts
@@ -0,0 +1,31 @@
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  timeout: 90_000,
+  expect: {
+    timeout: 10_000,
+  },
+  fullyParallel: false,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 1 : 0,
+  reporter: process.env.CI ? "github" : "line",
+  use: {
+    baseURL: "http://127.0.0.1:3100",
+    trace: "retain-on-failure",
+  },
+  webServer: {
+    command: "bun dev --hostname 127.0.0.1 --port 3100",
+    url: "http://127.0.0.1:3100",
+    reuseExistingServer: false,
+    timeout: 120_000,
+  },
+  projects: [
+    {
+      name: "webkit",
+      use: {
+        ...devices["Desktop Safari"],
+      },
+    },
+  ],
+});
diff --git a/tests/booth-control.spec.ts b/tests/booth-control.spec.ts
new file mode 100644
index 0000000..0e4fa55
--- /dev/null
+++ b/tests/booth-control.spec.ts
@@ -0,0 +1,424 @@
+import { expect, test, type BrowserContext, type Page } from "@playwright/test";
+
+const EVENT = "browser-journey";
+const STORAGE_KEY = `webbooth:${EVENT}:booth-key`;
+const RECOVERED_ID = "10000000-0000-4000-8000-000000000001";
+const ACCEPTED_KEYS = new Set(["session-key", "remember-key", "fresh-key"]);
+
+type ApiFixture = {
+  paused: boolean;
+  uploadMode: "success" | "lost-ack" | "permanent";
+  uploadAttempts: string[];
+  acknowledgedIds: Set<string>;
+  reconnectAcknowledgement: boolean;
+  externalRequests: string[];
+  pageErrors: string[];
+};
+
+async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture) {
+  await context.addInitScript(() => {
+    const nativeSetTimeout = window.setTimeout.bind(window);
+    window.setTimeout = ((callback: TimerHandler, delay?: number, ...args: unknown[]) => {
+      const accelerated = delay === 1_000
+        ? 150
+        : delay === 300
+          ? 45
+          : delay === 400
+            ? 60
+            : delay;
+      return nativeSetTimeout(callback, accelerated, ...args);
+    }) as typeof window.setTimeout;
+
+    const state = {
+      cameraRequests: Number(sessionStorage.getItem("__booth-camera-requests") ?? 0),
+      trackStops: Number(sessionStorage.getItem("__booth-track-stops") ?? 0),
+    };
+    Object.defineProperty(window, "__boothTest", {
+      configurable: true,
+      value: state,
+    });
+
+    Object.defineProperty(HTMLMediaElement.prototype, "play", {
+      configurable: true,
+      value: async () => {},
+    });
+    Object.defineProperty(HTMLVideoElement.prototype, "videoWidth", {
+      configurable: true,
+      get: () => 640,
+    });
+    Object.defineProperty(HTMLVideoElement.prototype, "videoHeight", {
+      configurable: true,
+      get: () => 480,
+    });
+    Object.defineProperty(HTMLCanvasElement.prototype, "getContext", {
+      configurable: true,
+      value: () => ({
+        translate() {},
+        scale() {},
+        drawImage() {},
+        fillRect() {},
+        fillStyle: "#000",
+      }),
+    });
+    Object.defineProperty(HTMLCanvasElement.prototype, "toBlob", {
+      configurable: true,
+      value: (callback: BlobCallback) => callback(new Blob(
+        [new Uint8Array([0xff, 0xd8, 0xff, 0xd9])],
+        { type: "image/jpeg" }
+      )),
+    });
+
+    const mediaDevices = navigator.mediaDevices ?? {};
+    Object.defineProperty(mediaDevices, "getUserMedia", {
+      configurable: true,
+      value: async () => {
+        state.cameraRequests++;
+        sessionStorage.setItem("__booth-camera-requests", String(state.cameraRequests));
+        const stream = new MediaStream();
+        const track = {
+          readyState: "live",
+          stop() {
+            if (this.readyState === "ended") return;
+            this.readyState = "ended";
+            state.trackStops++;
+            sessionStorage.setItem("__booth-track-stops", String(state.trackStops));
+          },
+        };
+        Object.defineProperty(stream, "getTracks", {
+          configurable: true,
+          value: () => [track],
+        });
+        return stream;
+      },
+    });
+    Object.defineProperty(navigator, "mediaDevices", {
+      configurable: true,
+      value: mediaDevices,
+    });
+  });
+
+  await context.route("**/*", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    if (url.hostname !== "127.0.0.1") {
+      fixture.externalRequests.push(url.href);
+      await route.abort("blockedbyclient");
+      return;
+    }
+
+    if (!url.pathname.startsWith("/api/")) {
+      await route.continue();
+      return;
+    }
+
+    if (url.pathname === "/api/booth/preflight") {
+      const key = request.headers()["x-booth-key"] ?? "";
+      if (!ACCEPTED_KEYS.has(key)) {
+        await route.fulfill({
+          status: 401,
+          contentType: "application/json",
+          body: JSON.stringify({ error: "unauthorized" }),
+        });
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          experience: { frames: ["square", "beacon"] },
+          operationalState: {
+            version: 1,
+            paused: fixture.paused,
+            updatedAt: "2026-07-24T12:00:00.000Z",
+          },
+          serverTime: "2026-07-24T12:00:00.000Z",
+        }),
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/booth-state") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          version: 1,
+          paused: fixture.paused,
+          updatedAt: "2026-07-24T12:00:00.000Z",
+        }),
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/booths") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: "{}",
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/upload") {
+      const captureId = request.headers()["x-capture-id"] ?? "missing";
+      fixture.uploadAttempts.push(captureId);
+      if (fixture.uploadMode === "permanent") {
+        await route.fulfill({
+          status: 400,
+          contentType: "application/json",
+          body: JSON.stringify({ error: "test rejection" }),
+        });
+        return;
+      }
+      if (fixture.uploadMode === "lost-ack" && !fixture.reconnectAcknowledgement) {
+        fixture.acknowledgedIds.add(captureId);
+        await route.abort("connectionfailed");
+        return;
+      }
+      fixture.acknowledgedIds.add(captureId);
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          url: "data:image/jpeg;base64,/9j/2Q==",
+          key: `${EVENT}/mock.jpg`,
+          duplicate: fixture.uploadAttempts.filter((id) => id === captureId).length > 1,
+        }),
+      });
+      return;
+    }
+
+    throw new Error(`Unexpected API request: ${request.method()} ${url.pathname}`);
+  });
+}
+
+async function seedRecoveredPhoto(page: Page) {
+  await page.evaluate(async ({ event, id }) => {
+    const db = await new Promise<IDBDatabase>((resolve, reject) => {
+      const request = indexedDB.open("ipad-webbooth", 2);
+      request.onupgradeneeded = () => {
+        if (!request.result.objectStoreNames.contains("photo-outbox")) {
+          request.result.createObjectStore("photo-outbox", { keyPath: "id" });
+        }
+        if (!request.result.objectStoreNames.contains("photo-outbox-leases")) {
+          request.result.createObjectStore("photo-outbox-leases", { keyPath: "event" });
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(new Error(
+        request.error?.message ?? "opening the browser fixture outbox failed"
+      ));
+      request.onblocked = () => reject(new Error("browser fixture outbox was blocked"));
+    });
+    await new Promise<void>((resolve, reject) => {
+      const transaction = db.transaction("photo-outbox", "readwrite");
+      transaction.objectStore("photo-outbox").put({
+        id,
+        event,
+        // This recovered fixture never reaches upload; a byte array avoids a
+        // WebKit headless Blob-cloning limitation while exercising real IDB.
+        blob: new Uint8Array([0xff, 0xd8, 0xff, 0xd9]),
+        createdAt: 1,
+        attempts: 1,
+        lastError: "saved browser fixture",
+        failureKind: "permanent",
+        errorClass: "payload",
+        metadata: {
+          capturedAt: 1,
+          source: "framed",
+          frameKey: "square",
+        },
+      });
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () => reject(new Error(
+        transaction.error?.message ?? "seeding the browser fixture outbox failed"
+      ));
+      transaction.onabort = () => reject(new Error(
+        transaction.error?.message ?? "seeding the browser fixture outbox aborted"
+      ));
+    });
+    db.close();
+  }, { event: EVENT, id: RECOVERED_ID });
+}
+
+async function deleteOutboxPhoto(page: Page, id: string) {
+  await page.evaluate(async (itemId) => {
+    const request = indexedDB.open("ipad-webbooth", 2);
+    const db = await new Promise<IDBDatabase>((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(new Error(
+        request.error?.message ?? "opening the browser fixture outbox failed"
+      ));
+    });
+    await new Promise<void>((resolve, reject) => {
+      const transaction = db.transaction("photo-outbox", "readwrite");
+      transaction.objectStore("photo-outbox").delete(itemId);
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () => reject(new Error(
+        transaction.error?.message ?? "deleting the browser fixture outbox row failed"
+      ));
+    });
+    db.close();
+  }, id);
+}
+
+async function outboxCount(page: Page) {
+  return page.evaluate(async (event) => {
+    const request = indexedDB.open("ipad-webbooth", 2);
+    const db = await new Promise<IDBDatabase>((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(new Error(
+        request.error?.message ?? "opening the browser fixture outbox failed"
+      ));
+    });
+    const rows = await new Promise<Array<{ event: string }>>((resolve, reject) => {
+      const transaction = db.transaction("photo-outbox", "readonly");
+      const get = transaction.objectStore("photo-outbox").getAll();
+      get.onsuccess = () => resolve(get.result);
+      get.onerror = () => reject(new Error(
+        get.error?.message ?? "reading the browser fixture outbox failed"
+      ));
+    });
+    db.close();
+    return rows.filter((row) => row.event === event).length;
+  }, EVENT);
+}
+
+async function cameraState(page: Page) {
+  return page.evaluate(() => {
+    const state = (window as typeof window & {
+      __boothTest: { cameraRequests: number; trackStops: number };
+    }).__boothTest;
+    return { ...state };
+  });
+}
+
+test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
+  context,
+  page,
+}) => {
+  const fixture: ApiFixture = {
+    paused: false,
+    uploadMode: "success",
+    uploadAttempts: [],
+    acknowledgedIds: new Set(),
+    reconnectAcknowledgement: false,
+    externalRequests: [],
+    pageErrors: [],
+  };
+  await installBrowserMocks(context, fixture);
+  page.on("dialog", (dialog) => void dialog.accept());
+  page.on("pageerror", (error) => fixture.pageErrors.push(error.message));
+
+  await page.goto(`/${EVENT}`, { waitUntil: "networkidle" });
+  // Next dev may issue one full refresh after its first compilation. Let that
+  // settle before seeding origin-scoped IndexedDB and changing routes.
+  await page.waitForTimeout(750);
+  await seedRecoveredPhoto(page);
+  await page.reload();
+
+  await expect(page.getByLabel("Booth readiness").getByText("1 photo waiting safely"))
+    .toBeVisible();
+  await expect(page.getByRole("heading", { name: "Unlock Booth" })).toBeVisible();
+  expect((await cameraState(page)).cameraRequests).toBe(0);
+
+  await page.getByLabel("Booth Key").fill("wrong-key");
+  await page.getByRole("button", { name: "Unlock Booth" }).click();
+  await expect(page.getByText("Booth Key rejected")).toBeVisible();
+  await expect(page.getByLabel("Booth readiness").getByText("1 photo waiting safely"))
+    .toBeVisible();
+  expect(await outboxCount(page)).toBe(1);
+  expect((await cameraState(page)).cameraRequests).toBe(0);
+
+  await deleteOutboxPhoto(page, RECOVERED_ID);
+  await page.reload();
+  await expect(page.getByLabel("Booth readiness").getByText("No photos waiting"))
+    .toBeVisible();
+
+  await page.getByLabel("Booth Key").fill("session-key");
+  await page.getByRole("button", { name: "Unlock Booth" }).click();
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+  expect(await page.evaluate((key) => ({
+    session: sessionStorage.getItem(key),
+    local: localStorage.getItem(key),
+  }), STORAGE_KEY)).toEqual({ session: "session-key", local: null });
+  expect((await cameraState(page)).cameraRequests).toBeGreaterThan(0);
+
+  expect(fixture.pageErrors).toEqual([]);
+
+  const pickerCamera = await cameraState(page);
+  fixture.paused = true;
+  await page.reload();
+  await expect(page.getByRole("heading", { name: "Booth paused" })).toBeVisible();
+  expect((await cameraState(page)).cameraRequests).toBe(pickerCamera.cameraRequests);
+
+  fixture.paused = false;
+  await page.reload();
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+  expect((await cameraState(page)).cameraRequests).toBeGreaterThan(
+    pickerCamera.cameraRequests
+  );
+
+  fixture.uploadMode = "lost-ack";
+  await page.getByRole("button", { name: /Beacon 3 photos/ }).click();
+  await page.getByRole("button", { name: "Start" }).click();
+
+  await expect(page.getByRole("button", { name: /Retry 1 pending/ })).toBeVisible();
+  await expect.poll(() => fixture.uploadAttempts.length).toBeGreaterThan(0);
+
+  fixture.reconnectAcknowledgement = true;
+  await page.evaluate(() => window.dispatchEvent(new Event("online")));
+  await expect(page.getByRole("button", { name: /Retry 1 pending/ })).toHaveCount(0);
+  expect(new Set(fixture.uploadAttempts).size).toBe(1);
+  expect(fixture.acknowledgedIds.size).toBe(1);
+
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+
+  fixture.uploadMode = "permanent";
+  await page.getByRole("button", { name: /Square 1 photo/ }).click();
+  await page.getByRole("button", { name: "Start" }).click();
+  await expect(page.getByRole("button", { name: /Retry 1 pending/ })).toBeVisible();
+
+  const beforeExit = await cameraState(page);
+  await page.getByRole("button", { name: "Operator" }).click();
+  await page.getByLabel("Booth or Admin Key").fill("fresh-key");
+  await page.getByRole("button", { name: "Verify and exit" }).click();
+  await expect(page.getByRole("heading", { name: "Booth exited" })).toBeVisible();
+  await expect(page.getByText("1 pending photo remain in the Photo Outbox.")).toBeVisible();
+  expect((await cameraState(page)).trackStops).toBeGreaterThan(beforeExit.trackStops);
+  expect(await page.evaluate((key) => ({
+    session: sessionStorage.getItem(key),
+    local: localStorage.getItem(key),
+  }), STORAGE_KEY)).toEqual({ session: null, local: null });
+
+  // Seed the next durable recovery explicitly because WebKit headless cannot
+  // clone the mocked capture Blob into IndexedDB and correctly triggers the
+  // app's memory-only fallback for that synthetic capture.
+  await seedRecoveredPhoto(page);
+  await page.reload();
+  await expect(page.getByLabel("Booth readiness").getByText("1 photo waiting safely"))
+    .toBeVisible();
+  await page.getByLabel("Booth Key").fill("remember-key");
+  await page.getByLabel("Remember on this iPad").check();
+  await page.getByRole("button", { name: "Unlock Booth" }).click();
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+  expect(await page.evaluate((key) => ({
+    session: sessionStorage.getItem(key),
+    local: localStorage.getItem(key),
+  }), STORAGE_KEY)).toEqual({ session: null, local: "remember-key" });
+
+  const manifestHref = await page.locator('link[rel="manifest"]').getAttribute("href");
+  expect(manifestHref).toBe(`/${EVENT}/manifest.webmanifest`);
+  const manifest = await page.evaluate(async (href) => {
+    const response = await fetch(href!);
+    return response.json();
+  }, manifestHref);
+  expect(manifest).toMatchObject({
+    id: `/${EVENT}`,
+    start_url: `/${EVENT}`,
+    scope: `/${EVENT}`,
+  });
+  expect(JSON.stringify(manifest)).not.toMatch(/boothKey|credential|hash|\?/i);
+  expect(page.url()).toBe(`http://127.0.0.1:3100/${EVENT}`);
+  expect(fixture.externalRequests).toEqual([]);
+});

From 48f95f0afc634f8620b8e935bda1cc32a2fc619e Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:22:03 +0800
Subject: [PATCH 062/105] fix: close booth control review gaps

---
 .../booth-session/operational-client.ts       |   4 +-
 app/[event]/booth-unlock.test.tsx             |   7 +
 app/[event]/page.tsx                          |  18 +-
 tests/booth-control.spec.ts                   | 161 ++++++++++++++++--
 4 files changed, 167 insertions(+), 23 deletions(-)

diff --git a/app/[event]/booth-session/operational-client.ts b/app/[event]/booth-session/operational-client.ts
index 678bfb7..8051653 100644
--- a/app/[event]/booth-session/operational-client.ts
+++ b/app/[event]/booth-session/operational-client.ts
@@ -71,7 +71,7 @@ export class BoothStatePoller {
   private runEpoch = 0;
 
   constructor(private readonly options: BoothStatePollerOptions) {
-    this.fetch = options.fetch ?? fetch;
+    this.fetch = options.fetch ?? ((input, init) => fetch(input, init));
     this.onState = options.onState ?? (() => {});
     this.setTimer = options.setTimer ?? defaultSetTimer;
     this.clearTimer = options.clearTimer ?? defaultClearTimer;
@@ -167,7 +167,7 @@ export class BoothHeartbeatReporter {
   private runEpoch = 0;
 
   constructor(private readonly options: BoothHeartbeatReporterOptions) {
-    this.fetch = options.fetch ?? fetch;
+    this.fetch = options.fetch ?? ((input, init) => fetch(input, init));
     this.onAuthRequired = options.onAuthRequired ?? (() => {});
     this.setTimer = options.setTimer ?? defaultSetTimer;
     this.clearTimer = options.clearTimer ?? defaultClearTimer;
diff --git a/app/[event]/booth-unlock.test.tsx b/app/[event]/booth-unlock.test.tsx
index fbdd6d5..90bd570 100644
--- a/app/[event]/booth-unlock.test.tsx
+++ b/app/[event]/booth-unlock.test.tsx
@@ -127,6 +127,13 @@ describe("Booth page safety wiring", () => {
     expect(source).toContain('"x-booth-key": credential.key');
     expect(source).not.toContain("keyRef");
   });
+
+  test("verified Operator exit tears down the lifecycle-owned credential", async () => {
+    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
+
+    expect(source).toContain("await lifecycle.leaveEvent(session)");
+    expect(source).not.toContain("await sessionRef.current?.stop()");
+  });
 });
 
 describe("Booth unlock presentation", () => {
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 58af5cc..ee7ed92 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -315,6 +315,10 @@ export default function Booth() {
         }
       },
       onCameraStart: () => {
+        // Stored credentials can complete preflight without a fresh tap.
+        // Attempt wake anyway; gesture-restricted browsers report the visible
+        // Auto-Lock fallback instead of silently leaving the Booth unprotected.
+        void requestWake();
         const reporter = heartbeatReporterRef.current;
         if (reporter && deviceIdRef.current && sessionStartedAtRef.current) {
           const upload = uploadStateRef.current;
@@ -353,7 +357,14 @@ export default function Booth() {
         setLastSuccessfulUploadAt(Date.now());
       },
     }),
-    [applyOperationalState, pauseBoundary, startCamera, stopCamera, wakeController]
+    [
+      applyOperationalState,
+      pauseBoundary,
+      requestWake,
+      startCamera,
+      stopCamera,
+      wakeController,
+    ]
   );
 
   useEffect(() => {
@@ -690,7 +701,8 @@ export default function Booth() {
     stopHeartbeat: () => heartbeatReporterRef.current?.stop(),
     stopPoller: () => statePollerRef.current?.stop(),
     stopSession: async () => {
-      await sessionRef.current?.stop();
+      const session = sessionRef.current;
+      if (session) await lifecycle.leaveEvent(session);
     },
     clearCredentials: () => clearBoothCredential(
       event,
@@ -709,7 +721,7 @@ export default function Booth() {
       setAccessFeedback("locked");
       setAccessState("exited");
     },
-  }), [event, pauseBoundary, stopCamera, wakeController]);
+  }), [event, lifecycle, pauseBoundary, stopCamera, wakeController]);
 
   // preview crops to the chosen frame's photo aspect (w/h of its first slot),
   // so guests see exactly what will be captured. Fullscreen until a mode is set.
diff --git a/tests/booth-control.spec.ts b/tests/booth-control.spec.ts
index 0e4fa55..5089404 100644
--- a/tests/booth-control.spec.ts
+++ b/tests/booth-control.spec.ts
@@ -11,6 +11,7 @@ type ApiFixture = {
   uploadAttempts: string[];
   acknowledgedIds: Set<string>;
   reconnectAcknowledgement: boolean;
+  stateRequests: number;
   externalRequests: string[];
   pageErrors: string[];
 };
@@ -25,6 +26,8 @@ async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture)
           ? 45
           : delay === 400
             ? 60
+            : delay === 5_000
+              ? 120
             : delay;
       return nativeSetTimeout(callback, accelerated, ...args);
     }) as typeof window.setTimeout;
@@ -32,6 +35,8 @@ async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture)
     const state = {
       cameraRequests: Number(sessionStorage.getItem("__booth-camera-requests") ?? 0),
       trackStops: Number(sessionStorage.getItem("__booth-track-stops") ?? 0),
+      wakeRequests: Number(sessionStorage.getItem("__booth-wake-requests") ?? 0),
+      timeline: [] as string[],
     };
     Object.defineProperty(window, "__boothTest", {
       configurable: true,
@@ -62,12 +67,13 @@ async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture)
     });
     Object.defineProperty(HTMLCanvasElement.prototype, "toBlob", {
       configurable: true,
-      value: (callback: BlobCallback) => callback(new Blob(
-        [new Uint8Array([0xff, 0xd8, 0xff, 0xd9])],
-        { type: "image/jpeg" }
-      )),
+      value: (callback: BlobCallback) => {
+        // WebKit headless cannot structured-clone a synthetic Blob into
+        // IndexedDB. The app only transports these bytes after capture, so a
+        // cloneable byte view preserves the durable handoff path under test.
+        callback(new Uint8Array([0xff, 0xd8, 0xff, 0xd9]) as unknown as Blob);
+      },
     });
-
     const mediaDevices = navigator.mediaDevices ?? {};
     Object.defineProperty(mediaDevices, "getUserMedia", {
       configurable: true,
@@ -81,6 +87,7 @@ async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture)
             if (this.readyState === "ended") return;
             this.readyState = "ended";
             state.trackStops++;
+            state.timeline.push("track-stop");
             sessionStorage.setItem("__booth-track-stops", String(state.trackStops));
           },
         };
@@ -95,6 +102,58 @@ async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture)
       configurable: true,
       value: mediaDevices,
     });
+    Object.defineProperty(navigator, "wakeLock", {
+      configurable: true,
+      value: {
+        request: async () => {
+          state.wakeRequests++;
+          sessionStorage.setItem("__booth-wake-requests", String(state.wakeRequests));
+          throw new DOMException("test gesture restriction", "NotAllowedError");
+        },
+      },
+    });
+
+    const pendingOutboxIds = new WeakMap<IDBTransaction, string[]>();
+    const nativeTransaction = IDBDatabase.prototype.transaction;
+    Object.defineProperty(IDBDatabase.prototype, "transaction", {
+      configurable: true,
+      value: function (
+        this: IDBDatabase,
+        storeNames: string | string[],
+        mode?: IDBTransactionMode,
+        options?: IDBTransactionOptions
+      ) {
+        const transaction = nativeTransaction.call(this, storeNames, mode, options);
+        const names = typeof storeNames === "string" ? [storeNames] : storeNames;
+        if (mode === "readwrite" && names.includes("photo-outbox")) {
+          transaction.addEventListener("complete", () => {
+            for (const id of pendingOutboxIds.get(transaction) ?? []) {
+              state.timeline.push(`outbox-commit:${id}`);
+            }
+          }, { once: true });
+        }
+        return transaction;
+      },
+    });
+    const nativePut = IDBObjectStore.prototype.put;
+    Object.defineProperty(IDBObjectStore.prototype, "put", {
+      configurable: true,
+      value: function (this: IDBObjectStore, value: unknown, key?: IDBValidKey) {
+        if (
+          this.name === "photo-outbox"
+          && value
+          && typeof value === "object"
+          && typeof (value as { id?: unknown }).id === "string"
+        ) {
+          const ids = pendingOutboxIds.get(this.transaction) ?? [];
+          ids.push((value as { id: string }).id);
+          pendingOutboxIds.set(this.transaction, ids);
+        }
+        return key === undefined
+          ? nativePut.call(this, value)
+          : nativePut.call(this, value, key);
+      },
+    });
   });
 
   await context.route("**/*", async (route) => {
@@ -138,6 +197,7 @@ async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture)
     }
 
     if (url.pathname === "/api/booth-state") {
+      fixture.stateRequests++;
       await route.fulfill({
         status: 200,
         contentType: "application/json",
@@ -287,12 +347,51 @@ async function outboxCount(page: Page) {
 async function cameraState(page: Page) {
   return page.evaluate(() => {
     const state = (window as typeof window & {
-      __boothTest: { cameraRequests: number; trackStops: number };
+      __boothTest: {
+        cameraRequests: number;
+        trackStops: number;
+        wakeRequests: number;
+        timeline: string[];
+      };
     }).__boothTest;
-    return { ...state };
+    return { ...state, timeline: [...state.timeline] };
   });
 }
 
+async function resetTimeline(page: Page) {
+  await page.evaluate(() => {
+    const state = (window as typeof window & {
+      __boothTest: { timeline: string[] };
+    }).__boothTest;
+    state.timeline.length = 0;
+  });
+}
+
+async function outboxIds(page: Page) {
+  return page.evaluate(async (event) => {
+    const request = indexedDB.open("ipad-webbooth", 2);
+    const db = await new Promise<IDBDatabase>((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(new Error(
+        request.error?.message ?? "opening the browser fixture outbox failed"
+      ));
+    });
+    const rows = await new Promise<Array<{ id: string; event: string }>>((resolve, reject) => {
+      const transaction = db.transaction("photo-outbox", "readonly");
+      const get = transaction.objectStore("photo-outbox").getAll();
+      get.onsuccess = () => resolve(get.result);
+      get.onerror = () => reject(new Error(
+        get.error?.message ?? "reading the browser fixture outbox failed"
+      ));
+    });
+    db.close();
+    return rows
+      .filter((row) => row.event === event)
+      .map((row) => row.id)
+      .sort();
+  }, EVENT);
+}
+
 test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
   context,
   page,
@@ -303,6 +402,7 @@ test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
     uploadAttempts: [],
     acknowledgedIds: new Set(),
     reconnectAcknowledgement: false,
+    stateRequests: 0,
     externalRequests: [],
     pageErrors: [],
   };
@@ -343,24 +443,24 @@ test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
     local: localStorage.getItem(key),
   }), STORAGE_KEY)).toEqual({ session: "session-key", local: null });
   expect((await cameraState(page)).cameraRequests).toBeGreaterThan(0);
+  await expect.poll(() => fixture.stateRequests).toBeGreaterThan(0);
 
   expect(fixture.pageErrors).toEqual([]);
 
   const pickerCamera = await cameraState(page);
   fixture.paused = true;
-  await page.reload();
   await expect(page.getByRole("heading", { name: "Booth paused" })).toBeVisible();
+  await expect.poll(async () => (await cameraState(page)).trackStops)
+    .toBeGreaterThan(pickerCamera.trackStops);
   expect((await cameraState(page)).cameraRequests).toBe(pickerCamera.cameraRequests);
 
   fixture.paused = false;
-  await page.reload();
   await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
-  expect((await cameraState(page)).cameraRequests).toBeGreaterThan(
-    pickerCamera.cameraRequests
-  );
+  await expect.poll(async () => (await cameraState(page)).cameraRequests)
+    .toBeGreaterThan(pickerCamera.cameraRequests);
 
   fixture.uploadMode = "lost-ack";
-  await page.getByRole("button", { name: /Beacon 3 photos/ }).click();
+  await page.getByRole("button", { name: /Square 1 photo/ }).click();
   await page.getByRole("button", { name: "Start" }).click();
 
   await expect(page.getByRole("button", { name: /Retry 1 pending/ })).toBeVisible();
@@ -375,9 +475,29 @@ test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
   await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
 
   fixture.uploadMode = "permanent";
-  await page.getByRole("button", { name: /Square 1 photo/ }).click();
+  await resetTimeline(page);
+  const captureCamera = await cameraState(page);
+  await page.getByRole("button", { name: /Beacon 3 photos/ }).click();
   await page.getByRole("button", { name: "Start" }).click();
+  fixture.paused = true;
+  await expect(page.getByRole("heading", { name: "Booth paused" })).toBeVisible();
+  expect((await cameraState(page)).trackStops).toBe(captureCamera.trackStops);
   await expect(page.getByRole("button", { name: /Retry 1 pending/ })).toBeVisible();
+  const [preExitPendingId] = await outboxIds(page);
+  expect(preExitPendingId).toMatch(
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+  );
+  await expect.poll(async () => (await cameraState(page)).trackStops)
+    .toBeGreaterThan(captureCamera.trackStops);
+  const captureTimeline = (await cameraState(page)).timeline;
+  expect(captureTimeline.indexOf(`outbox-commit:${preExitPendingId}`))
+    .toBeLessThan(captureTimeline.indexOf("track-stop"));
+
+  const stoppedAfterCapture = await cameraState(page);
+  fixture.paused = false;
+  await expect.poll(async () => (await cameraState(page)).cameraRequests)
+    .toBeGreaterThan(stoppedAfterCapture.cameraRequests);
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
 
   const beforeExit = await cameraState(page);
   await page.getByRole("button", { name: "Operator" }).click();
@@ -390,14 +510,12 @@ test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
     session: sessionStorage.getItem(key),
     local: localStorage.getItem(key),
   }), STORAGE_KEY)).toEqual({ session: null, local: null });
+  expect(await outboxIds(page)).toEqual([preExitPendingId]);
 
-  // Seed the next durable recovery explicitly because WebKit headless cannot
-  // clone the mocked capture Blob into IndexedDB and correctly triggers the
-  // app's memory-only fallback for that synthetic capture.
-  await seedRecoveredPhoto(page);
   await page.reload();
   await expect(page.getByLabel("Booth readiness").getByText("1 photo waiting safely"))
     .toBeVisible();
+  expect(await outboxIds(page)).toEqual([preExitPendingId]);
   await page.getByLabel("Booth Key").fill("remember-key");
   await page.getByLabel("Remember on this iPad").check();
   await page.getByRole("button", { name: "Unlock Booth" }).click();
@@ -407,6 +525,13 @@ test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
     local: localStorage.getItem(key),
   }), STORAGE_KEY)).toEqual({ session: null, local: "remember-key" });
 
+  const wakeBeforeRelaunch = (await cameraState(page)).wakeRequests;
+  await page.reload();
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+  await expect(page.getByText("Screen Wake Lock is unavailable.")).toBeVisible();
+  expect((await cameraState(page)).wakeRequests).toBeGreaterThan(wakeBeforeRelaunch);
+  expect(await outboxIds(page)).toEqual([preExitPendingId]);
+
   const manifestHref = await page.locator('link[rel="manifest"]').getAttribute("href");
   expect(manifestHref).toBe(`/${EVENT}/manifest.webmanifest`);
   const manifest = await page.evaluate(async (href) => {

From 120e5d553381c949f572a3e98174717a36500249 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:11:31 +0800
Subject: [PATCH 063/105] feat: expose private export photo sources

---
 app/event-store.test.ts    | 141 +++++++++++++++++++++++++++++++++++--
 app/event-store.ts         |  81 +++++++++++++--------
 app/photo-metadata.test.ts | 103 +++++++++++++++++++++++++++
 app/photo-metadata.ts      | 124 ++++++++++++++++++++++++++++++++
 4 files changed, 414 insertions(+), 35 deletions(-)
 create mode 100644 app/photo-metadata.test.ts
 create mode 100644 app/photo-metadata.ts

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index fc25a48..0d4a11b 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -26,6 +26,7 @@ import {
   type StoredObjectBody,
 } from "./event-store";
 import type { BoothHeartbeatInput } from "./booth-control";
+import { InvalidPhotoReceiptError } from "./photo-metadata";
 
 class FailPrivatePhotoWriteStore extends InMemoryObjectStore {
   private writesFail = true;
@@ -78,6 +79,25 @@ class WaterlinePhotoStore extends InMemoryObjectStore {
   }
 }
 
+class PagedExportPhotoStore extends InMemoryObjectStore {
+  photoLists = 0;
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    if (options.prefix === "launch/") {
+      this.photoLists += 1;
+      return super.list({ ...options, limit: 1 });
+    }
+    return super.list(options);
+  }
+}
+
+class FailingReceiptReadStore extends InMemoryObjectStore {
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    if (key.includes("/photo-metadata/")) throw new Error("private STATE unavailable");
+    return super.get(key);
+  }
+}
+
 class MissingDuplicatePhotoMetadataStore extends InMemoryObjectStore {
   hideExistingPhoto = false;
 
@@ -1435,7 +1455,7 @@ describe("EventStore", () => {
     const initial = await store.listPhotos("launch");
 
     const delayed = await store.putPhoto("launch", new Uint8Array([2]).buffer, {
-      upload: { captureId: "018f0000-0000-4000-8000-000000000102", capturedAt: 1000 },
+      upload: { captureId: "018f0000-0000-4000-8000-000000000102", capturedAt: 1000000000000 },
     });
     const delta = await store.listPhotos("launch", initial.cursor);
 
@@ -1493,7 +1513,7 @@ describe("EventStore", () => {
     let duringSnapshot: Awaited<ReturnType<EventStore["putPhoto"]>> | null = null;
     photos.setFirstPhotoListHook(async () => {
       duringSnapshot = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
-        upload: { captureId: "018f0000-0000-4000-8000-000000000105", capturedAt: 1000 },
+        upload: { captureId: "018f0000-0000-4000-8000-000000000105", capturedAt: 1000000000000 },
       });
     });
 
@@ -1694,7 +1714,7 @@ describe("EventStore", () => {
     const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
     const initial = await store.listPhotos("launch");
     const upload = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
-      upload: { captureId: "018f0000-0000-4000-8000-000000000106", capturedAt: 1000 },
+      upload: { captureId: "018f0000-0000-4000-8000-000000000106", capturedAt: 1000000000000 },
     });
     photos.rejectPhotoLists = true;
 
@@ -1707,7 +1727,7 @@ describe("EventStore", () => {
     const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
     const initial = await store.listPhotos("launch");
     const upload = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
-      upload: { captureId: "018f0000-0000-4000-8000-000000000107", capturedAt: 1000 },
+      upload: { captureId: "018f0000-0000-4000-8000-000000000107", capturedAt: 1000000000000 },
     });
     await store.deletePhoto("launch", upload.key);
 
@@ -1987,4 +2007,117 @@ describe("EventStore", () => {
       expect(roundTripped.messages![key]).toBe(messages[key as keyof typeof messages]);
     }
   });
+
+  describe("export photo sources", () => {
+    const firstKey = "launch/1721793600000-018f0000-0000-4000-8000-000000000001.jpg";
+    const secondKey = "launch/1721793600001-018f0000-0000-4000-8000-000000000002.png";
+    const receipt = (key: string) => ({
+      version: 1,
+      key,
+      uploadedAt: "2026-07-24T00:00:00.000Z",
+      capturedAt: 1721793600000,
+      source: "framed",
+      frameKey: "square",
+      configRevisionId: "018f0000-0000-7000-8000-000000000001",
+    });
+
+    test("pages exact Event images and joins only each exact private receipt", async () => {
+      const photos = new PagedExportPhotoStore({
+        [firstKey]: new Uint8Array([1, 2, 3]),
+        [secondKey]: new Uint8Array([4, 5]),
+        "launch/readme.txt": "not a photo",
+        "other/1721793600000-other.jpg": new Uint8Array([9]),
+      });
+      const state = new BoothStateAccessStore();
+      state.set(photoReceiptKey("launch", firstKey), JSON.stringify(receipt(firstKey)));
+      state.set(photoReceiptKey("launch", secondKey), JSON.stringify({
+        ...receipt(secondKey),
+        source: "camera-fallback",
+        frameKey: undefined,
+      }));
+      const store = new EventStore(photos, state, "https://photos.example");
+
+      const sources = [];
+      for await (const source of store.iterateExportPhotoSources("launch")) sources.push(source);
+
+      expect(photos.photoLists).toBeGreaterThan(1);
+      expect(sources.map(({ key }) => key)).toEqual([firstKey, secondKey]);
+      expect(sources[0]).toEqual({
+        key: firstKey,
+        size: 3,
+        uploadedAt: expect.any(String),
+        receipt: {
+          capturedAt: 1721793600000,
+          source: "framed",
+          frameKey: "square",
+        },
+      });
+      expect(sources[1]?.receipt).toEqual({
+        capturedAt: 1721793600000,
+        source: "camera-fallback",
+      });
+      expect(JSON.stringify(sources)).not.toContain("configRevisionId");
+      expect(JSON.stringify(sources)).not.toContain("photo-metadata");
+      expect(state.reads).toEqual([
+        photoReceiptKey("launch", firstKey),
+        photoReceiptKey("launch", secondKey),
+      ]);
+    });
+
+    test("uses null for one missing exact receipt and never yields orphan receipts", async () => {
+      const photos = new InMemoryObjectStore({ [firstKey]: new Uint8Array([1]) });
+      const state = new InMemoryObjectStore({
+        [photoReceiptKey("launch", secondKey)]: JSON.stringify(receipt(secondKey)),
+      });
+      const store = new EventStore(photos, state, "https://photos.example");
+      const sources = [];
+      for await (const source of store.iterateExportPhotoSources("launch")) sources.push(source);
+      expect(sources).toHaveLength(1);
+      expect(sources[0]?.key).toBe(firstKey);
+      expect(sources[0]?.receipt).toBeNull();
+    });
+
+    test("rejects non-canonical Events before public or private access", async () => {
+      const photos = new BoothStateAccessStore();
+      const state = new BoothStateAccessStore();
+      const store = new EventStore(photos, state, "https://photos.example");
+      await expect(async () => {
+        for await (const _source of store.iterateExportPhotoSources("Launch Event")) {
+          // no-op
+        }
+      }).toThrow(InvalidEventSlugError);
+      expect(photos.lists).toEqual([]);
+      expect(state.reads).toEqual([]);
+    });
+
+    test("fails enriched inventory on corrupt, wrong-key, or unavailable private receipts", async () => {
+      for (const stored of [
+        { ...receipt(firstKey), version: 2 },
+        { ...receipt(firstKey), key: secondKey },
+        { ...receipt(firstKey), credential: "secret" },
+      ]) {
+        const photos = new InMemoryObjectStore({ [firstKey]: new Uint8Array([1]) });
+        const state = new InMemoryObjectStore({
+          [photoReceiptKey("launch", firstKey)]: JSON.stringify(stored),
+        });
+        const store = new EventStore(photos, state, "https://photos.example");
+        await expect(async () => {
+          for await (const _source of store.iterateExportPhotoSources("launch")) {
+            // no-op
+          }
+        }).toThrow(InvalidPhotoReceiptError);
+      }
+
+      const unavailable = new EventStore(
+        new InMemoryObjectStore({ [firstKey]: new Uint8Array([1]) }),
+        new FailingReceiptReadStore(),
+        "https://photos.example",
+      );
+      await expect(async () => {
+        for await (const _source of unavailable.iterateExportPhotoSources("launch")) {
+          // no-op
+        }
+      }).toThrow("private STATE unavailable");
+    });
+  });
 });
diff --git a/app/event-store.ts b/app/event-store.ts
index 98a05ec..40682bc 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -27,6 +27,11 @@ import {
 } from "./booth-control";
 import { canonicalEvent, InvalidEventSlugError, slugifyEvent } from "./event-identity";
 import type { StableCaptureIdentity, StableUpload } from "./upload-contract";
+import {
+  InvalidPhotoReceiptError,
+  parsePhotoReceipt,
+  type PhotoReceiptV1,
+} from "./photo-metadata";
 export { canonicalEvent, InvalidEventSlugError, slugifyEvent };
 export { EVENT_CONFIG_VERSION };
 export type { EventConfig } from "./event-config";
@@ -293,6 +298,12 @@ export type ConfigHistory = {
 };
 export type BoothHeartbeatListOptions = { cursor?: string | null; limit?: number };
 export type BoothHeartbeatPage = { booths: AdminBoothRecord[]; cursor: string | null };
+export type ExportPhotoSource = {
+  key: string;
+  size: number;
+  uploadedAt: string;
+  receipt: Pick<PhotoReceiptV1, "capturedAt" | "source" | "frameKey"> | null;
+};
 
 export class ConfigConflictError extends Error {
   constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
@@ -1172,6 +1183,38 @@ export class EventStore {
     } while (cursor);
   }
 
+  async *iterateExportPhotoSources(
+    event: string,
+  ): AsyncGenerator<ExportPhotoSource> {
+    const canonical = canonicalEvent(event);
+    for await (const photo of this.iteratePhotoObjects(canonical)) {
+      const receiptObject = await this.state.get(
+        photoReceiptKey(canonical, photo.key),
+      );
+      let receipt: ExportPhotoSource["receipt"] = null;
+      if (receiptObject) {
+        let value: unknown;
+        try {
+          value = await receiptObject.json<unknown>();
+        } catch {
+          throw new InvalidPhotoReceiptError(photo.key, "invalid_shape");
+        }
+        const parsed = parsePhotoReceipt(value, photo.key);
+        receipt = {
+          capturedAt: parsed.capturedAt,
+          ...(parsed.source !== undefined ? { source: parsed.source } : {}),
+          ...(parsed.frameKey !== undefined ? { frameKey: parsed.frameKey } : {}),
+        };
+      }
+      yield {
+        key: photo.key,
+        size: photo.size,
+        uploadedAt: photo.uploaded.toISOString(),
+        receipt,
+      };
+    }
+  }
+
   getPhoto(key: string): Promise<StoredObjectBody | null> {
     return this.photos.get(key);
   }
@@ -1596,15 +1639,7 @@ type PhotoFeedCursor = {
   sequence: number;
 };
 
-type PrivatePhotoMetadata = {
-  version: 1;
-  key: string;
-  uploadedAt: string;
-  capturedAt: number;
-  source?: StableUpload["source"];
-  frameKey?: string;
-  configRevisionId?: string;
-};
+type PrivatePhotoMetadata = PhotoReceiptV1;
 
 function photoPrivateMetadata(key: string, uploadedAt: Date, upload?: StableUpload): PrivatePhotoMetadata {
   return {
@@ -1732,30 +1767,14 @@ function parsePhotoFeedCommitted(event: string, value: unknown): PrivatePhotoFee
 }
 
 function parsePrivatePhotoMetadata(event: string, value: unknown): PrivatePhotoMetadata | null {
-  if (!isRecord(value)) return null;
-  if (
-    value.version !== 1
-    || typeof value.key !== "string"
-    || !isPhotoKey(event, value.key)
-    || typeof value.uploadedAt !== "string"
-    || Number.isNaN(Date.parse(value.uploadedAt))
-    || typeof value.capturedAt !== "number"
-    || !Number.isSafeInteger(value.capturedAt)
-    || (value.source !== undefined && value.source !== "framed" && value.source !== "camera-fallback")
-    || (value.frameKey !== undefined && !isBoundedToken(value.frameKey))
-    || (value.configRevisionId !== undefined && !isBoundedToken(value.configRevisionId))
-  ) {
+  if (!isRecord(value) || typeof value.key !== "string" || !isPhotoKey(event, value.key)) {
+    return null;
+  }
+  try {
+    return parsePhotoReceipt(value, value.key);
+  } catch {
     return null;
   }
-  return {
-    version: 1,
-    key: value.key,
-    uploadedAt: value.uploadedAt,
-    capturedAt: value.capturedAt,
-    ...(value.source ? { source: value.source } : {}),
-    ...(typeof value.frameKey === "string" ? { frameKey: value.frameKey } : {}),
-    ...(typeof value.configRevisionId === "string" ? { configRevisionId: value.configRevisionId } : {}),
-  };
 }
 
 function samePrivatePhotoMetadata(left: PrivatePhotoMetadata, right: PrivatePhotoMetadata): boolean {
diff --git a/app/photo-metadata.test.ts b/app/photo-metadata.test.ts
new file mode 100644
index 0000000..a97b896
--- /dev/null
+++ b/app/photo-metadata.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import {
+  InvalidPhotoReceiptError,
+  parsePhotoReceipt,
+  type PhotoReceiptV1,
+} from "./photo-metadata";
+
+const key = "launch/1721793600000-018f0000-0000-4000-8000-000000000001.jpg";
+const complete: PhotoReceiptV1 = {
+  version: 1,
+  key,
+  uploadedAt: "2026-07-24T00:00:00.000Z",
+  capturedAt: 1721793600000,
+  source: "framed",
+  frameKey: "square",
+  configRevisionId: "018f0000-0000-7000-8000-000000000001",
+};
+
+function expectReason(value: unknown, expectedKey: string, reason: InvalidPhotoReceiptError["reason"]) {
+  try {
+    parsePhotoReceipt(value, expectedKey);
+    throw new Error("expected receipt parsing to fail");
+  } catch (error) {
+    expect(error).toBeInstanceOf(InvalidPhotoReceiptError);
+    expect((error as InvalidPhotoReceiptError).reason).toBe(reason);
+    expect((error as InvalidPhotoReceiptError).expectedKey).toBe(expectedKey);
+  }
+}
+
+describe("photo receipt parsing", () => {
+  test("constructs a fresh complete allowlisted receipt", () => {
+    const parsed = parsePhotoReceipt(complete, key);
+    expect(parsed).toEqual(complete);
+    expect(parsed).not.toBe(complete);
+  });
+
+  test("accepts only the required fields", () => {
+    expect(parsePhotoReceipt({
+      version: 1,
+      key,
+      uploadedAt: "2026-07-24T08:00:00+08:00",
+      capturedAt: 1721793600000,
+    }, key)).toEqual({
+      version: 1,
+      key,
+      uploadedAt: "2026-07-24T08:00:00+08:00",
+      capturedAt: 1721793600000,
+    });
+  });
+
+  test("rejects invalid shapes, missing fields, extra data, and nested leaks", () => {
+    for (const value of [
+      null,
+      [],
+      {},
+      {
+        version: 1,
+        key,
+        capturedAt: complete.capturedAt,
+      },
+      { ...complete, credential: "secret" },
+      { ...complete, headers: { authorization: "secret" } },
+      { ...complete, url: "https://private.example" },
+      { ...complete, error: "raw storage error" },
+    ]) {
+      expectReason(value, key, "invalid_shape");
+    }
+  });
+
+  test("classifies unsupported versions and exact-key mismatches", () => {
+    expectReason({ ...complete, version: 2 }, key, "unsupported_version");
+    expectReason({ ...complete, key: "other/photo.jpg" }, key, "key_mismatch");
+  });
+
+  test("rejects non-RFC3339 upload timestamps", () => {
+    for (const uploadedAt of [
+      "2026-07-24",
+      "July 24, 2026",
+      "2026-07-24 00:00:00Z",
+      "2026-13-24T00:00:00Z",
+      "2026-02-30T00:00:00Z",
+      "2026-07-24T00:00:00+14:30",
+    ]) {
+      expectReason({ ...complete, uploadedAt }, key, "invalid_timestamp");
+    }
+  });
+
+  test("rejects invalid capture metadata", () => {
+    for (const patch of [
+      { capturedAt: 123 },
+      { capturedAt: 1721793600000.5 },
+      { source: "file" },
+      { frameKey: "" },
+      { frameKey: "../square" },
+      { frameKey: "x".repeat(129) },
+      { configRevisionId: "" },
+      { configRevisionId: "revision/slash" },
+      { configRevisionId: "x".repeat(129) },
+    ]) {
+      expectReason({ ...complete, ...patch }, key, "invalid_metadata");
+    }
+  });
+});
diff --git a/app/photo-metadata.ts b/app/photo-metadata.ts
new file mode 100644
index 0000000..ea6cf9c
--- /dev/null
+++ b/app/photo-metadata.ts
@@ -0,0 +1,124 @@
+import type { CaptureSource } from "./upload-contract";
+
+const RECEIPT_KEYS = new Set([
+  "version",
+  "key",
+  "uploadedAt",
+  "capturedAt",
+  "source",
+  "frameKey",
+  "configRevisionId",
+]);
+const REQUIRED_RECEIPT_KEYS = ["version", "key", "uploadedAt", "capturedAt"] as const;
+const RFC3339 =
+  /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:0\d|1[0-4]):[0-5]\d)$/;
+const SAFE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+function isRfc3339(value: unknown): value is string {
+  if (typeof value !== "string" || !RFC3339.test(value)) return false;
+  const year = Number(value.slice(0, 4));
+  const month = Number(value.slice(5, 7));
+  const day = Number(value.slice(8, 10));
+  if (day > new Date(Date.UTC(year, month, 0)).getUTCDate()) return false;
+  const offset = /[+-](\d{2}):(\d{2})$/.exec(value);
+  if (offset) {
+    const hours = Number(offset[1]);
+    const minutes = Number(offset[2]);
+    if (hours > 14 || (hours === 14 && minutes !== 0)) return false;
+  }
+  return Number.isFinite(Date.parse(value));
+}
+
+export type PhotoReceiptV1 = {
+  version: 1;
+  key: string;
+  uploadedAt: string;
+  capturedAt: number;
+  source?: CaptureSource;
+  frameKey?: string;
+  configRevisionId?: string;
+};
+
+export class InvalidPhotoReceiptError extends Error {
+  constructor(
+    readonly expectedKey: string,
+    readonly reason:
+      | "invalid_shape"
+      | "unsupported_version"
+      | "key_mismatch"
+      | "invalid_timestamp"
+      | "invalid_metadata",
+  ) {
+    super(`invalid photo receipt (${reason})`);
+    this.name = "InvalidPhotoReceiptError";
+  }
+}
+
+function invalid(
+  expectedKey: string,
+  reason: InvalidPhotoReceiptError["reason"],
+): never {
+  throw new InvalidPhotoReceiptError(expectedKey, reason);
+}
+
+export function parsePhotoReceipt(
+  value: unknown,
+  expectedKey: string,
+): PhotoReceiptV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return invalid(expectedKey, "invalid_shape");
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).some((key) => !RECEIPT_KEYS.has(key))
+    || REQUIRED_RECEIPT_KEYS.some((key) => !Object.hasOwn(record, key))
+  ) {
+    return invalid(expectedKey, "invalid_shape");
+  }
+  if (record.version !== 1) return invalid(expectedKey, "unsupported_version");
+  if (typeof record.key !== "string") return invalid(expectedKey, "invalid_shape");
+  if (record.key !== expectedKey) return invalid(expectedKey, "key_mismatch");
+  if (
+    !isRfc3339(record.uploadedAt)
+  ) {
+    return invalid(expectedKey, "invalid_timestamp");
+  }
+  if (
+    typeof record.capturedAt !== "number"
+    || !Number.isSafeInteger(record.capturedAt)
+    || record.capturedAt < 1_000_000_000_000
+    || record.capturedAt > 9_999_999_999_999
+    || (
+      record.source !== undefined
+      && record.source !== "framed"
+      && record.source !== "camera-fallback"
+    )
+    || (record.frameKey !== undefined && !SAFE_TOKEN.test(String(record.frameKey)))
+    || (
+      record.configRevisionId !== undefined
+      && !SAFE_TOKEN.test(String(record.configRevisionId))
+    )
+  ) {
+    return invalid(expectedKey, "invalid_metadata");
+  }
+  if (
+    (record.frameKey !== undefined && typeof record.frameKey !== "string")
+    || (
+      record.configRevisionId !== undefined
+      && typeof record.configRevisionId !== "string"
+    )
+  ) {
+    return invalid(expectedKey, "invalid_metadata");
+  }
+  return {
+    version: 1,
+    key: record.key,
+    uploadedAt: record.uploadedAt,
+    capturedAt: record.capturedAt,
+    ...(record.source !== undefined ? { source: record.source } : {}),
+    ...(record.frameKey !== undefined ? { frameKey: record.frameKey } : {}),
+    ...(record.configRevisionId !== undefined
+      ? { configRevisionId: record.configRevisionId }
+      : {}),
+  };
+}

From ed5cec7194112c2f839c313c953dbefb32d5798e Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:18:49 +0800
Subject: [PATCH 064/105] feat: build bounded event package artifacts

---
 app/export-package.test.ts | 268 +++++++++++++++++++++++++++
 app/export-package.ts      | 358 +++++++++++++++++++++++++++++++++++++
 2 files changed, 626 insertions(+)
 create mode 100644 app/export-package.test.ts
 create mode 100644 app/export-package.ts

diff --git a/app/export-package.test.ts b/app/export-package.test.ts
new file mode 100644
index 0000000..8c60949
--- /dev/null
+++ b/app/export-package.test.ts
@@ -0,0 +1,268 @@
+import { describe, expect, test } from "bun:test";
+import type { ExportPhotoSource } from "./event-store";
+import {
+  buildContactSheetHtml,
+  buildExportSummary,
+  buildManifestCsv,
+  encodePackageArtifacts,
+  escapeCsvCell,
+  escapeHtml,
+  preparePackageRows,
+} from "./export-package";
+
+function source(
+  key: string,
+  patch: Partial<ExportPhotoSource> = {},
+): ExportPhotoSource {
+  return {
+    key,
+    size: 10,
+    uploadedAt: "2026-07-24T00:00:00.000Z",
+    receipt: null,
+    ...patch,
+  };
+}
+
+describe("event package rows", () => {
+  test("uses safe deterministic archive names and suffixes collisions", () => {
+    const rows = preparePackageRows([
+      source("launch/1753315200000-normal.jpg"),
+      source("launch/1753315200001-a b🔥.jpg"),
+      source("launch/other/a?b.jpg"),
+      source("launch/more/a*b.jpg"),
+      source("launch/.."),
+      source("launch/\0.jpg"),
+    ], () => undefined);
+
+    expect(rows.map(({ archivePath }) => archivePath)).toEqual([
+      "photos/1753315200000-normal.jpg",
+      "photos/1753315200001-a_b_.jpg",
+      "photos/a_b.jpg",
+      "photos/a_b-2.jpg",
+      "photos/photo",
+      "photos/_.jpg",
+    ]);
+    expect(rows[0]?.key).toBe("launch/1753315200000-normal.jpg");
+  });
+
+  test("uses receipt, filename, then upload timestamps and allowlisted metadata", () => {
+    const rows = preparePackageRows([
+      source("launch/1753315200000-first.jpg", {
+        receipt: { capturedAt: 1753315100000, source: "framed", frameKey: "square" },
+      }),
+      source("launch/1753315200001-second.jpg"),
+      source("launch/no-time.jpg", {
+        uploadedAt: "2026-07-24T02:00:00.000Z",
+        receipt: { capturedAt: 1753315100002 },
+      }),
+      source("launch/no-receipt-time.jpg", {
+        uploadedAt: "2026-07-24T03:00:00.000Z",
+      }),
+    ], (frameKey) => frameKey === "square" ? "Square Frame" : undefined);
+
+    expect(rows[0]).toMatchObject({
+      capturedAtEpochMs: 1753315100000,
+      timestampSource: "receipt",
+      frameKey: "square",
+      frameLabel: "Square Frame",
+      captureSource: "framed",
+      hasReceipt: true,
+    });
+    expect(rows[1]).toMatchObject({
+      capturedAtEpochMs: 1753315200001,
+      timestampSource: "filename",
+      frameKey: "unknown",
+      captureSource: "unknown",
+      hasReceipt: false,
+    });
+    expect(rows[2]).toMatchObject({
+      timestampSource: "receipt",
+      frameKey: "unknown",
+      frameLabel: "unknown",
+      captureSource: "unknown",
+    });
+    expect(rows[3]).toMatchObject({
+      capturedAt: "2026-07-24T03:00:00.000Z",
+      timestampSource: "upload",
+    });
+  });
+});
+
+describe("event package escaping", () => {
+  test("escapes CSV injection, quotes, commas, controls, and Unicode", () => {
+    expect(escapeCsvCell(" =SUM(A1:A2)")).toBe("\"' =SUM(A1:A2)\"");
+    expect(escapeCsvCell("+cmd")).toBe("'+cmd");
+    expect(escapeCsvCell("-1")).toBe("'-1");
+    expect(escapeCsvCell("@name")).toBe("'@name");
+    expect(escapeCsvCell("a,\"b\"\r\n雪")).toBe("\"a,\"\"b\"\"\r\n雪\"");
+    expect(escapeCsvCell(42)).toBe("42");
+  });
+
+  test("builds the exact RFC4180 manifest shape", () => {
+    const row = preparePackageRows([
+      source("launch/1753315200000-photo.jpg"),
+    ], () => undefined)[0]!;
+    const csv = buildManifestCsv([row]);
+    expect(csv.startsWith(
+      "key,filename,size_bytes,uploaded_at,captured_at,timestamp_source,frame_key,frame_label,capture_source\r\n",
+    )).toBeTrue();
+    expect(csv.endsWith("\r\n")).toBeTrue();
+  });
+
+  test("escapes HTML and emits a self-contained relative-only contact sheet", () => {
+    expect(escapeHtml("<>&\"'")).toBe("&lt;&gt;&amp;&quot;&#39;");
+    const rows = preparePackageRows([
+      source("launch/1753315200000-<photo>.jpg", {
+        receipt: { capturedAt: 1753315200000, frameKey: "square" },
+      }),
+    ], () => "<Square & Frame>");
+    const summary = buildExportSummary({
+      event: "<Launch>",
+      generatedAt: new Date("2026-07-24T04:00:00.000Z"),
+      configuredTimeZone: "Asia/Singapore",
+      rows,
+    });
+    const html = buildContactSheetHtml({ event: "<Launch>", summary, rows });
+    expect(html.startsWith("<!doctype html>")).toBeTrue();
+    expect(html).toContain('<meta charset="utf-8">');
+    expect(html).toContain("@media print");
+    expect(html).toContain(rows[0]!.archivePath);
+    expect(html).toContain("&lt;Launch&gt;");
+    expect(html).toContain("&lt;Square &amp; Frame&gt;");
+    expect(html).toContain(`<time datetime="${rows[0]!.capturedAt}">`);
+    for (const forbidden of [
+      "<script",
+      "<link",
+      "<base",
+      "@import",
+      "onclick=",
+      "http:",
+      "https:",
+      'src="//',
+      rows[0]!.key,
+    ]) {
+      expect(html.toLowerCase()).not.toContain(forbidden.toLowerCase());
+    }
+
+    const empty = buildContactSheetHtml({
+      event: "empty",
+      summary: buildExportSummary({
+        event: "empty",
+        generatedAt: new Date("2026-07-24T04:00:00.000Z"),
+        rows: [],
+      }),
+      rows: [],
+    });
+    expect(empty).toContain("0 photos");
+  });
+});
+
+describe("event package summary", () => {
+  test("builds exact empty summary and falls back from an invalid timezone", () => {
+    expect(buildExportSummary({
+      event: "launch",
+      generatedAt: new Date("2026-07-24T04:00:00.000Z"),
+      configuredTimeZone: "Not/AZone",
+      rows: [],
+    })).toEqual({
+      version: 1,
+      event: "launch",
+      generatedAt: "2026-07-24T04:00:00.000Z",
+      timeZone: "UTC",
+      timeZoneSource: "utc-fallback",
+      photoCount: 0,
+      totalBytes: 0,
+      metadataCoverage: {
+        receipts: { known: 0, unknown: 0 },
+        frames: { known: 0, unknown: 0 },
+        sources: { known: 0, unknown: 0 },
+      },
+      timestampSources: { receipt: 0, filename: 0, upload: 0 },
+      firstCaptureAt: null,
+      lastCaptureAt: null,
+      frameUsage: [],
+      hourly: [],
+      busiestPeriods: [],
+    });
+  });
+
+  test("groups timezone hours, coverage, frame use, and chronological bounds", () => {
+    const rows = preparePackageRows([
+      source("launch/1730611800000-one.jpg", {
+        size: 4,
+        receipt: { capturedAt: 1730611800000, source: "framed", frameKey: "square" },
+      }),
+      source("launch/1730615400000-two.jpg", {
+        size: 6,
+        receipt: { capturedAt: 1730615400000, source: "framed", frameKey: "square" },
+      }),
+      source("launch/no-time.jpg", {
+        size: 2,
+        uploadedAt: "2024-11-03T07:30:00.000Z",
+      }),
+    ], (key) => key === "square" ? "Square" : undefined);
+    const summary = buildExportSummary({
+      event: "launch",
+      generatedAt: new Date("2026-07-24T04:00:00.000Z"),
+      configuredTimeZone: "America/New_York",
+      rows,
+    });
+
+    expect(summary).toMatchObject({
+      timeZone: "America/New_York",
+      timeZoneSource: "configured",
+      photoCount: 3,
+      totalBytes: 12,
+      metadataCoverage: {
+        receipts: { known: 2, unknown: 1 },
+        frames: { known: 2, unknown: 1 },
+        sources: { known: 2, unknown: 1 },
+      },
+      timestampSources: { receipt: 2, filename: 0, upload: 1 },
+      firstCaptureAt: "2024-11-03T05:30:00.000Z",
+      lastCaptureAt: "2024-11-03T07:30:00.000Z",
+      frameUsage: [{ frameKey: "square", frameLabel: "Square", count: 2 }],
+    });
+    expect(summary.hourly.map(({ period }) => period)).toEqual([
+      "2024-11-03 01:00 GMT-04:00",
+      "2024-11-03 01:00 GMT-05:00",
+      "2024-11-03 02:00 GMT-05:00",
+    ]);
+    expect(summary.busiestPeriods).toHaveLength(3);
+  });
+
+  test("encodes deterministic UTF-8 artifacts with pretty JSON newline", () => {
+    const rows = preparePackageRows([
+      source("launch/1753315200000-photo.jpg"),
+    ], () => undefined);
+    const artifacts = encodePackageArtifacts({
+      event: "launch",
+      generatedAt: new Date("2026-07-24T04:00:00.000Z"),
+      configuredTimeZone: "UTC",
+      rows,
+    });
+    const decoder = new TextDecoder();
+    expect(decoder.decode(artifacts.manifest)).toBe(buildManifestCsv(rows));
+    expect(decoder.decode(artifacts.summary)).toEndWith("\n");
+    expect(decoder.decode(artifacts.summary)).toContain("\n  \"version\": 1,");
+    expect(decoder.decode(artifacts.contactSheet)).toStartWith("<!doctype html>");
+  });
+
+  test("breaks equal frame counts by deterministic code-unit key order", () => {
+    const rows = preparePackageRows([
+      source("launch/1753315200000-z.jpg", {
+        receipt: { capturedAt: 1753315200000, frameKey: "a" },
+      }),
+      source("launch/1753315200001-a.jpg", {
+        receipt: { capturedAt: 1753315200001, frameKey: "Z" },
+      }),
+    ], (key) => key);
+    const summary = buildExportSummary({
+      event: "launch",
+      generatedAt: new Date("2026-07-24T04:00:00.000Z"),
+      rows,
+    });
+
+    expect(summary.frameUsage.map(({ frameKey }) => frameKey)).toEqual(["Z", "a"]);
+  });
+});
diff --git a/app/export-package.ts b/app/export-package.ts
new file mode 100644
index 0000000..aaebe21
--- /dev/null
+++ b/app/export-package.ts
@@ -0,0 +1,358 @@
+import type { ExportPhotoSource } from "./event-store";
+
+export type TimestampSource = "receipt" | "filename" | "upload";
+
+export type PackagePhotoRow = {
+  key: string;
+  filename: string;
+  archivePath: string;
+  sizeBytes: number;
+  uploadedAt: string;
+  capturedAt: string;
+  capturedAtEpochMs: number;
+  timestampSource: TimestampSource;
+  frameKey: string | "unknown";
+  frameLabel: string | "unknown";
+  captureSource: "framed" | "camera-fallback" | "unknown";
+  hasReceipt: boolean;
+};
+
+export type ExportSummaryV1 = {
+  version: 1;
+  event: string;
+  generatedAt: string;
+  timeZone: string;
+  timeZoneSource: "configured" | "utc-fallback";
+  photoCount: number;
+  totalBytes: number;
+  metadataCoverage: {
+    receipts: { known: number; unknown: number };
+    frames: { known: number; unknown: number };
+    sources: { known: number; unknown: number };
+  };
+  timestampSources: {
+    receipt: number;
+    filename: number;
+    upload: number;
+  };
+  firstCaptureAt: string | null;
+  lastCaptureAt: string | null;
+  frameUsage: Array<{
+    frameKey: string;
+    frameLabel: string;
+    count: number;
+  }>;
+  hourly: Array<{ period: string; count: number }>;
+  busiestPeriods: Array<{ period: string; count: number }>;
+};
+
+function validEpoch13(value: unknown): value is number {
+  return typeof value === "number"
+    && Number.isSafeInteger(value)
+    && value >= 1_000_000_000_000
+    && value <= 9_999_999_999_999;
+}
+
+function originalBasename(key: string): string {
+  return key.split("/").at(-1) ?? "";
+}
+
+function sanitizeFilename(value: string): string {
+  let safe = value.replace(/[^A-Za-z0-9._-]/gu, "_");
+  if (safe === "" || safe === "." || safe === "..") safe = "photo";
+  if (safe.length > 160) {
+    const dot = safe.lastIndexOf(".");
+    const extension = dot > 0 && safe.length - dot <= 16 ? safe.slice(dot) : "";
+    safe = `${safe.slice(0, 160 - extension.length)}${extension}`;
+  }
+  return safe;
+}
+
+function uniqueFilename(candidate: string, emitted: Set<string>): string {
+  const collisionKey = candidate.toLowerCase();
+  if (!emitted.has(collisionKey)) {
+    emitted.add(collisionKey);
+    return candidate;
+  }
+  const dot = candidate.lastIndexOf(".");
+  const hasExtension = dot > 0;
+  const stem = hasExtension ? candidate.slice(0, dot) : candidate;
+  const extension = hasExtension ? candidate.slice(dot) : "";
+  for (let suffix = 2; ; suffix += 1) {
+    const next = `${stem}-${suffix}${extension}`;
+    const nextKey = next.toLowerCase();
+    if (!emitted.has(nextKey)) {
+      emitted.add(nextKey);
+      return next;
+    }
+  }
+}
+
+function filenameTimestamp(filename: string): number | null {
+  const match = /^(\d{13})(?=[^0-9]|$)/.exec(filename);
+  if (!match) return null;
+  const value = Number(match[1]);
+  return validEpoch13(value) && Number.isFinite(new Date(value).getTime())
+    ? value
+    : null;
+}
+
+export function preparePackageRows(
+  sources: readonly ExportPhotoSource[],
+  frameLabelFor: (frameKey: string) => string | undefined,
+): PackagePhotoRow[] {
+  const emitted = new Set<string>();
+  return sources.map((source) => {
+    const original = originalBasename(source.key);
+    const filename = uniqueFilename(sanitizeFilename(original), emitted);
+    const receiptTimestamp = source.receipt?.capturedAt;
+    const fromFilename = filenameTimestamp(original);
+    let capturedAtEpochMs: number;
+    let timestampSource: TimestampSource;
+    if (validEpoch13(receiptTimestamp)) {
+      capturedAtEpochMs = receiptTimestamp;
+      timestampSource = "receipt";
+    } else if (fromFilename !== null) {
+      capturedAtEpochMs = fromFilename;
+      timestampSource = "filename";
+    } else {
+      capturedAtEpochMs = Date.parse(source.uploadedAt);
+      if (!Number.isFinite(capturedAtEpochMs)) {
+        throw new TypeError(`invalid public upload timestamp for ${source.key}`);
+      }
+      timestampSource = "upload";
+    }
+    const receiptFrame = source.receipt?.frameKey;
+    const frameKey = receiptFrame ?? "unknown";
+    const frameLabel =
+      receiptFrame === undefined ? "unknown" : frameLabelFor(receiptFrame) ?? "unknown";
+    return {
+      key: source.key,
+      filename,
+      archivePath: `photos/${filename}`,
+      sizeBytes: source.size,
+      uploadedAt: new Date(source.uploadedAt).toISOString(),
+      capturedAt: new Date(capturedAtEpochMs).toISOString(),
+      capturedAtEpochMs,
+      timestampSource,
+      frameKey,
+      frameLabel,
+      captureSource: source.receipt?.source ?? "unknown",
+      hasReceipt: source.receipt !== null,
+    };
+  });
+}
+
+export function escapeCsvCell(value: string | number): string {
+  const original = String(value);
+  const formulaLike = /^\s*[=+\-@]/u.test(original);
+  const safe = formulaLike ? `'${original}` : original;
+  const quote = /[",\r\n\t]/u.test(safe)
+    || /^\s|\s$/u.test(original)
+    || formulaLike && /^\s/u.test(original);
+  return quote ? `"${safe.replaceAll('"', '""')}"` : safe;
+}
+
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+const MANIFEST_COLUMNS = [
+  "key",
+  "filename",
+  "size_bytes",
+  "uploaded_at",
+  "captured_at",
+  "timestamp_source",
+  "frame_key",
+  "frame_label",
+  "capture_source",
+] as const;
+
+export function buildManifestCsv(rows: readonly PackagePhotoRow[]): string {
+  const lines = [MANIFEST_COLUMNS.join(",")];
+  for (const row of rows) {
+    lines.push([
+      row.key,
+      row.filename,
+      row.sizeBytes,
+      row.uploadedAt,
+      row.capturedAt,
+      row.timestampSource,
+      row.frameKey,
+      row.frameLabel,
+      row.captureSource,
+    ].map(escapeCsvCell).join(","));
+  }
+  return `${lines.join("\r\n")}\r\n`;
+}
+
+function validTimeZone(configured?: string): {
+  timeZone: string;
+  timeZoneSource: ExportSummaryV1["timeZoneSource"];
+} {
+  if (configured) {
+    try {
+      new Intl.DateTimeFormat("en", { timeZone: configured }).format(0);
+      return { timeZone: configured, timeZoneSource: "configured" };
+    } catch {
+      // Fall through to the deterministic safe default.
+    }
+  }
+  return { timeZone: "UTC", timeZoneSource: "utc-fallback" };
+}
+
+function normalizeOffset(value: string): string {
+  if (value === "GMT" || value === "UTC") return "GMT+00:00";
+  const match = /^GMT([+-])(\d{1,2})(?::?(\d{2}))?$/.exec(value);
+  if (!match) return value;
+  return `GMT${match[1]}${match[2]!.padStart(2, "0")}:${match[3] ?? "00"}`;
+}
+
+function hourlyPeriod(epochMs: number, timeZone: string): string {
+  const parts = new Intl.DateTimeFormat("en-CA-u-nu-latn", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    hourCycle: "h23",
+    timeZoneName: "longOffset",
+  }).formatToParts(epochMs);
+  const part = (type: Intl.DateTimeFormatPartTypes) =>
+    parts.find((candidate) => candidate.type === type)?.value ?? "";
+  return `${part("year")}-${part("month")}-${part("day")} ${part("hour")}:00 ${normalizeOffset(part("timeZoneName"))}`;
+}
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export function buildExportSummary(input: {
+  event: string;
+  generatedAt: Date;
+  configuredTimeZone?: string;
+  rows: readonly PackagePhotoRow[];
+}): ExportSummaryV1 {
+  const { timeZone, timeZoneSource } = validTimeZone(input.configuredTimeZone);
+  const timestampSources = { receipt: 0, filename: 0, upload: 0 };
+  const frameCounts = new Map<string, { frameLabel: string; count: number }>();
+  const hourCounts = new Map<string, { count: number; firstEpoch: number }>();
+  let receiptKnown = 0;
+  let frameKnown = 0;
+  let sourceKnown = 0;
+  let totalBytes = 0;
+  let firstEpoch = Number.POSITIVE_INFINITY;
+  let lastEpoch = Number.NEGATIVE_INFINITY;
+
+  for (const row of input.rows) {
+    totalBytes += row.sizeBytes;
+    timestampSources[row.timestampSource] += 1;
+    if (row.hasReceipt) receiptKnown += 1;
+    if (row.frameKey !== "unknown") {
+      frameKnown += 1;
+      const current = frameCounts.get(row.frameKey);
+      frameCounts.set(row.frameKey, {
+        frameLabel: row.frameLabel,
+        count: (current?.count ?? 0) + 1,
+      });
+    }
+    if (row.captureSource !== "unknown") sourceKnown += 1;
+    firstEpoch = Math.min(firstEpoch, row.capturedAtEpochMs);
+    lastEpoch = Math.max(lastEpoch, row.capturedAtEpochMs);
+    const period = hourlyPeriod(row.capturedAtEpochMs, timeZone);
+    const currentHour = hourCounts.get(period);
+    hourCounts.set(period, {
+      count: (currentHour?.count ?? 0) + 1,
+      firstEpoch: Math.min(currentHour?.firstEpoch ?? row.capturedAtEpochMs, row.capturedAtEpochMs),
+    });
+  }
+
+  const hourly = [...hourCounts.entries()]
+    .sort((left, right) => left[1].firstEpoch - right[1].firstEpoch)
+    .map(([period, value]) => ({ period, count: value.count }));
+  const busiestPeriods = [...hourly]
+    .sort((left, right) => right.count - left.count || compareText(left.period, right.period))
+    .slice(0, 3);
+  const frameUsage = [...frameCounts.entries()]
+    .map(([frameKey, value]) => ({ frameKey, frameLabel: value.frameLabel, count: value.count }))
+    .sort((left, right) => right.count - left.count || compareText(left.frameKey, right.frameKey));
+  const photoCount = input.rows.length;
+  return {
+    version: 1,
+    event: input.event,
+    generatedAt: input.generatedAt.toISOString(),
+    timeZone,
+    timeZoneSource,
+    photoCount,
+    totalBytes,
+    metadataCoverage: {
+      receipts: { known: receiptKnown, unknown: photoCount - receiptKnown },
+      frames: { known: frameKnown, unknown: photoCount - frameKnown },
+      sources: { known: sourceKnown, unknown: photoCount - sourceKnown },
+    },
+    timestampSources,
+    firstCaptureAt: photoCount === 0 ? null : new Date(firstEpoch).toISOString(),
+    lastCaptureAt: photoCount === 0 ? null : new Date(lastEpoch).toISOString(),
+    frameUsage,
+    hourly,
+    busiestPeriods,
+  };
+}
+
+export function buildContactSheetHtml(input: {
+  event: string;
+  summary: ExportSummaryV1;
+  rows: readonly PackagePhotoRow[];
+}): string {
+  const cards = input.rows.map((row) => {
+    const period = hourlyPeriod(row.capturedAtEpochMs, input.summary.timeZone);
+    return `<figure>
+<img src="${escapeHtml(row.archivePath)}" alt="${escapeHtml(row.filename)}" loading="lazy">
+<figcaption><strong>${escapeHtml(row.filename)}</strong><span>${escapeHtml(row.frameLabel)}</span><time datetime="${escapeHtml(row.capturedAt)}">${escapeHtml(period)}</time></figcaption>
+</figure>`;
+  }).join("\n");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(input.event)} photo contact sheet</title>
+<style>
+:root{font-family:system-ui,sans-serif;color:#171717;background:#fff}body{margin:0;padding:24px}h1{margin:0 0 4px}.summary{margin:0 0 24px;color:#555}.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:16px}figure{margin:0;border:1px solid #bbb;border-radius:8px;overflow:hidden;break-inside:avoid}img{display:block;width:100%;aspect-ratio:1;object-fit:contain;background:#eee}figcaption{display:grid;gap:3px;padding:10px;overflow-wrap:anywhere}figcaption span,time{font-size:.85rem;color:#555}@media print{body{padding:0}.grid{grid-template-columns:repeat(3,1fr);gap:8mm}figure{border-color:#777;border-radius:0}img{max-height:65mm}}
+</style>
+</head>
+<body>
+<h1>${escapeHtml(input.event)}</h1>
+<p class="summary">${input.summary.photoCount} photos · ${input.summary.totalBytes} bytes · ${escapeHtml(input.summary.timeZone)}</p>
+<main class="grid">${cards}</main>
+</body>
+</html>
+`;
+}
+
+export function encodePackageArtifacts(input: {
+  event: string;
+  generatedAt: Date;
+  configuredTimeZone?: string;
+  rows: readonly PackagePhotoRow[];
+}): {
+  manifest: Uint8Array;
+  summary: Uint8Array;
+  contactSheet: Uint8Array;
+} {
+  const summary = buildExportSummary(input);
+  const encoder = new TextEncoder();
+  return {
+    manifest: encoder.encode(buildManifestCsv(input.rows)),
+    summary: encoder.encode(`${JSON.stringify(summary, null, 2)}\n`),
+    contactSheet: encoder.encode(
+      buildContactSheetHtml({ event: input.event, summary, rows: input.rows }),
+    ),
+  };
+}

From c7a52b09bf578941360fbd704b0d41f6b5405ff5 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:24:27 +0800
Subject: [PATCH 065/105] fix: bound colliding export filenames

---
 app/export-package.test.ts | 12 ++++++++++++
 app/export-package.ts      | 12 +++++++++---
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/app/export-package.test.ts b/app/export-package.test.ts
index 8c60949..28a7b1a 100644
--- a/app/export-package.test.ts
+++ b/app/export-package.test.ts
@@ -45,6 +45,18 @@ describe("event package rows", () => {
     expect(rows[0]?.key).toBe("launch/1753315200000-normal.jpg");
   });
 
+  test("keeps collision suffixes inside the archive filename limit", () => {
+    const filename = `${"a".repeat(156)}.jpg`;
+    const rows = preparePackageRows([
+      source(`launch/${filename}`),
+      source(`launch/duplicate/${filename}`),
+    ], () => undefined);
+
+    expect(rows[0]!.filename).toHaveLength(160);
+    expect(rows[1]!.filename).toHaveLength(160);
+    expect(rows[1]!.filename).toBe(`${"a".repeat(154)}-2.jpg`);
+  });
+
   test("uses receipt, filename, then upload timestamps and allowlisted metadata", () => {
     const rows = preparePackageRows([
       source("launch/1753315200000-first.jpg", {
diff --git a/app/export-package.ts b/app/export-package.ts
index aaebe21..2f8d364 100644
--- a/app/export-package.ts
+++ b/app/export-package.ts
@@ -46,6 +46,8 @@ export type ExportSummaryV1 = {
   busiestPeriods: Array<{ period: string; count: number }>;
 };
 
+const MAX_ARCHIVE_FILENAME_LENGTH = 160;
+
 function validEpoch13(value: unknown): value is number {
   return typeof value === "number"
     && Number.isSafeInteger(value)
@@ -60,10 +62,10 @@ function originalBasename(key: string): string {
 function sanitizeFilename(value: string): string {
   let safe = value.replace(/[^A-Za-z0-9._-]/gu, "_");
   if (safe === "" || safe === "." || safe === "..") safe = "photo";
-  if (safe.length > 160) {
+  if (safe.length > MAX_ARCHIVE_FILENAME_LENGTH) {
     const dot = safe.lastIndexOf(".");
     const extension = dot > 0 && safe.length - dot <= 16 ? safe.slice(dot) : "";
-    safe = `${safe.slice(0, 160 - extension.length)}${extension}`;
+    safe = `${safe.slice(0, MAX_ARCHIVE_FILENAME_LENGTH - extension.length)}${extension}`;
   }
   return safe;
 }
@@ -79,7 +81,11 @@ function uniqueFilename(candidate: string, emitted: Set<string>): string {
   const stem = hasExtension ? candidate.slice(0, dot) : candidate;
   const extension = hasExtension ? candidate.slice(dot) : "";
   for (let suffix = 2; ; suffix += 1) {
-    const next = `${stem}-${suffix}${extension}`;
+    const suffixText = `-${suffix}`;
+    const stemLength = MAX_ARCHIVE_FILENAME_LENGTH
+      - suffixText.length
+      - extension.length;
+    const next = `${stem.slice(0, Math.max(1, stemLength))}${suffixText}${extension}`;
     const nextKey = next.toLowerCase();
     if (!emitted.has(nextKey)) {
       emitted.add(nextKey);

From 9dfa00335c671e90cc83d3a11e092df1413fc8ab Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:25:40 +0800
Subject: [PATCH 066/105] fix: bound dotted export collisions

---
 app/export-package.test.ts | 11 +++++++++++
 app/export-package.ts      | 18 +++++++++++-------
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/app/export-package.test.ts b/app/export-package.test.ts
index 28a7b1a..f9132ba 100644
--- a/app/export-package.test.ts
+++ b/app/export-package.test.ts
@@ -57,6 +57,17 @@ describe("event package rows", () => {
     expect(rows[1]!.filename).toBe(`${"a".repeat(154)}-2.jpg`);
   });
 
+  test("does not treat a long dotted suffix as an unbounded extension", () => {
+    const filename = `a.${"b".repeat(158)}`;
+    const rows = preparePackageRows([
+      source(`launch/${filename}`),
+      source(`launch/duplicate/${filename}`),
+    ], () => undefined);
+
+    expect(rows.map(({ filename: value }) => value.length)).toEqual([160, 160]);
+    expect(rows[1]!.filename).toEndWith("-2");
+  });
+
   test("uses receipt, filename, then upload timestamps and allowlisted metadata", () => {
     const rows = preparePackageRows([
       source("launch/1753315200000-first.jpg", {
diff --git a/app/export-package.ts b/app/export-package.ts
index 2f8d364..7f14d94 100644
--- a/app/export-package.ts
+++ b/app/export-package.ts
@@ -59,13 +59,20 @@ function originalBasename(key: string): string {
   return key.split("/").at(-1) ?? "";
 }
 
+function splitArchiveExtension(value: string): { stem: string; extension: string } {
+  const dot = value.lastIndexOf(".");
+  const hasBoundedExtension = dot > 0 && value.length - dot <= 16;
+  return hasBoundedExtension
+    ? { stem: value.slice(0, dot), extension: value.slice(dot) }
+    : { stem: value, extension: "" };
+}
+
 function sanitizeFilename(value: string): string {
   let safe = value.replace(/[^A-Za-z0-9._-]/gu, "_");
   if (safe === "" || safe === "." || safe === "..") safe = "photo";
   if (safe.length > MAX_ARCHIVE_FILENAME_LENGTH) {
-    const dot = safe.lastIndexOf(".");
-    const extension = dot > 0 && safe.length - dot <= 16 ? safe.slice(dot) : "";
-    safe = `${safe.slice(0, MAX_ARCHIVE_FILENAME_LENGTH - extension.length)}${extension}`;
+    const { stem, extension } = splitArchiveExtension(safe);
+    safe = `${stem.slice(0, MAX_ARCHIVE_FILENAME_LENGTH - extension.length)}${extension}`;
   }
   return safe;
 }
@@ -76,10 +83,7 @@ function uniqueFilename(candidate: string, emitted: Set<string>): string {
     emitted.add(collisionKey);
     return candidate;
   }
-  const dot = candidate.lastIndexOf(".");
-  const hasExtension = dot > 0;
-  const stem = hasExtension ? candidate.slice(0, dot) : candidate;
-  const extension = hasExtension ? candidate.slice(dot) : "";
+  const { stem, extension } = splitArchiveExtension(candidate);
   for (let suffix = 2; ; suffix += 1) {
     const suffixText = `-${suffix}`;
     const stemLength = MAX_ARCHIVE_FILENAME_LENGTH

From 791953129ce0e1c6ce94496aaed6ad107204a55f Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:29:06 +0800
Subject: [PATCH 067/105] fix: scale colliding export filenames

---
 app/export-package.test.ts | 27 +++++++++++++++++++++++++++
 app/export-package.ts      | 21 ++++++++++++++++++---
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/app/export-package.test.ts b/app/export-package.test.ts
index f9132ba..edb819d 100644
--- a/app/export-package.test.ts
+++ b/app/export-package.test.ts
@@ -68,6 +68,33 @@ describe("event package rows", () => {
     expect(rows[1]!.filename).toEndWith("-2");
   });
 
+  test("resolves a large normalized collision group with bounded membership probes", () => {
+    const originalHas = Set.prototype.has;
+    let membershipProbes = 0;
+    Set.prototype.has = function (value) {
+      membershipProbes += 1;
+      return originalHas.call(this, value);
+    };
+
+    try {
+      const rows = preparePackageRows(
+        Array.from({ length: 1_024 }, (_, index) =>
+          source(`launch/${index}/${index % 2 === 0 ? "a?b.jpg" : "A*b.JPG"}`)),
+        () => undefined,
+      );
+
+      expect(rows[0]!.filename).toBe("a_b.jpg");
+      expect(rows[1]!.filename).toBe("A_b-2.JPG");
+      expect(rows.at(-1)!.filename).toBe("A_b-1024.JPG");
+      expect(new Set(rows.map(({ filename }) => filename.toLowerCase())).size).toBe(
+        rows.length,
+      );
+      expect(membershipProbes).toBeLessThan(5_000);
+    } finally {
+      Set.prototype.has = originalHas;
+    }
+  });
+
   test("uses receipt, filename, then upload timestamps and allowlisted metadata", () => {
     const rows = preparePackageRows([
       source("launch/1753315200000-first.jpg", {
diff --git a/app/export-package.ts b/app/export-package.ts
index 7f14d94..e8dec7e 100644
--- a/app/export-package.ts
+++ b/app/export-package.ts
@@ -77,14 +77,23 @@ function sanitizeFilename(value: string): string {
   return safe;
 }
 
-function uniqueFilename(candidate: string, emitted: Set<string>): string {
+function uniqueFilename(
+  candidate: string,
+  emitted: Set<string>,
+  nextSuffixByCollisionKey: Map<string, number>,
+): string {
   const collisionKey = candidate.toLowerCase();
   if (!emitted.has(collisionKey)) {
     emitted.add(collisionKey);
+    nextSuffixByCollisionKey.set(collisionKey, 2);
     return candidate;
   }
   const { stem, extension } = splitArchiveExtension(candidate);
-  for (let suffix = 2; ; suffix += 1) {
+  for (
+    let suffix = nextSuffixByCollisionKey.get(collisionKey) ?? 2;
+    ;
+    suffix += 1
+  ) {
     const suffixText = `-${suffix}`;
     const stemLength = MAX_ARCHIVE_FILENAME_LENGTH
       - suffixText.length
@@ -93,6 +102,7 @@ function uniqueFilename(candidate: string, emitted: Set<string>): string {
     const nextKey = next.toLowerCase();
     if (!emitted.has(nextKey)) {
       emitted.add(nextKey);
+      nextSuffixByCollisionKey.set(collisionKey, suffix + 1);
       return next;
     }
   }
@@ -112,9 +122,14 @@ export function preparePackageRows(
   frameLabelFor: (frameKey: string) => string | undefined,
 ): PackagePhotoRow[] {
   const emitted = new Set<string>();
+  const nextSuffixByCollisionKey = new Map<string, number>();
   return sources.map((source) => {
     const original = originalBasename(source.key);
-    const filename = uniqueFilename(sanitizeFilename(original), emitted);
+    const filename = uniqueFilename(
+      sanitizeFilename(original),
+      emitted,
+      nextSuffixByCollisionKey,
+    );
     const receiptTimestamp = source.receipt?.capturedAt;
     const fromFilename = filenameTimestamp(original);
     let capturedAtEpochMs: number;

From c70a398028934e09694785929f6eb452ab061f35 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:58:37 +0800
Subject: [PATCH 068/105] feat: guard exact composite review decisions

---
 .../booth-session/capture-flow.test.ts        | 215 ++++++++++++++++++
 app/[event]/booth-session/capture-flow.ts     | 144 ++++++++++++
 app/[event]/booth-session/review.test.ts      | 125 ++++++++++
 app/[event]/booth-session/review.ts           |  73 ++++++
 app/templates.test.ts                         | 170 +++++++++++++-
 app/templates.ts                              |  31 ++-
 6 files changed, 753 insertions(+), 5 deletions(-)
 create mode 100644 app/[event]/booth-session/capture-flow.test.ts
 create mode 100644 app/[event]/booth-session/capture-flow.ts
 create mode 100644 app/[event]/booth-session/review.test.ts
 create mode 100644 app/[event]/booth-session/review.ts

diff --git a/app/[event]/booth-session/capture-flow.test.ts b/app/[event]/booth-session/capture-flow.test.ts
new file mode 100644
index 0000000..057509e
--- /dev/null
+++ b/app/[event]/booth-session/capture-flow.test.ts
@@ -0,0 +1,215 @@
+import { describe, expect, test } from "bun:test";
+import {
+  INITIAL_CAPTURE_FLOW_STATE,
+  reduceCaptureFlow,
+  type CaptureFlowState,
+  type ReviewCandidate,
+} from "./capture-flow";
+
+const canvas = { width: 1200, height: 1800 } as HTMLCanvasElement;
+const candidate: ReviewCandidate = {
+  id: "candidate-current",
+  source: "framed",
+  frameKey: "lighthouse",
+  canvas,
+};
+
+function capturing(frameKey = "lighthouse"): CaptureFlowState {
+  return {
+    ...INITIAL_CAPTURE_FLOW_STATE,
+    phase: "capturing",
+    frameKey,
+  };
+}
+
+describe("reduceCaptureFlow", () => {
+  test("a fresh Frame choice moves from picker through ready to capturing", () => {
+    const ready = reduceCaptureFlow(INITIAL_CAPTURE_FLOW_STATE, {
+      type: "select-frame",
+      frameKey: "beacon",
+    });
+    expect(ready).toEqual({
+      phase: "ready",
+      frameKey: "beacon",
+      candidate: null,
+      autoAcceptPending: false,
+      error: null,
+    });
+
+    expect(reduceCaptureFlow(ready, { type: "start-capture" })).toEqual({
+      ...ready,
+      phase: "capturing",
+    });
+  });
+
+  test("capture completion retains the selected Frame and enters timed review", () => {
+    const next = reduceCaptureFlow(capturing(), {
+      type: "capture-complete",
+      candidate,
+      reviewEnabled: true,
+    });
+
+    expect(next).toEqual({
+      phase: "reviewing",
+      frameKey: "lighthouse",
+      candidate,
+      autoAcceptPending: true,
+      error: null,
+    });
+  });
+
+  test("Retake returns to ready with the same Frame", () => {
+    const reviewing = reduceCaptureFlow(capturing(), {
+      type: "capture-complete",
+      candidate,
+      reviewEnabled: true,
+    });
+
+    expect(reduceCaptureFlow(reviewing, {
+      type: "retake",
+      candidateId: candidate.id,
+    })).toEqual({
+      phase: "ready",
+      frameKey: "lighthouse",
+      candidate: null,
+      autoAcceptPending: false,
+      error: null,
+    });
+  });
+
+  test("acceptance synchronously enters accepting and disables automatic acceptance", () => {
+    const reviewing = reduceCaptureFlow(capturing(), {
+      type: "capture-complete",
+      candidate,
+      reviewEnabled: true,
+    });
+
+    const accepting = reduceCaptureFlow(reviewing, {
+      type: "accept",
+      candidateId: candidate.id,
+    });
+
+    expect(accepting.phase).toBe("accepting");
+    expect(accepting.candidate).toBe(candidate);
+    expect(accepting.autoAcceptPending).toBe(false);
+  });
+
+  test("encode or enqueue failure returns the same candidate to untimed review", () => {
+    const accepting: CaptureFlowState = {
+      phase: "accepting",
+      frameKey: "lighthouse",
+      candidate,
+      autoAcceptPending: false,
+      error: null,
+    };
+
+    expect(reduceCaptureFlow(accepting, {
+      type: "accept-failed",
+      candidateId: candidate.id,
+      error: "Could not save the photo",
+    })).toEqual({
+      phase: "reviewing",
+      frameKey: "lighthouse",
+      candidate,
+      autoAcceptPending: false,
+      error: "Could not save the photo",
+    });
+  });
+
+  test("durable enqueue success clears the Frame and enters handoff", () => {
+    const accepting: CaptureFlowState = {
+      phase: "accepting",
+      frameKey: "lighthouse",
+      candidate,
+      autoAcceptPending: false,
+      error: null,
+    };
+
+    expect(reduceCaptureFlow(accepting, {
+      type: "enqueue-succeeded",
+      candidateId: candidate.id,
+    })).toEqual({
+      phase: "handoff",
+      frameKey: null,
+      candidate: null,
+      autoAcceptPending: false,
+      error: null,
+    });
+  });
+
+  test("completed handoff resets to a fresh Frame picker", () => {
+    const handoff: CaptureFlowState = {
+      phase: "handoff",
+      frameKey: null,
+      candidate: null,
+      autoAcceptPending: false,
+      error: null,
+    };
+
+    expect(reduceCaptureFlow(handoff, { type: "handoff-complete" })).toBe(
+      INITIAL_CAPTURE_FLOW_STATE,
+    );
+  });
+
+  test("review-disabled capture moves directly to accepting", () => {
+    const next = reduceCaptureFlow(capturing(), {
+      type: "capture-complete",
+      candidate,
+      reviewEnabled: false,
+    });
+
+    expect(next.phase).toBe("accepting");
+    expect(next.frameKey).toBe("lighthouse");
+    expect(next.candidate).toBe(candidate);
+    expect(next.autoAcceptPending).toBe(false);
+  });
+
+  test("More Time cancels only the current candidate's timer", () => {
+    const reviewing = reduceCaptureFlow(capturing(), {
+      type: "capture-complete",
+      candidate,
+      reviewEnabled: true,
+    });
+
+    const next = reduceCaptureFlow(reviewing, {
+      type: "more-time",
+      candidateId: candidate.id,
+    });
+
+    expect(next.phase).toBe("reviewing");
+    expect(next.autoAcceptPending).toBe(false);
+    expect(next.candidate).toBe(candidate);
+  });
+
+  test("stale candidate callbacks and actions are identity no-ops", () => {
+    const reviewing = reduceCaptureFlow(capturing(), {
+      type: "capture-complete",
+      candidate,
+      reviewEnabled: true,
+    });
+    const staleReviewActions = [
+      { type: "more-time", candidateId: "candidate-old" },
+      { type: "retake", candidateId: "candidate-old" },
+      { type: "accept", candidateId: "candidate-old" },
+    ] as const;
+    const accepting = reduceCaptureFlow(reviewing, {
+      type: "accept",
+      candidateId: candidate.id,
+    });
+    const staleAcceptanceActions = [
+      {
+        type: "accept-failed",
+        candidateId: "candidate-old",
+        error: "stale failure",
+      },
+      { type: "enqueue-succeeded", candidateId: "candidate-old" },
+    ] as const;
+
+    for (const action of staleReviewActions) {
+      expect(reduceCaptureFlow(reviewing, action)).toBe(reviewing);
+    }
+    for (const action of staleAcceptanceActions) {
+      expect(reduceCaptureFlow(accepting, action)).toBe(accepting);
+    }
+  });
+});
diff --git a/app/[event]/booth-session/capture-flow.ts b/app/[event]/booth-session/capture-flow.ts
new file mode 100644
index 0000000..6f29a5a
--- /dev/null
+++ b/app/[event]/booth-session/capture-flow.ts
@@ -0,0 +1,144 @@
+export type CapturePhase =
+  | "picker"
+  | "ready"
+  | "capturing"
+  | "reviewing"
+  | "accepting"
+  | "handoff";
+
+export type ReviewCandidate = {
+  id: string;
+  source: "framed" | "camera-fallback";
+  frameKey?: string;
+  canvas: HTMLCanvasElement;
+};
+
+export type CaptureFlowState = {
+  phase: CapturePhase;
+  frameKey: string | null;
+  candidate: ReviewCandidate | null;
+  autoAcceptPending: boolean;
+  error: string | null;
+};
+
+export type CaptureFlowAction =
+  | { type: "select-frame"; frameKey: string }
+  | { type: "start-capture" }
+  | {
+      type: "capture-complete";
+      candidate: ReviewCandidate;
+      reviewEnabled: boolean;
+    }
+  | { type: "more-time"; candidateId: string }
+  | { type: "retake"; candidateId: string }
+  | { type: "accept"; candidateId: string }
+  | { type: "accept-failed"; candidateId: string; error: string }
+  | { type: "enqueue-succeeded"; candidateId: string }
+  | { type: "handoff-complete" };
+
+export const INITIAL_CAPTURE_FLOW_STATE: CaptureFlowState = {
+  phase: "picker",
+  frameKey: null,
+  candidate: null,
+  autoAcceptPending: false,
+  error: null,
+};
+
+export function reduceCaptureFlow(
+  state: CaptureFlowState,
+  action: CaptureFlowAction
+): CaptureFlowState {
+  switch (action.type) {
+    case "select-frame":
+      if (state.phase !== "picker") return state;
+      return {
+        phase: "ready",
+        frameKey: action.frameKey,
+        candidate: null,
+        autoAcceptPending: false,
+        error: null,
+      };
+
+    case "start-capture":
+      if (state.phase !== "ready" || !state.frameKey) return state;
+      return { ...state, phase: "capturing", error: null };
+
+    case "capture-complete":
+      if (state.phase !== "capturing") return state;
+      return {
+        ...state,
+        phase: action.reviewEnabled ? "reviewing" : "accepting",
+        candidate: action.candidate,
+        autoAcceptPending: action.reviewEnabled,
+        error: null,
+      };
+
+    case "more-time":
+      if (!isCurrentCandidate(state, action.candidateId, "reviewing")) {
+        return state;
+      }
+      if (!state.autoAcceptPending) return state;
+      return { ...state, autoAcceptPending: false };
+
+    case "retake":
+      if (!isCurrentCandidate(state, action.candidateId, "reviewing")) {
+        return state;
+      }
+      return {
+        phase: "ready",
+        frameKey: state.frameKey,
+        candidate: null,
+        autoAcceptPending: false,
+        error: null,
+      };
+
+    case "accept":
+      if (!isCurrentCandidate(state, action.candidateId, "reviewing")) {
+        return state;
+      }
+      return {
+        ...state,
+        phase: "accepting",
+        autoAcceptPending: false,
+        error: null,
+      };
+
+    case "accept-failed":
+      if (!isCurrentCandidate(state, action.candidateId, "accepting")) {
+        return state;
+      }
+      return {
+        ...state,
+        phase: "reviewing",
+        autoAcceptPending: false,
+        error: action.error,
+      };
+
+    case "enqueue-succeeded":
+      if (!isCurrentCandidate(state, action.candidateId, "accepting")) {
+        return state;
+      }
+      return {
+        phase: "handoff",
+        frameKey: null,
+        candidate: null,
+        autoAcceptPending: false,
+        error: null,
+      };
+
+    case "handoff-complete":
+      if (state.phase !== "handoff") return state;
+      return INITIAL_CAPTURE_FLOW_STATE;
+  }
+}
+
+function isCurrentCandidate(
+  state: CaptureFlowState,
+  candidateId: string,
+  phase: "reviewing" | "accepting"
+): boolean {
+  return (
+    state.phase === phase
+    && state.candidate?.id === candidateId
+  );
+}
diff --git a/app/[event]/booth-session/review.test.ts b/app/[event]/booth-session/review.test.ts
new file mode 100644
index 0000000..940ec9f
--- /dev/null
+++ b/app/[event]/booth-session/review.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ReviewDecisionGate,
+  type ReviewChoice,
+  type ReviewClock,
+} from "./review";
+
+class ManualReviewClock implements ReviewClock {
+  private nextHandle = 0;
+  readonly timers = new Map<number, { callback: () => void; ms: number }>();
+
+  setTimeout(callback: () => void, ms: number) {
+    const handle = ++this.nextHandle;
+    this.timers.set(handle, { callback, ms });
+    return handle;
+  }
+
+  clearTimeout(handle: unknown) {
+    this.timers.delete(handle as number);
+  }
+
+  fire(handle = [...this.timers.keys()][0]) {
+    const timer = this.timers.get(handle);
+    if (!timer) return false;
+    this.timers.delete(handle);
+    timer.callback();
+    return true;
+  }
+}
+
+function setup(seconds = 5) {
+  const clock = new ManualReviewClock();
+  const decisions: ReviewChoice[] = [];
+  const gate = new ReviewDecisionGate(
+    seconds,
+    (choice) => decisions.push(choice),
+    clock,
+  );
+  return { clock, decisions, gate };
+}
+
+describe("ReviewDecisionGate", () => {
+  test("automatically accepts after the configured five seconds", () => {
+    const { clock, decisions, gate } = setup();
+
+    gate.start();
+
+    expect([...clock.timers.values()].map((timer) => timer.ms)).toEqual([5_000]);
+    clock.fire();
+    expect(decisions).toEqual(["accept"]);
+  });
+
+  test("More Time cancels automatic acceptance without deciding", () => {
+    const { clock, decisions, gate } = setup();
+    gate.start();
+    const staleTimer = [...clock.timers.values()][0].callback;
+
+    expect(gate.moreTime()).toBe(true);
+    staleTimer();
+
+    expect(clock.timers.size).toBe(0);
+    expect(decisions).toEqual([]);
+    expect(gate.accept()).toBe(true);
+    expect(decisions).toEqual(["accept"]);
+  });
+
+  test("Retake before timeout wins and cancels the timer", () => {
+    const { clock, decisions, gate } = setup();
+    gate.start();
+
+    expect(gate.retake()).toBe(true);
+
+    expect(clock.timers.size).toBe(0);
+    expect(decisions).toEqual(["retake"]);
+  });
+
+  test("a button and timer race has exactly one synchronous winner", () => {
+    const timerWins = setup();
+    timerWins.gate.start();
+    const timerHandle = [...timerWins.clock.timers.keys()][0];
+    const staleTimer = timerWins.clock.timers.get(timerHandle)!.callback;
+    timerWins.clock.fire(timerHandle);
+
+    expect(timerWins.gate.retake()).toBe(false);
+    expect(timerWins.decisions).toEqual(["accept"]);
+
+    const buttonWins = setup();
+    buttonWins.gate.start();
+    const staleButtonTimer = [...buttonWins.clock.timers.values()][0].callback;
+    expect(buttonWins.gate.accept()).toBe(true);
+    staleButtonTimer();
+
+    expect(buttonWins.gate.retake()).toBe(false);
+    expect(buttonWins.decisions).toEqual(["accept"]);
+    staleTimer();
+    expect(timerWins.decisions).toEqual(["accept"]);
+  });
+
+  test("repeated decisions and repeated More Time clicks lose", () => {
+    const { decisions, gate } = setup();
+    gate.start();
+
+    expect(gate.moreTime()).toBe(true);
+    expect(gate.moreTime()).toBe(false);
+    expect(gate.retake()).toBe(true);
+    expect(gate.retake()).toBe(false);
+    expect(gate.accept()).toBe(false);
+    expect(decisions).toEqual(["retake"]);
+  });
+
+  test("cancel prevents a stale unmount callback and all later decisions", () => {
+    const { clock, decisions, gate } = setup();
+    gate.start();
+    const staleTimer = [...clock.timers.values()][0].callback;
+
+    gate.cancel();
+    staleTimer();
+
+    expect(clock.timers.size).toBe(0);
+    expect(gate.accept()).toBe(false);
+    expect(gate.retake()).toBe(false);
+    expect(gate.moreTime()).toBe(false);
+    expect(decisions).toEqual([]);
+  });
+});
diff --git a/app/[event]/booth-session/review.ts b/app/[event]/booth-session/review.ts
new file mode 100644
index 0000000..5112b15
--- /dev/null
+++ b/app/[event]/booth-session/review.ts
@@ -0,0 +1,73 @@
+export type ReviewChoice = "accept" | "retake";
+
+export interface ReviewClock {
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+const SYSTEM_REVIEW_CLOCK: ReviewClock = {
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: (handle) =>
+    clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export class ReviewDecisionGate {
+  private status: "open" | "decided" | "cancelled" = "open";
+  private started = false;
+  private automaticAcceptanceAvailable = true;
+  private timer: { handle: unknown } | null = null;
+
+  constructor(
+    private readonly autoAcceptSeconds: number,
+    private readonly onDecision: (choice: ReviewChoice) => void,
+    private readonly clock: ReviewClock = SYSTEM_REVIEW_CLOCK
+  ) {}
+
+  start(): void {
+    if (this.status !== "open" || this.started) return;
+    this.started = true;
+    const handle = this.clock.setTimeout(
+      () => {
+        if (this.automaticAcceptanceAvailable) this.decide("accept");
+      },
+      Math.max(0, this.autoAcceptSeconds * 1_000)
+    );
+    this.timer = { handle };
+  }
+
+  accept(): boolean {
+    return this.decide("accept");
+  }
+
+  retake(): boolean {
+    return this.decide("retake");
+  }
+
+  moreTime(): boolean {
+    if (this.status !== "open" || !this.timer) return false;
+    this.automaticAcceptanceAvailable = false;
+    this.clearTimer();
+    return true;
+  }
+
+  cancel(): void {
+    if (this.status !== "open") return;
+    this.status = "cancelled";
+    this.automaticAcceptanceAvailable = false;
+    this.clearTimer();
+  }
+
+  private decide(choice: ReviewChoice): boolean {
+    if (this.status !== "open") return false;
+    this.status = "decided";
+    this.clearTimer();
+    this.onDecision(choice);
+    return true;
+  }
+
+  private clearTimer(): void {
+    const timer = this.timer;
+    this.timer = null;
+    if (timer) this.clock.clearTimeout(timer.handle);
+  }
+}
diff --git a/app/templates.test.ts b/app/templates.test.ts
index b769ca2..52aaf8a 100644
--- a/app/templates.test.ts
+++ b/app/templates.test.ts
@@ -1,5 +1,15 @@
 import { test, expect } from "bun:test";
-import { coverRect, containRect, availableTemplates, TEMPLATES, GROUPS } from "./templates";
+import {
+  coverRect,
+  containRect,
+  availableTemplates,
+  composeToCanvas,
+  encodeCanvas,
+  composite,
+  TEMPLATES,
+  GROUPS,
+  type Template,
+} from "./templates";
 
 test("no config -> only ungrouped default frames", () => {
   expect(availableTemplates(null)).toEqual(["square"]);
@@ -80,3 +90,161 @@ test("contain: never crops — drawn box fits inside the slot", () => {
   expect(r.dx).toBe(0);
   expect(Math.round(r.dh)).toBe(360); // letterboxed top/bottom
 });
+
+type FakeCanvas = HTMLCanvasElement & {
+  encodingCalls: Array<{ type?: string; quality?: number }>;
+};
+
+async function withCanvasEnvironment<T>(
+  run: (calls: string[], canvases: FakeCanvas[]) => Promise<T>,
+): Promise<T> {
+  const calls: string[] = [];
+  const canvases: FakeCanvas[] = [];
+  const previousDocument = Object.getOwnPropertyDescriptor(globalThis, "document");
+  const previousImage = Object.getOwnPropertyDescriptor(globalThis, "Image");
+
+  class FakeImage {
+    crossOrigin = "";
+    onload: (() => void) | null = null;
+    onerror: ((error: unknown) => void) | null = null;
+    private value = "";
+
+    set src(src: string) {
+      this.value = src;
+      queueMicrotask(() => this.onload?.());
+    }
+
+    get src() {
+      return this.value;
+    }
+  }
+
+  Object.defineProperty(globalThis, "Image", {
+    configurable: true,
+    value: FakeImage,
+  });
+  Object.defineProperty(globalThis, "document", {
+    configurable: true,
+    value: {
+      createElement(tag: string) {
+        expect(tag).toBe("canvas");
+        const context = {
+          fillStyle: "",
+          fillRect(x: number, y: number, w: number, h: number) {
+            calls.push(`background:${this.fillStyle}:${x},${y},${w},${h}`);
+          },
+          drawImage(source: CanvasImageSource, ...coordinates: number[]) {
+            const name =
+              source instanceof FakeImage
+                ? source.src
+                : (source as unknown as { name: string }).name;
+            calls.push(`image:${name}:${coordinates.join(",")}`);
+          },
+        };
+        const canvas = {
+          width: 0,
+          height: 0,
+          encodingCalls: [] as Array<{ type?: string; quality?: number }>,
+          getContext: () => context,
+          toBlob(
+            callback: BlobCallback,
+            type?: string,
+            quality?: number,
+          ) {
+            canvas.encodingCalls.push({ type, quality });
+            callback(new Blob(["jpeg"], { type }));
+          },
+          toDataURL() {
+            canvas.encodingCalls.push({ type: "data-url" });
+            return "data:image/jpeg;base64,";
+          },
+        } as unknown as FakeCanvas;
+        canvases.push(canvas);
+        return canvas;
+      },
+    },
+  });
+
+  try {
+    return await run(calls, canvases);
+  } finally {
+    if (previousDocument) {
+      Object.defineProperty(globalThis, "document", previousDocument);
+    } else {
+      delete (globalThis as { document?: Document }).document;
+    }
+    if (previousImage) {
+      Object.defineProperty(globalThis, "Image", previousImage);
+    } else {
+      delete (globalThis as { Image?: typeof Image }).Image;
+    }
+  }
+}
+
+const layeredTemplate: Template = {
+  label: "Layered",
+  shots: 1,
+  intervalMs: 0,
+  canvas: { w: 600, h: 400 },
+  background: "#123456",
+  bgImage: "/background.png",
+  overlay: "/overlay.png",
+  slots: [{ x: 50, y: 25, w: 500, h: 350 }],
+};
+
+test("composeToCanvas preserves background, photo, and overlay draw order without encoding", async () => {
+  await withCanvasEnvironment(async (calls, canvases) => {
+    const canvas = await composeToCanvas(
+      [{ name: "photo" } as unknown as CanvasImageSource],
+      [{ w: 1000, h: 700 }],
+      layeredTemplate,
+    );
+
+    expect(canvas).toBe(canvases[0]);
+    expect({ width: canvas.width, height: canvas.height }).toEqual({
+      width: 600,
+      height: 400,
+    });
+    expect(calls.map((call) => call.split(":")[0] + ":" + call.split(":")[1])).toEqual([
+      "background:#123456",
+      "image:/background.png",
+      "image:photo",
+      "image:/overlay.png",
+    ]);
+    expect(canvases[0].encodingCalls).toEqual([]);
+  });
+});
+
+test("encodeCanvas is the single JPEG encoding boundary with a configurable quality", async () => {
+  await withCanvasEnvironment(async (_calls, canvases) => {
+    const canvas = await composeToCanvas([], [], {
+      ...layeredTemplate,
+      background: undefined,
+      bgImage: undefined,
+      overlay: undefined,
+      slots: [],
+    });
+
+    await expect(encodeCanvas(canvas, 0.75)).resolves.toBeInstanceOf(Blob);
+    expect(canvases[0].encodingCalls).toEqual([
+      { type: "image/jpeg", quality: 0.75 },
+    ]);
+  });
+});
+
+test("composite remains a compose-then-encode compatibility wrapper", async () => {
+  await withCanvasEnvironment(async (_calls, canvases) => {
+    await expect(composite([], [], {
+      ...layeredTemplate,
+      background: undefined,
+      bgImage: undefined,
+      overlay: undefined,
+      slots: [],
+    })).resolves.toBeInstanceOf(Blob);
+
+    expect(canvases).toHaveLength(1);
+    expect(canvases[0].encodingCalls).toEqual([
+      { type: "image/jpeg", quality: 0.9 },
+    ]);
+  });
+});
diff --git a/app/templates.ts b/app/templates.ts
index 86a884e..0cc4287 100644
--- a/app/templates.ts
+++ b/app/templates.ts
@@ -54,12 +54,13 @@ function loadImage(src: string): Promise<HTMLImageElement> {
 }
 
 // Composite captured frames (already mirrored, full-res canvases) into the
-// template. Browser-only (uses canvas). Returns a JPEG blob.
-export async function composite(
+// template. Browser-only (uses canvas). The returned canvas is the exact
+// review surface and remains unencoded until the guest accepts it.
+export async function composeToCanvas(
   frames: CanvasImageSource[],
   frameSizes: { w: number; h: number }[],
   t: Template
-): Promise<Blob> {
+): Promise<HTMLCanvasElement> {
   const canvas = document.createElement("canvas");
   canvas.width = t.canvas.w;
   canvas.height = t.canvas.h;
@@ -91,7 +92,29 @@ export async function composite(
     ctx.drawImage(await loadImage(t.overlay), 0, 0, canvas.width, canvas.height);
   }
 
+  return canvas;
+}
+
+// Encode only after review acceptance so the preview and queued photo share
+// one exact composite.
+export function encodeCanvas(
+  canvas: HTMLCanvasElement,
+  quality = 0.9
+): Promise<Blob> {
   return new Promise((res, rej) =>
-    canvas.toBlob((b) => (b ? res(b) : rej(new Error("could not encode the photo"))), "image/jpeg", 0.9)
+    canvas.toBlob(
+      (b) => (b ? res(b) : rej(new Error("could not encode the photo"))),
+      "image/jpeg",
+      quality
+    )
   );
 }
+
+// Compatibility wrapper for callers that do not yet present a review step.
+export async function composite(
+  frames: CanvasImageSource[],
+  frameSizes: { w: number; h: number }[],
+  t: Template
+): Promise<Blob> {
+  return encodeCanvas(await composeToCanvas(frames, frameSizes, t));
+}

From fbc145abb84c2d5a362862baa273dfb21f65f5f3 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 21:52:32 +0800
Subject: [PATCH 069/105] feat: open exact handoff photos safely

---
 app/[event]/gallery/gallery.module.css       | 101 ++++++++
 app/[event]/gallery/handoff-gallery.test.tsx |  74 ++++++
 app/[event]/gallery/handoff-gallery.tsx      | 258 +++++++++++++++++++
 app/[event]/gallery/page.tsx                 |   5 +
 app/api/photo/handlers.test.ts               |  75 ++++++
 app/api/photo/handlers.ts                    |  39 +++
 app/api/photo/route.ts                       |  11 +
 app/event-store.test.ts                      |  44 ++++
 app/event-store.ts                           |  15 ++
 app/i18n/catalog.ts                          |  24 ++
 10 files changed, 646 insertions(+)
 create mode 100644 app/[event]/gallery/gallery.module.css
 create mode 100644 app/[event]/gallery/handoff-gallery.test.tsx
 create mode 100644 app/[event]/gallery/handoff-gallery.tsx
 create mode 100644 app/[event]/gallery/page.tsx
 create mode 100644 app/api/photo/handlers.test.ts
 create mode 100644 app/api/photo/handlers.ts
 create mode 100644 app/api/photo/route.ts

diff --git a/app/[event]/gallery/gallery.module.css b/app/[event]/gallery/gallery.module.css
new file mode 100644
index 0000000..316adb0
--- /dev/null
+++ b/app/[event]/gallery/gallery.module.css
@@ -0,0 +1,101 @@
+.gallery {
+  min-height: 100dvh;
+  display: grid;
+  place-items: center;
+  padding: max(24px, env(safe-area-inset-top)) max(20px, env(safe-area-inset-right)) max(24px, env(safe-area-inset-bottom)) max(20px, env(safe-area-inset-left));
+  color: #fff;
+  background: radial-gradient(circle at top, #3b1730, #090509 58%);
+}
+
+.card {
+  display: grid;
+  width: min(100%, 680px);
+  gap: 18px;
+  text-align: center;
+}
+
+.card h1 {
+  font-size: clamp(28px, 7vw, 52px);
+  line-height: 1;
+}
+
+.photo {
+  width: 100%;
+  max-height: 70dvh;
+  object-fit: contain;
+  border-radius: 16px;
+  background: #1b1119;
+  box-shadow: 0 18px 52px rgba(0, 0, 0, .38);
+  animation: appear 220ms ease-out;
+}
+
+.actions {
+  display: flex;
+  justify-content: center;
+}
+
+.status {
+  display: grid;
+  justify-items: center;
+  gap: 16px;
+  padding: 24px;
+  border: 1px solid rgba(255, 255, 255, .28);
+  border-radius: 16px;
+  background: rgba(16, 7, 14, .78);
+}
+
+.status p,
+.error {
+  max-width: 36rem;
+  font-size: 18px;
+  line-height: 1.45;
+}
+
+.error {
+  color: #ffc5df;
+}
+
+.primaryAction,
+.secondaryAction {
+  min-height: 44px;
+  padding: 11px 20px;
+  border: 2px solid transparent;
+  border-radius: 999px;
+  font: inherit;
+  font-weight: 750;
+  cursor: pointer;
+}
+
+.primaryAction {
+  color: #1a0712;
+  background: #ff75b5;
+}
+
+.secondaryAction {
+  color: #fff;
+  border-color: currentColor;
+  background: transparent;
+}
+
+.primaryAction:focus-visible,
+.secondaryAction:focus-visible,
+.status:focus-visible,
+.error:focus-visible {
+  outline: 3px solid #fff;
+  outline-offset: 4px;
+}
+
+@keyframes appear {
+  from { opacity: 0; transform: translateY(6px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@media (forced-colors: active) {
+  .gallery { background: Canvas; color: CanvasText; }
+  .status, .photo { border: 1px solid CanvasText; }
+  .primaryAction, .secondaryAction { color: ButtonText; background: ButtonFace; border-color: ButtonText; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .photo { animation: none; }
+}
diff --git a/app/[event]/gallery/handoff-gallery.test.tsx b/app/[event]/gallery/handoff-gallery.test.tsx
new file mode 100644
index 0000000..0c48f73
--- /dev/null
+++ b/app/[event]/gallery/handoff-gallery.test.tsx
@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  HandoffGalleryView,
+  parseDirectPhotoQuery,
+  transferPublicPhoto,
+  type HandoffGalleryState,
+} from "./handoff-gallery";
+
+const photo = {
+  key: "launch/0000000001000-photo.jpg",
+  url: "https://photos.example/launch/0000000001000-photo.jpg",
+  uploadedAt: "2026-07-24T12:00:00.000Z",
+};
+
+function render(state: HandoffGalleryState, locale: "en" | "zh-SG" | "ar" = "en") {
+  return renderToStaticMarkup(
+    <HandoffGalleryView state={state} locale={locale} onRetry={() => {}} onSave={() => {}} />
+  );
+}
+
+describe("direct photo query", () => {
+  test("accepts exactly one already-decoded complete photo query value", () => {
+    expect(parseDirectPhotoQuery(new URLSearchParams(`photo=${encodeURIComponent(photo.key)}`))).toBe(photo.key);
+    expect(parseDirectPhotoQuery(new URLSearchParams("photo=launch%252Fdouble-decoded.jpg"))).toBe("launch%2Fdouble-decoded.jpg");
+  });
+
+  test("rejects missing and repeated photo query values", () => {
+    expect(parseDirectPhotoQuery(new URLSearchParams())).toBeNull();
+    expect(parseDirectPhotoQuery(new URLSearchParams("photo=one&photo=two"))).toBeNull();
+  });
+});
+
+describe("direct photo Gallery shell", () => {
+  test("renders loading and all recoverable status states in focusable live UI", () => {
+    expect(render({ kind: "loading" })).toContain('role="status"');
+    for (const state of ["invalid", "not-found", "offline", "error"] as const) {
+      const html = render({ kind: state });
+      expect(html).toContain('role="alert"');
+      expect(html).toContain('tabindex="-1"');
+      expect(html).toContain(">Try again</button>");
+    }
+  });
+
+  test("shows only a semantic exact photo with a visible save or share action", () => {
+    const html = render({ kind: "ready", photo });
+
+    expect(html).toContain(`<img src="${photo.url}"`);
+    expect(html).toContain("Save or share");
+    expect(html).not.toContain("/api/photos");
+    expect(html).not.toMatch(/receipt|frame|revision|credential|photo-index/i);
+  });
+
+  test("uses the existing Arabic catalog and RTL direction", () => {
+    const html = render({ kind: "not-found" }, "ar");
+
+    expect(html).toContain('dir="rtl"');
+    expect(html).toContain("هذه الصورة لم تعد متاحة.");
+  });
+
+  test("falls back to a browser download when file sharing is unavailable", async () => {
+    const downloads: Array<{ filename: string; blob: Blob }> = [];
+    const outcome = await transferPublicPhoto(photo, {
+      fetchPhoto: async () => new Response(new Blob(["photo"], { type: "image/jpeg" })),
+      canShare: () => false,
+      share: async () => {},
+      download: (blob, filename) => downloads.push({ blob, filename }),
+    });
+
+    expect(outcome).toBe("downloaded");
+    expect(downloads).toHaveLength(1);
+    expect(downloads[0]!.filename).toBe("0000000001000-photo.jpg");
+  });
+});
diff --git a/app/[event]/gallery/handoff-gallery.tsx b/app/[event]/gallery/handoff-gallery.tsx
new file mode 100644
index 0000000..247f950
--- /dev/null
+++ b/app/[event]/gallery/handoff-gallery.tsx
@@ -0,0 +1,258 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useParams, useSearchParams } from "next/navigation";
+import {
+  localeDirection,
+  message,
+  SUPPORTED_LOCALES,
+  type SupportedLocale,
+} from "@/app/i18n/catalog";
+import {
+  applyDocumentLocale,
+  deviceLocaleStorageKey,
+  resolveDeviceLocale,
+} from "@/app/i18n/locale";
+import styles from "./gallery.module.css";
+
+export type DirectPhoto = { key: string; url: string; uploadedAt: string };
+export type HandoffGalleryState =
+  | { kind: "loading" }
+  | { kind: "ready"; photo: DirectPhoto }
+  | { kind: "invalid" }
+  | { kind: "not-found" }
+  | { kind: "offline" }
+  | { kind: "error" };
+
+type PhotoTransferDeps = {
+  fetchPhoto: (url: string) => Promise<Response>;
+  canShare: (data: ShareData) => boolean;
+  share: (data: ShareData) => Promise<void>;
+  download: (blob: Blob, filename: string) => void;
+};
+
+export function parseDirectPhotoQuery(params: Pick<URLSearchParams, "getAll">): string | null {
+  const values = params.getAll("photo");
+  return values.length === 1 && values[0] ? values[0] : null;
+}
+
+export async function transferPublicPhoto(
+  photo: DirectPhoto,
+  deps: PhotoTransferDeps
+): Promise<"shared" | "downloaded"> {
+  const response = await deps.fetchPhoto(photo.url);
+  if (!response.ok) throw new Error("photo download failed");
+  const blob = await response.blob();
+  const filename = photo.key.slice(photo.key.lastIndexOf("/") + 1);
+  const file = new File([blob], filename, { type: blob.type || "image/jpeg" });
+  const data = { files: [file], title: "Photo" };
+  if (deps.canShare(data)) {
+    await deps.share(data);
+    return "shared";
+  }
+  deps.download(blob, filename);
+  return "downloaded";
+}
+
+function browserTransferDeps(): PhotoTransferDeps {
+  return {
+    fetchPhoto: (url) => fetch(url),
+    canShare: (data) => typeof navigator.share === "function"
+      && typeof navigator.canShare === "function"
+      && navigator.canShare(data),
+    share: (data) => navigator.share(data),
+    download(blob, filename) {
+      const url = URL.createObjectURL(blob);
+      const link = document.createElement("a");
+      link.href = url;
+      link.download = filename;
+      link.rel = "noopener";
+      document.body.append(link);
+      link.click();
+      link.remove();
+      window.setTimeout(() => URL.revokeObjectURL(url), 0);
+    },
+  };
+}
+
+function stateMessage(locale: SupportedLocale, state: Exclude<HandoffGalleryState, { kind: "ready" }>): string {
+  switch (state.kind) {
+    case "loading": return message(locale, "galleryLoading");
+    case "invalid": return message(locale, "galleryInvalid");
+    case "not-found": return message(locale, "galleryNotFound");
+    case "offline": return message(locale, "galleryOffline");
+    case "error": return message(locale, "galleryUnavailable");
+  }
+}
+
+function isDirectPhoto(value: unknown, expectedKey: string): value is DirectPhoto {
+  if (!value || typeof value !== "object") return false;
+  const photo = value as Record<string, unknown>;
+  return photo.key === expectedKey
+    && typeof photo.url === "string"
+    && typeof photo.uploadedAt === "string";
+}
+
+function storedLocale(event: string): string | null {
+  try {
+    return window.localStorage.getItem(deviceLocaleStorageKey(event));
+  } catch {
+    return null;
+  }
+}
+
+function initialLocale(event: string): SupportedLocale {
+  return resolveDeviceLocale({
+    event,
+    configured: SUPPORTED_LOCALES,
+    storedLocale: storedLocale(event),
+    navigatorLanguages: navigator.languages,
+  });
+}
+
+type HandoffGalleryViewProps = {
+  state: HandoffGalleryState;
+  locale: SupportedLocale;
+  onRetry: () => void;
+  onSave: () => void;
+  saveError?: boolean;
+  statusRef?: (element: HTMLElement | null) => void;
+};
+
+export function HandoffGalleryView({
+  state,
+  locale,
+  onRetry,
+  onSave,
+  saveError = false,
+  statusRef,
+}: HandoffGalleryViewProps) {
+  const direction = localeDirection(locale);
+  const hasPhoto = state.kind === "ready";
+
+  return (
+    <main className={styles.gallery} lang={locale} dir={direction}>
+      <section className={styles.card}>
+        <h1>{message(locale, "handoffTitle")}</h1>
+        {hasPhoto ? (
+          <>
+            <img className={styles.photo} src={state.photo.url} alt={message(locale, "preview")} />
+            <div className={styles.actions}>
+              <button className={styles.primaryAction} type="button" onClick={onSave}>
+                {message(locale, "gallerySave")}
+              </button>
+            </div>
+            {saveError ? (
+              <p ref={statusRef} className={styles.error} role="alert" tabIndex={-1}>
+                {message(locale, "gallerySaveError")}
+              </p>
+            ) : null}
+          </>
+        ) : (
+          <section
+            ref={statusRef}
+            className={styles.status}
+            role={state.kind === "loading" ? "status" : "alert"}
+            aria-live={state.kind === "loading" ? "polite" : "assertive"}
+            tabIndex={-1}
+          >
+            <p>{stateMessage(locale, state)}</p>
+            {state.kind !== "loading" ? (
+              <button className={styles.secondaryAction} type="button" onClick={onRetry}>
+                {message(locale, "galleryRetry")}
+              </button>
+            ) : null}
+          </section>
+        )}
+      </section>
+    </main>
+  );
+}
+
+export default function HandoffGallery() {
+  const { event } = useParams<{ event: string }>();
+  const params = useSearchParams();
+  const photoKey = params ? parseDirectPhotoQuery(params) : null;
+  const [state, setState] = useState<HandoffGalleryState>({ kind: "loading" });
+  const [locale, setLocale] = useState<SupportedLocale>("en");
+  const [saveError, setSaveError] = useState(false);
+  const statusRef = useRef<HTMLElement>(null);
+  const setStatusElement = useCallback((element: HTMLElement | null) => {
+    statusRef.current = element;
+  }, []);
+
+  useEffect(() => {
+    setLocale(initialLocale(event));
+  }, [event]);
+
+  useEffect(() => {
+    applyDocumentLocale(document.documentElement, locale);
+  }, [locale]);
+
+  const load = useCallback(async (signal?: AbortSignal) => {
+    if (!photoKey) {
+      setState({ kind: "invalid" });
+      return;
+    }
+    if (!navigator.onLine) {
+      setState({ kind: "offline" });
+      return;
+    }
+
+    setSaveError(false);
+    setState({ kind: "loading" });
+    try {
+      const query = new URLSearchParams({ event, key: photoKey });
+      const response = await fetch(`/api/photo?${query}`, { cache: "no-store", signal });
+      if (response.status === 400) {
+        setState({ kind: "invalid" });
+        return;
+      }
+      if (response.status === 404) {
+        setState({ kind: "not-found" });
+        return;
+      }
+      if (!response.ok) throw new Error(`photo lookup returned ${response.status}`);
+      const payload: unknown = await response.json();
+      if (!isDirectPhoto(payload, photoKey)) {
+        setState({ kind: "invalid" });
+        return;
+      }
+      setState({ kind: "ready", photo: payload });
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") return;
+      setState({ kind: navigator.onLine ? "error" : "offline" });
+    }
+  }, [event, photoKey]);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    void load(controller.signal);
+    return () => controller.abort();
+  }, [load]);
+
+  useEffect(() => {
+    if (state.kind !== "ready" || saveError) statusRef.current?.focus();
+  }, [saveError, state.kind]);
+
+  const save = useCallback(async () => {
+    if (state.kind !== "ready") return;
+    setSaveError(false);
+    try {
+      await transferPublicPhoto(state.photo, browserTransferDeps());
+    } catch (error) {
+      if (!(error instanceof DOMException && error.name === "AbortError")) setSaveError(true);
+    }
+  }, [state]);
+
+  return (
+    <HandoffGalleryView
+      state={state}
+      locale={locale}
+      onRetry={() => { void load(); }}
+      onSave={() => { void save(); }}
+      saveError={saveError}
+      statusRef={setStatusElement}
+    />
+  );
+}
diff --git a/app/[event]/gallery/page.tsx b/app/[event]/gallery/page.tsx
new file mode 100644
index 0000000..51038ff
--- /dev/null
+++ b/app/[event]/gallery/page.tsx
@@ -0,0 +1,5 @@
+import HandoffGallery from "./handoff-gallery";
+
+export default function GalleryPage() {
+  return <HandoffGallery />;
+}
diff --git a/app/api/photo/handlers.test.ts b/app/api/photo/handlers.test.ts
new file mode 100644
index 0000000..07e4be2
--- /dev/null
+++ b/app/api/photo/handlers.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import {
+  EventStore,
+  InMemoryObjectStore,
+  type StoredObjectBody,
+} from "@/app/event-store";
+import { getPublicPhoto } from "./handlers";
+
+class ExactPhotoReadStore extends InMemoryObjectStore {
+  readonly reads: string[] = [];
+
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    this.reads.push(key);
+    return super.get(key);
+  }
+}
+
+function request(query: string): NextRequest {
+  return new NextRequest(`https://app.test/api/photo?${query}`);
+}
+
+describe("exact public photo handler", () => {
+  test("returns only the direct public photo contract without caching", async () => {
+    const uploaded = new Date("2026-07-24T12:00:00.000Z");
+    const key = "launch/0000000001000-photo.jpg";
+    const photos = new ExactPhotoReadStore();
+    photos.set(key, "photo", uploaded);
+    const response = await getPublicPhoto(
+      request(`event=launch&key=${encodeURIComponent(key)}`),
+      { store: new EventStore(photos, new InMemoryObjectStore(), "https://photos.example") }
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Cache-Control")).toBe("no-store");
+    expect(await response.json()).toEqual({
+      key,
+      url: "https://photos.example/launch/0000000001000-photo.jpg",
+      uploadedAt: uploaded.toISOString(),
+    });
+    expect(photos.reads).toEqual([key]);
+  });
+
+  test("rejects aliases and malformed, cross-Event keys before reading PHOTOS", async () => {
+    const key = "launch/0000000001000-photo.jpg";
+    const photos = new ExactPhotoReadStore();
+    photos.set(key, "photo");
+    const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+
+    for (const query of [
+      `event=Launch&key=${encodeURIComponent(key)}`,
+      "event=launch&key=launch%2F",
+      "event=launch&key=0000000001000-photo.jpg",
+      "event=launch&key=launch%2F..%2Fother%2F0000000001000-photo.jpg",
+      "event=launch&key=other%2F0000000001000-photo.jpg",
+    ]) {
+      const response = await getPublicPhoto(request(query), { store });
+      expect(response.status).toBe(400);
+    }
+    expect(photos.reads).toEqual([]);
+  });
+
+  test("returns a precise not-found response for one valid exact missing key", async () => {
+    const key = "launch/0000000001000-missing.jpg";
+    const photos = new ExactPhotoReadStore();
+    const response = await getPublicPhoto(
+      request(`event=launch&key=${encodeURIComponent(key)}`),
+      { store: new EventStore(photos, new InMemoryObjectStore(), "https://photos.example") }
+    );
+
+    expect(response.status).toBe(404);
+    expect(await response.json()).toEqual({ error: "photo not found" });
+    expect(photos.reads).toEqual([key]);
+  });
+});
diff --git a/app/api/photo/handlers.ts b/app/api/photo/handlers.ts
new file mode 100644
index 0000000..a5d8e95
--- /dev/null
+++ b/app/api/photo/handlers.ts
@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  EventStore,
+  InvalidEventSlugError,
+} from "@/app/event-store";
+
+export type PublicPhotoHandlerDeps = { store: EventStore };
+
+export async function getPublicPhoto(
+  request: NextRequest,
+  deps: PublicPhotoHandlerDeps
+): Promise<NextResponse> {
+  let event: string;
+  try {
+    event = canonicalEvent(request.nextUrl.searchParams.get("event"));
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) {
+      return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+    throw error;
+  }
+
+  const keys = request.nextUrl.searchParams.getAll("key");
+  if (keys.length !== 1 || !keys[0]) {
+    return NextResponse.json({ error: "key must be a complete Event-owned image key" }, { status: 400 });
+  }
+
+  try {
+    const photo = await deps.store.getPublicPhoto(event, keys[0]);
+    if (!photo) return NextResponse.json({ error: "photo not found" }, { status: 404 });
+    return NextResponse.json(photo, { headers: { "Cache-Control": "no-store" } });
+  } catch (error) {
+    if (error instanceof TypeError) {
+      return NextResponse.json({ error: "key must be a complete Event-owned image key" }, { status: 400 });
+    }
+    throw error;
+  }
+}
diff --git a/app/api/photo/route.ts b/app/api/photo/route.ts
new file mode 100644
index 0000000..e60490a
--- /dev/null
+++ b/app/api/photo/route.ts
@@ -0,0 +1,11 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { getPublicPhoto } from "./handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request: NextRequest) {
+  const { env } = getCloudflareContext();
+  return getPublicPhoto(request, { store: EventStore.fromEnv(env) });
+}
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 0d4a11b..f4e2f4c 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -107,6 +107,19 @@ class MissingDuplicatePhotoMetadataStore extends InMemoryObjectStore {
   }
 }
 
+class ExactPhotoReadStore extends InMemoryObjectStore {
+  readonly reads: string[] = [];
+
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    this.reads.push(key);
+    return super.get(key);
+  }
+
+  resetReads(): void {
+    this.reads.length = 0;
+  }
+}
+
 class InstrumentedStateStore extends InMemoryObjectStore {
   reads = 0;
 
@@ -1798,6 +1811,37 @@ describe("EventStore", () => {
     expect(photos.has("other/0000000001000-b.jpg")).toBe(true);
   });
 
+  test("gets only an exact public image owned by the canonical Event", async () => {
+    const uploaded = new Date("2026-07-24T12:00:00.000Z");
+    const key = "launch/0000000001000-photo.jpg";
+    const photos = new ExactPhotoReadStore();
+    photos.set(key, "photo", uploaded);
+    photos.set("other/0000000001000-photo.jpg", "other", uploaded);
+    const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
+
+    await expect(store.getPublicPhoto("launch", key)).resolves.toEqual({
+      key,
+      url: "https://photos.example/launch/0000000001000-photo.jpg",
+      uploadedAt: uploaded.toISOString(),
+    });
+    expect(photos.reads).toEqual([key]);
+
+    photos.resetReads();
+    await expect(store.getPublicPhoto("Launch", key)).rejects.toBeInstanceOf(InvalidEventSlugError);
+    for (const malformed of [
+      "launch/",
+      "0000000001000-photo.jpg",
+      "launch/../other/0000000001000-photo.jpg",
+      "other/0000000001000-photo.jpg",
+    ]) {
+      await expect(store.getPublicPhoto("launch", malformed)).rejects.toBeInstanceOf(TypeError);
+    }
+    expect(photos.reads).toEqual([]);
+
+    await expect(store.getPublicPhoto("launch", "launch/0000000001000-missing.jpg")).resolves.toBeNull();
+    expect(photos.reads).toEqual(["launch/0000000001000-missing.jpg"]);
+  });
+
   test("writes an exact private heartbeat with a server-controlled timestamp", async () => {
     const now = new Date("2026-07-24T00:00:00.000Z");
     const photos = new InMemoryObjectStore();
diff --git a/app/event-store.ts b/app/event-store.ts
index 40682bc..2b78567 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -277,6 +277,7 @@ function isPhotoKey(event: string, key: string): boolean {
 }
 
 export type Photo = { key: string; url: string; uploadedAt: Date };
+export type PublicPhoto = { key: string; url: string; uploadedAt: string };
 export type PhotoFeed = { photos: Photo[]; cursor: string | null; unchanged: boolean; truncated: boolean };
 export type PutPhotoOptions = { upload?: StableUpload };
 export type PutPhotoResult = {
@@ -1219,6 +1220,20 @@ export class EventStore {
     return this.photos.get(key);
   }
 
+  async getPublicPhoto(event: string, completeKey: string): Promise<PublicPhoto | null> {
+    const canonical = canonicalEvent(event);
+    if (!isPhotoKey(canonical, completeKey)) {
+      throw new TypeError("public photo key must be an exact Event-owned image key");
+    }
+    const object = await this.photos.get(completeKey);
+    if (!object || object.key !== completeKey) return null;
+    return {
+      key: completeKey,
+      url: this.publicUrl(completeKey),
+      uploadedAt: object.uploaded.toISOString(),
+    };
+  }
+
   async deletePhoto(event: string, key: string): Promise<boolean> {
     if (!isPhotoKey(event, key)) return false;
     const existing = await this.photos.get(key);
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
index 332e1cc..e88dc94 100644
--- a/app/i18n/catalog.ts
+++ b/app/i18n/catalog.ts
@@ -28,6 +28,14 @@ export const englishMessages = {
   handoffTitle: "Your photo is ready",
   handoffBody: "Scan to open this photo on your phone.",
   viewPhoto: "View photo",
+  galleryLoading: "Opening your photo…",
+  galleryInvalid: "This photo link is invalid.",
+  galleryNotFound: "This photo is no longer available.",
+  galleryOffline: "You’re offline. Reconnect and try again.",
+  galleryUnavailable: "We couldn’t open this photo.",
+  galleryRetry: "Try again",
+  gallerySave: "Save or share",
+  gallerySaveError: "Couldn’t save this photo. Try again.",
   nextGuest: "Next guest",
   pausedTitle: "Booth paused",
   countdownShot: "Photo {shot} of {total}",
@@ -60,6 +68,14 @@ export const chineseSingaporeMessages: Record<MessageKey, string> = {
   handoffTitle: "您的照片已准备好",
   handoffBody: "扫描二维码，在手机上打开此照片。",
   viewPhoto: "查看照片",
+  galleryLoading: "正在打开您的照片…",
+  galleryInvalid: "此照片链接无效。",
+  galleryNotFound: "此照片已无法查看。",
+  galleryOffline: "您目前处于离线状态。请重新连接后再试。",
+  galleryUnavailable: "无法打开此照片。",
+  galleryRetry: "重试",
+  gallerySave: "保存或分享",
+  gallerySaveError: "无法保存此照片。请重试。",
   nextGuest: "下一位来宾",
   pausedTitle: "拍照亭已暂停",
   countdownShot: "第 {shot} 张，共 {total} 张",
@@ -91,6 +107,14 @@ export const arabicMessages: Record<MessageKey, string> = {
   handoffTitle: "صورتك جاهزة",
   handoffBody: "امسح الرمز لفتح هذه الصورة على هاتفك.",
   viewPhoto: "اعرض الصورة",
+  galleryLoading: "جارٍ فتح صورتك…",
+  galleryInvalid: "رابط هذه الصورة غير صالح.",
+  galleryNotFound: "هذه الصورة لم تعد متاحة.",
+  galleryOffline: "أنت غير متصل. أعد الاتصال وحاول مرة أخرى.",
+  galleryUnavailable: "تعذر فتح هذه الصورة.",
+  galleryRetry: "حاول مرة أخرى",
+  gallerySave: "احفظ أو شارك",
+  gallerySaveError: "تعذر حفظ هذه الصورة. حاول مرة أخرى.",
   nextGuest: "الضيف التالي",
   pausedTitle: "كشك التصوير متوقف مؤقتًا",
   countdownShot: "الصورة {shot} من {total}",

From 1d4ccf32442972ea628082729b485525a9f275ad Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:02:35 +0800
Subject: [PATCH 070/105] fix: harden direct photo handoff

---
 app/[event]/gallery/handoff-gallery.test.tsx | 191 +++++++++++++++++-
 app/[event]/gallery/handoff-gallery.tsx      | 197 ++++++++++++++-----
 app/api/photo/handlers.test.ts               |  20 ++
 app/api/photo/handlers.ts                    |   3 +-
 app/event-store.ts                           |   8 +-
 5 files changed, 368 insertions(+), 51 deletions(-)

diff --git a/app/[event]/gallery/handoff-gallery.test.tsx b/app/[event]/gallery/handoff-gallery.test.tsx
index 0c48f73..4f65645 100644
--- a/app/[event]/gallery/handoff-gallery.test.tsx
+++ b/app/[event]/gallery/handoff-gallery.test.tsx
@@ -1,8 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
 import {
+  focusHandoffStatus,
+  HandoffGalleryController,
   HandoffGalleryView,
   parseDirectPhotoQuery,
+  prefetchPublicPhoto,
   transferPublicPhoto,
   type HandoffGalleryState,
 } from "./handoff-gallery";
@@ -13,6 +16,14 @@ const photo = {
   uploadedAt: "2026-07-24T12:00:00.000Z",
 };
 
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((next) => {
+    resolve = next;
+  });
+  return { promise, resolve };
+}
+
 function render(state: HandoffGalleryState, locale: "en" | "zh-SG" | "ar" = "en") {
   return renderToStaticMarkup(
     <HandoffGalleryView state={state} locale={locale} onRetry={() => {}} onSave={() => {}} />
@@ -58,12 +69,42 @@ describe("direct photo Gallery shell", () => {
     expect(html).toContain("هذه الصورة لم تعد متاحة.");
   });
 
-  test("falls back to a browser download when file sharing is unavailable", async () => {
+  test("prefetches before the click path and invokes native share synchronously", async () => {
+    const order: string[] = [];
+    const prefetched = await prefetchPublicPhoto(photo, async (url) => {
+      expect(url).toBe(photo.url);
+      return new Response(new Blob(["photo"], { type: "image/jpeg" }));
+    });
+    const transfer = transferPublicPhoto(photo, prefetched, {
+      fetchPhoto: async () => {
+        order.push("late fetch");
+        return new Response();
+      },
+      canShare: () => {
+        order.push("can share");
+        return true;
+      },
+      share: async () => {
+        order.push("share");
+      },
+      download: () => {
+        order.push("download");
+      },
+    });
+
+    expect(order).toEqual(["can share", "share"]);
+    expect(await transfer).toBe("shared");
+  });
+
+  test("falls back to download when native sharing rejects", async () => {
     const downloads: Array<{ filename: string; blob: Blob }> = [];
-    const outcome = await transferPublicPhoto(photo, {
+    const prefetched = new Blob(["photo"], { type: "image/jpeg" });
+    const outcome = await transferPublicPhoto(photo, prefetched, {
       fetchPhoto: async () => new Response(new Blob(["photo"], { type: "image/jpeg" })),
-      canShare: () => false,
-      share: async () => {},
+      canShare: () => true,
+      share: async () => {
+        throw new Error("native share rejected");
+      },
       download: (blob, filename) => downloads.push({ blob, filename }),
     });
 
@@ -71,4 +112,146 @@ describe("direct photo Gallery shell", () => {
     expect(downloads).toHaveLength(1);
     expect(downloads[0]!.filename).toBe("0000000001000-photo.jpg");
   });
+
+  test("uses download without attempting late native share when prefetch is unavailable", async () => {
+    const actions: string[] = [];
+    const outcome = await transferPublicPhoto(photo, null, {
+      fetchPhoto: async () => {
+        actions.push("fetch");
+        return new Response(new Blob(["photo"], { type: "image/jpeg" }));
+      },
+      canShare: () => {
+        actions.push("can share");
+        return true;
+      },
+      share: async () => {
+        actions.push("share");
+      },
+      download: () => {
+        actions.push("download");
+      },
+    });
+
+    expect(outcome).toBe("downloaded");
+    expect(actions).toEqual(["fetch", "download"]);
+  });
+});
+
+describe("interactive direct photo Gallery", () => {
+  test("loads the exact photo through loading and ready states", async () => {
+    const states: HandoffGalleryState[] = [];
+    const requests: string[] = [];
+    const controller = new HandoffGalleryController({
+      isOnline: () => true,
+      fetchPhoto: async (url) => {
+        requests.push(url);
+        return Response.json(photo);
+      },
+      onState: (state) => states.push(state),
+    });
+
+    await controller.load("launch", photo.key);
+
+    expect(requests).toEqual([
+      `/api/photo?event=launch&key=${encodeURIComponent(photo.key)}`,
+    ]);
+    expect(states).toEqual([{ kind: "loading" }, { kind: "ready", photo }]);
+  });
+
+  test("maps invalid, not-found, offline, and network failures to explicit states", async () => {
+    const states: HandoffGalleryState[] = [];
+    const responses = [
+      new Response(null, { status: 400 }),
+      new Response(null, { status: 404 }),
+    ];
+    const controller = new HandoffGalleryController({
+      isOnline: () => true,
+      fetchPhoto: async () => responses.shift() ?? Promise.reject(new Error("offline")),
+      onState: (state) => states.push(state),
+    });
+
+    await controller.load("launch", photo.key);
+    await controller.load("launch", photo.key);
+    await controller.load("launch", photo.key);
+
+    expect(states.filter((state) => state.kind !== "loading").map((state) => state.kind))
+      .toEqual(["invalid", "not-found", "error"]);
+
+    const offlineStates: HandoffGalleryState[] = [];
+    const offline = new HandoffGalleryController({
+      isOnline: () => false,
+      fetchPhoto: async () => {
+        throw new Error("must not fetch");
+      },
+      onState: (state) => offlineStates.push(state),
+    });
+    await offline.load("launch", photo.key);
+    expect(offlineStates).toEqual([{ kind: "offline" }]);
+  });
+
+  test("manual retry replaces an error with the exact photo", async () => {
+    const states: HandoffGalleryState[] = [];
+    let attempt = 0;
+    const controller = new HandoffGalleryController({
+      isOnline: () => true,
+      fetchPhoto: async () => {
+        attempt += 1;
+        return attempt === 1 ? new Response(null, { status: 503 }) : Response.json(photo);
+      },
+      onState: (state) => states.push(state),
+    });
+
+    await controller.load("launch", photo.key);
+    await controller.load("launch", photo.key);
+
+    expect(states.at(-1)).toEqual({ kind: "ready", photo });
+    expect(attempt).toBe(2);
+  });
+
+  test("aborts and fences a stale request after the Event and exact key change", async () => {
+    const first = deferred<Response>();
+    const second = deferred<Response>();
+    const firstPhoto = photo;
+    const secondPhoto = {
+      ...photo,
+      key: "other/0000000002000-photo.jpg",
+      url: "https://photos.example/other/0000000002000-photo.jpg",
+    };
+    const signals: AbortSignal[] = [];
+    const states: HandoffGalleryState[] = [];
+    let call = 0;
+    const controller = new HandoffGalleryController({
+      isOnline: () => true,
+      fetchPhoto: (_url, init) => {
+        signals.push(init.signal);
+        call += 1;
+        return call === 1 ? first.promise : second.promise;
+      },
+      onState: (state) => states.push(state),
+    });
+
+    const staleLoad = controller.load("launch", firstPhoto.key);
+    const currentLoad = controller.load("other", secondPhoto.key);
+    second.resolve(Response.json(secondPhoto));
+    await currentLoad;
+    first.resolve(Response.json(firstPhoto));
+    await staleLoad;
+
+    expect(signals[0]!.aborted).toBe(true);
+    expect(states.at(-1)).toEqual({ kind: "ready", photo: secondPhoto });
+    expect(states.filter((state) => state.kind === "ready")).toEqual([
+      { kind: "ready", photo: secondPhoto },
+    ]);
+  });
+
+  test("moves focus to status and save errors but not a ready photo", () => {
+    let focuses = 0;
+    const target = { focus: () => { focuses += 1; } };
+
+    focusHandoffStatus(target, { kind: "loading" }, false);
+    focusHandoffStatus(target, { kind: "ready", photo }, false);
+    focusHandoffStatus(target, { kind: "ready", photo }, true);
+
+    expect(focuses).toBe(2);
+  });
 });
diff --git a/app/[event]/gallery/handoff-gallery.tsx b/app/[event]/gallery/handoff-gallery.tsx
index 247f950..686880f 100644
--- a/app/[event]/gallery/handoff-gallery.tsx
+++ b/app/[event]/gallery/handoff-gallery.tsx
@@ -31,25 +31,59 @@ type PhotoTransferDeps = {
   download: (blob: Blob, filename: string) => void;
 };
 
+type HandoffGalleryControllerDeps = {
+  fetchPhoto: (
+    url: string,
+    init: { cache: "no-store"; signal: AbortSignal }
+  ) => Promise<Response>;
+  isOnline: () => boolean;
+  onState: (state: HandoffGalleryState) => void;
+};
+
 export function parseDirectPhotoQuery(params: Pick<URLSearchParams, "getAll">): string | null {
   const values = params.getAll("photo");
   return values.length === 1 && values[0] ? values[0] : null;
 }
 
+export async function prefetchPublicPhoto(
+  photo: DirectPhoto,
+  fetchPhoto: (url: string) => Promise<Response>
+): Promise<Blob> {
+  const response = await fetchPhoto(photo.url);
+  if (!response.ok) throw new Error("photo prefetch failed");
+  return response.blob();
+}
+
 export async function transferPublicPhoto(
   photo: DirectPhoto,
+  prefetchedBlob: Blob | null,
   deps: PhotoTransferDeps
 ): Promise<"shared" | "downloaded"> {
+  const filename = photo.key.slice(photo.key.lastIndexOf("/") + 1);
+  if (prefetchedBlob) {
+    const file = new File(
+      [prefetchedBlob],
+      filename,
+      { type: prefetchedBlob.type || "image/jpeg" }
+    );
+    const data = { files: [file], title: "Photo" };
+    try {
+      if (deps.canShare(data)) {
+        await deps.share(data);
+        return "shared";
+      }
+    } catch {
+      // A rejected native share still leaves a reliable direct download.
+    }
+    deps.download(prefetchedBlob, filename);
+    return "downloaded";
+  }
+
+  // Fetching here crosses Safari's transient user-activation boundary, so this
+  // path deliberately downloads instead of attempting a late native share.
   const response = await deps.fetchPhoto(photo.url);
   if (!response.ok) throw new Error("photo download failed");
   const blob = await response.blob();
-  const filename = photo.key.slice(photo.key.lastIndexOf("/") + 1);
-  const file = new File([blob], filename, { type: blob.type || "image/jpeg" });
-  const data = { files: [file], title: "Photo" };
-  if (deps.canShare(data)) {
-    await deps.share(data);
-    return "shared";
-  }
   deps.download(blob, filename);
   return "downloaded";
 }
@@ -93,6 +127,81 @@ function isDirectPhoto(value: unknown, expectedKey: string): value is DirectPhot
     && typeof photo.uploadedAt === "string";
 }
 
+export class HandoffGalleryController {
+  private generation = 0;
+  private active: AbortController | null = null;
+
+  constructor(private readonly deps: HandoffGalleryControllerDeps) {}
+
+  async load(event: string, photoKey: string | null): Promise<void> {
+    const generation = ++this.generation;
+    this.active?.abort();
+    const controller = new AbortController();
+    this.active = controller;
+    const publish = (state: HandoffGalleryState) => {
+      if (this.generation === generation && !controller.signal.aborted) {
+        this.deps.onState(state);
+      }
+    };
+
+    if (!photoKey) {
+      publish({ kind: "invalid" });
+      this.finish(generation);
+      return;
+    }
+    if (!this.deps.isOnline()) {
+      publish({ kind: "offline" });
+      this.finish(generation);
+      return;
+    }
+
+    publish({ kind: "loading" });
+    try {
+      const query = new URLSearchParams({ event, key: photoKey });
+      const response = await this.deps.fetchPhoto(`/api/photo?${query}`, {
+        cache: "no-store",
+        signal: controller.signal,
+      });
+      if (response.status === 400) {
+        publish({ kind: "invalid" });
+        return;
+      }
+      if (response.status === 404) {
+        publish({ kind: "not-found" });
+        return;
+      }
+      if (!response.ok) throw new Error(`photo lookup returned ${response.status}`);
+      const payload: unknown = await response.json();
+      publish(isDirectPhoto(payload, photoKey)
+        ? { kind: "ready", photo: payload }
+        : { kind: "invalid" });
+    } catch {
+      if (this.generation !== generation || controller.signal.aborted) return;
+      publish({ kind: this.deps.isOnline() ? "error" : "offline" });
+    } finally {
+      this.finish(generation);
+    }
+  }
+
+  cancel(): void {
+    this.generation += 1;
+    this.active?.abort();
+    this.active = null;
+  }
+
+  private finish(generation: number): void {
+    if (this.generation === generation) this.active = null;
+  }
+}
+
+export function focusHandoffStatus(
+  target: Pick<HTMLElement, "focus"> | null,
+  state: HandoffGalleryState,
+  saveError: boolean
+): void {
+  if (state.kind !== "ready" || saveError) target?.focus();
+}
+
 function storedLocale(event: string): string | null {
   try {
     return window.localStorage.getItem(deviceLocaleStorageKey(event));
@@ -177,6 +286,15 @@ export default function HandoffGallery() {
   const [locale, setLocale] = useState<SupportedLocale>("en");
   const [saveError, setSaveError] = useState(false);
   const statusRef = useRef<HTMLElement>(null);
+  const photoBlobRef = useRef<{ url: string; blob: Blob } | null>(null);
+  const controllerRef = useRef<HandoffGalleryController | null>(null);
+  if (!controllerRef.current) {
+    controllerRef.current = new HandoffGalleryController({
+      fetchPhoto: (url, init) => fetch(url, init),
+      isOnline: () => navigator.onLine,
+      onState: setState,
+    });
+  }
   const setStatusElement = useCallback((element: HTMLElement | null) => {
     statusRef.current = element;
   }, []);
@@ -189,57 +307,46 @@ export default function HandoffGallery() {
     applyDocumentLocale(document.documentElement, locale);
   }, [locale]);
 
-  const load = useCallback(async (signal?: AbortSignal) => {
-    if (!photoKey) {
-      setState({ kind: "invalid" });
-      return;
-    }
-    if (!navigator.onLine) {
-      setState({ kind: "offline" });
-      return;
-    }
-
+  const load = useCallback(async () => {
     setSaveError(false);
-    setState({ kind: "loading" });
-    try {
-      const query = new URLSearchParams({ event, key: photoKey });
-      const response = await fetch(`/api/photo?${query}`, { cache: "no-store", signal });
-      if (response.status === 400) {
-        setState({ kind: "invalid" });
-        return;
-      }
-      if (response.status === 404) {
-        setState({ kind: "not-found" });
-        return;
-      }
-      if (!response.ok) throw new Error(`photo lookup returned ${response.status}`);
-      const payload: unknown = await response.json();
-      if (!isDirectPhoto(payload, photoKey)) {
-        setState({ kind: "invalid" });
-        return;
-      }
-      setState({ kind: "ready", photo: payload });
-    } catch (error) {
-      if (error instanceof DOMException && error.name === "AbortError") return;
-      setState({ kind: navigator.onLine ? "error" : "offline" });
-    }
+    await controllerRef.current!.load(event, photoKey);
   }, [event, photoKey]);
 
   useEffect(() => {
-    const controller = new AbortController();
-    void load(controller.signal);
-    return () => controller.abort();
+    void load();
+    return () => controllerRef.current?.cancel();
   }, [load]);
 
   useEffect(() => {
-    if (state.kind !== "ready" || saveError) statusRef.current?.focus();
+    focusHandoffStatus(statusRef.current, state, saveError);
   }, [saveError, state.kind]);
 
+  useEffect(() => {
+    photoBlobRef.current = null;
+    if (state.kind !== "ready") return;
+    const photo = state.photo;
+    const controller = new AbortController();
+    let active = true;
+    void prefetchPublicPhoto(
+      photo,
+      (url) => fetch(url, { signal: controller.signal })
+    ).then((blob) => {
+      if (active) photoBlobRef.current = { url: photo.url, blob };
+    }).catch(() => {});
+    return () => {
+      active = false;
+      controller.abort();
+    };
+  }, [state]);
+
   const save = useCallback(async () => {
     if (state.kind !== "ready") return;
     setSaveError(false);
     try {
-      await transferPublicPhoto(state.photo, browserTransferDeps());
+      const prefetched = photoBlobRef.current?.url === state.photo.url
+        ? photoBlobRef.current.blob
+        : null;
+      await transferPublicPhoto(state.photo, prefetched, browserTransferDeps());
     } catch (error) {
       if (!(error instanceof DOMException && error.name === "AbortError")) setSaveError(true);
     }
diff --git a/app/api/photo/handlers.test.ts b/app/api/photo/handlers.test.ts
index 07e4be2..796da39 100644
--- a/app/api/photo/handlers.test.ts
+++ b/app/api/photo/handlers.test.ts
@@ -16,6 +16,12 @@ class ExactPhotoReadStore extends InMemoryObjectStore {
   }
 }
 
+class StorageTypeErrorStore extends InMemoryObjectStore {
+  override async get(_key: string): Promise<StoredObjectBody | null> {
+    throw new TypeError("simulated PHOTOS failure");
+  }
+}
+
 function request(query: string): NextRequest {
   return new NextRequest(`https://app.test/api/photo?${query}`);
 }
@@ -72,4 +78,18 @@ describe("exact public photo handler", () => {
     expect(await response.json()).toEqual({ error: "photo not found" });
     expect(photos.reads).toEqual([key]);
   });
+
+  test("does not misclassify an unexpected PHOTOS TypeError as invalid input", async () => {
+    const key = "launch/0000000001000-photo.jpg";
+    const store = new EventStore(
+      new StorageTypeErrorStore(),
+      new InMemoryObjectStore(),
+      "https://photos.example"
+    );
+
+    await expect(getPublicPhoto(
+      request(`event=launch&key=${encodeURIComponent(key)}`),
+      { store }
+    )).rejects.toThrow("simulated PHOTOS failure");
+  });
 });
diff --git a/app/api/photo/handlers.ts b/app/api/photo/handlers.ts
index a5d8e95..dc4bc39 100644
--- a/app/api/photo/handlers.ts
+++ b/app/api/photo/handlers.ts
@@ -3,6 +3,7 @@ import {
   canonicalEvent,
   EventStore,
   InvalidEventSlugError,
+  InvalidPublicPhotoKeyError,
 } from "@/app/event-store";
 
 export type PublicPhotoHandlerDeps = { store: EventStore };
@@ -31,7 +32,7 @@ export async function getPublicPhoto(
     if (!photo) return NextResponse.json({ error: "photo not found" }, { status: 404 });
     return NextResponse.json(photo, { headers: { "Cache-Control": "no-store" } });
   } catch (error) {
-    if (error instanceof TypeError) {
+    if (error instanceof InvalidPublicPhotoKeyError) {
       return NextResponse.json({ error: "key must be a complete Event-owned image key" }, { status: 400 });
     }
     throw error;
diff --git a/app/event-store.ts b/app/event-store.ts
index 2b78567..6010e25 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -352,6 +352,12 @@ export class InvalidPhotoCursorError extends Error {
   }
 }
 
+export class InvalidPublicPhotoKeyError extends TypeError {
+  constructor() {
+    super("public photo key must be an exact Event-owned image key");
+  }
+}
+
 export class InvalidStoredBoothHeartbeatError extends Error {
   constructor(readonly event: string) {
     super(`stored booth heartbeat for ${event} is corrupt or uses an unsupported version`);
@@ -1223,7 +1229,7 @@ export class EventStore {
   async getPublicPhoto(event: string, completeKey: string): Promise<PublicPhoto | null> {
     const canonical = canonicalEvent(event);
     if (!isPhotoKey(canonical, completeKey)) {
-      throw new TypeError("public photo key must be an exact Event-owned image key");
+      throw new InvalidPublicPhotoKeyError();
     }
     const object = await this.photos.get(completeKey);
     if (!object || object.key !== completeKey) return null;

From a6b5227b308f46005b384a3cdb267ced45528613 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:04:14 +0800
Subject: [PATCH 071/105] fix: fence capture attempts and fallback

---
 .../booth-session/capture-flow.test.ts        | 125 +++++++++++++++++-
 app/[event]/booth-session/capture-flow.ts     |  40 +++++-
 2 files changed, 160 insertions(+), 5 deletions(-)

diff --git a/app/[event]/booth-session/capture-flow.test.ts b/app/[event]/booth-session/capture-flow.test.ts
index 057509e..0fb3115 100644
--- a/app/[event]/booth-session/capture-flow.test.ts
+++ b/app/[event]/booth-session/capture-flow.test.ts
@@ -14,11 +14,15 @@ const candidate: ReviewCandidate = {
   canvas,
 };
 
-function capturing(frameKey = "lighthouse"): CaptureFlowState {
+function capturing(
+  frameKey = "lighthouse",
+  captureAttemptId = "attempt-current",
+): CaptureFlowState {
   return {
     ...INITIAL_CAPTURE_FLOW_STATE,
     phase: "capturing",
     frameKey,
+    captureAttemptId,
   };
 }
 
@@ -31,20 +35,26 @@ describe("reduceCaptureFlow", () => {
     expect(ready).toEqual({
       phase: "ready",
       frameKey: "beacon",
+      captureAttemptId: null,
       candidate: null,
       autoAcceptPending: false,
       error: null,
     });
 
-    expect(reduceCaptureFlow(ready, { type: "start-capture" })).toEqual({
+    expect(reduceCaptureFlow(ready, {
+      type: "start-capture",
+      attemptId: "attempt-framed",
+    })).toEqual({
       ...ready,
       phase: "capturing",
+      captureAttemptId: "attempt-framed",
     });
   });
 
   test("capture completion retains the selected Frame and enters timed review", () => {
     const next = reduceCaptureFlow(capturing(), {
       type: "capture-complete",
+      attemptId: "attempt-current",
       candidate,
       reviewEnabled: true,
     });
@@ -52,6 +62,7 @@ describe("reduceCaptureFlow", () => {
     expect(next).toEqual({
       phase: "reviewing",
       frameKey: "lighthouse",
+      captureAttemptId: null,
       candidate,
       autoAcceptPending: true,
       error: null,
@@ -61,6 +72,7 @@ describe("reduceCaptureFlow", () => {
   test("Retake returns to ready with the same Frame", () => {
     const reviewing = reduceCaptureFlow(capturing(), {
       type: "capture-complete",
+      attemptId: "attempt-current",
       candidate,
       reviewEnabled: true,
     });
@@ -71,6 +83,7 @@ describe("reduceCaptureFlow", () => {
     })).toEqual({
       phase: "ready",
       frameKey: "lighthouse",
+      captureAttemptId: null,
       candidate: null,
       autoAcceptPending: false,
       error: null,
@@ -80,6 +93,7 @@ describe("reduceCaptureFlow", () => {
   test("acceptance synchronously enters accepting and disables automatic acceptance", () => {
     const reviewing = reduceCaptureFlow(capturing(), {
       type: "capture-complete",
+      attemptId: "attempt-current",
       candidate,
       reviewEnabled: true,
     });
@@ -98,6 +112,7 @@ describe("reduceCaptureFlow", () => {
     const accepting: CaptureFlowState = {
       phase: "accepting",
       frameKey: "lighthouse",
+      captureAttemptId: null,
       candidate,
       autoAcceptPending: false,
       error: null,
@@ -110,6 +125,7 @@ describe("reduceCaptureFlow", () => {
     })).toEqual({
       phase: "reviewing",
       frameKey: "lighthouse",
+      captureAttemptId: null,
       candidate,
       autoAcceptPending: false,
       error: "Could not save the photo",
@@ -120,6 +136,7 @@ describe("reduceCaptureFlow", () => {
     const accepting: CaptureFlowState = {
       phase: "accepting",
       frameKey: "lighthouse",
+      captureAttemptId: null,
       candidate,
       autoAcceptPending: false,
       error: null,
@@ -131,6 +148,7 @@ describe("reduceCaptureFlow", () => {
     })).toEqual({
       phase: "handoff",
       frameKey: null,
+      captureAttemptId: null,
       candidate: null,
       autoAcceptPending: false,
       error: null,
@@ -141,6 +159,7 @@ describe("reduceCaptureFlow", () => {
     const handoff: CaptureFlowState = {
       phase: "handoff",
       frameKey: null,
+      captureAttemptId: null,
       candidate: null,
       autoAcceptPending: false,
       error: null,
@@ -154,6 +173,7 @@ describe("reduceCaptureFlow", () => {
   test("review-disabled capture moves directly to accepting", () => {
     const next = reduceCaptureFlow(capturing(), {
       type: "capture-complete",
+      attemptId: "attempt-current",
       candidate,
       reviewEnabled: false,
     });
@@ -167,6 +187,7 @@ describe("reduceCaptureFlow", () => {
   test("More Time cancels only the current candidate's timer", () => {
     const reviewing = reduceCaptureFlow(capturing(), {
       type: "capture-complete",
+      attemptId: "attempt-current",
       candidate,
       reviewEnabled: true,
     });
@@ -184,6 +205,7 @@ describe("reduceCaptureFlow", () => {
   test("stale candidate callbacks and actions are identity no-ops", () => {
     const reviewing = reduceCaptureFlow(capturing(), {
       type: "capture-complete",
+      attemptId: "attempt-current",
       candidate,
       reviewEnabled: true,
     });
@@ -212,4 +234,103 @@ describe("reduceCaptureFlow", () => {
       expect(reduceCaptureFlow(accepting, action)).toBe(accepting);
     }
   });
+
+  test("camera fallback completes a legal frameless capture through handoff", () => {
+    const fallbackCandidate: ReviewCandidate = {
+      id: "candidate-fallback",
+      source: "camera-fallback",
+      canvas,
+    };
+    const capturingFallback = reduceCaptureFlow(INITIAL_CAPTURE_FLOW_STATE, {
+      type: "start-fallback-capture",
+      attemptId: "attempt-fallback",
+    });
+    expect(capturingFallback).toEqual({
+      phase: "capturing",
+      frameKey: null,
+      captureAttemptId: "attempt-fallback",
+      candidate: null,
+      autoAcceptPending: false,
+      error: null,
+    });
+
+    const reviewingFallback = reduceCaptureFlow(capturingFallback, {
+      type: "capture-complete",
+      attemptId: "attempt-fallback",
+      candidate: fallbackCandidate,
+      reviewEnabled: true,
+    });
+    expect(reviewingFallback).toEqual({
+      phase: "reviewing",
+      frameKey: null,
+      captureAttemptId: null,
+      candidate: fallbackCandidate,
+      autoAcceptPending: true,
+      error: null,
+    });
+
+    const acceptingFallback = reduceCaptureFlow(reviewingFallback, {
+      type: "accept",
+      candidateId: fallbackCandidate.id,
+    });
+    expect(acceptingFallback.phase).toBe("accepting");
+    expect(reduceCaptureFlow(acceptingFallback, {
+      type: "enqueue-succeeded",
+      candidateId: fallbackCandidate.id,
+    })).toEqual({
+      phase: "handoff",
+      frameKey: null,
+      captureAttemptId: null,
+      candidate: null,
+      autoAcceptPending: false,
+      error: null,
+    });
+  });
+
+  test("an old completion after Retake and a new start cannot install its candidate", () => {
+    const ready = reduceCaptureFlow(INITIAL_CAPTURE_FLOW_STATE, {
+      type: "select-frame",
+      frameKey: "lighthouse",
+    });
+    const firstCapture = reduceCaptureFlow(ready, {
+      type: "start-capture",
+      attemptId: "attempt-first",
+    });
+    const firstReview = reduceCaptureFlow(firstCapture, {
+      type: "capture-complete",
+      attemptId: "attempt-first",
+      candidate,
+      reviewEnabled: true,
+    });
+    const readyAgain = reduceCaptureFlow(firstReview, {
+      type: "retake",
+      candidateId: candidate.id,
+    });
+    const secondCapture = reduceCaptureFlow(readyAgain, {
+      type: "start-capture",
+      attemptId: "attempt-second",
+    });
+    const staleCandidate: ReviewCandidate = {
+      ...candidate,
+      id: "candidate-stale",
+    };
+
+    expect(reduceCaptureFlow(secondCapture, {
+      type: "capture-complete",
+      attemptId: "attempt-first",
+      candidate: staleCandidate,
+      reviewEnabled: true,
+    })).toBe(secondCapture);
+
+    const secondCandidate: ReviewCandidate = {
+      ...candidate,
+      id: "candidate-second",
+    };
+    expect(reduceCaptureFlow(secondCapture, {
+      type: "capture-complete",
+      attemptId: "attempt-second",
+      candidate: secondCandidate,
+      reviewEnabled: true,
+    }).candidate).toBe(secondCandidate);
+  });
 });
diff --git a/app/[event]/booth-session/capture-flow.ts b/app/[event]/booth-session/capture-flow.ts
index 6f29a5a..64a142a 100644
--- a/app/[event]/booth-session/capture-flow.ts
+++ b/app/[event]/booth-session/capture-flow.ts
@@ -16,6 +16,7 @@ export type ReviewCandidate = {
 export type CaptureFlowState = {
   phase: CapturePhase;
   frameKey: string | null;
+  captureAttemptId: string | null;
   candidate: ReviewCandidate | null;
   autoAcceptPending: boolean;
   error: string | null;
@@ -23,9 +24,11 @@ export type CaptureFlowState = {
 
 export type CaptureFlowAction =
   | { type: "select-frame"; frameKey: string }
-  | { type: "start-capture" }
+  | { type: "start-capture"; attemptId: string }
+  | { type: "start-fallback-capture"; attemptId: string }
   | {
       type: "capture-complete";
+      attemptId: string;
       candidate: ReviewCandidate;
       reviewEnabled: boolean;
     }
@@ -39,6 +42,7 @@ export type CaptureFlowAction =
 export const INITIAL_CAPTURE_FLOW_STATE: CaptureFlowState = {
   phase: "picker",
   frameKey: null,
+  captureAttemptId: null,
   candidate: null,
   autoAcceptPending: false,
   error: null,
@@ -54,6 +58,7 @@ export function reduceCaptureFlow(
       return {
         phase: "ready",
         frameKey: action.frameKey,
+        captureAttemptId: null,
         candidate: null,
         autoAcceptPending: false,
         error: null,
@@ -61,13 +66,40 @@ export function reduceCaptureFlow(
 
     case "start-capture":
       if (state.phase !== "ready" || !state.frameKey) return state;
-      return { ...state, phase: "capturing", error: null };
+      return {
+        ...state,
+        phase: "capturing",
+        captureAttemptId: action.attemptId,
+        error: null,
+      };
+
+    case "start-fallback-capture":
+      if (
+        state.phase !== "picker"
+        && !(state.phase === "ready" && state.frameKey === null)
+      ) {
+        return state;
+      }
+      return {
+        phase: "capturing",
+        frameKey: null,
+        captureAttemptId: action.attemptId,
+        candidate: null,
+        autoAcceptPending: false,
+        error: null,
+      };
 
     case "capture-complete":
-      if (state.phase !== "capturing") return state;
+      if (
+        state.phase !== "capturing"
+        || state.captureAttemptId !== action.attemptId
+      ) {
+        return state;
+      }
       return {
         ...state,
         phase: action.reviewEnabled ? "reviewing" : "accepting",
+        captureAttemptId: null,
         candidate: action.candidate,
         autoAcceptPending: action.reviewEnabled,
         error: null,
@@ -87,6 +119,7 @@ export function reduceCaptureFlow(
       return {
         phase: "ready",
         frameKey: state.frameKey,
+        captureAttemptId: null,
         candidate: null,
         autoAcceptPending: false,
         error: null,
@@ -121,6 +154,7 @@ export function reduceCaptureFlow(
       return {
         phase: "handoff",
         frameKey: null,
+        captureAttemptId: null,
         candidate: null,
         autoAcceptPending: false,
         error: null,

From 348b1492bafe57291e8b41e40392d504aedbdf20 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:22:20 +0800
Subject: [PATCH 072/105] feat: review and hand off guest captures

---
 .../booth-session/capture-candidate.test.ts   |  44 ++
 .../booth-session/capture-candidate.ts        |  37 ++
 .../booth-session/capture-flow.test.ts        |  30 +
 app/[event]/booth-session/capture-flow.ts     |  21 +
 .../booth-session/countdown-audio.test.ts     |  94 +++
 app/[event]/booth-session/countdown-audio.ts  |  78 +++
 app/[event]/booth-session/handoff.test.ts     | 122 ++++
 app/[event]/booth-session/handoff.ts          |  54 ++
 app/[event]/booth-session/lifecycle.test.ts   |  39 ++
 app/[event]/booth-session/lifecycle.ts        |  33 +-
 app/[event]/booth-session/session.test.ts     | 127 +++-
 app/[event]/booth-session/session.ts          |  15 +-
 app/[event]/booth.module.css                  | 204 ++++++-
 app/[event]/capture-review.test.tsx           |  54 ++
 app/[event]/capture-review.tsx                | 111 ++++
 app/[event]/handoff-panel.test.tsx            |  73 +++
 app/[event]/handoff-panel.tsx                 | 107 ++++
 app/[event]/page.tsx                          | 564 ++++++++++++++----
 app/i18n/catalog.ts                           |  32 +
 19 files changed, 1709 insertions(+), 130 deletions(-)
 create mode 100644 app/[event]/booth-session/capture-candidate.test.ts
 create mode 100644 app/[event]/booth-session/capture-candidate.ts
 create mode 100644 app/[event]/booth-session/countdown-audio.test.ts
 create mode 100644 app/[event]/booth-session/countdown-audio.ts
 create mode 100644 app/[event]/booth-session/handoff.test.ts
 create mode 100644 app/[event]/booth-session/handoff.ts
 create mode 100644 app/[event]/capture-review.test.tsx
 create mode 100644 app/[event]/capture-review.tsx
 create mode 100644 app/[event]/handoff-panel.test.tsx
 create mode 100644 app/[event]/handoff-panel.tsx

diff --git a/app/[event]/booth-session/capture-candidate.test.ts b/app/[event]/booth-session/capture-candidate.test.ts
new file mode 100644
index 0000000..b8c47a5
--- /dev/null
+++ b/app/[event]/booth-session/capture-candidate.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { decodePhotoFileToCanvas } from "./capture-candidate";
+
+describe("file-camera review candidate", () => {
+  test("decodes into one canvas that can enter the exact review path", async () => {
+    let closed = 0;
+    const bitmap = {
+      width: 640,
+      height: 480,
+      close: () => {
+        closed++;
+      },
+    } as unknown as ImageBitmap;
+    const drawCalls: unknown[][] = [];
+    const canvas = {
+      width: 0,
+      height: 0,
+      getContext: () => ({
+        drawImage: (...args: unknown[]) => drawCalls.push(args),
+      }),
+    } as unknown as HTMLCanvasElement;
+
+    const decoded = await decodePhotoFileToCanvas(
+      new Blob(["camera"]),
+      async () => bitmap,
+      () => canvas,
+    );
+
+    expect(decoded).toBe(canvas);
+    expect([canvas.width, canvas.height]).toEqual([640, 480]);
+    expect(drawCalls).toEqual([[bitmap, 0, 0]]);
+    expect(closed).toBe(1);
+  });
+
+  test("rejects undecodable input instead of passing its bytes to a JPEG Outbox row", async () => {
+    await expect(decodePhotoFileToCanvas(
+      new Blob(["not an image"], { type: "image/heic" }),
+      async () => {
+        throw new DOMException("decode failed", "InvalidStateError");
+      },
+      () => ({}) as HTMLCanvasElement,
+    )).rejects.toThrow("Could not decode this photo");
+  });
+});
diff --git a/app/[event]/booth-session/capture-candidate.ts b/app/[event]/booth-session/capture-candidate.ts
new file mode 100644
index 0000000..69b6bd1
--- /dev/null
+++ b/app/[event]/booth-session/capture-candidate.ts
@@ -0,0 +1,37 @@
+type DecodeImage = (source: Blob) => Promise<ImageBitmap>;
+type CreateCanvas = () => HTMLCanvasElement;
+
+export async function decodePhotoFileToCanvas(
+  file: Blob,
+  decode: DecodeImage = (source) => createImageBitmap(source),
+  createCanvas: CreateCanvas = () => document.createElement("canvas"),
+): Promise<HTMLCanvasElement> {
+  let bitmap: ImageBitmap;
+  try {
+    bitmap = await decode(file);
+  } catch {
+    throw new Error("Could not decode this photo. Please take another one.");
+  }
+
+  try {
+    if (
+      !Number.isFinite(bitmap.width)
+      || !Number.isFinite(bitmap.height)
+      || bitmap.width <= 0
+      || bitmap.height <= 0
+    ) {
+      throw new Error("invalid decoded dimensions");
+    }
+    const canvas = createCanvas();
+    canvas.width = bitmap.width;
+    canvas.height = bitmap.height;
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("canvas unavailable");
+    context.drawImage(bitmap, 0, 0);
+    return canvas;
+  } catch {
+    throw new Error("Could not decode this photo. Please take another one.");
+  } finally {
+    bitmap.close();
+  }
+}
diff --git a/app/[event]/booth-session/capture-flow.test.ts b/app/[event]/booth-session/capture-flow.test.ts
index 0fb3115..e553ffc 100644
--- a/app/[event]/booth-session/capture-flow.test.ts
+++ b/app/[event]/booth-session/capture-flow.test.ts
@@ -27,6 +27,21 @@ function capturing(
 }
 
 describe("reduceCaptureFlow", () => {
+  test("an Event or pause reset releases every candidate and Frame", () => {
+    const reviewing: CaptureFlowState = {
+      phase: "reviewing",
+      frameKey: "lighthouse",
+      captureAttemptId: null,
+      candidate,
+      autoAcceptPending: true,
+      error: null,
+    };
+
+    expect(reduceCaptureFlow(reviewing, { type: "reset" })).toBe(
+      INITIAL_CAPTURE_FLOW_STATE,
+    );
+  });
+
   test("a fresh Frame choice moves from picker through ready to capturing", () => {
     const ready = reduceCaptureFlow(INITIAL_CAPTURE_FLOW_STATE, {
       type: "select-frame",
@@ -69,6 +84,21 @@ describe("reduceCaptureFlow", () => {
     });
   });
 
+  test("capture failure returns to camera-ready with the same Frame", () => {
+    expect(reduceCaptureFlow(capturing(), {
+      type: "capture-failed",
+      attemptId: "attempt-current",
+      error: "Could not compose photo",
+    })).toEqual({
+      phase: "ready",
+      frameKey: "lighthouse",
+      captureAttemptId: null,
+      candidate: null,
+      autoAcceptPending: false,
+      error: "Could not compose photo",
+    });
+  });
+
   test("Retake returns to ready with the same Frame", () => {
     const reviewing = reduceCaptureFlow(capturing(), {
       type: "capture-complete",
diff --git a/app/[event]/booth-session/capture-flow.ts b/app/[event]/booth-session/capture-flow.ts
index 64a142a..cc14397 100644
--- a/app/[event]/booth-session/capture-flow.ts
+++ b/app/[event]/booth-session/capture-flow.ts
@@ -23,9 +23,11 @@ export type CaptureFlowState = {
 };
 
 export type CaptureFlowAction =
+  | { type: "reset" }
   | { type: "select-frame"; frameKey: string }
   | { type: "start-capture"; attemptId: string }
   | { type: "start-fallback-capture"; attemptId: string }
+  | { type: "capture-failed"; attemptId: string; error: string }
   | {
       type: "capture-complete";
       attemptId: string;
@@ -53,6 +55,9 @@ export function reduceCaptureFlow(
   action: CaptureFlowAction
 ): CaptureFlowState {
   switch (action.type) {
+    case "reset":
+      return INITIAL_CAPTURE_FLOW_STATE;
+
     case "select-frame":
       if (state.phase !== "picker") return state;
       return {
@@ -89,6 +94,22 @@ export function reduceCaptureFlow(
         error: null,
       };
 
+    case "capture-failed":
+      if (
+        state.phase !== "capturing"
+        || state.captureAttemptId !== action.attemptId
+      ) {
+        return state;
+      }
+      return {
+        phase: "ready",
+        frameKey: state.frameKey,
+        captureAttemptId: null,
+        candidate: null,
+        autoAcceptPending: false,
+        error: action.error,
+      };
+
     case "capture-complete":
       if (
         state.phase !== "capturing"
diff --git a/app/[event]/booth-session/countdown-audio.test.ts b/app/[event]/booth-session/countdown-audio.test.ts
new file mode 100644
index 0000000..ecf3d49
--- /dev/null
+++ b/app/[event]/booth-session/countdown-audio.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { CountdownToneController } from "./countdown-audio";
+
+function audioHarness() {
+  const starts: number[] = [];
+  const frequencies: number[] = [];
+  let resumes = 0;
+  let closes = 0;
+  const context = {
+    state: "suspended",
+    currentTime: 10,
+    destination: {},
+    resume: async () => {
+      resumes++;
+      context.state = "running";
+    },
+    close: async () => {
+      closes++;
+      context.state = "closed";
+    },
+    createGain: () => ({
+      gain: {
+        setValueAtTime: () => {},
+        exponentialRampToValueAtTime: () => {},
+      },
+      connect: () => {},
+    }),
+    createOscillator: () => ({
+      frequency: {
+        setValueAtTime: (frequency: number) => frequencies.push(frequency),
+      },
+      connect: () => {},
+      start: (at: number) => starts.push(at),
+      stop: () => {},
+    }),
+  };
+  return { context, starts, frequencies, resumes: () => resumes, closes: () => closes };
+}
+
+describe("CountdownToneController", () => {
+  test("does nothing until activation is explicitly requested by a caller gesture", () => {
+    const harness = audioHarness();
+    const tones = new CountdownToneController(() => harness.context as unknown as AudioContext);
+
+    tones.tick(3);
+    tones.captured();
+
+    expect(harness.starts).toEqual([]);
+    expect(harness.resumes()).toBe(0);
+  });
+
+  test("activation resumes audio and enables bounded countdown and capture tones", async () => {
+    const harness = audioHarness();
+    const tones = new CountdownToneController(() => harness.context as unknown as AudioContext);
+
+    expect(await tones.activate()).toBe(true);
+    tones.tick(Number.NaN);
+    tones.tick(0);
+    tones.tick(4);
+    tones.tick(3);
+    tones.captured();
+
+    expect(harness.resumes()).toBe(1);
+    expect(harness.starts).toHaveLength(2);
+    expect(harness.frequencies.every((frequency) => frequency >= 200 && frequency <= 2_000)).toBe(true);
+  });
+
+  test("unsupported or denied audio degrades silently", async () => {
+    const unsupported = new CountdownToneController(() => null);
+    const denied = new CountdownToneController(() => {
+      throw new DOMException("denied", "NotAllowedError");
+    });
+
+    await expect(unsupported.activate()).resolves.toBe(false);
+    await expect(denied.activate()).resolves.toBe(false);
+    expect(() => {
+      unsupported.tick(3);
+      denied.captured();
+    }).not.toThrow();
+  });
+
+  test("dispose closes the context and permanently releases it", async () => {
+    const harness = audioHarness();
+    const tones = new CountdownToneController(() => harness.context as unknown as AudioContext);
+    await tones.activate();
+
+    await tones.dispose();
+    tones.tick(2);
+
+    expect(harness.closes()).toBe(1);
+    expect(harness.starts).toEqual([]);
+    await expect(tones.activate()).resolves.toBe(false);
+  });
+});
diff --git a/app/[event]/booth-session/countdown-audio.ts b/app/[event]/booth-session/countdown-audio.ts
new file mode 100644
index 0000000..6526a17
--- /dev/null
+++ b/app/[event]/booth-session/countdown-audio.ts
@@ -0,0 +1,78 @@
+type AudioContextFactory = () => AudioContext | null;
+
+function defaultAudioContextFactory(): AudioContext | null {
+  if (typeof window === "undefined") return null;
+  const AudioContextConstructor =
+    window.AudioContext
+    ?? (window as typeof window & { webkitAudioContext?: typeof AudioContext })
+      .webkitAudioContext;
+  return AudioContextConstructor ? new AudioContextConstructor() : null;
+}
+
+export class CountdownToneController {
+  private context: AudioContext | null = null;
+  private active = false;
+  private disposed = false;
+
+  constructor(
+    private readonly createContext: AudioContextFactory = defaultAudioContextFactory,
+  ) {}
+
+  async activate(): Promise<boolean> {
+    if (this.disposed) return false;
+    try {
+      this.context ??= this.createContext();
+      if (!this.context) return false;
+      if (this.context.state === "suspended") await this.context.resume();
+      this.active = this.context.state === "running";
+      return this.active;
+    } catch {
+      this.active = false;
+      this.context = null;
+      return false;
+    }
+  }
+
+  tick(count: number): void {
+    if (!Number.isInteger(count) || count < 1 || count > 3) return;
+    this.play(520 + (3 - count) * 90, 0.08);
+  }
+
+  captured(): void {
+    this.play(1_040, 0.13);
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.active = false;
+    const context = this.context;
+    this.context = null;
+    if (!context || context.state === "closed") return;
+    try {
+      await context.close();
+    } catch {
+      // Optional feedback must never interfere with capture cleanup.
+    }
+  }
+
+  private play(frequency: number, duration: number): void {
+    const context = this.context;
+    if (!this.active || !context || context.state !== "running") return;
+    try {
+      const oscillator = context.createOscillator();
+      const gain = context.createGain();
+      const start = context.currentTime;
+      oscillator.frequency.setValueAtTime(frequency, start);
+      gain.gain.setValueAtTime(0.0001, start);
+      gain.gain.exponentialRampToValueAtTime(0.11, start + 0.01);
+      gain.gain.exponentialRampToValueAtTime(0.0001, start + duration);
+      oscillator.connect(gain);
+      gain.connect(context.destination);
+      oscillator.start(start);
+      oscillator.stop(start + duration + 0.01);
+    } catch {
+      // Audio is progressive enhancement; visual countdown remains authoritative.
+    }
+  }
+}
diff --git a/app/[event]/booth-session/handoff.test.ts b/app/[event]/booth-session/handoff.test.ts
new file mode 100644
index 0000000..eb58645
--- /dev/null
+++ b/app/[event]/booth-session/handoff.test.ts
@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import type { OutboxItem } from "./outbox";
+import type { UploadAcknowledgement } from "./session";
+import {
+  applyAcknowledgement,
+  beginHandoff,
+  buildPhotoHandoffUrl,
+} from "./handoff";
+
+function item(id: string): OutboxItem {
+  return {
+    id,
+    event: "summer-party",
+    blob: new Blob(["photo"], { type: "image/jpeg" }),
+    createdAt: 1,
+    attempts: 0,
+  };
+}
+
+function acknowledgement(
+  id: string,
+  key: string | undefined = `summer-party/${id}.jpg`,
+): UploadAcknowledgement {
+  return {
+    item: item(id),
+    result: {
+      url: `https://photos.example/${id}.jpg`,
+      ...(key === undefined ? {} : { key }),
+    },
+  };
+}
+
+describe("current photo handoff", () => {
+  test("begins waiting for the exact durable Outbox identity", () => {
+    expect(beginHandoff(item("current"))).toEqual({
+      captureId: "current",
+      status: "waiting",
+    });
+  });
+
+  test("only the exact current identity can become ready", () => {
+    const waiting = beginHandoff(item("current"));
+
+    expect(applyAcknowledgement(
+      waiting,
+      acknowledgement("older"),
+      "https://booth.example",
+    )).toBe(waiting);
+    expect(applyAcknowledgement(
+      waiting,
+      acknowledgement("current"),
+      "https://booth.example",
+    )).toEqual({
+      captureId: "current",
+      status: "ready",
+      key: "summer-party/current.jpg",
+      photoUrl: "https://photos.example/current.jpg",
+      galleryUrl:
+        "https://booth.example/summer-party/gallery?photo=summer-party%2Fcurrent.jpg",
+    });
+  });
+
+  test("duplicate acknowledgement succeeds but a missing legacy key cannot make an exact QR", () => {
+    const waiting = beginHandoff(item("current"));
+    const duplicate = acknowledgement("current");
+    duplicate.result.duplicate = true;
+
+    expect(applyAcknowledgement(waiting, duplicate, "https://booth.example")?.status).toBe("ready");
+    const legacy = acknowledgement("current");
+    delete legacy.result.key;
+    expect(applyAcknowledgement(
+      waiting,
+      legacy,
+      "https://booth.example",
+    )).toBe(waiting);
+  });
+
+  test("a replacement or dismissed handoff cannot be reopened by a late acknowledgement", () => {
+    const newer = beginHandoff(item("newer"));
+
+    expect(applyAcknowledgement(
+      newer,
+      acknowledgement("older"),
+      "https://booth.example",
+    )).toBe(newer);
+    expect(applyAcknowledgement(
+      null,
+      acknowledgement("newer"),
+      "https://booth.example",
+    )).toBeNull();
+  });
+
+  test("a cross-Event or non-photo acknowledgement cannot create a handoff", () => {
+    const waiting = beginHandoff(item("current"));
+
+    expect(applyAcknowledgement(
+      waiting,
+      acknowledgement("current", "other-event/current.jpg"),
+      "https://booth.example",
+    )).toBe(waiting);
+    expect(applyAcknowledgement(
+      waiting,
+      acknowledgement("current", "summer-party/folder/current.jpg"),
+      "https://booth.example",
+    )).toBe(waiting);
+  });
+
+  test("encodes the complete key as one photo query value", () => {
+    const url = buildPhotoHandoffUrl(
+      "https://booth.example/base",
+      "summer-party",
+      "summer-party/folder/photo #1.jpg",
+    );
+
+    expect(url).toBe(
+      "https://booth.example/summer-party/gallery?photo=summer-party%2Ffolder%2Fphoto+%231.jpg",
+    );
+    expect(new URL(url).searchParams.getAll("photo")).toEqual([
+      "summer-party/folder/photo #1.jpg",
+    ]);
+  });
+});
diff --git a/app/[event]/booth-session/handoff.ts b/app/[event]/booth-session/handoff.ts
new file mode 100644
index 0000000..a7dd668
--- /dev/null
+++ b/app/[event]/booth-session/handoff.ts
@@ -0,0 +1,54 @@
+import type { OutboxItem } from "./outbox";
+import type { UploadAcknowledgement } from "./session";
+
+export type CurrentHandoff =
+  | { captureId: string; status: "waiting" }
+  | {
+      captureId: string;
+      status: "ready";
+      key: string;
+      photoUrl: string;
+      galleryUrl: string;
+    };
+
+export function beginHandoff(item: OutboxItem): CurrentHandoff {
+  return { captureId: item.id, status: "waiting" };
+}
+
+export function applyAcknowledgement(
+  current: CurrentHandoff | null,
+  acknowledgement: UploadAcknowledgement,
+  origin: string,
+): CurrentHandoff | null {
+  if (!current || current.captureId !== acknowledgement.item.id) return current;
+  const key = acknowledgement.result.key;
+  if (!key || !isEventPhotoKey(acknowledgement.item.event, key)) return current;
+  return {
+    captureId: current.captureId,
+    status: "ready",
+    key,
+    photoUrl: acknowledgement.result.url,
+    galleryUrl: buildPhotoHandoffUrl(
+      origin,
+      acknowledgement.item.event,
+      key,
+    ),
+  };
+}
+
+function isEventPhotoKey(event: string, key: string): boolean {
+  const prefix = `${event}/`;
+  if (!key.startsWith(prefix)) return false;
+  const filename = key.slice(prefix.length);
+  return /^[^/\\?#]+\.(?:jpe?g|png|gif|webp|hei[cf]|avif)$/i.test(filename);
+}
+
+export function buildPhotoHandoffUrl(
+  origin: string,
+  event: string,
+  completeKey: string,
+): string {
+  const url = new URL(`/${encodeURIComponent(event)}/gallery`, origin);
+  url.searchParams.set("photo", completeKey);
+  return url.toString();
+}
diff --git a/app/[event]/booth-session/lifecycle.test.ts b/app/[event]/booth-session/lifecycle.test.ts
index e1f84d4..a679adf 100644
--- a/app/[event]/booth-session/lifecycle.test.ts
+++ b/app/[event]/booth-session/lifecycle.test.ts
@@ -126,6 +126,44 @@ function activeCandidate(
 const photo = (name: string) => new Blob([name], { type: "image/jpeg" });
 
 describe("Booth lifecycle coordination", () => {
+  test("preflight preserves the validated capture and locale experience for the Booth", () => {
+    const operationalState = parseBoothOperationalState({
+      paused: false,
+      messages: {},
+      version: 1,
+      updatedAt: "2026-07-24T00:00:00.000Z",
+    });
+    const result = boothPreflightResultFromPayload({
+      experience: {
+        frames: ["square"],
+        locales: ["en", "zh-SG"],
+        defaultLocale: "zh-SG",
+        capture: {
+          reviewEnabled: false,
+          autoAcceptSeconds: 8,
+          countdownAudioDefault: true,
+        },
+      },
+      operationalState,
+    });
+
+    expect(result).toEqual({
+      kind: "ready",
+      frames: ["square"],
+      experience: {
+        frames: ["square"],
+        locales: ["en", "zh-SG"],
+        defaultLocale: "zh-SG",
+        capture: {
+          reviewEnabled: false,
+          autoAcceptSeconds: 8,
+          countdownAudioDefault: true,
+        },
+      },
+      operationalState,
+    });
+  });
+
   test("completes Outbox recovery before reading a stored credential or preflighting", async () => {
     const recovery = deferred<void>();
     const calls: string[] = [];
@@ -514,6 +552,7 @@ describe("preflight operational-state validation", () => {
     })).toEqual({
       kind: "ready",
       frames: ["square"],
+      experience: { frames: ["square"] },
       operationalState: validState,
     });
   });
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
index 03eff96..5605c43 100644
--- a/app/[event]/booth-session/lifecycle.ts
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -1,5 +1,10 @@
 import { availableTemplates } from "../../templates";
 import { parseBoothOperationalState } from "../../booth-control";
+import {
+  parseEventConfig,
+  projectEventExperience,
+  type EventExperience,
+} from "../../event-config";
 import type { BoothAccessState } from "./access";
 
 export type BoothAccessFeedback =
@@ -12,7 +17,12 @@ export type BoothAccessFeedback =
   | "ready";
 
 export type BoothPreflightResult =
-  | { kind: "ready"; frames: unknown; operationalState?: unknown }
+  | {
+      kind: "ready";
+      frames: unknown;
+      experience?: EventExperience;
+      operationalState?: unknown;
+    }
   | { kind: "unauthorized" }
   | { kind: "unavailable" }
   | { kind: "recovery-only" };
@@ -54,6 +64,7 @@ type BoothLifecycleDependencies<Result> = {
   onOutboxRecovered: () => void;
   onAccess: (state: BoothAccessState, feedback: BoothAccessFeedback) => void;
   onFrames: (frames: string[] | null) => void;
+  onExperience?: (experience: EventExperience | null) => void;
   onOperationalState: (state: unknown) => void;
   onCameraStart: () => void;
   onCameraStop: () => void;
@@ -79,10 +90,19 @@ export function boothPreflightResultFromPayload(value: unknown): BoothPreflightR
   const operationalState = parseBoothOperationalState(payload.operationalState);
   if (!operationalState) return { kind: "recovery-only" };
   const experience = payload.experience;
-  const frames = experience && typeof experience === "object" && !Array.isArray(experience)
-    ? (experience as { frames?: unknown }).frames
-    : undefined;
-  return { kind: "ready", frames, operationalState };
+  const config = parseEventConfig(
+    experience && typeof experience === "object" && !Array.isArray(experience)
+      ? { ...experience, version: 1 }
+      : null,
+  );
+  if (!config) return { kind: "recovery-only" };
+  const validatedExperience = projectEventExperience(config);
+  return {
+    kind: "ready",
+    frames: validatedExperience.frames,
+    experience: validatedExperience,
+    operationalState,
+  };
 }
 
 export class BoothLifecycleCoordinator<Result> {
@@ -123,6 +143,7 @@ export class BoothLifecycleCoordinator<Result> {
     this.active = active;
     this.deps.onReset(event);
     this.deps.onFrames(null);
+    this.deps.onExperience?.(null);
     this.deps.onAccess("locked", "recovering");
 
     let recovery: BoothSessionRecovery;
@@ -206,6 +227,7 @@ export class BoothLifecycleCoordinator<Result> {
     active.credential.key = "";
     this.deps.clearCredential(active.event);
     this.deps.onFrames(null);
+    this.deps.onExperience?.(null);
     this.deps.onCameraStop();
     this.deps.onAccess("locked", "rejected-key");
     return this.ensureStopped(active);
@@ -260,6 +282,7 @@ export class BoothLifecycleCoordinator<Result> {
       this.deps.onOperationalState(result.operationalState);
     }
     this.deps.onFrames(frames);
+    this.deps.onExperience?.(result.experience ?? { frames });
     this.deps.onAccess("ready", "ready");
     let startWork: Promise<void> | void;
     try {
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index 4fc9dca..e9512f5 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { createOutboxStore, MemoryOutboxStore, type OutboxItem } from "./outbox";
-import { BoothSession, runCaptureSequence, type UploadState } from "./session";
+import {
+  BoothSession,
+  runCaptureSequence,
+  type UploadAcknowledgement,
+  type UploadState,
+} from "./session";
 import { outboxUploadHeaders } from "./upload";
 import { HttpUploadError } from "./retry-policy";
 
@@ -112,6 +117,124 @@ function versionOneIndexedDb(rows: OutboxItem[]) {
 }
 
 describe("BoothSession outbox", () => {
+  test("acknowledges the exact stored item and response only after exact-row removal", async () => {
+    const itemWasRemoved: boolean[] = [];
+    const acknowledgements: UploadAcknowledgement[] = [];
+    class ObservedStore extends MemoryOutboxStore {
+      override async remove(id: string) {
+        await super.remove(id);
+        itemWasRemoved.push((await this.list("party")).every((item) => item.id !== id));
+      }
+    }
+    const store = new ObservedStore();
+    const result = {
+      url: "https://photos.example/current.jpg",
+      key: "party/current.jpg",
+      duplicate: true,
+    };
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => result,
+      (acknowledgement) => acknowledgements.push(acknowledgement),
+      () => "current",
+      () => 1,
+    );
+    const queued = await session.enqueueCapture(async () => photo("current"), {
+      metadata: { source: "framed", frameKey: "square" },
+    });
+
+    await session.process();
+
+    expect(itemWasRemoved).toEqual([true]);
+    expect(acknowledgements).toEqual([{ item: queued, result }]);
+  });
+
+  test("does not acknowledge when exact-row removal fails", async () => {
+    class RemoveFailureStore extends MemoryOutboxStore {
+      override async remove() {
+        throw new Error("cleanup failed");
+      }
+    }
+    const acknowledgements: UploadAcknowledgement[] = [];
+    const session = new BoothSession(
+      "party",
+      new RemoveFailureStore(),
+      async () => ({ url: "/photo", key: "party/current.jpg" }),
+      (acknowledgement) => acknowledgements.push(acknowledgement),
+    );
+    await session.enqueueCapture(async () => photo("current"), {
+      metadata: { source: "camera-fallback" },
+    });
+
+    await session.process();
+
+    expect(acknowledgements).toEqual([]);
+  });
+
+  test("lets the caller establish current handoff after enqueue before upload processing", async () => {
+    let handoffCaptureId: string | null = null;
+    const seenDuringAcknowledgement: Array<string | null> = [];
+    const session = new BoothSession(
+      "party",
+      new MemoryOutboxStore(),
+      async () => ({
+        url: "https://photos.example/current.jpg",
+        key: "party/current.jpg",
+      }),
+      ({ item }) => {
+        seenDuringAcknowledgement.push(handoffCaptureId);
+        expect(item.id).toBe(handoffCaptureId ?? "handoff-not-established");
+      },
+      () => "current",
+      () => 1,
+    );
+    await session.start();
+
+    const queued = await session.enqueueCapture(async () => photo("current"), {
+      metadata: { source: "framed", frameKey: "square" },
+    });
+    handoffCaptureId = queued.id;
+    await session.process();
+
+    expect(seenDuringAcknowledgement).toEqual(["current"]);
+    await session.stop();
+  });
+
+  test("durable enqueue does not depend on a second fallible Outbox list", async () => {
+    class PostPutListFailureStore extends MemoryOutboxStore {
+      failNextList = false;
+
+      override async put(item: OutboxItem) {
+        await super.put(item);
+        this.failNextList = true;
+      }
+
+      override async list(event: string) {
+        if (this.failNextList) {
+          this.failNextList = false;
+          throw new Error("post-put list failed");
+        }
+        return super.list(event);
+      }
+    }
+    const store = new PostPutListFailureStore();
+    const session = new BoothSession(
+      "party",
+      store,
+      async () => ({ url: "/photo" }),
+      () => {},
+      () => "current",
+      () => 1,
+    );
+
+    await expect(session.enqueueCapture(async () => photo("current"), {
+      metadata: { source: "camera-fallback" },
+    })).resolves.toMatchObject({ id: "current" });
+    await expect(store.list("party")).rejects.toThrow("post-put list failed");
+    expect((await store.list("party")).map((item) => item.id)).toEqual(["current"]);
+  });
+
   test("reserves strictly increasing FIFO order across concurrent durable puts", async () => {
     let releasePuts!: () => void;
     const putBarrier = new Promise<void>((resolve) => {
@@ -204,7 +327,7 @@ describe("BoothSession outbox", () => {
       attempted.push(await text(item.blob));
       uploadIdentities.push({ id: item.id, headers: outboxUploadHeaders(item) });
       return { url: `/photos/${await text(item.blob)}` };
-    }, ({ url }) => recoveredUrls.push(url));
+    }, ({ result: { url } }) => recoveredUrls.push(url));
     const states: string[] = [];
     recovered.subscribe((state) => states.push(`${state.status}:${state.pendingCount}:${state.error ?? ""}`));
     await recovered.recover();
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index 9787592..10b5c3e 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -11,6 +11,13 @@ export type UploadState = {
 
 export type UploadResult = { url: string; key?: string; duplicate?: boolean };
 export type Upload = (item: OutboxItem) => Promise<UploadResult>;
+export type UploadAcknowledgement = {
+  item: OutboxItem;
+  result: UploadResult;
+};
+export type OnAcknowledged = (
+  acknowledgement: UploadAcknowledgement,
+) => void;
 
 export type EnqueueCaptureOptions = {
   signal?: AbortSignal;
@@ -54,7 +61,7 @@ export class BoothSession {
     private readonly event: string,
     private readonly store: OutboxStore,
     private readonly upload: Upload,
-    private readonly onUploaded: (result: UploadResult) => void = () => {},
+    private readonly onAcknowledged: OnAcknowledged = () => {},
     private readonly makeId: () => string = () => crypto.randomUUID(),
     private readonly now: () => number = Date.now,
     options: BoothSessionOptions = {}
@@ -159,14 +166,12 @@ export class BoothSession {
       ...(options.rehearsalId === undefined ? {} : { rehearsalId: options.rehearsalId }),
     };
     await this.store.put(item);
-    const pending = await this.store.list(this.event);
     this.publish({
       status: this.state.status === "failed" ? "failed" : "idle",
-      pendingCount: pending.length,
+      pendingCount: this.state.pendingCount + 1,
       error: this.state.status === "failed" ? this.state.error : null,
       durable: this.store.isDurable(),
     });
-    if (this.started && !this.stopRequested) void this.process();
     return item;
   }
 
@@ -294,7 +299,7 @@ export class BoothSession {
       // item was removed. Post-ack failures may pause reconciliation, but can
       // never enter the retry path and recreate that item.
       try {
-        this.onUploaded(result);
+        this.onAcknowledged({ item, result });
       } catch {
         // The next state publication still reconciles the Booth UI.
       }
diff --git a/app/[event]/booth.module.css b/app/[event]/booth.module.css
index fb43b0b..2569a7f 100644
--- a/app/[event]/booth.module.css
+++ b/app/[event]/booth.module.css
@@ -74,6 +74,24 @@
   font-weight: 800;
 }
 
+.localePicker {
+  display: inline-flex;
+  min-height: 44px;
+  align-items: center;
+  gap: 10px;
+  font-weight: 700;
+}
+
+.localePicker select {
+  min-height: 44px;
+  padding: 0 38px 0 12px;
+  border: 2px solid rgba(255, 255, 255, 0.55);
+  border-radius: 10px;
+  background: #111119;
+  color: #fff;
+  font: inherit;
+}
+
 .choices {
   display: flex;
   gap: 20px;
@@ -102,7 +120,13 @@
 .shutter:focus-visible,
 .change:focus-visible,
 .liveLink:focus-visible,
-.fileBtn:focus-within {
+.fileBtn:focus-within,
+.localePicker select:focus-visible,
+.reviewActions button:focus-visible,
+.handoffLink:focus-visible,
+.handoffContinue:focus-visible,
+.error:focus-visible,
+.handoffPanel h1:focus-visible {
   outline: 3px solid #fff;
   outline-offset: 4px;
 }
@@ -240,6 +264,7 @@
   font-weight: 700;
   cursor: pointer;
   z-index: 5;
+  min-height: 44px;
 }
 .retry:disabled {
   cursor: default;
@@ -256,6 +281,143 @@
   border-radius: 12px;
   font-size: 15px;
   max-width: 80vw;
+  min-height: 44px;
+  border: 2px solid rgba(255, 255, 255, 0.8);
+  color: #fff;
+  cursor: pointer;
+  z-index: 8;
+}
+
+.review,
+.handoff {
+  position: absolute;
+  inset: 0;
+  z-index: 10;
+  display: grid;
+  place-items: center;
+  overflow: auto;
+  padding:
+    max(24px, env(safe-area-inset-top, 0px))
+    max(24px, env(safe-area-inset-right, 0px))
+    max(24px, env(safe-area-inset-bottom, 0px))
+    max(24px, env(safe-area-inset-left, 0px));
+  background: rgba(5, 5, 10, 0.92);
+  color: #fff;
+}
+
+.review {
+  grid-template-rows: minmax(0, 1fr) auto auto;
+  gap: 20px;
+}
+
+.reviewPreview {
+  display: grid;
+  width: 100%;
+  min-height: 0;
+  place-items: center;
+  overflow: hidden;
+}
+
+.reviewCanvas {
+  display: block;
+  max-width: 100%;
+  max-height: min(68dvh, 760px);
+  width: auto;
+  height: auto;
+  border-radius: 14px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.55);
+}
+
+.reviewActions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 12px;
+}
+
+.reviewActions button,
+.handoffContinue,
+.handoffLink {
+  display: inline-flex;
+  min-width: 132px;
+  min-height: 52px;
+  align-items: center;
+  justify-content: center;
+  padding: 12px 20px;
+  border: 2px solid rgba(255, 255, 255, 0.55);
+  border-radius: 14px;
+  background: #242431;
+  color: #fff;
+  font: 800 17px/1.2 system-ui, sans-serif;
+  text-align: center;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.reviewActions .reviewPrimary,
+.handoffContinue {
+  border-color: #ff65aa;
+  background: #ff2d8b;
+}
+
+.reviewActions button:disabled {
+  cursor: wait;
+  opacity: 0.5;
+}
+
+.reviewAnnouncement {
+  min-height: 44px;
+  max-width: 680px;
+  text-align: center;
+}
+
+.reviewAnnouncement p {
+  margin: 0;
+  padding: 10px;
+}
+
+.reviewAnnouncement [role="alert"] {
+  border-radius: 10px;
+  background: #a7192f;
+}
+
+.handoffPanel {
+  display: flex;
+  width: min(560px, 100%);
+  flex-direction: column;
+  align-items: center;
+  gap: 18px;
+  padding: clamp(26px, 5vw, 48px);
+  border: 1px solid #535263;
+  border-radius: 28px;
+  background: #111119;
+  text-align: center;
+  box-shadow: 0 26px 80px rgba(0, 0, 0, 0.5);
+}
+
+.handoffPanel h1 {
+  margin: 0;
+  border-radius: 8px;
+  font: 850 clamp(34px, 6vw, 54px)/1 ui-rounded, system-ui, sans-serif;
+}
+
+.handoffPanel p {
+  margin: 0;
+  color: #d1cfda;
+  font-size: 18px;
+  line-height: 1.45;
+}
+
+.handoffQr {
+  width: min(320px, 72vw);
+  height: auto;
+  border: 10px solid #fff;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.handoffLink {
+  overflow-wrap: anywhere;
 }
 
 .storageWarning {
@@ -269,7 +431,19 @@
   color: #fff;
   font-size: 13px;
   font-weight: 650;
-  z-index: 6;
+  z-index: 12;
+}
+
+.uploadError {
+  position: absolute;
+  left: 16px;
+  bottom: calc(16px + env(safe-area-inset-bottom, 0px));
+  z-index: 12;
+  max-width: min(420px, 75vw);
+  padding: 10px 14px;
+  border-radius: 12px;
+  background: #a7192f;
+  color: #fff;
 }
 
 /* Public operational state is deliberately simple: paused/disconnected only.
@@ -784,6 +958,14 @@
   .unlockRetry {
     width: 100%;
   }
+
+  .reviewActions {
+    width: 100%;
+  }
+
+  .reviewActions button {
+    flex: 1 1 140px;
+  }
 }
 
 @media (forced-colors: active) {
@@ -794,7 +976,15 @@
   .connectivity,
   .readinessRail,
   .readinessRail > div,
-  .unlockForm > input {
+  .unlockForm > input,
+  .review,
+  .handoff,
+  .handoffPanel,
+  .reviewActions button,
+  .handoffContinue,
+  .handoffLink,
+  .localePicker select,
+  .error {
     border-color: CanvasText;
     background: Canvas;
     color: CanvasText;
@@ -811,7 +1001,13 @@
   .shutter:focus-visible,
   .change:focus-visible,
   .liveLink:focus-visible,
-  .remember:focus-within {
+  .remember:focus-within,
+  .reviewActions button:focus-visible,
+  .handoffLink:focus-visible,
+  .handoffContinue:focus-visible,
+  .localePicker select:focus-visible,
+  .error:focus-visible,
+  .handoffPanel h1:focus-visible {
     outline: 3px solid Highlight;
     outline-offset: 4px;
   }
diff --git a/app/[event]/capture-review.test.tsx b/app/[event]/capture-review.test.tsx
new file mode 100644
index 0000000..ee8377c
--- /dev/null
+++ b/app/[event]/capture-review.test.tsx
@@ -0,0 +1,54 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { CaptureReview } from "./capture-review";
+
+const labels = {
+  usePhoto: "保留照片",
+  retake: "重新拍摄",
+  moreTime: "延长时间",
+  accepting: "正在安全保存…",
+  preview: "准确的照片预览",
+};
+
+function render(accepting: boolean, error: string | null = null) {
+  return renderToStaticMarkup(
+    <CaptureReview
+      canvas={{ width: 1200, height: 1800 } as HTMLCanvasElement}
+      autoAcceptSeconds={5}
+      accepting={accepting}
+      error={error}
+      labels={labels}
+      onAccept={() => {}}
+      onRetake={() => {}}
+      onMoreTime={() => {}}
+    />,
+  );
+}
+
+test("labels the exact-canvas preview and defaults focus to localized Use Photo", () => {
+  const html = render(false);
+
+  expect(html).toContain('role="img"');
+  expect(html).toContain('aria-label="准确的照片预览"');
+  expect(html).toContain("保留照片");
+  expect(html).toContain("重新拍摄");
+  expect(html).toContain("延长时间");
+  expect(html).toContain('autofocus=""');
+  expect(html).toContain('aria-live="polite"');
+});
+
+test("accepting disables every decision and announces localized progress", () => {
+  const html = render(true);
+
+  expect(html.match(/disabled=""/g)?.length).toBe(3);
+  expect(html).toContain('role="status"');
+  expect(html).toContain("正在安全保存…");
+});
+
+test("an acceptance error is exposed as an accessible alert without replacing the preview", () => {
+  const html = render(false, "无法保存这张照片");
+
+  expect(html).toContain('role="alert"');
+  expect(html).toContain("无法保存这张照片");
+  expect(html).toContain('aria-label="准确的照片预览"');
+});
diff --git a/app/[event]/capture-review.tsx b/app/[event]/capture-review.tsx
new file mode 100644
index 0000000..d65f6dc
--- /dev/null
+++ b/app/[event]/capture-review.tsx
@@ -0,0 +1,111 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import styles from "./booth.module.css";
+
+export type CaptureReviewProps = {
+  canvas: HTMLCanvasElement;
+  autoAcceptSeconds: number;
+  accepting: boolean;
+  error: string | null;
+  labels: {
+    usePhoto: string;
+    retake: string;
+    moreTime: string;
+    accepting: string;
+    preview: string;
+  };
+  onAccept(): void;
+  onRetake(): void;
+  onMoreTime(): void;
+};
+
+export function CaptureReview({
+  canvas,
+  autoAcceptSeconds,
+  accepting,
+  error,
+  labels,
+  onAccept,
+  onRetake,
+  onMoreTime,
+}: CaptureReviewProps) {
+  const previewRef = useRef<HTMLDivElement>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const acceptRef = useRef(onAccept);
+  acceptRef.current = onAccept;
+
+  useEffect(() => {
+    const preview = previewRef.current;
+    if (!preview) return;
+    canvas.setAttribute("aria-hidden", "true");
+    canvas.classList.add(styles.reviewCanvas);
+    preview.replaceChildren(canvas);
+    return () => {
+      if (canvas.parentNode === preview) preview.removeChild(canvas);
+    };
+  }, [canvas]);
+
+  useEffect(() => {
+    if (accepting || error || autoAcceptSeconds <= 0) return;
+    timerRef.current = setTimeout(() => acceptRef.current(), autoAcceptSeconds * 1_000);
+    return () => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+      timerRef.current = null;
+    };
+  }, [accepting, autoAcceptSeconds, canvas, error]);
+
+  const cancelTimer = () => {
+    if (timerRef.current !== null) clearTimeout(timerRef.current);
+    timerRef.current = null;
+  };
+
+  return (
+    <section className={styles.review} aria-label={labels.preview}>
+      <div
+        ref={previewRef}
+        className={styles.reviewPreview}
+        role="img"
+        aria-label={labels.preview}
+      />
+      <div className={styles.reviewActions}>
+        <button
+          className={styles.reviewPrimary}
+          type="button"
+          autoFocus
+          disabled={accepting}
+          onClick={() => {
+            cancelTimer();
+            onAccept();
+          }}
+        >
+          {labels.usePhoto}
+        </button>
+        <button
+          type="button"
+          disabled={accepting}
+          onClick={() => {
+            cancelTimer();
+            onRetake();
+          }}
+        >
+          {labels.retake}
+        </button>
+        <button
+          type="button"
+          disabled={accepting}
+          onClick={() => {
+            cancelTimer();
+            onMoreTime();
+          }}
+        >
+          {labels.moreTime}
+        </button>
+      </div>
+      <div className={styles.reviewAnnouncement} aria-live="polite">
+        {accepting && <p role="status">{labels.accepting}</p>}
+        {error && <p role="alert">{error}</p>}
+      </div>
+    </section>
+  );
+}
diff --git a/app/[event]/handoff-panel.test.tsx b/app/[event]/handoff-panel.test.tsx
new file mode 100644
index 0000000..5c4a661
--- /dev/null
+++ b/app/[event]/handoff-panel.test.tsx
@@ -0,0 +1,73 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { HandoffPanel, isCurrentQrImage } from "./handoff-panel";
+
+const labels = {
+  queued: "Safely queued",
+  title: "Your exact photo",
+  body: "Scan this code",
+  viewPhoto: "Open exact photo",
+  continue: "Continue",
+};
+
+test("waiting handoff announces durable queueing and always offers Continue", () => {
+  const html = renderToStaticMarkup(
+    <HandoffPanel
+      handoff={{ captureId: "current", status: "waiting" }}
+      labels={labels}
+      onContinue={() => {}}
+    />,
+  );
+
+  expect(html).toContain('role="status"');
+  expect(html).toContain("Safely queued");
+  expect(html).toContain("Continue");
+  expect(html).not.toContain("<img");
+});
+
+test("ready handoff focuses its heading and links visibly to the identical QR target", () => {
+  const galleryUrl =
+    "https://booth.example/summer-party/gallery?photo=summer-party%2Fcurrent.jpg";
+  const html = renderToStaticMarkup(
+    <HandoffPanel
+      handoff={{
+        captureId: "current",
+        status: "ready",
+        key: "summer-party/current.jpg",
+        photoUrl: "https://photos.example/current.jpg",
+        galleryUrl,
+      }}
+      labels={labels}
+      onContinue={() => {}}
+    />,
+  );
+
+  expect(html).toContain('tabindex="-1"');
+  expect(html).toContain("Your exact photo");
+  expect(html).toContain(`href="${galleryUrl.replaceAll("&", "&amp;")}"`);
+  expect(html).toContain("Open exact photo");
+  expect(html).toContain("Continue");
+});
+
+test("a stale asynchronous QR result cannot match a newer handoff", () => {
+  const newer = {
+    captureId: "newer",
+    status: "ready" as const,
+    key: "summer-party/newer.jpg",
+    photoUrl: "https://photos.example/newer.jpg",
+    galleryUrl:
+      "https://booth.example/summer-party/gallery?photo=summer-party%2Fnewer.jpg",
+  };
+
+  expect(isCurrentQrImage(newer, {
+    captureId: "older",
+    galleryUrl:
+      "https://booth.example/summer-party/gallery?photo=summer-party%2Folder.jpg",
+    dataUrl: "data:image/png;base64,older",
+  })).toBe(false);
+  expect(isCurrentQrImage(newer, {
+    captureId: "newer",
+    galleryUrl: newer.galleryUrl,
+    dataUrl: "data:image/png;base64,newer",
+  })).toBe(true);
+});
diff --git a/app/[event]/handoff-panel.tsx b/app/[event]/handoff-panel.tsx
new file mode 100644
index 0000000..d706281
--- /dev/null
+++ b/app/[event]/handoff-panel.tsx
@@ -0,0 +1,107 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import QRCode from "qrcode";
+import type { CurrentHandoff } from "./booth-session/handoff";
+import styles from "./booth.module.css";
+
+export type HandoffPanelProps = {
+  handoff: CurrentHandoff;
+  labels: {
+    queued: string;
+    title: string;
+    body: string;
+    viewPhoto: string;
+    continue: string;
+  };
+  onContinue(): void;
+};
+
+export type QrImage = {
+  captureId: string;
+  galleryUrl: string;
+  dataUrl: string;
+};
+
+export function isCurrentQrImage(
+  handoff: CurrentHandoff,
+  qr: QrImage | null,
+): qr is QrImage {
+  return handoff.status === "ready"
+    && qr?.captureId === handoff.captureId
+    && qr.galleryUrl === handoff.galleryUrl;
+}
+
+export function HandoffPanel({
+  handoff,
+  labels,
+  onContinue,
+}: HandoffPanelProps) {
+  const headingRef = useRef<HTMLHeadingElement>(null);
+  const [qr, setQr] = useState<QrImage | null>(null);
+
+  useEffect(() => {
+    headingRef.current?.focus();
+  }, [handoff.captureId]);
+
+  useEffect(() => {
+    let current = true;
+    setQr(null);
+    if (handoff.status !== "ready") return () => {
+      current = false;
+    };
+    const { captureId, galleryUrl } = handoff;
+    void QRCode.toDataURL(galleryUrl, {
+      errorCorrectionLevel: "M",
+      margin: 2,
+      width: 320,
+    }).then((dataUrl) => {
+      if (current) setQr({ captureId, galleryUrl, dataUrl });
+    }).catch(() => {
+      // The exact text link remains available if local QR generation fails.
+    });
+    return () => {
+      current = false;
+    };
+  }, [handoff]);
+
+  const exactQr = isCurrentQrImage(handoff, qr) ? qr : null;
+
+  return (
+    <section className={styles.handoff} aria-labelledby="handoff-title">
+      <div className={styles.handoffPanel}>
+        <h1 id="handoff-title" ref={headingRef} tabIndex={-1}>
+          {handoff.status === "ready" ? labels.title : labels.queued}
+        </h1>
+        {handoff.status === "waiting" ? (
+          <p role="status" aria-live="polite">{labels.queued}</p>
+        ) : (
+          <>
+            <p>{labels.body}</p>
+            {exactQr && (
+              // Generated locally from the same value used by the visible anchor.
+              // eslint-disable-next-line @next/next/no-img-element
+              <img
+                className={styles.handoffQr}
+                src={exactQr.dataUrl}
+                alt=""
+                data-gallery-url={exactQr.galleryUrl}
+              />
+            )}
+            <a
+              className={styles.handoffLink}
+              href={handoff.galleryUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              {labels.viewPhoto}
+            </a>
+          </>
+        )}
+        <button className={styles.handoffContinue} type="button" onClick={onContinue}>
+          {labels.continue}
+        </button>
+      </div>
+    </section>
+  );
+}
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index ee7ed92..b84d9e4 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -1,13 +1,27 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from "react";
 import { useParams } from "next/navigation";
 import styles from "./booth.module.css";
-import { TEMPLATES, availableTemplates, composite } from "../templates";
+import {
+  TEMPLATES,
+  availableTemplates,
+  composeToCanvas,
+  encodeCanvas,
+} from "../templates";
+import { frameLabel } from "../frame-packs/catalog";
 import { createOutboxStore, type OutboxItem } from "./booth-session/outbox";
 import {
   BoothSession,
   runCaptureSequence,
+  type UploadAcknowledgement,
   type UploadResult,
   type UploadState,
 } from "./booth-session/session";
@@ -53,6 +67,32 @@ import {
   performVerifiedOperatorExit,
   type OperatorExitResult,
 } from "./operator-controls";
+import { CaptureReview } from "./capture-review";
+import { CountdownToneController } from "./booth-session/countdown-audio";
+import {
+  INITIAL_CAPTURE_FLOW_STATE,
+  reduceCaptureFlow,
+  type ReviewCandidate,
+} from "./booth-session/capture-flow";
+import { decodePhotoFileToCanvas } from "./booth-session/capture-candidate";
+import {
+  applyAcknowledgement,
+  beginHandoff,
+  type CurrentHandoff,
+} from "./booth-session/handoff";
+import { HandoffPanel } from "./handoff-panel";
+import {
+  applyDocumentLocale,
+  deviceLocaleStorageKey,
+  resolveDeviceLocale,
+  resolveEnabledLocales,
+  saveDeviceLocale,
+} from "../i18n/locale";
+import {
+  message,
+  type SupportedLocale,
+} from "../i18n/catalog";
+import type { EventExperience } from "../event-config";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
 type OperationalState = BoothOperationalClientState;
@@ -120,6 +160,7 @@ async function requestBoothPreflight(
 export default function Booth() {
   const { event } = useParams<{ event: string }>();
   const videoRef = useRef<HTMLVideoElement>(null);
+  const shutterRef = useRef<HTMLButtonElement>(null);
   const streamRef = useRef<MediaStream | null>(null);
   const sessionRef = useRef<BoothSession | null>(null);
   const statePollerRef = useRef<BoothStatePoller | null>(null);
@@ -139,12 +180,23 @@ export default function Booth() {
     }).wakeLock;
     return new ScreenWakeController(provider);
   }, []);
+  const captureFlowRef = useRef(INITIAL_CAPTURE_FLOW_STATE);
+  const acceptingCandidatesRef = useRef(new Set<string>());
+  const tonesRef = useRef(new CountdownToneController());
   const [status, setStatus] = useState<Status>("starting");
   const [accessState, setAccessState] = useState<BoothAccessState>("locked");
   const [accessFeedback, setAccessFeedback] =
     useState<BoothAccessFeedback>("recovering");
   const [outboxRecovered, setOutboxRecovered] = useState(false);
   const [mode, setMode] = useState<keyof typeof TEMPLATES | null>(null);
+  const [captureFlow, dispatchCapture] = useReducer(
+    reduceCaptureFlow,
+    INITIAL_CAPTURE_FLOW_STATE,
+  );
+  captureFlowRef.current = captureFlow;
+  const [handoff, setHandoff] = useState<CurrentHandoff | null>(null);
+  const [experience, setExperience] = useState<EventExperience | null>(null);
+  const [locale, setLocale] = useState<SupportedLocale>("en");
   const [count, setCount] = useState(0);
   const [shot, setShot] = useState(0); // e.g. 2 of 3
   const [flash, setFlash] = useState(false);
@@ -168,6 +220,20 @@ export default function Booth() {
   // Event experience. `null` is never shown while the Booth is locked.
   const [enabled, setEnabled] = useState<string[] | null>(null);
 
+  const enabledLocales = useMemo(
+    () => resolveEnabledLocales(experience?.locales),
+    [experience?.locales],
+  );
+  const reviewEnabled = experience?.capture?.reviewEnabled ?? true;
+  const autoAcceptSeconds = experience?.capture?.autoAcceptSeconds ?? 5;
+  const countdownAudioEnabled =
+    experience?.capture?.countdownAudioDefault ?? false;
+  const label = useCallback(
+    (key: Parameters<typeof message>[1], values?: Record<string, string | number>) =>
+      message(locale, key, values),
+    [locale],
+  );
+
   const startCamera = useCallback(async () => {
     if (operationalRef.current.paused || unmountedRef.current) return;
     const request = ++cameraRequestRef.current;
@@ -233,6 +299,14 @@ export default function Booth() {
   }, [wakeController]);
 
   const clearFrame = useCallback(() => {
+    const candidate = captureFlowRef.current.candidate;
+    if (candidate) {
+      candidate.canvas.width = 0;
+      candidate.canvas.height = 0;
+      acceptingCandidatesRef.current.delete(candidate.id);
+    }
+    dispatchCapture({ type: "reset" });
+    setHandoff(null);
     setMode(null);
     setShot(0);
     setCount(0);
@@ -275,12 +349,14 @@ export default function Booth() {
       onReset: () => {
         const initial = createBoothOperationalSessionState(Date.now());
         pauseBoundary.reset();
+        clearFrame();
         operationalRef.current = initial.operational;
         uploadStateRef.current = INITIAL_UPLOAD_STATE;
         deviceIdRef.current = loadOrCreateDeviceId(window.localStorage);
         sessionStartedAtRef.current = initial.sessionStartedAt;
         setStatus("starting");
-        setMode(null);
+        setExperience(null);
+        acceptingCandidatesRef.current.clear();
         setLastUrl(null);
         setError(null);
         setCount(0);
@@ -297,17 +373,35 @@ export default function Booth() {
       onOutboxRecovered: () => setOutboxRecovered(true),
       onAccess: (state, feedback) => {
         if (state === "locked" && feedback === "rejected-key") {
+          clearFrame();
           setStatus("starting");
-          setMode(null);
           setError(null);
-          setCount(0);
-          setShot(0);
-          setFlash(false);
         }
         setAccessState(state);
         setAccessFeedback(feedback);
       },
       onFrames: setEnabled,
+      onExperience: (nextExperience) => {
+        setExperience(nextExperience);
+        if (!nextExperience) return;
+        let storedLocale: string | null = null;
+        try {
+          storedLocale = window.localStorage.getItem(
+            deviceLocaleStorageKey(event),
+          );
+        } catch {
+          // Locale persistence is best-effort.
+        }
+        const nextLocale = resolveDeviceLocale({
+          event,
+          configured: nextExperience.locales,
+          defaultLocale: nextExperience.defaultLocale,
+          storedLocale,
+          navigatorLanguages: navigator.languages,
+        });
+        setLocale(nextLocale);
+        applyDocumentLocale(document.documentElement, nextLocale);
+      },
       onOperationalState: (value) => {
         const state = parseBoothOperationalState(value);
         if (state) {
@@ -359,6 +453,8 @@ export default function Booth() {
     }),
     [
       applyOperationalState,
+      clearFrame,
+      event,
       pauseBoundary,
       requestWake,
       startCamera,
@@ -369,9 +465,12 @@ export default function Booth() {
 
   useEffect(() => {
     unmountedRef.current = false;
+    const tones = new CountdownToneController();
+    tonesRef.current = tones;
     return () => {
       unmountedRef.current = true;
       stopCamera();
+      void tones.dispose();
     };
   }, [stopCamera]);
 
@@ -437,11 +536,22 @@ export default function Booth() {
       return res.json() as Promise<{ url: string; key?: string; duplicate?: boolean }>;
     };
     let session!: BoothSession;
+    const acknowledge = (acknowledgement: UploadAcknowledgement) => {
+      if (!lifecycle.isActive(session)) return;
+      lifecycle.acceptUploaded(session, acknowledgement.result);
+      setHandoff((current) =>
+        applyAcknowledgement(
+          current,
+          acknowledgement,
+          window.location.origin,
+        )
+      );
+    };
     session = new BoothSession(
       event,
       createOutboxStore(),
       uploadOne,
-      (result) => lifecycle.acceptUploaded(session, result),
+      acknowledge,
       undefined,
       undefined,
       {
@@ -544,7 +654,98 @@ export default function Booth() {
     void sessionRef.current?.retry();
   }, [accessState, uploadState.pendingCount]);
 
-  // take the whole sequence for the chosen mode, composite, upload
+  const acceptCandidate = useCallback(async (
+    candidate: ReviewCandidate,
+    fromReview = true,
+  ) => {
+    // This identity guard runs before any await, so an automatic timer and a
+    // button can never encode or enqueue the same candidate twice.
+    if (acceptingCandidatesRef.current.has(candidate.id)) return;
+    acceptingCandidatesRef.current.add(candidate.id);
+    if (fromReview) {
+      dispatchCapture({ type: "accept", candidateId: candidate.id });
+    }
+    const session = sessionRef.current;
+    const controller = captureRef.current;
+    try {
+      if (!session) throw new Error(label("queueStarting"));
+      const blob = await encodeCanvas(candidate.canvas);
+      const item = await session.enqueueCapture(
+        async () => blob,
+        {
+          signal: controller?.signal,
+          metadata: {
+            source: candidate.source,
+            ...(candidate.frameKey ? { frameKey: candidate.frameKey } : {}),
+          },
+        },
+      );
+      if (
+        controller?.signal.aborted
+        || unmountedRef.current
+        || !lifecycle.isActive(session)
+      ) {
+        return;
+      }
+
+      // Establish correlation before upload processing can acknowledge.
+      setHandoff(beginHandoff(item));
+      dispatchCapture({
+        type: "enqueue-succeeded",
+        candidateId: candidate.id,
+      });
+      setError(null);
+      setMode(null);
+      setStatus("picking");
+      setCount(0);
+      setShot(0);
+      setFlash(false);
+      candidate.canvas.width = 0;
+      candidate.canvas.height = 0;
+      if (captureRef.current === controller) captureRef.current = null;
+      pauseBoundary.completeOperation();
+      // Pause never interrupts this ordered Outbox drain.
+      void session.process();
+    } catch {
+      if (
+        controller?.signal.aborted
+        || unmountedRef.current
+        || !session
+        || !lifecycle.isActive(session)
+      ) {
+        return;
+      }
+      acceptingCandidatesRef.current.delete(candidate.id);
+      dispatchCapture({
+        type: "accept-failed",
+        candidateId: candidate.id,
+        error: label("saveFailed"),
+      });
+    }
+  }, [label, lifecycle, pauseBoundary]);
+
+  const retakeCandidate = useCallback((candidate: ReviewCandidate) => {
+    if (acceptingCandidatesRef.current.has(candidate.id)) return;
+    acceptingCandidatesRef.current.add(candidate.id);
+    dispatchCapture({ type: "retake", candidateId: candidate.id });
+    candidate.canvas.width = 0;
+    candidate.canvas.height = 0;
+    captureRef.current?.abort();
+    captureRef.current = null;
+    setError(null);
+    setCount(0);
+    setShot(0);
+    setFlash(false);
+    const pausedAtBoundary = pauseBoundary.completeOperation();
+    if (!pausedAtBoundary) {
+      setStatus(candidate.frameKey ? "ready" : "denied");
+      if (candidate.frameKey) {
+        requestAnimationFrame(() => shutterRef.current?.focus());
+      }
+    }
+  }, [pauseBoundary]);
+
+  // Take the whole sequence, then keep the exact unencoded composite for review.
   const run = useCallback(async () => {
     if (
       accessState !== "ready"
@@ -553,59 +754,71 @@ export default function Booth() {
       || !mode
       || !pauseBoundary.beginOperation()
     ) return;
+    const toneActivation = countdownAudioEnabled
+      ? tonesRef.current.activate()
+      : Promise.resolve(false);
     const t = TEMPLATES[mode];
+    const attemptId = crypto.randomUUID();
+    dispatchCapture({ type: "start-capture", attemptId });
     setStatus("running");
     const controller = new AbortController();
     captureRef.current = controller;
     const session = sessionRef.current;
     try {
-      if (!session) throw new Error("Photo queue is still starting — please try again");
-      setDurableHandoffActive(true);
-      await session.enqueueCapture(
-        async (signal) => {
-          const frames = await runCaptureSequence({
-            shots: t.shots,
-            intervalMs: t.intervalMs,
-            signal,
-            captureFrame: grabFrame,
-            onCountdown: (nextCount, nextShot) => {
-              setCount(nextCount);
-              setShot(nextShot);
-            },
-            onFlash: setFlash,
-          });
-          return composite(frames, frames.map((f) => ({ w: f.width, h: f.height })), t);
+      if (!session) throw new Error(label("queueStarting"));
+      await toneActivation;
+      const frames = await runCaptureSequence({
+        shots: t.shots,
+        intervalMs: t.intervalMs,
+        signal: controller.signal,
+        captureFrame: grabFrame,
+        onCountdown: (nextCount, nextShot) => {
+          setCount(nextCount);
+          setShot(nextShot);
+          tonesRef.current.tick(nextCount);
         },
-        {
-          signal: controller.signal,
-          metadata: {
-            source: "framed",
-            frameKey: mode,
-          },
-        }
+        onFlash: (visible) => {
+          setFlash(visible);
+          if (visible) tonesRef.current.captured();
+        },
+      });
+      const canvas = await composeToCanvas(
+        frames,
+        frames.map((frame) => ({ w: frame.width, h: frame.height })),
+        t,
       );
       setDurableHandoffActive(false);
       if (controller.signal.aborted || !lifecycle.isActive(session)) return;
-      // Durable handoff is complete. Return to the picker before uploading so
-      // the next guest is never trapped on the previous guest's frame.
+      const candidate: ReviewCandidate = {
+        id: crypto.randomUUID(),
+        source: "framed",
+        frameKey: mode,
+        canvas,
+      };
+      dispatchCapture({
+        type: "capture-complete",
+        attemptId,
+        candidate,
+        reviewEnabled,
+      });
       setError(null);
-      if (!pauseBoundary.completeOperation()) clearFrame();
-      // Pause gates new capture only. It never interrupts the ordered Outbox.
-      void session.process();
-    } catch (e) {
+      setCount(0);
+      setShot(0);
+      setFlash(false);
+      if (!reviewEnabled) void acceptCandidate(candidate, false);
+    } catch {
       if (controller.signal.aborted || !session || !lifecycle.isActive(session)) return;
-      // composite (frame art fetch, toBlob) failed — surface it and recover
-      // instead of leaving the booth stuck in "running" until a reload
-      setError(e instanceof Error ? e.message : String(e));
+      const captureMessage = label("captureFailed");
+      dispatchCapture({
+        type: "capture-failed",
+        attemptId,
+        error: captureMessage,
+      });
+      setError(captureMessage);
       setShot(0);
       setCount(0);
       setFlash(false);
-      if (!pauseBoundary.completeOperation()) {
-        setMode(null);
-        setStatus(streamRef.current ? "picking" : "denied");
-      }
-    } finally {
-      setDurableHandoffActive(false);
+      if (!pauseBoundary.completeOperation()) setStatus("ready");
       if (captureRef.current === controller) captureRef.current = null;
     }
   }, [
@@ -613,15 +826,15 @@ export default function Booth() {
     status,
     mode,
     grabFrame,
+    label,
     lifecycle,
-    clearFrame,
     pauseBoundary,
+    reviewEnabled,
+    acceptCandidate,
+    countdownAudioEnabled,
   ]);
 
-  // fallback: native file input (camera) when getUserMedia is blocked.
-  // Re-encode to a real JPEG first — iPhones hand back HEIC, and the stored
-  // key/content-type is always .jpg / image/jpeg.
-  // ponytail: fallback photos stay frameless; compositing needs the live capture flow.
+  // File-camera fallback decodes to a canvas and joins the same exact review.
   const onFile = useCallback(
     async (e: React.ChangeEvent<HTMLInputElement>) => {
       if (accessState !== "ready" || operationalRef.current.paused) {
@@ -631,54 +844,57 @@ export default function Booth() {
       const file = e.target.files?.[0];
       e.target.value = "";
       if (!file || !pauseBoundary.beginOperation()) return;
+      const attemptId = crypto.randomUUID();
+      dispatchCapture({ type: "start-fallback-capture", attemptId });
+      setStatus("running");
       const controller = new AbortController();
       captureRef.current = controller;
       const session = sessionRef.current;
       try {
-        if (!session) throw new Error("Photo queue is still starting — please try again");
-        setDurableHandoffActive(true);
-        await session.enqueueCapture(async (signal) => {
-          if (signal?.aborted) throw new DOMException("Capture aborted", "AbortError");
-          let blob: Blob = file;
-          try {
-            const bmp = await createImageBitmap(file);
-            const c = document.createElement("canvas");
-            c.width = bmp.width;
-            c.height = bmp.height;
-            c.getContext("2d")!.drawImage(bmp, 0, 0);
-            blob = await new Promise<Blob>((res, rej) =>
-              c.toBlob((b) => (b ? res(b) : rej(new Error("re-encode failed"))), "image/jpeg", 0.9)
-            );
-          } catch {
-            // Undecodable file: preserve it; the server signature check decides.
-          }
-          return blob;
-        }, {
-          signal: controller.signal,
-          metadata: {
-            source: "camera-fallback",
-          },
-        });
-        setDurableHandoffActive(false);
+        if (!session) throw new Error(label("queueStarting"));
+        const canvas = await decodePhotoFileToCanvas(file);
         if (controller.signal.aborted || !lifecycle.isActive(session)) return;
+        const candidate: ReviewCandidate = {
+          id: crypto.randomUUID(),
+          source: "camera-fallback",
+          canvas,
+        };
+        dispatchCapture({
+          type: "capture-complete",
+          attemptId,
+          candidate,
+          reviewEnabled,
+        });
         setError(null);
-        pauseBoundary.completeOperation();
-        void session.process();
-      } catch (uploadError) {
+        if (!reviewEnabled) void acceptCandidate(candidate, false);
+      } catch {
         if (controller.signal.aborted || !session || !lifecycle.isActive(session)) return;
-        setError(uploadError instanceof Error ? uploadError.message : String(uploadError));
-        pauseBoundary.completeOperation();
-      } finally {
-        setDurableHandoffActive(false);
+        const captureMessage = label("decodeFailed");
+        dispatchCapture({
+          type: "capture-failed",
+          attemptId,
+          error: captureMessage,
+        });
+        setError(captureMessage);
+        if (!pauseBoundary.completeOperation()) setStatus("denied");
         if (captureRef.current === controller) captureRef.current = null;
       }
     },
-    [accessState, lifecycle, pauseBoundary]
+    [
+      acceptCandidate,
+      accessState,
+      label,
+      lifecycle,
+      pauseBoundary,
+      reviewEnabled,
+    ]
   );
 
   const pick = (m: keyof typeof TEMPLATES) => {
     if (accessState !== "ready" || operationalRef.current.paused) return;
+    dispatchCapture({ type: "select-frame", frameKey: m });
     setMode(m);
+    setError(null);
     setStatus("ready");
   };
 
@@ -723,6 +939,31 @@ export default function Booth() {
     },
   }), [event, lifecycle, pauseBoundary, stopCamera, wakeController]);
 
+  const changeLocale = (nextLocale: SupportedLocale) => {
+    if (!enabledLocales.includes(nextLocale)) return;
+    setLocale(nextLocale);
+    try {
+      saveDeviceLocale(event, nextLocale, window.localStorage);
+    } catch {
+      // Accessing storage itself can be denied in a restricted browser.
+    }
+    applyDocumentLocale(document.documentElement, nextLocale);
+  };
+
+  const changeFrame = () => {
+    dispatchCapture({ type: "reset" });
+    setMode(null);
+    setError(null);
+    setStatus("picking");
+  };
+
+  const continueFromHandoff = () => {
+    setHandoff(null);
+    dispatchCapture({ type: "handoff-complete" });
+    setError(null);
+    setStatus(streamRef.current ? "picking" : "denied");
+  };
+
   // preview crops to the chosen frame's photo aspect (w/h of its first slot),
   // so guests see exactly what will be captured. Fullscreen until a mode is set.
   const previewAspect = mode ? TEMPLATES[mode].slots[0].w / TEMPLATES[mode].slots[0].h : null;
@@ -747,21 +988,53 @@ export default function Booth() {
       />
       {flash && <div className={styles.flash} />}
       {count > 0 && (
-        <div className={styles.count}>
+        <div
+          className={styles.count}
+          role="status"
+          aria-live="assertive"
+          aria-atomic="true"
+        >
           {count}
-          {shot > 0 && <span className={styles.shot}>{shot} / {mode && TEMPLATES[mode].shots}</span>}
+          {shot > 0 && (
+            <span className={styles.shot}>
+              {label("countdownShot", {
+                shot,
+                total: mode ? TEMPLATES[mode].shots : shot,
+              })}
+            </span>
+          )}
         </div>
       )}
 
-      {accessState === "ready" && status === "picking" && (
+      {accessState === "ready" && status === "picking" && !handoff && (
         <div className={styles.picker}>
           {lastUrl && (
             // eslint-disable-next-line @next/next/no-img-element
-            <img src={lastUrl} alt="Last photo" className={styles.thumb} />
+            <img src={lastUrl} alt={label("lastPhoto")} className={styles.thumb} />
+          )}
+          {enabledLocales.length > 1 && (
+            <label className={styles.localePicker}>
+              <span>{label("language")}</span>
+              <select
+                value={locale}
+                onChange={(event) =>
+                  changeLocale(event.target.value as SupportedLocale)}
+              >
+                {enabledLocales.map((availableLocale) => (
+                  <option key={availableLocale} value={availableLocale}>
+                    {availableLocale === "en"
+                      ? "English"
+                      : availableLocale === "zh-SG"
+                        ? "简体中文"
+                        : "العربية"}
+                  </option>
+                ))}
+              </select>
+            </label>
           )}
-          <h1>Pick a style</h1>
+          <h1>{label("pickStyle")}</h1>
           {availableTemplates(enabled).length === 0 && (
-            <p>No frames are enabled for this event yet.</p>
+            <p>{label("noFrames")}</p>
           )}
           <div className={styles.choices}>
             {availableTemplates(enabled).map((k) => {
@@ -779,8 +1052,12 @@ export default function Booth() {
                   ) : (
                     <span className={`${styles.icon} ${styles.iconSquare}`} />
                   )}
-                  {t.label}
-                  <small>{t.shots === 1 ? "1 photo" : `${t.shots} photos`}</small>
+                  {frameLabel(t, locale)}
+                  <small>
+                    {t.shots === 1
+                      ? label("onePhoto")
+                      : label("photoCount", { count: t.shots })}
+                  </small>
                 </button>
               );
             })}
@@ -788,11 +1065,11 @@ export default function Booth() {
         </div>
       )}
 
-      {accessState === "ready" && status === "denied" && (
+      {accessState === "ready" && status === "denied" && !handoff && (
         <div className={styles.picker}>
-          <p>Camera unavailable. Use your device camera instead:</p>
+          <p>{label("cameraUnavailable")}</p>
           <label className={styles.fileBtn}>
-            Take a photo
+            {label("takePhoto")}
             <input
               type="file"
               accept="image/*"
@@ -805,34 +1082,81 @@ export default function Booth() {
         </div>
       )}
 
-      {accessState === "ready" && (status === "ready" || status === "running") && (
+      {accessState === "ready"
+        && !captureFlow.candidate
+        && (status === "ready" || status === "running") && (
         <div className={styles.bottom}>
           {lastUrl && (
             // eslint-disable-next-line @next/next/no-img-element
-            <img src={lastUrl} alt="Last photo" className={styles.thumb} />
+            <img src={lastUrl} alt={label("lastPhoto")} className={styles.thumb} />
           )}
           <button
+            ref={shutterRef}
             className={styles.shutter}
             onClick={run}
             disabled={accessState !== "ready" || operational.paused || status !== "ready"}
-            aria-label="Start"
+            aria-label={label("startCapture")}
           >
             {status === "running" ? "" : mode && TEMPLATES[mode].shots > 1 ? "▶" : ""}
           </button>
           <button
             className={styles.change}
-            onClick={() => setStatus("picking")}
+            onClick={changeFrame}
             disabled={accessState !== "ready" || operational.paused || status !== "ready"}
           >
-            {mode && TEMPLATES[mode].label} · change
+            {mode && label("changeFrame", {
+              frame: frameLabel(TEMPLATES[mode], locale),
+            })}
           </button>
           <a className={styles.liveLink} href={`/${event}/live`} target="_blank" rel="noreferrer">
-            Live →
+            {label("liveGallery")} →
           </a>
         </div>
       )}
 
-      {accessState === "ready" && uploadState.pendingCount > 0 && status !== "running" && (
+      {accessState === "ready"
+        && captureFlow.candidate
+        && (captureFlow.phase === "reviewing"
+          || captureFlow.phase === "accepting") && (
+        <CaptureReview
+          canvas={captureFlow.candidate.canvas}
+          autoAcceptSeconds={autoAcceptSeconds}
+          accepting={captureFlow.phase === "accepting"}
+          error={captureFlow.error}
+          labels={{
+            usePhoto: label("usePhoto"),
+            retake: label("retake"),
+            moreTime: label("moreTime"),
+            accepting: label("accepting"),
+            preview: label("preview"),
+          }}
+          onAccept={() => void acceptCandidate(captureFlow.candidate!)}
+          onRetake={() => retakeCandidate(captureFlow.candidate!)}
+          onMoreTime={() => dispatchCapture({
+            type: "more-time",
+            candidateId: captureFlow.candidate!.id,
+          })}
+        />
+      )}
+
+      {accessState === "ready" && handoff && (
+        <HandoffPanel
+          handoff={handoff}
+          labels={{
+            queued: label("queued"),
+            title: label("handoffTitle"),
+            body: label("handoffBody"),
+            viewPhoto: label("viewPhoto"),
+            continue: label("continue"),
+          }}
+          onContinue={continueFromHandoff}
+        />
+      )}
+
+      {accessState === "ready"
+        && uploadState.pendingCount > 0
+        && status !== "running"
+        && !handoff && (
         <button
           className={styles.retry}
           onClick={retryUpload}
@@ -840,8 +1164,8 @@ export default function Booth() {
           aria-live="polite"
         >
           {uploadState.status === "uploading"
-            ? `Uploading ${uploadState.pendingCount}…`
-            : `⟳ Retry ${uploadState.pendingCount} pending`}
+            ? label("uploading", { count: uploadState.pendingCount })
+            : `⟳ ${label("retryPending", { count: uploadState.pendingCount })}`}
         </button>
       )}
       {accessState !== "ready" && accessState !== "exited" && (
@@ -857,27 +1181,39 @@ export default function Booth() {
           onRetry={retryPreflight}
         />
       )}
-      {accessState === "ready" && (error || uploadState.error) && (
-        <div className={styles.error} onClick={() => setError(null)}>
-          {error || uploadState.error}
+      {accessState === "ready" && !captureFlow.candidate && error && (
+        <button
+          type="button"
+          className={styles.error}
+          onClick={() => setError(null)}
+          aria-label={label("dismissError")}
+        >
+          {error}
+        </button>
+      )}
+      {accessState === "ready" && uploadState.error && (
+        <div className={styles.uploadError} role="alert">
+          {uploadState.error}
         </div>
       )}
       {accessState === "ready" && !uploadState.durable && (
         <div className={styles.storageWarning} role="status">
-          Offline photo storage is unavailable. Pending photos may be lost if this page reloads.
+          {label("offlineStorageUnavailable")}
         </div>
       )}
       {accessState === "ready" && !operational.connected && (
         <div className={styles.connectivity} role="status" aria-live="polite">
-          Checking Event connection. The last pause state stays in effect.
+          {label("checkingConnection")}
         </div>
       )}
-      {accessState === "ready" && operational.paused && (
+      {accessState === "ready"
+        && operational.paused
+        && !(captureFlow.phase === "reviewing" && captureFlow.candidate) && (
         <section className={styles.operationalPause} aria-labelledby="booth-paused-title">
           <div className={styles.operationalPausePanel} role="status" aria-live="polite">
-            <p className={styles.operationalEyebrow}>Event operator</p>
-            <h1 id="booth-paused-title">Booth paused</h1>
-            <p>Finishing any photo already in progress. This Booth will resume when the Event is ready.</p>
+            <p className={styles.operationalEyebrow}>{label("eventOperator")}</p>
+            <h1 id="booth-paused-title">{label("pausedTitle")}</h1>
+            <p>{label("pausedBody")}</p>
           </div>
         </section>
       )}
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
index e88dc94..94226db 100644
--- a/app/i18n/catalog.ts
+++ b/app/i18n/catalog.ts
@@ -39,6 +39,17 @@ export const englishMessages = {
   nextGuest: "Next guest",
   pausedTitle: "Booth paused",
   countdownShot: "Photo {shot} of {total}",
+  language: "Language",
+  continue: "Continue",
+  dismissError: "Dismiss error",
+  eventOperator: "Event operator",
+  pausedBody:
+    "Finishing any photo already in progress. This Booth will resume when the Event is ready.",
+  checkingConnection:
+    "Checking Event connection. The last pause state stays in effect.",
+  captureFailed: "We couldn’t prepare this photo. Please try again.",
+  saveFailed: "We couldn’t safely save this photo. Choose Use Photo to retry or Retake.",
+  decodeFailed: "We couldn’t read this photo. Please take another one.",
 } satisfies Record<string, string>;
 
 export type MessageKey = keyof typeof englishMessages;
@@ -79,6 +90,15 @@ export const chineseSingaporeMessages: Record<MessageKey, string> = {
   nextGuest: "下一位来宾",
   pausedTitle: "拍照亭已暂停",
   countdownShot: "第 {shot} 张，共 {total} 张",
+  language: "语言",
+  continue: "继续",
+  dismissError: "关闭错误提示",
+  eventOperator: "活动管理员",
+  pausedBody: "正在完成已开始的照片。活动准备就绪后，拍照亭将恢复。",
+  checkingConnection: "正在检查活动连接。当前暂停状态保持不变。",
+  captureFailed: "无法准备这张照片。请重试。",
+  saveFailed: "无法安全保存这张照片。请选择“使用照片”重试或重拍。",
+  decodeFailed: "无法读取这张照片。请重新拍摄。",
 };
 
 export const arabicMessages: Record<MessageKey, string> = {
@@ -118,6 +138,18 @@ export const arabicMessages: Record<MessageKey, string> = {
   nextGuest: "الضيف التالي",
   pausedTitle: "كشك التصوير متوقف مؤقتًا",
   countdownShot: "الصورة {shot} من {total}",
+  language: "اللغة",
+  continue: "متابعة",
+  dismissError: "إغلاق الخطأ",
+  eventOperator: "منظّم الفعالية",
+  pausedBody:
+    "جارٍ إكمال أي صورة بدأ التقاطها. سيُستأنف الكشك عندما تصبح الفعالية جاهزة.",
+  checkingConnection:
+    "جارٍ التحقق من اتصال الفعالية. ستبقى حالة الإيقاف المؤقت الأخيرة سارية.",
+  captureFailed: "تعذر تجهيز هذه الصورة. حاول مرة أخرى.",
+  saveFailed:
+    "تعذر حفظ هذه الصورة بأمان. اختر استخدام الصورة للمحاولة مجددًا أو أعد الالتقاط.",
+  decodeFailed: "تعذرت قراءة هذه الصورة. التقط صورة أخرى.",
 };
 
 const catalogs: Record<SupportedLocale, Record<MessageKey, string>> = {

From 37ca23ea7b1b3d723b5d45f1632fa6ad64236ea5 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:31:37 +0800
Subject: [PATCH 073/105] fix: harden booth accessibility and cleanup

---
 .../booth-session/countdown-audio.test.ts     | 15 +++++++++
 app/[event]/booth-session/countdown-audio.ts  | 10 +++++-
 app/[event]/booth-unlock.test.tsx             | 11 +++++++
 app/[event]/booth.module.css                  | 15 +++++++++
 app/[event]/page.tsx                          | 28 +++++++++++++---
 app/i18n/locale.test.ts                       | 19 +++++++++++
 app/i18n/locale.ts                            | 32 +++++++++++++++++++
 7 files changed, 124 insertions(+), 6 deletions(-)

diff --git a/app/[event]/booth-session/countdown-audio.test.ts b/app/[event]/booth-session/countdown-audio.test.ts
index ecf3d49..4045a0f 100644
--- a/app/[event]/booth-session/countdown-audio.test.ts
+++ b/app/[event]/booth-session/countdown-audio.test.ts
@@ -79,6 +79,21 @@ describe("CountdownToneController", () => {
     }).not.toThrow();
   });
 
+  test("resume rejection closes the allocated context before forgetting it", async () => {
+    const harness = audioHarness();
+    harness.context.resume = async () => {
+      throw new DOMException("gesture rejected", "NotAllowedError");
+    };
+    const tones = new CountdownToneController(
+      () => harness.context as unknown as AudioContext,
+    );
+
+    await expect(tones.activate()).resolves.toBe(false);
+    expect(harness.closes()).toBe(1);
+    await tones.dispose();
+    expect(harness.closes()).toBe(1);
+  });
+
   test("dispose closes the context and permanently releases it", async () => {
     const harness = audioHarness();
     const tones = new CountdownToneController(() => harness.context as unknown as AudioContext);
diff --git a/app/[event]/booth-session/countdown-audio.ts b/app/[event]/booth-session/countdown-audio.ts
index 6526a17..be5a4ad 100644
--- a/app/[event]/booth-session/countdown-audio.ts
+++ b/app/[event]/booth-session/countdown-audio.ts
@@ -27,8 +27,16 @@ export class CountdownToneController {
       this.active = this.context.state === "running";
       return this.active;
     } catch {
+      const context = this.context;
       this.active = false;
-      this.context = null;
+      if (context && context.state !== "closed") {
+        try {
+          await context.close();
+        } catch {
+          // Audio is optional; cleanup failure must not block the booth.
+        }
+      }
+      if (this.context === context) this.context = null;
       return false;
     }
   }
diff --git a/app/[event]/booth-unlock.test.tsx b/app/[event]/booth-unlock.test.tsx
index 90bd570..a596460 100644
--- a/app/[event]/booth-unlock.test.tsx
+++ b/app/[event]/booth-unlock.test.tsx
@@ -134,6 +134,17 @@ describe("Booth page safety wiring", () => {
     expect(source).toContain("await lifecycle.leaveEvent(session)");
     expect(source).not.toContain("await sessionRef.current?.stop()");
   });
+
+  test("keeps the file-camera input keyboard and switch accessible", async () => {
+    const source = await Bun.file(`${import.meta.dir}/page.tsx`).text();
+    const css = await Bun.file(`${import.meta.dir}/booth.module.css`).text();
+
+    expect(source).toContain("className={styles.fileInput}");
+    expect(source).not.toContain("disabled={accessState !== \"ready\" || operational.paused}\n              hidden");
+    expect(css).toContain(".fileInput");
+    expect(css).toContain(".fileBtn:focus-within");
+    expect(css).toContain("min-height: 56px");
+  });
 });
 
 describe("Booth unlock presentation", () => {
diff --git a/app/[event]/booth.module.css b/app/[event]/booth.module.css
index 2569a7f..07810c3 100644
--- a/app/[event]/booth.module.css
+++ b/app/[event]/booth.module.css
@@ -239,6 +239,8 @@
 }
 
 .fileBtn {
+  position: relative;
+  overflow: hidden;
   display: inline-flex;
   min-height: 56px;
   align-items: center;
@@ -354,6 +356,19 @@
   cursor: pointer;
 }
 
+.fileInput {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  opacity: 0;
+  cursor: pointer;
+}
+
+.fileInput:disabled {
+  cursor: not-allowed;
+}
+
 .reviewActions .reviewPrimary,
 .handoffContinue {
   border-color: #ff65aa;
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index b84d9e4..0ace1b9 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -82,7 +82,7 @@ import {
 } from "./booth-session/handoff";
 import { HandoffPanel } from "./handoff-panel";
 import {
-  applyDocumentLocale,
+  DocumentLocaleLease,
   deviceLocaleStorageKey,
   resolveDeviceLocale,
   resolveEnabledLocales,
@@ -183,6 +183,7 @@ export default function Booth() {
   const captureFlowRef = useRef(INITIAL_CAPTURE_FLOW_STATE);
   const acceptingCandidatesRef = useRef(new Set<string>());
   const tonesRef = useRef(new CountdownToneController());
+  const documentLocaleRef = useRef<DocumentLocaleLease | null>(null);
   const [status, setStatus] = useState<Status>("starting");
   const [accessState, setAccessState] = useState<BoothAccessState>("locked");
   const [accessFeedback, setAccessFeedback] =
@@ -348,6 +349,7 @@ export default function Booth() {
         ),
       onReset: () => {
         const initial = createBoothOperationalSessionState(Date.now());
+        documentLocaleRef.current?.restore(event);
         pauseBoundary.reset();
         clearFrame();
         operationalRef.current = initial.operational;
@@ -383,7 +385,10 @@ export default function Booth() {
       onFrames: setEnabled,
       onExperience: (nextExperience) => {
         setExperience(nextExperience);
-        if (!nextExperience) return;
+        if (!nextExperience) {
+          documentLocaleRef.current?.restore(event);
+          return;
+        }
         let storedLocale: string | null = null;
         try {
           storedLocale = window.localStorage.getItem(
@@ -400,7 +405,10 @@ export default function Booth() {
           navigatorLanguages: navigator.languages,
         });
         setLocale(nextLocale);
-        applyDocumentLocale(document.documentElement, nextLocale);
+        documentLocaleRef.current ??= new DocumentLocaleLease(
+          document.documentElement,
+        );
+        documentLocaleRef.current.apply(event, nextLocale);
       },
       onOperationalState: (value) => {
         const state = parseBoothOperationalState(value);
@@ -500,6 +508,13 @@ export default function Booth() {
     return () => window.removeEventListener("beforeunload", warn);
   }, [durableHandoffActive, status, uploadState.pendingCount]);
 
+  useEffect(
+    () => () => {
+      documentLocaleRef.current?.restore(event);
+    },
+    [event],
+  );
+
   // grab the current video frame, mirrored to match the preview, at full res
   const grabFrame = useCallback((): HTMLCanvasElement => {
     const video = videoRef.current!;
@@ -947,7 +962,10 @@ export default function Booth() {
     } catch {
       // Accessing storage itself can be denied in a restricted browser.
     }
-    applyDocumentLocale(document.documentElement, nextLocale);
+    documentLocaleRef.current ??= new DocumentLocaleLease(
+      document.documentElement,
+    );
+    documentLocaleRef.current.apply(event, nextLocale);
   };
 
   const changeFrame = () => {
@@ -1071,12 +1089,12 @@ export default function Booth() {
           <label className={styles.fileBtn}>
             {label("takePhoto")}
             <input
+              className={styles.fileInput}
               type="file"
               accept="image/*"
               capture="user"
               onChange={onFile}
               disabled={accessState !== "ready" || operational.paused}
-              hidden
             />
           </label>
         </div>
diff --git a/app/i18n/locale.test.ts b/app/i18n/locale.test.ts
index 3849a77..48da3da 100644
--- a/app/i18n/locale.test.ts
+++ b/app/i18n/locale.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   applyDocumentLocale,
+  DocumentLocaleLease,
   deviceLocaleStorageKey,
   resolveDeviceLocale,
   resolveEnabledLocales,
@@ -128,4 +129,22 @@ describe("guest locale resolution", () => {
     applyDocumentLocale(root, "zh-SG");
     expect(root).toEqual({ lang: "zh-SG", dir: "ltr" });
   });
+
+  test("restores prior document language only for the active Event or unmount", () => {
+    const root = { lang: "fr", dir: "ltr" };
+    const lease = new DocumentLocaleLease(root);
+
+    lease.apply("launch", "ar");
+    expect(root).toEqual({ lang: "ar", dir: "rtl" });
+    expect(lease.restore("other-event")).toBe(false);
+    expect(root).toEqual({ lang: "ar", dir: "rtl" });
+
+    expect(lease.restore("launch")).toBe(true);
+    expect(root).toEqual({ lang: "fr", dir: "ltr" });
+
+    lease.apply("wedding", "zh-SG");
+    expect(root).toEqual({ lang: "zh-SG", dir: "ltr" });
+    expect(lease.restore()).toBe(true);
+    expect(root).toEqual({ lang: "fr", dir: "ltr" });
+  });
 });
diff --git a/app/i18n/locale.ts b/app/i18n/locale.ts
index a6f4c59..b2cda66 100644
--- a/app/i18n/locale.ts
+++ b/app/i18n/locale.ts
@@ -85,3 +85,35 @@ export function applyDocumentLocale(
   documentElement.lang = locale;
   documentElement.dir = localeDirection(locale);
 }
+
+type DocumentLocaleRoot = Pick<HTMLElement, "lang" | "dir">;
+
+export class DocumentLocaleLease {
+  private readonly originalLang: string;
+  private readonly originalDir: string;
+  private activeEvent: string | null = null;
+
+  constructor(private readonly documentElement: DocumentLocaleRoot) {
+    this.originalLang = documentElement.lang;
+    this.originalDir = documentElement.dir;
+  }
+
+  apply(event: string, locale: SupportedLocale): void {
+    this.activeEvent = event;
+    applyDocumentLocale(this.documentElement, locale);
+  }
+
+  restore(event?: string): boolean {
+    if (
+      this.activeEvent === null
+      || (event !== undefined && event !== this.activeEvent)
+    ) {
+      return false;
+    }
+
+    this.documentElement.lang = this.originalLang;
+    this.documentElement.dir = this.originalDir;
+    this.activeEvent = null;
+    return true;
+  }
+}

From 0356edeff149bd756bd1f3f3b30ba36bdec80b15 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:33:09 +0800
Subject: [PATCH 074/105] feat: page and rebuild private moderation index

---
 app/event-store.test.ts | 243 ++++++++++++++++++++++++++++++++
 app/event-store.ts      | 301 ++++++++++++++++++++++++++++++++++++++++
 app/moderation.test.ts  |  91 ++++++++++++
 app/moderation.ts       | 170 +++++++++++++++++++++++
 4 files changed, 805 insertions(+)
 create mode 100644 app/moderation.test.ts
 create mode 100644 app/moderation.ts

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index f4e2f4c..f31f141 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -7,6 +7,8 @@ import {
   EventStore,
   InMemoryObjectStore,
   InvalidEventSlugError,
+  InvalidStoredModerationPhotoError,
+  InvalidPhotoIndexRebuildStateError,
   InvalidPhotoCursorError,
   InvalidStoredConfigRevisionError,
   eventConfigKey,
@@ -20,6 +22,8 @@ import {
   photoFeedHeadKey,
   photoFeedMarkerKey,
   photoIndexKey,
+  photoIndexRebuildCheckpointKey,
+  photoIndexRebuildCompleteKey,
   photoReceiptKey,
   type ListOptions,
   type ListResult,
@@ -51,6 +55,58 @@ class FailPrivatePhotoWriteStore extends InMemoryObjectStore {
   }
 }
 
+class CappedListStore extends InMemoryObjectStore {
+  constructor(private readonly cap: number) {
+    super();
+  }
+
+  override list(options: ListOptions = {}): Promise<ListResult> {
+    return super.list({ ...options, limit: Math.min(options.limit ?? this.cap, this.cap) });
+  }
+}
+
+class FailNextIndexCreateStore extends InMemoryObjectStore {
+  fail = true;
+
+  override async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    if (this.fail && key.includes("/photo-index/v1/")) {
+      this.fail = false;
+      throw new Error("simulated index write failure");
+    }
+    return super.compareAndSwap(key, expectedEtag, value);
+  }
+}
+
+class MissingDuringRebuildStore extends InMemoryObjectStore {
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    if (key === "launch/1753315200000-gone.jpg") {
+      await this.delete(key);
+      return null;
+    }
+    return super.get(key);
+  }
+}
+
+class CrashBeforeCompleteMarkerStore extends InMemoryObjectStore {
+  crash = true;
+
+  override async compareAndSwap(
+    key: string,
+    expectedEtag: string | null,
+    value: ArrayBuffer | ArrayBufferView | string
+  ): Promise<boolean> {
+    if (this.crash && key === photoIndexRebuildCompleteKey("launch")) {
+      this.crash = false;
+      throw new Error("simulated crash before complete marker");
+    }
+    return super.compareAndSwap(key, expectedEtag, value);
+  }
+}
+
 class GuardedPhotoListStore extends InMemoryObjectStore {
   rejectPhotoLists = false;
 
@@ -1842,6 +1898,193 @@ describe("EventStore", () => {
     expect(photos.reads).toEqual(["launch/0000000001000-missing.jpg"]);
   });
 
+  test("pages the private inverse-time index newest-first across bounded storage pages", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new CappedListStore(1);
+    const store = new EventStore(photos, state, "https://photos.example");
+    const records = [
+      { key: "launch/0000000001000-a.jpg", capturedAt: 1_000 },
+      { key: "launch/0000000002000-b.jpg", capturedAt: 2_000 },
+      { key: "launch/0000000003000-c.jpg", capturedAt: 3_000 },
+    ];
+    for (const record of records) {
+      photos.set(record.key, record.key, new Date(record.capturedAt));
+      state.set(photoIndexKey("launch", record.key, record.capturedAt), JSON.stringify({
+        version: 1,
+        ...record,
+        uploadedAt: new Date(record.capturedAt).toISOString(),
+        source: "framed",
+        frameKey: "celebration",
+        configRevisionId: "private-revision",
+      }));
+    }
+
+    const first = await store.listModerationPhotos("launch", { limit: 2 });
+    expect(first.photos).toEqual([
+      {
+        key: records[2]!.key,
+        url: `https://photos.example/${records[2]!.key}`,
+        uploadedAt: new Date(3_000).toISOString(),
+        capturedAt: 3_000,
+        source: "framed",
+        frameKey: "celebration",
+      },
+      {
+        key: records[1]!.key,
+        url: `https://photos.example/${records[1]!.key}`,
+        uploadedAt: new Date(2_000).toISOString(),
+        capturedAt: 2_000,
+        source: "framed",
+        frameKey: "celebration",
+      },
+    ]);
+    expect(first.nextCursor).toStartWith("mod1.");
+
+    const newest = { key: "launch/0000000004000-new.jpg", capturedAt: 4_000 };
+    photos.set(newest.key, "new", new Date(newest.capturedAt));
+    state.set(photoIndexKey("launch", newest.key, newest.capturedAt), JSON.stringify({
+      version: 1,
+      ...newest,
+      uploadedAt: new Date(newest.capturedAt).toISOString(),
+    }));
+
+    const second = await store.listModerationPhotos("launch", {
+      limit: 2,
+      cursor: first.nextCursor!,
+    });
+    expect(second.photos.map((photo) => photo.key)).toEqual([records[0]!.key]);
+    expect(second.nextCursor).toBeNull();
+  });
+
+  test("filters inclusively, deduplicates exact keys, and skips missing public photos", async () => {
+    const photos = new InMemoryObjectStore({
+      "launch/0000000002000-b.jpg": "b",
+      "launch/0000000003000-c.jpg": "c",
+    });
+    const state = new InMemoryObjectStore();
+    const metadata = (key: string, capturedAt: number) => JSON.stringify({
+      version: 1,
+      key,
+      uploadedAt: new Date(capturedAt).toISOString(),
+      capturedAt,
+    });
+    state.set(photoIndexKey("launch", "launch/0000000004000-missing.jpg", 4_000),
+      metadata("launch/0000000004000-missing.jpg", 4_000));
+    state.set(photoIndexKey("launch", "launch/0000000003000-c.jpg", 3_500),
+      metadata("launch/0000000003000-c.jpg", 3_000));
+    state.set(photoIndexKey("launch", "launch/0000000003000-c.jpg", 3_000),
+      metadata("launch/0000000003000-c.jpg", 3_000));
+    state.set(photoIndexKey("launch", "launch/0000000002000-b.jpg", 2_000),
+      metadata("launch/0000000002000-b.jpg", 2_000));
+
+    const page = await new EventStore(photos, state, "https://photos.example")
+      .listModerationPhotos("launch", { limit: 10, from: 2_000, to: 3_000 });
+
+    expect(page.photos.map((photo) => photo.key)).toEqual([
+      "launch/0000000003000-c.jpg",
+      "launch/0000000002000-b.jpg",
+    ]);
+    expect(page.nextCursor).toBeNull();
+  });
+
+  test("fails explicitly on corrupt, future, expanded, or cross-Event index records", async () => {
+    const photos = new InMemoryObjectStore({ "launch/0000000001000-a.jpg": "a" });
+    for (const record of [
+      { version: 2, key: "launch/0000000001000-a.jpg", uploadedAt: new Date(1_000).toISOString(), capturedAt: 1_000 },
+      { version: 1, key: "other/0000000001000-a.jpg", uploadedAt: new Date(1_000).toISOString(), capturedAt: 1_000 },
+      { version: 1, key: "launch/0000000001000-a.jpg", uploadedAt: new Date(1_000).toISOString(), capturedAt: 1_000, heartbeat: true },
+    ]) {
+      const state = new InMemoryObjectStore({
+        [photoIndexKey("launch", "launch/0000000001000-a.jpg", 1_000)]: JSON.stringify(record),
+      });
+      await expect(new EventStore(photos, state, "https://photos.example")
+        .listModerationPhotos("launch", { limit: 10 }))
+        .rejects.toBeInstanceOf(InvalidStoredModerationPhotoError);
+    }
+  });
+
+  test("rebuilds legacy indexes in bounded add-only batches without receipts", async () => {
+    const photos = new InMemoryObjectStore();
+    photos.set("launch/1753315200000-a.jpg", "a", new Date("2025-07-25T00:00:00.000Z"));
+    photos.set("launch/legacy-b.jpg", "b", new Date("2025-07-26T00:00:00.000Z"));
+    photos.set("launch/notes.txt", "notes", new Date("2025-07-27T00:00:00.000Z"));
+    photos.set("other/1753315200000-other.jpg", "other");
+    const state = new InMemoryObjectStore();
+    const existingKey = photoIndexKey("launch", "launch/1753315200000-a.jpg", 1753315200000);
+    state.set(existingKey, "existing-bytes");
+    const existingEtag = (await state.get(existingKey))!.etag;
+    const store = new EventStore(photos, state, "https://photos.example");
+
+    const first = await store.rebuildPhotoIndex("launch", { batchSize: 2 });
+    expect(first).toMatchObject({ complete: false, scanned: 2, indexed: 1 });
+    expect(first.checkpoint).toBe("launch/legacy-b.jpg");
+    expect((await state.get(existingKey))!.etag).toBe(existingEtag);
+
+    const second = await store.rebuildPhotoIndex("launch", { batchSize: 2 });
+    expect(second).toMatchObject({ complete: true, scanned: 1, indexed: 0 });
+    expect(state.has(photoIndexKey(
+      "launch",
+      "launch/legacy-b.jpg",
+      new Date("2025-07-26T00:00:00.000Z").getTime()
+    ))).toBe(true);
+    expect(state.has(photoReceiptKey("launch", "launch/1753315200000-a.jpg"))).toBe(false);
+    expect(state.has(photoReceiptKey("launch", "launch/legacy-b.jpg"))).toBe(false);
+    expect(state.has(photoIndexRebuildCompleteKey("launch"))).toBe(true);
+    expect((await state.list({ prefix: "events/other/" })).objects).toHaveLength(0);
+  });
+
+  test("does not checkpoint past a failed index batch and safely retries create-only writes", async () => {
+    const photos = new InMemoryObjectStore({
+      "launch/1753315200000-a.jpg": "a",
+      "launch/1753315200001-b.jpg": "b",
+    });
+    const state = new FailNextIndexCreateStore();
+    const store = new EventStore(photos, state, "https://photos.example");
+
+    await expect(store.rebuildPhotoIndex("launch", { batchSize: 2 })).rejects.toThrow("index");
+    expect(state.has(photoIndexRebuildCheckpointKey("launch"))).toBe(false);
+    const retried = await store.rebuildPhotoIndex("launch", { batchSize: 2 });
+    expect(retried).toMatchObject({ complete: true, scanned: 2, indexed: 2 });
+  });
+
+  test("rechecks public truth and recovers a crash after the final checkpoint", async () => {
+    const photos = new MissingDuringRebuildStore({
+      "launch/1753315200000-gone.jpg": "gone",
+      "launch/1753315200001-kept.jpg": "kept",
+    });
+    const state = new CrashBeforeCompleteMarkerStore();
+    const store = new EventStore(photos, state, "https://photos.example");
+
+    await expect(store.rebuildPhotoIndex("launch", { batchSize: 10 }))
+      .rejects.toThrow("complete marker");
+    expect(state.has(photoIndexKey("launch", "launch/1753315200000-gone.jpg", 1753315200000))).toBe(false);
+    expect(state.has(photoIndexRebuildCheckpointKey("launch"))).toBe(true);
+    expect(state.has(photoIndexRebuildCompleteKey("launch"))).toBe(false);
+
+    const recovered = await store.rebuildPhotoIndex("launch", { batchSize: 10 });
+    expect(recovered).toEqual({
+      complete: true,
+      scanned: 0,
+      indexed: 0,
+      checkpoint: "launch/1753315200001-kept.jpg",
+    });
+  });
+
+  test("rejects corrupt rebuild checkpoints without touching photos", async () => {
+    const photos = new InMemoryObjectStore({ "launch/1753315200000-a.jpg": "a" });
+    const state = new InMemoryObjectStore({
+      [photoIndexRebuildCheckpointKey("launch")]: JSON.stringify({
+        version: 2,
+        event: "launch",
+        lastPhotoKey: "launch/1753315200000-a.jpg",
+      }),
+    });
+    await expect(new EventStore(photos, state, "https://photos.example")
+      .rebuildPhotoIndex("launch", { batchSize: 10 }))
+      .rejects.toBeInstanceOf(InvalidPhotoIndexRebuildStateError);
+    expect(photos.has("launch/1753315200000-a.jpg")).toBe(true);
+  });
+
   test("writes an exact private heartbeat with a server-controlled timestamp", async () => {
     const now = new Date("2026-07-24T00:00:00.000Z");
     const photos = new InMemoryObjectStore();
diff --git a/app/event-store.ts b/app/event-store.ts
index 6010e25..ec9b6f2 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -32,6 +32,12 @@ import {
   parsePhotoReceipt,
   type PhotoReceiptV1,
 } from "./photo-metadata";
+import {
+  decodeModerationCursor,
+  encodeModerationCursor,
+  parseModerationPhotoRecord,
+  type ModerationPhoto,
+} from "./moderation";
 export { canonicalEvent, InvalidEventSlugError, slugifyEvent };
 export { EVENT_CONFIG_VERSION };
 export type { EventConfig } from "./event-config";
@@ -256,6 +262,10 @@ export const photoReceiptKey = (event: string, key: string) =>
   `events/${event}/photo-metadata/${key.slice(eventPhotoPrefix(event).length)}.json`;
 export const photoIndexKey = (event: string, key: string, sortTime: number) =>
   `events/${event}/photo-index/v1/${String(9_999_999_999_999 - sortTime).padStart(13, "0")}-${base64url(key)}.json`;
+export const photoIndexRebuildCheckpointKey = (event: string) =>
+  `events/${event}/photo-index-rebuild/v1/checkpoint.json`;
+export const photoIndexRebuildCompleteKey = (event: string) =>
+  `events/${event}/photo-index-rebuild/v1/complete.json`;
 export const photoFeedHeadKey = (event: string) => `events/${event}/photo-feed/v1/head.json`;
 const photoFeedEntryKey = (event: string, key: string) =>
   `events/${event}/photo-feed/v1/entries/${base64url(key)}.json`;
@@ -305,6 +315,13 @@ export type ExportPhotoSource = {
   uploadedAt: string;
   receipt: Pick<PhotoReceiptV1, "capturedAt" | "source" | "frameKey"> | null;
 };
+export type ModerationPhotoPage = { photos: ModerationPhoto[]; nextCursor: string | null };
+export type PhotoIndexRebuildResult = {
+  complete: boolean;
+  scanned: number;
+  indexed: number;
+  checkpoint: string | null;
+};
 
 export class ConfigConflictError extends Error {
   constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
@@ -358,6 +375,18 @@ export class InvalidPublicPhotoKeyError extends TypeError {
   }
 }
 
+export class InvalidStoredModerationPhotoError extends Error {
+  constructor(readonly event: string, readonly indexKey: string) {
+    super(`stored moderation photo for ${event} is corrupt or uses an unsupported version`);
+  }
+}
+
+export class InvalidPhotoIndexRebuildStateError extends Error {
+  constructor(readonly event: string) {
+    super(`photo index rebuild state for ${event} is corrupt or uses an unsupported version`);
+  }
+}
+
 export class InvalidStoredBoothHeartbeatError extends Error {
   constructor(readonly event: string) {
     super(`stored booth heartbeat for ${event} is corrupt or uses an unsupported version`);
@@ -1181,6 +1210,247 @@ export class EventStore {
     await this.writePhotoFeedMarker(event, entry.key, node.sequence);
   }
 
+  async listModerationPhotos(
+    event: string,
+    options: {
+      cursor?: string;
+      limit?: number;
+      from?: number;
+      to?: number;
+    }
+  ): Promise<ModerationPhotoPage> {
+    const canonical = canonicalEvent(event);
+    const limit = options.limit ?? 48;
+    const from = options.from ?? null;
+    const to = options.to ?? null;
+    if (
+      !Number.isInteger(limit)
+      || limit < 1
+      || limit > 100
+      || !isNullableSafeTimestamp(from)
+      || !isNullableSafeTimestamp(to)
+      || (from !== null && to !== null && from > to)
+    ) {
+      throw new TypeError("invalid moderation page options");
+    }
+    const decoded = options.cursor === undefined
+      ? null
+      : decodeModerationCursor(options.cursor, { event: canonical, from, to });
+    const prefix = `events/${canonical}/photo-index/v1/`;
+    let startAfter = decoded?.afterIndexKey;
+    let exhausted = false;
+    let lastScanned: string | null = startAfter ?? null;
+    const seen = new Set<string>();
+    const photos: ModerationPhoto[] = [];
+
+    while (photos.length < limit && !exhausted) {
+      const page = await this.state.list({
+        prefix,
+        ...(startAfter ? { startAfter } : {}),
+        limit: Math.max(1, limit - photos.length),
+      });
+      if (page.objects.length === 0) {
+        if (page.truncated) throw new InvalidStoredModerationPhotoError(canonical, startAfter ?? prefix);
+        exhausted = true;
+        break;
+      }
+      for (const object of page.objects) {
+        lastScanned = object.key;
+        startAfter = object.key;
+        const stored = await this.state.get(object.key);
+        if (!stored) continue;
+        let value: unknown;
+        try {
+          value = await stored.json<unknown>();
+        } catch {
+          throw new InvalidStoredModerationPhotoError(canonical, object.key);
+        }
+        const record = parseModerationPhotoRecord(canonical, value);
+        if (!record) throw new InvalidStoredModerationPhotoError(canonical, object.key);
+        if (
+          seen.has(record.key)
+          || (from !== null && record.capturedAt < from)
+          || (to !== null && record.capturedAt > to)
+        ) {
+          continue;
+        }
+        seen.add(record.key);
+        const publicPhoto = await this.photos.get(record.key);
+        if (!publicPhoto || !isPhotoKey(canonical, publicPhoto.key)) continue;
+        photos.push({ ...record, url: this.publicUrl(record.key) });
+        if (photos.length === limit) break;
+      }
+      exhausted = !page.truncated;
+    }
+
+    return {
+      photos,
+      nextCursor: !exhausted && lastScanned
+        ? encodeModerationCursor({
+            version: 1,
+            event: canonical,
+            afterIndexKey: lastScanned,
+            from,
+            to,
+          })
+        : null,
+    };
+  }
+
+  async rebuildPhotoIndex(
+    event: string,
+    options: { batchSize: number }
+  ): Promise<PhotoIndexRebuildResult> {
+    const canonical = canonicalEvent(event);
+    if (!Number.isInteger(options.batchSize) || options.batchSize < 1 || options.batchSize > 1_000) {
+      throw new TypeError("photo index rebuild batch size must be an integer from 1 to 1000");
+    }
+    const completeKey = photoIndexRebuildCompleteKey(canonical);
+    const checkpointKey = photoIndexRebuildCheckpointKey(canonical);
+    const existingComplete = await this.state.get(completeKey);
+    if (existingComplete) {
+      await this.parseRebuildComplete(canonical, existingComplete);
+      const checkpoint = await this.readRebuildCheckpoint(canonical);
+      return {
+        complete: true,
+        scanned: 0,
+        indexed: 0,
+        checkpoint: checkpoint?.lastPhotoKey ?? null,
+      };
+    }
+
+    const checkpoint = await this.readRebuildCheckpoint(canonical);
+    const page = await this.photos.list({
+      prefix: eventPhotoPrefix(canonical),
+      ...(checkpoint ? { startAfter: checkpoint.lastPhotoKey } : {}),
+      limit: options.batchSize,
+    });
+    let indexed = 0;
+    let lastPhotoKey = checkpoint?.lastPhotoKey ?? null;
+
+    for (const object of page.objects) {
+      lastPhotoKey = object.key;
+      if (!isPhotoKey(canonical, object.key)) continue;
+      const current = await this.photos.get(object.key);
+      if (!current || !isPhotoKey(canonical, current.key)) continue;
+      const capturedAt = capturedAtFromLegacyPhotoKey(canonical, current.key)
+        ?? current.uploaded.getTime();
+      const metadata: PrivatePhotoMetadata = {
+        ...photoPrivateMetadata(current.key, current.uploaded),
+        capturedAt,
+      };
+      const created = await this.state.compareAndSwap(
+        photoIndexKey(canonical, current.key, capturedAt),
+        null,
+        JSON.stringify(metadata),
+        jsonWriteOptions()
+      );
+      if (created) indexed += 1;
+    }
+
+    if (page.objects.length > 0 && lastPhotoKey) {
+      const nextCheckpoint: PrivatePhotoIndexRebuildCheckpoint = {
+        version: 1,
+        event: canonical,
+        lastPhotoKey,
+      };
+      const advanced = await this.state.compareAndSwap(
+        checkpointKey,
+        checkpoint?.etag ?? null,
+        JSON.stringify(nextCheckpoint),
+        jsonWriteOptions()
+      );
+      if (!advanced) {
+        const current = await this.readRebuildCheckpoint(canonical);
+        if (!current) throw new InvalidPhotoIndexRebuildStateError(canonical);
+        return {
+          complete: false,
+          scanned: page.objects.length,
+          indexed,
+          checkpoint: current.lastPhotoKey,
+        };
+      }
+    }
+
+    const complete = !page.truncated;
+    if (complete) {
+      const marker: PrivatePhotoIndexRebuildComplete = {
+        version: 1,
+        event: canonical,
+        completedAt: this.now().toISOString(),
+      };
+      await this.state.compareAndSwap(
+        completeKey,
+        null,
+        JSON.stringify(marker),
+        jsonWriteOptions()
+      );
+      const stored = await this.state.get(completeKey);
+      if (!stored) throw new InvalidPhotoIndexRebuildStateError(canonical);
+      await this.parseRebuildComplete(canonical, stored);
+    }
+
+    return {
+      complete,
+      scanned: page.objects.length,
+      indexed,
+      checkpoint: lastPhotoKey,
+    };
+  }
+
+  private async readRebuildCheckpoint(
+    event: string
+  ): Promise<(PrivatePhotoIndexRebuildCheckpoint & { etag: string }) | null> {
+    const object = await this.state.get(photoIndexRebuildCheckpointKey(event));
+    if (!object) return null;
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidPhotoIndexRebuildStateError(event);
+    }
+    if (
+      !isRecord(value)
+      || !hasExactObjectKeys(value, ["version", "event", "lastPhotoKey"])
+      || value.version !== 1
+      || value.event !== event
+      || typeof value.lastPhotoKey !== "string"
+      || !value.lastPhotoKey.startsWith(eventPhotoPrefix(event))
+      || /[\\?#]/.test(value.lastPhotoKey)
+    ) {
+      throw new InvalidPhotoIndexRebuildStateError(event);
+    }
+    return {
+      version: 1,
+      event,
+      lastPhotoKey: value.lastPhotoKey,
+      etag: object.etag,
+    };
+  }
+
+  private async parseRebuildComplete(
+    event: string,
+    object: StoredObjectBody
+  ): Promise<PrivatePhotoIndexRebuildComplete> {
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidPhotoIndexRebuildStateError(event);
+    }
+    if (
+      !isRecord(value)
+      || !hasExactObjectKeys(value, ["version", "event", "completedAt"])
+      || value.version !== 1
+      || value.event !== event
+      || typeof value.completedAt !== "string"
+      || Number.isNaN(Date.parse(value.completedAt))
+    ) {
+      throw new InvalidPhotoIndexRebuildStateError(event);
+    }
+    return { version: 1, event, completedAt: value.completedAt };
+  }
+
   async *iteratePhotoObjects(event: string): AsyncGenerator<StoredObject> {
     let cursor: string | undefined;
     do {
@@ -1662,6 +1932,18 @@ type PhotoFeedCursor = {
 
 type PrivatePhotoMetadata = PhotoReceiptV1;
 
+type PrivatePhotoIndexRebuildCheckpoint = {
+  version: 1;
+  event: string;
+  lastPhotoKey: string;
+};
+
+type PrivatePhotoIndexRebuildComplete = {
+  version: 1;
+  event: string;
+  completedAt: string;
+};
+
 function photoPrivateMetadata(key: string, uploadedAt: Date, upload?: StableUpload): PrivatePhotoMetadata {
   return {
     version: 1,
@@ -1810,6 +2092,25 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+function hasExactObjectKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const sortedExpected = [...expected].sort();
+  return actual.length === sortedExpected.length
+    && actual.every((key, index) => key === sortedExpected[index]);
+}
+
+function isNullableSafeTimestamp(value: unknown): value is number | null {
+  return value === null
+    || (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
+}
+
+function capturedAtFromLegacyPhotoKey(event: string, key: string): number | null {
+  const match = key.slice(eventPhotoPrefix(event).length).match(/^(\d{13})-/);
+  if (!match) return null;
+  const capturedAt = Number(match[1]);
+  return Number.isSafeInteger(capturedAt) ? capturedAt : null;
+}
+
 function isBoundedToken(value: unknown): value is string {
   return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value);
 }
diff --git a/app/moderation.test.ts b/app/moderation.test.ts
new file mode 100644
index 0000000..6221b86
--- /dev/null
+++ b/app/moderation.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import {
+  InvalidModerationCursorError,
+  decodeModerationCursor,
+  encodeModerationCursor,
+  parseModerationPhotoRecord,
+} from "./moderation";
+
+const cursor = {
+  version: 1 as const,
+  event: "launch",
+  afterIndexKey: "events/launch/photo-index/v1/8246684799999-bGF1bmNoL3Bob3RvLmpwZw.json",
+  from: 1753315200000,
+  to: 1753401600000,
+};
+
+describe("moderation cursor", () => {
+  test("round-trips only strict Event-bound filter state", () => {
+    const encoded = encodeModerationCursor(cursor);
+    expect(encoded).toStartWith("mod1.");
+    expect(decodeModerationCursor(encoded, {
+      event: "launch",
+      from: cursor.from,
+      to: cursor.to,
+    })).toEqual(cursor);
+  });
+
+  test("rejects malformed, expanded, unsupported, cross-Event, and changed-filter cursors", () => {
+    const encoded = encodeModerationCursor(cursor);
+    const badValues = [
+      "",
+      "mod1.***",
+      `mod1.${btoa(JSON.stringify({ ...cursor, extra: true }))}`,
+      `mod1.${btoa(JSON.stringify({ ...cursor, version: 2 }))}`,
+      `mod1.${btoa(JSON.stringify({ ...cursor, event: "other" }))}`,
+      `mod1.${btoa(JSON.stringify({ ...cursor, afterIndexKey: "launch/photo.jpg" }))}`,
+    ];
+    for (const value of badValues) {
+      expect(() => decodeModerationCursor(value, {
+        event: "launch",
+        from: cursor.from,
+        to: cursor.to,
+      })).toThrow(InvalidModerationCursorError);
+    }
+    expect(() => decodeModerationCursor(encoded, {
+      event: "launch",
+      from: null,
+      to: cursor.to,
+    })).toThrow(InvalidModerationCursorError);
+  });
+});
+
+describe("private moderation photo records", () => {
+  test("strictly projects safe photo fields and omits private operational metadata", () => {
+    expect(parseModerationPhotoRecord("launch", {
+      version: 1,
+      key: "launch/1753315200000-a.jpg",
+      uploadedAt: "2025-07-24T00:00:00.000Z",
+      capturedAt: 1753315200000,
+      source: "framed",
+      frameKey: "celebration",
+      configRevisionId: "private-revision",
+    })).toEqual({
+      key: "launch/1753315200000-a.jpg",
+      uploadedAt: "2025-07-24T00:00:00.000Z",
+      capturedAt: 1753315200000,
+      source: "framed",
+      frameKey: "celebration",
+    });
+  });
+
+  test("rejects corrupt, future, expanded, and cross-Event records", () => {
+    const valid = {
+      version: 1,
+      key: "launch/1753315200000-a.jpg",
+      uploadedAt: "2025-07-24T00:00:00.000Z",
+      capturedAt: 1753315200000,
+    };
+    for (const value of [
+      { ...valid, version: 2 },
+      { ...valid, key: "other/1753315200000-a.jpg" },
+      { ...valid, uploadedAt: "not-an-instant" },
+      { ...valid, capturedAt: 1.5 },
+      { ...valid, frameKey: 42 },
+      { ...valid, configRevisionId: 42 },
+      { ...valid, heartbeat: true },
+    ]) {
+      expect(parseModerationPhotoRecord("launch", value)).toBeNull();
+    }
+  });
+});
diff --git a/app/moderation.ts b/app/moderation.ts
new file mode 100644
index 0000000..b4d6a75
--- /dev/null
+++ b/app/moderation.ts
@@ -0,0 +1,170 @@
+export type ModerationPhoto = {
+  key: string;
+  url: string;
+  uploadedAt: string;
+  capturedAt: number;
+  source?: "framed" | "camera-fallback";
+  frameKey?: string;
+};
+
+export type ModerationCursor = {
+  version: 1;
+  event: string;
+  afterIndexKey: string;
+  from: number | null;
+  to: number | null;
+};
+
+type ModerationPhotoRecord = Omit<ModerationPhoto, "url">;
+
+const PHOTO_EXTENSIONS = /\.(?:jpe?g|png|gif|webp|hei[cf]|avif)$/i;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+export class InvalidModerationCursorError extends Error {
+  constructor() {
+    super("moderation cursor is invalid for this Event and filter");
+  }
+}
+
+export function encodeModerationCursor(cursor: ModerationCursor): string {
+  validateCursor(cursor, cursor);
+  return `mod1.${base64url(JSON.stringify(cursor))}`;
+}
+
+export function decodeModerationCursor(
+  encoded: string,
+  expected: Pick<ModerationCursor, "event" | "from" | "to">
+): ModerationCursor {
+  if (!encoded.startsWith("mod1.")) throw new InvalidModerationCursorError();
+  let value: unknown;
+  try {
+    value = JSON.parse(base64urlDecode(encoded.slice(5)));
+  } catch {
+    throw new InvalidModerationCursorError();
+  }
+  return validateCursor(value, expected);
+}
+
+export function parseModerationPhotoRecord(
+  event: string,
+  value: unknown
+): ModerationPhotoRecord | null {
+  if (!isRecord(value)) return null;
+  const allowed = new Set([
+    "version",
+    "key",
+    "uploadedAt",
+    "capturedAt",
+    "source",
+    "frameKey",
+    "configRevisionId",
+  ]);
+  if (
+    Object.keys(value).some((key) => !allowed.has(key))
+    || value.version !== 1
+    || typeof value.key !== "string"
+    || !isEventPhotoKey(event, value.key)
+    || typeof value.uploadedAt !== "string"
+    || !isStoredInstant(value.uploadedAt)
+    || typeof value.capturedAt !== "number"
+    || !Number.isSafeInteger(value.capturedAt)
+    || value.capturedAt < 0
+    || (value.source !== undefined && value.source !== "framed" && value.source !== "camera-fallback")
+    || (
+      value.frameKey !== undefined
+      && (typeof value.frameKey !== "string" || !TOKEN.test(value.frameKey))
+    )
+    || (
+      value.configRevisionId !== undefined
+      && (typeof value.configRevisionId !== "string" || !TOKEN.test(value.configRevisionId))
+    )
+  ) {
+    return null;
+  }
+  return {
+    key: value.key,
+    uploadedAt: value.uploadedAt,
+    capturedAt: value.capturedAt,
+    ...(value.source ? { source: value.source } : {}),
+    ...(typeof value.frameKey === "string" ? { frameKey: value.frameKey } : {}),
+  };
+}
+
+function validateCursor(
+  value: unknown,
+  expected: Pick<ModerationCursor, "event" | "from" | "to">
+): ModerationCursor {
+  if (!isRecord(value)) throw new InvalidModerationCursorError();
+  if (
+    !hasExactKeys(value, ["version", "event", "afterIndexKey", "from", "to"])
+    || value.version !== 1
+    || typeof value.event !== "string"
+    || value.event !== expected.event
+    || typeof value.afterIndexKey !== "string"
+    || !isPhotoIndexKey(value.event, value.afterIndexKey)
+    || !isNullableTimestamp(value.from)
+    || !isNullableTimestamp(value.to)
+    || value.from !== expected.from
+    || value.to !== expected.to
+  ) {
+    throw new InvalidModerationCursorError();
+  }
+  return {
+    version: 1,
+    event: value.event,
+    afterIndexKey: value.afterIndexKey,
+    from: value.from,
+    to: value.to,
+  };
+}
+
+function isPhotoIndexKey(event: string, key: string): boolean {
+  const prefix = `events/${event}/photo-index/v1/`;
+  const suffix = key.slice(prefix.length);
+  return key.startsWith(prefix)
+    && /^\d{13}-[A-Za-z0-9_-]+\.json$/.test(suffix);
+}
+
+function isEventPhotoKey(event: string, key: string): boolean {
+  const prefix = `${event}/`;
+  const filename = key.slice(prefix.length);
+  return key.startsWith(prefix)
+    && filename.length > 0
+    && !/[\/\\?#]/.test(filename)
+    && PHOTO_EXTENSIONS.test(filename);
+}
+
+function isStoredInstant(value: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)
+    && !Number.isNaN(Date.parse(value));
+}
+
+function isNullableTimestamp(value: unknown): value is number | null {
+  return value === null
+    || (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function base64url(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+function base64urlDecode(value: string): string {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) throw new Error("invalid base64url");
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/")
+    + "=".repeat((4 - value.length % 4) % 4);
+  const binary = atob(padded);
+  return new TextDecoder().decode(Uint8Array.from(binary, (character) => character.charCodeAt(0)));
+}

From 039719f94c79fba6ab8f0fe4360f74751e890dd2 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:36:30 +0800
Subject: [PATCH 075/105] feat: moderate photos with exact private cleanup

---
 app/api/moderation/photos/handlers.test.ts | 155 ++++++++++++++++++++
 app/api/moderation/photos/handlers.ts      | 160 +++++++++++++++++++++
 app/api/moderation/photos/rebuild/route.ts |  14 ++
 app/api/moderation/photos/route.ts         |  14 ++
 app/api/photos/handlers.test.ts            | 102 ++++++++++++-
 app/api/photos/handlers.ts                 |  67 ++++++++-
 app/api/photos/route.ts                    |  27 +---
 app/event-store.test.ts                    | 115 ++++++++++++++-
 app/event-store.ts                         |  48 ++++++-
 9 files changed, 671 insertions(+), 31 deletions(-)
 create mode 100644 app/api/moderation/photos/handlers.test.ts
 create mode 100644 app/api/moderation/photos/handlers.ts
 create mode 100644 app/api/moderation/photos/rebuild/route.ts
 create mode 100644 app/api/moderation/photos/route.ts

diff --git a/app/api/moderation/photos/handlers.test.ts b/app/api/moderation/photos/handlers.test.ts
new file mode 100644
index 0000000..180b591
--- /dev/null
+++ b/app/api/moderation/photos/handlers.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import {
+  EventStore,
+  InMemoryObjectStore,
+  type DeletePhotoResult,
+  type ModerationPhotoPage,
+  type PhotoIndexRebuildResult,
+} from "@/app/event-store";
+import { getModerationPhotos, postModerationRebuild } from "./handlers";
+
+class ModerationHandlerStore extends EventStore {
+  calls: string[] = [];
+  page: ModerationPhotoPage = { photos: [], nextCursor: null };
+  rebuild: PhotoIndexRebuildResult = {
+    complete: false,
+    scanned: 10,
+    indexed: 8,
+    checkpoint: "launch/last.jpg",
+  };
+
+  constructor() {
+    super(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+  }
+
+  override async listModerationPhotos(
+    event: string,
+    options: { cursor?: string; limit?: number; from?: number; to?: number }
+  ): Promise<ModerationPhotoPage> {
+    this.calls.push(`list:${event}:${JSON.stringify(options)}`);
+    return this.page;
+  }
+
+  override async rebuildPhotoIndex(
+    event: string,
+    options: { batchSize: number }
+  ): Promise<PhotoIndexRebuildResult> {
+    this.calls.push(`rebuild:${event}:${options.batchSize}`);
+    return this.rebuild;
+  }
+
+  override async deletePhoto(): Promise<DeletePhotoResult> {
+    throw new Error("unused");
+  }
+}
+
+function request(
+  path: string,
+  { key = "admin", method = "GET" }: { key?: string; method?: string } = {}
+) {
+  return new NextRequest(`https://app.test${path}`, {
+    method,
+    headers: { "x-booth-key": key },
+  });
+}
+
+describe("Admin moderation handlers", () => {
+  test("fails closed before store access when the Admin secret is missing or wrong", async () => {
+    for (const [adminKey, status] of [[undefined, 503], ["different", 401]] as const) {
+      const store = new ModerationHandlerStore();
+      const response = await getModerationPhotos(
+        request("/api/moderation/photos?event=launch"),
+        { store, adminKey }
+      );
+      expect(response.status).toBe(status);
+      expect(store.calls).toEqual([]);
+    }
+  });
+
+  test("strictly validates canonical Event, limit, time-zone instants, order, and cursor", async () => {
+    const invalidQueries = [
+      "event=Launch",
+      "event=launch&limit=0",
+      "event=launch&limit=101",
+      "event=launch&limit=1.5",
+      "event=launch&from=2026-07-24",
+      "event=launch&from=2026-07-24T00%3A00%3A00",
+      "event=launch&from=2026-02-30T00%3A00%3A00Z",
+      "event=launch&from=2026-07-25T00%3A00%3A00Z&to=2026-07-24T00%3A00%3A00Z",
+      "event=launch&cursor=bad",
+      "event=launch&limit=48&limit=49",
+      "event=launch&private=true",
+    ];
+    for (const query of invalidQueries) {
+      const store = new ModerationHandlerStore();
+      const response = await getModerationPhotos(
+        request(`/api/moderation/photos?${query}`),
+        { store, adminKey: "admin" }
+      );
+      expect(response.status).toBe(400);
+      expect(store.calls).toEqual([]);
+    }
+  });
+
+  test("defaults to 48, accepts bounded filters, and allowlists the no-store page response", async () => {
+    const store = new ModerationHandlerStore();
+    store.page = {
+      photos: [{
+        key: "launch/1753315200000-a.jpg",
+        url: "https://photos.example/launch/1753315200000-a.jpg",
+        uploadedAt: "2025-07-24T00:00:00.000Z",
+        capturedAt: 1753315200000,
+        source: "framed",
+        frameKey: "celebration",
+        receipt: "must-not-leak",
+      } as never],
+      nextCursor: "opaque",
+      revision: "must-not-leak",
+    } as never;
+
+    const response = await getModerationPhotos(request(
+      "/api/moderation/photos?event=launch&from=2025-07-24T00%3A00%3A00%2B08%3A00&to=2025-07-25T00%3A00%3A00Z"
+    ), { store, adminKey: "admin" });
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(store.calls).toEqual([
+      `list:launch:${JSON.stringify({
+        limit: 48,
+        from: Date.parse("2025-07-24T00:00:00+08:00"),
+        to: Date.parse("2025-07-25T00:00:00Z"),
+      })}`,
+    ]);
+    expect(await response.json()).toEqual({
+      photos: [{
+        key: "launch/1753315200000-a.jpg",
+        url: "https://photos.example/launch/1753315200000-a.jpg",
+        uploadedAt: "2025-07-24T00:00:00.000Z",
+        capturedAt: 1753315200000,
+        source: "framed",
+        frameKey: "celebration",
+      }],
+      nextCursor: "opaque",
+    });
+  });
+
+  test("runs one bounded rebuild batch and distinguishes incomplete from complete", async () => {
+    const store = new ModerationHandlerStore();
+    const incomplete = await postModerationRebuild(
+      request("/api/moderation/photos/rebuild?event=launch", { method: "POST" }),
+      { store, adminKey: "admin", rebuildBatchSize: 75 }
+    );
+    expect(incomplete.status).toBe(202);
+    expect(incomplete.headers.get("cache-control")).toBe("no-store");
+    expect(store.calls).toEqual(["rebuild:launch:75"]);
+
+    store.rebuild = { complete: true, scanned: 0, indexed: 0, checkpoint: "launch/last.jpg" };
+    const complete = await postModerationRebuild(
+      request("/api/moderation/photos/rebuild?event=launch", { method: "POST" }),
+      { store, adminKey: "admin", rebuildBatchSize: 75 }
+    );
+    expect(complete.status).toBe(200);
+    expect(await complete.json()).toEqual(store.rebuild);
+  });
+});
diff --git a/app/api/moderation/photos/handlers.ts b/app/api/moderation/photos/handlers.ts
new file mode 100644
index 0000000..365e402
--- /dev/null
+++ b/app/api/moderation/photos/handlers.ts
@@ -0,0 +1,160 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  EventStore,
+  InvalidEventSlugError,
+} from "@/app/event-store";
+import {
+  decodeModerationCursor,
+  InvalidModerationCursorError,
+} from "@/app/moderation";
+import { adminOk } from "@/app/upload-auth";
+
+export type ModerationHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+  rebuildBatchSize?: number;
+};
+
+const jsonError = (error: string, status: number) =>
+  NextResponse.json({ error }, {
+    status,
+    headers: { "Cache-Control": "no-store" },
+  });
+
+function authorize(req: NextRequest, deps: ModerationHandlerDeps): NextResponse | null {
+  if (!deps.adminKey) return jsonError("moderation disabled: no key configured", 503);
+  return adminOk(req.headers.get("x-booth-key") ?? "", deps.adminKey) === "ok"
+    ? null
+    : jsonError("unauthorized", 401);
+}
+
+function hasOnlySingleQueryKeys(
+  params: URLSearchParams,
+  allowed: readonly string[]
+): boolean {
+  return Array.from(params.keys()).every((key) => allowed.includes(key))
+    && allowed.every((key) => params.getAll(key).length <= 1);
+}
+
+function parseEvent(value: string | null): string | NextResponse {
+  try {
+    return canonicalEvent(value);
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) return jsonError(error.message, 400);
+    throw error;
+  }
+}
+
+export async function getModerationPhotos(
+  req: NextRequest,
+  deps: ModerationHandlerDeps
+): Promise<NextResponse> {
+  const authError = authorize(req, deps);
+  if (authError) return authError;
+  const params = req.nextUrl.searchParams;
+  if (!hasOnlySingleQueryKeys(params, ["event", "cursor", "limit", "from", "to"])) {
+    return jsonError("invalid moderation query", 400);
+  }
+  const event = parseEvent(params.get("event"));
+  if (event instanceof NextResponse) return event;
+  const rawLimit = params.get("limit");
+  if (rawLimit !== null && !/^(?:[1-9]|[1-9][0-9]|100)$/.test(rawLimit)) {
+    return jsonError("invalid moderation limit", 400);
+  }
+  const from = parseOptionalInstant(params.get("from"));
+  const to = parseOptionalInstant(params.get("to"));
+  if (from === undefined || to === undefined || (from !== null && to !== null && from > to)) {
+    return jsonError("invalid moderation time filter", 400);
+  }
+  const cursor = params.get("cursor");
+  if (cursor !== null) {
+    try {
+      decodeModerationCursor(cursor, { event, from, to });
+    } catch (error) {
+      if (error instanceof InvalidModerationCursorError) {
+        return jsonError(error.message, 400);
+      }
+      throw error;
+    }
+  }
+
+  const page = await deps.store.listModerationPhotos(event, {
+    limit: rawLimit === null ? 48 : Number(rawLimit),
+    ...(cursor !== null ? { cursor } : {}),
+    ...(from !== null ? { from } : {}),
+    ...(to !== null ? { to } : {}),
+  });
+  return NextResponse.json({
+    photos: page.photos.map((photo) => ({
+      key: photo.key,
+      url: photo.url,
+      uploadedAt: photo.uploadedAt,
+      capturedAt: photo.capturedAt,
+      ...(photo.source ? { source: photo.source } : {}),
+      ...(photo.frameKey ? { frameKey: photo.frameKey } : {}),
+    })),
+    nextCursor: page.nextCursor,
+  }, { headers: { "Cache-Control": "no-store" } });
+}
+
+export async function postModerationRebuild(
+  req: NextRequest,
+  deps: ModerationHandlerDeps
+): Promise<NextResponse> {
+  const authError = authorize(req, deps);
+  if (authError) return authError;
+  const params = req.nextUrl.searchParams;
+  if (!hasOnlySingleQueryKeys(params, ["event"])) {
+    return jsonError("invalid moderation rebuild query", 400);
+  }
+  const event = parseEvent(params.get("event"));
+  if (event instanceof NextResponse) return event;
+  const batchSize = deps.rebuildBatchSize ?? 100;
+  if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 1_000) {
+    throw new TypeError("invalid moderation rebuild batch size");
+  }
+  const result = await deps.store.rebuildPhotoIndex(event, { batchSize });
+  return NextResponse.json({
+    complete: result.complete,
+    scanned: result.scanned,
+    indexed: result.indexed,
+    checkpoint: result.checkpoint,
+  }, {
+    status: result.complete ? 200 : 202,
+    headers: { "Cache-Control": "no-store" },
+  });
+}
+
+function parseOptionalInstant(value: string | null): number | null | undefined {
+  if (value === null) return null;
+  const match = value.match(
+    /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|([+-])(\d{2}):(\d{2}))$/
+  );
+  if (!match) return undefined;
+  const [, year, month, day, hour, minute, second, fraction = "", zone, sign, zoneHour, zoneMinute] = match;
+  const offsetHour = zone === "Z" ? 0 : Number(zoneHour);
+  const offsetMinute = zone === "Z" ? 0 : Number(zoneMinute);
+  if (offsetHour > 14 || offsetMinute > 59 || (offsetHour === 14 && offsetMinute !== 0)) {
+    return undefined;
+  }
+  const parsed = Date.parse(value);
+  if (!Number.isSafeInteger(parsed)) return undefined;
+  const offset = zone === "Z"
+    ? 0
+    : (sign === "+" ? 1 : -1) * (offsetHour * 60 + offsetMinute);
+  const local = new Date(parsed + offset * 60_000);
+  const milliseconds = Number(fraction.padEnd(3, "0"));
+  if (
+    local.getUTCFullYear() !== Number(year)
+    || local.getUTCMonth() + 1 !== Number(month)
+    || local.getUTCDate() !== Number(day)
+    || local.getUTCHours() !== Number(hour)
+    || local.getUTCMinutes() !== Number(minute)
+    || local.getUTCSeconds() !== Number(second)
+    || local.getUTCMilliseconds() !== milliseconds
+  ) {
+    return undefined;
+  }
+  return parsed;
+}
diff --git a/app/api/moderation/photos/rebuild/route.ts b/app/api/moderation/photos/rebuild/route.ts
new file mode 100644
index 0000000..ec295f2
--- /dev/null
+++ b/app/api/moderation/photos/rebuild/route.ts
@@ -0,0 +1,14 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { postModerationRebuild } from "../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return postModerationRebuild(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/moderation/photos/route.ts b/app/api/moderation/photos/route.ts
new file mode 100644
index 0000000..2b45226
--- /dev/null
+++ b/app/api/moderation/photos/route.ts
@@ -0,0 +1,14 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { getModerationPhotos } from "./handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return getModerationPhotos(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/photos/handlers.test.ts b/app/api/photos/handlers.test.ts
index 9573569..2d20f34 100644
--- a/app/api/photos/handlers.test.ts
+++ b/app/api/photos/handlers.test.ts
@@ -1,12 +1,39 @@
 import { describe, expect, test } from "bun:test";
 import { NextRequest } from "next/server";
-import { EventStore, InMemoryObjectStore } from "@/app/event-store";
-import { getPhotos } from "./handlers";
+import {
+  EventStore,
+  InMemoryObjectStore,
+  photoIndexKey,
+  photoReceiptKey,
+  type DeletePhotoResult,
+} from "@/app/event-store";
+import { deletePhoto, getPhotos } from "./handlers";
 
 function request(query = "event=launch") {
   return new NextRequest(`https://app.test/api/photos?${query}`);
 }
 
+class DeleteHandlerStore extends EventStore {
+  calls: Array<{ event: string; key: string }> = [];
+  result: DeletePhotoResult = { deleted: false };
+
+  constructor() {
+    super(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+  }
+
+  override async deletePhoto(event: string, key: string): Promise<DeletePhotoResult> {
+    this.calls.push({ event, key });
+    return this.result;
+  }
+}
+
+function deleteRequest(query: string, key = "admin") {
+  return new NextRequest(`https://app.test/api/photos?${query}`, {
+    method: "DELETE",
+    headers: { "x-booth-key": key },
+  });
+}
+
 describe("photos handler", () => {
   test("keeps the after/cursor response contract while reading the private incremental feed", async () => {
     const store = new EventStore(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
@@ -88,4 +115,75 @@ describe("photos handler", () => {
     expect(body.photos).toEqual([]);
     expect(body.cursor).toStartWith("pf1.");
   });
+
+  test("DELETE fails closed before validation or store access", async () => {
+    for (const [adminKey, status] of [[undefined, 503], ["different", 401]] as const) {
+      const store = new DeleteHandlerStore();
+      const response = await deletePhoto(
+        deleteRequest("event=Launch&key=fragment.jpg"),
+        { store, adminKey }
+      );
+      expect(response.status).toBe(status);
+      expect(store.calls).toEqual([]);
+    }
+  });
+
+  test("DELETE rejects aliases, missing keys, duplicates, and unknown query fields", async () => {
+    for (const query of [
+      "event=Launch&key=launch%2F1753315200000-a.jpg",
+      "event=launch",
+      "event=launch&key=a&key=b",
+      "event=launch&key=a&prefix=true",
+    ]) {
+      const store = new DeleteHandlerStore();
+      const response = await deletePhoto(deleteRequest(query), { store, adminKey: "admin" });
+      expect(response.status).toBe(400);
+      expect(store.calls).toEqual([]);
+    }
+  });
+
+  test("DELETE preserves 404 and reports only additive cleanupPending", async () => {
+    const store = new DeleteHandlerStore();
+    const missing = await deletePhoto(
+      deleteRequest("event=launch&key=launch%2F1753315200000-a.jpg"),
+      { store, adminKey: "admin" }
+    );
+    expect(missing.status).toBe(404);
+
+    store.result = {
+      deleted: true,
+      cleanup: { index: "failed", receipt: "deleted" },
+    };
+    const response = await deletePhoto(
+      deleteRequest("event=launch&key=launch%2F1753315200000-a.jpg"),
+      { store, adminKey: "admin" }
+    );
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(await response.json()).toEqual({
+      deleted: true,
+      key: "launch/1753315200000-a.jpg",
+      cleanupPending: true,
+    });
+  });
+
+  test("DELETE exact cleanup success never exposes private derived key names", async () => {
+    const photos = new InMemoryObjectStore();
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(photos, state, "https://photos.example");
+    const uploaded = await store.putPhoto("launch", new Uint8Array([1]).buffer, {
+      upload: { captureId: "018f0000-0000-4000-8000-000000000204", capturedAt: 1753315200000 },
+    });
+    expect(state.has(photoReceiptKey("launch", uploaded.key))).toBe(true);
+    expect(state.has(photoIndexKey("launch", uploaded.key, 1753315200000))).toBe(true);
+
+    const response = await deletePhoto(
+      deleteRequest(`event=launch&key=${encodeURIComponent(uploaded.key)}`),
+      { store, adminKey: "admin" }
+    );
+    const body = await response.json() as Record<string, unknown>;
+    expect(body).toEqual({ deleted: true, key: uploaded.key, cleanupPending: false });
+    expect(JSON.stringify(body)).not.toContain("photo-index");
+    expect(JSON.stringify(body)).not.toContain("photo-metadata");
+  });
 });
diff --git a/app/api/photos/handlers.ts b/app/api/photos/handlers.ts
index 946d669..05838ad 100644
--- a/app/api/photos/handlers.ts
+++ b/app/api/photos/handlers.ts
@@ -5,8 +5,9 @@ import {
   InvalidEventSlugError,
   InvalidPhotoCursorError,
 } from "@/app/event-store";
+import { adminOk } from "@/app/upload-auth";
 
-export type PhotoHandlerDeps = { store: EventStore };
+export type PhotoHandlerDeps = { store: EventStore; adminKey?: string };
 
 export async function getPhotos(req: NextRequest, deps: PhotoHandlerDeps): Promise<NextResponse> {
   let event: string;
@@ -18,7 +19,9 @@ export async function getPhotos(req: NextRequest, deps: PhotoHandlerDeps): Promi
   }
   const after = req.nextUrl.searchParams.get("after") ?? req.nextUrl.searchParams.get("cursor");
   try {
-    return NextResponse.json(await deps.store.listPhotos(event, after));
+    return NextResponse.json(await deps.store.listPhotos(event, after), {
+      headers: { "Cache-Control": "no-store" },
+    });
   } catch (error) {
     if (error instanceof InvalidPhotoCursorError) {
       return NextResponse.json({ error: error.message }, { status: 400 });
@@ -26,3 +29,63 @@ export async function getPhotos(req: NextRequest, deps: PhotoHandlerDeps): Promi
     throw error;
   }
 }
+
+export async function deletePhoto(
+  req: NextRequest,
+  deps: PhotoHandlerDeps
+): Promise<NextResponse> {
+  if (!deps.adminKey) {
+    return NextResponse.json(
+      { error: "deletion disabled: no key configured" },
+      { status: 503, headers: { "Cache-Control": "no-store" } }
+    );
+  }
+  if (adminOk(req.headers.get("x-booth-key") ?? "", deps.adminKey) !== "ok") {
+    return NextResponse.json(
+      { error: "unauthorized" },
+      { status: 401, headers: { "Cache-Control": "no-store" } }
+    );
+  }
+  const params = req.nextUrl.searchParams;
+  if (
+    Array.from(params.keys()).some((key) => key !== "event" && key !== "key")
+    || params.getAll("event").length !== 1
+    || params.getAll("key").length !== 1
+  ) {
+    return NextResponse.json(
+      { error: "invalid photo deletion query" },
+      { status: 400, headers: { "Cache-Control": "no-store" } }
+    );
+  }
+  let event: string;
+  try {
+    event = canonicalEvent(params.get("event"));
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) {
+      return NextResponse.json(
+        { error: error.message },
+        { status: 400, headers: { "Cache-Control": "no-store" } }
+      );
+    }
+    throw error;
+  }
+  const key = params.get("key");
+  if (!key) {
+    return NextResponse.json(
+      { error: "key is required" },
+      { status: 400, headers: { "Cache-Control": "no-store" } }
+    );
+  }
+  const result = await deps.store.deletePhoto(event, key);
+  if (!result.deleted) {
+    return NextResponse.json(
+      { error: "photo not found" },
+      { status: 404, headers: { "Cache-Control": "no-store" } }
+    );
+  }
+  return NextResponse.json({
+    deleted: true,
+    key,
+    cleanupPending: result.cleanup.index === "failed" || result.cleanup.receipt === "failed",
+  }, { headers: { "Cache-Control": "no-store" } });
+}
diff --git a/app/api/photos/route.ts b/app/api/photos/route.ts
index fedee8a..0ea6fbf 100644
--- a/app/api/photos/route.ts
+++ b/app/api/photos/route.ts
@@ -1,8 +1,7 @@
 import { getCloudflareContext } from "@opennextjs/cloudflare";
-import { NextRequest, NextResponse } from "next/server";
-import { canonicalEvent, EventStore, InvalidEventSlugError } from "@/app/event-store";
-import { adminOk } from "@/app/upload-auth";
-import { getPhotos } from "./handlers";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { deletePhoto, getPhotos } from "./handlers";
 
 // no caching by Next — the gallery polls this for fresh photos
 export const dynamic = "force-dynamic";
@@ -14,20 +13,8 @@ export async function GET(req: NextRequest) {
 
 export async function DELETE(req: NextRequest) {
   const { env } = getCloudflareContext();
-  const auth = adminOk(req.headers.get("x-booth-key") ?? "", env.BOOTH_UPLOAD_KEY);
-  if (auth === "disabled") return NextResponse.json({ error: "deletion disabled: no key configured" }, { status: 503 });
-  if (auth === "unauthorized") return NextResponse.json({ error: "unauthorized" }, { status: 401 });
-
-  let event: string;
-  try {
-    event = canonicalEvent(req.nextUrl.searchParams.get("event"));
-  } catch (error) {
-    if (error instanceof InvalidEventSlugError) return NextResponse.json({ error: error.message }, { status: 400 });
-    throw error;
-  }
-  const key = req.nextUrl.searchParams.get("key");
-  if (!key) return NextResponse.json({ error: "key is required" }, { status: 400 });
-  const deleted = await EventStore.fromEnv(env).deletePhoto(event, key);
-  if (!deleted) return NextResponse.json({ error: "photo not found" }, { status: 404 });
-  return NextResponse.json({ deleted: true, key });
+  return deletePhoto(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
 }
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index f31f141..76a446f 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -107,6 +107,29 @@ class CrashBeforeCompleteMarkerStore extends InMemoryObjectStore {
   }
 }
 
+class RecordingDeleteStore extends InMemoryObjectStore {
+  readonly gets: string[] = [];
+  readonly deletes: string[] = [];
+  readonly lists: ListOptions[] = [];
+  readonly failDeletes = new Set<string>();
+
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    this.gets.push(key);
+    return super.get(key);
+  }
+
+  override async delete(key: string): Promise<void> {
+    this.deletes.push(key);
+    if (this.failDeletes.has(key)) throw new Error(`simulated delete failure for ${key}`);
+    return super.delete(key);
+  }
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    this.lists.push({ ...options });
+    return super.list(options);
+  }
+}
+
 class GuardedPhotoListStore extends InMemoryObjectStore {
   rejectPhotoLists = false;
 
@@ -1860,9 +1883,12 @@ describe("EventStore", () => {
       "launch/notes.txt": "keep",
     });
     const store = new EventStore(photos, new InMemoryObjectStore(), "https://photos.example");
-    expect(await store.deletePhoto("launch", "other/0000000001000-b.jpg")).toBe(false);
-    expect(await store.deletePhoto("launch", "launch/notes.txt")).toBe(false);
-    expect(await store.deletePhoto("launch", "launch/0000000001000-a.jpg")).toBe(true);
+    expect(await store.deletePhoto("launch", "other/0000000001000-b.jpg")).toEqual({ deleted: false });
+    expect(await store.deletePhoto("launch", "launch/notes.txt")).toEqual({ deleted: false });
+    expect(await store.deletePhoto("launch", "launch/0000000001000-a.jpg")).toEqual({
+      deleted: true,
+      cleanup: { index: "missing", receipt: "missing" },
+    });
     expect(photos.has("launch/0000000001000-a.jpg")).toBe(false);
     expect(photos.has("other/0000000001000-b.jpg")).toBe(true);
   });
@@ -1898,6 +1924,89 @@ describe("EventStore", () => {
     expect(photos.reads).toEqual(["launch/0000000001000-missing.jpg"]);
   });
 
+  test("deletes public bytes first then only the exact receipt-derived private records", async () => {
+    const photoKey = "launch/1753315200000-a.jpg";
+    const adjacentKey = "launch/1753315200001-b.jpg";
+    const photos = new RecordingDeleteStore({
+      [photoKey]: "a",
+      [adjacentKey]: "b",
+      "other/1753315200000-a.jpg": "other",
+    });
+    const state = new RecordingDeleteStore();
+    const receiptKey = photoReceiptKey("launch", photoKey);
+    const indexKey = photoIndexKey("launch", photoKey, 1_753_315_199_999);
+    const adjacentReceipt = photoReceiptKey("launch", adjacentKey);
+    const adjacentIndex = photoIndexKey("launch", adjacentKey, 1_753_315_200_001);
+    state.set(receiptKey, JSON.stringify({
+      version: 1,
+      key: photoKey,
+      uploadedAt: "2025-07-24T00:00:00.000Z",
+      capturedAt: 1_753_315_199_999,
+    }));
+    state.set(indexKey, "index");
+    state.set(adjacentReceipt, "adjacent receipt");
+    state.set(adjacentIndex, "adjacent index");
+
+    const result = await new EventStore(photos, state, "https://photos.example")
+      .deletePhoto("launch", photoKey);
+
+    expect(result).toEqual({
+      deleted: true,
+      cleanup: { index: "deleted", receipt: "deleted" },
+    });
+    expect(photos.deletes).toEqual([photoKey]);
+    expect(state.deletes).toEqual([indexKey, receiptKey]);
+    expect(state.lists).toEqual([]);
+    expect(photos.has(adjacentKey)).toBe(true);
+    expect(photos.has("other/1753315200000-a.jpg")).toBe(true);
+    expect(state.has(adjacentReceipt)).toBe(true);
+    expect(state.has(adjacentIndex)).toBe(true);
+  });
+
+  test("uses exact safe fallback time and reports independent cleanup failures after deletion", async () => {
+    const key = "launch/1753315200000-a.jpg";
+    const photos = new RecordingDeleteStore();
+    photos.set(key, "a", new Date("2025-07-25T00:00:00.000Z"));
+    const state = new RecordingDeleteStore({
+      [photoReceiptKey("launch", key)]: "corrupt",
+      [photoIndexKey("launch", key, 1_753_315_200_000)]: "index",
+    });
+    const receiptKey = photoReceiptKey("launch", key);
+    const indexKey = photoIndexKey("launch", key, 1_753_315_200_000);
+    state.failDeletes.add(indexKey);
+    state.failDeletes.add(receiptKey);
+
+    const result = await new EventStore(photos, state, "https://photos.example")
+      .deletePhoto("launch", key);
+
+    expect(result).toEqual({
+      deleted: true,
+      cleanup: { index: "failed", receipt: "failed" },
+    });
+    expect(photos.has(key)).toBe(false);
+    expect(state.deletes).toEqual([indexKey, receiptKey]);
+  });
+
+  test("does no private cleanup when public deletion fails", async () => {
+    const key = "launch/1753315200000-a.jpg";
+    const photos = new RecordingDeleteStore({ [key]: "a" });
+    photos.failDeletes.add(key);
+    const state = new RecordingDeleteStore({
+      [photoReceiptKey("launch", key)]: JSON.stringify({
+        version: 1,
+        key,
+        uploadedAt: "2025-07-24T00:00:00.000Z",
+        capturedAt: 1_753_315_200_000,
+      }),
+      [photoIndexKey("launch", key, 1_753_315_200_000)]: "index",
+    });
+
+    await expect(new EventStore(photos, state, "https://photos.example")
+      .deletePhoto("launch", key)).rejects.toThrow("delete failure");
+    expect(state.deletes).toEqual([]);
+    expect(state.has(photoReceiptKey("launch", key))).toBe(true);
+  });
+
   test("pages the private inverse-time index newest-first across bounded storage pages", async () => {
     const photos = new InMemoryObjectStore();
     const state = new CappedListStore(1);
diff --git a/app/event-store.ts b/app/event-store.ts
index ec9b6f2..203e3f8 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -297,6 +297,15 @@ export type PutPhotoResult = {
   receiptStored: boolean;
   indexStored: boolean;
 };
+export type DeletePhotoResult =
+  | { deleted: false }
+  | {
+      deleted: true;
+      cleanup: {
+        index: "deleted" | "missing" | "failed";
+        receipt: "deleted" | "missing" | "failed";
+      };
+    };
 export type ConfigMutationResult = {
   config: EventConfig;
   revision: ConfigRevision;
@@ -1510,12 +1519,43 @@ export class EventStore {
     };
   }
 
-  async deletePhoto(event: string, key: string): Promise<boolean> {
-    if (!isPhotoKey(event, key)) return false;
+  async deletePhoto(event: string, key: string): Promise<DeletePhotoResult> {
+    const canonical = canonicalEvent(event);
+    if (!isPhotoKey(canonical, key)) return { deleted: false };
     const existing = await this.photos.get(key);
-    if (!existing) return false;
+    if (!existing) return { deleted: false };
+    const receiptKey = photoReceiptKey(canonical, key);
+    const receipt = await this.state.get(receiptKey);
+    let sortTime = capturedAtFromLegacyPhotoKey(canonical, key) ?? existing.uploaded.getTime();
+    if (receipt) {
+      try {
+        sortTime = parsePhotoReceipt(await receipt.json<unknown>(), key).capturedAt;
+      } catch {
+        // A corrupt derived record cannot block exact public deletion. Its one
+        // exact receipt is still cleaned below using the safe public fallback.
+      }
+    }
     await this.photos.delete(key);
-    return true;
+    const index = await this.deleteDerivedRecord(
+      photoIndexKey(canonical, key, sortTime)
+    );
+    const receiptCleanup = await this.deleteDerivedRecord(receiptKey);
+    return {
+      deleted: true,
+      cleanup: { index, receipt: receiptCleanup },
+    };
+  }
+
+  private async deleteDerivedRecord(
+    key: string
+  ): Promise<"deleted" | "missing" | "failed"> {
+    try {
+      if (!await this.state.get(key)) return "missing";
+      await this.state.delete(key);
+      return "deleted";
+    } catch {
+      return "failed";
+    }
   }
 
   async readHealthState<T>(): Promise<T | null> {

From 5a0ab30276cb35a2109d7c0f572e921ada4bad73 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:37:59 +0800
Subject: [PATCH 076/105] fix: reject impossible moderation timestamps

---
 app/moderation.test.ts | 1 +
 app/moderation.ts      | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/app/moderation.test.ts b/app/moderation.test.ts
index 6221b86..9984a5b 100644
--- a/app/moderation.test.ts
+++ b/app/moderation.test.ts
@@ -80,6 +80,7 @@ describe("private moderation photo records", () => {
       { ...valid, version: 2 },
       { ...valid, key: "other/1753315200000-a.jpg" },
       { ...valid, uploadedAt: "not-an-instant" },
+      { ...valid, uploadedAt: "2025-02-30T00:00:00.000Z" },
       { ...valid, capturedAt: 1.5 },
       { ...valid, frameKey: 42 },
       { ...valid, configRevisionId: 42 },
diff --git a/app/moderation.ts b/app/moderation.ts
index b4d6a75..4949d77 100644
--- a/app/moderation.ts
+++ b/app/moderation.ts
@@ -135,8 +135,9 @@ function isEventPhotoKey(event: string, key: string): boolean {
 }
 
 function isStoredInstant(value: string): boolean {
-  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)
-    && !Number.isNaN(Date.parse(value));
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) return false;
+  const parsed = Date.parse(value);
+  return !Number.isNaN(parsed) && new Date(parsed).toISOString() === value;
 }
 
 function isNullableTimestamp(value: unknown): value is number | null {

From bc5919db82f70ee17f08db899c98e4944cba1f17 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:03:36 +0800
Subject: [PATCH 077/105] feat: store reusable event presets

---
 app/event-config.test.ts |  13 +++
 app/event-config.ts      |   6 +-
 app/event-preset.test.ts |  91 +++++++++++++++++++++
 app/event-preset.ts      | 109 +++++++++++++++++++++++++
 app/event-store.test.ts  | 132 +++++++++++++++++++++++++++++++
 app/event-store.ts       | 167 +++++++++++++++++++++++++++++++++++++++
 6 files changed, 515 insertions(+), 3 deletions(-)
 create mode 100644 app/event-preset.test.ts
 create mode 100644 app/event-preset.ts

diff --git a/app/event-config.test.ts b/app/event-config.test.ts
index c69d800..97a7e1b 100644
--- a/app/event-config.test.ts
+++ b/app/event-config.test.ts
@@ -3,6 +3,7 @@ import {
   isRevisionId,
   parseConfigRevision,
   parseEventConfig,
+  parseEventExperience,
   projectEventExperience,
   projectPublicConfig,
 } from "./event-config";
@@ -82,6 +83,18 @@ describe("event config schema", () => {
     expect(JSON.stringify(projected)).not.toContain("currentRevisionId");
   });
 
+  test("exports the same explicit safe experience parser used by presets", () => {
+    expect(parseEventExperience({
+      frames: ["square"],
+      boothKeyHash: "ignored",
+      capture: { reviewEnabled: true, secret: "ignored" },
+    })).toEqual({
+      frames: ["square"],
+      capture: { reviewEnabled: true },
+    });
+    expect(parseEventExperience({ frames: ["bad/frame"] })).toBeNull();
+  });
+
   test("revision parsing rejects credentials inside experience", () => {
     const base = {
       version: 1,
diff --git a/app/event-config.ts b/app/event-config.ts
index 085d831..d7ae100 100644
--- a/app/event-config.ts
+++ b/app/event-config.ts
@@ -43,7 +43,7 @@ export type PublicEventConfig = Omit<EventExperience, "frames"> & {
 export const isRevisionId = (value: unknown): value is string =>
   typeof value === "string" && UUID.test(value);
 
-function parseExperience(value: unknown): EventExperience | null {
+export function parseEventExperience(value: unknown): EventExperience | null {
   if (!value || typeof value !== "object") return null;
   const v = value as Record<string, unknown>;
   if (!Array.isArray(v.frames) || !v.frames.every((x) => typeof x === "string" && TOKEN.test(x))) return null;
@@ -86,7 +86,7 @@ export function parseEventConfig(value: unknown): EventConfig | null {
   if (!value || typeof value !== "object") return null;
   const v = value as Record<string, unknown>;
   if (v.version !== undefined && v.version !== EVENT_CONFIG_VERSION) return null;
-  const experience = parseExperience({ ...v, frames: v.frames ?? [] });
+  const experience = parseEventExperience({ ...v, frames: v.frames ?? [] });
   if (!experience) return null;
   if (v.boothKeyHash !== undefined && typeof v.boothKeyHash !== "string") return null;
   if (v.currentRevisionId !== undefined && !isRevisionId(v.currentRevisionId)) return null;
@@ -106,7 +106,7 @@ export function parseConfigRevision(value: unknown): ConfigRevision | null {
   if (v.boothKeyHash !== undefined) return null;
   if (v.sourceRevisionId !== undefined && !isRevisionId(v.sourceRevisionId)) return null;
   if (v.sourcePresetId !== undefined && (typeof v.sourcePresetId !== "string" || !TOKEN.test(v.sourcePresetId))) return null;
-  const config = parseExperience(v.config);
+  const config = parseEventExperience(v.config);
   if (!config || (v.config as Record<string, unknown>).boothKeyHash !== undefined) return null;
   return {
     version: EVENT_CONFIG_VERSION,
diff --git a/app/event-preset.test.ts b/app/event-preset.test.ts
new file mode 100644
index 0000000..abd785d
--- /dev/null
+++ b/app/event-preset.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import type { EventExperience } from "./event-config";
+import {
+  isPresetId,
+  parseEventPreset,
+  serializePresetExperience,
+} from "./event-preset";
+
+const completeExperience: EventExperience = {
+  frames: ["square", "strip"],
+  locales: ["en", "zh-SG", "ar"],
+  defaultLocale: "en",
+  timeZone: "Asia/Singapore",
+  capture: {
+    reviewEnabled: true,
+    autoAcceptSeconds: 5,
+    countdownAudioDefault: false,
+  },
+  gallery: {
+    title: "Launch Night",
+    accentColor: "#c45f39",
+  },
+};
+
+const storedPreset = {
+  version: 1 as const,
+  id: "launch-night",
+  label: "Launch Night",
+  createdAt: "2026-07-24T00:00:00.000Z",
+  updatedAt: "2026-07-24T01:00:00.000Z",
+  config: completeExperience,
+};
+
+describe("Event presets", () => {
+  test("round-trips the complete safe experience using fresh nested values", () => {
+    const parsed = parseEventPreset(storedPreset);
+    expect(parsed).toEqual(storedPreset);
+    expect(parsed?.config).not.toBe(completeExperience);
+    expect(parsed?.config.frames).not.toBe(completeExperience.frames);
+    expect(parsed?.config.capture).not.toBe(completeExperience.capture);
+    expect(parsed?.config.gallery).not.toBe(completeExperience.gallery);
+  });
+
+  test("explicit serialization omits Event, credential, revision, and operational data", () => {
+    const unsafe = {
+      ...completeExperience,
+      event: "secret-event",
+      boothKey: "plaintext",
+      boothKeyHash: "hash",
+      currentRevisionId: "018f0000-0000-7000-8000-000000000001",
+      health: { status: "up" },
+      booths: [{ id: "device" }],
+      rehearsal: { id: "run" },
+      photos: ["launch/photo.jpg"],
+      capture: { ...completeExperience.capture, credential: "leak" },
+      gallery: { ...completeExperience.gallery, private: "leak" },
+    } as EventExperience;
+
+    expect(serializePresetExperience(unsafe)).toEqual(completeExperience);
+    const json = JSON.stringify(serializePresetExperience(unsafe));
+    for (const forbidden of [
+      "event",
+      "boothKey",
+      "boothKeyHash",
+      "currentRevisionId",
+      "health",
+      "booths",
+      "rehearsal",
+      "photos",
+      "credential",
+      "private",
+    ]) {
+      expect(json).not.toContain(forbidden);
+    }
+  });
+
+  test("rejects unsafe identities, labels, versions, fields, and malformed experience", () => {
+    expect(isPresetId("a")).toBeTrue();
+    expect(isPresetId("launch-night-2")).toBeTrue();
+    for (const id of ["", "-launch", "launch-", "Launch", "../launch", "a".repeat(65)]) {
+      expect(isPresetId(id)).toBeFalse();
+    }
+
+    expect(parseEventPreset({ ...storedPreset, version: 2 })).toBeNull();
+    expect(parseEventPreset({ ...storedPreset, id: "../launch" })).toBeNull();
+    expect(parseEventPreset({ ...storedPreset, label: "   " })).toBeNull();
+    expect(parseEventPreset({ ...storedPreset, label: "x".repeat(81) })).toBeNull();
+    expect(parseEventPreset({ ...storedPreset, boothKeyHash: "leak" })).toBeNull();
+    expect(parseEventPreset({ ...storedPreset, config: { frames: ["bad/frame"] } })).toBeNull();
+  });
+});
diff --git a/app/event-preset.ts b/app/event-preset.ts
new file mode 100644
index 0000000..f47f1fc
--- /dev/null
+++ b/app/event-preset.ts
@@ -0,0 +1,109 @@
+import {
+  parseEventExperience,
+  type EventExperience,
+} from "./event-config";
+
+export const EVENT_PRESET_VERSION = 1 as const;
+const PRESET_FIELDS = new Set([
+  "version",
+  "id",
+  "label",
+  "createdAt",
+  "updatedAt",
+  "config",
+]);
+
+export type EventPreset = {
+  version: typeof EVENT_PRESET_VERSION;
+  id: string;
+  label: string;
+  createdAt: string;
+  updatedAt: string;
+  config: EventExperience;
+};
+
+export const isPresetId = (value: unknown): value is string =>
+  typeof value === "string"
+  && /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(value);
+
+function isIsoTimestamp(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+function isPresetLabel(value: unknown): value is string {
+  return typeof value === "string"
+    && value.trim().length > 0
+    && [...value].length <= 80;
+}
+
+export function serializePresetExperience(
+  experience: EventExperience,
+): EventExperience {
+  const parsed = parseEventExperience(experience);
+  if (!parsed) throw new TypeError("invalid preset experience");
+  return {
+    frames: [...parsed.frames],
+    ...(parsed.locales ? { locales: [...parsed.locales] } : {}),
+    ...(parsed.defaultLocale !== undefined ? { defaultLocale: parsed.defaultLocale } : {}),
+    ...(parsed.timeZone !== undefined ? { timeZone: parsed.timeZone } : {}),
+    ...(parsed.capture
+      ? {
+          capture: {
+            ...(parsed.capture.reviewEnabled !== undefined
+              ? { reviewEnabled: parsed.capture.reviewEnabled }
+              : {}),
+            ...(parsed.capture.autoAcceptSeconds !== undefined
+              ? { autoAcceptSeconds: parsed.capture.autoAcceptSeconds }
+              : {}),
+            ...(parsed.capture.countdownAudioDefault !== undefined
+              ? { countdownAudioDefault: parsed.capture.countdownAudioDefault }
+              : {}),
+          },
+        }
+      : {}),
+    ...(parsed.gallery
+      ? {
+          gallery: {
+            ...(parsed.gallery.title !== undefined ? { title: parsed.gallery.title } : {}),
+            ...(parsed.gallery.accentColor !== undefined
+              ? { accentColor: parsed.gallery.accentColor }
+              : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+export function parseEventPreset(value: unknown): EventPreset | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).some((key) => !PRESET_FIELDS.has(key))
+    || Object.keys(record).length !== PRESET_FIELDS.size
+    || record.version !== EVENT_PRESET_VERSION
+    || !isPresetId(record.id)
+    || !isPresetLabel(record.label)
+    || !isIsoTimestamp(record.createdAt)
+    || !isIsoTimestamp(record.updatedAt)
+    || Date.parse(record.updatedAt) < Date.parse(record.createdAt)
+  ) {
+    return null;
+  }
+  const config = parseEventExperience(record.config);
+  if (!config) return null;
+  return {
+    version: EVENT_PRESET_VERSION,
+    id: record.id,
+    label: record.label,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    config: serializePresetExperience(config),
+  };
+}
+
+export function validatePresetLabel(value: unknown): string {
+  if (!isPresetLabel(value)) throw new TypeError("preset label must contain 1 to 80 characters");
+  return value;
+}
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 76a446f..5db70e3 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -11,6 +11,8 @@ import {
   InvalidPhotoIndexRebuildStateError,
   InvalidPhotoCursorError,
   InvalidStoredConfigRevisionError,
+  InvalidStoredEventPresetError,
+  PresetConflictError,
   eventConfigKey,
   eventConfigMutationKey,
   eventConfigRevisionKey,
@@ -25,6 +27,8 @@ import {
   photoIndexRebuildCheckpointKey,
   photoIndexRebuildCompleteKey,
   photoReceiptKey,
+  eventPresetKey,
+  eventPresetPrefix,
   type ListOptions,
   type ListResult,
   type StoredObjectBody,
@@ -2516,4 +2520,132 @@ describe("EventStore", () => {
       }).toThrow("private STATE unavailable");
     });
   });
+
+  describe("Event presets", () => {
+    const experience = {
+      frames: ["square", "strip"],
+      locales: ["en", "zh-SG", "ar"],
+      defaultLocale: "en",
+      timeZone: "Asia/Singapore",
+      capture: {
+        reviewEnabled: true,
+        autoAcceptSeconds: 5,
+        countdownAudioDefault: false,
+      },
+      gallery: { title: "Launch Night", accentColor: "#c45f39" },
+    };
+
+    test("creates and updates one exact private preset with server timestamps", async () => {
+      let now = new Date("2026-07-24T00:00:00.000Z");
+      const photos = new InMemoryObjectStore();
+      const state = new InMemoryObjectStore();
+      const store = new EventStore(photos, state, "https://photos.example", () => now);
+
+      const created = await store.putEventPreset("launch", {
+        label: "Launch",
+        config: experience,
+        expectedUpdatedAt: null,
+      });
+      expect(created).toEqual({
+        version: 1,
+        id: "launch",
+        label: "Launch",
+        createdAt: "2026-07-24T00:00:00.000Z",
+        updatedAt: "2026-07-24T00:00:00.000Z",
+        config: experience,
+      });
+      expect(state.has(eventPresetKey("launch"))).toBeTrue();
+      expect((await state.list()).objects.map((object) => object.key)).toEqual([
+        "presets/launch.json",
+      ]);
+      expect((await photos.list()).objects).toEqual([]);
+
+      now = new Date("2026-07-24T01:00:00.000Z");
+      const updated = await store.putEventPreset("launch", {
+        label: "Launch updated",
+        config: { ...experience, frames: ["strip"] },
+        expectedUpdatedAt: created.updatedAt,
+      });
+      expect(updated.createdAt).toBe(created.createdAt);
+      expect(updated.updatedAt).toBe(now.toISOString());
+      expect(updated.config.frames).toEqual(["strip"]);
+      expect(await store.getEventPreset("launch")).toEqual(updated);
+    });
+
+    test("enforces create-only and exact observed update conflicts", async () => {
+      const state = new InMemoryObjectStore();
+      const store = new EventStore(
+        new InMemoryObjectStore(),
+        state,
+        "https://photos.example",
+        () => new Date("2026-07-24T00:00:00.000Z"),
+      );
+      const created = await store.putEventPreset("launch", {
+        label: "Launch",
+        config: experience,
+        expectedUpdatedAt: null,
+      });
+
+      await expect(store.putEventPreset("launch", {
+        label: "Duplicate",
+        config: experience,
+        expectedUpdatedAt: null,
+      })).rejects.toBeInstanceOf(PresetConflictError);
+      await expect(store.putEventPreset("launch", {
+        label: "Stale",
+        config: experience,
+        expectedUpdatedAt: "2026-07-23T00:00:00.000Z",
+      })).rejects.toBeInstanceOf(PresetConflictError);
+
+      const exactObject = await state.get(eventPresetKey("launch"));
+      const won = await state.compareAndSwap(
+        eventPresetKey("launch"),
+        exactObject!.etag,
+        JSON.stringify({ ...created, label: "Concurrent", updatedAt: "2026-07-24T00:00:01.000Z" }),
+      );
+      expect(won).toBeTrue();
+      await expect(store.putEventPreset("launch", {
+        label: "Lost race",
+        config: experience,
+        expectedUpdatedAt: created.updatedAt,
+      })).rejects.toBeInstanceOf(PresetConflictError);
+    });
+
+    test("pages privately, passes opaque cursors, and sorts each page by label then ID", async () => {
+      const state = new InMemoryObjectStore();
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      for (const [id, label] of [["z", "Beta"], ["a", "Alpha"], ["b", "Alpha"]] as const) {
+        await store.putEventPreset(id, { label, config: experience, expectedUpdatedAt: null });
+      }
+
+      const page = await store.listEventPresets({ limit: 3 });
+      expect(page.presets.map(({ id }) => id)).toEqual(["a", "b", "z"]);
+      expect(page.cursor).toBeNull();
+      await expect(store.listEventPresets({ limit: 0 })).rejects.toThrow("1 to 100");
+      await expect(store.listEventPresets({ limit: 101 })).rejects.toThrow("1 to 100");
+      await expect(store.listEventPresets({ cursor: "" })).rejects.toThrow("cursor");
+      expect(eventPresetPrefix()).toBe("presets/");
+    });
+
+    test("fails explicitly for corrupt stored presets and never offers deletion", async () => {
+      const state = new InMemoryObjectStore({
+        [eventPresetKey("broken")]: JSON.stringify({
+          version: 2,
+          id: "broken",
+          label: "Broken",
+          createdAt: "2026-07-24T00:00:00.000Z",
+          updatedAt: "2026-07-24T00:00:00.000Z",
+          config: { frames: [] },
+        }),
+      });
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      await expect(store.getEventPreset("broken")).rejects.toBeInstanceOf(
+        InvalidStoredEventPresetError,
+      );
+      await expect(store.listEventPresets()).rejects.toBeInstanceOf(
+        InvalidStoredEventPresetError,
+      );
+      expect("deleteEventPreset" in store).toBeFalse();
+    });
+  });
 });
diff --git a/app/event-store.ts b/app/event-store.ts
index 203e3f8..a5fbd32 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -13,6 +13,14 @@ import {
   type EventConfig,
   type EventExperience,
 } from "./event-config";
+import {
+  EVENT_PRESET_VERSION,
+  isPresetId,
+  parseEventPreset,
+  serializePresetExperience,
+  validatePresetLabel,
+  type EventPreset,
+} from "./event-preset";
 import {
   BOOTH_STALE_AFTER_MS,
   parseBoothHeartbeat,
@@ -254,6 +262,11 @@ export const boothHeartbeatKey = (event: string, deviceId: string) =>
 export const boothHeartbeatPrefix = (event: string) => `events/${event}/booths/`;
 export const boothOperationalStateKey = (event: string) =>
   `events/${event}/booth-state.json`;
+export const eventPresetKey = (presetId: string) => {
+  if (!isPresetId(presetId)) throw new TypeError("invalid preset ID");
+  return `presets/${presetId}.json`;
+};
+export const eventPresetPrefix = () => "presets/";
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
 export const stablePhotoKey = (event: string, id: StableCaptureIdentity) =>
@@ -331,6 +344,13 @@ export type PhotoIndexRebuildResult = {
   indexed: number;
   checkpoint: string | null;
 };
+export type EventPresetListOptions = { cursor?: string; limit?: number };
+export type EventPresetPage = { presets: EventPreset[]; cursor: string | null };
+export type PutEventPresetInput = {
+  label: string;
+  config: EventExperience;
+  expectedUpdatedAt: string | null;
+};
 
 export class ConfigConflictError extends Error {
   constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
@@ -362,6 +382,22 @@ export class InvalidStoredEventConfigError extends Error {
   }
 }
 
+export class InvalidStoredEventPresetError extends Error {
+  constructor(readonly presetId: string) {
+    super(`stored Event preset ${presetId} is corrupt or uses an unsupported version`);
+  }
+}
+
+export class PresetConflictError extends Error {
+  constructor(
+    readonly presetId: string,
+    readonly expectedUpdatedAt: string | null,
+    readonly currentUpdatedAt: string | null,
+  ) {
+    super("Event preset changed");
+  }
+}
+
 export class PhotoIndexWriteError extends Error {
   constructor(
     readonly photo: Pick<PutPhotoResult, "key" | "url" | "duplicate">,
@@ -470,6 +506,137 @@ export class EventStore {
     });
   }
 
+  async getEventPreset(presetId: string): Promise<EventPreset | null> {
+    const key = eventPresetKey(presetId);
+    const object = await this.state.get(key);
+    if (!object) return null;
+    return this.readEventPresetObject(presetId, object);
+  }
+
+  async listEventPresets(
+    options: EventPresetListOptions = {},
+  ): Promise<EventPresetPage> {
+    const limit = options.limit ?? 50;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw new TypeError("preset limit must be an integer from 1 to 100");
+    }
+    if (
+      options.cursor !== undefined
+      && (typeof options.cursor !== "string" || options.cursor.length === 0)
+    ) {
+      throw new TypeError("preset cursor is invalid");
+    }
+    const page = await this.state.list({
+      prefix: eventPresetPrefix(),
+      ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
+      limit,
+    });
+    const presets = await Promise.all(page.objects.map(async (listed) => {
+      const match = /^presets\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)\.json$/.exec(
+        listed.key,
+      );
+      if (!match) throw new InvalidStoredEventPresetError(listed.key);
+      const object = await this.state.get(listed.key);
+      if (!object) throw new InvalidStoredEventPresetError(match[1]!);
+      return this.readEventPresetObject(match[1]!, object);
+    }));
+    presets.sort((left, right) => {
+      if (left.label < right.label) return -1;
+      if (left.label > right.label) return 1;
+      if (left.id < right.id) return -1;
+      if (left.id > right.id) return 1;
+      return 0;
+    });
+    return {
+      presets,
+      cursor: page.truncated ? page.cursor ?? null : null,
+    };
+  }
+
+  async putEventPreset(
+    presetId: string,
+    input: PutEventPresetInput,
+  ): Promise<EventPreset> {
+    const key = eventPresetKey(presetId);
+    const label = validatePresetLabel(input.label);
+    const config = serializePresetExperience(input.config);
+    if (
+      input.expectedUpdatedAt !== null
+      && (
+        typeof input.expectedUpdatedAt !== "string"
+        || !Number.isFinite(Date.parse(input.expectedUpdatedAt))
+      )
+    ) {
+      throw new TypeError("expected preset timestamp is invalid");
+    }
+
+    const currentObject = await this.state.get(key);
+    const current = currentObject
+      ? await this.readEventPresetObject(presetId, currentObject)
+      : null;
+    if (
+      (input.expectedUpdatedAt === null && current !== null)
+      || (
+        input.expectedUpdatedAt !== null
+        && current?.updatedAt !== input.expectedUpdatedAt
+      )
+    ) {
+      throw new PresetConflictError(
+        presetId,
+        input.expectedUpdatedAt,
+        current?.updatedAt ?? null,
+      );
+    }
+
+    const serverTime = this.nextPresetTimestamp(current?.updatedAt ?? null);
+    const preset: EventPreset = {
+      version: EVENT_PRESET_VERSION,
+      id: presetId,
+      label,
+      createdAt: current?.createdAt ?? serverTime,
+      updatedAt: serverTime,
+      config,
+    };
+    const written = await this.state.compareAndSwap(
+      key,
+      currentObject?.etag ?? null,
+      JSON.stringify(preset),
+      jsonWriteOptions(),
+    );
+    if (!written) {
+      const raced = await this.getEventPreset(presetId);
+      throw new PresetConflictError(
+        presetId,
+        input.expectedUpdatedAt,
+        raced?.updatedAt ?? null,
+      );
+    }
+    return preset;
+  }
+
+  private async readEventPresetObject(
+    presetId: string,
+    object: StoredObjectBody,
+  ): Promise<EventPreset> {
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredEventPresetError(presetId);
+    }
+    const preset = parseEventPreset(value);
+    if (!preset || preset.id !== presetId) {
+      throw new InvalidStoredEventPresetError(presetId);
+    }
+    return preset;
+  }
+
+  private nextPresetTimestamp(previous: string | null): string {
+    const serverNow = this.now().getTime();
+    const previousTime = previous === null ? Number.NEGATIVE_INFINITY : Date.parse(previous);
+    return new Date(Math.max(serverNow, previousTime + 1)).toISOString();
+  }
+
   async saveConfigRevision(
     event: string,
     input: ConfigSaveInput

From e5d10f34e78899fa9d1653dc6a79312158761bfd Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:21:08 +0800
Subject: [PATCH 078/105] fix: globally order preset pages

---
 app/event-store.test.ts | 13 +++---
 app/event-store.ts      | 97 +++++++++++++++++++++++++++++++----------
 2 files changed, 82 insertions(+), 28 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 5db70e3..0c9a0f1 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -2611,16 +2611,19 @@ describe("EventStore", () => {
       })).rejects.toBeInstanceOf(PresetConflictError);
     });
 
-    test("pages privately, passes opaque cursors, and sorts each page by label then ID", async () => {
+    test("pages privately with global label and ID ordering", async () => {
       const state = new InMemoryObjectStore();
       const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
-      for (const [id, label] of [["z", "Beta"], ["a", "Alpha"], ["b", "Alpha"]] as const) {
+      for (const [id, label] of [["a", "Zulu"], ["b", "Yankee"], ["c", "Alpha"]] as const) {
         await store.putEventPreset(id, { label, config: experience, expectedUpdatedAt: null });
       }
 
-      const page = await store.listEventPresets({ limit: 3 });
-      expect(page.presets.map(({ id }) => id)).toEqual(["a", "b", "z"]);
-      expect(page.cursor).toBeNull();
+      const first = await store.listEventPresets({ limit: 2 });
+      expect(first.presets.map(({ id }) => id)).toEqual(["c", "b"]);
+      expect(first.cursor).not.toBeNull();
+      const second = await store.listEventPresets({ limit: 2, cursor: first.cursor! });
+      expect(second.presets.map(({ id }) => id)).toEqual(["a"]);
+      expect(second.cursor).toBeNull();
       await expect(store.listEventPresets({ limit: 0 })).rejects.toThrow("1 to 100");
       await expect(store.listEventPresets({ limit: 101 })).rejects.toThrow("1 to 100");
       await expect(store.listEventPresets({ cursor: "" })).rejects.toThrow("cursor");
diff --git a/app/event-store.ts b/app/event-store.ts
index a5fbd32..e92622e 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -352,6 +352,42 @@ export type PutEventPresetInput = {
   expectedUpdatedAt: string | null;
 };
 
+type EventPresetCursor = Pick<EventPreset, "label" | "id">;
+const EVENT_PRESET_CURSOR_PREFIX = "preset-v1:";
+
+function compareEventPresets(left: EventPresetCursor, right: EventPresetCursor): number {
+  if (left.label < right.label) return -1;
+  if (left.label > right.label) return 1;
+  if (left.id < right.id) return -1;
+  if (left.id > right.id) return 1;
+  return 0;
+}
+
+function encodeEventPresetCursor(preset: EventPresetCursor): string {
+  return `${EVENT_PRESET_CURSOR_PREFIX}${encodeURIComponent(preset.label)}:${preset.id}`;
+}
+
+function parseEventPresetCursor(value: string): EventPresetCursor {
+  if (!value.startsWith(EVENT_PRESET_CURSOR_PREFIX)) {
+    throw new TypeError("preset cursor is invalid");
+  }
+  const payload = value.slice(EVENT_PRESET_CURSOR_PREFIX.length);
+  const separator = payload.lastIndexOf(":");
+  if (separator <= 0) throw new TypeError("preset cursor is invalid");
+  const encodedLabel = payload.slice(0, separator);
+  const id = payload.slice(separator + 1);
+  try {
+    const label = decodeURIComponent(encodedLabel);
+    validatePresetLabel(label);
+    if (encodeURIComponent(label) !== encodedLabel || !isPresetId(id)) {
+      throw new TypeError("preset cursor is invalid");
+    }
+    return { label, id };
+  } catch {
+    throw new TypeError("preset cursor is invalid");
+  }
+}
+
 export class ConfigConflictError extends Error {
   constructor(readonly expectedRevisionId: string | null, readonly currentRevisionId: string | null) {
     super("event configuration changed");
@@ -526,30 +562,45 @@ export class EventStore {
     ) {
       throw new TypeError("preset cursor is invalid");
     }
-    const page = await this.state.list({
-      prefix: eventPresetPrefix(),
-      ...(options.cursor !== undefined ? { cursor: options.cursor } : {}),
-      limit,
-    });
-    const presets = await Promise.all(page.objects.map(async (listed) => {
-      const match = /^presets\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)\.json$/.exec(
-        listed.key,
-      );
-      if (!match) throw new InvalidStoredEventPresetError(listed.key);
-      const object = await this.state.get(listed.key);
-      if (!object) throw new InvalidStoredEventPresetError(match[1]!);
-      return this.readEventPresetObject(match[1]!, object);
-    }));
-    presets.sort((left, right) => {
-      if (left.label < right.label) return -1;
-      if (left.label > right.label) return 1;
-      if (left.id < right.id) return -1;
-      if (left.id > right.id) return 1;
-      return 0;
-    });
+    const after = options.cursor === undefined
+      ? null
+      : parseEventPresetCursor(options.cursor);
+    const presets: EventPreset[] = [];
+    let storageCursor: string | undefined;
+    do {
+      const page = await this.state.list({
+        prefix: eventPresetPrefix(),
+        ...(storageCursor !== undefined ? { cursor: storageCursor } : {}),
+        limit: PAGE_SIZE,
+      });
+      const pagePresets = await Promise.all(page.objects.map(async (listed) => {
+        const match = /^presets\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)\.json$/.exec(
+          listed.key,
+        );
+        if (!match) throw new InvalidStoredEventPresetError(listed.key);
+        const object = await this.state.get(listed.key);
+        if (!object) throw new InvalidStoredEventPresetError(match[1]!);
+        return this.readEventPresetObject(match[1]!, object);
+      }));
+      presets.push(...pagePresets);
+      if (!page.truncated) {
+        storageCursor = undefined;
+        break;
+      }
+      if (!page.cursor) throw new InvalidStoredEventPresetError(eventPresetPrefix());
+      storageCursor = page.cursor;
+    } while (storageCursor !== undefined);
+
+    presets.sort(compareEventPresets);
+    const remaining = after === null
+      ? presets
+      : presets.filter((preset) => compareEventPresets(preset, after) > 0);
+    const result = remaining.slice(0, limit);
     return {
-      presets,
-      cursor: page.truncated ? page.cursor ?? null : null,
+      presets: result,
+      cursor: remaining.length > limit
+        ? encodeEventPresetCursor(result[result.length - 1]!)
+        : null,
     };
   }
 

From 6afc78d41852f55e233a06956dd9b0991babaeac Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:30:33 +0800
Subject: [PATCH 079/105] fix: bound globally ordered preset paging

---
 app/event-preset.test.ts |   1 +
 app/event-preset.ts      |  17 ++++-
 app/event-store.test.ts  |  45 +++++++++++++
 app/event-store.ts       | 136 ++++++++++++++++++++++-----------------
 4 files changed, 140 insertions(+), 59 deletions(-)

diff --git a/app/event-preset.test.ts b/app/event-preset.test.ts
index abd785d..cace511 100644
--- a/app/event-preset.test.ts
+++ b/app/event-preset.test.ts
@@ -85,6 +85,7 @@ describe("Event presets", () => {
     expect(parseEventPreset({ ...storedPreset, id: "../launch" })).toBeNull();
     expect(parseEventPreset({ ...storedPreset, label: "   " })).toBeNull();
     expect(parseEventPreset({ ...storedPreset, label: "x".repeat(81) })).toBeNull();
+    expect(parseEventPreset({ ...storedPreset, label: "\ud800" })).toBeNull();
     expect(parseEventPreset({ ...storedPreset, boothKeyHash: "leak" })).toBeNull();
     expect(parseEventPreset({ ...storedPreset, config: { frames: ["bad/frame"] } })).toBeNull();
   });
diff --git a/app/event-preset.ts b/app/event-preset.ts
index f47f1fc..b035a55 100644
--- a/app/event-preset.ts
+++ b/app/event-preset.ts
@@ -35,7 +35,22 @@ function isIsoTimestamp(value: unknown): value is string {
 function isPresetLabel(value: unknown): value is string {
   return typeof value === "string"
     && value.trim().length > 0
-    && [...value].length <= 80;
+    && [...value].length <= 80
+    && isWellFormedUtf16(value);
+}
+
+function isWellFormedUtf16(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return false;
+      index += 1;
+    } else if (unit >= 0xdc00 && unit <= 0xdfff) {
+      return false;
+    }
+  }
+  return true;
 }
 
 export function serializePresetExperience(
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 0c9a0f1..8374ebb 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -28,6 +28,7 @@ import {
   photoIndexRebuildCompleteKey,
   photoReceiptKey,
   eventPresetKey,
+  eventPresetIndexKey,
   eventPresetPrefix,
   type ListOptions,
   type ListResult,
@@ -216,6 +217,26 @@ class InstrumentedStateStore extends InMemoryObjectStore {
   }
 }
 
+class PresetAccessStore extends InMemoryObjectStore {
+  gets = 0;
+  lists = 0;
+
+  override async get(key: string): Promise<StoredObjectBody | null> {
+    this.gets += 1;
+    return super.get(key);
+  }
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    this.lists += 1;
+    return super.list(options);
+  }
+
+  resetAccess(): void {
+    this.gets = 0;
+    this.lists = 0;
+  }
+}
+
 class BoothStateAccessStore extends InMemoryObjectStore {
   readonly reads: string[] = [];
   readonly writes: string[] = [];
@@ -2556,6 +2577,7 @@ describe("EventStore", () => {
       });
       expect(state.has(eventPresetKey("launch"))).toBeTrue();
       expect((await state.list()).objects.map((object) => object.key)).toEqual([
+        eventPresetIndexKey("launch", "Launch"),
         "presets/launch.json",
       ]);
       expect((await photos.list()).objects).toEqual([]);
@@ -2570,6 +2592,8 @@ describe("EventStore", () => {
       expect(updated.updatedAt).toBe(now.toISOString());
       expect(updated.config.frames).toEqual(["strip"]);
       expect(await store.getEventPreset("launch")).toEqual(updated);
+      expect(state.has(eventPresetIndexKey("launch", "Launch"))).toBeFalse();
+      expect(state.has(eventPresetIndexKey("launch", "Launch updated"))).toBeTrue();
     });
 
     test("enforces create-only and exact observed update conflicts", async () => {
@@ -2627,11 +2651,32 @@ describe("EventStore", () => {
       await expect(store.listEventPresets({ limit: 0 })).rejects.toThrow("1 to 100");
       await expect(store.listEventPresets({ limit: 101 })).rejects.toThrow("1 to 100");
       await expect(store.listEventPresets({ cursor: "" })).rejects.toThrow("cursor");
+      await expect(store.listEventPresets({ cursor: "1" })).rejects.toThrow("cursor");
       expect(eventPresetPrefix()).toBe("presets/");
     });
 
+    test("bounds list work to the requested sortable index page", async () => {
+      const state = new PresetAccessStore();
+      const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+      for (let index = 0; index < 101; index += 1) {
+        await store.putEventPreset(`preset-${index}`, {
+          label: `Label ${String(100 - index).padStart(3, "0")}`,
+          config: experience,
+          expectedUpdatedAt: null,
+        });
+      }
+      state.resetAccess();
+
+      const page = await store.listEventPresets({ limit: 1 });
+      expect(page.presets).toHaveLength(1);
+      expect(page.cursor).not.toBeNull();
+      expect(state.lists).toBe(1);
+      expect(state.gets).toBe(1);
+    });
+
     test("fails explicitly for corrupt stored presets and never offers deletion", async () => {
       const state = new InMemoryObjectStore({
+        [eventPresetIndexKey("broken", "Broken")]: "{}",
         [eventPresetKey("broken")]: JSON.stringify({
           version: 2,
           id: "broken",
diff --git a/app/event-store.ts b/app/event-store.ts
index e92622e..6c177af 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -267,6 +267,16 @@ export const eventPresetKey = (presetId: string) => {
   return `presets/${presetId}.json`;
 };
 export const eventPresetPrefix = () => "presets/";
+const eventPresetIndexPrefix = () => `${eventPresetPrefix()}_index/v1/`;
+export const eventPresetIndexKey = (presetId: string, label: string) => {
+  if (!isPresetId(presetId)) throw new TypeError("invalid preset ID");
+  validatePresetLabel(label);
+  let encodedLabel = "";
+  for (let index = 0; index < label.length; index += 1) {
+    encodedLabel += label.charCodeAt(index).toString(16).padStart(4, "0");
+  }
+  return `${eventPresetIndexPrefix()}${encodedLabel}/${presetId}.json`;
+};
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
 export const stablePhotoKey = (event: string, id: StableCaptureIdentity) =>
@@ -352,40 +362,43 @@ export type PutEventPresetInput = {
   expectedUpdatedAt: string | null;
 };
 
-type EventPresetCursor = Pick<EventPreset, "label" | "id">;
 const EVENT_PRESET_CURSOR_PREFIX = "preset-v1:";
 
-function compareEventPresets(left: EventPresetCursor, right: EventPresetCursor): number {
-  if (left.label < right.label) return -1;
-  if (left.label > right.label) return 1;
-  if (left.id < right.id) return -1;
-  if (left.id > right.id) return 1;
-  return 0;
+function parseEventPresetIndexKey(
+  key: string,
+): Pick<EventPreset, "label" | "id"> | null {
+  const prefix = eventPresetIndexPrefix();
+  if (!key.startsWith(prefix)) return null;
+  const match = /^([0-9a-f]+)\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)\.json$/.exec(
+    key.slice(prefix.length),
+  );
+  if (!match || match[1]!.length % 4 !== 0) return null;
+  let label = "";
+  for (let offset = 0; offset < match[1]!.length; offset += 4) {
+    label += String.fromCharCode(Number.parseInt(match[1]!.slice(offset, offset + 4), 16));
+  }
+  try {
+    validatePresetLabel(label);
+  } catch {
+    return null;
+  }
+  const id = match[2]!;
+  return eventPresetIndexKey(id, label) === key ? { label, id } : null;
 }
 
-function encodeEventPresetCursor(preset: EventPresetCursor): string {
-  return `${EVENT_PRESET_CURSOR_PREFIX}${encodeURIComponent(preset.label)}:${preset.id}`;
+function encodeEventPresetCursor(afterIndexKey: string): string {
+  return `${EVENT_PRESET_CURSOR_PREFIX}${afterIndexKey}`;
 }
 
-function parseEventPresetCursor(value: string): EventPresetCursor {
+function parseEventPresetCursor(value: string): string {
   if (!value.startsWith(EVENT_PRESET_CURSOR_PREFIX)) {
     throw new TypeError("preset cursor is invalid");
   }
-  const payload = value.slice(EVENT_PRESET_CURSOR_PREFIX.length);
-  const separator = payload.lastIndexOf(":");
-  if (separator <= 0) throw new TypeError("preset cursor is invalid");
-  const encodedLabel = payload.slice(0, separator);
-  const id = payload.slice(separator + 1);
-  try {
-    const label = decodeURIComponent(encodedLabel);
-    validatePresetLabel(label);
-    if (encodeURIComponent(label) !== encodedLabel || !isPresetId(id)) {
-      throw new TypeError("preset cursor is invalid");
-    }
-    return { label, id };
-  } catch {
+  const afterIndexKey = value.slice(EVENT_PRESET_CURSOR_PREFIX.length);
+  if (!parseEventPresetIndexKey(afterIndexKey)) {
     throw new TypeError("preset cursor is invalid");
   }
+  return afterIndexKey;
 }
 
 export class ConfigConflictError extends Error {
@@ -562,44 +575,29 @@ export class EventStore {
     ) {
       throw new TypeError("preset cursor is invalid");
     }
-    const after = options.cursor === undefined
-      ? null
+    const afterIndexKey = options.cursor === undefined
+      ? undefined
       : parseEventPresetCursor(options.cursor);
+    const page = await this.state.list({
+      prefix: eventPresetIndexPrefix(),
+      ...(afterIndexKey !== undefined ? { startAfter: afterIndexKey } : {}),
+      limit,
+    });
     const presets: EventPreset[] = [];
-    let storageCursor: string | undefined;
-    do {
-      const page = await this.state.list({
-        prefix: eventPresetPrefix(),
-        ...(storageCursor !== undefined ? { cursor: storageCursor } : {}),
-        limit: PAGE_SIZE,
-      });
-      const pagePresets = await Promise.all(page.objects.map(async (listed) => {
-        const match = /^presets\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)\.json$/.exec(
-          listed.key,
-        );
-        if (!match) throw new InvalidStoredEventPresetError(listed.key);
-        const object = await this.state.get(listed.key);
-        if (!object) throw new InvalidStoredEventPresetError(match[1]!);
-        return this.readEventPresetObject(match[1]!, object);
-      }));
-      presets.push(...pagePresets);
-      if (!page.truncated) {
-        storageCursor = undefined;
-        break;
-      }
-      if (!page.cursor) throw new InvalidStoredEventPresetError(eventPresetPrefix());
-      storageCursor = page.cursor;
-    } while (storageCursor !== undefined);
-
-    presets.sort(compareEventPresets);
-    const remaining = after === null
-      ? presets
-      : presets.filter((preset) => compareEventPresets(preset, after) > 0);
-    const result = remaining.slice(0, limit);
+    let lastScannedKey: string | null = null;
+    for (const listed of page.objects) {
+      lastScannedKey = listed.key;
+      const index = parseEventPresetIndexKey(listed.key);
+      if (!index) throw new InvalidStoredEventPresetError(listed.key);
+      const object = await this.state.get(eventPresetKey(index.id));
+      if (!object) continue;
+      const preset = await this.readEventPresetObject(index.id, object);
+      if (preset.label === index.label) presets.push(preset);
+    }
     return {
-      presets: result,
-      cursor: remaining.length > limit
-        ? encodeEventPresetCursor(result[result.length - 1]!)
+      presets,
+      cursor: page.truncated && lastScannedKey !== null
+        ? encodeEventPresetCursor(lastScannedKey)
         : null,
     };
   }
@@ -648,6 +646,12 @@ export class EventStore {
       updatedAt: serverTime,
       config,
     };
+    const indexKey = eventPresetIndexKey(presetId, label);
+    await this.state.put(
+      indexKey,
+      JSON.stringify({ version: EVENT_PRESET_VERSION, id: presetId, label }),
+      jsonWriteOptions(),
+    );
     const written = await this.state.compareAndSwap(
       key,
       currentObject?.etag ?? null,
@@ -656,12 +660,28 @@ export class EventStore {
     );
     if (!written) {
       const raced = await this.getEventPreset(presetId);
+      if (raced?.label !== label) {
+        try {
+          await this.state.delete(indexKey);
+        } catch {
+          // A stale private index entry is harmless and bounded list paging
+          // skips it after checking the authoritative preset.
+        }
+      }
       throw new PresetConflictError(
         presetId,
         input.expectedUpdatedAt,
         raced?.updatedAt ?? null,
       );
     }
+    if (current && current.label !== label) {
+      try {
+        await this.state.delete(eventPresetIndexKey(presetId, current.label));
+      } catch {
+        // The new authoritative preset and index are already durable. A stale
+        // exact index entry is skipped by listEventPresets.
+      }
+    }
     return preset;
   }
 

From d304a210534d467e758a955a78a84fc2a3b7b3d7 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:37:03 +0800
Subject: [PATCH 080/105] fix: version preset ordering indexes

---
 app/event-store.test.ts                       | 86 ++++++++++++++++++-
 app/event-store.ts                            | 79 +++++++++++++----
 ...6-07-24-release-4-repeatable-operations.md | 13 ++-
 3 files changed, 154 insertions(+), 24 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 8374ebb..234ecef 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -237,6 +237,35 @@ class PresetAccessStore extends InMemoryObjectStore {
   }
 }
 
+class DeferredPresetIndexDeleteStore extends InMemoryObjectStore {
+  readonly deletionStarted: Promise<void>;
+  private markDeletionStarted!: () => void;
+  private readonly deletionReleased: Promise<void>;
+  private releaseDeletion!: () => void;
+
+  constructor(private readonly blockedKey: string) {
+    super();
+    this.deletionStarted = new Promise((resolve) => {
+      this.markDeletionStarted = resolve;
+    });
+    this.deletionReleased = new Promise((resolve) => {
+      this.releaseDeletion = resolve;
+    });
+  }
+
+  override async delete(key: string): Promise<void> {
+    if (key === this.blockedKey) {
+      this.markDeletionStarted();
+      await this.deletionReleased;
+    }
+    return super.delete(key);
+  }
+
+  resumeDeletion(): void {
+    this.releaseDeletion();
+  }
+}
+
 class BoothStateAccessStore extends InMemoryObjectStore {
   readonly reads: string[] = [];
   readonly writes: string[] = [];
@@ -2577,7 +2606,7 @@ describe("EventStore", () => {
       });
       expect(state.has(eventPresetKey("launch"))).toBeTrue();
       expect((await state.list()).objects.map((object) => object.key)).toEqual([
-        eventPresetIndexKey("launch", "Launch"),
+        eventPresetIndexKey("launch", "Launch", created.updatedAt),
         "presets/launch.json",
       ]);
       expect((await photos.list()).objects).toEqual([]);
@@ -2592,8 +2621,8 @@ describe("EventStore", () => {
       expect(updated.updatedAt).toBe(now.toISOString());
       expect(updated.config.frames).toEqual(["strip"]);
       expect(await store.getEventPreset("launch")).toEqual(updated);
-      expect(state.has(eventPresetIndexKey("launch", "Launch"))).toBeFalse();
-      expect(state.has(eventPresetIndexKey("launch", "Launch updated"))).toBeTrue();
+      expect(state.has(eventPresetIndexKey("launch", "Launch", created.updatedAt))).toBeFalse();
+      expect(state.has(eventPresetIndexKey("launch", "Launch updated", updated.updatedAt))).toBeTrue();
     });
 
     test("enforces create-only and exact observed update conflicts", async () => {
@@ -2674,9 +2703,58 @@ describe("EventStore", () => {
       expect(state.gets).toBe(1);
     });
 
+    test("an older delayed cleanup cannot delete a newer live label index", async () => {
+      let now = new Date("2026-07-24T00:00:00.000Z");
+      const oldAlphaIndex = eventPresetIndexKey(
+        "launch",
+        "Alpha",
+        now.toISOString(),
+      );
+      const state = new DeferredPresetIndexDeleteStore(oldAlphaIndex);
+      const store = new EventStore(
+        new InMemoryObjectStore(),
+        state,
+        "https://photos.example",
+        () => now,
+      );
+      const created = await store.putEventPreset("launch", {
+        label: "Alpha",
+        config: experience,
+        expectedUpdatedAt: null,
+      });
+
+      now = new Date("2026-07-24T00:00:01.000Z");
+      const betaWrite = store.putEventPreset("launch", {
+        label: "Beta",
+        config: experience,
+        expectedUpdatedAt: created.updatedAt,
+      });
+      await state.deletionStarted;
+      const beta = await store.getEventPreset("launch");
+      expect(beta?.label).toBe("Beta");
+
+      now = new Date("2026-07-24T00:00:02.000Z");
+      const alpha = await store.putEventPreset("launch", {
+        label: "Alpha",
+        config: experience,
+        expectedUpdatedAt: beta!.updatedAt,
+      });
+      state.resumeDeletion();
+      await betaWrite;
+
+      expect(alpha.label).toBe("Alpha");
+      expect((await store.listEventPresets()).presets.map(({ label }) => label)).toEqual([
+        "Alpha",
+      ]);
+    });
+
     test("fails explicitly for corrupt stored presets and never offers deletion", async () => {
       const state = new InMemoryObjectStore({
-        [eventPresetIndexKey("broken", "Broken")]: "{}",
+        [eventPresetIndexKey(
+          "broken",
+          "Broken",
+          "2026-07-24T00:00:00.000Z",
+        )]: "{}",
         [eventPresetKey("broken")]: JSON.stringify({
           version: 2,
           id: "broken",
diff --git a/app/event-store.ts b/app/event-store.ts
index 6c177af..84e8769 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -268,14 +268,40 @@ export const eventPresetKey = (presetId: string) => {
 };
 export const eventPresetPrefix = () => "presets/";
 const eventPresetIndexPrefix = () => `${eventPresetPrefix()}_index/v1/`;
-export const eventPresetIndexKey = (presetId: string, label: string) => {
+function utf16Hex(value: string): string {
+  let encoded = "";
+  for (let index = 0; index < value.length; index += 1) {
+    encoded += value.charCodeAt(index).toString(16).padStart(4, "0");
+  }
+  return encoded;
+}
+
+function decodeUtf16Hex(value: string): string | null {
+  if (value.length === 0 || value.length % 4 !== 0 || !/^[0-9a-f]+$/.test(value)) {
+    return null;
+  }
+  let decoded = "";
+  for (let offset = 0; offset < value.length; offset += 4) {
+    decoded += String.fromCharCode(Number.parseInt(value.slice(offset, offset + 4), 16));
+  }
+  return decoded;
+}
+
+export const eventPresetIndexKey = (
+  presetId: string,
+  label: string,
+  updatedAt: string,
+) => {
   if (!isPresetId(presetId)) throw new TypeError("invalid preset ID");
   validatePresetLabel(label);
-  let encodedLabel = "";
-  for (let index = 0; index < label.length; index += 1) {
-    encodedLabel += label.charCodeAt(index).toString(16).padStart(4, "0");
+  const updatedTime = Date.parse(updatedAt);
+  if (
+    !Number.isFinite(updatedTime)
+    || new Date(updatedTime).toISOString() !== updatedAt
+  ) {
+    throw new TypeError("invalid preset timestamp");
   }
-  return `${eventPresetIndexPrefix()}${encodedLabel}/${presetId}.json`;
+  return `${eventPresetIndexPrefix()}${utf16Hex(label)}/${presetId}/${utf16Hex(updatedAt)}.json`;
 };
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
@@ -366,24 +392,29 @@ const EVENT_PRESET_CURSOR_PREFIX = "preset-v1:";
 
 function parseEventPresetIndexKey(
   key: string,
-): Pick<EventPreset, "label" | "id"> | null {
+): Pick<EventPreset, "label" | "id" | "updatedAt"> | null {
   const prefix = eventPresetIndexPrefix();
   if (!key.startsWith(prefix)) return null;
-  const match = /^([0-9a-f]+)\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)\.json$/.exec(
+  const match = /^([0-9a-f]+)\/([a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?)\/([0-9a-f]+)\.json$/.exec(
     key.slice(prefix.length),
   );
-  if (!match || match[1]!.length % 4 !== 0) return null;
-  let label = "";
-  for (let offset = 0; offset < match[1]!.length; offset += 4) {
-    label += String.fromCharCode(Number.parseInt(match[1]!.slice(offset, offset + 4), 16));
-  }
+  if (!match) return null;
+  const label = decodeUtf16Hex(match[1]!);
+  const updatedAt = decodeUtf16Hex(match[3]!);
+  if (label === null || updatedAt === null) return null;
   try {
     validatePresetLabel(label);
   } catch {
     return null;
   }
   const id = match[2]!;
-  return eventPresetIndexKey(id, label) === key ? { label, id } : null;
+  try {
+    return eventPresetIndexKey(id, label, updatedAt) === key
+      ? { label, id, updatedAt }
+      : null;
+  } catch {
+    return null;
+  }
 }
 
 function encodeEventPresetCursor(afterIndexKey: string): string {
@@ -592,7 +623,12 @@ export class EventStore {
       const object = await this.state.get(eventPresetKey(index.id));
       if (!object) continue;
       const preset = await this.readEventPresetObject(index.id, object);
-      if (preset.label === index.label) presets.push(preset);
+      if (
+        preset.label === index.label
+        && preset.updatedAt === index.updatedAt
+      ) {
+        presets.push(preset);
+      }
     }
     return {
       presets,
@@ -646,10 +682,15 @@ export class EventStore {
       updatedAt: serverTime,
       config,
     };
-    const indexKey = eventPresetIndexKey(presetId, label);
+    const indexKey = eventPresetIndexKey(presetId, label, preset.updatedAt);
     await this.state.put(
       indexKey,
-      JSON.stringify({ version: EVENT_PRESET_VERSION, id: presetId, label }),
+      JSON.stringify({
+        version: EVENT_PRESET_VERSION,
+        id: presetId,
+        label,
+        updatedAt: preset.updatedAt,
+      }),
       jsonWriteOptions(),
     );
     const written = await this.state.compareAndSwap(
@@ -674,9 +715,11 @@ export class EventStore {
         raced?.updatedAt ?? null,
       );
     }
-    if (current && current.label !== label) {
+    if (current) {
       try {
-        await this.state.delete(eventPresetIndexKey(presetId, current.label));
+        await this.state.delete(
+          eventPresetIndexKey(presetId, current.label, current.updatedAt),
+        );
       } catch {
         // The new authoritative preset and index are already durable. A stale
         // exact index entry is skipped by listEventPresets.
diff --git a/docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md b/docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md
index bd72846..1df3425 100644
--- a/docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md
+++ b/docs/superpowers/plans/2026-07-24-release-4-repeatable-operations.md
@@ -216,9 +216,12 @@ Test:
 - Lists accept opaque cursors and limits `1..100`, default `50`.
 - Corrupt or unsupported stored versions fail explicitly.
 - Presets are sorted by label then ID without trusting client locale.
-- Only `STATE/presets/{id}.json` is written.
+- The authoritative record is only `STATE/presets/{id}.json`; bounded global
+  ordering may additionally write version-unique derived entries under the
+  private `STATE/presets/_index/v1/` namespace.
 - `PHOTOS`, Events, config revisions, and adjacent presets stay untouched.
-- No delete method or prefix cleanup exists.
+- No preset delete method or prefix cleanup exists. Updating a preset may
+  delete only the exact superseded derived index key.
 
 - [ ] **Step 5: Implement CAS-backed private preset methods**
 
@@ -228,6 +231,12 @@ compare against `null`. For update, read and validate the record, compare
 retry may return a conflict; the Admin reconciles by reloading and comparing
 the safe content rather than overwriting a newer change.
 
+Keep list work bounded with a private sortable index whose key encodes the
+label, preset ID, and exact `updatedAt`. The opaque cursor carries the last
+scanned derived key and resumes with `startAfter`. Readers validate every
+entry against the authoritative preset and advance across stale entries.
+Version-unique index keys make exact cleanup safe from delayed ABA updates.
+
 - [ ] **Step 6: Run focused and full checks**
 
 ```bash

From 6a152631bd667ec03ec1b6cc653b297afe04bab6 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:45:32 +0800
Subject: [PATCH 081/105] feat: apply presets through config revisions

---
 app/api/presets/[presetId]/route.ts |  18 +++
 app/api/presets/apply/route.ts      |  14 ++
 app/api/presets/handlers.test.ts    | 193 +++++++++++++++++++++++
 app/api/presets/handlers.ts         | 232 ++++++++++++++++++++++++++++
 app/api/presets/route.ts            |  14 ++
 app/event-store.test.ts             |  77 +++++++++
 app/event-store.ts                  |  68 ++++++--
 7 files changed, 607 insertions(+), 9 deletions(-)
 create mode 100644 app/api/presets/[presetId]/route.ts
 create mode 100644 app/api/presets/apply/route.ts
 create mode 100644 app/api/presets/handlers.test.ts
 create mode 100644 app/api/presets/handlers.ts
 create mode 100644 app/api/presets/route.ts

diff --git a/app/api/presets/[presetId]/route.ts b/app/api/presets/[presetId]/route.ts
new file mode 100644
index 0000000..00ed55d
--- /dev/null
+++ b/app/api/presets/[presetId]/route.ts
@@ -0,0 +1,18 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { putPreset } from "../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function PUT(
+  req: NextRequest,
+  context: { params: Promise<{ presetId: string }> },
+) {
+  const { presetId } = await context.params;
+  const { env } = getCloudflareContext();
+  return putPreset(req, presetId, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/presets/apply/route.ts b/app/api/presets/apply/route.ts
new file mode 100644
index 0000000..dcd72b2
--- /dev/null
+++ b/app/api/presets/apply/route.ts
@@ -0,0 +1,14 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { postPresetApply } from "../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return postPresetApply(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/presets/handlers.test.ts b/app/api/presets/handlers.test.ts
new file mode 100644
index 0000000..d37b90f
--- /dev/null
+++ b/app/api/presets/handlers.test.ts
@@ -0,0 +1,193 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import {
+  ConfigConflictError,
+  EventPresetNotFoundError,
+  EventStore,
+  InMemoryObjectStore,
+  PresetConflictError,
+  type ConfigMutationResult,
+  type ConfigPresetApplyInput,
+  type EventPresetPage,
+  type EventPresetListOptions,
+  type PutEventPresetInput,
+} from "@/app/event-store";
+import type { EventPreset } from "@/app/event-preset";
+import { getPresets, postPresetApply, putPreset } from "./handlers";
+
+const preset: EventPreset = {
+  version: 1,
+  id: "launch-night",
+  label: "Launch Night",
+  createdAt: "2026-07-24T00:00:00.000Z",
+  updatedAt: "2026-07-24T00:00:00.000Z",
+  config: { frames: ["square"], locales: ["en"], defaultLocale: "en" },
+};
+
+class PresetHandlerStore extends EventStore {
+  calls: string[] = [];
+  listResult: EventPresetPage = { presets: [preset], cursor: null };
+  putError: unknown;
+  applyError: unknown;
+
+  constructor() {
+    super(new InMemoryObjectStore(), new InMemoryObjectStore(), "https://photos.example");
+  }
+
+  override async listEventPresets(options: EventPresetListOptions): Promise<EventPresetPage> {
+    this.calls.push(`list:${JSON.stringify(options)}`);
+    return this.listResult;
+  }
+
+  override async putEventPreset(id: string, input: PutEventPresetInput): Promise<EventPreset> {
+    this.calls.push(`put:${id}:${JSON.stringify(input)}`);
+    if (this.putError) throw this.putError;
+    return { ...preset, id, label: input.label, config: input.config };
+  }
+
+  override async applyEventPreset(
+    event: string,
+    input: ConfigPresetApplyInput,
+  ): Promise<ConfigMutationResult> {
+    this.calls.push(`apply:${event}:${JSON.stringify(input)}`);
+    if (this.applyError) throw this.applyError;
+    return {
+      config: {
+        ...preset.config,
+        boothKeyHash: "private",
+        currentRevisionId: input.mutationId,
+      },
+      revision: {
+        version: 1,
+        id: input.mutationId,
+        createdAt: "2026-07-24T00:00:00.000Z",
+        parentRevisionId: input.baseRevisionId,
+        reason: "preset",
+        sourcePresetId: input.presetId,
+        config: preset.config,
+      },
+      idempotent: false,
+    };
+  }
+}
+
+function request(
+  path: string,
+  options: { method?: string; key?: string; body?: unknown } = {},
+): NextRequest {
+  return new NextRequest(`https://app.test${path}`, {
+    method: options.method,
+    headers: {
+      "x-booth-key": options.key ?? "admin",
+      "content-type": "application/json",
+    },
+    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+  });
+}
+
+describe("Admin preset handlers", () => {
+  test("authenticates before parsing or storage", async () => {
+    for (const [adminKey, status] of [[undefined, 503], ["different", 401]] as const) {
+      const store = new PresetHandlerStore();
+      const response = await getPresets(request("/api/presets?limit=nope"), {
+        store,
+        adminKey,
+      });
+      expect(response.status).toBe(status);
+      expect(store.calls).toEqual([]);
+    }
+  });
+
+  test("pages presets with strict bounded input and an explicit safe response", async () => {
+    const store = new PresetHandlerStore();
+    store.listResult = {
+      presets: [{ ...preset, credential: "never" } as never],
+      cursor: "opaque",
+    };
+    const response = await getPresets(request("/api/presets?limit=25"), {
+      store,
+      adminKey: "admin",
+    });
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(store.calls).toEqual(["list:{\"limit\":25}"]);
+    expect(JSON.stringify(await response.json())).not.toContain("credential");
+
+    for (const query of ["limit=0", "limit=101", "limit=1.5", "secret=x", "limit=2&limit=3"]) {
+      const invalidStore = new PresetHandlerStore();
+      expect((await getPresets(request(`/api/presets?${query}`), {
+        store: invalidStore,
+        adminKey: "admin",
+      })).status).toBe(400);
+      expect(invalidStore.calls).toEqual([]);
+    }
+  });
+
+  test("strictly saves only a safe experience and reports conflicts", async () => {
+    const store = new PresetHandlerStore();
+    const response = await putPreset(request("/api/presets/launch-night", {
+      method: "PUT",
+      body: {
+        label: "Launch Night",
+        config: preset.config,
+        expectedUpdatedAt: null,
+      },
+    }), "launch-night", { store, adminKey: "admin" });
+    expect(response.status).toBe(200);
+    expect(store.calls[0]).toContain("put:launch-night:");
+
+    for (const body of [
+      { label: "Unsafe", config: { ...preset.config, boothKeyHash: "secret" }, expectedUpdatedAt: null },
+      { label: "Unsafe", config: preset.config, expectedUpdatedAt: null, device: "private" },
+    ]) {
+      const invalidStore = new PresetHandlerStore();
+      expect((await putPreset(request("/api/presets/launch-night", {
+        method: "PUT",
+        body,
+      }), "launch-night", { store: invalidStore, adminKey: "admin" })).status).toBe(400);
+      expect(invalidStore.calls).toEqual([]);
+    }
+
+    store.putError = new PresetConflictError("launch-night", null, preset.updatedAt);
+    expect((await putPreset(request("/api/presets/launch-night", {
+      method: "PUT",
+      body: { label: preset.label, config: preset.config, expectedUpdatedAt: null },
+    }), "launch-night", { store, adminKey: "admin" })).status).toBe(409);
+  });
+
+  test("applies a preset to one canonical Event and allowlists the public config", async () => {
+    const mutationId = "018f0000-0000-4000-8000-000000000301";
+    const store = new PresetHandlerStore();
+    const body = { presetId: "launch-night", mutationId, baseRevisionId: null };
+    const response = await postPresetApply(request("/api/presets/apply?event=launch", {
+      method: "POST",
+      body,
+    }), { store, adminKey: "admin" });
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      ...preset.config,
+      hasBoothKey: true,
+      currentRevisionId: mutationId,
+      sourcePresetId: "launch-night",
+      idempotent: false,
+    });
+
+    const invalidStore = new PresetHandlerStore();
+    expect((await postPresetApply(request("/api/presets/apply?event=Launch", {
+      method: "POST",
+      body,
+    }), { store: invalidStore, adminKey: "admin" })).status).toBe(400);
+    expect(invalidStore.calls).toEqual([]);
+
+    store.applyError = new EventPresetNotFoundError("launch-night");
+    expect((await postPresetApply(request("/api/presets/apply?event=launch", {
+      method: "POST",
+      body,
+    }), { store, adminKey: "admin" })).status).toBe(404);
+    store.applyError = new ConfigConflictError(null, mutationId);
+    expect((await postPresetApply(request("/api/presets/apply?event=launch", {
+      method: "POST",
+      body,
+    }), { store, adminKey: "admin" })).status).toBe(409);
+  });
+});
diff --git a/app/api/presets/handlers.ts b/app/api/presets/handlers.ts
new file mode 100644
index 0000000..1a6369d
--- /dev/null
+++ b/app/api/presets/handlers.ts
@@ -0,0 +1,232 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  ConfigConflictError,
+  ConfigMutationConflictError,
+  EventPresetNotFoundError,
+  EventStore,
+  InvalidEventSlugError,
+  PresetConflictError,
+} from "@/app/event-store";
+import {
+  isRevisionId,
+  parseEventExperience,
+  projectPublicConfig,
+} from "@/app/event-config";
+import { isPresetId, type EventPreset } from "@/app/event-preset";
+import { adminOk } from "@/app/upload-auth";
+
+export type PresetHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+};
+
+const json = (body: unknown, init?: ResponseInit) =>
+  NextResponse.json(body, {
+    ...init,
+    headers: { ...init?.headers, "Cache-Control": "no-store" },
+  });
+
+const errorResponse = (error: string, status: number) =>
+  json({ error }, { status });
+
+function authorize(req: NextRequest, deps: PresetHandlerDeps): NextResponse | null {
+  if (!deps.adminKey) return errorResponse("presets disabled: no key configured", 503);
+  return adminOk(req.headers.get("x-booth-key") ?? "", deps.adminKey) === "ok"
+    ? null
+    : errorResponse("unauthorized", 401);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length
+    && actual.every((key, index) => key === expected[index]);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const allowed = new Set(keys);
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function isStrictExperience(value: unknown): boolean {
+  if (
+    !isRecord(value)
+    || !hasOnlyKeys(value, [
+      "frames",
+      "locales",
+      "defaultLocale",
+      "timeZone",
+      "capture",
+      "gallery",
+    ])
+  ) {
+    return false;
+  }
+  if (
+    value.capture !== undefined
+    && (
+      !isRecord(value.capture)
+      || !hasOnlyKeys(value.capture, [
+        "reviewEnabled",
+        "autoAcceptSeconds",
+        "countdownAudioDefault",
+      ])
+    )
+  ) {
+    return false;
+  }
+  return value.gallery === undefined
+    || (
+      isRecord(value.gallery)
+      && hasOnlyKeys(value.gallery, ["title", "accentColor"])
+    );
+}
+
+function safePreset(preset: EventPreset): EventPreset {
+  return {
+    version: 1,
+    id: preset.id,
+    label: preset.label,
+    createdAt: preset.createdAt,
+    updatedAt: preset.updatedAt,
+    config: {
+      frames: [...preset.config.frames],
+      ...(preset.config.locales ? { locales: [...preset.config.locales] } : {}),
+      ...(preset.config.defaultLocale ? { defaultLocale: preset.config.defaultLocale } : {}),
+      ...(preset.config.timeZone ? { timeZone: preset.config.timeZone } : {}),
+      ...(preset.config.capture ? { capture: { ...preset.config.capture } } : {}),
+      ...(preset.config.gallery ? { gallery: { ...preset.config.gallery } } : {}),
+    },
+  };
+}
+
+export async function getPresets(
+  req: NextRequest,
+  deps: PresetHandlerDeps,
+): Promise<NextResponse> {
+  const rejected = authorize(req, deps);
+  if (rejected) return rejected;
+  const params = req.nextUrl.searchParams;
+  if (Array.from(params.keys()).some((key) => key !== "cursor" && key !== "limit")) {
+    return errorResponse("invalid preset query", 400);
+  }
+  if (params.getAll("cursor").length > 1 || params.getAll("limit").length > 1) {
+    return errorResponse("invalid preset query", 400);
+  }
+  const rawLimit = params.get("limit");
+  if (rawLimit !== null && !/^(?:[1-9]|[1-9][0-9]|100)$/.test(rawLimit)) {
+    return errorResponse("invalid preset limit", 400);
+  }
+  try {
+    const page = await deps.store.listEventPresets({
+      ...(params.has("cursor") ? { cursor: params.get("cursor")! } : {}),
+      limit: rawLimit === null ? 50 : Number(rawLimit),
+    });
+    return json({
+      presets: page.presets.map(safePreset),
+      cursor: page.cursor,
+    });
+  } catch (error) {
+    if (error instanceof TypeError) return errorResponse("invalid preset query", 400);
+    throw error;
+  }
+}
+
+export async function putPreset(
+  req: NextRequest,
+  presetId: string,
+  deps: PresetHandlerDeps,
+): Promise<NextResponse> {
+  const rejected = authorize(req, deps);
+  if (rejected) return rejected;
+  if (!isPresetId(presetId)) return errorResponse("invalid preset ID", 400);
+  const value = await req.json().catch(() => null);
+  if (!isRecord(value) || !hasExactKeys(value, ["label", "config", "expectedUpdatedAt"])) {
+    return errorResponse("invalid preset request", 400);
+  }
+  const config = isStrictExperience(value.config)
+    ? parseEventExperience(value.config)
+    : null;
+  if (
+    typeof value.label !== "string"
+    || !config
+    || (
+      value.expectedUpdatedAt !== null
+      && typeof value.expectedUpdatedAt !== "string"
+    )
+  ) {
+    return errorResponse("invalid preset request", 400);
+  }
+  try {
+    return json(safePreset(await deps.store.putEventPreset(presetId, {
+      label: value.label,
+      config,
+      expectedUpdatedAt: value.expectedUpdatedAt,
+    })));
+  } catch (error) {
+    if (error instanceof PresetConflictError) {
+      return errorResponse("preset conflict", 409);
+    }
+    if (error instanceof TypeError) return errorResponse("invalid preset request", 400);
+    throw error;
+  }
+}
+
+export async function postPresetApply(
+  req: NextRequest,
+  deps: PresetHandlerDeps,
+): Promise<NextResponse> {
+  const rejected = authorize(req, deps);
+  if (rejected) return rejected;
+  const params = req.nextUrl.searchParams;
+  if (
+    Array.from(params.keys()).some((key) => key !== "event")
+    || params.getAll("event").length !== 1
+  ) {
+    return errorResponse("invalid preset apply query", 400);
+  }
+  let event: string;
+  try {
+    event = canonicalEvent(params.get("event"));
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) return errorResponse(error.message, 400);
+    throw error;
+  }
+  const value = await req.json().catch(() => null);
+  if (
+    !isRecord(value)
+    || !hasExactKeys(value, ["presetId", "mutationId", "baseRevisionId"])
+    || !isPresetId(value.presetId)
+    || !isRevisionId(value.mutationId)
+    || (value.baseRevisionId !== null && !isRevisionId(value.baseRevisionId))
+  ) {
+    return errorResponse("invalid preset apply request", 400);
+  }
+  try {
+    const result = await deps.store.applyEventPreset(event, {
+      presetId: value.presetId,
+      mutationId: value.mutationId,
+      baseRevisionId: value.baseRevisionId,
+    });
+    return json({
+      ...projectPublicConfig(result.config),
+      currentRevisionId: result.revision.id,
+      sourcePresetId: value.presetId,
+      idempotent: result.idempotent,
+    });
+  } catch (error) {
+    if (error instanceof EventPresetNotFoundError) {
+      return errorResponse("preset not found", 404);
+    }
+    if (error instanceof ConfigConflictError || error instanceof ConfigMutationConflictError) {
+      return errorResponse("configuration conflict", 409);
+    }
+    if (error instanceof TypeError) return errorResponse("invalid preset apply request", 400);
+    throw error;
+  }
+}
diff --git a/app/api/presets/route.ts b/app/api/presets/route.ts
new file mode 100644
index 0000000..32ac0fe
--- /dev/null
+++ b/app/api/presets/route.ts
@@ -0,0 +1,14 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { getPresets } from "./handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return getPresets(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 234ecef..a71c203 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -4,6 +4,7 @@ import {
   ConfigConflictError,
   ConfigMutationConflictError,
   ConfigRevisionNotFoundError,
+  EventPresetNotFoundError,
   EventStore,
   InMemoryObjectStore,
   InvalidEventSlugError,
@@ -2748,6 +2749,82 @@ describe("EventStore", () => {
       ]);
     });
 
+    test("applies a preset through the shared revision head while preserving credentials", async () => {
+      const store = new EventStore(
+        new InMemoryObjectStore(),
+        new InMemoryObjectStore(),
+        "https://photos.example",
+        () => new Date("2026-07-24T00:00:00.000Z"),
+      );
+      const current = await store.saveConfigRevision("launch", {
+        config: { frames: ["old"], boothKeyHash: "stored-secret-hash" },
+        baseRevisionId: null,
+        mutationId: "018f0000-0000-4000-8000-000000000201",
+        boothKeyMutationFingerprint: "a".repeat(64),
+      });
+      await store.putEventPreset("launch-night", {
+        label: "Launch Night",
+        config: experience,
+        expectedUpdatedAt: null,
+      });
+      const input = {
+        presetId: "launch-night",
+        mutationId: "018f0000-0000-4000-8000-000000000202",
+        baseRevisionId: current.revision.id,
+      };
+
+      const applied = await store.applyEventPreset("launch", input);
+      const retried = await store.applyEventPreset("launch", input);
+
+      expect(applied.idempotent).toBeFalse();
+      expect(retried.idempotent).toBeTrue();
+      expect(applied.revision).toMatchObject({
+        id: input.mutationId,
+        reason: "preset",
+        sourcePresetId: "launch-night",
+        config: experience,
+      });
+      expect(applied.config).toMatchObject({
+        ...experience,
+        boothKeyHash: "stored-secret-hash",
+        currentRevisionId: input.mutationId,
+      });
+      expect(JSON.stringify(applied.revision)).not.toContain("stored-secret-hash");
+    });
+
+    test("binds preset content to its retry intent and rejects a missing preset", async () => {
+      const store = new EventStore(
+        new InMemoryObjectStore(),
+        new InMemoryObjectStore(),
+        "https://photos.example",
+        () => new Date("2026-07-24T00:00:00.000Z"),
+      );
+      await expect(store.applyEventPreset("launch", {
+        presetId: "missing",
+        mutationId: "018f0000-0000-4000-8000-000000000203",
+        baseRevisionId: null,
+      })).rejects.toBeInstanceOf(EventPresetNotFoundError);
+
+      const created = await store.putEventPreset("launch-night", {
+        label: "Launch Night",
+        config: experience,
+        expectedUpdatedAt: null,
+      });
+      const input = {
+        presetId: "launch-night",
+        mutationId: "018f0000-0000-4000-8000-000000000204",
+        baseRevisionId: null,
+      };
+      await store.applyEventPreset("launch", input);
+      await store.putEventPreset("launch-night", {
+        label: "Launch Night Updated",
+        config: { ...experience, frames: ["square"] },
+        expectedUpdatedAt: created.updatedAt,
+      });
+      await expect(store.applyEventPreset("launch", input))
+        .rejects.toBeInstanceOf(ConfigMutationConflictError);
+    });
+
     test("fails explicitly for corrupt stored presets and never offers deletion", async () => {
       const state = new InMemoryObjectStore({
         [eventPresetIndexKey(
diff --git a/app/event-store.ts b/app/event-store.ts
index 84e8769..ed87133 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -71,21 +71,28 @@ export type ConfigRestoreInput = {
   baseRevisionId: string | null;
   mutationId: string;
 };
+export type ConfigPresetApplyInput = {
+  presetId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+};
 type ConfigMutationIntent = {
   version: typeof EVENT_CONFIG_VERSION;
   config: EventExperience;
   baseRevisionId: string | null;
   boothKeyMutationFingerprint: string | null;
-  reason: "save" | "restore";
+  reason: "save" | "restore" | "preset";
   sourceRevisionId?: string;
+  sourcePresetId?: string;
 };
 type ConfigAppendInput = {
   config: EventConfig;
   baseRevisionId: string | null;
   mutationId: string;
   boothKeyMutationFingerprint: string | null;
-  reason: "save" | "restore";
+  reason: "save" | "restore" | "preset";
   sourceRevisionId?: string;
+  sourcePresetId?: string;
 };
 
 export type StoredObject = {
@@ -478,6 +485,12 @@ export class PresetConflictError extends Error {
   }
 }
 
+export class EventPresetNotFoundError extends Error {
+  constructor(readonly presetId: string) {
+    super(`Event preset ${presetId} was not found`);
+  }
+}
+
 export class PhotoIndexWriteError extends Error {
   constructor(
     readonly photo: Pick<PutPhotoResult, "key" | "url" | "duplicate">,
@@ -810,6 +823,29 @@ export class EventStore {
     });
   }
 
+  async applyEventPreset(
+    event: string,
+    input: ConfigPresetApplyInput,
+  ): Promise<ConfigMutationResult> {
+    if (
+      !isPresetId(input.presetId)
+      || !isRevisionId(input.mutationId)
+      || (input.baseRevisionId !== null && !isRevisionId(input.baseRevisionId))
+    ) {
+      throw new TypeError("invalid preset application");
+    }
+    const preset = await this.getEventPreset(input.presetId);
+    if (!preset) throw new EventPresetNotFoundError(input.presetId);
+    return this.appendConfigRevision(canonicalEvent(event), {
+      config: preset.config,
+      baseRevisionId: input.baseRevisionId,
+      mutationId: input.mutationId,
+      boothKeyMutationFingerprint: null,
+      reason: "preset",
+      sourcePresetId: preset.id,
+    });
+  }
+
   private async appendConfigRevision(
     event: string,
     input: ConfigAppendInput
@@ -823,7 +859,8 @@ export class EventStore {
       input.baseRevisionId,
       input.boothKeyMutationFingerprint,
       input.reason,
-      input.sourceRevisionId
+      input.sourceRevisionId,
+      input.sourcePresetId,
     );
     const existing = await this.readRevision(event, input.mutationId);
 
@@ -864,6 +901,7 @@ export class EventStore {
       parentRevisionId,
       reason: input.reason,
       ...(input.sourceRevisionId ? { sourceRevisionId: input.sourceRevisionId } : {}),
+      ...(input.sourcePresetId ? { sourcePresetId: input.sourcePresetId } : {}),
       config: requestedExperience,
     };
     const appended = await this.state.compareAndSwap(
@@ -1946,8 +1984,9 @@ export class EventStore {
     config: EventExperience,
     baseRevisionId: string | null,
     boothKeyMutationFingerprint: string | null,
-    reason: "save" | "restore",
-    sourceRevisionId?: string
+    reason: "save" | "restore" | "preset",
+    sourceRevisionId?: string,
+    sourcePresetId?: string,
   ): Promise<void> {
     const intent: ConfigMutationIntent = {
       version: EVENT_CONFIG_VERSION,
@@ -1956,6 +1995,7 @@ export class EventStore {
       boothKeyMutationFingerprint,
       reason,
       ...(sourceRevisionId ? { sourceRevisionId } : {}),
+      ...(sourcePresetId ? { sourcePresetId } : {}),
     };
     const key = eventConfigMutationKey(event, mutationId);
     const created = await this.state.compareAndSwap(
@@ -1981,6 +2021,7 @@ export class EventStore {
       || parsed.boothKeyMutationFingerprint !== boothKeyMutationFingerprint
       || parsed.reason !== reason
       || parsed.sourceRevisionId !== sourceRevisionId
+      || parsed.sourcePresetId !== sourcePresetId
       || !sameExperience(parsed.config, config)
     ) {
       throw new ConfigMutationConflictError();
@@ -2023,7 +2064,7 @@ export class EventStore {
       revision.id !== input.mutationId
       || revision.reason !== input.reason
       || revision.sourceRevisionId !== input.sourceRevisionId
-      || revision.sourcePresetId !== undefined
+      || revision.sourcePresetId !== input.sourcePresetId
       || !sameExperience(revision.config, requested)
     ) {
       throw new ConfigMutationConflictError();
@@ -2127,11 +2168,19 @@ function parseConfigMutationIntent(value: unknown): ConfigMutationIntent | null
   const reason = intent.reason;
   if (
     intent.version !== EVENT_CONFIG_VERSION
-    || (reason !== "save" && reason !== "restore")
+    || (reason !== "save" && reason !== "restore" && reason !== "preset")
     || (
       reason === "save"
-        ? Object.keys(intent).length !== 5 || "sourceRevisionId" in intent
-        : Object.keys(intent).length !== 6 || !isRevisionId(intent.sourceRevisionId)
+        ? Object.keys(intent).length !== 5
+          || "sourceRevisionId" in intent
+          || "sourcePresetId" in intent
+        : reason === "restore"
+          ? Object.keys(intent).length !== 6
+            || !isRevisionId(intent.sourceRevisionId)
+            || "sourcePresetId" in intent
+          : Object.keys(intent).length !== 6
+            || !isPresetId(intent.sourcePresetId)
+            || "sourceRevisionId" in intent
     )
     || (
       intent.baseRevisionId !== null
@@ -2167,6 +2216,7 @@ function parseConfigMutationIntent(value: unknown): ConfigMutationIntent | null
     boothKeyMutationFingerprint: intent.boothKeyMutationFingerprint as string | null,
     reason,
     ...(reason === "restore" ? { sourceRevisionId: intent.sourceRevisionId as string } : {}),
+    ...(reason === "preset" ? { sourcePresetId: intent.sourcePresetId as string } : {}),
   };
 }
 

From c49454a7188b823b47733e875cf607e6bfd8ef80 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:46:26 +0800
Subject: [PATCH 082/105] feat: add preset admin state

---
 app/[event]/admin/preset-state.test.ts | 95 ++++++++++++++++++++++++++
 app/[event]/admin/preset-state.ts      | 78 +++++++++++++++++++++
 2 files changed, 173 insertions(+)
 create mode 100644 app/[event]/admin/preset-state.test.ts
 create mode 100644 app/[event]/admin/preset-state.ts

diff --git a/app/[event]/admin/preset-state.test.ts b/app/[event]/admin/preset-state.test.ts
new file mode 100644
index 0000000..7c18e5c
--- /dev/null
+++ b/app/[event]/admin/preset-state.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import type { EventPreset } from "../../event-preset";
+import {
+  getOrCreatePresetApply,
+  mergePresetPage,
+  reconcileAppliedPreset,
+} from "./preset-state";
+
+const preset = (id: string, label: string, updatedAt = "2026-07-24T00:00:00.000Z"): EventPreset => ({
+  version: 1,
+  id,
+  label,
+  createdAt: "2026-07-24T00:00:00.000Z",
+  updatedAt,
+  config: { frames: [id] },
+});
+
+describe("Admin preset state", () => {
+  test("deduplicates exact IDs, keeps updates, and globally orders label then ID", () => {
+    expect(mergePresetPage(
+      [preset("z", "Beta"), preset("a", "Alpha")],
+      [preset("z", "Aardvark", "2026-07-24T01:00:00.000Z"), preset("b", "Alpha")],
+    ).map(({ id, label }) => [id, label])).toEqual([
+      ["z", "Aardvark"],
+      ["a", "Alpha"],
+      ["b", "Alpha"],
+    ]);
+  });
+
+  test("retains the exact retry tuple until the base changes", () => {
+    const pending = new Map();
+    let next = 0;
+    const makeId = () => `id-${++next}`;
+    const first = getOrCreatePresetApply(pending, "launch", null, makeId);
+    expect(getOrCreatePresetApply(pending, "launch", null, makeId)).toBe(first);
+    const rebased = getOrCreatePresetApply(pending, "launch", "revision-2", makeId);
+    expect(rebased).not.toBe(first);
+    expect(rebased).toEqual({
+      presetId: "launch",
+      mutationId: "id-2",
+      baseRevisionId: "revision-2",
+    });
+  });
+
+  test("rebases the complete authoritative experience and rejects stale responses", () => {
+    const revisionId = "018f0000-0000-4000-8000-000000000401";
+    const config = {
+      frames: ["square"],
+      locales: ["en", "ar"],
+      defaultLocale: "ar",
+      timeZone: "Asia/Singapore",
+      capture: {
+        reviewEnabled: false,
+        autoAcceptSeconds: 8,
+        countdownAudioDefault: true,
+      },
+      gallery: { title: "Night", accentColor: "#112233" },
+      hasBoothKey: true,
+    };
+    const history = {
+      config,
+      currentRevisionId: revisionId,
+      revisions: [{
+        version: 1 as const,
+        id: revisionId,
+        createdAt: "2026-07-24T00:00:00.000Z",
+        parentRevisionId: null,
+        reason: "preset" as const,
+        sourcePresetId: "launch",
+        config: { ...config, hasBoothKey: undefined },
+      }],
+    };
+    expect(reconcileAppliedPreset({
+      response: { ...config, currentRevisionId: revisionId },
+      history,
+      sourcePresetId: "launch",
+    })).toEqual({
+      experience: {
+        frames: ["square"],
+        locales: ["en", "ar"],
+        defaultLocale: "ar",
+        timeZone: "Asia/Singapore",
+        capture: config.capture,
+        gallery: config.gallery,
+      },
+      currentRevisionId: revisionId,
+      hasBoothKey: true,
+    });
+    expect(() => reconcileAppliedPreset({
+      response: { ...config, currentRevisionId: revisionId },
+      history: { ...history, currentRevisionId: null },
+      sourcePresetId: "launch",
+    })).toThrow("stale");
+  });
+});
diff --git a/app/[event]/admin/preset-state.ts b/app/[event]/admin/preset-state.ts
new file mode 100644
index 0000000..e5bde44
--- /dev/null
+++ b/app/[event]/admin/preset-state.ts
@@ -0,0 +1,78 @@
+import type { EventExperience, PublicEventConfig } from "../../event-config";
+import type { EventPreset } from "../../event-preset";
+import type { ConfigHistoryResponse } from "./config-mutation";
+
+export type PendingPresetApply = Readonly<{
+  presetId: string;
+  mutationId: string;
+  baseRevisionId: string | null;
+}>;
+
+export function mergePresetPage(
+  current: readonly EventPreset[],
+  incoming: readonly EventPreset[],
+): EventPreset[] {
+  const byId = new Map(current.map((preset) => [preset.id, preset]));
+  for (const preset of incoming) byId.set(preset.id, preset);
+  return [...byId.values()].sort((left, right) =>
+    left.label < right.label
+      ? -1
+      : left.label > right.label
+        ? 1
+        : left.id < right.id
+          ? -1
+          : left.id > right.id
+            ? 1
+            : 0
+  );
+}
+
+export function getOrCreatePresetApply(
+  pending: Map<string, PendingPresetApply>,
+  presetId: string,
+  baseRevisionId: string | null,
+  makeId: () => string,
+): PendingPresetApply {
+  const retained = pending.get(presetId);
+  if (retained?.baseRevisionId === baseRevisionId) return retained;
+  const created = Object.freeze({
+    presetId,
+    mutationId: makeId(),
+    baseRevisionId,
+  });
+  pending.set(presetId, created);
+  return created;
+}
+
+export function reconcileAppliedPreset(input: {
+  response: PublicEventConfig & { currentRevisionId: string };
+  history: ConfigHistoryResponse;
+  sourcePresetId: string;
+}): {
+  experience: EventExperience;
+  currentRevisionId: string;
+  hasBoothKey: boolean;
+} {
+  const head = input.history.revisions.find(
+    (revision) => revision.id === input.history.currentRevisionId,
+  );
+  if (
+    input.history.currentRevisionId !== input.response.currentRevisionId
+    || head?.reason !== "preset"
+    || head.sourcePresetId !== input.sourcePresetId
+    || input.history.config.frames === null
+    || input.history.config.hasBoothKey !== input.response.hasBoothKey
+  ) {
+    throw new TypeError("preset application response is stale");
+  }
+  const {
+    hasBoothKey,
+    frames,
+    ...rest
+  } = input.history.config;
+  return {
+    experience: { ...rest, frames: [...frames] },
+    currentRevisionId: input.history.currentRevisionId,
+    hasBoothKey,
+  };
+}

From 06d708e9025575529354f0acc38adb0744879c24 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:49:00 +0800
Subject: [PATCH 083/105] feat: define rehearsal evidence reduction

---
 app/rehearsal.test.ts | 174 ++++++++++++++
 app/rehearsal.ts      | 540 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 714 insertions(+)
 create mode 100644 app/rehearsal.test.ts
 create mode 100644 app/rehearsal.ts

diff --git a/app/rehearsal.test.ts b/app/rehearsal.test.ts
new file mode 100644
index 0000000..729ed87
--- /dev/null
+++ b/app/rehearsal.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import {
+  parseRehearsalEvidence,
+  parseRehearsalSession,
+  reduceRehearsal,
+  type RehearsalEvidence,
+  type RehearsalSession,
+} from "./rehearsal";
+
+const rehearsalId = "018f0000-0000-4000-8000-000000000501";
+const deviceId = "018f0000-0000-4000-8000-000000000502";
+const firstBoot = "018f0000-0000-4000-8000-000000000503";
+const secondBoot = "018f0000-0000-4000-8000-000000000504";
+const firstCapture = "018f0000-0000-4000-8000-000000000505";
+const secondCapture = "018f0000-0000-4000-8000-000000000506";
+const revisionId = "018f0000-0000-4000-8000-000000000507";
+type EvidenceDetails = RehearsalEvidence extends infer Evidence
+  ? Evidence extends RehearsalEvidence
+    ? Omit<Evidence, "version" | "id" | "rehearsalId" | "observedAt" | "recordedAt">
+    : never
+  : never;
+
+const session: RehearsalSession = {
+  version: 1,
+  id: rehearsalId,
+  startedAt: "2026-07-24T00:00:00.000Z",
+  configRevisionId: revisionId,
+  frames: ["square", "strip"],
+};
+
+function evidence(
+  index: number,
+  value: EvidenceDetails,
+): RehearsalEvidence {
+  return {
+    version: 1,
+    id: `018f0000-0000-4000-8000-${String(600 + index).padStart(12, "0")}`,
+    rehearsalId,
+    observedAt: 1_753_315_200_000 + index,
+    recordedAt: new Date(1_753_315_200_000 + index).toISOString(),
+    ...value,
+  } as RehearsalEvidence;
+}
+
+describe("rehearsal schemas", () => {
+  test("strictly parses sessions and rejects unsafe expansion", () => {
+    expect(parseRehearsalSession(session)).toEqual(session);
+    for (const invalid of [
+      { ...session, id: rehearsalId.toUpperCase() },
+      { ...session, frames: ["../unsafe"] },
+      { ...session, boothKeyHash: "secret" },
+      { ...session, version: 2 },
+    ]) {
+      expect(parseRehearsalSession(invalid)).toBeNull();
+    }
+  });
+
+  test("strictly parses Event-owned evidence and rejects arbitrary diagnostics", () => {
+    const valid = evidence(1, {
+      kind: "photo-acknowledged",
+      captureId: firstCapture,
+      capturedAt: 1_753_315_200_000,
+      frameKey: "square",
+      photoKey: "launch/1753315200000-a.jpg",
+    });
+    expect(parseRehearsalEvidence(valid, "launch")).toEqual(valid);
+    expect(parseRehearsalEvidence({ ...valid, photoKey: "other/1753315200000-a.jpg" }, "launch")).toBeNull();
+    expect(parseRehearsalEvidence({ ...valid, error: "private stack" }, "launch")).toBeNull();
+  });
+});
+
+describe("rehearsal completion", () => {
+  test("requires the complete ordered recovery, delivery, canary, and outbox story", () => {
+    const firstKey = "launch/1753315200000-a.jpg";
+    const secondKey = "launch/1753315200001-b.jpg";
+    const records: RehearsalEvidence[] = [
+      evidence(1, {
+        kind: "booth-ready",
+        deviceId,
+        bootId: firstBoot,
+        cameraReady: true,
+        durableStorage: true,
+      }),
+      evidence(2, { kind: "network-failure", captureId: firstCapture, bootId: firstBoot, errorClass: "network" }),
+      evidence(3, { kind: "network-failure", captureId: secondCapture, bootId: firstBoot, errorClass: "timeout" }),
+      evidence(4, {
+        kind: "outbox-recovered",
+        previousBootId: firstBoot,
+        bootId: secondBoot,
+        captureIds: [firstCapture, secondCapture],
+      }),
+      evidence(5, {
+        kind: "photo-acknowledged",
+        captureId: firstCapture,
+        capturedAt: 1_753_315_200_000,
+        frameKey: "square",
+        photoKey: firstKey,
+      }),
+      evidence(6, {
+        kind: "photo-acknowledged",
+        captureId: secondCapture,
+        capturedAt: 1_753_315_200_001,
+        frameKey: "strip",
+        photoKey: secondKey,
+      }),
+      evidence(7, { kind: "ordered-drain", bootId: secondBoot, captureIds: [firstCapture, secondCapture] }),
+      evidence(8, { kind: "delivery-observed", photoKey: firstKey, feedObserved: true, publicImageObserved: true }),
+      evidence(9, { kind: "canary-designated", photoKey: firstKey }),
+      evidence(10, { kind: "canary-deleted", photoKey: firstKey, cleanupPending: true }),
+      evidence(11, { kind: "outbox-empty", bootId: secondBoot, pendingCount: 0 }),
+      evidence(12, { kind: "photo-retained", photoKey: secondKey }),
+      evidence(13, { kind: "manual-check", check: "power" }),
+    ];
+    const summary = reduceRehearsal({
+      session,
+      evidence: records,
+      currentRevisionId: revisionId,
+    });
+    expect(summary.status).toBe("complete");
+    expect(Object.values(summary.requirements).every(({ complete }) => complete)).toBeTrue();
+    expect(summary.manualChecks.power).toBeTrue();
+    expect(summary.remainingExactKeys).toEqual([]);
+    expect(summary.trackedPhotos).toEqual([
+      {
+        captureId: firstCapture,
+        frameKey: "square",
+        photoKey: firstKey,
+        disposition: "canary-deleted",
+      },
+      {
+        captureId: secondCapture,
+        frameKey: "strip",
+        photoKey: secondKey,
+        disposition: "retained",
+      },
+    ]);
+  });
+
+  test("does not overcount duplicates, fallback frames, mismatched recovery, or stale sessions", () => {
+    const failed = evidence(1, {
+      kind: "network-failure",
+      captureId: firstCapture,
+      bootId: firstBoot,
+      errorClass: "network",
+    });
+    const summary = reduceRehearsal({
+      session,
+      evidence: [
+        failed,
+        { ...failed, id: "018f0000-0000-4000-8000-000000000699" },
+        evidence(2, {
+          kind: "outbox-recovered",
+          previousBootId: firstBoot,
+          bootId: firstBoot,
+          captureIds: [firstCapture],
+        }),
+        evidence(3, {
+          kind: "photo-acknowledged",
+          captureId: firstCapture,
+          capturedAt: 1_753_315_200_000,
+          photoKey: "launch/1753315200000-a.jpg",
+        }),
+        evidence(4, { kind: "abandoned" }),
+      ],
+      currentRevisionId: null,
+    });
+    expect(summary.requirements["two-network-failures"].complete).toBeFalse();
+    expect(summary.requirements["frames-covered"].complete).toBeFalse();
+    expect(summary.requirements["reload-recovered"].complete).toBeFalse();
+    expect(summary.status).toBe("abandoned");
+    expect(summary.stale).toBeTrue();
+    expect(summary.remainingExactKeys).toEqual(["launch/1753315200000-a.jpg"]);
+  });
+});
diff --git a/app/rehearsal.ts b/app/rehearsal.ts
new file mode 100644
index 0000000..6bff4ea
--- /dev/null
+++ b/app/rehearsal.ts
@@ -0,0 +1,540 @@
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const IMAGE_EXTENSION = /\.(?:jpe?g|png|gif|webp|hei[cf]|avif)$/i;
+const MAX_IDS = 256;
+
+export type RehearsalSession = {
+  version: 1;
+  id: string;
+  startedAt: string;
+  configRevisionId: string | null;
+  frames: string[];
+};
+
+type RehearsalEvidenceBase = {
+  version: 1;
+  id: string;
+  rehearsalId: string;
+  observedAt: number;
+  recordedAt: string;
+};
+
+export type RehearsalEvidence =
+  | (RehearsalEvidenceBase & {
+      kind: "booth-ready";
+      deviceId: string;
+      bootId: string;
+      cameraReady: true;
+      durableStorage: true;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "network-failure";
+      captureId: string;
+      bootId: string;
+      errorClass: "network" | "timeout";
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "outbox-recovered";
+      previousBootId: string;
+      bootId: string;
+      captureIds: string[];
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "photo-acknowledged";
+      captureId: string;
+      capturedAt: number;
+      frameKey?: string;
+      photoKey: string;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "ordered-drain";
+      bootId: string;
+      captureIds: string[];
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "delivery-observed";
+      photoKey: string;
+      feedObserved: true;
+      publicImageObserved: true;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "canary-designated";
+      photoKey: string;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "canary-deleted";
+      photoKey: string;
+      cleanupPending: boolean;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "outbox-empty";
+      bootId: string;
+      pendingCount: 0;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "photo-retained" | "photo-deleted";
+      photoKey: string;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "manual-check";
+      check: ManualCheck;
+    })
+  | (RehearsalEvidenceBase & {
+      kind: "abandoned";
+    });
+
+export type RehearsalEvidenceInput = RehearsalEvidence extends infer Evidence
+  ? Evidence extends RehearsalEvidence
+    ? Omit<Evidence, "recordedAt">
+    : never
+  : never;
+
+export type RehearsalRequirement =
+  | "booth-ready"
+  | "frames-covered"
+  | "two-network-failures"
+  | "reload-recovered"
+  | "ordered-drain"
+  | "public-delivery"
+  | "canary-deleted"
+  | "outbox-empty";
+
+export type ManualCheck =
+  | "composition"
+  | "projector"
+  | "power"
+  | "charging"
+  | "backup-network";
+
+export type RehearsalSummary = {
+  status: "active" | "stale" | "complete" | "abandoned";
+  stale: boolean;
+  requirements: Record<RehearsalRequirement, {
+    complete: boolean;
+    evidenceIds: string[];
+  }>;
+  manualChecks: Record<ManualCheck, boolean>;
+  trackedPhotos: {
+    captureId: string;
+    frameKey?: string;
+    photoKey: string;
+    disposition: "pending" | "canary-deleted" | "retained" | "deleted";
+  }[];
+  remainingExactKeys: string[];
+};
+
+const REQUIREMENTS: readonly RehearsalRequirement[] = [
+  "booth-ready",
+  "frames-covered",
+  "two-network-failures",
+  "reload-recovered",
+  "ordered-drain",
+  "public-delivery",
+  "canary-deleted",
+  "outbox-empty",
+];
+
+const MANUAL_CHECKS: readonly ManualCheck[] = [
+  "composition",
+  "projector",
+  "power",
+  "charging",
+  "backup-network",
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const sorted = [...expected].sort();
+  return actual.length === sorted.length
+    && actual.every((key, index) => key === sorted[index]);
+}
+
+function isUuid(value: unknown): value is string {
+  return typeof value === "string" && UUID_V4.test(value);
+}
+
+function isTimestamp(value: unknown): value is number {
+  return typeof value === "number"
+    && Number.isSafeInteger(value)
+    && value >= 1_000_000_000_000
+    && value <= 9_999_999_999_999;
+}
+
+function isStoredInstant(value: unknown): value is string {
+  if (
+    typeof value !== "string"
+    || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+  ) {
+    return false;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+
+function isIdList(value: unknown): value is string[] {
+  return Array.isArray(value)
+    && value.length <= MAX_IDS
+    && value.every(isUuid)
+    && new Set(value).size === value.length;
+}
+
+function isPhotoKey(value: unknown, event?: string): value is string {
+  if (typeof value !== "string") return false;
+  if (event !== undefined) {
+    const prefix = `${event}/`;
+    if (!value.startsWith(prefix)) return false;
+    const filename = value.slice(prefix.length);
+    return filename.length > 0
+      && !/[\/\\?#]/.test(filename)
+      && IMAGE_EXTENSION.test(filename);
+  }
+  const slash = value.indexOf("/");
+  return slash > 0
+    && TOKEN.test(value.slice(0, slash))
+    && !/[\/\\?#]/.test(value.slice(slash + 1))
+    && IMAGE_EXTENSION.test(value);
+}
+
+export function parseRehearsalSession(value: unknown): RehearsalSession | null {
+  if (
+    !isRecord(value)
+    || !hasExactKeys(value, [
+      "version",
+      "id",
+      "startedAt",
+      "configRevisionId",
+      "frames",
+    ])
+    || value.version !== 1
+    || !isUuid(value.id)
+    || !isStoredInstant(value.startedAt)
+    || (value.configRevisionId !== null && !isUuid(value.configRevisionId))
+    || !Array.isArray(value.frames)
+    || value.frames.length > MAX_IDS
+    || !value.frames.every((frame) => typeof frame === "string" && TOKEN.test(frame))
+    || new Set(value.frames).size !== value.frames.length
+  ) {
+    return null;
+  }
+  return {
+    version: 1,
+    id: value.id,
+    startedAt: value.startedAt,
+    configRevisionId: value.configRevisionId,
+    frames: [...value.frames],
+  };
+}
+
+export function parseRehearsalEvidence(
+  value: unknown,
+  event?: string,
+): RehearsalEvidence | null {
+  if (!isRecord(value) || typeof value.kind !== "string") return null;
+  const common = ["version", "id", "rehearsalId", "observedAt", "recordedAt", "kind"];
+  if (
+    value.version !== 1
+    || !isUuid(value.id)
+    || !isUuid(value.rehearsalId)
+    || !isTimestamp(value.observedAt)
+    || !isStoredInstant(value.recordedAt)
+  ) {
+    return null;
+  }
+
+  const base = {
+    version: 1 as const,
+    id: value.id,
+    rehearsalId: value.rehearsalId,
+    observedAt: value.observedAt,
+    recordedAt: value.recordedAt,
+  };
+  switch (value.kind) {
+    case "booth-ready":
+      if (
+        !hasExactKeys(value, [...common, "deviceId", "bootId", "cameraReady", "durableStorage"])
+        || !isUuid(value.deviceId)
+        || !isUuid(value.bootId)
+        || value.cameraReady !== true
+        || value.durableStorage !== true
+      ) return null;
+      return { ...base, kind: value.kind, deviceId: value.deviceId, bootId: value.bootId, cameraReady: true, durableStorage: true };
+    case "network-failure":
+      if (
+        !hasExactKeys(value, [...common, "captureId", "bootId", "errorClass"])
+        || !isUuid(value.captureId)
+        || !isUuid(value.bootId)
+        || (value.errorClass !== "network" && value.errorClass !== "timeout")
+      ) return null;
+      return { ...base, kind: value.kind, captureId: value.captureId, bootId: value.bootId, errorClass: value.errorClass };
+    case "outbox-recovered":
+      if (
+        !hasExactKeys(value, [...common, "previousBootId", "bootId", "captureIds"])
+        || !isUuid(value.previousBootId)
+        || !isUuid(value.bootId)
+        || !isIdList(value.captureIds)
+      ) return null;
+      return { ...base, kind: value.kind, previousBootId: value.previousBootId, bootId: value.bootId, captureIds: [...value.captureIds] };
+    case "photo-acknowledged": {
+      const keys = [...common, "captureId", "capturedAt", "photoKey"];
+      if (Object.hasOwn(value, "frameKey")) keys.push("frameKey");
+      if (
+        !hasExactKeys(value, keys)
+        || !isUuid(value.captureId)
+        || !isTimestamp(value.capturedAt)
+        || !isPhotoKey(value.photoKey, event)
+        || (
+          value.frameKey !== undefined
+          && (typeof value.frameKey !== "string" || !TOKEN.test(value.frameKey))
+        )
+      ) return null;
+      return {
+        ...base,
+        kind: value.kind,
+        captureId: value.captureId,
+        capturedAt: value.capturedAt,
+        ...(typeof value.frameKey === "string" ? { frameKey: value.frameKey } : {}),
+        photoKey: value.photoKey,
+      };
+    }
+    case "ordered-drain":
+      if (
+        !hasExactKeys(value, [...common, "bootId", "captureIds"])
+        || !isUuid(value.bootId)
+        || !isIdList(value.captureIds)
+      ) return null;
+      return { ...base, kind: value.kind, bootId: value.bootId, captureIds: [...value.captureIds] };
+    case "delivery-observed":
+      if (
+        !hasExactKeys(value, [...common, "photoKey", "feedObserved", "publicImageObserved"])
+        || !isPhotoKey(value.photoKey, event)
+        || value.feedObserved !== true
+        || value.publicImageObserved !== true
+      ) return null;
+      return { ...base, kind: value.kind, photoKey: value.photoKey, feedObserved: true, publicImageObserved: true };
+    case "canary-designated":
+      if (!hasExactKeys(value, [...common, "photoKey"]) || !isPhotoKey(value.photoKey, event)) return null;
+      return { ...base, kind: value.kind, photoKey: value.photoKey };
+    case "canary-deleted":
+      if (
+        !hasExactKeys(value, [...common, "photoKey", "cleanupPending"])
+        || !isPhotoKey(value.photoKey, event)
+        || typeof value.cleanupPending !== "boolean"
+      ) return null;
+      return { ...base, kind: value.kind, photoKey: value.photoKey, cleanupPending: value.cleanupPending };
+    case "outbox-empty":
+      if (
+        !hasExactKeys(value, [...common, "bootId", "pendingCount"])
+        || !isUuid(value.bootId)
+        || value.pendingCount !== 0
+      ) return null;
+      return { ...base, kind: value.kind, bootId: value.bootId, pendingCount: 0 };
+    case "photo-retained":
+    case "photo-deleted":
+      if (!hasExactKeys(value, [...common, "photoKey"]) || !isPhotoKey(value.photoKey, event)) return null;
+      return { ...base, kind: value.kind, photoKey: value.photoKey };
+    case "manual-check":
+      if (
+        !hasExactKeys(value, [...common, "check"])
+        || typeof value.check !== "string"
+        || !(MANUAL_CHECKS as readonly string[]).includes(value.check)
+      ) return null;
+      return { ...base, kind: value.kind, check: value.check as ManualCheck };
+    case "abandoned":
+      return hasExactKeys(value, common) ? { ...base, kind: value.kind } : null;
+    default:
+      return null;
+  }
+}
+
+function sameOrder(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+export function reduceRehearsal(input: {
+  session: RehearsalSession;
+  evidence: readonly RehearsalEvidence[];
+  currentRevisionId: string | null;
+}): RehearsalSummary {
+  const records = [...input.evidence].sort((left, right) =>
+    left.recordedAt.localeCompare(right.recordedAt) || left.id.localeCompare(right.id)
+  );
+  const requirements = Object.fromEntries(REQUIREMENTS.map((requirement) => [
+    requirement,
+    { complete: false, evidenceIds: [] as string[] },
+  ])) as RehearsalSummary["requirements"];
+  const manualChecks = Object.fromEntries(
+    MANUAL_CHECKS.map((check) => [check, false]),
+  ) as RehearsalSummary["manualChecks"];
+
+  const ready = records.filter((record) => record.kind === "booth-ready");
+  if (ready.length > 0) {
+    requirements["booth-ready"] = {
+      complete: true,
+      evidenceIds: ready.map(({ id }) => id),
+    };
+  }
+
+  const acknowledged = records.filter(
+    (record): record is Extract<RehearsalEvidence, { kind: "photo-acknowledged" }> =>
+      record.kind === "photo-acknowledged",
+  );
+  const acknowledgementsByCapture = new Map<string, typeof acknowledged[number]>();
+  const acknowledgementsByKey = new Map<string, typeof acknowledged[number]>();
+  for (const record of acknowledged) {
+    if (!acknowledgementsByCapture.has(record.captureId)) {
+      acknowledgementsByCapture.set(record.captureId, record);
+    }
+    if (!acknowledgementsByKey.has(record.photoKey)) {
+      acknowledgementsByKey.set(record.photoKey, record);
+    }
+  }
+  const frameEvidence = input.session.frames.map((frame) =>
+    acknowledged.find((record) => record.frameKey === frame)
+  );
+  if (frameEvidence.every(Boolean)) {
+    requirements["frames-covered"] = {
+      complete: true,
+      evidenceIds: [...new Set(frameEvidence.map((record) => record!.id))],
+    };
+  }
+
+  const failures = records.filter(
+    (record): record is Extract<RehearsalEvidence, { kind: "network-failure" }> =>
+      record.kind === "network-failure",
+  );
+  const failuresByCapture = new Map<string, typeof failures[number]>();
+  for (const failure of failures) {
+    if (!failuresByCapture.has(failure.captureId)) failuresByCapture.set(failure.captureId, failure);
+  }
+  const distinctFailures = [...failuresByCapture.values()];
+  if (distinctFailures.length >= 2) {
+    requirements["two-network-failures"] = {
+      complete: true,
+      evidenceIds: distinctFailures.map(({ id }) => id),
+    };
+  }
+
+  const recovered = records.filter(
+    (record): record is Extract<RehearsalEvidence, { kind: "outbox-recovered" }> =>
+      record.kind === "outbox-recovered",
+  );
+  const validRecovery = recovered.find((record) =>
+    distinctFailures.length >= 2
+    && distinctFailures.every((failure) =>
+      record.captureIds.includes(failure.captureId)
+      && record.bootId !== failure.bootId
+    )
+  );
+  if (validRecovery) {
+    requirements["reload-recovered"] = {
+      complete: true,
+      evidenceIds: [
+        ...distinctFailures.map(({ id }) => id),
+        validRecovery.id,
+      ],
+    };
+  }
+
+  const drains = records.filter(
+    (record): record is Extract<RehearsalEvidence, { kind: "ordered-drain" }> =>
+      record.kind === "ordered-drain",
+  );
+  const validDrain = validRecovery && drains.find((record) =>
+    record.bootId === validRecovery.bootId
+    && sameOrder(record.captureIds, validRecovery.captureIds)
+    && record.captureIds.every((captureId) => acknowledgementsByCapture.has(captureId))
+  );
+  if (validRecovery && validDrain) {
+    requirements["ordered-drain"] = {
+      complete: true,
+      evidenceIds: [
+        validRecovery.id,
+        validDrain.id,
+        ...validDrain.captureIds.map((captureId) => acknowledgementsByCapture.get(captureId)!.id),
+      ],
+    };
+  }
+
+  const delivery = records.find(
+    (record): record is Extract<RehearsalEvidence, { kind: "delivery-observed" }> =>
+      record.kind === "delivery-observed" && acknowledgementsByKey.has(record.photoKey),
+  );
+  if (delivery) {
+    requirements["public-delivery"] = {
+      complete: true,
+      evidenceIds: [acknowledgementsByKey.get(delivery.photoKey)!.id, delivery.id],
+    };
+  }
+
+  const designations = records.filter(
+    (record): record is Extract<RehearsalEvidence, { kind: "canary-designated" }> =>
+      record.kind === "canary-designated" && acknowledgementsByKey.has(record.photoKey),
+  );
+  const deletedCanary = records.find(
+    (record): record is Extract<RehearsalEvidence, { kind: "canary-deleted" }> =>
+      record.kind === "canary-deleted"
+      && designations.some((designation) => designation.photoKey === record.photoKey),
+  );
+  if (deletedCanary) {
+    const designation = designations.find(({ photoKey }) => photoKey === deletedCanary.photoKey)!;
+    requirements["canary-deleted"] = {
+      complete: true,
+      evidenceIds: [
+        acknowledgementsByKey.get(deletedCanary.photoKey)!.id,
+        designation.id,
+        deletedCanary.id,
+      ],
+    };
+  }
+
+  const empty = records.filter((record) => record.kind === "outbox-empty");
+  if (empty.length > 0) {
+    requirements["outbox-empty"] = {
+      complete: true,
+      evidenceIds: empty.map(({ id }) => id),
+    };
+  }
+  for (const record of records) {
+    if (record.kind === "manual-check") manualChecks[record.check] = true;
+  }
+
+  const retained = new Set(records.flatMap((record) =>
+    record.kind === "photo-retained" ? [record.photoKey] : []
+  ));
+  const deleted = new Set(records.flatMap((record) =>
+    record.kind === "photo-deleted" ? [record.photoKey] : []
+  ));
+  const trackedPhotos = [...acknowledgementsByCapture.values()].map((record) => {
+    const disposition = deletedCanary?.photoKey === record.photoKey
+      ? "canary-deleted" as const
+      : retained.has(record.photoKey)
+        ? "retained" as const
+        : deleted.has(record.photoKey)
+          ? "deleted" as const
+          : "pending" as const;
+    return {
+      captureId: record.captureId,
+      ...(record.frameKey ? { frameKey: record.frameKey } : {}),
+      photoKey: record.photoKey,
+      disposition,
+    };
+  });
+  const remainingExactKeys = trackedPhotos
+    .filter(({ disposition }) => disposition === "pending")
+    .map(({ photoKey }) => photoKey);
+  const stale = input.session.configRevisionId !== input.currentRevisionId;
+  const complete = REQUIREMENTS.every((requirement) => requirements[requirement].complete);
+  const abandoned = records.some((record) => record.kind === "abandoned");
+  return {
+    status: abandoned ? "abandoned" : stale ? "stale" : complete ? "complete" : "active",
+    stale,
+    requirements,
+    manualChecks,
+    trackedPhotos,
+    remainingExactKeys,
+  };
+}

From 5a2b6a22f5daa40b8022dc6f264b3928ee57dac4 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:48:32 +0800
Subject: [PATCH 084/105] test: verify guest capture and handoff

---
 docs/runbooks/deployment.md          |  25 +-
 docs/runbooks/pre-event-readiness.md |  57 +++
 tests/booth-control.spec.ts          |  13 +-
 tests/guest-capture.spec.ts          | 741 +++++++++++++++++++++++++++
 4 files changed, 832 insertions(+), 4 deletions(-)
 create mode 100644 tests/guest-capture.spec.ts

diff --git a/docs/runbooks/deployment.md b/docs/runbooks/deployment.md
index 5516bcc..ad29991 100644
--- a/docs/runbooks/deployment.md
+++ b/docs/runbooks/deployment.md
@@ -42,6 +42,21 @@ bun run test:browser
 bun run deploy:staging
 ```
 
+The full WebKit command includes `tests/guest-capture.spec.ts`. To diagnose
+only the Release 2 journey without contacting a deployed environment, run:
+
+```bash
+bun run test:browser -- tests/guest-capture.spec.ts
+```
+
+It must cover exact reviewed-canvas encoding for one-shot and multi-shot
+Frames, Retake and More Time, auto-accept, encode recovery, one-identity
+button/timer races, queued next-guest continuation, stale acknowledgement
+fencing, matching QR/text targets, direct-photo lookup, Event-scoped locale
+persistence and fallback, keyboard focus, reduced motion, forced colors,
+camera-file fallback, and optional-audio failure. Any request outside the
+local test origin is a test failure.
+
 Run the complete real-iPad section in `pre-event-readiness.md` with a
 throwaway canonical staging Event that is distinct from production. The
 automated WebKit journey does not prove real Safari camera permission,
@@ -49,13 +64,17 @@ orientation/crop, camera-indicator shutdown, Add-to-Home-Screen launch,
 standalone background/foreground behavior, Screen Wake Lock, IndexedDB
 survival across relaunch, Safari cross-tab leases, venue-network reconnect
 timing, real multi-shot pause timing, or camera/wake release during Operator
-exit.
+exit. It also cannot certify full-resolution canvas memory, Safari HEIC
+decode/orientation, Web Audio activation or silent-mode behavior, physical QR
+readability, VoiceOver timing, iOS suspension/eviction, Larger Text, or actual
+high-contrast rendering.
 
 Confirm staging photos do not appear in production and staging config does not
 affect production. For smoke-test moderation, delete only one complete
 Event-owned throwaway image key. Stop promotion on any failed real-device
-check. Only after recording a passing iPad rehearsal should you promote
-explicitly:
+check. For Release 2, retain the rehearsal record named in
+`pre-event-readiness.md`, including the second-phone exact-photo QR result.
+Only after recording a passing iPad rehearsal should you promote explicitly:
 
 ```bash
 bun run deploy:production
diff --git a/docs/runbooks/pre-event-readiness.md b/docs/runbooks/pre-event-readiness.md
index 653dc7a..58211f9 100644
--- a/docs/runbooks/pre-event-readiness.md
+++ b/docs/runbooks/pre-event-readiness.md
@@ -27,6 +27,63 @@ staging HTTPS before production promotion:
 9. Confirm Screen Wake Lock remains active across foreground return. If the target iPadOS denies or lacks it, follow the displayed instructions and set **Settings → Display & Brightness → Auto-Lock → Never** for the event.
 10. Queue one pending photo, use the discoverable Operator control, reject one wrong fresh key, then exit with a valid fresh Booth or Admin Key. Confirm the camera and wake lock release, heartbeat/poller/session activity stops, stored credentials clear, and the pending count remains intact after relaunch.
 
+### Release 2 guest capture and handoff
+
+Continue on the same throwaway staging Event, target iPad, and staging HTTPS
+hostname. The mocked WebKit journey is a repeatable regression check; it does
+not replace any check in this section.
+
+1. Capture every enabled Frame with the real iPad camera. Inspect the final
+   canvas at its configured resolution for crop, orientation, background and
+   overlay order, color, and memory stability. Exercise both one-shot and
+   multi-shot Frames.
+2. Confirm the review shows the exact completed composite. Retake and verify
+   the same Frame remains selected. Accept and verify the Frame clears only
+   after the photo is durably in the Photo Outbox.
+3. Let auto-accept win once, cancel it with **More Time** once, and rapidly
+   alternate **Use Photo** and **Retake** near the timeout. Each candidate must
+   create at most one Outbox row and one capture identity.
+4. Exercise an encoding failure on staging or a diagnostic build. Confirm no
+   Outbox row is created, the error is announced, and **Use Photo** can retry
+   or **Retake** can recover without reloading.
+5. Deny or disable in-browser camera access and use the file-camera fallback
+   with a real HEIC photo. Confirm decode, orientation, exact review, acceptance,
+   and the accessible decode-error recovery path.
+6. Pause the Event while a guest is reviewing, then while acceptance is
+   persisting. Review must remain safe; acceptance must either reach durable
+   handoff exactly once or report a recoverable error before the camera stops.
+7. Disable the venue network, accept a photo, and confirm the queued handoff
+   lets the next guest continue without inventing a QR. Restore connectivity
+   and verify ordered upload with no duplicate object.
+8. Queue two guests. Keep the older upload acknowledgement delayed until the
+   newer handoff has begun. The older acknowledgement must not replace, reopen,
+   or produce a QR for the current guest.
+9. When the current acknowledgement arrives, compare the visible text link
+   with the QR target. Scan the QR using a second physical phone and verify the
+   staging Gallery opens the exact complete Event-owned key and photo. A
+   localhost QR is not valid evidence.
+10. With VoiceOver on the iPad and second phone, traverse Frame selection,
+    countdown status, review actions, queued/ready handoff, direct-photo status,
+    and save/share. Confirm logical focus order, visible focus, concise
+    announcements, and no repeated or stale announcement.
+11. Select Arabic and confirm right-to-left document direction, then `zh-SG`.
+    Exercise an unavailable device/config locale and an absent localized Frame
+    label; both must fall back to English/default Frame text without a blank
+    control. Relaunch and confirm the supported Event-scoped locale persists.
+12. Enable countdown audio after a guest gesture and confirm bounded countdown
+    and shutter tones. Repeat with audio denied or unavailable: the visual
+    countdown and capture must continue without an error.
+13. Repeat the changed guest screens in installed landscape mode with Larger
+    Text, Reduce Motion, and Increase Contrast/high-contrast settings. Confirm
+    review controls, QR text link, and next-guest action remain visible and
+    keyboard/Switch Control operable.
+
+Record the Event slug, build revision, iPad/iPadOS model, second-phone model,
+enabled Frames, and pass/fail result for every item. Release 2 is not complete
+and production must not be promoted until every real-device item passes. Never
+remove test photos by prefix; copy and delete only each complete Event-owned
+image key intended for cleanup.
+
 Then capture one photo with every enabled Frame and check crop, draw order,
 orientation, color, and final resolution. Confirm each photo appears once in
 the Live Gallery without a full-page refresh, exercise Save/Share on a phone,
diff --git a/tests/booth-control.spec.ts b/tests/booth-control.spec.ts
index 5089404..6a451a7 100644
--- a/tests/booth-control.spec.ts
+++ b/tests/booth-control.spec.ts
@@ -184,7 +184,16 @@ async function installBrowserMocks(context: BrowserContext, fixture: ApiFixture)
         status: 200,
         contentType: "application/json",
         body: JSON.stringify({
-          experience: { frames: ["square", "beacon"] },
+          experience: {
+            frames: ["square", "beacon"],
+            locales: ["en"],
+            defaultLocale: "en",
+            capture: {
+              reviewEnabled: false,
+              autoAcceptSeconds: 5,
+              countdownAudioDefault: false,
+            },
+          },
           operationalState: {
             version: 1,
             paused: fixture.paused,
@@ -463,6 +472,8 @@ test("WebKit keeps Booth control credential-free and Outbox-safe", async ({
   await page.getByRole("button", { name: /Square 1 photo/ }).click();
   await page.getByRole("button", { name: "Start" }).click();
 
+  await expect(page.getByRole("heading", { name: "Photo safely queued." })).toBeVisible();
+  await page.getByRole("button", { name: "Continue" }).click();
   await expect(page.getByRole("button", { name: /Retry 1 pending/ })).toBeVisible();
   await expect.poll(() => fixture.uploadAttempts.length).toBeGreaterThan(0);
 
diff --git a/tests/guest-capture.spec.ts b/tests/guest-capture.spec.ts
new file mode 100644
index 0000000..8ddbe25
--- /dev/null
+++ b/tests/guest-capture.spec.ts
@@ -0,0 +1,741 @@
+import {
+  expect,
+  test,
+  type BrowserContext,
+  type Page,
+  type Route,
+} from "@playwright/test";
+
+const EVENT = "guest-capture";
+const BOOTH_KEY = "guest-key";
+const LOCALE_KEY = `boothLocale:${EVENT}`;
+
+type HeldUpload = {
+  captureId: string;
+  route: Route;
+};
+
+type GuestFixture = {
+  camera: "ready" | "denied";
+  audio: "ready" | "denied";
+  online: boolean;
+  holdUploads: boolean;
+  uploadAttempts: string[];
+  heldUploads: HeldUpload[];
+  photoKeys: Map<string, string>;
+  externalRequests: string[];
+  pageErrors: string[];
+  experience: {
+    frames: string[];
+    locales: string[];
+    defaultLocale: string;
+    capture: {
+      reviewEnabled: boolean;
+      autoAcceptSeconds: number;
+      countdownAudioDefault: boolean;
+    };
+  };
+};
+
+type GuestBrowserState = {
+  nextCanvasId: number;
+  reviewedCanvasIds: string[];
+  encodedCanvasIds: string[];
+  failNextEncoding: boolean;
+  audioStarts: number;
+  bitmapCloses: number;
+  online: boolean;
+};
+
+function createFixture(
+  overrides: Partial<Pick<GuestFixture, "camera" | "audio">> = {},
+): GuestFixture {
+  return {
+    camera: overrides.camera ?? "ready",
+    audio: overrides.audio ?? "ready",
+    online: true,
+    holdUploads: false,
+    uploadAttempts: [],
+    heldUploads: [],
+    photoKeys: new Map(),
+    externalRequests: [],
+    pageErrors: [],
+    experience: {
+      frames: ["square", "beacon"],
+      locales: ["en", "zh-SG", "ar"],
+      defaultLocale: "en",
+      capture: {
+        reviewEnabled: true,
+        autoAcceptSeconds: 2,
+        countdownAudioDefault: true,
+      },
+    },
+  };
+}
+
+async function installGuestMocks(
+  context: BrowserContext,
+  fixture: GuestFixture,
+) {
+  await context.addInitScript(({ camera, audio }) => {
+    const nativeSetTimeout = window.setTimeout.bind(window);
+    let fireAutoAccept = () => {};
+    window.setTimeout = ((
+      callback: TimerHandler,
+      delay?: number,
+      ...args: unknown[]
+    ) => {
+      if (delay === 2_000 && typeof callback === "function") {
+        fireAutoAccept = () => callback(...args);
+      }
+      const accelerated = delay === 1_000
+        ? 12
+        : delay === 300
+          ? 4
+          : delay === 400
+            ? 5
+            : delay === 2_000
+              ? 120
+              : delay === 5_000
+                ? 150
+                : delay;
+      return nativeSetTimeout(callback, accelerated, ...args);
+    }) as typeof window.setTimeout;
+
+    const state: GuestBrowserState = {
+      nextCanvasId: 0,
+      reviewedCanvasIds: [],
+      encodedCanvasIds: [],
+      failNextEncoding: false,
+      audioStarts: 0,
+      bitmapCloses: 0,
+      online: true,
+    };
+    Object.defineProperty(window, "__guestCaptureTest", {
+      configurable: true,
+      value: state,
+    });
+    Object.defineProperty(window, "__fireGuestAutoAccept", {
+      configurable: true,
+      value: () => fireAutoAccept(),
+    });
+    Object.defineProperty(navigator, "onLine", {
+      configurable: true,
+      get: () => state.online,
+    });
+
+    const nativeCreateElement = Document.prototype.createElement;
+    Object.defineProperty(Document.prototype, "createElement", {
+      configurable: true,
+      value: function (
+        this: Document,
+        tagName: string,
+        options?: ElementCreationOptions,
+      ) {
+        const element = nativeCreateElement.call(this, tagName, options);
+        if (tagName.toLowerCase() === "canvas") {
+          state.nextCanvasId += 1;
+          element.setAttribute("data-test-canvas-id", String(state.nextCanvasId));
+        }
+        return element;
+      },
+    });
+
+    Object.defineProperty(HTMLMediaElement.prototype, "play", {
+      configurable: true,
+      value: async () => {},
+    });
+    Object.defineProperty(HTMLVideoElement.prototype, "videoWidth", {
+      configurable: true,
+      get: () => 640,
+    });
+    Object.defineProperty(HTMLVideoElement.prototype, "videoHeight", {
+      configurable: true,
+      get: () => 480,
+    });
+    Object.defineProperty(HTMLCanvasElement.prototype, "getContext", {
+      configurable: true,
+      value: () => ({
+        translate() {},
+        scale() {},
+        drawImage() {},
+        fillRect() {},
+        clearRect() {},
+        createImageData(width: number, height: number) {
+          return {
+            data: new Uint8ClampedArray(width * height * 4),
+            width,
+            height,
+          };
+        },
+        putImageData() {},
+        fillStyle: "#000",
+      }),
+    });
+    Object.defineProperty(HTMLCanvasElement.prototype, "toDataURL", {
+      configurable: true,
+      value: () => "data:image/png;base64,iVBORw0KGgo=",
+    });
+    Object.defineProperty(HTMLCanvasElement.prototype, "toBlob", {
+      configurable: true,
+      value: function (this: HTMLCanvasElement, callback: BlobCallback) {
+        const canvasId = this.dataset.testCanvasId ?? "missing";
+        state.encodedCanvasIds.push(canvasId);
+        if (state.failNextEncoding) {
+          state.failNextEncoding = false;
+          callback(null);
+          return;
+        }
+        // Synthetic Blobs cannot be structured-cloned into WebKit's IDB in
+        // headless mode. These JPEG marker bytes exercise the same durable row.
+        callback(new Uint8Array([0xff, 0xd8, 0xff, 0xd9]) as unknown as Blob);
+      },
+    });
+    Object.defineProperty(window, "createImageBitmap", {
+      configurable: true,
+      value: async () => ({
+        width: 4032,
+        height: 3024,
+        close: () => {
+          state.bitmapCloses += 1;
+        },
+      }),
+    });
+
+    const mediaDevices = navigator.mediaDevices ?? {};
+    Object.defineProperty(mediaDevices, "getUserMedia", {
+      configurable: true,
+      value: async () => {
+        if (camera === "denied") {
+          throw new DOMException("camera denied by browser fixture", "NotAllowedError");
+        }
+        const stream = new MediaStream();
+        const track = { stop() {} };
+        Object.defineProperty(stream, "getTracks", {
+          configurable: true,
+          value: () => [track],
+        });
+        return stream;
+      },
+    });
+    Object.defineProperty(navigator, "mediaDevices", {
+      configurable: true,
+      value: mediaDevices,
+    });
+    Object.defineProperty(navigator, "wakeLock", {
+      configurable: true,
+      value: {
+        request: async () => {
+          throw new DOMException("gesture unavailable", "NotAllowedError");
+        },
+      },
+    });
+
+    class BrowserAudioContext {
+      state: AudioContextState = audio === "ready" ? "running" : "suspended";
+      currentTime = 0;
+      destination = {};
+
+      async resume() {
+        if (audio === "denied") {
+          throw new DOMException("audio denied", "NotAllowedError");
+        }
+        this.state = "running";
+      }
+
+      async close() {
+        this.state = "closed";
+      }
+
+      createOscillator() {
+        return {
+          frequency: { setValueAtTime() {} },
+          connect() {},
+          start() {
+            state.audioStarts += 1;
+          },
+          stop() {},
+        };
+      }
+
+      createGain() {
+        return {
+          gain: {
+            setValueAtTime() {},
+            exponentialRampToValueAtTime() {},
+          },
+          connect() {},
+        };
+      }
+    }
+    Object.defineProperty(window, "AudioContext", {
+      configurable: true,
+      value: BrowserAudioContext,
+    });
+  }, { camera: fixture.camera, audio: fixture.audio });
+
+  await context.route("**/*", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    if (url.hostname !== "127.0.0.1") {
+      fixture.externalRequests.push(url.href);
+      await route.abort("blockedbyclient");
+      return;
+    }
+    if (!url.pathname.startsWith("/api/") && !url.pathname.startsWith("/mock-photo/")) {
+      await route.continue();
+      return;
+    }
+
+    if (url.pathname === "/api/booth/preflight") {
+      if (request.headers()["x-booth-key"] !== BOOTH_KEY) {
+        await route.fulfill({
+          status: 401,
+          contentType: "application/json",
+          body: JSON.stringify({ error: "unauthorized" }),
+        });
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          experience: fixture.experience,
+          operationalState: {
+            version: 1,
+            paused: false,
+            updatedAt: "2026-07-24T12:00:00.000Z",
+          },
+          serverTime: "2026-07-24T12:00:00.000Z",
+        }),
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/booth-state") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          version: 1,
+          paused: false,
+          updatedAt: "2026-07-24T12:00:00.000Z",
+        }),
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/booths") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: "{}",
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/upload") {
+      const captureId = request.headers()["x-capture-id"] ?? "missing";
+      fixture.uploadAttempts.push(captureId);
+      if (fixture.holdUploads || !fixture.online) {
+        fixture.heldUploads.push({ captureId, route });
+        return;
+      }
+      const key = `${EVENT}/${captureId}.jpg`;
+      fixture.photoKeys.set(captureId, key);
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          url: `/mock-photo/${captureId}.jpg`,
+          key,
+          duplicate: false,
+        }),
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/photo") {
+      const key = url.searchParams.get("key") ?? "";
+      const captureId = [...fixture.photoKeys.entries()]
+        .find(([, storedKey]) => storedKey === key)?.[0];
+      if (!captureId || url.searchParams.get("event") !== EVENT) {
+        await route.fulfill({
+          status: 404,
+          contentType: "application/json",
+          body: JSON.stringify({ error: "not found" }),
+        });
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        headers: { "cache-control": "no-store" },
+        body: JSON.stringify({
+          key,
+          url: `/mock-photo/${captureId}.jpg`,
+          uploadedAt: "2026-07-24T12:00:00.000Z",
+        }),
+      });
+      return;
+    }
+
+    if (url.pathname.startsWith("/mock-photo/")) {
+      await route.fulfill({
+        status: 200,
+        contentType: "image/jpeg",
+        body: Buffer.from([0xff, 0xd8, 0xff, 0xd9]),
+      });
+      return;
+    }
+
+    throw new Error(`Unexpected API request: ${request.method()} ${url.pathname}`);
+  });
+}
+
+async function unlock(page: Page) {
+  await page.goto(`/${EVENT}`, { waitUntil: "networkidle" });
+  await page.getByLabel("Booth Key").fill(BOOTH_KEY);
+  await page.getByRole("button", { name: "Unlock Booth" }).click();
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+}
+
+async function browserState(page: Page): Promise<GuestBrowserState> {
+  return page.evaluate(() => ({
+    ...(window as typeof window & {
+      __guestCaptureTest: GuestBrowserState;
+    }).__guestCaptureTest,
+  }));
+}
+
+async function setBrowserOnline(page: Page, online: boolean) {
+  await page.evaluate((nextOnline) => {
+    const state = (window as typeof window & {
+      __guestCaptureTest: GuestBrowserState;
+    }).__guestCaptureTest;
+    state.online = nextOnline;
+    window.dispatchEvent(new Event(nextOnline ? "online" : "offline"));
+  }, online);
+}
+
+async function outboxIds(page: Page): Promise<string[]> {
+  return page.evaluate(async (event) => {
+    const request = indexedDB.open("ipad-webbooth", 2);
+    const db = await new Promise<IDBDatabase>((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+    const rows = await new Promise<Array<{ id: string; event: string }>>(
+      (resolve, reject) => {
+        const transaction = db.transaction("photo-outbox", "readonly");
+        const result = transaction.objectStore("photo-outbox").getAll();
+        result.onsuccess = () => resolve(result.result);
+        result.onerror = () => reject(result.error);
+      },
+    );
+    db.close();
+    return rows
+      .filter((row) => row.event === event)
+      .map((row) => row.id)
+      .sort();
+  }, EVENT);
+}
+
+async function reviewCanvasId(page: Page): Promise<string> {
+  const preview = page.getByRole("img", { name: "Photo preview" });
+  await expect(preview).toBeVisible();
+  const canvas = preview.locator("canvas");
+  await expect(canvas).toHaveCount(1);
+  const id = await canvas.getAttribute("data-test-canvas-id");
+  expect(id).toBeTruthy();
+  await page.evaluate((canvasId) => {
+    const state = (window as typeof window & {
+      __guestCaptureTest: GuestBrowserState;
+    }).__guestCaptureTest;
+    state.reviewedCanvasIds.push(canvasId);
+  }, id!);
+  return id!;
+}
+
+async function captureFrame(page: Page, buttonName: RegExp) {
+  await page.getByRole("button", { name: buttonName }).click();
+  await page.getByRole("button", { name: "Start" }).click();
+}
+
+async function acknowledge(
+  fixture: GuestFixture,
+  expectedCaptureId?: string,
+) {
+  await expect.poll(() => fixture.heldUploads.length).toBeGreaterThan(0);
+  const held = fixture.heldUploads.shift()!;
+  if (expectedCaptureId) expect(held.captureId).toBe(expectedCaptureId);
+  const key = `${EVENT}/${held.captureId}.jpg`;
+  fixture.photoKeys.set(held.captureId, key);
+  await held.route.fulfill({
+    status: 200,
+    contentType: "application/json",
+    body: JSON.stringify({
+      url: `/mock-photo/${held.captureId}.jpg`,
+      key,
+      duplicate: false,
+    }),
+  });
+  return { captureId: held.captureId, key };
+}
+
+async function seriousGuestAccessibilityIssues(page: Page): Promise<string[]> {
+  return page.evaluate(() => {
+    const issues: string[] = [];
+    const visible = (element: Element) => {
+      const style = getComputedStyle(element);
+      return style.display !== "none" && style.visibility !== "hidden";
+    };
+    const name = (element: Element) =>
+      element.getAttribute("aria-label")
+      || element.getAttribute("alt")
+      || (element instanceof HTMLInputElement
+        || element instanceof HTMLSelectElement
+        ? [...element.labels ?? []].map((label) => label.textContent?.trim()).join(" ")
+        : "")
+      || element.textContent?.trim()
+      || "";
+
+    for (const element of document.querySelectorAll("button, a[href], input, select, [role='img']")) {
+      if (visible(element) && !name(element)) {
+        issues.push(`unnamed ${element.tagName.toLowerCase()}`);
+      }
+    }
+    for (const image of document.querySelectorAll("img")) {
+      if (!image.hasAttribute("alt")) issues.push("image missing alt");
+    }
+    const ids = [...document.querySelectorAll("[id]")].map((element) => element.id);
+    for (const id of new Set(ids)) {
+      if (ids.filter((candidate) => candidate === id).length > 1) {
+        issues.push(`duplicate id ${id}`);
+      }
+    }
+    return issues;
+  });
+}
+
+test("WebKit reviews the exact one-shot and multi-shot canvas before one durable handoff", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture();
+  await installGuestMocks(context, fixture);
+  page.on("pageerror", (error) => fixture.pageErrors.push(error.message));
+  await unlock(page);
+
+  await captureFrame(page, /Square 1 photo/);
+  const firstReviewCanvas = await reviewCanvasId(page);
+  expect((await browserState(page)).encodedCanvasIds).toEqual([]);
+
+  await page.getByRole("button", { name: "Retake" }).click();
+  await expect(page.getByRole("button", { name: "Start" })).toBeFocused();
+  expect(await outboxIds(page)).toEqual([]);
+
+  await page.getByRole("button", { name: "Start" }).click();
+  const acceptedCanvas = await reviewCanvasId(page);
+  expect(acceptedCanvas).not.toBe(firstReviewCanvas);
+  await page.getByRole("button", { name: "More Time" }).click();
+  await page.waitForTimeout(220);
+  await expect(page.getByRole("img", { name: "Photo preview" })).toBeVisible();
+  expect(await outboxIds(page)).toEqual([]);
+
+  fixture.online = false;
+  fixture.holdUploads = true;
+  await setBrowserOnline(page, false);
+  await page.getByRole("button", { name: "Use Photo" }).click();
+  await expect(page.getByRole("heading", { name: "Photo safely queued." })).toBeVisible();
+  const [firstCaptureId] = await outboxIds(page);
+  expect(firstCaptureId).toBeTruthy();
+  expect((await browserState(page)).encodedCanvasIds).toEqual([acceptedCanvas]);
+
+  fixture.online = true;
+  await setBrowserOnline(page, true);
+  const firstAcknowledgement = await acknowledge(fixture, firstCaptureId);
+  const link = page.getByRole("link", { name: "View photo" });
+  const firstGalleryUrl =
+    `http://127.0.0.1:3100/${EVENT}/gallery?photo=${encodeURIComponent(firstAcknowledgement.key)}`;
+  await expect(link).toHaveAttribute(
+    "href",
+    firstGalleryUrl,
+  );
+  await expect(page.locator("img[data-gallery-url]")).toHaveAttribute(
+    "data-gallery-url",
+    await link.getAttribute("href") as string,
+  );
+
+  const directPagePromise = context.waitForEvent("page");
+  await link.click();
+  const directPage = await directPagePromise;
+  await expect(directPage.getByRole("heading", { name: "Your photo is ready" })).toBeVisible();
+  await expect(directPage.getByRole("img", { name: "Photo preview" })).toHaveAttribute(
+    "src",
+    `/mock-photo/${firstCaptureId}.jpg`,
+  );
+  expect(directPage.url()).toContain(
+    `/${EVENT}/gallery?photo=${encodeURIComponent(firstAcknowledgement.key)}`,
+  );
+  await directPage.close();
+
+  await page.getByRole("button", { name: "Continue" }).click();
+  fixture.holdUploads = true;
+  await captureFrame(page, /Beacon 3 photos/);
+  const multiReviewCanvas = await reviewCanvasId(page);
+  await expect(page.getByRole("heading", { name: "Photo safely queued." })).toBeVisible();
+  const multiCaptureId = (await outboxIds(page))[0];
+  expect(multiCaptureId).toBeTruthy();
+  expect((await browserState(page)).encodedCanvasIds).toContain(multiReviewCanvas);
+  expect((await browserState(page)).audioStarts).toBeGreaterThanOrEqual(4);
+
+  fixture.holdUploads = false;
+  await acknowledge(fixture, multiCaptureId);
+  await expect(page.getByRole("heading", { name: "Your photo is ready" })).toBeVisible();
+  await page.getByRole("button", { name: "Continue" }).click();
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+  expect(fixture.externalRequests).toEqual([]);
+  expect(fixture.pageErrors).toEqual([]);
+});
+
+test("WebKit fences encode races and keeps the newer handoff during delayed recovery", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture();
+  await installGuestMocks(context, fixture);
+  page.on("pageerror", (error) => fixture.pageErrors.push(error.message));
+  await unlock(page);
+
+  await captureFrame(page, /Square 1 photo/);
+  const failedCanvas = await reviewCanvasId(page);
+  await page.getByRole("button", { name: "More Time" }).click();
+  await page.evaluate(() => {
+    (window as typeof window & {
+      __guestCaptureTest: GuestBrowserState;
+    }).__guestCaptureTest.failNextEncoding = true;
+  });
+  await page.getByRole("button", { name: "Use Photo" }).click();
+  await expect(page.getByText("We couldn’t safely save this photo.")).toBeVisible();
+  expect(await outboxIds(page)).toEqual([]);
+
+  fixture.online = false;
+  fixture.holdUploads = true;
+  await setBrowserOnline(page, false);
+  await page.getByRole("button", { name: "Use Photo" }).click();
+  await expect(page.getByRole("heading", { name: "Photo safely queued." })).toBeVisible();
+  const [olderId] = await outboxIds(page);
+  expect((await browserState(page)).encodedCanvasIds)
+    .toEqual([failedCanvas, failedCanvas]);
+
+  await page.getByRole("button", { name: "Continue" }).click();
+  await captureFrame(page, /Square 1 photo/);
+  const newerCanvas = await reviewCanvasId(page);
+  await page.evaluate(() => {
+    (window as typeof window & {
+      __fireGuestAutoAccept(): void;
+    }).__fireGuestAutoAccept();
+    const buttons = [...document.querySelectorAll("button")];
+    const use = buttons.find((button) => button.textContent?.trim() === "Use Photo");
+    use?.click();
+  });
+  await expect.poll(async () => (await outboxIds(page)).length).toBe(2);
+  const newerId = (await outboxIds(page)).find((id) => id !== olderId)!;
+  expect(newerId).toBeTruthy();
+  expect((await browserState(page)).encodedCanvasIds.filter(
+    (canvasId) => canvasId === newerCanvas,
+  )).toHaveLength(1);
+  await expect(page.getByRole("heading", { name: "Photo safely queued." })).toBeVisible();
+
+  fixture.online = true;
+  await setBrowserOnline(page, true);
+  const olderAcknowledgement = await acknowledge(fixture, olderId);
+  expect(olderAcknowledgement.captureId).toBe(olderId);
+  await expect(page.getByRole("heading", { name: "Photo safely queued." })).toBeVisible();
+  await expect(page.getByRole("link", { name: "View photo" })).toHaveCount(0);
+
+  const newerAcknowledgement = await acknowledge(fixture, newerId);
+  const exactLink = page.getByRole("link", { name: "View photo" });
+  await expect(exactLink).toHaveAttribute(
+    "href",
+    `http://127.0.0.1:3100/${EVENT}/gallery?photo=${encodeURIComponent(newerAcknowledgement.key)}`,
+  );
+  expect(await outboxIds(page)).toEqual([]);
+  expect(new Set(fixture.uploadAttempts)).toEqual(new Set([olderId, newerId]));
+  expect(fixture.pageErrors).toEqual([]);
+});
+
+test("WebKit persists Arabic, falls back to English, and preserves keyboard semantics", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture();
+  await installGuestMocks(context, fixture);
+  page.on("pageerror", (error) => fixture.pageErrors.push(error.message));
+  await page.emulateMedia({ reducedMotion: "reduce", forcedColors: "active" });
+  await unlock(page);
+
+  await page.getByLabel("Language").selectOption("ar");
+  await expect(page.locator("html")).toHaveAttribute("lang", "ar");
+  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");
+  await expect(page.getByRole("heading", { name: "اختر إطارًا" })).toBeVisible();
+  expect(await page.evaluate((key) => localStorage.getItem(key), LOCALE_KEY)).toBe("ar");
+  await page.reload();
+  await expect(page.getByRole("heading", { name: "اختر إطارًا" })).toBeVisible();
+
+  fixture.experience = {
+    ...fixture.experience,
+    locales: ["en"],
+    defaultLocale: "unsupported",
+  };
+  await page.evaluate((key) => localStorage.setItem(key, "unsupported"), LOCALE_KEY);
+  await page.reload();
+  await expect(page.locator("html")).toHaveAttribute("lang", "en");
+  await expect(page.locator("html")).toHaveAttribute("dir", "ltr");
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+  // WebKit can report an aborted poll as an access-control page error while a
+  // reload replaces the document. Audit the settled English guest surface.
+  fixture.pageErrors.length = 0;
+
+  await page.locator("body").focus();
+  await page.keyboard.press("Tab");
+  await expect(page.getByRole("button", { name: /Square 1 photo/ })).toBeFocused();
+  await page.keyboard.press("Enter");
+  await page.keyboard.press("Tab");
+  await expect(page.getByRole("button", { name: "Start" })).toBeFocused();
+  await page.keyboard.press("Enter");
+  await reviewCanvasId(page);
+  await expect(page.getByRole("button", { name: "Use Photo" })).toBeFocused();
+  expect(await seriousGuestAccessibilityIssues(page)).toEqual([]);
+  expect(fixture.pageErrors).toEqual([]);
+});
+
+test("WebKit file-camera fallback reaches review when camera and audio are unavailable", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture({ camera: "denied", audio: "denied" });
+  await installGuestMocks(context, fixture);
+  page.on("pageerror", (error) => fixture.pageErrors.push(error.message));
+  await page.goto(`/${EVENT}`, { waitUntil: "networkidle" });
+  await page.getByLabel("Booth Key").fill(BOOTH_KEY);
+  await page.getByRole("button", { name: "Unlock Booth" }).click();
+  await expect(page.getByText("Camera unavailable. Use your device camera instead:"))
+    .toBeVisible();
+
+  await page.locator('input[type="file"]').setInputFiles({
+    name: "fallback.heic",
+    mimeType: "image/heic",
+    buffer: Buffer.from([0x00, 0x00, 0x00, 0x18]),
+  });
+  const fallbackCanvas = await reviewCanvasId(page);
+  fixture.holdUploads = true;
+  await page.getByRole("button", { name: "Use Photo" }).click();
+  await expect(page.getByRole("heading", { name: "Photo safely queued." })).toBeVisible();
+  expect((await browserState(page)).encodedCanvasIds).toEqual([fallbackCanvas]);
+  expect((await browserState(page)).bitmapCloses).toBe(1);
+  expect((await browserState(page)).audioStarts).toBe(0);
+  expect(fixture.externalRequests).toEqual([]);
+  expect(fixture.pageErrors).toEqual([]);
+});

From a429fafbd0eaf0c439698e0fdf097849805acd96 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:41:13 +0800
Subject: [PATCH 085/105] feat: stream enriched event exports

---
 app/api/export/handlers.test.ts | 102 ++++++++++++++
 app/api/export/handlers.ts      | 109 +++++++++++++++
 app/api/export/route.ts         |  74 ++---------
 app/export-stream.test.ts       | 211 +++++++++++++++++++++++++++++
 app/export-stream.ts            | 226 ++++++++++++++++++++++++++++++++
 app/zip.test.ts                 |  39 +++++-
 app/zip.ts                      |  29 +++-
 7 files changed, 721 insertions(+), 69 deletions(-)
 create mode 100644 app/api/export/handlers.test.ts
 create mode 100644 app/api/export/handlers.ts
 create mode 100644 app/export-stream.test.ts
 create mode 100644 app/export-stream.ts

diff --git a/app/api/export/handlers.test.ts b/app/api/export/handlers.test.ts
new file mode 100644
index 0000000..1d6cce2
--- /dev/null
+++ b/app/api/export/handlers.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { InvalidPhotoReceiptError } from "@/app/photo-metadata";
+import { ExportTooLargeError } from "@/app/export-stream";
+import { handleExport, type ExportHandlerDeps } from "./handlers";
+
+function request(
+  query: string,
+  key = "admin-secret",
+): NextRequest {
+  return new NextRequest(`https://booth.example/api/export?${query}`, {
+    headers: { "x-booth-key": key },
+  });
+}
+
+function deps(overrides: Partial<ExportHandlerDeps> = {}) {
+  let reads = 0;
+  const empty = () => new ReadableStream<Uint8Array>({ start(c) { c.close(); } });
+  const store = {
+    async readConfig() { reads++; return { frames: [], timeZone: "Asia/Singapore" }; },
+  } as unknown as EventStore;
+  return {
+    value: {
+      store,
+      adminKey: "admin-secret",
+      frameLabelFor: () => undefined,
+      now: () => new Date("2026-07-24T00:00:00.000Z"),
+      preparePhotoOnly: async () => empty(),
+      preparePackage: async () => empty(),
+      ...overrides,
+    },
+    reads: () => reads,
+  };
+}
+
+describe("export HTTP boundary", () => {
+  test("authenticates before validation or storage", async () => {
+    const missing = deps({ adminKey: undefined });
+    expect((await handleExport(request("event=Launch Event"), missing.value)).status).toBe(503);
+    expect(missing.reads()).toBe(0);
+
+    const wrong = deps();
+    expect((await handleExport(request("event=launch", "booth-key"), wrong.value)).status).toBe(401);
+    expect(wrong.reads()).toBe(0);
+  });
+
+  test("accepts only canonical exact query contracts", async () => {
+    for (const query of [
+      "event=Launch",
+      "event=launch&format=package",
+      "event=launch&contactSheet=1",
+      "event=launch&format=other",
+      "event=launch&format=package&contactSheet=0",
+      "event=launch&format=package&format=package&contactSheet=1",
+      "event=launch&format=package&contactSheet=1&contactSheet=1",
+      "event=launch&unknown=1",
+    ]) {
+      const current = deps();
+      expect((await handleExport(request(query), current.value)).status).toBe(400);
+      expect(current.reads()).toBe(0);
+    }
+  });
+
+  test("preserves legacy and enriched response contracts", async () => {
+    const legacy = await handleExport(request("event=launch"), deps().value);
+    expect(legacy.status).toBe(200);
+    expect(legacy.headers.get("content-type")).toBe("application/zip");
+    expect(legacy.headers.get("content-disposition")).toBe('attachment; filename="launch-photos.zip"');
+    expect(legacy.headers.get("cache-control")).toBe("private, no-store");
+    expect(legacy.headers.get("x-content-type-options")).toBe("nosniff");
+
+    const enriched = await handleExport(
+      request("event=launch&format=package&contactSheet=1"),
+      deps().value,
+    );
+    expect(enriched.status).toBe(200);
+    expect(enriched.headers.get("content-disposition")).toBe('attachment; filename="launch-package.zip"');
+  });
+
+  test("maps expected failures without exposing private detail", async () => {
+    const cases = [
+      [new ExportTooLargeError("zip_bytes"), 413],
+      [new InvalidPhotoReceiptError("launch/private-secret.jpg", "key_mismatch"), 422],
+      [new Error("events/launch/photo-metadata/raw-private.json admin-secret"), 503],
+    ] as const;
+    for (const [failure, status] of cases) {
+      const current = deps({
+        preparePackage: async () => { throw failure; },
+      });
+      const response = await handleExport(
+        request("event=launch&format=package&contactSheet=1"),
+        current.value,
+      );
+      const text = await response.text();
+      expect(response.status).toBe(status);
+      expect(text).not.toContain("raw-private");
+      expect(text).not.toContain("admin-secret");
+      expect(text).not.toContain("launch/private-secret");
+    }
+  });
+});
diff --git a/app/api/export/handlers.ts b/app/api/export/handlers.ts
new file mode 100644
index 0000000..65a851f
--- /dev/null
+++ b/app/api/export/handlers.ts
@@ -0,0 +1,109 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  InvalidEventSlugError,
+} from "@/app/event-store";
+import {
+  ExportTooLargeError,
+  preparePackageExport,
+  preparePhotoOnlyExport,
+  type ExportStreamDeps,
+} from "@/app/export-stream";
+import { InvalidPhotoReceiptError } from "@/app/photo-metadata";
+import { adminOk } from "@/app/upload-auth";
+
+type PreparePhotoOnly = typeof preparePhotoOnlyExport;
+type PreparePackage = typeof preparePackageExport;
+
+export type ExportHandlerDeps = ExportStreamDeps & {
+  adminKey?: string;
+  preparePhotoOnly?: PreparePhotoOnly;
+  preparePackage?: PreparePackage;
+};
+
+const errorResponse = (error: string, status: number) =>
+  NextResponse.json(
+    { error },
+    {
+      status,
+      headers: {
+        "cache-control": "private, no-store",
+        "x-content-type-options": "nosniff",
+      },
+    },
+  );
+
+function queryMode(
+  req: NextRequest,
+): { event: string; mode: "photos" | "package" } | NextResponse {
+  const params = req.nextUrl.searchParams;
+  const allowed = new Set(["event", "format", "contactSheet"]);
+  for (const key of params.keys()) {
+    if (!allowed.has(key) || params.getAll(key).length !== 1) {
+      return errorResponse("invalid export request", 400);
+    }
+  }
+  if (params.getAll("event").length !== 1) {
+    return errorResponse("invalid export request", 400);
+  }
+  let event: string;
+  try {
+    event = canonicalEvent(params.get("event"));
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) {
+      return errorResponse("invalid event", 400);
+    }
+    throw error;
+  }
+
+  const format = params.get("format");
+  const contactSheet = params.get("contactSheet");
+  if (format === null && contactSheet === null) {
+    return { event, mode: "photos" };
+  }
+  if (format === "package" && contactSheet === "1") {
+    return { event, mode: "package" };
+  }
+  return errorResponse("invalid export request", 400);
+}
+
+export async function handleExport(
+  req: NextRequest,
+  deps: ExportHandlerDeps,
+): Promise<NextResponse> {
+  if (!deps.adminKey) {
+    return errorResponse("export unavailable", 503);
+  }
+  if (adminOk(req.headers.get("x-booth-key") ?? "", deps.adminKey) !== "ok") {
+    return errorResponse("unauthorized", 401);
+  }
+  const query = queryMode(req);
+  if (query instanceof NextResponse) return query;
+
+  try {
+    const stream = query.mode === "photos"
+      ? await (deps.preparePhotoOnly ?? preparePhotoOnlyExport)(query.event, deps)
+      : await (deps.preparePackage ?? preparePackageExport)(
+        query.event,
+        (await deps.store.readConfig(query.event))?.timeZone,
+        deps,
+      );
+    const suffix = query.mode === "photos" ? "photos" : "package";
+    return new NextResponse(stream, {
+      headers: {
+        "content-type": "application/zip",
+        "content-disposition": `attachment; filename="${query.event}-${suffix}.zip"`,
+        "cache-control": "private, no-store",
+        "x-content-type-options": "nosniff",
+      },
+    });
+  } catch (error) {
+    if (error instanceof ExportTooLargeError) {
+      return errorResponse("event is too large for one archive", 413);
+    }
+    if (error instanceof InvalidPhotoReceiptError) {
+      return errorResponse("stored photo metadata is invalid", 422);
+    }
+    return errorResponse("export temporarily unavailable", 503);
+  }
+}
diff --git a/app/api/export/route.ts b/app/api/export/route.ts
index 9d55afa..2d4ae41 100644
--- a/app/api/export/route.ts
+++ b/app/api/export/route.ts
@@ -1,73 +1,17 @@
 import { getCloudflareContext } from "@opennextjs/cloudflare";
-import { NextRequest, NextResponse } from "next/server";
-import { canonicalEvent, EventStore, InvalidEventSlugError } from "@/app/event-store";
-import { adminOk } from "@/app/upload-auth";
-import { localPart, centralPart, endPart } from "@/app/zip";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { TEMPLATES } from "@/app/templates";
+import { handleExport } from "./handlers";
 
 export const dynamic = "force-dynamic";
 
 export async function GET(req: NextRequest) {
   const { env } = getCloudflareContext();
-  // Admin key only — a per-event booth key must never bulk-download photos.
-  const auth = adminOk(req.headers.get("x-booth-key") ?? "", env.BOOTH_UPLOAD_KEY);
-  if (auth === "disabled") {
-    return NextResponse.json({ error: "export disabled: no key configured" }, { status: 503 });
-  }
-  if (auth === "unauthorized") {
-    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
-  }
-
-  let event: string;
-  try {
-    event = canonicalEvent(req.nextUrl.searchParams.get("event"));
-  } catch (error) {
-    if (error instanceof InvalidEventSlugError) return NextResponse.json({ error: error.message }, { status: 400 });
-    throw error;
-  }
-  const store = EventStore.fromEnv(env);
-
-  const objects: { key: string; size: number }[] = [];
-  for await (const object of store.iteratePhotoObjects(event)) objects.push(object);
-
-  // STORE zip has no ZIP64 — reject past its hard limits instead of silently
-  // emitting a corrupt archive.
-  const totalBytes = objects.reduce((n, o) => n + o.size, 0);
-  if (objects.length > 0xffff || totalBytes > 3.9e9) {
-    return NextResponse.json({ error: "event too large for a single zip" }, { status: 413 });
-  }
-
-  // Stream the zip: fetch and emit one object per pull, central directory
-  // last — memory stays at one photo instead of the whole event (which OOMed
-  // the 128 MB Worker isolate when buffered with Promise.all + concat).
-  const te = new TextEncoder();
-  const central: Uint8Array[] = [];
-  let offset = 0;
-  let i = 0;
-  const stream = new ReadableStream<Uint8Array>({
-    async pull(controller) {
-      while (i < objects.length) {
-        const { key } = objects[i++];
-        const obj = await store.getPhoto(key);
-        if (!obj) continue; // deleted mid-export; skip it
-        const data = new Uint8Array(await obj.arrayBuffer());
-        const name = te.encode(key.split("/").pop() ?? key);
-        const { bytes, crc } = localPart(name, data);
-        central.push(centralPart({ name, crc, size: data.length, offset }));
-        offset += bytes.length;
-        controller.enqueue(bytes);
-        return;
-      }
-      const centralLen = central.reduce((n, c) => n + c.length, 0);
-      for (const c of central) controller.enqueue(c);
-      controller.enqueue(endPart(central.length, centralLen, offset));
-      controller.close();
-    },
-  });
-
-  return new NextResponse(stream, {
-    headers: {
-      "content-type": "application/zip",
-      "content-disposition": `attachment; filename="${event}-photos.zip"`,
-    },
+  return handleExport(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+    frameLabelFor: (frameKey) => TEMPLATES[frameKey]?.label,
+    now: () => new Date(),
   });
 }
diff --git a/app/export-stream.test.ts b/app/export-stream.test.ts
new file mode 100644
index 0000000..af8d98b
--- /dev/null
+++ b/app/export-stream.test.ts
@@ -0,0 +1,211 @@
+import { describe, expect, test } from "bun:test";
+import {
+  EventStore,
+  InMemoryObjectStore,
+  type ExportPhotoSource,
+  type StoredObjectBody,
+} from "./event-store";
+import {
+  ExportTooLargeError,
+  MAX_ZIP_ENTRIES,
+  preparePackageExport,
+  preparePhotoOnlyExport,
+} from "./export-stream";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function storeWith(
+  photos: Record<string, string> = {},
+  state: Record<string, string> = {},
+): EventStore {
+  return new EventStore(
+    new InMemoryObjectStore(photos),
+    new InMemoryObjectStore(state),
+    "https://photos.example",
+    () => new Date("2026-07-24T12:00:00.000Z"),
+  );
+}
+
+async function chunks(stream: ReadableStream<Uint8Array>): Promise<Uint8Array[]> {
+  const reader = stream.getReader();
+  const values: Uint8Array[] = [];
+  for (;;) {
+    const next = await reader.read();
+    if (next.done) return values;
+    values.push(next.value);
+  }
+}
+
+function entries(values: Uint8Array[]): Map<string, Uint8Array> {
+  const bytes = new Uint8Array(values.flatMap((value) => [...value]));
+  const files = new Map<string, Uint8Array>();
+  let offset = 0;
+  while (
+    bytes[offset] === 0x50
+    && bytes[offset + 1] === 0x4b
+    && bytes[offset + 2] === 0x03
+    && bytes[offset + 3] === 0x04
+  ) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset + offset);
+    const size = view.getUint32(18, true);
+    const nameLength = view.getUint16(26, true);
+    const extraLength = view.getUint16(28, true);
+    const nameStart = offset + 30;
+    const dataStart = nameStart + nameLength + extraLength;
+    const name = decoder.decode(bytes.slice(nameStart, nameStart + nameLength));
+    files.set(name, bytes.slice(dataStart, dataStart + size));
+    offset = dataStart + size;
+  }
+  return files;
+}
+
+describe("export streams", () => {
+  test("keeps legacy root names and emits photo headers and bodies separately", async () => {
+    const store = storeWith({
+      "launch/1700000000000-a.jpg": "alpha",
+      "launch/1700000000001-b.jpg": "beta",
+    });
+    const values = await chunks(await preparePhotoOnlyExport("launch", {
+      store,
+      frameLabelFor: () => undefined,
+      now: () => new Date("2026-07-24T12:00:00.000Z"),
+    }));
+    const archive = entries(values);
+
+    expect([...archive.keys()]).toEqual([
+      "1700000000000-a.jpg",
+      "1700000000001-b.jpg",
+    ]);
+    expect(decoder.decode(archive.get("1700000000000-a.jpg"))).toBe("alpha");
+    expect(values.some((value) => value.length === encoder.encode("alpha").length)).toBe(true);
+    expect([...archive.keys()].some((name) => name.includes("manifest"))).toBe(false);
+  });
+
+  test("enriched package joins metadata and appends generated entries", async () => {
+    const key = "launch/1700000000000-a.jpg";
+    const store = storeWith(
+      { [key]: "alpha" },
+      {
+        "events/launch/photo-metadata/1700000000000-a.jpg.json": JSON.stringify({
+          version: 1,
+          key,
+          uploadedAt: "2026-07-24T12:00:00.000Z",
+          capturedAt: 1700000000000,
+          source: "framed",
+          frameKey: "square",
+        }),
+      },
+    );
+    const archive = entries(await chunks(await preparePackageExport(
+      "launch",
+      "Asia/Singapore",
+      {
+        store,
+        frameLabelFor: (frame) => frame === "square" ? "Square" : undefined,
+        now: () => new Date("2026-07-24T12:00:00.000Z"),
+      },
+    )));
+
+    expect([...archive.keys()]).toEqual([
+      "photos/1700000000000-a.jpg",
+      "manifest.csv",
+      "summary.json",
+      "contact-sheet.html",
+    ]);
+    expect(decoder.decode(archive.get("manifest.csv"))).toContain("square,Square,framed");
+    expect(decoder.decode(archive.get("summary.json"))).toContain('"timeZone": "Asia/Singapore"');
+    expect(decoder.decode(archive.get("contact-sheet.html"))).toContain('src="photos/1700000000000-a.jpg"');
+    expect(decoder.decode(archive.get("manifest.csv"))).not.toContain("events/launch/photos/");
+  });
+
+  test("a photo deleted after inventory is absent from every package section", async () => {
+    const source: ExportPhotoSource = {
+      key: "launch/1700000000000-gone.jpg",
+      size: 5,
+      uploadedAt: "2026-07-24T12:00:00.000Z",
+      receipt: null,
+    };
+    const store = {
+      async *iterateExportPhotoSources() { yield source; },
+      getPhoto: async () => null,
+    } as unknown as EventStore;
+    const archive = entries(await chunks(await preparePackageExport(
+      "launch",
+      undefined,
+      {
+        store,
+        frameLabelFor: () => undefined,
+        now: () => new Date("2026-07-24T12:00:00.000Z"),
+      },
+    )));
+
+    expect([...archive.keys()]).toEqual([
+      "manifest.csv",
+      "summary.json",
+      "contact-sheet.html",
+    ]);
+    expect(decoder.decode(archive.get("manifest.csv"))).not.toContain("gone.jpg");
+    expect(JSON.parse(decoder.decode(archive.get("summary.json"))).photoCount).toBe(0);
+    expect(decoder.decode(archive.get("contact-sheet.html"))).not.toContain("gone.jpg");
+  });
+
+  test("reads at most one photo body before asking for the next", async () => {
+    let firstFinished = false;
+    let secondStartedBeforeFirstFinished = false;
+    const source = (index: number): ExportPhotoSource => ({
+      key: `launch/170000000000${index}-photo.jpg`,
+      size: 1,
+      uploadedAt: "2026-07-24T12:00:00.000Z",
+      receipt: null,
+    });
+    const body = (key: string, index: number): StoredObjectBody => ({
+      key,
+      size: 1,
+      uploaded: new Date(),
+      etag: String(index),
+      async arrayBuffer() {
+        if (index === 2 && !firstFinished) secondStartedBeforeFirstFinished = true;
+        await Promise.resolve();
+        if (index === 1) firstFinished = true;
+        return new Uint8Array([index]).buffer;
+      },
+      async text() { return ""; },
+      async json<T>() { return {} as T; },
+    });
+    const store = {
+      async *iterateExportPhotoSources() { yield source(1); yield source(2); },
+      async getPhoto(key: string) {
+        return body(key, key.includes("001-") ? 1 : 2);
+      },
+    } as unknown as EventStore;
+
+    await chunks(await preparePackageExport("launch", undefined, {
+      store,
+      frameLabelFor: () => undefined,
+      now: () => new Date(),
+    }));
+    expect(secondStartedBeforeFirstFinished).toBe(false);
+  });
+
+  test("rejects classic ZIP entry overflow before returning a stream", async () => {
+    const store = {
+      async *iteratePhotoObjects() {
+        for (let index = 0; index <= MAX_ZIP_ENTRIES; index++) {
+          yield {
+            key: `launch/${index}.jpg`,
+            size: 0,
+            uploaded: new Date(),
+            etag: String(index),
+          };
+        }
+      },
+    } as unknown as EventStore;
+
+    await expect(preparePhotoOnlyExport("launch", {
+      store,
+      frameLabelFor: () => undefined,
+      now: () => new Date(),
+    })).rejects.toEqual(new ExportTooLargeError("entry_count"));
+  });
+});
diff --git a/app/export-stream.ts b/app/export-stream.ts
new file mode 100644
index 0000000..42dd449
--- /dev/null
+++ b/app/export-stream.ts
@@ -0,0 +1,226 @@
+import {
+  canonicalEvent,
+  type EventStore,
+  type ExportPhotoSource,
+} from "./event-store";
+import {
+  encodePackageArtifacts,
+  preparePackageRows,
+  type PackagePhotoRow,
+} from "./export-package";
+import {
+  centralPart,
+  endPart,
+  estimateStoreZipBytes,
+  storedEntryHeader,
+} from "./zip";
+
+export const MAX_ZIP_ENTRIES = 0xffff;
+export const MAX_ZIP_BYTES = 3_900_000_000;
+export const MAX_GENERATED_ENTRY_BYTES = 8 * 1024 * 1024;
+export const MAX_GENERATED_TOTAL_BYTES = 16 * 1024 * 1024;
+
+export class ExportTooLargeError extends Error {
+  constructor(
+    readonly reason:
+      | "entry_count"
+      | "zip_bytes"
+      | "generated_entry"
+      | "generated_total",
+  ) {
+    super(`event export exceeds ${reason} limit`);
+  }
+}
+
+export type ExportStreamDeps = {
+  store: EventStore;
+  frameLabelFor: (frameKey: string) => string | undefined;
+  now: () => Date;
+};
+
+type PlannedPhoto = {
+  key: string;
+  size: number;
+  name: Uint8Array;
+  row?: PackagePhotoRow;
+};
+
+type GeneratedFile = {
+  name: string;
+  data: Uint8Array;
+};
+
+const encoder = new TextEncoder();
+const GENERATED_NAMES = [
+  "manifest.csv",
+  "summary.json",
+  "contact-sheet.html",
+] as const;
+
+function basename(key: string): string {
+  return key.split("/").at(-1) ?? key;
+}
+
+function checkEntries(count: number): void {
+  if (count > MAX_ZIP_ENTRIES) throw new ExportTooLargeError("entry_count");
+}
+
+function checkZipSize(
+  entries: readonly { nameBytes: number; dataBytes: number }[],
+): void {
+  if (estimateStoreZipBytes(entries) > MAX_ZIP_BYTES) {
+    throw new ExportTooLargeError("zip_bytes");
+  }
+}
+
+function generatedFiles(input: {
+  event: string;
+  generatedAt: Date;
+  configuredTimeZone?: string;
+  rows: readonly PackagePhotoRow[];
+}): GeneratedFile[] {
+  const artifacts = encodePackageArtifacts(input);
+  return [
+    { name: GENERATED_NAMES[0], data: artifacts.manifest },
+    { name: GENERATED_NAMES[1], data: artifacts.summary },
+    { name: GENERATED_NAMES[2], data: artifacts.contactSheet },
+  ];
+}
+
+function checkGenerated(files: readonly GeneratedFile[]): void {
+  if (files.some((file) => file.data.byteLength > MAX_GENERATED_ENTRY_BYTES)) {
+    throw new ExportTooLargeError("generated_entry");
+  }
+  const total = files.reduce((sum, file) => sum + file.data.byteLength, 0);
+  if (total > MAX_GENERATED_TOTAL_BYTES) {
+    throw new ExportTooLargeError("generated_total");
+  }
+}
+
+function buildStream(input: {
+  photos: readonly PlannedPhoto[];
+  store: EventStore;
+  finish: (emittedRows: readonly PackagePhotoRow[]) => GeneratedFile[];
+}): ReadableStream<Uint8Array> {
+  const central: Uint8Array[] = [];
+  const emittedRows: PackagePhotoRow[] = [];
+  let photoIndex = 0;
+  let offset = 0;
+  let finished = false;
+
+  const emitFile = (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    name: Uint8Array,
+    data: Uint8Array,
+  ) => {
+    const { header, crc, size } = storedEntryHeader(name, data);
+    central.push(centralPart({ name, crc, size, offset }));
+    offset += header.byteLength + data.byteLength;
+    controller.enqueue(header);
+    controller.enqueue(data);
+  };
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      while (photoIndex < input.photos.length) {
+        const photo = input.photos[photoIndex++]!;
+        const object = await input.store.getPhoto(photo.key);
+        if (!object) continue;
+        const data = new Uint8Array(await object.arrayBuffer());
+        emitFile(controller, photo.name, data);
+        if (photo.row) {
+          emittedRows.push({ ...photo.row, sizeBytes: data.byteLength });
+        }
+        return;
+      }
+      if (finished) return;
+      finished = true;
+      const generated = input.finish(emittedRows);
+      checkGenerated(generated);
+      for (const file of generated) {
+        emitFile(controller, encoder.encode(file.name), file.data);
+      }
+      const centralLength = central.reduce(
+        (sum, part) => sum + part.byteLength,
+        0,
+      );
+      for (const part of central) controller.enqueue(part);
+      controller.enqueue(endPart(central.length, centralLength, offset));
+      controller.close();
+    },
+  });
+}
+
+export async function preparePhotoOnlyExport(
+  event: string,
+  deps: ExportStreamDeps,
+): Promise<ReadableStream<Uint8Array>> {
+  const canonical = canonicalEvent(event);
+  const photos: PlannedPhoto[] = [];
+  for await (const object of deps.store.iteratePhotoObjects(canonical)) {
+    photos.push({
+      key: object.key,
+      size: object.size,
+      name: encoder.encode(basename(object.key)),
+    });
+    checkEntries(photos.length);
+  }
+  checkZipSize(photos.map((photo) => ({
+    nameBytes: photo.name.byteLength,
+    dataBytes: photo.size,
+  })));
+  return buildStream({
+    photos,
+    store: deps.store,
+    finish: () => [],
+  });
+}
+
+export async function preparePackageExport(
+  event: string,
+  configuredTimeZone: string | undefined,
+  deps: ExportStreamDeps,
+): Promise<ReadableStream<Uint8Array>> {
+  const canonical = canonicalEvent(event);
+  const sources: ExportPhotoSource[] = [];
+  for await (const source of deps.store.iterateExportPhotoSources(canonical)) {
+    sources.push(source);
+    checkEntries(sources.length + GENERATED_NAMES.length);
+  }
+  const rows = preparePackageRows(sources, deps.frameLabelFor);
+  const generatedAt = deps.now();
+  const candidate = generatedFiles({
+    event: canonical,
+    generatedAt,
+    configuredTimeZone,
+    rows,
+  });
+  checkGenerated(candidate);
+  const photos = sources.map((source, index): PlannedPhoto => ({
+    key: source.key,
+    size: source.size,
+    name: encoder.encode(rows[index]!.archivePath),
+    row: rows[index],
+  }));
+  checkZipSize([
+    ...photos.map((photo) => ({
+      nameBytes: photo.name.byteLength,
+      dataBytes: photo.size,
+    })),
+    ...candidate.map((file) => ({
+      nameBytes: encoder.encode(file.name).byteLength,
+      dataBytes: file.data.byteLength,
+    })),
+  ]);
+
+  return buildStream({
+    photos,
+    store: deps.store,
+    finish: (emittedRows) => generatedFiles({
+      event: canonical,
+      generatedAt,
+      configuredTimeZone,
+      rows: emittedRows,
+    }),
+  });
+}
diff --git a/app/zip.test.ts b/app/zip.test.ts
index 673c56a..ab40de3 100644
--- a/app/zip.test.ts
+++ b/app/zip.test.ts
@@ -1,5 +1,11 @@
 import { test, expect } from "bun:test";
-import { localPart, centralPart, endPart } from "./zip";
+import {
+  centralPart,
+  endPart,
+  estimateStoreZipBytes,
+  localPart,
+  storedEntryHeader,
+} from "./zip";
 
 const te = new TextEncoder();
 const le32At = (b: Uint8Array, i: number) => b[i] | (b[i + 1] << 8) | (b[i + 2] << 16) | ((b[i + 3] << 24) >>> 0);
@@ -42,3 +48,34 @@ test("zip parts assemble into a structurally valid STORE archive", () => {
   const second = offset + central[0].length;
   expect(le32At(zip, second + 42)).toBe(offsets[1]);
 });
+
+test("stored entry header describes separate bytes without copying them", () => {
+  const name = te.encode("portrait.jpg");
+  const data = te.encode("separate photo bytes");
+  const split = storedEntryHeader(name, data);
+  const combined = localPart(name, data);
+
+  expect(split.header.length).toBe(30 + name.length);
+  expect(split.header.slice(30)).toEqual(name);
+  expect(le32At(split.header, 14) >>> 0).toBe(split.crc >>> 0);
+  expect(le32At(split.header, 18)).toBe(data.length);
+  expect(le32At(split.header, 22)).toBe(data.length);
+  expect(split.size).toBe(data.length);
+  expect(combined.bytes).toEqual(
+    new Uint8Array([...split.header, ...data]),
+  );
+});
+
+test("STORE zip estimates exact local, central, and EOCD byte lengths", () => {
+  const entries = [
+    { nameBytes: te.encode("plain.jpg").length, dataBytes: 123 },
+    { nameBytes: te.encode("照片.jpg").length, dataBytes: 456 },
+  ];
+  const expected = entries.reduce(
+    (total, entry) =>
+      total + 30 + entry.nameBytes + entry.dataBytes + 46 + entry.nameBytes,
+    22,
+  );
+
+  expect(estimateStoreZipBytes(entries)).toBe(expected);
+});
diff --git a/app/zip.ts b/app/zip.ts
index 6f69e37..fe93625 100644
--- a/app/zip.ts
+++ b/app/zip.ts
@@ -17,8 +17,12 @@ function concat(...parts: Uint8Array[]): Uint8Array {
   return out;
 }
 
-// Local file header + name + data — the streamable per-file chunk.
-export function localPart(name: Uint8Array, data: Uint8Array): { bytes: Uint8Array; crc: number } {
+// Local file header + name only. Keeping the body separate lets callers
+// enqueue one already-loaded photo without allocating a second full copy.
+export function storedEntryHeader(
+  name: Uint8Array,
+  data: Uint8Array,
+): { header: Uint8Array; crc: number; size: number } {
   const crc = crc32(data);
   const header = concat(
     le32(0x04034b50),
@@ -33,7 +37,13 @@ export function localPart(name: Uint8Array, data: Uint8Array): { bytes: Uint8Arr
     le16(name.length),
     le16(0) // extra field length
   );
-  return { bytes: concat(header, name, data), crc };
+  return { header: concat(header, name), crc, size: data.length };
+}
+
+// Local file header + name + data — retained byte-for-byte for compatibility.
+export function localPart(name: Uint8Array, data: Uint8Array): { bytes: Uint8Array; crc: number } {
+  const { header, crc } = storedEntryHeader(name, data);
+  return { bytes: concat(header, data), crc };
 }
 
 // Central directory record for one file, pointing back at its local header.
@@ -73,3 +83,16 @@ export function endPart(count: number, centralLen: number, centralOffset: number
     le16(0) // comment length
   );
 }
+
+/** Exact byte estimate for a classic STORE archive with no ZIP comment/extra fields. */
+export function estimateStoreZipBytes(
+  entries: readonly { nameBytes: number; dataBytes: number }[],
+): number {
+  return entries.reduce(
+    (total, entry) =>
+      total
+      + 30 + entry.nameBytes + entry.dataBytes
+      + 46 + entry.nameBytes,
+    22,
+  );
+}

From 814d4a0ca5d8a626adc976da19a833f0bc9d70cb Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:43:29 +0800
Subject: [PATCH 086/105] feat: add admin post-event package export

---
 app/[event]/admin/admin.module.css      |  12 +-
 app/[event]/admin/export-client.test.ts |  71 +++++++++++
 app/[event]/admin/export-client.ts      |  70 +++++++++++
 app/[event]/admin/export-panel.test.tsx |  38 ++++++
 app/[event]/admin/export-panel.tsx      | 152 ++++++++++++++++++++++++
 app/[event]/admin/page.tsx              |  38 ++----
 app/i18n/catalog.ts                     |  51 ++++++++
 7 files changed, 402 insertions(+), 30 deletions(-)
 create mode 100644 app/[event]/admin/export-client.test.ts
 create mode 100644 app/[event]/admin/export-client.ts
 create mode 100644 app/[event]/admin/export-panel.test.tsx
 create mode 100644 app/[event]/admin/export-panel.tsx

diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index 2c56b7f..12c8f84 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -71,6 +71,16 @@
 .restoreConfirm button:last-child { color: var(--paper); background: var(--ink); }
 .restoreConfirm button:disabled { cursor: wait; opacity: .6; }
 .sideCard, .linkCard { border: 2px solid var(--ink); padding: 17px; background: #fff; }.sideCard .cardNumber { color: var(--pink); display: block; margin-bottom: 16px; }.sideCard h2 { font-size: 30px; margin-bottom: 10px; }.sideCard p { margin-bottom: 16px; }
+.exportPanel { border: 3px solid var(--ink); padding: 17px; background: #fff; box-shadow: inset 0 7px var(--green); }
+.exportPanel .cardNumber { display: block; margin: 7px 0 14px; color: var(--pink); }
+.exportPanel h2 { font: 900 30px/.9 Impact, "Arial Narrow", sans-serif; letter-spacing: -.02em; text-transform: uppercase; }
+.exportPanel > p { margin-top: 10px; font-size: 14px; line-height: 1.45; }
+.exportPanel .exportHint { border-inline-start: 5px solid var(--amber); padding: 9px 11px; background: #fff5d6; font-weight: 700; }
+.exportActions { display: grid; gap: 8px; margin-top: 14px; }
+.exportPrimary, .exportSecondary { min-height: 48px; width: 100%; border: 2px solid var(--ink); padding: 12px 14px; color: #fff; background: var(--pink); font: 900 14px/1.15 system-ui, sans-serif; cursor: pointer; }
+.exportSecondary { color: var(--ink); background: var(--amber); }
+.exportPrimary:disabled, .exportSecondary:disabled { cursor: wait; opacity: .58; }
+.exportPanel .exportStatus { min-height: 1.45em; margin-top: 9px; font: 800 11px/1.45 ui-monospace, monospace; }
 .keyRow { display: flex; }.keyRow input { min-width: 0; width: 100%; border: 1px solid var(--ink); padding: 11px; font: 12px/1 ui-monospace, monospace; }.keyRow button, .copyWide, .clearKey, .saveButton, .exportButton, .linkActions a, .linkActions button, .failure button { border: 1px solid var(--ink); color: var(--ink); background: var(--amber); padding: 10px 12px; font: 800 12px/1 system-ui, sans-serif; cursor: pointer; text-decoration: none; }.groupHead button:disabled, .keyRow input:disabled, .keyRow button:disabled, .clearKey:disabled { cursor: wait; opacity: .55; }.copyWide, .clearKey { margin-top: 7px; width: 100%; background: #fff; }.clearKey { border-style: dashed; color: #555; }
 .linkCard { display: grid; grid-template-columns: minmax(0, 1fr) 94px; gap: 12px; background: var(--ink); color: #fff; }.linkCard > div > span { color: var(--amber); font: 800 9px/1 ui-monospace, monospace; text-transform: uppercase; }.linkCard h2 { font-size: 25px; margin: 6px 0 10px; }.linkCard code { display: block; color: #d3cec4; font: 10px/1.35 ui-monospace, monospace; word-break: break-all; }.linkCard img { width: 94px; height: 94px; background: #fff; padding: 5px; }.linkActions { display: flex; gap: 5px; margin-top: 12px; }.linkActions a, .linkActions button { flex: 1; padding: 8px; text-align: center; background: transparent; color: #fff; border-color: #777; }.saveButton, .exportButton { width: 100%; padding: 14px; background: var(--pink); color: #fff; border: 0; }.exportButton { margin-top: 8px; color: var(--ink); background: var(--amber); }.saveButton:disabled, .exportButton:disabled { opacity: .5; cursor: wait; }
 .contactSheet { display: grid; grid-template-columns: repeat(auto-fill, minmax(155px, 1fr)); gap: 8px; padding-top: 15px; }.contactPhoto { position: relative; min-width: 0; padding: 7px; background: #fff; border: 1px solid #b2aea5; }.contactPhoto > img { display: block; width: 100%; aspect-ratio: 1; object-fit: cover; background: #ccc; }.contactPhoto > div:not(.deleteConfirm) { display: flex; justify-content: space-between; gap: 8px; padding-top: 7px; }.contactPhoto time { font: 800 10px/1 ui-monospace, monospace; }.contactPhoto code { overflow: hidden; text-overflow: ellipsis; font: 9px/1 ui-monospace, monospace; color: #777; }.removePhoto { width: 100%; margin-top: 7px; border: 0; padding: 6px; background: transparent; color: #b3154a; font: 700 10px/1 system-ui, sans-serif; cursor: pointer; }.deleteConfirm { position: absolute; inset: 7px; z-index: 3; display: flex; flex-direction: column; justify-content: center; gap: 7px; padding: 12px; color: #fff; background: rgba(16,16,16,.96); }.deleteConfirm span { font: 800 12px/1.3 system-ui, sans-serif; }.deleteConfirm button { padding: 7px; border: 1px solid #777; color: #fff; background: transparent; cursor: pointer; }.deleteConfirm button:first-of-type { color: #fff; background: #c51651; border-color: #c51651; }
@@ -78,7 +88,7 @@
 .boothOperations { border-block: 2px solid var(--ink); padding-block: 18px; }.boothOperationsHead { display: flex; align-items: flex-end; justify-content: space-between; gap: 18px; }.boothOperationsHead h2 { margin-top: 8px; font: 900 clamp(30px, 4vw, 52px)/.9 Impact, "Arial Narrow", sans-serif; letter-spacing: -.02em; text-transform: uppercase; }.boothOperationsHead p { max-width: 52ch; margin-top: 8px; font-size: 13px; line-height: 1.4; }.boothControlState { flex: 0 0 auto; border: 2px solid var(--ink); padding: 10px 12px; color: var(--ink); background: var(--green); text-align: end; }.boothControlState[data-paused="true"] { color: #fff; background: #be124e; }.boothControlState span { display: block; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlState strong { display: block; margin-top: 4px; font: 900 19px/1 "Arial Narrow", Arial, sans-serif; text-transform: uppercase; }.boothControlBar { display: grid; grid-template-columns: minmax(0, 1fr) auto; column-gap: 12px; row-gap: 7px; margin-top: 18px; padding: 13px; color: #fff; background: var(--ink); }.boothControlBar label { grid-column: 1 / -1; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlBar textarea { min-height: 44px; width: 100%; resize: vertical; border: 1px solid #777; padding: 10px; color: #fff; background: #1a1a19; font: 13px/1.25 system-ui, sans-serif; }.boothActions { display: flex; align-items: stretch; gap: 7px; }.boothActions button, .boothLoadMore { min-height: 44px; border: 1px solid #777; padding: 10px 12px; color: #fff; background: transparent; font: 800 11px/1.1 system-ui, sans-serif; cursor: pointer; }.boothActions .boothPauseButton { border-color: var(--pink); color: var(--ink); background: var(--pink); }.boothActions button:disabled, .boothLoadMore:disabled, .boothControlBar textarea:disabled { cursor: wait; opacity: .58; }.boothStatusError { margin-top: 9px; border-inline-start: 5px solid #be124e; padding: 10px 12px; color: #8f1239; background: #ffe4e6; font: 800 12px/1.3 system-ui, sans-serif; }.boothRoster { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 295px), 1fr)); gap: 9px; margin: 14px 0 0; padding: 0; list-style: none; }.boothRow { min-width: 0; border: 2px solid var(--ink); padding: 11px; background: #fff; }.boothRow[data-stale="true"] { border-color: #be124e; background: #fff1f2; }.boothRowHead { display: flex; align-items: center; justify-content: space-between; gap: 9px; padding-bottom: 9px; border-bottom: 1px solid var(--ink); }.boothRowHead > code { min-width: 0; overflow: hidden; font: 800 13px/1 ui-monospace, monospace; text-overflow: ellipsis; white-space: nowrap; }.boothPresence { flex: 0 0 auto; padding: 4px 6px; color: #fff; background: #be124e; font: 900 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothPresence[data-live="true"] { color: var(--ink); background: var(--green); }.boothFacts { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 9px 12px; margin-top: 10px; }.boothFacts div { min-width: 0; }.boothFacts dt { color: #635f57; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .06em; text-transform: uppercase; }.boothFacts dd { overflow: hidden; margin-top: 3px; font: 800 12px/1.2 system-ui, sans-serif; text-overflow: ellipsis; white-space: nowrap; }.boothFacts dd code { font: 800 11px/1.2 ui-monospace, monospace; }.boothEmpty { margin-top: 14px; border: 2px dashed #8c8880; padding: 20px; background: rgba(255,255,255,.5); }.boothEmpty strong { font: 900 20px/1 Impact, sans-serif; text-transform: uppercase; }.boothEmpty p { margin-top: 7px; font-size: 13px; }.boothLoadMore { display: block; width: 100%; margin-top: 9px; border-color: var(--ink); color: var(--ink); background: var(--amber); }
 .authPage { display: grid; place-items: center; padding: 20px; background: var(--ink); color: #fff; }.authCard { width: min(500px, 100%); border-top: 8px solid var(--pink); padding: clamp(25px, 5vw, 55px); background: #1a1a19; }.authCard h1 { margin: 25px 0; font: 900 clamp(58px, 10vw, 90px)/.78 Impact, sans-serif; text-transform: uppercase; }.authCard > p:not(.kicker) { color: #bbb; line-height: 1.4; margin-bottom: 28px; }.authCard label { display: block; margin-bottom: 8px; font: 800 11px/1 ui-monospace, monospace; text-transform: uppercase; }.authCard input { width: 100%; padding: 14px; border: 1px solid #777; background: #080808; color: #fff; font: 16px/1 ui-monospace, monospace; }.authCard button { width: 100%; margin-top: 10px; padding: 15px; border: 0; color: #fff; background: var(--pink); font-weight: 900; cursor: pointer; }
 .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
-@media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; }.localeOptions label:has(input:checked), .experienceToggle:has(input:checked) { border: 2px solid Highlight; box-shadow: none; } }
+@media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; }.localeOptions label:has(input:checked), .experienceToggle:has(input:checked) { border: 2px solid Highlight; box-shadow: none; }.exportPanel { border: 3px solid CanvasText; box-shadow: none; }.exportPrimary, .exportSecondary { border: 2px solid ButtonText; } }
 @media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; }.boothOperationsHead { align-items: start; flex-direction: column; }.boothControlState { text-align: start; } }
 @media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; }.boothControlBar { grid-template-columns: 1fr; }.boothActions { display: grid; grid-template-columns: 1fr 1fr; }.boothRoster { grid-template-columns: 1fr; } }
 @media (max-width: 600px) { .experiencePanel { grid-template-columns: 1fr; }.localeOptions { grid-template-columns: 1fr; }.experienceField { grid-template-columns: 1fr; gap: 6px; } }
diff --git a/app/[event]/admin/export-client.test.ts b/app/[event]/admin/export-client.test.ts
new file mode 100644
index 0000000..3be9924
--- /dev/null
+++ b/app/[event]/admin/export-client.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import {
+  adminExportRequest,
+  downloadAdminExport,
+  ExportDownloadError,
+} from "./export-client";
+
+describe("Admin export client", () => {
+  test("builds exact package and compatibility requests with the secret only in a header", () => {
+    expect(adminExportRequest({
+      event: "launch",
+      adminKey: "secret",
+      mode: "package",
+    })).toEqual({
+      url: "/api/export?event=launch&format=package&contactSheet=1",
+      suggestedName: "launch-package.zip",
+      headers: { "x-booth-key": "secret" },
+    });
+    const photos = adminExportRequest({
+      event: "launch",
+      adminKey: "secret",
+      mode: "photos",
+    });
+    expect(photos).toEqual({
+      url: "/api/export?event=launch",
+      suggestedName: "launch-photos.zip",
+      headers: { "x-booth-key": "secret" },
+    });
+    expect(`${photos.url}${photos.suggestedName}`).not.toContain("secret");
+  });
+
+  test("asks for a file destination before fetching and pipes the response body", async () => {
+    const order: string[] = [];
+    const written: Uint8Array[] = [];
+    const writable = new WritableStream<Uint8Array>({
+      write(value) { written.push(value); },
+    });
+    await downloadAdminExport(
+      { event: "launch", adminKey: "secret", mode: "package" },
+      {
+        pickFile: async (name) => {
+          order.push(`pick:${name}`);
+          return { createWritable: async () => writable };
+        },
+        fetch: async (url, init) => {
+          order.push(`fetch:${url}:${new Headers(init?.headers).get("x-booth-key")}`);
+          return new Response(new Uint8Array([1, 2, 3]));
+        },
+        fallback: () => { throw new Error("fallback should not run"); },
+      },
+    );
+
+    expect(order).toEqual([
+      "pick:launch-package.zip",
+      "fetch:/api/export?event=launch&format=package&contactSheet=1:secret",
+    ]);
+    expect(written).toEqual([new Uint8Array([1, 2, 3])]);
+  });
+
+  test("uses bounded status errors and never returns raw response text", async () => {
+    for (const status of [401, 413, 422, 503, 500]) {
+      await expect(downloadAdminExport(
+        { event: "launch", adminKey: "secret", mode: "photos" },
+        {
+          fetch: async () => new Response("raw private exception", { status }),
+          fallback: () => {},
+        },
+      )).rejects.toEqual(new ExportDownloadError(status));
+    }
+  });
+});
diff --git a/app/[event]/admin/export-client.ts b/app/[event]/admin/export-client.ts
new file mode 100644
index 0000000..9d37cd6
--- /dev/null
+++ b/app/[event]/admin/export-client.ts
@@ -0,0 +1,70 @@
+export type AdminExportMode = "package" | "photos";
+
+export type AdminExportRequest = {
+  url: string;
+  suggestedName: string;
+  headers: { "x-booth-key": string };
+};
+
+export type SaveFileHandle = {
+  createWritable(): Promise<WritableStream<Uint8Array>>;
+};
+
+export type ExportDownloadDeps = {
+  fetch: (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ) => Promise<Response>;
+  pickFile?: (suggestedName: string) => Promise<SaveFileHandle>;
+  fallback: (blob: Blob, suggestedName: string) => void;
+};
+
+export class ExportDownloadError extends Error {
+  constructor(readonly status: number) {
+    super(`export request failed with status ${status}`);
+  }
+}
+
+export function adminExportRequest(input: {
+  event: string;
+  adminKey: string;
+  mode: AdminExportMode;
+}): AdminExportRequest {
+  return input.mode === "package"
+    ? {
+      url: `/api/export?event=${encodeURIComponent(input.event)}&format=package&contactSheet=1`,
+      suggestedName: `${input.event}-package.zip`,
+      headers: { "x-booth-key": input.adminKey },
+    }
+    : {
+      url: `/api/export?event=${encodeURIComponent(input.event)}`,
+      suggestedName: `${input.event}-photos.zip`,
+      headers: { "x-booth-key": input.adminKey },
+    };
+}
+
+export async function downloadAdminExport(
+  input: {
+    event: string;
+    adminKey: string;
+    mode: AdminExportMode;
+  },
+  deps: ExportDownloadDeps,
+): Promise<void> {
+  const request = adminExportRequest(input);
+  // This deliberately happens before the first network await so the native
+  // picker retains the click's user activation.
+  const handle = deps.pickFile
+    ? await deps.pickFile(request.suggestedName)
+    : null;
+  const response = await deps.fetch(request.url, {
+    cache: "no-store",
+    headers: request.headers,
+  });
+  if (!response.ok) throw new ExportDownloadError(response.status);
+  if (handle && response.body) {
+    await response.body.pipeTo(await handle.createWritable());
+    return;
+  }
+  deps.fallback(await response.blob(), request.suggestedName);
+}
diff --git a/app/[event]/admin/export-panel.test.tsx b/app/[event]/admin/export-panel.test.tsx
new file mode 100644
index 0000000..7543eff
--- /dev/null
+++ b/app/[event]/admin/export-panel.test.tsx
@@ -0,0 +1,38 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ExportPanel } from "./export-panel";
+
+const render = (locale: "en" | "zh-SG" | "ar" = "en") =>
+  renderToStaticMarkup(
+    <ExportPanel
+      event="launch"
+      adminKey="never-render-this-secret"
+      locale={locale}
+      onUnauthorized={() => {}}
+      onNotice={() => {}}
+      onError={() => {}}
+    />,
+  );
+
+test("renders an accessible primary package action and secondary compatibility action", () => {
+  const html = render();
+  expect(html).toContain("<h2");
+  expect(html).toContain("Post-event package");
+  expect(html).toContain("manifest");
+  expect(html).toContain("analytics");
+  expect(html).toContain("printable contact sheet");
+  expect(html).toContain(">Download event package</button>");
+  expect(html).toContain(">Download photos only</button>");
+  expect(html).toContain('aria-live="polite"');
+  expect(html).not.toMatch(/Export \d+ photos/);
+  expect(html).not.toContain("never-render-this-secret");
+  expect(html).not.toContain("href=");
+  expect(html).not.toContain("localStorage");
+});
+
+test("renders complete localized copy and Arabic direction", () => {
+  expect(render("zh-SG")).toContain("下载活动资料包");
+  const arabic = render("ar");
+  expect(arabic).toContain('dir="rtl"');
+  expect(arabic).toContain("تنزيل حزمة الحدث");
+});
diff --git a/app/[event]/admin/export-panel.tsx b/app/[event]/admin/export-panel.tsx
new file mode 100644
index 0000000..baa7b27
--- /dev/null
+++ b/app/[event]/admin/export-panel.tsx
@@ -0,0 +1,152 @@
+"use client";
+
+import { useState } from "react";
+import {
+  localeDirection,
+  message,
+  type SupportedLocale,
+} from "../../i18n/catalog";
+import {
+  downloadAdminExport,
+  ExportDownloadError,
+  type AdminExportMode,
+  type ExportDownloadDeps,
+  type SaveFileHandle,
+} from "./export-client";
+import styles from "./admin.module.css";
+
+export type ExportPanelProps = {
+  event: string;
+  adminKey: string;
+  locale: SupportedLocale;
+  onUnauthorized: () => void;
+  onNotice: (message: string) => void;
+  onError: (message: string) => void;
+};
+
+type FilePickerWindow = Window & {
+  showSaveFilePicker?: (options: {
+    suggestedName: string;
+    types: Array<{
+      description: string;
+      accept: Record<string, string[]>;
+    }>;
+  }) => Promise<SaveFileHandle>;
+};
+
+function browserDownloadDeps(): ExportDownloadDeps {
+  const picker = (window as FilePickerWindow).showSaveFilePicker;
+  return {
+    fetch: window.fetch.bind(window),
+    ...(picker
+      ? {
+        pickFile: (suggestedName: string) => picker({
+          suggestedName,
+          types: [{
+            description: "ZIP archive",
+            accept: { "application/zip": [".zip"] },
+          }],
+        }),
+      }
+      : {}),
+    fallback(blob, suggestedName) {
+      const url = URL.createObjectURL(blob);
+      const anchor = document.createElement("a");
+      anchor.href = url;
+      anchor.download = suggestedName;
+      anchor.click();
+      URL.revokeObjectURL(url);
+    },
+  };
+}
+
+function errorMessage(locale: SupportedLocale, status: number): string {
+  if (status === 413) return message(locale, "exportTooLarge");
+  if (status === 422) return message(locale, "exportMetadataInvalid");
+  if (status === 503) return message(locale, "exportUnavailable");
+  return message(locale, "exportGenericError");
+}
+
+export function ExportPanel({
+  event,
+  adminKey,
+  locale,
+  onUnauthorized,
+  onNotice,
+  onError,
+}: ExportPanelProps) {
+  const [activeMode, setActiveMode] = useState<AdminExportMode | null>(null);
+
+  const download = async (mode: AdminExportMode) => {
+    if (activeMode !== null) return;
+    setActiveMode(mode);
+    onError("");
+    try {
+      await downloadAdminExport(
+        { event, adminKey, mode },
+        browserDownloadDeps(),
+      );
+      onNotice(message(
+        locale,
+        mode === "package" ? "exportPackageDone" : "exportPhotosDone",
+      ));
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") return;
+      if (error instanceof ExportDownloadError) {
+        if (error.status === 401) {
+          onUnauthorized();
+          return;
+        }
+        onError(errorMessage(locale, error.status));
+        return;
+      }
+      onError(message(locale, "exportGenericError"));
+    } finally {
+      setActiveMode(null);
+    }
+  };
+
+  const busyText = activeMode === "package"
+    ? message(locale, "exportPackageBusy")
+    : activeMode === "photos"
+      ? message(locale, "exportPhotosBusy")
+      : "";
+
+  return (
+    <section
+      className={styles.exportPanel}
+      dir={localeDirection(locale)}
+      aria-labelledby="post-event-export-title"
+    >
+      <span className={styles.cardNumber}>07</span>
+      <h2 id="post-event-export-title">{message(locale, "exportPanelTitle")}</h2>
+      <p>{message(locale, "exportPanelDescription")}</p>
+      <p className={styles.exportHint}>{message(locale, "exportDesktopHint")}</p>
+      <div className={styles.exportActions}>
+        <button
+          className={styles.exportPrimary}
+          type="button"
+          disabled={activeMode !== null}
+          onClick={() => void download("package")}
+        >
+          {activeMode === "package"
+            ? message(locale, "exportPackageBusy")
+            : message(locale, "exportPackageAction")}
+        </button>
+        <button
+          className={styles.exportSecondary}
+          type="button"
+          disabled={activeMode !== null}
+          onClick={() => void download("photos")}
+        >
+          {activeMode === "photos"
+            ? message(locale, "exportPhotosBusy")
+            : message(locale, "exportPhotosAction")}
+        </button>
+      </div>
+      <p className={styles.exportStatus} aria-live="polite" aria-atomic="true">
+        {busyText}
+      </p>
+    </section>
+  );
+}
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index b5a45fc..8b273c0 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -22,6 +22,7 @@ import {
 } from "./booth-operations";
 import { BoothOperationsPanel } from "./booth-operations-panel";
 import { ConfigHistoryPanel } from "./config-history-panel";
+import { ExportPanel } from "./export-panel";
 import {
   buildConfigSaveBody,
   clearRestoreRequestAfterReconciliation,
@@ -39,7 +40,6 @@ type Photo = { key: string; url: string; uploadedAt: string };
 type AuthState = "missing" | "ready" | "invalid";
 type Probe = { status: "up" | "degraded" | "down"; detail: string };
 type Health = { upload: Probe; live: Probe };
-type FilePickerWindow = Window & { showSaveFilePicker?: (options: { suggestedName: string; types: { description: string; accept: Record<string, string[]> }[] }) => Promise<{ createWritable(): Promise<WritableStream<Uint8Array>> }> };
 const CONFIG_CONFLICT_MESSAGE = "Configuration changed; review the latest version before saving.";
 
 export default function Admin() {
@@ -66,7 +66,6 @@ export default function Admin() {
   const [photosLoaded, setPhotosLoaded] = useState(false);
   const [photosError, setPhotosError] = useState("");
   const [saving, setSaving] = useState(false);
-  const [exporting, setExporting] = useState(false);
   const [deleting, setDeleting] = useState("");
   const [confirmDelete, setConfirmDelete] = useState("");
   const [notice, setNotice] = useState("");
@@ -650,32 +649,6 @@ export default function Admin() {
     }
   };
 
-  const exportZip = async () => {
-    setExporting(true); setError("");
-    try {
-      // Ask for the destination while the click's user activation is still
-      // live. The response can then stream straight to disk without a giant blob.
-      const picker = (window as FilePickerWindow).showSaveFilePicker;
-      const handle = picker ? await picker({ suggestedName: `${event}-photos.zip`, types: [{ description: "ZIP archive", accept: { "application/zip": [".zip"] } }] }) : null;
-      const response = await fetch(`/api/export?event=${encodeURIComponent(event)}`, { headers: { "x-booth-key": adminKey } });
-      if (response.status === 401) { invalidateAuth(); throw new Error("That admin key was rejected."); }
-      if (!response.ok) throw new Error(`Export failed (${response.status})`);
-      if (handle && response.body) {
-        const writable = await handle.createWritable();
-        await response.body.pipeTo(writable);
-      } else {
-        const blob = await response.blob();
-        const url = URL.createObjectURL(blob);
-        const anchor = document.createElement("a");
-        anchor.href = url; anchor.download = `${event}-photos.zip`; anchor.click();
-        URL.revokeObjectURL(url);
-      }
-    } catch (cause) {
-      if (cause instanceof DOMException && cause.name === "AbortError") return;
-      setError(cause instanceof Error ? cause.message : "Export could not be created");
-    } finally { setExporting(false); }
-  };
-
   const deletePhoto = async (photo: Photo) => {
     setDeleting(photo.key); setError("");
     try {
@@ -852,8 +825,15 @@ export default function Admin() {
               saving={saving}
               onSave={() => void save()}
             />
-            <button className={styles.exportButton} onClick={() => void exportZip()} disabled={exporting}>{exporting ? "Building archive…" : `Export ${photos.length} photos (.zip)`}</button>
           </section>
+          <ExportPanel
+            event={event}
+            adminKey={adminKey}
+            locale={defaultLocale}
+            onUnauthorized={invalidateAuth}
+            onNotice={setNotice}
+            onError={setError}
+          />
         </aside>
       </div>
     </main>
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
index 94226db..228486c 100644
--- a/app/i18n/catalog.ts
+++ b/app/i18n/catalog.ts
@@ -50,6 +50,25 @@ export const englishMessages = {
   captureFailed: "We couldn’t prepare this photo. Please try again.",
   saveFailed: "We couldn’t safely save this photo. Choose Use Photo to retry or Retake.",
   decodeFailed: "We couldn’t read this photo. Please take another one.",
+  exportPanelTitle: "Post-event package",
+  exportPanelDescription:
+    "Download photos with an escaped manifest, timezone-aware analytics, and a printable contact sheet.",
+  exportDesktopHint:
+    "For large archives, use a desktop browser with direct-to-disk downloads.",
+  exportPackageAction: "Download event package",
+  exportPhotosAction: "Download photos only",
+  exportPackageBusy: "Downloading event package…",
+  exportPhotosBusy: "Downloading photos…",
+  exportPackageDone: "Event package downloaded.",
+  exportPhotosDone: "Photo archive downloaded.",
+  exportTooLarge:
+    "This event exceeds the single-ZIP safety limit. Try photos-only or ask an operator to split the export; do not delete photos.",
+  exportMetadataInvalid:
+    "Stored photo metadata needs investigation. Photos-only export remains available.",
+  exportUnavailable:
+    "Export is temporarily unavailable. Your photos are unchanged; please retry.",
+  exportGenericError:
+    "The export could not be downloaded. Your photos are unchanged; please retry.",
 } satisfies Record<string, string>;
 
 export type MessageKey = keyof typeof englishMessages;
@@ -99,6 +118,19 @@ export const chineseSingaporeMessages: Record<MessageKey, string> = {
   captureFailed: "无法准备这张照片。请重试。",
   saveFailed: "无法安全保存这张照片。请选择“使用照片”重试或重拍。",
   decodeFailed: "无法读取这张照片。请重新拍摄。",
+  exportPanelTitle: "活动结束资料包",
+  exportPanelDescription: "下载照片，以及安全转义的清单、按时区统计的数据和可打印的联系表。",
+  exportDesktopHint: "大型压缩包建议使用支持直接保存到磁盘的桌面浏览器下载。",
+  exportPackageAction: "下载活动资料包",
+  exportPhotosAction: "仅下载照片",
+  exportPackageBusy: "正在下载活动资料包…",
+  exportPhotosBusy: "正在下载照片…",
+  exportPackageDone: "活动资料包已下载。",
+  exportPhotosDone: "照片压缩包已下载。",
+  exportTooLarge: "此活动超过单个 ZIP 的安全上限。请尝试仅下载照片，或请操作员拆分导出；不要删除照片。",
+  exportMetadataInvalid: "存储的照片元数据需要检查。仍可使用仅下载照片。",
+  exportUnavailable: "导出暂时不可用。照片未被更改，请重试。",
+  exportGenericError: "无法下载导出文件。照片未被更改，请重试。",
 };
 
 export const arabicMessages: Record<MessageKey, string> = {
@@ -150,6 +182,25 @@ export const arabicMessages: Record<MessageKey, string> = {
   saveFailed:
     "تعذر حفظ هذه الصورة بأمان. اختر استخدام الصورة للمحاولة مجددًا أو أعد الالتقاط.",
   decodeFailed: "تعذرت قراءة هذه الصورة. التقط صورة أخرى.",
+  exportPanelTitle: "حزمة ما بعد الحدث",
+  exportPanelDescription:
+    "نزّل الصور مع بيان آمن وتحليلات حسب المنطقة الزمنية وصفحة صور قابلة للطباعة.",
+  exportDesktopHint:
+    "للأرشيفات الكبيرة، استخدم متصفح سطح مكتب يدعم التنزيل المباشر إلى القرص.",
+  exportPackageAction: "تنزيل حزمة الحدث",
+  exportPhotosAction: "تنزيل الصور فقط",
+  exportPackageBusy: "جارٍ تنزيل حزمة الحدث…",
+  exportPhotosBusy: "جارٍ تنزيل الصور…",
+  exportPackageDone: "تم تنزيل حزمة الحدث.",
+  exportPhotosDone: "تم تنزيل أرشيف الصور.",
+  exportTooLarge:
+    "يتجاوز هذا الحدث حد أمان ملف ZIP واحد. جرّب الصور فقط أو اطلب من المشغّل تقسيم التصدير؛ لا تحذف الصور.",
+  exportMetadataInvalid:
+    "تحتاج بيانات الصور المخزنة إلى التحقيق. يظل تصدير الصور فقط متاحًا.",
+  exportUnavailable:
+    "التصدير غير متاح مؤقتًا. لم تتغير صورك؛ يرجى إعادة المحاولة.",
+  exportGenericError:
+    "تعذر تنزيل التصدير. لم تتغير صورك؛ يرجى إعادة المحاولة.",
 };
 
 const catalogs: Record<SupportedLocale, Record<MessageKey, string>> = {

From 63f7983cd29d3e93e9dd6bdc454407277ad25822 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:46:54 +0800
Subject: [PATCH 087/105] test: verify post-event package release

---
 docs/runbooks/deployment.md          |  24 +++
 docs/runbooks/pre-event-readiness.md |  34 +++++
 tests/post-event-package.spec.ts     | 211 +++++++++++++++++++++++++++
 3 files changed, 269 insertions(+)
 create mode 100644 tests/post-event-package.spec.ts

diff --git a/docs/runbooks/deployment.md b/docs/runbooks/deployment.md
index ad29991..84ee507 100644
--- a/docs/runbooks/deployment.md
+++ b/docs/runbooks/deployment.md
@@ -80,6 +80,30 @@ Only after recording a passing iPad rehearsal should you promote explicitly:
 bun run deploy:production
 ```
 
+### Release 5 staging export gate
+
+Use a canonical throwaway staging Event that is distinct from every production
+Event. Upload designated current and legacy canaries, including one missing a
+private receipt. Export the legacy photo-only ZIP and confirm its root-photo
+layout is unchanged. Export the enriched package, run `unzip -t`, and complete
+the offline contact-sheet, print-preview, spreadsheet, timezone/analytics, and
+private-data checks in `pre-event-readiness.md`.
+
+Delete only the designated staging canary by its complete Event-owned key.
+Export again and confirm that exact photo is absent from all package sections.
+Confirm neither export can return production photos and that no staging state
+is visible through the production Worker.
+
+- `413` is the single STORE ZIP/Worker safety limit. It is not permission to
+  delete stored photos; use photo-only export or arrange operator-assisted
+  splitting.
+- `422` means private photo metadata needs investigation. The compatibility
+  photo-only export remains available.
+- `503` is a retryable private/export infrastructure failure.
+- Never exercise large-Event limits by filling production storage.
+- Rollback changes Worker code only. It never deletes or rewrites `PHOTOS` or
+  `STATE`.
+
 After production deployment, verify the home page, Event config read/write, one exact-key throwaway upload/delete, incremental Live Gallery arrival, export, Worker logs, and the next health cron tick. The canary proves R2 write/read and public delivery; external uptime proves the Worker can be reached.
 
 ## Lazy legacy-state migration
diff --git a/docs/runbooks/pre-event-readiness.md b/docs/runbooks/pre-event-readiness.md
index 58211f9..a39071b 100644
--- a/docs/runbooks/pre-event-readiness.md
+++ b/docs/runbooks/pre-event-readiness.md
@@ -93,6 +93,40 @@ For moderation cleanup, first copy the complete throwaway image key and verify
 that it belongs to the staging Event. Delete only that exact key; never use a
 prefix, filename fragment, or production Event.
 
+## Post-event package rehearsal
+
+Use a throwaway canonical staging Event with a configured timezone and a
+fixture containing a current framed photo, a camera-fallback photo, a legacy
+photo without a receipt, and a removed/unknown historical Frame.
+
+1. Download the photo-only ZIP and confirm every photo remains at the archive
+   root with no generated entries.
+2. Download the enriched package and confirm it contains `photos/`,
+   `manifest.csv`, `summary.json`, and `contact-sheet.html`.
+3. Run `unzip -t <event>-package.zip` and require a clean result.
+4. Extract the package, disable networking, and open
+   `contact-sheet.html`. Confirm every image loads through its relative
+   `photos/` path.
+5. Open print preview and inspect the grid, page breaks, captions, and target
+   paper size.
+6. Import `manifest.csv` into Excel, Numbers, or Google Sheets and confirm
+   formula-looking fixture cells remain text.
+7. Compare the configured timezone, first/last capture, hourly and busiest
+   periods, Frame usage, byte totals, and metadata-coverage totals against the
+   fixture.
+8. Delete only one designated throwaway photo by its complete Event-owned key,
+   export again, and confirm it is absent from photos, manifest, summary, and
+   contact sheet.
+9. Search the extracted package for `photo-metadata`, `photo-index`, revision
+   IDs, Booth records, rehearsal evidence, health state, hashes, credentials,
+   and private storage prefixes. None may be present.
+
+The automated suite cannot certify native desktop file-picker streaming,
+production-like R2 behavior during a long response, spreadsheet application
+imports, offline extracted-file policy, or the operator's actual printer.
+Record those manual desktop/staging results before relying on the post-event
+package.
+
 ## Operational checks
 
 - Confirm the production and staging domains show the intended build and do not share Event data.
diff --git a/tests/post-event-package.spec.ts b/tests/post-event-package.spec.ts
new file mode 100644
index 0000000..057498f
--- /dev/null
+++ b/tests/post-event-package.spec.ts
@@ -0,0 +1,211 @@
+import { expect, test, type BrowserContext, type Page } from "@playwright/test";
+
+const EVENT = "post-event-package";
+const ADMIN_KEY = "browser-admin-secret";
+
+type ExportFixture = {
+  status: number;
+  requests: Array<{
+    url: string;
+    key: string;
+  }>;
+  delay: boolean;
+};
+
+async function installAdminMocks(
+  context: BrowserContext,
+  fixture: ExportFixture,
+) {
+  await context.route("**/api/**", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    const key = request.headers()["x-booth-key"] ?? "";
+
+    if (url.pathname === "/api/export") {
+      fixture.requests.push({ url: url.href, key });
+      if (fixture.delay) {
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      if (fixture.status !== 200) {
+        await route.fulfill({
+          status: fixture.status,
+          contentType: "application/json",
+          body: JSON.stringify({ error: "raw private error must not render" }),
+        });
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/zip",
+        headers: {
+          "content-disposition": url.searchParams.get("format") === "package"
+            ? `attachment; filename="${EVENT}-package.zip"`
+            : `attachment; filename="${EVENT}-photos.zip"`,
+        },
+        body: "PK fixture archive",
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/health") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          upload: { status: "up", detail: "fixture" },
+          live: { status: "up", detail: "fixture" },
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/config/revisions") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          config: {
+            frames: ["square"],
+            hasBoothKey: true,
+            locales: ["en"],
+            defaultLocale: "en",
+            timeZone: "Asia/Singapore",
+          },
+          currentRevisionId: null,
+          revisions: [],
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/photos") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ photos: [], cursor: null }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/booth-state") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          version: 1,
+          paused: false,
+          updatedAt: "2026-07-24T12:00:00.000Z",
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/booths") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ booths: [], cursor: null }),
+      });
+      return;
+    }
+    throw new Error(`Unexpected Admin API request: ${request.method()} ${url.pathname}`);
+  });
+}
+
+async function unlock(page: Page) {
+  await page.goto(`/${EVENT}/admin`);
+  const input = page.getByLabel("Admin key");
+  await input.focus();
+  await input.fill(ADMIN_KEY);
+  await input.press("Enter");
+  await expect(page.getByRole("heading", { name: EVENT })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Post-event package" })).toBeVisible();
+}
+
+test("Admin downloads exact package and compatibility archives accessibly", async ({
+  context,
+  page,
+}) => {
+  const fixture: ExportFixture = { status: 200, requests: [], delay: true };
+  await installAdminMocks(context, fixture);
+  await unlock(page);
+
+  const exportPanel = page.getByRole("heading", {
+    name: "Post-event package",
+  }).locator("..");
+  const packageButton = exportPanel.getByRole("button").nth(0);
+  const photosButton = exportPanel.getByRole("button").nth(1);
+  const packageDownload = page.waitForEvent("download");
+  await packageButton.click();
+  await expect(packageButton).toBeDisabled();
+  await expect(photosButton).toBeDisabled();
+  await expect(exportPanel.locator('[aria-live="polite"]')).toHaveText(
+    "Downloading event package…",
+  );
+  expect((await packageDownload).suggestedFilename()).toBe(`${EVENT}-package.zip`);
+
+  fixture.delay = false;
+  const photosDownload = page.waitForEvent("download");
+  await photosButton.click();
+  expect((await photosDownload).suggestedFilename()).toBe(`${EVENT}-photos.zip`);
+
+  expect(fixture.requests).toEqual([
+    {
+      url: `http://127.0.0.1:3100/api/export?event=${EVENT}&format=package&contactSheet=1`,
+      key: ADMIN_KEY,
+    },
+    {
+      url: `http://127.0.0.1:3100/api/export?event=${EVENT}`,
+      key: ADMIN_KEY,
+    },
+  ]);
+  for (const request of fixture.requests) {
+    expect(request.url).not.toContain(ADMIN_KEY);
+  }
+
+  const violations = await page.evaluate(() => {
+    const issues: string[] = [];
+    const ids = [...document.querySelectorAll("[id]")].map((node) => node.id);
+    if (new Set(ids).size !== ids.length) issues.push("duplicate ids");
+    for (const image of document.querySelectorAll("img")) {
+      if (!image.hasAttribute("alt")) issues.push("image without alt");
+    }
+    for (const button of document.querySelectorAll("button")) {
+      if (!(button.textContent ?? "").trim() && !button.getAttribute("aria-label")) {
+        issues.push("unnamed button");
+      }
+    }
+    return issues;
+  });
+  expect(violations).toEqual([]);
+});
+
+test("Admin renders bounded export errors and a retry remains available", async ({
+  context,
+  page,
+}) => {
+  const fixture: ExportFixture = { status: 413, requests: [], delay: false };
+  await installAdminMocks(context, fixture);
+  await unlock(page);
+  const packageButton = page.getByRole("button", {
+    name: "Download event package",
+  });
+
+  await packageButton.click();
+  await expect(page.getByText(/single-ZIP safety limit/)).toBeVisible();
+  await expect(page.getByText("raw private error must not render")).toHaveCount(0);
+  await expect(packageButton).toBeEnabled();
+
+  fixture.status = 422;
+  await packageButton.click();
+  await expect(page.getByText(/metadata needs investigation/)).toBeVisible();
+
+  fixture.status = 503;
+  await packageButton.click();
+  await expect(page.getByText(/temporarily unavailable/)).toBeVisible();
+
+  fixture.status = 200;
+  const retryDownload = page.waitForEvent("download");
+  await packageButton.click();
+  expect((await retryDownload).suggestedFilename()).toBe(`${EVENT}-package.zip`);
+
+  fixture.status = 401;
+  await packageButton.click();
+  await expect(page.getByRole("heading", { name: /Operator sign-in/i })).toBeVisible();
+});

From b0201d98932516bace0f2fedd2e3dc257bcddadc Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:43:52 +0800
Subject: [PATCH 088/105] feat: preserve projector with shared gallery controls

---
 app/[event]/gallery/gallery.module.css      |  97 ++++++++
 app/[event]/gallery/photo-actions.test.ts   | 131 ++++++++++
 app/[event]/gallery/photo-actions.ts        | 162 +++++++++++++
 app/[event]/gallery/photo-lightbox.test.tsx |  66 +++++
 app/[event]/gallery/photo-lightbox.tsx      | 188 ++++++++++++++
 app/[event]/live/live.module.css            |  23 +-
 app/[event]/live/marquee.test.ts            |  44 ++++
 app/[event]/live/marquee.ts                 |  20 ++
 app/[event]/live/page.tsx                   | 256 ++++++++------------
 app/[event]/live/wrap.test.ts               |   5 +
 app/i18n/catalog.ts                         |  51 ++++
 11 files changed, 883 insertions(+), 160 deletions(-)
 create mode 100644 app/[event]/gallery/photo-actions.test.ts
 create mode 100644 app/[event]/gallery/photo-actions.ts
 create mode 100644 app/[event]/gallery/photo-lightbox.test.tsx
 create mode 100644 app/[event]/gallery/photo-lightbox.tsx
 create mode 100644 app/[event]/live/marquee.test.ts
 create mode 100644 app/[event]/live/marquee.ts

diff --git a/app/[event]/gallery/gallery.module.css b/app/[event]/gallery/gallery.module.css
index 316adb0..c260bc6 100644
--- a/app/[event]/gallery/gallery.module.css
+++ b/app/[event]/gallery/gallery.module.css
@@ -99,3 +99,100 @@
 @media (prefers-reduced-motion: reduce) {
   .photo { animation: none; }
 }
+
+.lightbox {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr) auto auto;
+  gap: 14px;
+  padding: max(16px, env(safe-area-inset-top)) max(16px, env(safe-area-inset-right)) max(16px, env(safe-area-inset-bottom)) max(16px, env(safe-area-inset-left));
+  color: #fff;
+  background: rgba(5, 3, 5, .96);
+}
+
+.lightboxHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  width: min(100%, 1100px);
+  margin: auto;
+}
+
+.lightboxHeader h2 {
+  font-size: clamp(20px, 4vw, 32px);
+}
+
+.lightboxPhoto {
+  width: min(100%, 1100px);
+  height: 100%;
+  min-height: 0;
+  margin: auto;
+  object-fit: contain;
+}
+
+.lightboxActions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 10px;
+}
+
+.lightboxActions button,
+.iconAction {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 10px 18px;
+  border: 2px solid transparent;
+  border-radius: 999px;
+  color: #210713;
+  background: #ff75b5;
+  font: inherit;
+  font-weight: 750;
+  cursor: pointer;
+}
+
+.iconAction {
+  padding: 0;
+  color: #fff;
+  background: rgba(255, 255, 255, .14);
+  font-size: 28px;
+}
+
+.lightboxActions button:disabled { opacity: .55; }
+
+.lightboxLink {
+  width: min(100%, 760px);
+  margin: auto;
+  overflow-wrap: anywhere;
+  text-align: center;
+  font-size: 13px;
+}
+
+.lightboxLink a { color: #ffd1e7; }
+
+.lightboxActions button:focus-visible,
+.iconAction:focus-visible,
+.lightboxLink a:focus-visible {
+  outline: 3px solid #fff;
+  outline-offset: 3px;
+}
+
+.srStatus {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+@media (forced-colors: active) {
+  .lightbox { background: Canvas; color: CanvasText; }
+  .lightboxActions button,
+  .iconAction { color: ButtonText; background: ButtonFace; border-color: ButtonText; }
+  .lightboxLink a { color: LinkText; }
+}
diff --git a/app/[event]/gallery/photo-actions.test.ts b/app/[event]/gallery/photo-actions.test.ts
new file mode 100644
index 0000000..a6789c8
--- /dev/null
+++ b/app/[event]/gallery/photo-actions.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+import {
+  exactGalleryUrl,
+  savePhoto,
+  sharePhoto,
+  type PhotoActionDeps,
+} from "./photo-actions";
+
+const photo = {
+  key: "events/show/1700000000000 guest/photo.jpg",
+  url: "https://photos.example/events/show/photo.jpg",
+  uploadedAt: "2026-07-24T12:00:00.000Z",
+};
+
+function deps(overrides: Partial<PhotoActionDeps> = {}): PhotoActionDeps & {
+  actions: string[];
+} {
+  const actions: string[] = [];
+  return {
+    actions,
+    fetchBlob: async (url) => {
+      actions.push(`fetch:${url}`);
+      return new Blob(["photo"], { type: "image/jpeg" });
+    },
+    canShare: (data) => {
+      actions.push(data.files ? "can-share:file" : "can-share:link");
+      return Boolean(data.files);
+    },
+    share: async (data) => {
+      actions.push(data.files ? "share:file" : `share:${data.url}`);
+    },
+    createObjectURL: () => {
+      actions.push("object:create");
+      return "blob:photo";
+    },
+    revokeObjectURL: (url) => actions.push(`object:revoke:${url}`),
+    download: (url, filename) => actions.push(`download:${url}:${filename}`),
+    ...overrides,
+  };
+}
+
+describe("exact Gallery actions", () => {
+  test("encodes the complete key as one photo query value", () => {
+    const url = exactGalleryUrl("https://booth.example/current", "show", photo.key);
+    expect(url).toBe(
+      "https://booth.example/show/gallery?photo=events%2Fshow%2F1700000000000+guest%2Fphoto.jpg"
+    );
+    expect(new URL(url).searchParams.getAll("photo")).toEqual([photo.key]);
+  });
+
+  test("prefers exact prefetched bytes for native file share", async () => {
+    const runtime = deps();
+    const blob = new Blob(["exact"], { type: "image/jpeg" });
+    const result = await savePhoto({
+      photo,
+      prefetched: { key: photo.key, url: photo.url, blob },
+      exactUrl: exactGalleryUrl("https://booth.example", "show", photo.key),
+      deps: runtime,
+    });
+
+    expect(result).toEqual({ kind: "shared" });
+    expect(runtime.actions).toEqual(["can-share:file", "share:file"]);
+  });
+
+  test("never reuses stale prefetched bytes for a newer exact photo", async () => {
+    const runtime = deps();
+    await savePhoto({
+      photo,
+      prefetched: {
+        key: "events/show/old.jpg",
+        url: photo.url,
+        blob: new Blob(["old"], { type: "image/jpeg" }),
+      },
+      exactUrl: exactGalleryUrl("https://booth.example", "show", photo.key),
+      deps: runtime,
+    });
+
+    expect(runtime.actions[0]).toBe(`fetch:${photo.url}`);
+  });
+
+  test("shares the same visible exact URL when file sharing is unavailable", async () => {
+    const runtime = deps({
+      canShare: () => false,
+    });
+    const exactUrl = exactGalleryUrl("https://booth.example", "show", photo.key);
+    const result = await sharePhoto({
+      photo,
+      prefetched: null,
+      exactUrl,
+      deps: runtime,
+    });
+
+    expect(result).toEqual({ kind: "shared" });
+    expect(runtime.actions).toContain(`share:${exactUrl}`);
+  });
+
+  test("always revokes object URL download fallbacks", async () => {
+    const runtime = deps({
+      canShare: () => false,
+      share: async () => {
+        throw new Error("link share unavailable");
+      },
+    });
+    const result = await savePhoto({
+      photo,
+      prefetched: null,
+      exactUrl: exactGalleryUrl("https://booth.example", "show", photo.key),
+      deps: runtime,
+    });
+
+    expect(result).toEqual({ kind: "downloaded" });
+    expect(runtime.actions).toContain("object:create");
+    expect(runtime.actions).toContain("object:revoke:blob:photo");
+  });
+
+  test("treats native share cancellation as a non-error outcome", async () => {
+    const runtime = deps({
+      share: async () => {
+        throw new DOMException("cancelled", "AbortError");
+      },
+    });
+    const result = await savePhoto({
+      photo,
+      prefetched: { key: photo.key, url: photo.url, blob: new Blob(["photo"]) },
+      exactUrl: exactGalleryUrl("https://booth.example", "show", photo.key),
+      deps: runtime,
+    });
+
+    expect(result).toEqual({ kind: "cancelled" });
+  });
+});
diff --git a/app/[event]/gallery/photo-actions.ts b/app/[event]/gallery/photo-actions.ts
new file mode 100644
index 0000000..dce54f5
--- /dev/null
+++ b/app/[event]/gallery/photo-actions.ts
@@ -0,0 +1,162 @@
+import type { FeedPhoto } from "@/app/photo-feed/types";
+
+export type PrefetchedPhoto = {
+  key: string;
+  url: string;
+  blob: Blob;
+};
+
+export type PhotoActionResult =
+  | { kind: "shared" }
+  | { kind: "downloaded" }
+  | { kind: "cancelled" }
+  | { kind: "error"; error: string };
+
+export type PhotoActionDeps = {
+  fetchBlob(url: string): Promise<Blob>;
+  canShare(data: ShareData): boolean;
+  share(data: ShareData): Promise<void>;
+  createObjectURL(blob: Blob): string;
+  revokeObjectURL(url: string): void;
+  download(objectUrl: string, filename: string): void;
+};
+
+export type PhotoActionInput = {
+  photo: FeedPhoto;
+  prefetched: PrefetchedPhoto | null;
+  exactUrl: string;
+  deps: PhotoActionDeps;
+};
+
+export function exactGalleryUrl(
+  origin: string,
+  event: string,
+  completeKey: string,
+): string {
+  const url = new URL(`/${encodeURIComponent(event)}/gallery`, origin);
+  url.searchParams.set("photo", completeKey);
+  return url.toString();
+}
+
+export function browserPhotoActionDeps(): PhotoActionDeps {
+  return {
+    async fetchBlob(url) {
+      const response = await fetch(url, { cache: "no-store" });
+      if (!response.ok) throw new Error(`Photo returned ${response.status}`);
+      return response.blob();
+    },
+    canShare: (data) =>
+      typeof navigator.share === "function"
+      && typeof navigator.canShare === "function"
+      && navigator.canShare(data),
+    share: (data) => navigator.share(data),
+    createObjectURL: (blob) => URL.createObjectURL(blob),
+    revokeObjectURL: (url) => URL.revokeObjectURL(url),
+    download(objectUrl, filename) {
+      const link = document.createElement("a");
+      link.href = objectUrl;
+      link.download = filename;
+      link.rel = "noopener";
+      document.body.append(link);
+      link.click();
+      link.remove();
+    },
+  };
+}
+
+function photoFilename(photo: FeedPhoto): string {
+  const name = photo.key.slice(photo.key.lastIndexOf("/") + 1).trim();
+  return name || "event-photo.jpg";
+}
+
+function isCancellation(error: unknown): boolean {
+  return error instanceof DOMException
+    && (error.name === "AbortError" || error.name === "NotAllowedError");
+}
+
+function exactPrefetch(input: PhotoActionInput): Blob | null {
+  return input.prefetched?.key === input.photo.key
+    && input.prefetched.url === input.photo.url
+    ? input.prefetched.blob
+    : null;
+}
+
+async function blobFor(input: PhotoActionInput): Promise<Blob> {
+  return exactPrefetch(input) ?? input.deps.fetchBlob(input.photo.url);
+}
+
+async function downloadBlob(input: PhotoActionInput, blob: Blob): Promise<PhotoActionResult> {
+  let objectUrl: string | null = null;
+  try {
+    objectUrl = input.deps.createObjectURL(blob);
+    input.deps.download(objectUrl, photoFilename(input.photo));
+    return { kind: "downloaded" };
+  } catch (error) {
+    return {
+      kind: "error",
+      error: error instanceof Error ? error.message : "Photo action failed",
+    };
+  } finally {
+    if (objectUrl !== null) input.deps.revokeObjectURL(objectUrl);
+  }
+}
+
+async function tryFileShare(
+  input: PhotoActionInput,
+  blob: Blob,
+): Promise<PhotoActionResult | null> {
+  const file = new File([blob], photoFilename(input.photo), {
+    type: blob.type || "image/jpeg",
+  });
+  const data: ShareData = { files: [file], title: "Event photo", url: input.exactUrl };
+  if (!input.deps.canShare(data)) return null;
+  try {
+    await input.deps.share(data);
+    return { kind: "shared" };
+  } catch (error) {
+    if (isCancellation(error)) return { kind: "cancelled" };
+    return null;
+  }
+}
+
+export async function savePhoto(input: PhotoActionInput): Promise<PhotoActionResult> {
+  try {
+    const blob = await blobFor(input);
+    const shared = await tryFileShare(input, blob);
+    return shared ?? downloadBlob(input, blob);
+  } catch (error) {
+    if (isCancellation(error)) return { kind: "cancelled" };
+    return {
+      kind: "error",
+      error: error instanceof Error ? error.message : "Photo action failed",
+    };
+  }
+}
+
+export async function sharePhoto(input: PhotoActionInput): Promise<PhotoActionResult> {
+  const prefetched = exactPrefetch(input);
+  if (prefetched) {
+    const shared = await tryFileShare(input, prefetched);
+    if (shared) return shared;
+  }
+
+  try {
+    await input.deps.share({
+      title: "Event photo",
+      text: "Event photo",
+      url: input.exactUrl,
+    });
+    return { kind: "shared" };
+  } catch (error) {
+    if (isCancellation(error)) return { kind: "cancelled" };
+  }
+
+  try {
+    return downloadBlob(input, await blobFor(input));
+  } catch (error) {
+    return {
+      kind: "error",
+      error: error instanceof Error ? error.message : "Photo action failed",
+    };
+  }
+}
diff --git a/app/[event]/gallery/photo-lightbox.test.tsx b/app/[event]/gallery/photo-lightbox.test.tsx
new file mode 100644
index 0000000..77da647
--- /dev/null
+++ b/app/[event]/gallery/photo-lightbox.test.tsx
@@ -0,0 +1,66 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { PhotoLightbox, type PhotoLightboxLabels } from "./photo-lightbox";
+
+const photo = {
+  key: "events/show/1700000000000-photo.jpg",
+  url: "https://photos.example/show/photo.jpg",
+  uploadedAt: "2026-07-24T12:00:00.000Z",
+};
+
+const labels: PhotoLightboxLabels = {
+  title: "Photo viewer",
+  photoAlt: "Event photo",
+  save: "Save",
+  share: "Share",
+  close: "Close",
+  previous: "Previous",
+  next: "Next",
+  working: "Working…",
+  actionError: "Action failed",
+};
+
+test("renders a labelled exact-photo modal with semantic controls and status regions", () => {
+  const exactUrl =
+    "https://booth.example/show/gallery?photo=events%2Fshow%2F1700000000000-photo.jpg";
+  const html = renderToStaticMarkup(
+    <PhotoLightbox
+      event="show"
+      photo={photo}
+      origin="https://booth.example"
+      labels={labels}
+      onClose={() => {}}
+    />
+  );
+
+  expect(html).toContain('role="dialog"');
+  expect(html).toContain('aria-modal="true"');
+  const labelledBy = html.match(/aria-labelledby="([^"]+)"/)?.[1];
+  expect(labelledBy).toStartWith("photo-lightbox-title-");
+  expect(html).toContain(`id="${labelledBy}"`);
+  expect(html).toContain(`<img src="${photo.url}" alt="Event photo"`);
+  expect(html).toContain(">Save</button>");
+  expect(html).toContain(">Share</button>");
+  expect(html).toContain('aria-label="Close"');
+  expect(html).toContain('role="status"');
+  expect(html).toContain('role="alert"');
+  expect(html).toContain(`<a href="${exactUrl}"`);
+  expect(html).toContain("<bdi>");
+});
+
+test("renders optional previous and next actions without owning navigation state", () => {
+  const html = renderToStaticMarkup(
+    <PhotoLightbox
+      event="show"
+      photo={photo}
+      origin="https://booth.example"
+      labels={labels}
+      onClose={() => {}}
+      onPrevious={() => {}}
+      onNext={() => {}}
+    />
+  );
+
+  expect(html).toContain('aria-label="Previous"');
+  expect(html).toContain('aria-label="Next"');
+});
diff --git a/app/[event]/gallery/photo-lightbox.tsx b/app/[event]/gallery/photo-lightbox.tsx
new file mode 100644
index 0000000..2d2f554
--- /dev/null
+++ b/app/[event]/gallery/photo-lightbox.tsx
@@ -0,0 +1,188 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { FeedPhoto } from "@/app/photo-feed/types";
+import {
+  browserPhotoActionDeps,
+  exactGalleryUrl,
+  savePhoto,
+  sharePhoto,
+  type PhotoActionDeps,
+  type PrefetchedPhoto,
+} from "./photo-actions";
+import styles from "./gallery.module.css";
+
+export type PhotoLightboxLabels = {
+  title: string;
+  photoAlt: string;
+  save: string;
+  share: string;
+  close: string;
+  previous: string;
+  next: string;
+  working: string;
+  actionError: string;
+};
+
+type PhotoLightboxProps = {
+  event: string;
+  photo: FeedPhoto;
+  origin: string;
+  labels: PhotoLightboxLabels;
+  onClose(): void;
+  onPrevious?: (() => void) | undefined;
+  onNext?: (() => void) | undefined;
+  actionDeps?: PhotoActionDeps | undefined;
+};
+
+function focusableElements(container: HTMLElement): HTMLElement[] {
+  return Array.from(
+    container.querySelectorAll<HTMLElement>(
+      'button:not([disabled]),a[href],[tabindex]:not([tabindex="-1"])'
+    )
+  ).filter((element) => !element.hasAttribute("aria-hidden"));
+}
+
+export function PhotoLightbox({
+  event,
+  photo,
+  origin,
+  labels,
+  onClose,
+  onPrevious,
+  onNext,
+  actionDeps,
+}: PhotoLightboxProps) {
+  const generatedTitleId = useId();
+  const titleId = generatedTitleId
+    ? `photo-lightbox-title-${generatedTitleId.replace(/:/g, "")}`
+    : "photo-lightbox-title";
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const restoreFocusRef = useRef<HTMLElement | null>(null);
+  const generationRef = useRef(0);
+  const [prefetched, setPrefetched] = useState<PrefetchedPhoto | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const exactUrl = useMemo(
+    () => exactGalleryUrl(origin, event, photo.key),
+    [event, origin, photo.key]
+  );
+  const deps = useMemo(
+    () => actionDeps ?? browserPhotoActionDeps(),
+    [actionDeps]
+  );
+
+  useEffect(() => {
+    restoreFocusRef.current = document.activeElement instanceof HTMLElement
+      ? document.activeElement
+      : null;
+    closeRef.current?.focus();
+    return () => restoreFocusRef.current?.focus();
+  }, []);
+
+  useEffect(() => {
+    const generation = ++generationRef.current;
+    setPrefetched(null);
+    setError("");
+    let active = true;
+    void deps.fetchBlob(photo.url).then((blob) => {
+      if (active && generationRef.current === generation) {
+        setPrefetched({ key: photo.key, url: photo.url, blob });
+      }
+    }).catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, [deps, photo.key, photo.url]);
+
+  const act = useCallback(async (kind: "save" | "share") => {
+    const generation = generationRef.current;
+    setBusy(true);
+    setError("");
+    const input = { photo, prefetched, exactUrl, deps };
+    const result = kind === "save" ? await savePhoto(input) : await sharePhoto(input);
+    if (generationRef.current !== generation) return;
+    setBusy(false);
+    if (result.kind === "error") setError(labels.actionError);
+  }, [deps, exactUrl, labels.actionError, photo, prefetched]);
+
+  const onKeyDown = useCallback((keyboardEvent: React.KeyboardEvent) => {
+    if (keyboardEvent.key === "Escape") {
+      keyboardEvent.preventDefault();
+      onClose();
+      return;
+    }
+    if (keyboardEvent.key !== "Tab" || !dialogRef.current) return;
+    const focusable = focusableElements(dialogRef.current);
+    if (focusable.length === 0) return;
+    const first = focusable[0]!;
+    const last = focusable.at(-1)!;
+    if (keyboardEvent.shiftKey && document.activeElement === first) {
+      keyboardEvent.preventDefault();
+      last.focus();
+    } else if (!keyboardEvent.shiftKey && document.activeElement === last) {
+      keyboardEvent.preventDefault();
+      first.focus();
+    }
+  }, [onClose]);
+
+  return (
+    <div
+      ref={dialogRef}
+      className={styles.lightbox}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={titleId}
+      onKeyDown={onKeyDown}
+    >
+      <div className={styles.lightboxHeader}>
+        <h2 id={titleId}>{labels.title}</h2>
+        <button
+          ref={closeRef}
+          className={styles.iconAction}
+          type="button"
+          aria-label={labels.close}
+          onClick={onClose}
+        >
+          ×
+        </button>
+      </div>
+      <img className={styles.lightboxPhoto} src={photo.url} alt={labels.photoAlt} />
+      <div className={styles.lightboxActions}>
+        {onPrevious ? (
+          <button type="button" aria-label={labels.previous} onClick={onPrevious}>
+            ←
+          </button>
+        ) : null}
+        <button type="button" disabled={busy} onClick={() => void act("save")}>
+          {labels.save}
+        </button>
+        <button type="button" disabled={busy} onClick={() => void act("share")}>
+          {labels.share}
+        </button>
+        {onNext ? (
+          <button type="button" aria-label={labels.next} onClick={onNext}>
+            →
+          </button>
+        ) : null}
+      </div>
+      <p className={styles.lightboxLink}>
+        <a href={exactUrl}><bdi>{exactUrl}</bdi></a>
+      </p>
+      <p className={styles.srStatus} role="status" aria-live="polite">
+        {busy ? labels.working : ""}
+      </p>
+      <p className={styles.srStatus} role="alert">
+        {error}
+      </p>
+    </div>
+  );
+}
diff --git a/app/[event]/live/live.module.css b/app/[event]/live/live.module.css
index 01bdac2..d650a91 100644
--- a/app/[event]/live/live.module.css
+++ b/app/[event]/live/live.module.css
@@ -70,16 +70,26 @@
   padding-bottom: 12px;
 }
 
+.tileButton {
+  display: block;
+  width: 100%;
+  min-height: 44px;
+  padding: 0;
+  border: 0;
+  border-radius: 10px;
+  background: #111;
+  cursor: pointer;
+}
+
 .tile {
   display: block;
   width: 100%;
   height: auto; /* full image, not cropped */
   border-radius: 10px;
-  cursor: pointer;
   background: #111;
   animation: pop 400ms ease-out;
 }
-.tile:focus-visible { outline: 4px solid #ff2d8b; outline-offset: -4px; }
+.tileButton:focus-visible { outline: 4px solid #ff2d8b; outline-offset: 3px; }
 
 @keyframes pop {
   from { opacity: 0; transform: scale(0.9); }
@@ -157,3 +167,12 @@
   .tile, .pulse { animation: none; }
   .colInner { will-change: auto; }
 }
+
+@media (forced-colors: active) {
+  .tileButton:focus-visible,
+  .feedStatus button:focus-visible,
+  .feedToast button:focus-visible {
+    outline: 3px solid Highlight;
+    outline-offset: 3px;
+  }
+}
diff --git a/app/[event]/live/marquee.test.ts b/app/[event]/live/marquee.test.ts
new file mode 100644
index 0000000..5e622a7
--- /dev/null
+++ b/app/[event]/live/marquee.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DRAG_ACTIVATION_THRESHOLD_PX,
+  MANUAL_PAUSE_MS,
+  marqueeTileKey,
+  shouldAnimateMarquee,
+  suppressActivationAfterDrag,
+} from "./marquee";
+
+describe("projector marquee invariants", () => {
+  test("keeps newest-first tile identity stable across prepends", () => {
+    const before = ["event/200-b.jpg", "event/100-a.jpg"].map((key) =>
+      marqueeTileKey(key, 0)
+    );
+    const after = ["event/300-c.jpg", "event/200-b.jpg", "event/100-a.jpg"].map(
+      (key) => marqueeTileKey(key, 0)
+    );
+
+    expect(after.slice(1)).toEqual(before);
+  });
+
+  test("suppresses activation only after more than ten pixels of travel", () => {
+    expect(DRAG_ACTIVATION_THRESHOLD_PX).toBe(10);
+    expect(suppressActivationAfterDrag(10)).toBe(false);
+    expect(suppressActivationAfterDrag(10.01)).toBe(true);
+  });
+
+  test("resumes automatic movement four seconds after manual interaction", () => {
+    expect(MANUAL_PAUSE_MS).toBe(4_000);
+  });
+
+  test("reduced motion keeps photos rendered without automatic marquee motion", () => {
+    expect(shouldAnimateMarquee({
+      reducedMotion: true,
+      viewportHeight: 700,
+      tallestColumnHeight: 1_400,
+    })).toBe(false);
+    expect(shouldAnimateMarquee({
+      reducedMotion: false,
+      viewportHeight: 700,
+      tallestColumnHeight: 1_400,
+    })).toBe(true);
+  });
+});
diff --git a/app/[event]/live/marquee.ts b/app/[event]/live/marquee.ts
new file mode 100644
index 0000000..15524ea
--- /dev/null
+++ b/app/[event]/live/marquee.ts
@@ -0,0 +1,20 @@
+export const DRAG_ACTIVATION_THRESHOLD_PX = 10;
+export const MANUAL_PAUSE_MS = 4_000;
+
+export function marqueeTileKey(completeKey: string, occurrence: number): string {
+  return `${completeKey}#${occurrence}`;
+}
+
+export function suppressActivationAfterDrag(distance: number): boolean {
+  return distance > DRAG_ACTIVATION_THRESHOLD_PX;
+}
+
+export function shouldAnimateMarquee(input: {
+  reducedMotion: boolean;
+  viewportHeight: number;
+  tallestColumnHeight: number;
+}): boolean {
+  return !input.reducedMotion
+    && input.viewportHeight > 0
+    && input.tallestColumnHeight > input.viewportHeight;
+}
diff --git a/app/[event]/live/page.tsx b/app/[event]/live/page.tsx
index f3418c5..6aacbec 100644
--- a/app/[event]/live/page.tsx
+++ b/app/[event]/live/page.tsx
@@ -1,25 +1,37 @@
 "use client";
 
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { useParams } from "next/navigation";
 import QRCode from "qrcode";
+import { message, SUPPORTED_LOCALES, type SupportedLocale } from "@/app/i18n/catalog";
+import {
+  applyDocumentLocale,
+  deviceLocaleStorageKey,
+  resolveDeviceLocale,
+} from "@/app/i18n/locale";
+import { PROJECTOR_FEED_PROFILE } from "@/app/photo-feed/controller";
+import type { FeedPhoto } from "@/app/photo-feed/types";
+import { usePhotoFeed } from "@/app/photo-feed/use-photo-feed";
+import { PhotoLightbox } from "../gallery/photo-lightbox";
 import styles from "./live.module.css";
+import {
+  MANUAL_PAUSE_MS,
+  marqueeTileKey,
+  shouldAnimateMarquee,
+  suppressActivationAfterDrag,
+} from "./marquee";
 import { wrap } from "./wrap";
 
-type Photo = { key: string; url: string; uploadedAt: string };
-
 const SPEED = 40; // px/sec
 const GAP = 12; // must match the CSS gap/padding-bottom on .copy
 const PAD = 14;
 
 export default function Live() {
   const { event } = useParams<{ event: string }>();
-  const [photos, setPhotos] = useState<Photo[]>([]);
-  const [feedState, setFeedState] = useState<"loading" | "ready" | "error">("loading");
-  const [feedError, setFeedError] = useState("");
-  const [full, setFull] = useState<string | null>(null);
-  const [saving, setSaving] = useState(false);
-  const [saveMsg, setSaveMsg] = useState("");
+  const feed = usePhotoFeed(event, PROJECTOR_FEED_PROFILE);
+  const photos = feed.photos;
+  const [full, setFull] = useState<FeedPhoto | null>(null);
+  const [locale, setLocale] = useState<SupportedLocale>("en");
   // measured height/width per photo url, so columns can be balanced by real height
   const [ratios, setRatios] = useState<Record<string, number>>({});
   const [vw, setVw] = useState(0);
@@ -30,10 +42,30 @@ export default function Live() {
   const [reducedMotion, setReducedMotion] = useState(false);
 
   useEffect(() => {
-    QRCode.toDataURL(window.location.href, { width: 300, margin: 1 })
+    const galleryUrl = new URL(`/${encodeURIComponent(event)}/gallery`, window.location.origin);
+    QRCode.toDataURL(galleryUrl.toString(), { width: 300, margin: 1 })
       .then(setQr)
       .catch(() => {});
-  }, []);
+  }, [event]);
+
+  useEffect(() => {
+    let storedLocale: string | null = null;
+    try {
+      storedLocale = window.localStorage.getItem(deviceLocaleStorageKey(event));
+    } catch {
+      // Storage is an enhancement; browser language still provides a locale.
+    }
+    setLocale(resolveDeviceLocale({
+      event,
+      configured: SUPPORTED_LOCALES,
+      storedLocale,
+      navigatorLanguages: navigator.languages,
+    }));
+  }, [event]);
+
+  useEffect(() => {
+    applyDocumentLocale(document.documentElement, locale);
+  }, [locale]);
 
   useEffect(() => {
     const query = window.matchMedia("(prefers-reduced-motion: reduce)");
@@ -51,51 +83,10 @@ export default function Live() {
   const fullRef = useRef(false);
   // cumulative pointer travel of the last drag; >10px suppresses the tile click
   const dragDistRef = useRef(0);
-  const cursorRef = useRef<string | null>(null);
   useEffect(() => {
     fullRef.current = !!full;
   }, [full]);
 
-  const pollPhotos = useCallback(async (signal?: AbortSignal) => {
-    try {
-      const after = cursorRef.current;
-      const query = new URLSearchParams({ event });
-      if (after) query.set("after", after);
-      const res = await fetch(`/api/photos?${query}`, { cache: "no-store", signal });
-      if (!res.ok) throw new Error(`Gallery feed returned ${res.status}`);
-      const data = await res.json();
-      if (!Array.isArray(data.photos)) throw new Error("Gallery feed had an unexpected shape");
-      const incoming = data.photos as Photo[];
-      setPhotos((current) => {
-        if (!after) return incoming;
-        const seen = new Set(incoming.map((photo) => photo.key || photo.url));
-        return [...incoming, ...current.filter((photo) => !seen.has(photo.key || photo.url))];
-      });
-      if (typeof data.cursor === "string" && data.cursor) cursorRef.current = data.cursor;
-      setFeedState("ready");
-      setFeedError("");
-    } catch (cause) {
-      if (cause instanceof DOMException && cause.name === "AbortError") return;
-      setFeedState("error");
-      setFeedError(cause instanceof Error ? cause.message : "The gallery feed is unavailable");
-    }
-  }, [event]);
-
-  useEffect(() => {
-    let alive = true;
-    const controller = new AbortController();
-    cursorRef.current = null;
-    setPhotos([]);
-    setFeedState("loading");
-    void pollPhotos(controller.signal);
-    const id = setInterval(() => { if (alive) void pollPhotos(controller.signal); }, 3000);
-    return () => {
-      alive = false;
-      controller.abort();
-      clearInterval(id);
-    };
-  }, [event, pollPhotos]);
-
   useEffect(() => {
     const calc = () => {
       setVw(window.innerWidth);
@@ -112,14 +103,18 @@ export default function Live() {
   // Balanced masonry: drop each photo into the shortest column so far (by
   // measured aspect ratio, since all columns share one width), so columns
   // end at nearly the same height.
-  const columns: Photo[][] = Array.from({ length: cols }, () => []);
+  const columns: FeedPhoto[][] = Array.from({ length: cols }, () => []);
   const heights = new Array<number>(cols).fill(0); // px incl. trailing gap
   for (const p of photos) {
     const i = heights.indexOf(Math.min(...heights));
     columns[i].push(p);
     heights[i] += (ratios[p.url] ?? 1) * colW + GAP; // assume square until measured
   }
-  const animate = !reducedMotion && vh > 0 && Math.max(0, ...heights) > vh;
+  const animate = shouldAnimateMarquee({
+    reducedMotion,
+    viewportHeight: vh,
+    tallestColumnHeight: Math.max(0, ...heights),
+  });
 
   // Measure each column's loop period (one copy's height, incl. its trailing
   // padding) after every render, so the wrap always lands on identical pixels.
@@ -150,7 +145,7 @@ export default function Live() {
     let dragY: number | null = null; // pointer y while dragging, else null
     let lastMoveT = 0;
     const bump = () => {
-      idleUntil = performance.now() + 4000;
+      idleUntil = performance.now() + MANUAL_PAUSE_MS;
     };
 
     const move = (delta: number) => {
@@ -228,69 +223,15 @@ export default function Live() {
     };
   }, [animate]);
 
-  // Pre-fetch the open photo's bytes so save() can call navigator.share()
-  // immediately — Safari drops the transient user activation if share() comes
-  // after a slow awaited fetch, making "Save photo" silently do nothing.
-  const fullBlobRef = useRef<{ url: string; blob: Blob } | null>(null);
-  useEffect(() => {
-    if (!full) return;
-    setSaveMsg("");
-    let alive = true;
-    fetch(full)
-      .then((r) => r.blob())
-      .then((blob) => {
-        if (alive) fullBlobRef.current = { url: full, blob };
-      })
-      .catch(() => {});
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") setFull(null);
-    };
-    window.addEventListener("keydown", onKey);
-    return () => {
-      alive = false;
-      window.removeEventListener("keydown", onKey);
-    };
-  }, [full]);
-
-  // Save to device. On mobile, prefer the native share sheet (Save to Photos
-  // on iOS); fall back to a download link on desktop. Cross-origin-safe: the
-  // bytes are fetched, then shared/linked as a same-origin object.
-  const save = useCallback(async (url: string) => {
-    setSaving(true);
-    setSaveMsg("");
-    try {
-      const blob =
-        fullBlobRef.current?.url === url ? fullBlobRef.current.blob : await (await fetch(url)).blob();
-      const file = new File([blob], `photobooth-${Date.now()}.jpg`, { type: "image/jpeg" });
-      if (typeof navigator.canShare === "function" && navigator.canShare({ files: [file] })) {
-        await navigator.share({ files: [file] });
-      } else {
-        const obj = URL.createObjectURL(blob);
-        const a = document.createElement("a");
-        a.href = obj;
-        a.download = file.name;
-        a.click();
-        URL.revokeObjectURL(obj);
-      }
-    } catch (e) {
-      // cancelling the share sheet is fine; anything else deserves feedback
-      if (!(e instanceof DOMException && e.name === "AbortError")) {
-        setSaveMsg("Couldn't save — try pressing and holding the photo instead");
-      }
-    } finally {
-      setSaving(false);
-    }
-  }, []);
-
   return (
-    <main className={styles.live}>
-      {photos.length === 0 && feedState === "loading" && <div className={styles.feedStatus}><span className={styles.pulse} /> <p>Opening the gallery…</p></div>}
-      {photos.length === 0 && feedState === "ready" && <div className={styles.feedStatus}><strong>Ready for the first photo.</strong><p>New photographs will appear here automatically.</p></div>}
-      {feedState === "error" && <div className={photos.length ? styles.feedToast : styles.feedStatus} role="alert"><strong>Gallery connection lost</strong><p>{feedError}</p><button onClick={() => void pollPhotos()}>Try again now</button></div>}
+    <main className={styles.live} lang={locale} dir={locale === "ar" ? "rtl" : "ltr"}>
+      {photos.length === 0 && feed.status === "loading" && <div className={styles.feedStatus}><span className={styles.pulse} /> <p>{message(locale, "galleryBrowseLoading")}</p></div>}
+      {photos.length === 0 && feed.status === "ready" && <div className={styles.feedStatus}><strong>{message(locale, "galleryBrowseEmpty")}</strong><p>{message(locale, "galleryBrowseEmptyBody")}</p></div>}
+      {feed.status === "error" && <div className={photos.length ? styles.feedToast : styles.feedStatus} role="alert"><strong>{message(locale, "galleryConnectionLost")}</strong><p>{feed.error}</p><button onClick={feed.refresh}>{message(locale, "galleryRetry")}</button></div>}
 
       {qr && (
         // eslint-disable-next-line @next/next/no-img-element
-        <img className={styles.qr} src={qr} alt="Scan to view this live gallery on your phone" />
+        <img className={styles.qr} src={qr} alt={message(locale, "galleryQrAlt")} />
       )}
 
       <div className={styles.grid}>
@@ -298,45 +239,44 @@ export default function Live() {
           // repeat the column's photos until one copy fills the screen, so the
           // two-copy loop never exposes empty space
           const m = animate && heights[i] > 0 ? Math.max(1, Math.ceil(vh / heights[i])) : 1;
-          const unit: Photo[] = [];
+          const unit: FeedPhoto[] = [];
           for (let k = 0; k < m; k++) unit.push(...col);
 
           // key by url + occurrence, not list index: a new photo at the head
           // must not re-key (remount + replay the pop animation on) every
           // tile after it
           const seen = new Map<string, number>();
-          const tileKey = (url: string) => {
-            const n = seen.get(url) ?? 0;
-            seen.set(url, n + 1);
-            return `${url}#${n}`;
+          const tileKey = (key: string) => {
+            const n = seen.get(key) ?? 0;
+            seen.set(key, n + 1);
+            return marqueeTileKey(key, n);
           };
           const copy = (prefix: string) => (
             <div key={prefix} className={styles.copy} aria-hidden={prefix === "b" || undefined}>
               {unit.map((p) => (
-                // eslint-disable-next-line @next/next/no-img-element
-                <img
-                  key={tileKey(p.url)}
-                  src={p.url}
-                  alt=""
-                  loading="lazy"
-                  className={styles.tile}
-                  role="button"
-                  tabIndex={prefix === "b" ? -1 : 0}
+                <button
+                  key={tileKey(p.key)}
+                  type="button"
+                  className={styles.tileButton}
+                  tabIndex={prefix === "b" ? -1 : undefined}
                   onClick={() => {
-                    if (dragDistRef.current > 10) return; // was a drag, not a tap
-                    setFull(p.url);
-                  }}
-                  onKeyDown={(event) => {
-                    if (event.key === "Enter" || event.key === " ") {
-                      event.preventDefault();
-                      setFull(p.url);
-                    }
-                  }}
-                  onLoad={(e) => {
-                    const { naturalWidth: w, naturalHeight: h } = e.currentTarget;
-                    if (w > 0) setRatios((mm) => (mm[p.url] ? mm : { ...mm, [p.url]: h / w }));
+                    if (suppressActivationAfterDrag(dragDistRef.current)) return;
+                    setFull(p);
                   }}
-                />
+                  aria-label={message(locale, "galleryPhotoLabel")}
+                >
+                  {/* eslint-disable-next-line @next/next/no-img-element */}
+                  <img
+                    src={p.url}
+                    alt=""
+                    loading="lazy"
+                    className={styles.tile}
+                    onLoad={(e) => {
+                      const { naturalWidth: w, naturalHeight: h } = e.currentTarget;
+                      if (w > 0) setRatios((mm) => (mm[p.url] ? mm : { ...mm, [p.url]: h / w }));
+                    }}
+                  />
+                </button>
               ))}
             </div>
           );
@@ -358,23 +298,23 @@ export default function Live() {
       </div>
 
       {full && (
-        <div className={styles.lightbox} role="dialog" aria-modal="true" onClick={() => setFull(null)}>
-          {/* eslint-disable-next-line @next/next/no-img-element */}
-          <img src={full} alt="Event photo" className={styles.fullImg} onClick={(e) => e.stopPropagation()} />
-          <div className={styles.actions} onClick={(e) => e.stopPropagation()}>
-            <button className={styles.save} onClick={() => save(full)} disabled={saving}>
-              {saving ? "Saving…" : "⬇ Save photo"}
-            </button>
-            <button className={styles.close} onClick={() => setFull(null)}>
-              Close
-            </button>
-          </div>
-          {saveMsg && (
-            <p className={styles.saveMsg} onClick={(e) => e.stopPropagation()}>
-              {saveMsg}
-            </p>
-          )}
-        </div>
+        <PhotoLightbox
+          event={event}
+          photo={full}
+          origin={window.location.origin}
+          labels={{
+            title: message(locale, "galleryLightboxTitle"),
+            photoAlt: message(locale, "galleryPhotoAlt"),
+            save: message(locale, "gallerySave"),
+            share: message(locale, "galleryShare"),
+            close: message(locale, "galleryClose"),
+            previous: message(locale, "galleryPrevious"),
+            next: message(locale, "galleryNext"),
+            working: message(locale, "galleryWorking"),
+            actionError: message(locale, "galleryActionError"),
+          }}
+          onClose={() => setFull(null)}
+        />
       )}
     </main>
   );
diff --git a/app/[event]/live/wrap.test.ts b/app/[event]/live/wrap.test.ts
index 95728bb..a58fdc4 100644
--- a/app/[event]/live/wrap.test.ts
+++ b/app/[event]/live/wrap.test.ts
@@ -26,3 +26,8 @@ test("zero or negative period returns 0", () => {
   expect(wrap(123, 0)).toBe(0);
   expect(wrap(123, -5)).toBe(0);
 });
+
+test("each projector column wraps against its own independent period", () => {
+  expect(wrap(450, 400)).toBe(50);
+  expect(wrap(450, 275)).toBe(175);
+});
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
index 228486c..1398222 100644
--- a/app/i18n/catalog.ts
+++ b/app/i18n/catalog.ts
@@ -36,6 +36,23 @@ export const englishMessages = {
   galleryRetry: "Try again",
   gallerySave: "Save or share",
   gallerySaveError: "Couldn’t save this photo. Try again.",
+  galleryBrowseTitle: "Event photos",
+  galleryBrowseLoading: "Opening the gallery…",
+  galleryBrowseEmpty: "Ready for the first photo.",
+  galleryBrowseEmptyBody: "New photographs will appear here automatically.",
+  galleryConnectionLost: "Gallery connection lost",
+  galleryPhotoLabel: "Open event photo",
+  galleryQrAlt: "Scan to browse event photos on your phone",
+  galleryLightboxTitle: "Event photo",
+  galleryPhotoAlt: "Event photo",
+  galleryShare: "Share",
+  galleryClose: "Close",
+  galleryPrevious: "Previous photo",
+  galleryNext: "Next photo",
+  galleryWorking: "Working…",
+  galleryActionError: "That action didn’t finish. Try again.",
+  galleryNewPhotos: "{count} new photos",
+  galleryJumpLatest: "Jump to latest",
   nextGuest: "Next guest",
   pausedTitle: "Booth paused",
   countdownShot: "Photo {shot} of {total}",
@@ -106,6 +123,23 @@ export const chineseSingaporeMessages: Record<MessageKey, string> = {
   galleryRetry: "重试",
   gallerySave: "保存或分享",
   gallerySaveError: "无法保存此照片。请重试。",
+  galleryBrowseTitle: "活动照片",
+  galleryBrowseLoading: "正在打开相册…",
+  galleryBrowseEmpty: "等待第一张照片。",
+  galleryBrowseEmptyBody: "新照片会自动显示在这里。",
+  galleryConnectionLost: "相册连接已中断",
+  galleryPhotoLabel: "打开活动照片",
+  galleryQrAlt: "扫描二维码，在手机上浏览活动照片",
+  galleryLightboxTitle: "活动照片",
+  galleryPhotoAlt: "活动照片",
+  galleryShare: "分享",
+  galleryClose: "关闭",
+  galleryPrevious: "上一张照片",
+  galleryNext: "下一张照片",
+  galleryWorking: "正在处理…",
+  galleryActionError: "操作未完成。请重试。",
+  galleryNewPhotos: "{count} 张新照片",
+  galleryJumpLatest: "跳至最新照片",
   nextGuest: "下一位来宾",
   pausedTitle: "拍照亭已暂停",
   countdownShot: "第 {shot} 张，共 {total} 张",
@@ -167,6 +201,23 @@ export const arabicMessages: Record<MessageKey, string> = {
   galleryRetry: "حاول مرة أخرى",
   gallerySave: "احفظ أو شارك",
   gallerySaveError: "تعذر حفظ هذه الصورة. حاول مرة أخرى.",
+  galleryBrowseTitle: "صور الفعالية",
+  galleryBrowseLoading: "جارٍ فتح المعرض…",
+  galleryBrowseEmpty: "بانتظار الصورة الأولى.",
+  galleryBrowseEmptyBody: "ستظهر الصور الجديدة هنا تلقائيًا.",
+  galleryConnectionLost: "انقطع اتصال المعرض",
+  galleryPhotoLabel: "افتح صورة الفعالية",
+  galleryQrAlt: "امسح الرمز لتصفح صور الفعالية على هاتفك",
+  galleryLightboxTitle: "صورة الفعالية",
+  galleryPhotoAlt: "صورة الفعالية",
+  galleryShare: "شارك",
+  galleryClose: "إغلاق",
+  galleryPrevious: "الصورة السابقة",
+  galleryNext: "الصورة التالية",
+  galleryWorking: "جارٍ التنفيذ…",
+  galleryActionError: "لم يكتمل الإجراء. حاول مرة أخرى.",
+  galleryNewPhotos: "{count} صور جديدة",
+  galleryJumpLatest: "انتقل إلى الأحدث",
   nextGuest: "الضيف التالي",
   pausedTitle: "كشك التصوير متوقف مؤقتًا",
   countdownShot: "الصورة {shot} من {total}",

From a25219e0e70a5911af6ab7e292f748ebc4c83dc7 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:49:37 +0800
Subject: [PATCH 089/105] fix: fence shared photo actions

---
 app/[event]/gallery/photo-actions.test.ts | 22 ++++++++++++++++++++++
 app/[event]/gallery/photo-actions.ts      | 21 +++++++++++++++------
 app/[event]/gallery/photo-lightbox.tsx    |  4 +++-
 3 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/app/[event]/gallery/photo-actions.test.ts b/app/[event]/gallery/photo-actions.test.ts
index a6789c8..1b50938 100644
--- a/app/[event]/gallery/photo-actions.test.ts
+++ b/app/[event]/gallery/photo-actions.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   exactGalleryUrl,
+  isCurrentPhotoAction,
   savePhoto,
   sharePhoto,
   type PhotoActionDeps,
@@ -128,4 +129,25 @@ describe("exact Gallery actions", () => {
 
     expect(result).toEqual({ kind: "cancelled" });
   });
+
+  test("fences a completed action after the open photo generation changes", () => {
+    expect(isCurrentPhotoAction(4, 4)).toBe(true);
+    expect(isCurrentPhotoAction(4, 5)).toBe(false);
+  });
+
+  test("falls back safely if native file capability detection throws", async () => {
+    const runtime = deps({
+      canShare: () => {
+        throw new DOMException("unsupported data", "DataError");
+      },
+    });
+    const result = await savePhoto({
+      photo,
+      prefetched: { key: photo.key, url: photo.url, blob: new Blob(["photo"]) },
+      exactUrl: exactGalleryUrl("https://booth.example", "show", photo.key),
+      deps: runtime,
+    });
+
+    expect(result).toEqual({ kind: "downloaded" });
+  });
 });
diff --git a/app/[event]/gallery/photo-actions.ts b/app/[event]/gallery/photo-actions.ts
index dce54f5..677d36d 100644
--- a/app/[event]/gallery/photo-actions.ts
+++ b/app/[event]/gallery/photo-actions.ts
@@ -38,6 +38,13 @@ export function exactGalleryUrl(
   return url.toString();
 }
 
+export function isCurrentPhotoAction(
+  actionGeneration: number,
+  currentGeneration: number,
+): boolean {
+  return actionGeneration === currentGeneration;
+}
+
 export function browserPhotoActionDeps(): PhotoActionDeps {
   return {
     async fetchBlob(url) {
@@ -51,7 +58,9 @@ export function browserPhotoActionDeps(): PhotoActionDeps {
       && navigator.canShare(data),
     share: (data) => navigator.share(data),
     createObjectURL: (blob) => URL.createObjectURL(blob),
-    revokeObjectURL: (url) => URL.revokeObjectURL(url),
+    revokeObjectURL: (url) => {
+      window.setTimeout(() => URL.revokeObjectURL(url), 0);
+    },
     download(objectUrl, filename) {
       const link = document.createElement("a");
       link.href = objectUrl;
@@ -105,12 +114,12 @@ async function tryFileShare(
   input: PhotoActionInput,
   blob: Blob,
 ): Promise<PhotoActionResult | null> {
-  const file = new File([blob], photoFilename(input.photo), {
-    type: blob.type || "image/jpeg",
-  });
-  const data: ShareData = { files: [file], title: "Event photo", url: input.exactUrl };
-  if (!input.deps.canShare(data)) return null;
   try {
+    const file = new File([blob], photoFilename(input.photo), {
+      type: blob.type || "image/jpeg",
+    });
+    const data: ShareData = { files: [file], title: "Event photo", url: input.exactUrl };
+    if (!input.deps.canShare(data)) return null;
     await input.deps.share(data);
     return { kind: "shared" };
   } catch (error) {
diff --git a/app/[event]/gallery/photo-lightbox.tsx b/app/[event]/gallery/photo-lightbox.tsx
index 2d2f554..ef63b92 100644
--- a/app/[event]/gallery/photo-lightbox.tsx
+++ b/app/[event]/gallery/photo-lightbox.tsx
@@ -12,6 +12,7 @@ import type { FeedPhoto } from "@/app/photo-feed/types";
 import {
   browserPhotoActionDeps,
   exactGalleryUrl,
+  isCurrentPhotoAction,
   savePhoto,
   sharePhoto,
   type PhotoActionDeps,
@@ -91,6 +92,7 @@ export function PhotoLightbox({
   useEffect(() => {
     const generation = ++generationRef.current;
     setPrefetched(null);
+    setBusy(false);
     setError("");
     let active = true;
     void deps.fetchBlob(photo.url).then((blob) => {
@@ -109,7 +111,7 @@ export function PhotoLightbox({
     setError("");
     const input = { photo, prefetched, exactUrl, deps };
     const result = kind === "save" ? await savePhoto(input) : await sharePhoto(input);
-    if (generationRef.current !== generation) return;
+    if (!isCurrentPhotoAction(generation, generationRef.current)) return;
     setBusy(false);
     if (result.kind === "error") setError(labels.actionError);
   }, [deps, exactUrl, labels.actionError, photo, prefetched]);

From 7149ce4746340e3e92319be8d1205e9922bdc169 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:49:37 +0800
Subject: [PATCH 090/105] feat: add the phone browse gallery

---
 app/[event]/gallery/browse-gallery.test.tsx | 137 ++++++++
 app/[event]/gallery/gallery.module.css      | 168 ++++++++-
 app/[event]/gallery/handoff-gallery.tsx     | 355 +++++++++++++++++---
 app/[event]/gallery/scroll-anchor.test.ts   |  51 +++
 app/[event]/gallery/scroll-anchor.ts        |  32 ++
 5 files changed, 691 insertions(+), 52 deletions(-)
 create mode 100644 app/[event]/gallery/browse-gallery.test.tsx
 create mode 100644 app/[event]/gallery/scroll-anchor.test.ts
 create mode 100644 app/[event]/gallery/scroll-anchor.ts

diff --git a/app/[event]/gallery/browse-gallery.test.tsx b/app/[event]/gallery/browse-gallery.test.tsx
new file mode 100644
index 0000000..e5c8189
--- /dev/null
+++ b/app/[event]/gallery/browse-gallery.test.tsx
@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  BrowseGalleryView,
+  browseGalleryUrl,
+  correlateSelectedPhoto,
+  mergeBrowsePhotos,
+  openBrowsePhoto,
+  restoreBrowseUrl,
+} from "./handoff-gallery";
+
+const newest = {
+  key: "show/0000000003000-new.jpg",
+  url: "https://photos.example/show/new.jpg",
+  uploadedAt: "2026-07-24T12:03:00.000Z",
+};
+const direct = {
+  key: "show/0000000001000-direct.jpg",
+  url: "https://photos.example/show/direct.jpg",
+  uploadedAt: "2026-07-24T12:01:00.000Z",
+};
+
+function render(input: Partial<Parameters<typeof BrowseGalleryView>[0]> = {}) {
+  return renderToStaticMarkup(
+    <BrowseGalleryView
+      locale="en"
+      photos={[]}
+      feedStatus="loading"
+      feedError={null}
+      directState={null}
+      newPhotoCount={0}
+      onOpen={() => {}}
+      onRetryFeed={() => {}}
+      onRetryDirect={() => {}}
+      onJumpLatest={() => {}}
+      {...input}
+    />
+  );
+}
+
+describe("phone browse Gallery presentation", () => {
+  test("a missing photo query opens the browse feed instead of an invalid-link page", () => {
+    const html = render();
+    expect(html).toContain("Event photos");
+    expect(html).toContain('role="status"');
+    expect(html).not.toContain("This photo link is invalid.");
+  });
+
+  test("renders semantic newest-first exact-key tiles and ready/empty states", () => {
+    const html = render({ photos: [newest, direct], feedStatus: "ready" });
+    expect(html.indexOf(newest.url)).toBeLessThan(html.indexOf(direct.url));
+    expect(html).toContain(`data-photo-key="${newest.key}"`);
+    expect(html.match(/<button/g)?.length).toBeGreaterThanOrEqual(2);
+    expect(render({ feedStatus: "ready" })).toContain("Ready for the first photo.");
+  });
+
+  test("retains browse tiles and manual retry when the feed fails", () => {
+    const html = render({
+      photos: [newest],
+      feedStatus: "error",
+      feedError: "venue network unavailable",
+    });
+    expect(html).toContain(newest.url);
+    expect(html).toContain("venue network unavailable");
+    expect(html).toContain(">Try again</button>");
+  });
+
+  test("shows a retryable direct-link failure without replacing browse", () => {
+    const html = render({
+      photos: [newest],
+      feedStatus: "ready",
+      directState: { kind: "not-found" },
+    });
+    expect(html).toContain(newest.url);
+    expect(html).toContain("This photo is no longer available.");
+    expect(html).toContain(">Try again</button>");
+  });
+
+  test("announces incoming photos and exposes Jump to latest", () => {
+    const html = render({
+      photos: [newest],
+      feedStatus: "ready",
+      newPhotoCount: 3,
+    });
+    expect(html).toContain("3 new photos");
+    expect(html).toContain("Jump to latest");
+  });
+
+  test("uses RTL catalog and semantic photo labels", () => {
+    const html = render({
+      locale: "ar",
+      photos: [newest],
+      feedStatus: "ready",
+    });
+    expect(html).toContain('dir="rtl"');
+    expect(html).toContain('aria-label="افتح صورة الفعالية"');
+  });
+});
+
+describe("browse exact-photo correlation and history", () => {
+  test("deduplicates one direct photo when it arrives in the feed", () => {
+    expect(mergeBrowsePhotos([newest, direct], direct)).toEqual([newest, direct]);
+    expect(correlateSelectedPhoto(direct, [
+      newest,
+      { ...direct, url: "https://photos.example/show/fresh.jpg" },
+    ])?.url).toBe("https://photos.example/show/fresh.jpg");
+  });
+
+  test("writes one exact-photo query without navigation and restores browse URL", () => {
+    const calls: Array<{ kind: string; url: string }> = [];
+    const history = {
+      pushState: (_data: unknown, _unused: string, url?: string | URL | null) => {
+        calls.push({ kind: "push", url: String(url) });
+      },
+      replaceState: (_data: unknown, _unused: string, url?: string | URL | null) => {
+        calls.push({ kind: "replace", url: String(url) });
+      },
+    };
+    const exact = openBrowsePhoto(
+      history,
+      "https://booth.example/current",
+      "show",
+      direct.key
+    );
+    restoreBrowseUrl(history, "https://booth.example/current", "show");
+
+    expect(exact).toBe(
+      "https://booth.example/show/gallery?photo=show%2F0000000001000-direct.jpg"
+    );
+    expect(calls).toEqual([
+      { kind: "push", url: exact },
+      { kind: "replace", url: "https://booth.example/show/gallery" },
+    ]);
+    expect(browseGalleryUrl("https://booth.example/current", "show"))
+      .toBe("https://booth.example/show/gallery");
+  });
+});
diff --git a/app/[event]/gallery/gallery.module.css b/app/[event]/gallery/gallery.module.css
index c260bc6..cacdc4f 100644
--- a/app/[event]/gallery/gallery.module.css
+++ b/app/[event]/gallery/gallery.module.css
@@ -7,6 +7,161 @@
   background: radial-gradient(circle at top, #3b1730, #090509 58%);
 }
 
+.browse {
+  min-height: 100dvh;
+  padding: max(28px, env(safe-area-inset-top)) max(16px, env(safe-area-inset-right)) max(36px, env(safe-area-inset-bottom)) max(16px, env(safe-area-inset-left));
+  color: #f9edf4;
+  background:
+    linear-gradient(rgba(255, 117, 181, .07) 1px, transparent 1px) 0 0 / 100% 88px,
+    #100a0f;
+}
+
+.browseHeader {
+  width: min(100%, 1180px);
+  margin: 0 auto clamp(24px, 6vw, 52px);
+}
+
+.browseEyebrow {
+  margin-bottom: 6px;
+  color: #ff91c2;
+  font-size: 12px;
+  font-weight: 800;
+  letter-spacing: .15em;
+  text-transform: uppercase;
+}
+
+.browseHeader h1 {
+  max-width: 12ch;
+  font-size: clamp(40px, 12vw, 92px);
+  font-weight: 850;
+  letter-spacing: -.055em;
+  line-height: .9;
+}
+
+.browseGrid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  align-items: start;
+  width: min(100%, 1180px);
+  margin: 0 auto;
+  gap: 12px;
+}
+
+.browseTile {
+  min-width: 0;
+  min-height: 44px;
+  padding: 0;
+  overflow: hidden;
+  border: 1px solid rgba(255, 255, 255, .13);
+  border-radius: 14px;
+  background: #21131d;
+  box-shadow: 0 12px 28px rgba(0, 0, 0, .22);
+  cursor: zoom-in;
+  animation: browseAppear 240ms ease-out both;
+}
+
+.browseTile img {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.browseTile:focus-visible,
+.inlineStatus button:focus-visible,
+.inlineError button:focus-visible,
+.newPhotoNotice button:focus-visible {
+  outline: 3px solid #fff;
+  outline-offset: 4px;
+}
+
+.browseEmpty,
+.inlineStatus,
+.inlineError {
+  display: grid;
+  justify-items: start;
+  width: min(100%, 1180px);
+  margin: 0 auto 20px;
+  gap: 10px;
+  padding: 18px;
+  border: 1px solid rgba(255, 255, 255, .16);
+  border-radius: 14px;
+  background: rgba(28, 17, 26, .92);
+}
+
+.browseEmpty {
+  justify-items: center;
+  min-height: 34dvh;
+  align-content: center;
+  text-align: center;
+}
+
+.browseEmpty h2 { font-size: clamp(24px, 6vw, 42px); }
+.browseEmpty p,
+.inlineStatus p,
+.inlineError p { max-width: 48rem; line-height: 1.55; }
+
+.inlineError {
+  border-color: #a75579;
+}
+
+.inlineStatus button,
+.inlineError button,
+.newPhotoNotice button {
+  min-height: 44px;
+  padding: 10px 16px;
+  border: 2px solid currentColor;
+  border-radius: 999px;
+  color: #fff;
+  background: transparent;
+  font: inherit;
+  font-weight: 750;
+  cursor: pointer;
+}
+
+.browsePulse {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  background: #ff75b5;
+  animation: browsePulse 900ms ease-in-out infinite alternate;
+}
+
+.newPhotoNotice {
+  position: sticky;
+  top: max(10px, env(safe-area-inset-top));
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 14px;
+  width: min(100%, 560px);
+  margin: 0 auto 18px;
+  padding: 10px 10px 10px 16px;
+  border: 1px solid rgba(255, 255, 255, .22);
+  border-radius: 999px;
+  color: #fff;
+  background: rgba(54, 18, 40, .94);
+  box-shadow: 0 12px 36px rgba(0, 0, 0, .35);
+  backdrop-filter: blur(14px);
+}
+
+@keyframes browseAppear {
+  from { opacity: 0; transform: translateY(8px); }
+}
+
+@keyframes browsePulse {
+  to { opacity: .3; transform: scale(.7); }
+}
+
+@media (min-width: 680px) {
+  .browse { padding-inline: 24px; }
+  .browseGrid { grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 16px; }
+}
+
+@media (min-width: 1040px) {
+  .browseGrid { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+}
+
 .card {
   display: grid;
   width: min(100%, 680px);
@@ -94,10 +249,21 @@
   .gallery { background: Canvas; color: CanvasText; }
   .status, .photo { border: 1px solid CanvasText; }
   .primaryAction, .secondaryAction { color: ButtonText; background: ButtonFace; border-color: ButtonText; }
+  .browse { color: CanvasText; background: Canvas; }
+  .browseTile,
+  .browseEmpty,
+  .inlineStatus,
+  .inlineError,
+  .newPhotoNotice { color: CanvasText; background: Canvas; border-color: CanvasText; }
+  .inlineStatus button,
+  .inlineError button,
+  .newPhotoNotice button { color: ButtonText; background: ButtonFace; border-color: ButtonText; }
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .photo { animation: none; }
+  .photo,
+  .browseTile,
+  .browsePulse { animation: none; }
 }
 
 .lightbox {
diff --git a/app/[event]/gallery/handoff-gallery.tsx b/app/[event]/gallery/handoff-gallery.tsx
index 686880f..61989d7 100644
--- a/app/[event]/gallery/handoff-gallery.tsx
+++ b/app/[event]/gallery/handoff-gallery.tsx
@@ -1,6 +1,14 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type Ref,
+} from "react";
 import { useParams, useSearchParams } from "next/navigation";
 import {
   localeDirection,
@@ -13,6 +21,12 @@ import {
   deviceLocaleStorageKey,
   resolveDeviceLocale,
 } from "@/app/i18n/locale";
+import { BROWSE_FEED_PROFILE } from "@/app/photo-feed/controller";
+import type { FeedPhoto } from "@/app/photo-feed/types";
+import { usePhotoFeed } from "@/app/photo-feed/use-photo-feed";
+import { exactGalleryUrl } from "./photo-actions";
+import { PhotoLightbox } from "./photo-lightbox";
+import { anchoredScrollTop, chooseScrollAnchor, type ScrollAnchor } from "./scroll-anchor";
 import styles from "./gallery.module.css";
 
 export type DirectPhoto = { key: string; url: string; uploadedAt: string };
@@ -278,88 +292,327 @@ export function HandoffGalleryView({
   );
 }
 
+type BrowseHistory = Pick<History, "pushState" | "replaceState">;
+
+export function browseGalleryUrl(origin: string, event: string): string {
+  return new URL(`/${encodeURIComponent(event)}/gallery`, origin).toString();
+}
+
+export function openBrowsePhoto(
+  history: BrowseHistory,
+  origin: string,
+  event: string,
+  completeKey: string,
+): string {
+  const url = exactGalleryUrl(origin, event, completeKey);
+  history.pushState(null, "", url);
+  return url;
+}
+
+export function restoreBrowseUrl(
+  history: BrowseHistory,
+  origin: string,
+  event: string,
+): string {
+  const url = browseGalleryUrl(origin, event);
+  history.replaceState(null, "", url);
+  return url;
+}
+
+export function mergeBrowsePhotos(
+  feedPhotos: readonly FeedPhoto[],
+  directPhoto: FeedPhoto | null,
+): FeedPhoto[] {
+  void directPhoto;
+  // The server feed is authoritative for newest-first browse ordering. A
+  // direct handoff may be older than the initial feed window, so it stays in
+  // the lightbox until its exact key naturally arrives in the feed.
+  return feedPhotos as FeedPhoto[];
+}
+
+export function correlateSelectedPhoto(
+  selected: FeedPhoto | null,
+  feedPhotos: readonly FeedPhoto[],
+): FeedPhoto | null {
+  if (!selected) return null;
+  return feedPhotos.find((photo) => photo.key === selected.key) ?? selected;
+}
+
+type BrowseGalleryViewProps = {
+  locale: SupportedLocale;
+  photos: readonly FeedPhoto[];
+  feedStatus: "loading" | "ready" | "error";
+  feedError: string | null;
+  directState: HandoffGalleryState | null;
+  newPhotoCount: number;
+  onOpen(photo: FeedPhoto): void;
+  onRetryFeed(): void;
+  onRetryDirect(): void;
+  onJumpLatest(): void;
+  gridRef?: Ref<HTMLDivElement>;
+};
+
+export function BrowseGalleryView({
+  locale,
+  photos,
+  feedStatus,
+  feedError,
+  directState,
+  newPhotoCount,
+  onOpen,
+  onRetryFeed,
+  onRetryDirect,
+  onJumpLatest,
+  gridRef,
+}: BrowseGalleryViewProps) {
+  const direction = localeDirection(locale);
+  const directFailure = directState
+    && directState.kind !== "ready"
+    && directState.kind !== "loading"
+    ? directState
+    : null;
+
+  return (
+    <main className={styles.browse} lang={locale} dir={direction}>
+      <header className={styles.browseHeader}>
+        <p className={styles.browseEyebrow}>{message(locale, "liveGallery")}</p>
+        <h1>{message(locale, "galleryBrowseTitle")}</h1>
+      </header>
+
+      {newPhotoCount > 0 ? (
+        <aside className={styles.newPhotoNotice} aria-live="polite">
+          <strong>{message(locale, "galleryNewPhotos", { count: newPhotoCount })}</strong>
+          <button type="button" onClick={onJumpLatest}>
+            {message(locale, "galleryJumpLatest")}
+          </button>
+        </aside>
+      ) : null}
+
+      {directState?.kind === "loading" ? (
+        <section className={styles.inlineStatus} role="status" aria-live="polite">
+          {message(locale, "galleryLoading")}
+        </section>
+      ) : null}
+      {directFailure ? (
+        <section className={styles.inlineError} role="alert">
+          <p>{stateMessage(locale, directFailure)}</p>
+          <button type="button" onClick={onRetryDirect}>
+            {message(locale, "galleryRetry")}
+          </button>
+        </section>
+      ) : null}
+
+      {photos.length === 0 && feedStatus === "loading" ? (
+        <section className={styles.browseEmpty} role="status" aria-live="polite">
+          <span className={styles.browsePulse} />
+          <p>{message(locale, "galleryBrowseLoading")}</p>
+        </section>
+      ) : null}
+      {photos.length === 0 && feedStatus === "ready" ? (
+        <section className={styles.browseEmpty}>
+          <h2>{message(locale, "galleryBrowseEmpty")}</h2>
+          <p>{message(locale, "galleryBrowseEmptyBody")}</p>
+        </section>
+      ) : null}
+      {feedStatus === "error" ? (
+        <section className={styles.inlineError} role="alert">
+          <strong>{message(locale, "galleryConnectionLost")}</strong>
+          {feedError ? <p>{feedError}</p> : null}
+          <button type="button" onClick={onRetryFeed}>
+            {message(locale, "galleryRetry")}
+          </button>
+        </section>
+      ) : null}
+
+      <div ref={gridRef} className={styles.browseGrid} aria-label={message(locale, "galleryBrowseTitle")}>
+        {photos.map((photo) => (
+          <button
+            key={photo.key}
+            className={styles.browseTile}
+            type="button"
+            data-photo-key={photo.key}
+            aria-label={message(locale, "galleryPhotoLabel")}
+            onClick={() => onOpen(photo)}
+          >
+            <img src={photo.url} alt="" loading="lazy" />
+          </button>
+        ))}
+      </div>
+    </main>
+  );
+}
+
 export default function HandoffGallery() {
   const { event } = useParams<{ event: string }>();
   const params = useSearchParams();
   const photoKey = params ? parseDirectPhotoQuery(params) : null;
-  const [state, setState] = useState<HandoffGalleryState>({ kind: "loading" });
+  const hasPhotoQuery = (params?.getAll("photo").length ?? 0) > 0;
+  const feed = usePhotoFeed(event, BROWSE_FEED_PROFILE);
+  const [directState, setDirectState] = useState<HandoffGalleryState | null>(
+    photoKey ? { kind: "loading" } : hasPhotoQuery ? { kind: "invalid" } : null
+  );
   const [locale, setLocale] = useState<SupportedLocale>("en");
-  const [saveError, setSaveError] = useState(false);
-  const statusRef = useRef<HTMLElement>(null);
-  const photoBlobRef = useRef<{ url: string; blob: Blob } | null>(null);
+  const [origin, setOrigin] = useState("");
+  const [newPhotoCount, setNewPhotoCount] = useState(0);
+  const gridRef = useRef<HTMLDivElement>(null);
+  const anchorRef = useRef<(ScrollAnchor & { scrollTop: number }) | null>(null);
+  const selectedRef = useRef<FeedPhoto | null>(null);
   const controllerRef = useRef<HandoffGalleryController | null>(null);
   if (!controllerRef.current) {
     controllerRef.current = new HandoffGalleryController({
       fetchPhoto: (url, init) => fetch(url, init),
       isOnline: () => navigator.onLine,
-      onState: setState,
+      onState: (state) => {
+        if (state.kind === "ready") selectedRef.current = state.photo;
+        setDirectState(state);
+      },
     });
   }
-  const setStatusElement = useCallback((element: HTMLElement | null) => {
-    statusRef.current = element;
-  }, []);
 
   useEffect(() => {
     setLocale(initialLocale(event));
+    setOrigin(window.location.origin);
   }, [event]);
 
   useEffect(() => {
     applyDocumentLocale(document.documentElement, locale);
   }, [locale]);
 
-  const load = useCallback(async () => {
-    setSaveError(false);
+  const loadDirect = useCallback(async () => {
+    if (!photoKey) return;
     await controllerRef.current!.load(event, photoKey);
   }, [event, photoKey]);
 
   useEffect(() => {
-    void load();
-    return () => controllerRef.current?.cancel();
-  }, [load]);
-
-  useEffect(() => {
-    focusHandoffStatus(statusRef.current, state, saveError);
-  }, [saveError, state.kind]);
-
-  useEffect(() => {
-    photoBlobRef.current = null;
-    if (state.kind !== "ready") return;
-    const photo = state.photo;
-    const controller = new AbortController();
-    let active = true;
-    void prefetchPublicPhoto(
-      photo,
-      (url) => fetch(url, { signal: controller.signal })
-    ).then((blob) => {
-      if (active) photoBlobRef.current = { url: photo.url, blob };
-    }).catch(() => {});
+    if (!photoKey) {
+      controllerRef.current?.cancel();
+      selectedRef.current = null;
+      setDirectState(hasPhotoQuery ? { kind: "invalid" } : null);
+      return;
+    }
+    if (selectedRef.current?.key === photoKey) {
+      setDirectState({ kind: "ready", photo: selectedRef.current });
+      return;
+    }
+    void loadDirect();
     return () => {
-      active = false;
-      controller.abort();
+      controllerRef.current?.cancel();
     };
-  }, [state]);
+  }, [hasPhotoQuery, loadDirect, photoKey]);
 
-  const save = useCallback(async () => {
-    if (state.kind !== "ready") return;
-    setSaveError(false);
-    try {
-      const prefetched = photoBlobRef.current?.url === state.photo.url
-        ? photoBlobRef.current.blob
-        : null;
-      await transferPublicPhoto(state.photo, prefetched, browserTransferDeps());
-    } catch (error) {
-      if (!(error instanceof DOMException && error.name === "AbortError")) setSaveError(true);
+  const captureAnchor = useCallback(() => {
+    if (window.scrollY <= 0 || !gridRef.current) {
+      anchorRef.current = null;
+      return;
+    }
+    const visible = Array.from(
+      gridRef.current.querySelectorAll<HTMLElement>("[data-photo-key]")
+    ).map((element) => {
+      const rect = element.getBoundingClientRect();
+      return {
+        key: element.dataset.photoKey ?? "",
+        top: rect.top,
+        bottom: rect.bottom,
+      };
+    }).filter((item) => item.top < window.innerHeight);
+    const anchor = chooseScrollAnchor(visible);
+    anchorRef.current = anchor ? { ...anchor, scrollTop: window.scrollY } : null;
+  }, []);
+
+  useEffect(() => {
+    window.addEventListener("scroll", captureAnchor, { passive: true });
+    captureAnchor();
+    return () => window.removeEventListener("scroll", captureAnchor);
+  }, [captureAnchor]);
+
+  useLayoutEffect(() => {
+    const prior = anchorRef.current;
+    if (feed.inserted.length > 0 && prior && gridRef.current) {
+      const match = Array.from(
+        gridRef.current.querySelectorAll<HTMLElement>("[data-photo-key]")
+      ).find((element) => element.dataset.photoKey === prior.key);
+      if (match) {
+        window.scrollTo({
+          top: anchoredScrollTop({
+            previousScrollTop: prior.scrollTop,
+            beforeTop: prior.top,
+            afterTop: match.getBoundingClientRect().top,
+          }),
+          behavior: "auto",
+        });
+        setNewPhotoCount((count) => count + feed.inserted.length);
+      }
     }
-  }, [state]);
+    captureAnchor();
+  }, [captureAnchor, feed.inserted, feed.photos]);
+
+  const selected = useMemo(
+    () => correlateSelectedPhoto(
+      directState?.kind === "ready" ? directState.photo : null,
+      feed.photos
+    ),
+    [directState, feed.photos]
+  );
+
+  const photos = useMemo(
+    () => mergeBrowsePhotos(feed.photos, selected),
+    [feed.photos, selected]
+  );
+
+  const openPhoto = useCallback((photo: FeedPhoto) => {
+    selectedRef.current = photo;
+    setDirectState({ kind: "ready", photo });
+    openBrowsePhoto(window.history, window.location.origin, event, photo.key);
+  }, [event]);
+
+  const closePhoto = useCallback(() => {
+    controllerRef.current?.cancel();
+    selectedRef.current = null;
+    setDirectState(null);
+    restoreBrowseUrl(window.history, window.location.origin, event);
+  }, [event]);
+
+  const jumpLatest = useCallback(() => {
+    const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    window.scrollTo({ top: 0, behavior: reduced ? "auto" : "smooth" });
+    setNewPhotoCount(0);
+    anchorRef.current = null;
+  }, []);
 
   return (
-    <HandoffGalleryView
-      state={state}
+    <>
+    <BrowseGalleryView
       locale={locale}
-      onRetry={() => { void load(); }}
-      onSave={() => { void save(); }}
-      saveError={saveError}
-      statusRef={setStatusElement}
+      photos={photos}
+      feedStatus={feed.status}
+      feedError={feed.error}
+      directState={directState}
+      newPhotoCount={newPhotoCount}
+      onOpen={openPhoto}
+      onRetryFeed={feed.refresh}
+      onRetryDirect={() => { void loadDirect(); }}
+      onJumpLatest={jumpLatest}
+      gridRef={gridRef}
     />
+    {selected && origin ? (
+      <PhotoLightbox
+        event={event}
+        photo={selected}
+        origin={origin}
+        labels={{
+          title: message(locale, "galleryLightboxTitle"),
+          photoAlt: message(locale, "galleryPhotoAlt"),
+          save: message(locale, "gallerySave"),
+          share: message(locale, "galleryShare"),
+          close: message(locale, "galleryClose"),
+          previous: message(locale, "galleryPrevious"),
+          next: message(locale, "galleryNext"),
+          working: message(locale, "galleryWorking"),
+          actionError: message(locale, "galleryActionError"),
+        }}
+        onClose={closePhoto}
+      />
+    ) : null}
+    </>
   );
 }
diff --git a/app/[event]/gallery/scroll-anchor.test.ts b/app/[event]/gallery/scroll-anchor.test.ts
new file mode 100644
index 0000000..cd30926
--- /dev/null
+++ b/app/[event]/gallery/scroll-anchor.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { anchoredScrollTop, chooseScrollAnchor } from "./scroll-anchor";
+
+describe("browse Gallery scroll anchoring", () => {
+  test("chooses the first still-visible exact key across mixed-height rows", () => {
+    expect(chooseScrollAnchor([
+      { key: "gone", top: -320, bottom: -1 },
+      { key: "partial", top: -18, bottom: 220 },
+      { key: "next", top: 220, bottom: 640 },
+    ])).toEqual({ key: "partial", top: -18 });
+  });
+
+  test("returns no anchor when no exact-key tile remains visible", () => {
+    expect(chooseScrollAnchor([])).toBeNull();
+    expect(chooseScrollAnchor([
+      { key: "above", top: -200, bottom: 0 },
+      { key: "", top: 0, bottom: 200 },
+    ])).toBeNull();
+  });
+
+  test("preserves the visible position across one or several prepends", () => {
+    expect(anchoredScrollTop({
+      previousScrollTop: 500,
+      beforeTop: 80,
+      afterTop: 260,
+    })).toBe(680);
+    expect(anchoredScrollTop({
+      previousScrollTop: 680,
+      beforeTop: 260,
+      afterTop: 920,
+    })).toBe(1_340);
+  });
+
+  test("does not adjust at the top and clamps negative movement", () => {
+    expect(anchoredScrollTop({
+      previousScrollTop: 0,
+      beforeTop: 0,
+      afterTop: 200,
+    })).toBe(0);
+    expect(anchoredScrollTop({
+      previousScrollTop: -10,
+      beforeTop: 0,
+      afterTop: 200,
+    })).toBe(0);
+    expect(anchoredScrollTop({
+      previousScrollTop: 20,
+      beforeTop: 200,
+      afterTop: 0,
+    })).toBe(0);
+  });
+});
diff --git a/app/[event]/gallery/scroll-anchor.ts b/app/[event]/gallery/scroll-anchor.ts
new file mode 100644
index 0000000..4b5f580
--- /dev/null
+++ b/app/[event]/gallery/scroll-anchor.ts
@@ -0,0 +1,32 @@
+export type ScrollAnchor = { key: string; top: number };
+
+export function chooseScrollAnchor(
+  visible: readonly { key: string; top: number; bottom: number }[],
+): ScrollAnchor | null {
+  const first = visible.find((item) =>
+    item.key.length > 0
+    && Number.isFinite(item.top)
+    && Number.isFinite(item.bottom)
+    && item.bottom > 0
+  );
+  return first ? { key: first.key, top: first.top } : null;
+}
+
+export function anchoredScrollTop(input: {
+  previousScrollTop: number;
+  beforeTop: number;
+  afterTop: number;
+}): number {
+  if (
+    input.previousScrollTop <= 0
+    || !Number.isFinite(input.previousScrollTop)
+    || !Number.isFinite(input.beforeTop)
+    || !Number.isFinite(input.afterTop)
+  ) {
+    return 0;
+  }
+  return Math.max(
+    0,
+    input.previousScrollTop + input.afterTop - input.beforeTop
+  );
+}

From 5e15f9ba3e44fb1a4b41d3f71bf6429fa7a69860 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:52:04 +0800
Subject: [PATCH 091/105] docs: add gallery and rehearsal staging gates

---
 docs/runbooks/deployment.md          | 28 ++++++++++++
 docs/runbooks/pre-event-readiness.md | 65 ++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)

diff --git a/docs/runbooks/deployment.md b/docs/runbooks/deployment.md
index 84ee507..b9ae2d0 100644
--- a/docs/runbooks/deployment.md
+++ b/docs/runbooks/deployment.md
@@ -80,6 +80,34 @@ Only after recording a passing iPad rehearsal should you promote explicitly:
 bun run deploy:production
 ```
 
+### Release 3 staging gallery and moderation gate
+
+Run `bun run test:browser -- tests/gallery-moderation.spec.ts`, then complete
+the Release 3 physical-phone/projector checklist in
+`pre-event-readiness.md`. Confirm the bounded rebuild's checkpoint, completion
+marker, index, and receipts exist only in staging `STATE`. Test exactly one
+designated canary deletion and one derived-cleanup failure; neither permits a
+prefix delete or an ambiguous retry. Verify staging records and photos never
+appear through the production Worker.
+
+### Release 4 staging operations gate
+
+Release 4 follows only the explicit `deploy:staging` then
+`deploy:production` path. Run
+`bun run test:browser -- tests/rehearsal-operations.spec.ts`, then complete the
+real-iPad guided rehearsal before promotion.
+
+- Inspect exact staging records to confirm presets, sessions, and evidence
+  exist only in staging `STATE`.
+- Rehearsal photo bytes are normal exact public photos in staging `PHOTOS`;
+  never place rehearsal state there.
+- Never use the health canary prefix for rehearsal evidence or photos.
+- Never add or run cleanup-all, prefix-delete, or abandoned-session cleanup.
+- Resolve stale or abandoned sessions through their visible complete keys,
+  one at a time.
+- Rollback changes Worker code only. It does not delete presets, sessions,
+  evidence, photos, indexes, or receipts.
+
 ### Release 5 staging export gate
 
 Use a canonical throwaway staging Event that is distinct from every production
diff --git a/docs/runbooks/pre-event-readiness.md b/docs/runbooks/pre-event-readiness.md
index a39071b..ddaa98e 100644
--- a/docs/runbooks/pre-event-readiness.md
+++ b/docs/runbooks/pre-event-readiness.md
@@ -84,6 +84,71 @@ and production must not be promoted until every real-device item passes. Never
 remove test photos by prefix; copy and delete only each complete Event-owned
 image key intended for cleanup.
 
+### Release 3 gallery and moderation
+
+Continue with a throwaway canonical staging Event that is distinct from
+production:
+
+1. Upload enough exact photos to require multiple moderation pages. Interrupt
+   and resume the bounded add-only index rebuild, then confirm its checkpoint,
+   completion marker, index, and receipts exist only in staging `STATE`.
+2. Leave the physical projector running while photos arrive. Verify adaptive
+   polling, independent looping columns, four-second manual-scroll pause,
+   motion quality, visible gaps, and browse-QR readability at venue distance.
+3. On a physical phone, keep an older tile in view while several photos arrive.
+   Confirm the visible exact-key anchor stays put, the new-photo count is
+   correct, and **Jump to latest** returns to the newest-first edge.
+4. Open an exact handoff deep link before the browse feed settles. Exercise
+   native Share/Save, including cancellation, and confirm the shared dialog
+   uses the same complete key and URL.
+5. Filter and page Admin moderation, inspect with previous/next and arrow keys,
+   close with Escape, and verify focus returns to the exact originating tile.
+6. Delete one designated canary using its complete Event-owned key. Confirm
+   adjacent public photos and private records remain byte-identical.
+7. Simulate a derived cleanup failure. The public photo must remain deleted,
+   disappear from moderation, show only a cleanup warning, and never invite a
+   second public DELETE.
+8. Exercise the complete flow keyboard-only and with VoiceOver, Arabic RTL,
+   200% text, Reduce Motion, and high contrast. Obtain native-speaker review
+   for supported non-English catalog changes.
+
+Automated WebKit cannot certify iOS native Share activation or Save to Photos,
+VoiceOver speech timing, Safari process suspension, long-running physical
+projector performance, production-like R2 races, or translation quality.
+Never use prefix cleanup; retain abandoned staging records or remove each
+intended photo individually by complete key.
+
+### Release 4 guided rehearsal
+
+Run the guided rehearsal on the actual target iPad over staging HTTPS:
+
+1. Apply the intended preset to a throwaway canonical staging Event, then
+   separately install and verify that Event's Booth Key.
+2. Open the generated rehearsal link and verify authenticated preflight,
+   camera readiness, and durable IndexedDB before accepting evidence.
+3. Capture and accept one photo with every snapshotted Frame; inspect each
+   physical composition.
+4. Create two genuine network-class upload failures on two distinct captures,
+   reload Safari, and confirm a different boot ID recovers both exact rows.
+5. Reconnect and confirm exact oldest-first drain with no duplicate public
+   photos or acknowledgements.
+6. Observe one acknowledged exact key in the public Photo Feed and fetch its
+   public bytes.
+7. Designate that exact key as the moderation canary, delete it through the
+   existing exact-key endpoint, and verify adjacent photos remain.
+8. Explicitly retain or individually delete every other rehearsal photo.
+   Completion and abandonment must never perform automatic cleanup.
+9. Confirm the Photo Outbox and rehearsal evidence outbox are both empty.
+10. Complete projector, power, charging, and backup-network manual checks.
+11. Change config once and verify the old immutable rehearsal becomes stale.
+    Start a new rehearsal rather than rewriting its snapshot or evidence.
+
+A browser simulator cannot prove real camera composition, Safari
+IndexedDB/suspension behavior, genuine venue-network failure, installed wake
+behavior, projector crop/brightness/motion, charging and power, backup
+network, or VoiceOver. Record the Event, build, devices, exact remaining keys,
+and every result. Production promotion remains blocked until they pass.
+
 Then capture one photo with every enabled Frame and check crop, draw order,
 orientation, color, and final resolution. Confirm each photo appears once in
 the Live Gallery without a full-page refresh, exercise Save/Share on a phone,

From cf64aa768e8568d25edd71f4b3cb646ee57a1adb Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:52:56 +0800
Subject: [PATCH 092/105] fix: validate preset target before state access

---
 app/event-store.test.ts | 16 ++++++++++++++++
 app/event-store.ts      |  3 ++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index a71c203..c39ea75 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -2825,6 +2825,22 @@ describe("EventStore", () => {
         .rejects.toBeInstanceOf(ConfigMutationConflictError);
     });
 
+    test("rejects a non-canonical target Event before reading the global preset", async () => {
+      const state = new PresetAccessStore();
+      const store = new EventStore(
+        new InMemoryObjectStore(),
+        state,
+        "https://photos.example",
+      );
+      await expect(store.applyEventPreset("Launch Event", {
+        presetId: "launch-night",
+        mutationId: "018f0000-0000-4000-8000-000000000205",
+        baseRevisionId: null,
+      })).rejects.toBeInstanceOf(InvalidEventSlugError);
+      expect(state.gets).toBe(0);
+      expect(state.lists).toBe(0);
+    });
+
     test("fails explicitly for corrupt stored presets and never offers deletion", async () => {
       const state = new InMemoryObjectStore({
         [eventPresetIndexKey(
diff --git a/app/event-store.ts b/app/event-store.ts
index ed87133..d7f6ce4 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -827,6 +827,7 @@ export class EventStore {
     event: string,
     input: ConfigPresetApplyInput,
   ): Promise<ConfigMutationResult> {
+    const canonical = canonicalEvent(event);
     if (
       !isPresetId(input.presetId)
       || !isRevisionId(input.mutationId)
@@ -836,7 +837,7 @@ export class EventStore {
     }
     const preset = await this.getEventPreset(input.presetId);
     if (!preset) throw new EventPresetNotFoundError(input.presetId);
-    return this.appendConfigRevision(canonicalEvent(event), {
+    return this.appendConfigRevision(canonical, {
       config: preset.config,
       baseRevisionId: input.baseRevisionId,
       mutationId: input.mutationId,

From fc5fda594e32762afcbf16f2f46ca19a3fe7edca Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:57:34 +0800
Subject: [PATCH 093/105] test: verify public gallery browser flows

---
 app/[event]/gallery/handoff-gallery.tsx |  17 +++
 bun.lock                                |   5 +
 package.json                            |   1 +
 tests/gallery-moderation.spec.ts        | 147 ++++++++++++++++++++++++
 4 files changed, 170 insertions(+)
 create mode 100644 tests/gallery-moderation.spec.ts

diff --git a/app/[event]/gallery/handoff-gallery.tsx b/app/[event]/gallery/handoff-gallery.tsx
index 61989d7..5985186 100644
--- a/app/[event]/gallery/handoff-gallery.tsx
+++ b/app/[event]/gallery/handoff-gallery.tsx
@@ -457,6 +457,8 @@ export default function HandoffGallery() {
   const gridRef = useRef<HTMLDivElement>(null);
   const anchorRef = useRef<(ScrollAnchor & { scrollTop: number }) | null>(null);
   const selectedRef = useRef<FeedPhoto | null>(null);
+  const browseTriggerRef = useRef<HTMLElement | null>(null);
+  const browseTriggerKeyRef = useRef<string | null>(null);
   const controllerRef = useRef<HandoffGalleryController | null>(null);
   if (!controllerRef.current) {
     controllerRef.current = new HandoffGalleryController({
@@ -560,16 +562,31 @@ export default function HandoffGallery() {
   );
 
   const openPhoto = useCallback((photo: FeedPhoto) => {
+    browseTriggerRef.current = document.activeElement instanceof HTMLElement
+      ? document.activeElement
+      : null;
+    browseTriggerKeyRef.current = photo.key;
     selectedRef.current = photo;
     setDirectState({ kind: "ready", photo });
     openBrowsePhoto(window.history, window.location.origin, event, photo.key);
   }, [event]);
 
   const closePhoto = useCallback(() => {
+    const trigger = browseTriggerRef.current;
+    const triggerKey = browseTriggerKeyRef.current;
+    browseTriggerRef.current = null;
+    browseTriggerKeyRef.current = null;
     controllerRef.current?.cancel();
     selectedRef.current = null;
     setDirectState(null);
     restoreBrowseUrl(window.history, window.location.origin, event);
+    window.requestAnimationFrame(() => {
+      const currentTrigger = triggerKey
+        ? Array.from(document.querySelectorAll<HTMLElement>("[data-photo-key]"))
+          .find((element) => element.dataset.photoKey === triggerKey)
+        : null;
+      (currentTrigger ?? (trigger?.isConnected ? trigger : null))?.focus();
+    });
   }, [event]);
 
   const jumpLatest = useCallback(() => {
diff --git a/bun.lock b/bun.lock
index d388e70..98da51e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -12,6 +12,7 @@
         "react-dom": "^19.0.0",
       },
       "devDependencies": {
+        "@axe-core/playwright": "^4.12.1",
         "@cloudflare/workers-types": "^5.20260705.1",
         "@playwright/test": "^1.61.1",
         "@types/bun": "^1.2.19",
@@ -136,6 +137,8 @@
 
     "@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.3.0", "", {}, "sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ=="],
 
+    "@axe-core/playwright": ["@axe-core/playwright@4.12.1", "", { "dependencies": { "axe-core": "~4.12.1" }, "peerDependencies": { "playwright-core": ">= 1.0.0" } }, "sha512-rMd7xriptqKpP+w5265i4Hdkv2X5kbu6uiBi/B2I7uf3hieRBM3qDCfaKPtxfiYb2mKXfF+yLODJwIx+Jv1GDw=="],
+
     "@cloudflare/kv-asset-handler": ["@cloudflare/kv-asset-handler@0.5.0", "", {}, "sha512-jxQYkj8dSIzc0cD6cMMNdOc1UVjqSqu8BZdor5s8cGjW2I8BjODt/kWPVdY+u9zj3ms75Q5qaZgnxUad83+eAg=="],
 
     "@cloudflare/unenv-preset": ["@cloudflare/unenv-preset@2.16.1", "", { "peerDependencies": { "unenv": "2.0.0-rc.24", "workerd": ">1.20260305.0 <2.0.0-0" }, "optionalPeers": ["workerd"] }, "sha512-ECxObrMfyTl5bhQf/lZCXwo5G6xX9IAUo+nDMKK4SZ8m4Jvvxp52vilxyySSWh2YTZz8+HQ07qGH/2rEom1vDw=="],
@@ -436,6 +439,8 @@
 
     "aws4fetch": ["aws4fetch@1.0.20", "", {}, "sha512-/djoAN709iY65ETD6LKCtyyEI04XIBP5xVvfmNxsEP0uJB5tyaGBztSryRr4HqMStr9R06PisQE7m9zDTXKu6g=="],
 
+    "axe-core": ["axe-core@4.12.1", "", {}, "sha512-s7iGf5GaVMxEG0ENN9x+xTr7GFZCb1ZP/1uATUpCEK2X78nDB3RwbtFCo9pGAf9ru+VwoQ464DkaLEeRM08wJA=="],
+
     "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
     "blake3-wasm": ["blake3-wasm@2.1.5", "", {}, "sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g=="],
diff --git a/package.json b/package.json
index 9d14296..8d46bbe 100644
--- a/package.json
+++ b/package.json
@@ -27,6 +27,7 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
     "@cloudflare/workers-types": "^5.20260705.1",
     "@playwright/test": "^1.61.1",
     "@types/bun": "^1.2.19",
diff --git a/tests/gallery-moderation.spec.ts b/tests/gallery-moderation.spec.ts
new file mode 100644
index 0000000..5577838
--- /dev/null
+++ b/tests/gallery-moderation.spec.ts
@@ -0,0 +1,147 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test, type BrowserContext, type Page } from "@playwright/test";
+
+const EVENT = "gallery-browser";
+const PIXEL =
+  "data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=";
+const first = {
+  key: `${EVENT}/1753315200002-first.jpg`,
+  url: PIXEL,
+  uploadedAt: "2026-07-24T00:00:02.000Z",
+};
+const second = {
+  key: `${EVENT}/1753315200001-second.jpg`,
+  url: PIXEL,
+  uploadedAt: "2026-07-24T00:00:01.000Z",
+};
+const third = {
+  key: `${EVENT}/1753315200003-third.jpg`,
+  url: PIXEL,
+  uploadedAt: "2026-07-24T00:00:03.000Z",
+};
+
+async function seriousA11yViolations(page: Page) {
+  return (await new AxeBuilder({ page }).analyze()).violations.filter(
+    ({ impact }) => impact === "serious" || impact === "critical",
+  );
+}
+
+async function installGalleryRoutes(
+  context: BrowserContext,
+  options: { delayedFeed?: boolean } = {},
+) {
+  let active = 0;
+  let maximumActive = 0;
+  let feedRequests = 0;
+  await context.route("**/api/**", async (route) => {
+    const url = new URL(route.request().url());
+    if (url.pathname === "/api/photo") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          ...first,
+          key: url.searchParams.get("key"),
+        }),
+      });
+      return;
+    }
+    if (url.pathname !== "/api/photos") {
+      throw new Error(`Unexpected Gallery API request: ${url.pathname}`);
+    }
+    active += 1;
+    maximumActive = Math.max(maximumActive, active);
+    feedRequests += 1;
+    if (options.delayedFeed) {
+      await new Promise((resolve) => setTimeout(resolve, 750));
+    }
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        photos: feedRequests === 1 ? [first, second] : [],
+        cursor: `cursor-${feedRequests}`,
+      }),
+    });
+    active -= 1;
+  });
+  return {
+    stats: () => ({ active, maximumActive, feedRequests }),
+  };
+}
+
+test("phone browse opens an exact deep link before its slow feed and restores URL/focus", async ({
+  context,
+  page,
+}) => {
+  const routes = await installGalleryRoutes(context, { delayedFeed: true });
+  const deepLink = `/${EVENT}/gallery?photo=${encodeURIComponent(first.key)}`;
+  await page.goto(deepLink);
+
+  const dialog = page.getByRole("dialog", { name: "Event photo" });
+  await expect(dialog).toBeVisible();
+  await expect(dialog.getByRole("button", { name: "Close" })).toBeFocused();
+  await expect(dialog.getByRole("link")).toHaveAttribute(
+    "href",
+    new RegExp(`photo=${encodeURIComponent(first.key)}`),
+  );
+  await page.keyboard.press("Escape");
+  await expect(dialog).toHaveCount(0);
+  await expect(page).toHaveURL(`/${EVENT}/gallery`);
+
+  await expect(page.getByRole("button", { name: "Open event photo" })).toHaveCount(2);
+  const secondTile = page.getByRole("button", { name: "Open event photo" }).nth(1);
+  await secondTile.focus();
+  await secondTile.click();
+  await expect(page).toHaveURL(new RegExp(`photo=${encodeURIComponent(second.key)}`));
+  await page.getByRole("button", { name: "Close" }).click();
+  await expect(secondTile).toBeFocused();
+  expect(routes.stats().maximumActive).toBe(1);
+  expect(await seriousA11yViolations(page)).toEqual([]);
+});
+
+test("projector retains photos across feed errors, retries, and exposes the browse QR", async ({
+  context,
+  page,
+}) => {
+  let active = 0;
+  let maximumActive = 0;
+  let requestCount = 0;
+  await context.route("**/api/photos**", async (route) => {
+    active += 1;
+    maximumActive = Math.max(maximumActive, active);
+    requestCount += 1;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    if (requestCount === 2) {
+      await route.fulfill({
+        status: 503,
+        contentType: "application/json",
+        body: JSON.stringify({ error: "temporary fixture failure" }),
+      });
+    } else {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          photos: requestCount === 1 ? [first, second] : [third],
+          cursor: `cursor-${requestCount}`,
+        }),
+      });
+    }
+    active -= 1;
+  });
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await page.goto(`/${EVENT}/live`);
+
+  await expect(page.getByRole("button", { name: "Open event photo" })).toHaveCount(2);
+  await expect(page.getByAltText("Scan to browse event photos on your phone")).toBeVisible();
+  await expect(page.getByRole("alert").filter({ hasText: "Gallery connection lost" }))
+    .toContainText("Gallery connection lost", {
+    timeout: 7_000,
+  });
+  await expect(page.getByRole("button", { name: "Open event photo" })).toHaveCount(2);
+  await page.getByRole("button", { name: "Try again" }).click();
+  await expect(page.getByRole("button", { name: "Open event photo" })).toHaveCount(3);
+  expect(maximumActive).toBe(1);
+  expect(await seriousA11yViolations(page)).toEqual([]);
+});

From af41f009d28e5dc090eda6abbba2524e150d3ac8 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:59:04 +0800
Subject: [PATCH 094/105] feat: scale and localize admin moderation

---
 .../admin-moderation-integration.test.ts      |  13 +
 app/[event]/admin/admin.module.css            |  55 ++-
 app/[event]/admin/moderation-dialog.test.tsx  |  74 ++++
 app/[event]/admin/moderation-dialog.tsx       | 185 ++++++++++
 app/[event]/admin/moderation-panel.test.tsx   |  76 ++++
 app/[event]/admin/moderation-panel.tsx        | 207 +++++++++++
 app/[event]/admin/moderation-state.test.ts    | 101 +++++
 app/[event]/admin/moderation-state.ts         | 169 +++++++++
 app/[event]/admin/page.tsx                    | 348 +++++++++++++++---
 app/i18n/catalog.test.ts                      |   7 +
 app/i18n/catalog.ts                           | 113 ++++++
 app/i18n/locale.test.ts                       |   8 +
 app/i18n/locale.ts                            |  22 ++
 13 files changed, 1332 insertions(+), 46 deletions(-)
 create mode 100644 app/[event]/admin/admin-moderation-integration.test.ts
 create mode 100644 app/[event]/admin/moderation-dialog.test.tsx
 create mode 100644 app/[event]/admin/moderation-dialog.tsx
 create mode 100644 app/[event]/admin/moderation-panel.test.tsx
 create mode 100644 app/[event]/admin/moderation-panel.tsx
 create mode 100644 app/[event]/admin/moderation-state.test.ts
 create mode 100644 app/[event]/admin/moderation-state.ts

diff --git a/app/[event]/admin/admin-moderation-integration.test.ts b/app/[event]/admin/admin-moderation-integration.test.ts
new file mode 100644
index 0000000..a387a64
--- /dev/null
+++ b/app/[event]/admin/admin-moderation-integration.test.ts
@@ -0,0 +1,13 @@
+import { expect, test } from "bun:test";
+
+test("Admin replaces the public polling contact sheet with authenticated moderation paging", async () => {
+  const source = await Bun.file(new URL("./page.tsx", import.meta.url)).text();
+
+  expect(source).toContain("/api/moderation/photos?");
+  expect(source).toContain('"x-booth-key": adminKey');
+  expect(source).toContain("<ModerationPanel");
+  expect(source).toContain("<ModerationDialog");
+  expect(source).not.toContain("Recent contact sheet");
+  expect(source).not.toContain("setInterval(() => void loadPhotos()");
+  expect(source).not.toContain("fetch(`/api/photos?${query}`, { cache: \"no-store\" })");
+});
diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index 12c8f84..5466524 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -84,12 +84,63 @@
 .keyRow { display: flex; }.keyRow input { min-width: 0; width: 100%; border: 1px solid var(--ink); padding: 11px; font: 12px/1 ui-monospace, monospace; }.keyRow button, .copyWide, .clearKey, .saveButton, .exportButton, .linkActions a, .linkActions button, .failure button { border: 1px solid var(--ink); color: var(--ink); background: var(--amber); padding: 10px 12px; font: 800 12px/1 system-ui, sans-serif; cursor: pointer; text-decoration: none; }.groupHead button:disabled, .keyRow input:disabled, .keyRow button:disabled, .clearKey:disabled { cursor: wait; opacity: .55; }.copyWide, .clearKey { margin-top: 7px; width: 100%; background: #fff; }.clearKey { border-style: dashed; color: #555; }
 .linkCard { display: grid; grid-template-columns: minmax(0, 1fr) 94px; gap: 12px; background: var(--ink); color: #fff; }.linkCard > div > span { color: var(--amber); font: 800 9px/1 ui-monospace, monospace; text-transform: uppercase; }.linkCard h2 { font-size: 25px; margin: 6px 0 10px; }.linkCard code { display: block; color: #d3cec4; font: 10px/1.35 ui-monospace, monospace; word-break: break-all; }.linkCard img { width: 94px; height: 94px; background: #fff; padding: 5px; }.linkActions { display: flex; gap: 5px; margin-top: 12px; }.linkActions a, .linkActions button { flex: 1; padding: 8px; text-align: center; background: transparent; color: #fff; border-color: #777; }.saveButton, .exportButton { width: 100%; padding: 14px; background: var(--pink); color: #fff; border: 0; }.exportButton { margin-top: 8px; color: var(--ink); background: var(--amber); }.saveButton:disabled, .exportButton:disabled { opacity: .5; cursor: wait; }
 .contactSheet { display: grid; grid-template-columns: repeat(auto-fill, minmax(155px, 1fr)); gap: 8px; padding-top: 15px; }.contactPhoto { position: relative; min-width: 0; padding: 7px; background: #fff; border: 1px solid #b2aea5; }.contactPhoto > img { display: block; width: 100%; aspect-ratio: 1; object-fit: cover; background: #ccc; }.contactPhoto > div:not(.deleteConfirm) { display: flex; justify-content: space-between; gap: 8px; padding-top: 7px; }.contactPhoto time { font: 800 10px/1 ui-monospace, monospace; }.contactPhoto code { overflow: hidden; text-overflow: ellipsis; font: 9px/1 ui-monospace, monospace; color: #777; }.removePhoto { width: 100%; margin-top: 7px; border: 0; padding: 6px; background: transparent; color: #b3154a; font: 700 10px/1 system-ui, sans-serif; cursor: pointer; }.deleteConfirm { position: absolute; inset: 7px; z-index: 3; display: flex; flex-direction: column; justify-content: center; gap: 7px; padding: 12px; color: #fff; background: rgba(16,16,16,.96); }.deleteConfirm span { font: 800 12px/1.3 system-ui, sans-serif; }.deleteConfirm button { padding: 7px; border: 1px solid #777; color: #fff; background: transparent; cursor: pointer; }.deleteConfirm button:first-of-type { color: #fff; background: #c51651; border-color: #c51651; }
+.moderation { min-width: 0; }
+.moderationFilters { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)) auto; gap: 9px; align-items: end; margin-top: 15px; border: 2px solid var(--ink); padding: 12px; background: #fff; }
+.moderationFilters label { min-width: 0; }
+.moderationFilters label > span { display: block; margin-bottom: 7px; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .07em; text-transform: uppercase; }
+.moderationFilters input { min-height: 44px; width: 100%; border: 1px solid var(--ink); padding: 9px; color: var(--ink); background: #fff; font: 700 13px/1 system-ui, sans-serif; }
+.moderationFilterActions { display: flex; gap: 6px; }
+.moderationFilterActions button, .moderationLoadMore, .moderationRebuild button { min-height: 44px; border: 1px solid var(--ink); padding: 10px 13px; color: var(--ink); background: var(--amber); font: 800 11px/1.1 system-ui, sans-serif; cursor: pointer; }
+.moderationFilterActions button:last-child { background: #fff; }
+.moderationFilterActions button:disabled, .moderationLoadMore:disabled, .moderationRebuild button:disabled { cursor: wait; opacity: .58; }
+.moderationSummary { display: flex; min-height: 34px; align-items: center; justify-content: space-between; gap: 12px; padding-block: 10px 7px; }
+.moderationSummary strong { font: 900 12px/1 ui-monospace, monospace; text-transform: uppercase; }
+.moderationSummary span { color: #635f57; font: 700 11px/1 system-ui, sans-serif; }
+.moderationLive, .moderationAlert { overflow: hidden; block-size: 0; inline-size: 0; position: absolute; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
+.moderationLive:not(:empty), .moderationAlert:not(:empty) { position: static; overflow: visible; block-size: auto; inline-size: auto; margin-bottom: 9px; border-inline-start: 5px solid var(--green); padding: 10px 12px; clip: auto; clip-path: none; color: var(--ink); background: #eaffcf; white-space: normal; font: 800 12px/1.35 system-ui, sans-serif; }
+.moderationAlert:not(:empty) { border-color: #be124e; color: #8f1239; background: #ffe4e6; }
+.moderationGrid { display: grid; grid-template-columns: repeat(auto-fill, minmax(155px, 1fr)); gap: 8px; margin: 0; padding: 0; list-style: none; }
+.moderationTile { min-width: 0; }
+.moderationTile > button { display: grid; width: 100%; min-height: 44px; border: 1px solid #b2aea5; padding: 7px; color: var(--ink); background: #fff; text-align: start; cursor: zoom-in; }
+.moderationTile img { display: block; width: 100%; aspect-ratio: 1; object-fit: cover; background: #ccc; }
+.moderationTile span { display: grid; min-width: 0; gap: 5px; padding-top: 8px; }
+.moderationTile time { font: 800 10px/1.2 ui-monospace, monospace; }
+.moderationTile bdi { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.moderationTile code { color: #635f57; font: 9px/1 ui-monospace, monospace; }
+.moderationLoadMore { width: 100%; margin-top: 9px; }
+.moderationRebuild { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 18px; align-items: center; margin-top: 15px; border-inline-start: 8px solid var(--green); padding: 15px; color: #fff; background: var(--ink); }
+.moderationRebuild h3 { font: 900 21px/1 Impact, "Arial Narrow", sans-serif; text-transform: uppercase; }
+.moderationRebuild p { max-width: 58ch; margin-top: 6px; color: #d3cec4; font-size: 12px; line-height: 1.4; }
+.moderationBackdrop { position: fixed; inset: 0; z-index: 50; display: grid; place-items: center; padding: clamp(10px, 3vw, 36px); background: rgba(8,8,8,.82); }
+.moderationDialog { display: grid; grid-template-columns: minmax(0, 1.4fr) minmax(240px, .6fr); grid-template-rows: auto minmax(0, 1fr) auto; gap: 12px 18px; width: min(1080px, 100%); max-height: calc(100dvh - 20px); overflow: auto; border: 2px solid var(--paper); padding: clamp(14px, 2.5vw, 28px); color: var(--paper); background: var(--ink); box-shadow: 10px 10px 0 var(--pink); }
+.moderationDialogHead { grid-column: 1 / -1; display: flex; align-items: flex-start; justify-content: space-between; gap: 20px; border-bottom: 1px solid #777; padding-bottom: 12px; }
+.moderationDialogHead p { color: var(--amber); font: 800 10px/1 ui-monospace, monospace; text-transform: uppercase; }
+.moderationDialogHead h2 { margin-top: 5px; font: 900 clamp(31px, 5vw, 58px)/.85 Impact, "Arial Narrow", sans-serif; text-transform: uppercase; }
+.moderationDialogHead button, .moderationDialogNav button, .moderationRemove, .moderationConfirm button { min-width: 44px; min-height: 44px; border: 1px solid #777; padding: 10px 13px; color: #fff; background: transparent; font: 800 12px/1.1 system-ui, sans-serif; cursor: pointer; }
+.moderationInspection { min-width: 0; margin: 0; }
+.moderationInspection img { display: block; max-width: 100%; max-height: min(64dvh, 780px); margin-inline: auto; object-fit: contain; background: #000; }
+.moderationInspection figcaption { display: flex; min-width: 0; flex-wrap: wrap; justify-content: space-between; gap: 8px; padding-top: 9px; }
+.moderationInspection time, .moderationInspection code { color: #d3cec4; font: 10px/1.2 ui-monospace, monospace; overflow-wrap: anywhere; }
+.moderationDialogNav { display: grid; grid-template-columns: 1fr 1fr; gap: 7px; align-self: start; }
+.moderationDialogNav button:disabled { cursor: default; opacity: .35; }
+.moderationCleanup, .moderationDialogError { grid-column: 2; border-inline-start: 5px solid var(--amber); padding: 11px; color: var(--ink); background: var(--amber); font: 800 12px/1.35 system-ui, sans-serif; }
+.moderationDialogError { border-color: var(--pink); color: #fff; background: #8f1239; }
+.moderationRemove { grid-column: 2; align-self: end; border-color: var(--pink); color: #fff; background: var(--pink); }
+.moderationConfirm { grid-column: 2; align-self: end; border: 1px solid #777; padding: 14px; }
+.moderationConfirm h3 { font: 900 23px/1 Impact, "Arial Narrow", sans-serif; text-transform: uppercase; }
+.moderationConfirm p { margin-top: 9px; font-size: 12px; line-height: 1.4; }
+.moderationConfirm p > span { display: block; margin-bottom: 4px; color: #bbb; font: 800 9px/1 ui-monospace, monospace; text-transform: uppercase; }
+.moderationConfirm code { overflow-wrap: anywhere; color: var(--amber); font: 10px/1.3 ui-monospace, monospace; }
+.moderationConfirm > div { display: grid; grid-template-columns: 1fr 1fr; gap: 7px; margin-top: 13px; }
+.moderationConfirm button:first-child { border-color: var(--pink); background: var(--pink); }
+.moderationConfirm button:disabled { cursor: wait; opacity: .58; }
 .failure, .emptySheet { padding: 28px; margin-top: 15px; border: 2px dashed #8c8880; background: rgba(255,255,255,.5); }.failure strong, .emptySheet strong { font: 900 22px/1 Impact, sans-serif; text-transform: uppercase; }.failure p, .emptySheet p { margin: 8px 0 14px; font-size: 13px; }.failure button { background: var(--amber); }
 .boothOperations { border-block: 2px solid var(--ink); padding-block: 18px; }.boothOperationsHead { display: flex; align-items: flex-end; justify-content: space-between; gap: 18px; }.boothOperationsHead h2 { margin-top: 8px; font: 900 clamp(30px, 4vw, 52px)/.9 Impact, "Arial Narrow", sans-serif; letter-spacing: -.02em; text-transform: uppercase; }.boothOperationsHead p { max-width: 52ch; margin-top: 8px; font-size: 13px; line-height: 1.4; }.boothControlState { flex: 0 0 auto; border: 2px solid var(--ink); padding: 10px 12px; color: var(--ink); background: var(--green); text-align: end; }.boothControlState[data-paused="true"] { color: #fff; background: #be124e; }.boothControlState span { display: block; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlState strong { display: block; margin-top: 4px; font: 900 19px/1 "Arial Narrow", Arial, sans-serif; text-transform: uppercase; }.boothControlBar { display: grid; grid-template-columns: minmax(0, 1fr) auto; column-gap: 12px; row-gap: 7px; margin-top: 18px; padding: 13px; color: #fff; background: var(--ink); }.boothControlBar label { grid-column: 1 / -1; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothControlBar textarea { min-height: 44px; width: 100%; resize: vertical; border: 1px solid #777; padding: 10px; color: #fff; background: #1a1a19; font: 13px/1.25 system-ui, sans-serif; }.boothActions { display: flex; align-items: stretch; gap: 7px; }.boothActions button, .boothLoadMore { min-height: 44px; border: 1px solid #777; padding: 10px 12px; color: #fff; background: transparent; font: 800 11px/1.1 system-ui, sans-serif; cursor: pointer; }.boothActions .boothPauseButton { border-color: var(--pink); color: var(--ink); background: var(--pink); }.boothActions button:disabled, .boothLoadMore:disabled, .boothControlBar textarea:disabled { cursor: wait; opacity: .58; }.boothStatusError { margin-top: 9px; border-inline-start: 5px solid #be124e; padding: 10px 12px; color: #8f1239; background: #ffe4e6; font: 800 12px/1.3 system-ui, sans-serif; }.boothRoster { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 295px), 1fr)); gap: 9px; margin: 14px 0 0; padding: 0; list-style: none; }.boothRow { min-width: 0; border: 2px solid var(--ink); padding: 11px; background: #fff; }.boothRow[data-stale="true"] { border-color: #be124e; background: #fff1f2; }.boothRowHead { display: flex; align-items: center; justify-content: space-between; gap: 9px; padding-bottom: 9px; border-bottom: 1px solid var(--ink); }.boothRowHead > code { min-width: 0; overflow: hidden; font: 800 13px/1 ui-monospace, monospace; text-overflow: ellipsis; white-space: nowrap; }.boothPresence { flex: 0 0 auto; padding: 4px 6px; color: #fff; background: #be124e; font: 900 9px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }.boothPresence[data-live="true"] { color: var(--ink); background: var(--green); }.boothFacts { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 9px 12px; margin-top: 10px; }.boothFacts div { min-width: 0; }.boothFacts dt { color: #635f57; font: 800 9px/1 ui-monospace, monospace; letter-spacing: .06em; text-transform: uppercase; }.boothFacts dd { overflow: hidden; margin-top: 3px; font: 800 12px/1.2 system-ui, sans-serif; text-overflow: ellipsis; white-space: nowrap; }.boothFacts dd code { font: 800 11px/1.2 ui-monospace, monospace; }.boothEmpty { margin-top: 14px; border: 2px dashed #8c8880; padding: 20px; background: rgba(255,255,255,.5); }.boothEmpty strong { font: 900 20px/1 Impact, sans-serif; text-transform: uppercase; }.boothEmpty p { margin-top: 7px; font-size: 13px; }.boothLoadMore { display: block; width: 100%; margin-top: 9px; border-color: var(--ink); color: var(--ink); background: var(--amber); }
 .authPage { display: grid; place-items: center; padding: 20px; background: var(--ink); color: #fff; }.authCard { width: min(500px, 100%); border-top: 8px solid var(--pink); padding: clamp(25px, 5vw, 55px); background: #1a1a19; }.authCard h1 { margin: 25px 0; font: 900 clamp(58px, 10vw, 90px)/.78 Impact, sans-serif; text-transform: uppercase; }.authCard > p:not(.kicker) { color: #bbb; line-height: 1.4; margin-bottom: 28px; }.authCard label { display: block; margin-bottom: 8px; font: 800 11px/1 ui-monospace, monospace; text-transform: uppercase; }.authCard input { width: 100%; padding: 14px; border: 1px solid #777; background: #080808; color: #fff; font: 16px/1 ui-monospace, monospace; }.authCard button { width: 100%; margin-top: 10px; padding: 15px; border: 0; color: #fff; background: var(--pink); font-weight: 900; cursor: pointer; }
 .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
-@media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; }.localeOptions label:has(input:checked), .experienceToggle:has(input:checked) { border: 2px solid Highlight; box-shadow: none; }.exportPanel { border: 3px solid CanvasText; box-shadow: none; }.exportPrimary, .exportSecondary { border: 2px solid ButtonText; } }
+@media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .moderationDialog button:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; }.localeOptions label:has(input:checked), .experienceToggle:has(input:checked) { border: 2px solid Highlight; box-shadow: none; }.exportPanel { border: 3px solid CanvasText; box-shadow: none; }.exportPrimary, .exportSecondary { border: 2px solid ButtonText; } }
 @media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; }.boothOperationsHead { align-items: start; flex-direction: column; }.boothControlState { text-align: start; } }
-@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; }.boothControlBar { grid-template-columns: 1fr; }.boothActions { display: grid; grid-template-columns: 1fr 1fr; }.boothRoster { grid-template-columns: 1fr; } }
+@media (max-width: 760px) { .moderationFilters { grid-template-columns: 1fr; }.moderationFilterActions { display: grid; grid-template-columns: 1fr 1fr; }.moderationRebuild { grid-template-columns: 1fr; }.moderationDialog { grid-template-columns: 1fr; }.moderationDialogHead, .moderationCleanup, .moderationDialogError, .moderationRemove, .moderationConfirm { grid-column: 1; } }
+@media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet, .moderationGrid { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; }.boothControlBar { grid-template-columns: 1fr; }.boothActions { display: grid; grid-template-columns: 1fr 1fr; }.boothRoster { grid-template-columns: 1fr; } }
 @media (max-width: 600px) { .experiencePanel { grid-template-columns: 1fr; }.localeOptions { grid-template-columns: 1fr; }.experienceField { grid-template-columns: 1fr; gap: 6px; } }
 @media (prefers-reduced-motion: reduce) { .console *, .console *::before, .console *::after, .authPage *, .authPage *::before, .authPage *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; } }
diff --git a/app/[event]/admin/moderation-dialog.test.tsx b/app/[event]/admin/moderation-dialog.test.tsx
new file mode 100644
index 0000000..826091b
--- /dev/null
+++ b/app/[event]/admin/moderation-dialog.test.tsx
@@ -0,0 +1,74 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ModerationDialog } from "./moderation-dialog";
+
+const photo = {
+  key: "launch/1753315200000-private-looking-name.jpg",
+  url: "https://photos.example/photo.jpg",
+  uploadedAt: "2026-07-24T00:00:00.000Z",
+  capturedAt: 1_753_315_200_000,
+};
+
+test("renders a labelled inspection dialog with navigation and exact confirmation", () => {
+  const html = renderToStaticMarkup(
+    <ModerationDialog
+      locale="en"
+      photo={photo}
+      position={2}
+      loadedCount={4}
+      hasPrevious
+      hasNext
+      confirming
+      deleting={false}
+      cleanupPending={false}
+      error=""
+      returnFocus={null}
+      onPrevious={() => {}}
+      onNext={() => {}}
+      onClose={() => {}}
+      onRequestDelete={() => {}}
+      onCancelDelete={() => {}}
+      onConfirmDelete={() => {}}
+    />
+  );
+
+  expect(html).toContain('role="dialog"');
+  expect(html).toContain('aria-modal="true"');
+  expect(html).toContain('aria-labelledby="moderation-dialog-title"');
+  expect(html).toContain("Previous");
+  expect(html).toContain("Next");
+  expect(html).toContain("Close");
+  expect(html).toContain("1753315200000-private-looking-name.jpg");
+  expect(html).toContain("<bdi><code>launch/1753315200000-private-looking-name.jpg</code></bdi>");
+  expect(html).toContain("Confirm exact deletion");
+  expect(html).toContain("Cancel");
+  expect(html).not.toMatch(/receipt|revision|device/i);
+});
+
+test("cleanup warning says the public photo is gone and offers no retry", () => {
+  const html = renderToStaticMarkup(
+    <ModerationDialog
+      locale="en"
+      photo={photo}
+      position={1}
+      loadedCount={1}
+      hasPrevious={false}
+      hasNext={false}
+      confirming={false}
+      deleting={false}
+      cleanupPending
+      error=""
+      returnFocus={null}
+      onPrevious={() => {}}
+      onNext={() => {}}
+      onClose={() => {}}
+      onRequestDelete={() => {}}
+      onCancelDelete={() => {}}
+      onConfirmDelete={() => {}}
+    />
+  );
+
+  expect(html).toContain("The public photo is already deleted");
+  expect(html).not.toContain("Retry delete");
+  expect(html).toContain('role="status"');
+});
diff --git a/app/[event]/admin/moderation-dialog.tsx b/app/[event]/admin/moderation-dialog.tsx
new file mode 100644
index 0000000..3a91a2f
--- /dev/null
+++ b/app/[event]/admin/moderation-dialog.tsx
@@ -0,0 +1,185 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { SupportedLocale } from "../../i18n/catalog";
+import { localeDirection, message } from "../../i18n/catalog";
+import { formatLocalizedDateTime } from "../../i18n/locale";
+import type { ModerationPhoto } from "../../moderation";
+import styles from "./admin.module.css";
+
+type ModerationDialogProps = {
+  locale: SupportedLocale;
+  photo: ModerationPhoto;
+  position: number;
+  loadedCount: number;
+  hasPrevious: boolean;
+  hasNext: boolean;
+  confirming: boolean;
+  deleting: boolean;
+  cleanupPending: boolean;
+  error: string;
+  timeZone?: string;
+  returnFocus: HTMLElement | null;
+  onPrevious: () => void;
+  onNext: () => void;
+  onClose: () => void;
+  onRequestDelete: () => void;
+  onCancelDelete: () => void;
+  onConfirmDelete: () => void;
+};
+
+const FOCUSABLE = [
+  "button:not([disabled])",
+  "[href]",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+function filename(key: string): string {
+  return key.slice(key.lastIndexOf("/") + 1);
+}
+
+export function ModerationDialog({
+  locale,
+  photo,
+  position,
+  loadedCount,
+  hasPrevious,
+  hasNext,
+  confirming,
+  deleting,
+  cleanupPending,
+  error,
+  timeZone,
+  returnFocus,
+  onPrevious,
+  onNext,
+  onClose,
+  onRequestDelete,
+  onCancelDelete,
+  onConfirmDelete,
+}: ModerationDialogProps) {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const text = (key: Parameters<typeof message>[1], values?: Record<string, string | number>) =>
+    message(locale, key, values);
+  const exactFilename = filename(photo.key);
+  const displayDate = formatLocalizedDateTime(photo.capturedAt, locale, timeZone);
+
+  useEffect(() => {
+    closeRef.current?.focus();
+    return () => {
+      if (returnFocus?.isConnected) returnFocus.focus();
+    };
+  }, [returnFocus]);
+
+  return (
+    <div className={styles.moderationBackdrop}>
+      <div
+        ref={dialogRef}
+        className={styles.moderationDialog}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="moderation-dialog-title"
+        dir={localeDirection(locale)}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            onClose();
+            return;
+          }
+          if (event.key === "ArrowLeft" && hasPrevious) {
+            event.preventDefault();
+            onPrevious();
+            return;
+          }
+          if (event.key === "ArrowRight" && hasNext) {
+            event.preventDefault();
+            onNext();
+            return;
+          }
+          if (event.key !== "Tab" || !dialogRef.current) return;
+          const focusable = [...dialogRef.current.querySelectorAll<HTMLElement>(FOCUSABLE)];
+          if (focusable.length === 0) return;
+          const first = focusable[0];
+          const last = focusable[focusable.length - 1];
+          if (event.shiftKey && document.activeElement === first) {
+            event.preventDefault();
+            last.focus();
+          } else if (!event.shiftKey && document.activeElement === last) {
+            event.preventDefault();
+            first.focus();
+          }
+        }}
+      >
+        <header className={styles.moderationDialogHead}>
+          <div>
+            <p>{text("moderationPosition", { position, count: loadedCount })}</p>
+            <h2 id="moderation-dialog-title">{text("moderationInspectTitle")}</h2>
+          </div>
+          <button ref={closeRef} type="button" onClick={onClose}>
+            {text("moderationClose")}
+          </button>
+        </header>
+
+        <figure className={styles.moderationInspection}>
+          <img
+            src={photo.url}
+            alt={text("moderationPhotoAlt", { date: displayDate })}
+          />
+          <figcaption>
+            <time dateTime={photo.uploadedAt}>{displayDate}</time>
+            <bdi><code>{exactFilename}</code></bdi>
+          </figcaption>
+        </figure>
+
+        <nav className={styles.moderationDialogNav} aria-label={text("moderationInspectTitle")}>
+          <button type="button" onClick={onPrevious} disabled={!hasPrevious}>
+            ← {text("moderationPrevious")}
+          </button>
+          <button type="button" onClick={onNext} disabled={!hasNext}>
+            {text("moderationNext")} →
+          </button>
+        </nav>
+
+        {cleanupPending && (
+          <p className={styles.moderationCleanup} role="status">
+            {text("moderationCleanupPending")}
+          </p>
+        )}
+        {error && <p className={styles.moderationDialogError} role="alert">{error}</p>}
+
+        {confirming ? (
+          <section className={styles.moderationConfirm} aria-labelledby="moderation-confirm-title">
+            <h3 id="moderation-confirm-title">{text("moderationConfirmTitle")}</h3>
+            <p>{text("moderationConfirmBody", { filename: exactFilename })}</p>
+            <p>
+              <span>{text("moderationCompleteKey")}</span>
+              <bdi><code>{photo.key}</code></bdi>
+            </p>
+            <div>
+              <button type="button" onClick={onConfirmDelete} disabled={deleting}>
+                {deleting ? text("moderationRemoving") : text("moderationConfirmDelete")}
+              </button>
+              <button type="button" onClick={onCancelDelete} disabled={deleting}>
+                {text("moderationCancel")}
+              </button>
+            </div>
+          </section>
+        ) : (
+          !cleanupPending && (
+            <button
+              className={styles.moderationRemove}
+              type="button"
+              onClick={onRequestDelete}
+            >
+              {text("moderationRemove")}
+            </button>
+          )
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/app/[event]/admin/moderation-panel.test.tsx b/app/[event]/admin/moderation-panel.test.tsx
new file mode 100644
index 0000000..c4c0439
--- /dev/null
+++ b/app/[event]/admin/moderation-panel.test.tsx
@@ -0,0 +1,76 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ModerationPanel } from "./moderation-panel";
+
+test("renders scalable localized moderation controls without claiming an Event total", () => {
+  const html = renderToStaticMarkup(
+    <ModerationPanel
+      locale="zh-SG"
+      photos={[{
+        key: "launch/1753315200000-photo.jpg",
+        url: "https://photos.example/photo.jpg",
+        uploadedAt: "2026-07-24T00:00:00.000Z",
+        capturedAt: 1_753_315_200_000,
+      }]}
+      filters={{ from: "", to: "" }}
+      nextCursor="cursor"
+      loading={false}
+      loadingMore={false}
+      error=""
+      notice=""
+      rebuild={{ complete: false, scanned: 100, indexed: 98 }}
+      rebuilding={false}
+      onFiltersChange={() => {}}
+      onApplyFilters={() => {}}
+      onClearFilters={() => {}}
+      onLoadMore={() => {}}
+      onOpen={() => {}}
+      onRebuild={() => {}}
+    />
+  );
+
+  expect(html).toContain('aria-labelledby="moderation-heading"');
+  expect(html).toContain('for="moderation-from"');
+  expect(html).toContain('for="moderation-to"');
+  expect(html).toContain("已载入 1 张");
+  expect(html).not.toContain("活动共有");
+  expect(html).toContain('loading="lazy"');
+  expect(html).toContain('type="button"');
+  expect(html).toContain("继续重建");
+  expect(html).toContain('aria-live="polite"');
+  expect(html).toContain('role="alert"');
+  expect(html).not.toMatch(/receipt|revision|device/i);
+});
+
+test("marks Load More busy and disabled while preserving a labelled photo button", () => {
+  const html = renderToStaticMarkup(
+    <ModerationPanel
+      locale="ar"
+      photos={[{
+        key: "launch/photo.jpg",
+        url: "https://photos.example/photo.jpg",
+        uploadedAt: "2026-07-24T00:00:00.000Z",
+        capturedAt: 1_753_315_200_000,
+      }]}
+      filters={{ from: "", to: "" }}
+      nextCursor="cursor"
+      loading={false}
+      loadingMore
+      error=""
+      notice=""
+      rebuild={null}
+      rebuilding={false}
+      onFiltersChange={() => {}}
+      onApplyFilters={() => {}}
+      onClearFilters={() => {}}
+      onLoadMore={() => {}}
+      onOpen={() => {}}
+      onRebuild={() => {}}
+    />
+  );
+
+  expect(html).toContain('dir="rtl"');
+  expect(html).toContain('aria-busy="true"');
+  expect(html).toContain('disabled=""');
+  expect(html).toContain("افتح الصورة");
+});
diff --git a/app/[event]/admin/moderation-panel.tsx b/app/[event]/admin/moderation-panel.tsx
new file mode 100644
index 0000000..a642e9a
--- /dev/null
+++ b/app/[event]/admin/moderation-panel.tsx
@@ -0,0 +1,207 @@
+"use client";
+
+import type { SupportedLocale } from "../../i18n/catalog";
+import { localeDirection, message } from "../../i18n/catalog";
+import { formatLocalizedDateTime } from "../../i18n/locale";
+import type { ModerationPhoto } from "../../moderation";
+import styles from "./admin.module.css";
+import type { ModerationFilters } from "./moderation-state";
+
+export type ModerationRebuildState = {
+  complete: boolean;
+  scanned: number;
+  indexed: number;
+};
+
+type ModerationPanelProps = {
+  locale: SupportedLocale;
+  photos: readonly ModerationPhoto[];
+  filters: ModerationFilters;
+  nextCursor: string | null;
+  loading: boolean;
+  loadingMore: boolean;
+  error: string;
+  notice: string;
+  rebuild: ModerationRebuildState | null;
+  rebuilding: boolean;
+  timeZone?: string;
+  headingRef?: React.RefObject<HTMLHeadingElement | null>;
+  photoRefs?: React.MutableRefObject<Map<string, HTMLButtonElement>>;
+  onFiltersChange: (filters: ModerationFilters) => void;
+  onApplyFilters: () => void;
+  onClearFilters: () => void;
+  onLoadMore: () => void;
+  onOpen: (photo: ModerationPhoto, trigger: HTMLButtonElement) => void;
+  onRebuild: () => void;
+};
+
+function filename(key: string): string {
+  return key.slice(key.lastIndexOf("/") + 1);
+}
+
+export function ModerationPanel({
+  locale,
+  photos,
+  filters,
+  nextCursor,
+  loading,
+  loadingMore,
+  error,
+  notice,
+  rebuild,
+  rebuilding,
+  timeZone,
+  headingRef,
+  photoRefs,
+  onFiltersChange,
+  onApplyFilters,
+  onClearFilters,
+  onLoadMore,
+  onOpen,
+  onRebuild,
+}: ModerationPanelProps) {
+  const text = (key: Parameters<typeof message>[1], values?: Record<string, string | number>) =>
+    message(locale, key, values);
+
+  return (
+    <section
+      className={styles.moderation}
+      aria-labelledby="moderation-heading"
+      dir={localeDirection(locale)}
+    >
+      <div className={styles.sectionHead}>
+        <div>
+          <span>04</span>
+          <h2 id="moderation-heading" ref={headingRef} tabIndex={-1}>
+            {text("moderationHeading")}
+          </h2>
+        </div>
+        <p>{text("moderationIntro")}</p>
+      </div>
+
+      <form
+        className={styles.moderationFilters}
+        onSubmit={(event) => {
+          event.preventDefault();
+          onApplyFilters();
+        }}
+      >
+        <label htmlFor="moderation-from">
+          <span>{text("moderationFrom")}</span>
+          <input
+            id="moderation-from"
+            type="datetime-local"
+            value={filters.from}
+            onChange={(event) => onFiltersChange({ ...filters, from: event.target.value })}
+          />
+        </label>
+        <label htmlFor="moderation-to">
+          <span>{text("moderationTo")}</span>
+          <input
+            id="moderation-to"
+            type="datetime-local"
+            value={filters.to}
+            onChange={(event) => onFiltersChange({ ...filters, to: event.target.value })}
+          />
+        </label>
+        <div className={styles.moderationFilterActions}>
+          <button type="submit" disabled={loading}>{text("moderationApply")}</button>
+          <button type="button" onClick={onClearFilters} disabled={loading}>
+            {text("moderationClear")}
+          </button>
+        </div>
+      </form>
+
+      <div className={styles.moderationSummary}>
+        <strong>{text("moderationLoaded", { count: photos.length })}</strong>
+        {loading && <span role="status">{text("moderationLoading")}</span>}
+      </div>
+
+      <div className={styles.moderationLive} aria-live="polite" aria-atomic="true">
+        {notice}
+      </div>
+      <div className={styles.moderationAlert} role="alert" aria-atomic="true">
+        {error}
+      </div>
+
+      {error && photos.length === 0 ? (
+        <div className={styles.failure}>
+          <strong>{text("moderationError")}</strong>
+          <button type="button" onClick={onApplyFilters}>{text("moderationRetry")}</button>
+        </div>
+      ) : photos.length === 0 && !loading ? (
+        <div className={styles.emptySheet}><strong>{text("moderationEmpty")}</strong></div>
+      ) : (
+        <ol className={styles.moderationGrid} aria-label={text("moderationHeading")}>
+          {photos.map((photo) => {
+            const displayDate = formatLocalizedDateTime(photo.capturedAt, locale, timeZone);
+            const exactFilename = filename(photo.key);
+            return (
+              <li key={photo.key} className={styles.moderationTile}>
+                <button
+                  type="button"
+                  ref={(element) => {
+                    if (!photoRefs) return;
+                    if (element) photoRefs.current.set(photo.key, element);
+                    else photoRefs.current.delete(photo.key);
+                  }}
+                  onClick={(event) => onOpen(photo, event.currentTarget)}
+                  aria-label={text("moderationOpenPhoto", { filename: exactFilename })}
+                >
+                  <img
+                    src={photo.url}
+                    alt={text("moderationPhotoAlt", { date: displayDate })}
+                    loading="lazy"
+                    decoding="async"
+                  />
+                  <span>
+                    <time dateTime={photo.uploadedAt}>{displayDate}</time>
+                    <bdi><code>{exactFilename}</code></bdi>
+                  </span>
+                </button>
+              </li>
+            );
+          })}
+        </ol>
+      )}
+
+      {nextCursor !== null && (
+        <button
+          className={styles.moderationLoadMore}
+          type="button"
+          onClick={onLoadMore}
+          disabled={loading || loadingMore}
+          aria-busy={loadingMore}
+        >
+          {loadingMore ? text("moderationLoadingMore") : text("moderationLoadMore")}
+        </button>
+      )}
+
+      <aside className={styles.moderationRebuild} aria-labelledby="moderation-rebuild-heading">
+        <div>
+          <h3 id="moderation-rebuild-heading">{text("moderationRebuildHeading")}</h3>
+          <p>{text("moderationRebuildIntro")}</p>
+          {rebuild && (
+            <p role="status">
+              {rebuild.complete
+                ? text("moderationRebuildComplete")
+                : text("moderationRebuildProgress", {
+                    scanned: rebuild.scanned,
+                    indexed: rebuild.indexed,
+                  })}
+            </p>
+          )}
+        </div>
+        {(!rebuild || !rebuild.complete) && (
+          <button type="button" onClick={onRebuild} disabled={rebuilding}>
+            {rebuilding
+              ? text("moderationRebuilding")
+              : rebuild
+                ? text("moderationRebuildContinue")
+                : text("moderationRebuildStart")}
+          </button>
+        )}
+      </aside>
+    </section>
+  );
+}
diff --git a/app/[event]/admin/moderation-state.test.ts b/app/[event]/admin/moderation-state.test.ts
new file mode 100644
index 0000000..ac70ff2
--- /dev/null
+++ b/app/[event]/admin/moderation-state.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import type { ModerationPhoto } from "../../moderation";
+import {
+  filtersChanged,
+  mergeModerationPage,
+  ModerationPageCoordinator,
+  moderationFilterInstant,
+  parseModerationPageResponse,
+  removeModeratedPhoto,
+} from "./moderation-state";
+
+const photo = (key: string, capturedAt: number): ModerationPhoto => ({
+  key: `launch/${key}.jpg`,
+  url: `https://photos.example/${key}.jpg`,
+  uploadedAt: new Date(capturedAt).toISOString(),
+  capturedAt,
+});
+
+describe("Admin moderation state", () => {
+  test("deduplicates exact keys and retains reverse-time order", () => {
+    expect(mergeModerationPage(
+      [photo("middle", 20), photo("old", 10)],
+      [photo("new", 30), photo("middle", 20)]
+    ).map(({ key }) => key)).toEqual([
+      "launch/new.jpg",
+      "launch/middle.jpg",
+      "launch/old.jpg",
+    ]);
+  });
+
+  test("detects an actual filter change but not an equivalent copy", () => {
+    expect(filtersChanged({ from: "", to: "" }, { from: "", to: "" })).toBe(false);
+    expect(filtersChanged(
+      { from: "2026-07-24T00:00", to: "" },
+      { from: "2026-07-25T00:00", to: "" }
+    )).toBe(true);
+  });
+
+  test("removes only the exact key and selects the next then previous focus target", () => {
+    const photos = [photo("new", 30), photo("middle", 20), photo("old", 10)];
+    expect(removeModeratedPhoto(photos, "launch/middle.jpg")).toEqual({
+      photos: [photos[0], photos[2]],
+      nextFocusKey: "launch/old.jpg",
+    });
+    expect(removeModeratedPhoto(photos, "launch/old.jpg").nextFocusKey)
+      .toBe("launch/middle.jpg");
+    expect(removeModeratedPhoto([photos[0]], photos[0].key)).toEqual({
+      photos: [],
+      nextFocusKey: null,
+    });
+  });
+
+  test("rejects stale pages after a filter, Event, or auth-scope reset", () => {
+    const coordinator = new ModerationPageCoordinator();
+    const old = coordinator.begin("launch", "admin-a", { from: "", to: "" });
+    const current = coordinator.begin("launch", "admin-a", {
+      from: "2026-07-24T00:00",
+      to: "",
+    });
+    expect(coordinator.accepts(old)).toBe(false);
+    expect(coordinator.accepts(current)).toBe(true);
+    coordinator.reset();
+    expect(coordinator.accepts(current)).toBe(false);
+  });
+
+  test("an empty final page keeps prior rows and clears the cursor", () => {
+    const coordinator = new ModerationPageCoordinator();
+    const ticket = coordinator.begin("launch", "admin-a", { from: "", to: "" });
+    expect(coordinator.merge(ticket, [photo("only", 10)], null, [], null)).toEqual({
+      photos: [photo("only", 10)],
+      nextCursor: null,
+    });
+  });
+
+  test("strictly parses the public moderation page shape", () => {
+    expect(parseModerationPageResponse({
+      photos: [photo("one", 10)],
+      nextCursor: "opaque",
+    })).toEqual({
+      photos: [photo("one", 10)],
+      nextCursor: "opaque",
+    });
+    expect(parseModerationPageResponse({
+      photos: [photo("one", 10)],
+      nextCursor: null,
+      receiptKey: "private",
+    })).toBeNull();
+    expect(parseModerationPageResponse({
+      photos: [{ ...photo("one", 10), deviceId: "private" }],
+      nextCursor: null,
+    })).toBeNull();
+  });
+
+  test("converts local datetime filters to RFC3339 instants and rejects invalid input", () => {
+    expect(moderationFilterInstant("")).toBeNull();
+    expect(moderationFilterInstant("not-a-date")).toBeUndefined();
+    expect(moderationFilterInstant("2026-07-24T08:30")).toMatch(
+      /^2026-07-24T\d{2}:30:00\.000Z$/
+    );
+  });
+});
diff --git a/app/[event]/admin/moderation-state.ts b/app/[event]/admin/moderation-state.ts
new file mode 100644
index 0000000..7ba1671
--- /dev/null
+++ b/app/[event]/admin/moderation-state.ts
@@ -0,0 +1,169 @@
+import type { ModerationPhoto } from "../../moderation";
+
+export type ModerationFilters = {
+  from: string;
+  to: string;
+};
+
+export type ModerationPageTicket = {
+  id: number;
+  event: string;
+  auth: string;
+  filters: ModerationFilters;
+};
+
+export type ModerationPageResponse = {
+  photos: ModerationPhoto[];
+  nextCursor: string | null;
+};
+
+export function mergeModerationPage(
+  current: readonly ModerationPhoto[],
+  incoming: readonly ModerationPhoto[]
+): ModerationPhoto[] {
+  const exact = new Map<string, ModerationPhoto>();
+  for (const photo of current) exact.set(photo.key, photo);
+  for (const photo of incoming) exact.set(photo.key, photo);
+  return [...exact.values()].sort((left, right) =>
+    right.capturedAt - left.capturedAt
+    || right.uploadedAt.localeCompare(left.uploadedAt)
+    || left.key.localeCompare(right.key)
+  );
+}
+
+export function removeModeratedPhoto(
+  photos: readonly ModerationPhoto[],
+  exactKey: string
+): {
+  photos: ModerationPhoto[];
+  nextFocusKey: string | null;
+} {
+  const index = photos.findIndex((photo) => photo.key === exactKey);
+  if (index < 0) return { photos: [...photos], nextFocusKey: null };
+  const remaining = photos.filter((photo) => photo.key !== exactKey);
+  return {
+    photos: remaining,
+    nextFocusKey: remaining[index]?.key ?? remaining[index - 1]?.key ?? null,
+  };
+}
+
+export function filtersChanged(
+  current: ModerationFilters,
+  next: ModerationFilters
+): boolean {
+  return current.from !== next.from || current.to !== next.to;
+}
+
+export function moderationFilterInstant(value: string): string | null | undefined {
+  if (value === "") return null;
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(value)) return undefined;
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed.toISOString();
+}
+
+export function parseModerationPageResponse(value: unknown): ModerationPageResponse | null {
+  if (!isRecord(value) || !hasExactKeys(value, ["photos", "nextCursor"])) return null;
+  if (
+    !Array.isArray(value.photos)
+    || (value.nextCursor !== null && typeof value.nextCursor !== "string")
+    || (typeof value.nextCursor === "string" && value.nextCursor.length === 0)
+  ) {
+    return null;
+  }
+  const photos: ModerationPhoto[] = [];
+  for (const candidate of value.photos) {
+    if (!isRecord(candidate)) return null;
+    const allowed = [
+      "key",
+      "url",
+      "uploadedAt",
+      "capturedAt",
+      "source",
+      "frameKey",
+    ];
+    if (
+      Object.keys(candidate).some((key) => !allowed.includes(key))
+      || typeof candidate.key !== "string"
+      || typeof candidate.url !== "string"
+      || typeof candidate.uploadedAt !== "string"
+      || Number.isNaN(Date.parse(candidate.uploadedAt))
+      || typeof candidate.capturedAt !== "number"
+      || !Number.isSafeInteger(candidate.capturedAt)
+      || candidate.capturedAt < 0
+      || (
+        candidate.source !== undefined
+        && candidate.source !== "framed"
+        && candidate.source !== "camera-fallback"
+      )
+      || (
+        candidate.frameKey !== undefined
+        && typeof candidate.frameKey !== "string"
+      )
+    ) {
+      return null;
+    }
+    photos.push({
+      key: candidate.key,
+      url: candidate.url,
+      uploadedAt: candidate.uploadedAt,
+      capturedAt: candidate.capturedAt,
+      ...(candidate.source ? { source: candidate.source } : {}),
+      ...(candidate.frameKey ? { frameKey: candidate.frameKey } : {}),
+    });
+  }
+  return { photos, nextCursor: value.nextCursor };
+}
+
+export class ModerationPageCoordinator {
+  private sequence = 0;
+  private active = 0;
+
+  begin(
+    event: string,
+    auth: string,
+    filters: ModerationFilters
+  ): ModerationPageTicket {
+    const ticket = {
+      id: ++this.sequence,
+      event,
+      auth,
+      filters: { ...filters },
+    };
+    this.active = ticket.id;
+    return ticket;
+  }
+
+  accepts(ticket: ModerationPageTicket): boolean {
+    return ticket.id === this.active;
+  }
+
+  reset(): void {
+    this.active = 0;
+  }
+
+  merge(
+    ticket: ModerationPageTicket,
+    current: readonly ModerationPhoto[],
+    currentCursor: string | null,
+    incoming: readonly ModerationPhoto[],
+    nextCursor: string | null
+  ): { photos: ModerationPhoto[]; nextCursor: string | null } | null {
+    void currentCursor;
+    if (!this.accepts(ticket)) return null;
+    return {
+      photos: mergeModerationPage(current, incoming),
+      nextCursor,
+    };
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length
+    && actual.every((key, index) => key === expected[index]);
+}
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index 8b273c0..0cf23cf 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -5,7 +5,13 @@ import { useParams } from "next/navigation";
 import QRCode from "qrcode";
 import { TEMPLATES } from "../../templates";
 import type { ConfigRevision, PublicEventConfig } from "../../event-config";
-import type { SupportedLocale } from "../../i18n/catalog";
+import { message, type SupportedLocale } from "../../i18n/catalog";
+import {
+  deviceLocaleStorageKey,
+  DocumentLocaleLease,
+  resolveDeviceLocale,
+} from "../../i18n/locale";
+import type { ModerationPhoto } from "../../moderation";
 import type { AdminBoothRecord, BoothOperationalState } from "../../booth-control";
 import {
   BoothKeyControls,
@@ -23,6 +29,19 @@ import {
 import { BoothOperationsPanel } from "./booth-operations-panel";
 import { ConfigHistoryPanel } from "./config-history-panel";
 import { ExportPanel } from "./export-panel";
+import { ModerationDialog } from "./moderation-dialog";
+import {
+  ModerationPanel,
+  type ModerationRebuildState,
+} from "./moderation-panel";
+import {
+  mergeModerationPage,
+  moderationFilterInstant,
+  ModerationPageCoordinator,
+  parseModerationPageResponse,
+  removeModeratedPhoto,
+  type ModerationFilters,
+} from "./moderation-state";
 import {
   buildConfigSaveBody,
   clearRestoreRequestAfterReconciliation,
@@ -36,7 +55,6 @@ import {
 } from "./config-mutation";
 import styles from "./admin.module.css";
 
-type Photo = { key: string; url: string; uploadedAt: string };
 type AuthState = "missing" | "ready" | "invalid";
 type Probe = { status: "up" | "degraded" | "down"; detail: string };
 type Health = { upload: Probe; live: Probe };
@@ -49,6 +67,7 @@ export default function Admin() {
   const [frames, setFrames] = useState<Set<string>>(new Set());
   const [locales, setLocales] = useState<Set<SupportedLocale>>(new Set(["en"]));
   const [defaultLocale, setDefaultLocale] = useState<SupportedLocale>("en");
+  const [uiLocale, setUiLocale] = useState<SupportedLocale>("en");
   const [timeZone, setTimeZone] = useState<string | undefined>();
   const [reviewEnabled, setReviewEnabled] = useState(true);
   const [autoAcceptSeconds, setAutoAcceptSeconds] = useState(5);
@@ -62,12 +81,23 @@ export default function Admin() {
   const [hasBoothKey, setHasBoothKey] = useState(false);
   const [boothKey, setBoothKey] = useState("");
   const [boothKeySaved, setBoothKeySaved] = useState(false);
-  const [photos, setPhotos] = useState<Photo[]>([]);
+  const [photos, setPhotos] = useState<ModerationPhoto[]>([]);
   const [photosLoaded, setPhotosLoaded] = useState(false);
   const [photosError, setPhotosError] = useState("");
+  const [photosLoading, setPhotosLoading] = useState(false);
+  const [photosLoadingMore, setPhotosLoadingMore] = useState(false);
+  const [photoCursor, setPhotoCursor] = useState<string | null>(null);
+  const [draftFilters, setDraftFilters] = useState<ModerationFilters>({ from: "", to: "" });
+  const [appliedFilters, setAppliedFilters] = useState<ModerationFilters>({ from: "", to: "" });
+  const [moderationNotice, setModerationNotice] = useState("");
+  const [moderationRebuild, setModerationRebuild] = useState<ModerationRebuildState | null>(null);
+  const [rebuildingModeration, setRebuildingModeration] = useState(false);
+  const [selectedPhoto, setSelectedPhoto] = useState<ModerationPhoto | null>(null);
+  const [dialogTrigger, setDialogTrigger] = useState<HTMLElement | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [cleanupPending, setCleanupPending] = useState(false);
+  const [deleting, setDeleting] = useState(false);
   const [saving, setSaving] = useState(false);
-  const [deleting, setDeleting] = useState("");
-  const [confirmDelete, setConfirmDelete] = useState("");
   const [notice, setNotice] = useState("");
   const [error, setError] = useState("");
   const [origin, setOrigin] = useState("");
@@ -84,7 +114,10 @@ export default function Admin() {
   const [boothMutationBusy, setBoothMutationBusy] = useState(false);
   const [boothStatusError, setBoothStatusError] = useState(false);
   const [boothMessageDraft, setBoothMessageDraft] = useState("");
-  const photoCursor = useRef<string | null>(null);
+  const moderationCoordinator = useRef(new ModerationPageCoordinator());
+  const moderationHeading = useRef<HTMLHeadingElement>(null);
+  const moderationPhotoRefs = useRef(new Map<string, HTMLButtonElement>());
+  const documentLocale = useRef<DocumentLocaleLease | null>(null);
   const boothCoordinator = useRef(new BoothOperationsCoordinator());
   const boothMessageEditing = useRef(false);
   const configMutationBusy = useRef(false);
@@ -124,13 +157,22 @@ export default function Admin() {
 
   useEffect(() => {
     setOrigin(window.location.origin);
+    documentLocale.current = new DocumentLocaleLease(document.documentElement);
     const stored = sessionStorage.getItem("adminKey") || "";
     if (stored) {
       setAdminKey(stored);
       setAuth("ready");
     }
+    return () => {
+      documentLocale.current?.restore();
+      documentLocale.current = null;
+    };
   }, []);
 
+  useEffect(() => {
+    documentLocale.current?.apply(event, uiLocale);
+  }, [event, uiLocale]);
+
   useEffect(() => {
     if (!origin) return;
     void QRCode.toDataURL(boothUrl, { width: 240, margin: 1 }).then(setBoothQr).catch(() => setBoothQr(""));
@@ -159,6 +201,13 @@ export default function Admin() {
       setFrames(new Set(rebased.frames));
       setLocales(new Set(rebased.locales));
       setDefaultLocale(rebased.defaultLocale);
+      setUiLocale(resolveDeviceLocale({
+        event,
+        configured: rebased.locales,
+        defaultLocale: rebased.defaultLocale,
+        storedLocale: localStorage.getItem(deviceLocaleStorageKey(event)),
+        navigatorLanguages: navigator.languages,
+      }));
       setTimeZone(rebased.timeZone);
       setReviewEnabled(rebased.reviewEnabled);
       setAutoAcceptSeconds(rebased.autoAcceptSeconds);
@@ -175,27 +224,67 @@ export default function Admin() {
     }
   }, [adminKey, defaults, event]);
 
-  const loadPhotos = useCallback(async (reset = false) => {
+  const requestModerationPage = useCallback(async (input: {
+    reset: boolean;
+    filters: ModerationFilters;
+    cursor: string | null;
+    current: readonly ModerationPhoto[];
+  }) => {
+    const ticket = moderationCoordinator.current.begin(event, adminKey, input.filters);
+    input.reset ? setPhotosLoading(true) : setPhotosLoadingMore(true);
     setPhotosError("");
+    setModerationNotice("");
+    if (input.reset) {
+      setPhotos([]);
+      setPhotoCursor(null);
+      setPhotosLoaded(false);
+      setSelectedPhoto(null);
+      setConfirmDelete(false);
+      setCleanupPending(false);
+    }
     try {
+      const from = moderationFilterInstant(input.filters.from);
+      const to = moderationFilterInstant(input.filters.to);
+      if (
+        from === undefined
+        || to === undefined
+        || (from !== null && to !== null && Date.parse(from) > Date.parse(to))
+      ) {
+        throw new Error("Choose a valid time range.");
+      }
       const query = new URLSearchParams({ event });
-      if (!reset && photoCursor.current) query.set("after", photoCursor.current);
-      const response = await fetch(`/api/photos?${query}`, { cache: "no-store" });
-      if (!response.ok) throw new Error(`Photo feed returned ${response.status}`);
-      const data = await response.json();
-      if (!Array.isArray(data.photos)) throw new Error("Photo feed had an unexpected shape");
-      setPhotos((current) => {
-        if (reset || !photoCursor.current) return data.photos;
-        const incoming = data.photos as Photo[];
-        const keys = new Set(incoming.map((photo) => photo.key));
-        return [...incoming, ...current.filter((photo) => !keys.has(photo.key))];
+      if (!input.reset && input.cursor) query.set("cursor", input.cursor);
+      if (from !== null) query.set("from", from);
+      if (to !== null) query.set("to", to);
+      const response = await fetch(`/api/moderation/photos?${query}`, {
+        cache: "no-store",
+        headers: { "x-booth-key": adminKey },
       });
-      if (typeof data.cursor === "string" && data.cursor) photoCursor.current = data.cursor;
+      if (!moderationCoordinator.current.accepts(ticket)) return;
+      if (response.status === 401) {
+        invalidateAuth();
+        return;
+      }
+      if (!response.ok) throw new Error(`Moderation returned ${response.status}`);
+      const page = parseModerationPageResponse(await response.json());
+      if (!moderationCoordinator.current.accepts(ticket)) return;
+      if (!page) throw new Error("Moderation response had an unexpected shape");
+      setPhotos(input.reset
+        ? mergeModerationPage([], page.photos)
+        : mergeModerationPage(input.current, page.photos));
+      setPhotoCursor(page.nextCursor);
       setPhotosLoaded(true);
     } catch (cause) {
-      setPhotosError(cause instanceof Error ? cause.message : "Photos could not be loaded");
+      if (!moderationCoordinator.current.accepts(ticket)) return;
+      setPhotosError(cause instanceof Error
+        ? cause.message
+        : message(uiLocale, "moderationError"));
+    } finally {
+      if (moderationCoordinator.current.accepts(ticket)) {
+        input.reset ? setPhotosLoading(false) : setPhotosLoadingMore(false);
+      }
     }
-  }, [event]);
+  }, [adminKey, event, uiLocale]);
 
   const loadBoothStatus = useCallback(async () => {
     const coordinator = boothCoordinator.current;
@@ -386,11 +475,21 @@ export default function Admin() {
   }, [adminKey, boothMessageDraft, boothOperationalState, event]);
 
   useEffect(() => {
-    photoCursor.current = null;
-    void loadPhotos(true);
-    const poll = window.setInterval(() => void loadPhotos(), 5000);
-    return () => window.clearInterval(poll);
-  }, [loadPhotos]);
+    moderationCoordinator.current.reset();
+    if (auth !== "ready" || !adminKey) {
+      setPhotos([]);
+      setPhotoCursor(null);
+      setPhotosLoaded(false);
+      return;
+    }
+    void requestModerationPage({
+      reset: true,
+      filters: appliedFilters,
+      cursor: null,
+      current: [],
+    });
+    return () => moderationCoordinator.current.reset();
+  }, [adminKey, appliedFilters, auth, event, requestModerationPage]);
 
   useEffect(() => {
     if (auth !== "ready" || !adminKey) return;
@@ -649,30 +748,112 @@ export default function Admin() {
     }
   };
 
-  const deletePhoto = async (photo: Photo) => {
-    setDeleting(photo.key); setError("");
+  const deletePhoto = async (photo: ModerationPhoto) => {
+    setDeleting(true);
+    setPhotosError("");
     try {
       const response = await fetch(`/api/photos?event=${encodeURIComponent(event)}&key=${encodeURIComponent(photo.key)}`, {
         method: "DELETE", headers: { "x-booth-key": adminKey },
       });
-      if (response.status === 401) { invalidateAuth(); throw new Error("That admin key was rejected."); }
+      if (response.status === 401) {
+        invalidateAuth();
+        return;
+      }
       if (!response.ok) throw new Error(`Delete failed (${response.status})`);
-      setPhotos((current) => current.filter((item) => item.key !== photo.key));
-      setConfirmDelete("");
-      setNotice("Photo removed from the event.");
+      const value: unknown = await response.json();
+      if (
+        !value
+        || typeof value !== "object"
+        || (value as { deleted?: unknown }).deleted !== true
+        || (value as { key?: unknown }).key !== photo.key
+        || typeof (value as { cleanupPending?: unknown }).cleanupPending !== "boolean"
+      ) {
+        throw new Error("Delete response had an unexpected shape");
+      }
+      const pending = (value as { cleanupPending: boolean }).cleanupPending;
+      const removal = removeModeratedPhoto(photos, photo.key);
+      setPhotos(removal.photos);
+      setConfirmDelete(false);
+      setModerationNotice(message(uiLocale, "moderationDeleted"));
+      setCleanupPending(pending);
+      setDialogTrigger(null);
+      if (!pending) setSelectedPhoto(null);
+      window.setTimeout(() => {
+        if (removal.nextFocusKey) {
+          moderationPhotoRefs.current.get(removal.nextFocusKey)?.focus();
+        } else {
+          moderationHeading.current?.focus();
+        }
+      }, 0);
     } catch (cause) {
-      setError(cause instanceof Error ? cause.message : "Photo could not be deleted");
-    } finally { setDeleting(""); }
+      setPhotosError(cause instanceof Error
+        ? cause.message
+        : message(uiLocale, "moderationDeleteError"));
+    } finally {
+      setDeleting(false);
+    }
+  };
+
+  const rebuildModerationIndex = async () => {
+    setRebuildingModeration(true);
+    setPhotosError("");
+    try {
+      const response = await fetch(
+        `/api/moderation/photos/rebuild?event=${encodeURIComponent(event)}`,
+        {
+          method: "POST",
+          cache: "no-store",
+          headers: { "x-booth-key": adminKey },
+        }
+      );
+      if (response.status === 401) {
+        invalidateAuth();
+        return;
+      }
+      if (!response.ok && response.status !== 202) {
+        throw new Error(`Index rebuild returned ${response.status}`);
+      }
+      const value: unknown = await response.json();
+      if (
+        !value
+        || typeof value !== "object"
+        || typeof (value as { complete?: unknown }).complete !== "boolean"
+        || typeof (value as { scanned?: unknown }).scanned !== "number"
+        || typeof (value as { indexed?: unknown }).indexed !== "number"
+      ) {
+        throw new Error("Index rebuild response had an unexpected shape");
+      }
+      setModerationRebuild({
+        complete: (value as { complete: boolean }).complete,
+        scanned: (value as { scanned: number }).scanned,
+        indexed: (value as { indexed: number }).indexed,
+      });
+      await requestModerationPage({
+        reset: true,
+        filters: appliedFilters,
+        cursor: null,
+        current: [],
+      });
+    } catch (cause) {
+      setPhotosError(cause instanceof Error
+        ? cause.message
+        : message(uiLocale, "moderationError"));
+    } finally {
+      setRebuildingModeration(false);
+    }
   };
 
   const facts: { label: string; value: string; tone: "good" | "bad" | "wait"; detail?: string }[] = [
     { label: "Config", value: configLoaded ? "Loaded" : configError ? "Error" : "Checking", tone: configLoaded ? "good" : configError ? "bad" : "wait" },
     { label: "Frames", value: `${frames.size} enabled`, tone: frames.size > 0 ? "good" : "bad" },
     { label: "Booth key", value: hasBoothKey ? "Installed" : "Missing", tone: hasBoothKey ? "good" : "bad" },
-    { label: "Photos", value: photosLoaded ? `${photos.length} live` : photosError ? "Error" : "Checking", tone: photosLoaded ? "good" : photosError ? "bad" : "wait" },
+    { label: "Photos", value: photosLoaded ? `${photos.length} loaded` : photosError ? "Error" : "Checking", tone: photosLoaded ? "good" : photosError ? "bad" : "wait" },
     { label: "Upload", value: health ? health.upload.status : "Unchecked", tone: health ? health.upload.status === "up" ? "good" : health.upload.status === "degraded" ? "wait" : "bad" : "wait", detail: health?.upload.detail },
     { label: "Live", value: health ? health.live.status : "Unchecked", tone: health ? health.live.status === "up" ? "good" : health.live.status === "degraded" ? "wait" : "bad" : "wait", detail: health?.live.detail },
   ];
+  const selectedIndex = selectedPhoto
+    ? photos.findIndex((photo) => photo.key === selectedPhoto.key)
+    : -1;
 
   if (auth !== "ready") {
     return (
@@ -786,16 +967,62 @@ export default function Admin() {
             onResume={() => void updateBoothOperationalState(false)}
           />
 
-          <section className={styles.section}>
-            <div className={styles.sectionHead}><div><span>04</span><h2>Recent contact sheet</h2></div><p>{photos.length} photograph{photos.length === 1 ? "" : "s"} currently in this event.</p></div>
-            {photosError && photos.length === 0 ? <div className={styles.failure}><strong>Photo feed unavailable</strong><p>{photosError}</p><button onClick={() => void loadPhotos(true)}>Retry photos</button></div> : photosLoaded && photos.length === 0 ?
-              <div className={styles.emptySheet}><strong>No exposures yet.</strong><p>Open the booth link and take a test photo before doors open.</p></div> :
-              <div className={styles.contactSheet}>{photos.slice(0, 16).map((photo) => <article key={photo.key} className={styles.contactPhoto}>
-                <img src={photo.url} alt={`Event photograph uploaded ${new Date(photo.uploadedAt).toLocaleString()}`} />
-                <div><time>{new Date(photo.uploadedAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time><code title={photo.key}>{photo.key.split("/").pop()}</code></div>
-                {confirmDelete === photo.key ? <div className={styles.deleteConfirm}><span>Delete exactly this photo?</span><button onClick={() => void deletePhoto(photo)} disabled={deleting === photo.key}>{deleting === photo.key ? "Removing…" : "Yes, remove"}</button><button onClick={() => setConfirmDelete("")}>Keep</button></div> : <button className={styles.removePhoto} onClick={() => setConfirmDelete(photo.key)}>Remove</button>}
-              </article>)}</div>}
-          </section>
+          <ModerationPanel
+            locale={uiLocale}
+            photos={photos}
+            filters={draftFilters}
+            nextCursor={photoCursor}
+            loading={photosLoading}
+            loadingMore={photosLoadingMore}
+            error={photosError}
+            notice={moderationNotice}
+            rebuild={moderationRebuild}
+            rebuilding={rebuildingModeration}
+            timeZone={timeZone}
+            headingRef={moderationHeading}
+            photoRefs={moderationPhotoRefs}
+            onFiltersChange={setDraftFilters}
+            onApplyFilters={() => {
+              if (
+                appliedFilters.from === draftFilters.from
+                && appliedFilters.to === draftFilters.to
+              ) {
+                void requestModerationPage({
+                  reset: true,
+                  filters: draftFilters,
+                  cursor: null,
+                  current: [],
+                });
+              } else {
+                setAppliedFilters({ ...draftFilters });
+              }
+            }}
+            onClearFilters={() => {
+              const clear = { from: "", to: "" };
+              setDraftFilters(clear);
+              if (appliedFilters.from || appliedFilters.to) setAppliedFilters(clear);
+              else void requestModerationPage({
+                reset: true,
+                filters: clear,
+                cursor: null,
+                current: [],
+              });
+            }}
+            onLoadMore={() => void requestModerationPage({
+              reset: false,
+              filters: appliedFilters,
+              cursor: photoCursor,
+              current: photos,
+            })}
+            onOpen={(photo, trigger) => {
+              setSelectedPhoto(photo);
+              setDialogTrigger(trigger);
+              setConfirmDelete(false);
+              setCleanupPending(false);
+              setPhotosError("");
+            }}
+            onRebuild={() => void rebuildModerationIndex()}
+          />
         </div>
 
         <aside className={styles.sideColumn}>
@@ -836,6 +1063,39 @@ export default function Admin() {
           />
         </aside>
       </div>
+      {selectedPhoto && (
+        <ModerationDialog
+          locale={uiLocale}
+          photo={selectedPhoto}
+          position={selectedIndex >= 0 ? selectedIndex + 1 : 1}
+          loadedCount={Math.max(photos.length, 1)}
+          hasPrevious={selectedIndex > 0}
+          hasNext={selectedIndex >= 0 && selectedIndex < photos.length - 1}
+          confirming={confirmDelete}
+          deleting={deleting}
+          cleanupPending={cleanupPending}
+          error={photosError}
+          timeZone={timeZone}
+          returnFocus={dialogTrigger}
+          onPrevious={() => {
+            if (selectedIndex > 0) setSelectedPhoto(photos[selectedIndex - 1]);
+          }}
+          onNext={() => {
+            if (selectedIndex >= 0 && selectedIndex < photos.length - 1) {
+              setSelectedPhoto(photos[selectedIndex + 1]);
+            }
+          }}
+          onClose={() => {
+            setSelectedPhoto(null);
+            setConfirmDelete(false);
+            setCleanupPending(false);
+            setPhotosError("");
+          }}
+          onRequestDelete={() => setConfirmDelete(true)}
+          onCancelDelete={() => setConfirmDelete(false)}
+          onConfirmDelete={() => void deletePhoto(selectedPhoto)}
+        />
+      )}
     </main>
   );
 }
diff --git a/app/i18n/catalog.test.ts b/app/i18n/catalog.test.ts
index 2779cc0..9a71a46 100644
--- a/app/i18n/catalog.test.ts
+++ b/app/i18n/catalog.test.ts
@@ -60,4 +60,11 @@ describe("guest message catalogs", () => {
     expect(localeDirection("en")).toBe("ltr");
     expect(localeDirection("zh-SG")).toBe("ltr");
   });
+
+  test("ships localized moderation copy with placeholder parity", () => {
+    expect(message("en", "moderationLoaded", { count: 12 })).toBe("12 photos loaded");
+    expect(message("zh-SG", "moderationLoaded", { count: 12 })).toContain("12");
+    expect(message("ar", "moderationOpenPhoto", { filename: "photo.jpg" }))
+      .toContain("photo.jpg");
+  });
 });
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
index 1398222..8263867 100644
--- a/app/i18n/catalog.ts
+++ b/app/i18n/catalog.ts
@@ -86,6 +86,44 @@ export const englishMessages = {
     "Export is temporarily unavailable. Your photos are unchanged; please retry.",
   exportGenericError:
     "The export could not be downloaded. Your photos are unchanged; please retry.",
+  moderationHeading: "Event moderation",
+  moderationIntro: "Review the full private photo index in reverse capture order.",
+  moderationFrom: "From",
+  moderationTo: "To",
+  moderationApply: "Apply filters",
+  moderationClear: "Clear filters",
+  moderationLoaded: "{count} photos loaded",
+  moderationOpenPhoto: "Open photo {filename}",
+  moderationPhotoAlt: "Event photo captured {date}",
+  moderationLoadMore: "Load more",
+  moderationLoadingMore: "Loading more…",
+  moderationLoading: "Loading moderation photos…",
+  moderationEmpty: "No photos match these filters.",
+  moderationError: "Moderation photos could not be loaded.",
+  moderationRetry: "Retry moderation",
+  moderationRebuildHeading: "Private index",
+  moderationRebuildIntro: "Rebuild missing entries in one bounded batch at a time.",
+  moderationRebuildStart: "Start rebuild",
+  moderationRebuildContinue: "Continue rebuild",
+  moderationRebuilding: "Rebuilding…",
+  moderationRebuildComplete: "Index rebuild complete.",
+  moderationRebuildProgress: "Scanned {scanned}; indexed {indexed}.",
+  moderationInspectTitle: "Inspect photo",
+  moderationPosition: "Photo {position} of {count} loaded",
+  moderationPrevious: "Previous",
+  moderationNext: "Next",
+  moderationClose: "Close",
+  moderationRemove: "Remove photo",
+  moderationConfirmTitle: "Delete exactly this photo?",
+  moderationConfirmBody: "This permanently removes {filename} from the public Event.",
+  moderationCompleteKey: "Complete object key",
+  moderationConfirmDelete: "Confirm exact deletion",
+  moderationCancel: "Cancel",
+  moderationRemoving: "Removing…",
+  moderationDeleted: "Photo deleted from the public Event.",
+  moderationCleanupPending:
+    "The public photo is already deleted. Private cleanup is pending; do not retry the public deletion.",
+  moderationDeleteError: "Photo could not be deleted.",
 } satisfies Record<string, string>;
 
 export type MessageKey = keyof typeof englishMessages;
@@ -165,6 +203,43 @@ export const chineseSingaporeMessages: Record<MessageKey, string> = {
   exportMetadataInvalid: "存储的照片元数据需要检查。仍可使用仅下载照片。",
   exportUnavailable: "导出暂时不可用。照片未被更改，请重试。",
   exportGenericError: "无法下载导出文件。照片未被更改，请重试。",
+  moderationHeading: "活动照片审核",
+  moderationIntro: "按拍摄时间倒序审核完整的私有照片索引。",
+  moderationFrom: "开始时间",
+  moderationTo: "结束时间",
+  moderationApply: "应用筛选条件",
+  moderationClear: "清除筛选条件",
+  moderationLoaded: "已载入 {count} 张",
+  moderationOpenPhoto: "打开照片 {filename}",
+  moderationPhotoAlt: "活动照片，拍摄于 {date}",
+  moderationLoadMore: "载入更多",
+  moderationLoadingMore: "正在载入更多…",
+  moderationLoading: "正在载入审核照片…",
+  moderationEmpty: "没有符合这些筛选条件的照片。",
+  moderationError: "无法载入审核照片。",
+  moderationRetry: "重试审核",
+  moderationRebuildHeading: "私有索引",
+  moderationRebuildIntro: "每次使用一个有界批次补建缺失项目。",
+  moderationRebuildStart: "开始重建",
+  moderationRebuildContinue: "继续重建",
+  moderationRebuilding: "正在重建…",
+  moderationRebuildComplete: "索引重建完成。",
+  moderationRebuildProgress: "已扫描 {scanned} 项；已编入索引 {indexed} 项。",
+  moderationInspectTitle: "检查照片",
+  moderationPosition: "已载入照片中的第 {position} 张，共 {count} 张",
+  moderationPrevious: "上一张",
+  moderationNext: "下一张",
+  moderationClose: "关闭",
+  moderationRemove: "移除照片",
+  moderationConfirmTitle: "确定删除这张照片？",
+  moderationConfirmBody: "这会从公开活动中永久移除 {filename}。",
+  moderationCompleteKey: "完整对象键",
+  moderationConfirmDelete: "确认精确删除",
+  moderationCancel: "取消",
+  moderationRemoving: "正在移除…",
+  moderationDeleted: "照片已从公开活动中删除。",
+  moderationCleanupPending: "公开照片已经删除。私有清理仍在进行；请勿再次删除公开照片。",
+  moderationDeleteError: "无法删除照片。",
 };
 
 export const arabicMessages: Record<MessageKey, string> = {
@@ -252,6 +327,44 @@ export const arabicMessages: Record<MessageKey, string> = {
     "التصدير غير متاح مؤقتًا. لم تتغير صورك؛ يرجى إعادة المحاولة.",
   exportGenericError:
     "تعذر تنزيل التصدير. لم تتغير صورك؛ يرجى إعادة المحاولة.",
+  moderationHeading: "إشراف صور الفعالية",
+  moderationIntro: "راجع فهرس الصور الخاص بالكامل بترتيب الالتقاط العكسي.",
+  moderationFrom: "من",
+  moderationTo: "إلى",
+  moderationApply: "طبّق عوامل التصفية",
+  moderationClear: "امسح عوامل التصفية",
+  moderationLoaded: "تم تحميل {count} صور",
+  moderationOpenPhoto: "افتح الصورة {filename}",
+  moderationPhotoAlt: "صورة فعالية التُقطت في {date}",
+  moderationLoadMore: "حمّل المزيد",
+  moderationLoadingMore: "جارٍ تحميل المزيد…",
+  moderationLoading: "جارٍ تحميل صور الإشراف…",
+  moderationEmpty: "لا توجد صور تطابق عوامل التصفية.",
+  moderationError: "تعذر تحميل صور الإشراف.",
+  moderationRetry: "أعد محاولة الإشراف",
+  moderationRebuildHeading: "الفهرس الخاص",
+  moderationRebuildIntro: "أعد بناء العناصر المفقودة على دفعات محدودة.",
+  moderationRebuildStart: "ابدأ إعادة البناء",
+  moderationRebuildContinue: "تابع إعادة البناء",
+  moderationRebuilding: "جارٍ إعادة البناء…",
+  moderationRebuildComplete: "اكتملت إعادة بناء الفهرس.",
+  moderationRebuildProgress: "تم فحص {scanned} وفهرسة {indexed}.",
+  moderationInspectTitle: "افحص الصورة",
+  moderationPosition: "الصورة {position} من أصل {count} محمّلة",
+  moderationPrevious: "السابقة",
+  moderationNext: "التالية",
+  moderationClose: "إغلاق",
+  moderationRemove: "احذف الصورة",
+  moderationConfirmTitle: "هل تريد حذف هذه الصورة تحديدًا؟",
+  moderationConfirmBody: "سيؤدي هذا إلى حذف {filename} نهائيًا من الفعالية العامة.",
+  moderationCompleteKey: "مفتاح العنصر الكامل",
+  moderationConfirmDelete: "أكّد الحذف الدقيق",
+  moderationCancel: "إلغاء",
+  moderationRemoving: "جارٍ الحذف…",
+  moderationDeleted: "حُذفت الصورة من الفعالية العامة.",
+  moderationCleanupPending:
+    "الصورة العامة محذوفة بالفعل. التنظيف الخاص معلّق؛ لا تعاود حذف الصورة العامة.",
+  moderationDeleteError: "تعذر حذف الصورة.",
 };
 
 const catalogs: Record<SupportedLocale, Record<MessageKey, string>> = {
diff --git a/app/i18n/locale.test.ts b/app/i18n/locale.test.ts
index 48da3da..327758c 100644
--- a/app/i18n/locale.test.ts
+++ b/app/i18n/locale.test.ts
@@ -6,6 +6,7 @@ import {
   resolveDeviceLocale,
   resolveEnabledLocales,
   saveDeviceLocale,
+  formatLocalizedDateTime,
 } from "./locale";
 
 describe("guest locale resolution", () => {
@@ -147,4 +148,11 @@ describe("guest locale resolution", () => {
     expect(lease.restore()).toBe(true);
     expect(root).toEqual({ lang: "fr", dir: "ltr" });
   });
+
+  test("formats operator timestamps with the selected locale and English fallback", () => {
+    const timestamp = "2026-07-24T00:00:00.000Z";
+    expect(formatLocalizedDateTime(timestamp, "zh-SG", "UTC")).toContain("2026");
+    expect(formatLocalizedDateTime(timestamp, "legacy", "UTC"))
+      .toBe(formatLocalizedDateTime(timestamp, "en", "UTC"));
+  });
 });
diff --git a/app/i18n/locale.ts b/app/i18n/locale.ts
index b2cda66..65b2118 100644
--- a/app/i18n/locale.ts
+++ b/app/i18n/locale.ts
@@ -86,6 +86,28 @@ export function applyDocumentLocale(
   documentElement.dir = localeDirection(locale);
 }
 
+export function formatLocalizedDateTime(
+  value: string | number,
+  locale: string,
+  timeZone?: string
+): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+  const supportedLocale = isSupportedLocale(locale) ? locale : "en";
+  try {
+    return new Intl.DateTimeFormat(supportedLocale, {
+      dateStyle: "medium",
+      timeStyle: "short",
+      ...(timeZone ? { timeZone } : {}),
+    }).format(date);
+  } catch {
+    return new Intl.DateTimeFormat("en", {
+      dateStyle: "medium",
+      timeStyle: "short",
+    }).format(date);
+  }
+}
+
 type DocumentLocaleRoot = Pick<HTMLElement, "lang" | "dir">;
 
 export class DocumentLocaleLease {

From 4341b66bc3e3bf751cc0d6b8afce9eb027c80873 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:54:16 +0800
Subject: [PATCH 095/105] feat: store private rehearsal evidence

---
 app/event-store.test.ts | 135 +++++++++++++++++++
 app/event-store.ts      | 284 ++++++++++++++++++++++++++++++++++++++++
 app/rehearsal.test.ts   |  95 ++++++++++++++
 app/rehearsal.ts        |  88 +++++++++----
 4 files changed, 574 insertions(+), 28 deletions(-)

diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index c39ea75..2e41e52 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -13,7 +13,10 @@ import {
   InvalidPhotoCursorError,
   InvalidStoredConfigRevisionError,
   InvalidStoredEventPresetError,
+  InvalidStoredRehearsalError,
   PresetConflictError,
+  RehearsalConflictError,
+  RehearsalNotFoundError,
   eventConfigKey,
   eventConfigMutationKey,
   eventConfigRevisionKey,
@@ -31,6 +34,10 @@ import {
   eventPresetKey,
   eventPresetIndexKey,
   eventPresetPrefix,
+  latestRehearsalKey,
+  rehearsalEvidenceKey,
+  rehearsalEvidencePrefix,
+  rehearsalSessionKey,
   type ListOptions,
   type ListResult,
   type StoredObjectBody,
@@ -494,6 +501,134 @@ describe("ObjectStore", () => {
   });
 });
 
+describe("private rehearsal storage", () => {
+  const rehearsalId = "018f0000-0000-4000-8000-000000000501";
+  const evidenceId = "018f0000-0000-4000-8000-000000000502";
+  const captureId = "018f0000-0000-4000-8000-000000000503";
+  const bootId = "018f0000-0000-4000-8000-000000000504";
+
+  test("snapshots the exact config head and frames, then completes a lost start retry", async () => {
+    const photos = new RecordingDeleteStore();
+    const state = new InMemoryObjectStore();
+    let now = new Date("2026-07-24T00:00:00.000Z");
+    const store = new EventStore(photos, state, "https://photos.example", () => now);
+    const config = await store.saveConfigRevision("launch", {
+      config: { frames: ["square", "strip"] },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-4000-8000-000000000510",
+    });
+
+    const started = await store.startRehearsal("launch", { rehearsalId });
+    now = new Date("2026-07-24T00:01:00.000Z");
+    await store.saveConfigRevision("launch", {
+      config: { frames: ["new-frame"] },
+      baseRevisionId: config.revision.id,
+      mutationId: "018f0000-0000-4000-8000-000000000511",
+    });
+    const retried = await store.startRehearsal("launch", { rehearsalId });
+
+    expect(started).toEqual({
+      version: 1,
+      id: rehearsalId,
+      startedAt: "2026-07-24T00:00:00.000Z",
+      configRevisionId: config.revision.id,
+      frames: ["square", "strip"],
+    });
+    expect(retried).toEqual(started);
+    expect(await store.readRehearsal("launch")).toEqual({
+      session: started,
+      evidence: [],
+    });
+    expect(state.has(rehearsalSessionKey("launch", rehearsalId))).toBeTrue();
+    expect(state.has(latestRehearsalKey("launch"))).toBeTrue();
+    expect((await photos.list()).objects).toHaveLength(0);
+    expect(photos.deletes).toEqual([]);
+  });
+
+  test("appends strict evidence with server time and exact idempotency", async () => {
+    const state = new CappedListStore(1);
+    let now = new Date("2026-07-24T00:00:00.000Z");
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example", () => now);
+    await store.startRehearsal("launch", { rehearsalId });
+    const input = {
+      version: 1 as const,
+      id: evidenceId,
+      rehearsalId,
+      observedAt: 1_753_315_200_000,
+      kind: "network-failure" as const,
+      captureId,
+      bootId,
+      errorClass: "network" as const,
+    };
+
+    const first = await store.appendRehearsalEvidence("launch", rehearsalId, input);
+    now = new Date("2026-07-24T00:05:00.000Z");
+    const retry = await store.appendRehearsalEvidence("launch", rehearsalId, input);
+
+    expect(first.idempotent).toBeFalse();
+    expect(first.evidence.recordedAt).toBe("2026-07-24T00:00:00.000Z");
+    expect(retry).toEqual({ evidence: first.evidence, idempotent: true });
+    expect(state.has(rehearsalEvidenceKey(
+      "launch",
+      rehearsalId,
+      input.observedAt,
+      evidenceId,
+    ))).toBeTrue();
+    expect((await store.readRehearsal("launch", rehearsalId)).evidence).toEqual([
+      first.evidence,
+    ]);
+
+    await expect(store.appendRehearsalEvidence("launch", rehearsalId, {
+      ...input,
+      errorClass: "timeout",
+    })).rejects.toBeInstanceOf(RehearsalConflictError);
+  });
+
+  test("isolates Events and fails explicitly for missing or corrupt private records", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
+    await store.startRehearsal("launch", { rehearsalId });
+    await expect(store.readRehearsal("other", rehearsalId))
+      .rejects.toBeInstanceOf(RehearsalNotFoundError);
+    await expect(store.appendRehearsalEvidence("other", rehearsalId, {
+      version: 1,
+      id: evidenceId,
+      rehearsalId,
+      observedAt: 1_753_315_200_000,
+      kind: "network-failure",
+      captureId,
+      bootId,
+      errorClass: "network",
+    })).rejects.toBeInstanceOf(RehearsalNotFoundError);
+    await expect(store.appendRehearsalEvidence("launch", rehearsalId, {
+      version: 1,
+      id: evidenceId,
+      rehearsalId,
+      observedAt: 1_753_315_200_000,
+      kind: "photo-deleted",
+      photoKey: "other/1753315200000-a.jpg",
+    })).rejects.toBeInstanceOf(TypeError);
+
+    state.set(rehearsalSessionKey("launch", rehearsalId), JSON.stringify({
+      version: 2,
+      id: rehearsalId,
+    }));
+    await expect(store.readRehearsal("launch", rehearsalId))
+      .rejects.toBeInstanceOf(InvalidStoredRehearsalError);
+  });
+
+  test("exposes only exact private key constructors and no cleanup method", () => {
+    expect(rehearsalSessionKey("launch", rehearsalId))
+      .toBe(`events/launch/rehearsals/${rehearsalId}/session.json`);
+    expect(rehearsalEvidencePrefix("launch", rehearsalId))
+      .toBe(`events/launch/rehearsals/${rehearsalId}/evidence/`);
+    expect(rehearsalEvidenceKey("launch", rehearsalId, 1_753_315_200_000, evidenceId))
+      .toBe(`events/launch/rehearsals/${rehearsalId}/evidence/1753315200000-${evidenceId}.json`);
+    expect(latestRehearsalKey("launch")).toBe("events/launch/rehearsals/latest.json");
+    expect("deleteRehearsal" in EventStore.prototype).toBeFalse();
+  });
+});
+
 describe("canonical event identity", () => {
   test("accepts canonical slugs and keeps the default event", () => {
     expect(canonicalEvent("launch-2026")).toBe("launch-2026");
diff --git a/app/event-store.ts b/app/event-store.ts
index d7f6ce4..af9c276 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -46,6 +46,14 @@ import {
   parseModerationPhotoRecord,
   type ModerationPhoto,
 } from "./moderation";
+import {
+  isRehearsalId,
+  parseRehearsalEvidence,
+  parseRehearsalSession,
+  type RehearsalEvidence,
+  type RehearsalEvidenceInput,
+  type RehearsalSession,
+} from "./rehearsal";
 export { canonicalEvent, InvalidEventSlugError, slugifyEvent };
 export { EVENT_CONFIG_VERSION };
 export type { EventConfig } from "./event-config";
@@ -310,6 +318,23 @@ export const eventPresetIndexKey = (
   }
   return `${eventPresetIndexPrefix()}${utf16Hex(label)}/${presetId}/${utf16Hex(updatedAt)}.json`;
 };
+export const rehearsalSessionKey = (event: string, rehearsalId: string) =>
+  `events/${canonicalEvent(event)}/rehearsals/${rehearsalId}/session.json`;
+export const rehearsalEvidencePrefix = (event: string, rehearsalId: string) =>
+  `events/${canonicalEvent(event)}/rehearsals/${rehearsalId}/evidence/`;
+export const rehearsalEvidenceKey = (
+  event: string,
+  rehearsalId: string,
+  observedAt: number,
+  evidenceId: string,
+) => `${rehearsalEvidencePrefix(event, rehearsalId)}${String(observedAt).padStart(13, "0")}-${evidenceId}.json`;
+export const latestRehearsalKey = (event: string) =>
+  `events/${canonicalEvent(event)}/rehearsals/latest.json`;
+const rehearsalEvidenceIdentityKey = (
+  event: string,
+  rehearsalId: string,
+  evidenceId: string,
+) => `events/${canonicalEvent(event)}/rehearsals/${rehearsalId}/evidence-identities/${evidenceId}.json`;
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
 export const stablePhotoKey = (event: string, id: StableCaptureIdentity) =>
@@ -491,6 +516,32 @@ export class EventPresetNotFoundError extends Error {
   }
 }
 
+export class RehearsalNotFoundError extends Error {
+  constructor(readonly event: string, readonly rehearsalId?: string) {
+    super(`rehearsal${rehearsalId ? ` ${rehearsalId}` : ""} was not found for ${event}`);
+  }
+}
+
+export class InvalidStoredRehearsalError extends Error {
+  constructor(readonly event: string, readonly rehearsalId?: string) {
+    super(`stored rehearsal${rehearsalId ? ` ${rehearsalId}` : ""} for ${event} is corrupt or uses an unsupported version`);
+  }
+}
+
+export class RehearsalConflictError extends Error {
+  constructor(readonly evidenceId?: string) {
+    super(evidenceId
+      ? `rehearsal evidence ${evidenceId} was already used for different evidence`
+      : "rehearsal already exists");
+  }
+}
+
+export class RehearsalEvidenceLimitError extends Error {
+  constructor() {
+    super("rehearsal evidence limit reached");
+  }
+}
+
 export class PhotoIndexWriteError extends Error {
   constructor(
     readonly photo: Pick<PutPhotoResult, "key" | "url" | "duplicate">,
@@ -847,6 +898,234 @@ export class EventStore {
     });
   }
 
+  async startRehearsal(
+    event: string,
+    input: { rehearsalId: string },
+  ): Promise<RehearsalSession> {
+    const canonical = canonicalEvent(event);
+    if (!isRehearsalId(input.rehearsalId)) {
+      throw new TypeError("invalid rehearsal ID");
+    }
+    const key = rehearsalSessionKey(canonical, input.rehearsalId);
+    const existing = await this.state.get(key);
+    let session: RehearsalSession;
+    if (existing) {
+      session = await this.readRehearsalSessionObject(canonical, input.rehearsalId, existing);
+    } else {
+      const config = await this.readConfig(canonical);
+      const candidate: RehearsalSession = {
+        version: 1,
+        id: input.rehearsalId,
+        startedAt: this.now().toISOString(),
+        configRevisionId: config?.currentRevisionId ?? null,
+        frames: [...(config?.frames ?? [])],
+      };
+      const created = await this.state.compareAndSwap(
+        key,
+        null,
+        JSON.stringify(candidate),
+        jsonWriteOptions(),
+      );
+      if (created) {
+        session = candidate;
+      } else {
+        const raced = await this.state.get(key);
+        if (!raced) throw new RehearsalConflictError();
+        session = await this.readRehearsalSessionObject(canonical, input.rehearsalId, raced);
+      }
+    }
+    await this.state.put(
+      latestRehearsalKey(canonical),
+      JSON.stringify({ version: 1, rehearsalId: session.id }),
+      jsonWriteOptions(),
+    );
+    return session;
+  }
+
+  async readRehearsal(
+    event: string,
+    rehearsalId?: string,
+  ): Promise<{ session: RehearsalSession; evidence: RehearsalEvidence[] }> {
+    const canonical = canonicalEvent(event);
+    let exactId = rehearsalId;
+    if (exactId === undefined) {
+      const pointer = await this.state.get(latestRehearsalKey(canonical));
+      if (!pointer) throw new RehearsalNotFoundError(canonical);
+      let value: unknown;
+      try {
+        value = await pointer.json<unknown>();
+      } catch {
+        throw new InvalidStoredRehearsalError(canonical);
+      }
+      if (
+        !isRecord(value)
+        || Object.keys(value).length !== 2
+        || value.version !== 1
+        || !isRehearsalId(value.rehearsalId)
+      ) {
+        throw new InvalidStoredRehearsalError(canonical);
+      }
+      exactId = value.rehearsalId;
+    }
+    if (!isRehearsalId(exactId)) throw new TypeError("invalid rehearsal ID");
+    const sessionObject = await this.state.get(rehearsalSessionKey(canonical, exactId));
+    if (!sessionObject) throw new RehearsalNotFoundError(canonical, exactId);
+    const session = await this.readRehearsalSessionObject(canonical, exactId, sessionObject);
+    const evidence: RehearsalEvidence[] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await this.state.list({
+        prefix: rehearsalEvidencePrefix(canonical, exactId),
+        ...(cursor ? { cursor } : {}),
+        limit: Math.min(PAGE_SIZE, 513 - evidence.length),
+      });
+      for (const listed of page.objects) {
+        if (evidence.length >= 512) throw new RehearsalEvidenceLimitError();
+        const object = await this.state.get(listed.key);
+        if (!object) throw new InvalidStoredRehearsalError(canonical, exactId);
+        let value: unknown;
+        try {
+          value = await object.json<unknown>();
+        } catch {
+          throw new InvalidStoredRehearsalError(canonical, exactId);
+        }
+        const parsed = parseRehearsalEvidence(value, canonical);
+        if (
+          !parsed
+          || parsed.rehearsalId !== exactId
+          || rehearsalEvidenceKey(canonical, exactId, parsed.observedAt, parsed.id) !== listed.key
+        ) {
+          throw new InvalidStoredRehearsalError(canonical, exactId);
+        }
+        evidence.push(parsed);
+      }
+      cursor = page.truncated ? page.cursor : undefined;
+      if (page.truncated && !cursor) throw new InvalidStoredRehearsalError(canonical, exactId);
+    } while (cursor);
+    evidence.sort((left, right) =>
+      left.recordedAt.localeCompare(right.recordedAt) || left.id.localeCompare(right.id)
+    );
+    return { session, evidence };
+  }
+
+  async appendRehearsalEvidence(
+    event: string,
+    rehearsalId: string,
+    input: RehearsalEvidenceInput,
+  ): Promise<{ evidence: RehearsalEvidence; idempotent: boolean }> {
+    const canonical = canonicalEvent(event);
+    if (!isRehearsalId(rehearsalId)) throw new TypeError("invalid rehearsal ID");
+    const record = parseRehearsalEvidence({
+      ...input,
+      recordedAt: this.now().toISOString(),
+    }, canonical);
+    if (!record || record.rehearsalId !== rehearsalId) {
+      throw new TypeError("invalid rehearsal evidence");
+    }
+    const key = rehearsalEvidenceKey(canonical, rehearsalId, record.observedAt, record.id);
+    const identityKey = rehearsalEvidenceIdentityKey(canonical, rehearsalId, record.id);
+    const semantic = rehearsalEvidenceSemantic(record);
+    const existingIdentity = await this.state.get(identityKey);
+    if (existingIdentity) {
+      return this.finishExistingRehearsalEvidence(
+        canonical,
+        rehearsalId,
+        record.id,
+        key,
+        semantic,
+        existingIdentity,
+      );
+    }
+    const current = await this.readRehearsal(canonical, rehearsalId);
+    if (current.evidence.length >= 512) throw new RehearsalEvidenceLimitError();
+    const claimed = await this.state.compareAndSwap(
+      identityKey,
+      null,
+      JSON.stringify({ version: 1, key, semantic }),
+      jsonWriteOptions(),
+    );
+    if (!claimed) {
+      const raced = await this.state.get(identityKey);
+      if (!raced) throw new RehearsalConflictError(record.id);
+      return this.finishExistingRehearsalEvidence(
+        canonical,
+        rehearsalId,
+        record.id,
+        key,
+        semantic,
+        raced,
+      );
+    }
+    const created = await this.state.compareAndSwap(
+      key,
+      null,
+      JSON.stringify(record),
+      jsonWriteOptions(),
+    );
+    if (!created) throw new RehearsalConflictError(record.id);
+    return { evidence: record, idempotent: false };
+  }
+
+  private async finishExistingRehearsalEvidence(
+    event: string,
+    rehearsalId: string,
+    evidenceId: string,
+    key: string,
+    semantic: string,
+    identity: StoredObjectBody,
+  ): Promise<{ evidence: RehearsalEvidence; idempotent: boolean }> {
+    let marker: unknown;
+    try {
+      marker = await identity.json<unknown>();
+    } catch {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    if (
+      !isRecord(marker)
+      || Object.keys(marker).length !== 3
+      || marker.version !== 1
+      || marker.key !== key
+      || marker.semantic !== semantic
+    ) {
+      throw new RehearsalConflictError(evidenceId);
+    }
+    const object = await this.state.get(key);
+    if (!object) throw new InvalidStoredRehearsalError(event, rehearsalId);
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    const evidence = parseRehearsalEvidence(value, event);
+    if (
+      !evidence
+      || evidence.rehearsalId !== rehearsalId
+      || rehearsalEvidenceSemantic(evidence) !== semantic
+    ) {
+      throw new RehearsalConflictError(evidenceId);
+    }
+    return { evidence, idempotent: true };
+  }
+
+  private async readRehearsalSessionObject(
+    event: string,
+    rehearsalId: string,
+    object: StoredObjectBody,
+  ): Promise<RehearsalSession> {
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    const session = parseRehearsalSession(value);
+    if (!session || session.id !== rehearsalId) {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    return session;
+  }
+
   private async appendConfigRevision(
     event: string,
     input: ConfigAppendInput
@@ -2227,6 +2506,11 @@ function memoryBytes(value: ArrayBuffer | ArrayBufferView | string): Uint8Array
   return new Uint8Array(value.slice(0));
 }
 
+function rehearsalEvidenceSemantic(evidence: RehearsalEvidence): string {
+  const { recordedAt: _recordedAt, ...semantic } = evidence;
+  return JSON.stringify(semantic);
+}
+
 function configExperience(config: EventConfig): EventExperience {
   const { boothKeyHash: _boothKeyHash, currentRevisionId: _currentRevisionId, ...experience } = config;
   return experience;
diff --git a/app/rehearsal.test.ts b/app/rehearsal.test.ts
index 729ed87..d2b4768 100644
--- a/app/rehearsal.test.ts
+++ b/app/rehearsal.test.ts
@@ -67,6 +67,28 @@ describe("rehearsal schemas", () => {
     expect(parseRehearsalEvidence({ ...valid, photoKey: "other/1753315200000-a.jpg" }, "launch")).toBeNull();
     expect(parseRehearsalEvidence({ ...valid, error: "private stack" }, "launch")).toBeNull();
   });
+
+  test("accepts deterministic server upload evidence IDs only for acknowledgements", () => {
+    const acknowledged = evidence(2, {
+      kind: "photo-acknowledged",
+      captureId: firstCapture,
+      capturedAt: 1_753_315_200_000,
+      photoKey: "launch/1753315200000-a.jpg",
+    });
+    expect(parseRehearsalEvidence({
+      ...acknowledged,
+      id: `upload-${firstCapture}`,
+    }, "launch")).not.toBeNull();
+    expect(parseRehearsalEvidence({
+      ...evidence(3, {
+        kind: "network-failure",
+        captureId: firstCapture,
+        bootId: firstBoot,
+        errorClass: "network",
+      }),
+      id: `upload-${firstCapture}`,
+    }, "launch")).toBeNull();
+  });
 });
 
 describe("rehearsal completion", () => {
@@ -171,4 +193,77 @@ describe("rehearsal completion", () => {
     expect(summary.stale).toBeTrue();
     expect(summary.remainingExactKeys).toEqual(["launch/1753315200000-a.jpg"]);
   });
+
+  test("requires each correlated proof to be recorded after its prerequisites", () => {
+    const key = "launch/1753315200000-a.jpg";
+    const summary = reduceRehearsal({
+      session,
+      evidence: [
+        evidence(1, {
+          kind: "outbox-recovered",
+          previousBootId: firstBoot,
+          bootId: secondBoot,
+          captureIds: [firstCapture, secondCapture],
+        }),
+        evidence(2, { kind: "ordered-drain", bootId: secondBoot, captureIds: [firstCapture, secondCapture] }),
+        evidence(3, { kind: "delivery-observed", photoKey: key, feedObserved: true, publicImageObserved: true }),
+        evidence(4, { kind: "canary-deleted", photoKey: key, cleanupPending: true }),
+        evidence(5, { kind: "network-failure", captureId: firstCapture, bootId: firstBoot, errorClass: "network" }),
+        evidence(6, { kind: "network-failure", captureId: secondCapture, bootId: firstBoot, errorClass: "timeout" }),
+        evidence(7, {
+          kind: "photo-acknowledged",
+          captureId: firstCapture,
+          capturedAt: 1_753_315_200_000,
+          frameKey: "square",
+          photoKey: key,
+        }),
+        evidence(8, {
+          kind: "photo-acknowledged",
+          captureId: secondCapture,
+          capturedAt: 1_753_315_200_001,
+          frameKey: "strip",
+          photoKey: "launch/1753315200001-b.jpg",
+        }),
+        evidence(9, { kind: "canary-designated", photoKey: key }),
+      ],
+      currentRevisionId: revisionId,
+    });
+
+    expect(summary.requirements["two-network-failures"].complete).toBeTrue();
+    expect(summary.requirements["reload-recovered"].complete).toBeFalse();
+    expect(summary.requirements["ordered-drain"].complete).toBeFalse();
+    expect(summary.requirements["public-delivery"].complete).toBeFalse();
+    expect(summary.requirements["canary-deleted"].complete).toBeFalse();
+  });
+
+  test("uses the latest server-recorded exact disposition for conflicting choices", () => {
+    const key = "launch/1753315200000-a.jpg";
+    const base = evidence(1, {
+      kind: "photo-acknowledged",
+      captureId: firstCapture,
+      capturedAt: 1_753_315_200_000,
+      photoKey: key,
+    });
+    const deletedLatest = reduceRehearsal({
+      session,
+      evidence: [
+        base,
+        evidence(2, { kind: "photo-retained", photoKey: key }),
+        evidence(3, { kind: "photo-deleted", photoKey: key }),
+      ],
+      currentRevisionId: revisionId,
+    });
+    const retainedLatest = reduceRehearsal({
+      session,
+      evidence: [
+        base,
+        evidence(2, { kind: "photo-deleted", photoKey: key }),
+        evidence(3, { kind: "photo-retained", photoKey: key }),
+      ],
+      currentRevisionId: revisionId,
+    });
+
+    expect(deletedLatest.trackedPhotos[0]?.disposition).toBe("deleted");
+    expect(retainedLatest.trackedPhotos[0]?.disposition).toBe("retained");
+  });
 });
diff --git a/app/rehearsal.ts b/app/rehearsal.ts
index 6bff4ea..3aee0ff 100644
--- a/app/rehearsal.ts
+++ b/app/rehearsal.ts
@@ -157,6 +157,10 @@ function isUuid(value: unknown): value is string {
   return typeof value === "string" && UUID_V4.test(value);
 }
 
+export function isRehearsalId(value: unknown): value is string {
+  return isUuid(value);
+}
+
 function isTimestamp(value: unknown): value is number {
   return typeof value === "number"
     && Number.isSafeInteger(value)
@@ -237,7 +241,15 @@ export function parseRehearsalEvidence(
   const common = ["version", "id", "rehearsalId", "observedAt", "recordedAt", "kind"];
   if (
     value.version !== 1
-    || !isUuid(value.id)
+    || (
+      !isUuid(value.id)
+      && !(
+        value.kind === "photo-acknowledged"
+        && typeof value.id === "string"
+        && value.id.startsWith("upload-")
+        && isUuid(value.id.slice("upload-".length))
+      )
+    )
     || !isUuid(value.rehearsalId)
     || !isTimestamp(value.observedAt)
     || !isStoredInstant(value.recordedAt)
@@ -354,14 +366,16 @@ function sameOrder(left: readonly string[], right: readonly string[]): boolean {
   return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 
+function evidenceOrder(left: RehearsalEvidence, right: RehearsalEvidence): number {
+  return left.recordedAt.localeCompare(right.recordedAt) || left.id.localeCompare(right.id);
+}
+
 export function reduceRehearsal(input: {
   session: RehearsalSession;
   evidence: readonly RehearsalEvidence[];
   currentRevisionId: string | null;
 }): RehearsalSummary {
-  const records = [...input.evidence].sort((left, right) =>
-    left.recordedAt.localeCompare(right.recordedAt) || left.id.localeCompare(right.id)
-  );
+  const records = [...input.evidence].sort(evidenceOrder);
   const requirements = Object.fromEntries(REQUIREMENTS.map((requirement) => [
     requirement,
     { complete: false, evidenceIds: [] as string[] },
@@ -422,18 +436,25 @@ export function reduceRehearsal(input: {
     (record): record is Extract<RehearsalEvidence, { kind: "outbox-recovered" }> =>
       record.kind === "outbox-recovered",
   );
-  const validRecovery = recovered.find((record) =>
-    distinctFailures.length >= 2
-    && distinctFailures.every((failure) =>
-      record.captureIds.includes(failure.captureId)
-      && record.bootId !== failure.bootId
-    )
-  );
+  let recoveryFailures: typeof failures = [];
+  const validRecovery = recovered.find((record) => {
+    const correlated = record.captureIds
+      .map((captureId) => failuresByCapture.get(captureId))
+      .filter((failure): failure is typeof failures[number] => Boolean(failure));
+    const valid = correlated.length >= 2
+      && correlated.every((failure) =>
+        failure.bootId === record.previousBootId
+        && record.bootId !== record.previousBootId
+        && evidenceOrder(failure, record) < 0
+      );
+    if (valid) recoveryFailures = correlated;
+    return valid;
+  });
   if (validRecovery) {
     requirements["reload-recovered"] = {
       complete: true,
       evidenceIds: [
-        ...distinctFailures.map(({ id }) => id),
+        ...recoveryFailures.map(({ id }) => id),
         validRecovery.id,
       ],
     };
@@ -446,7 +467,11 @@ export function reduceRehearsal(input: {
   const validDrain = validRecovery && drains.find((record) =>
     record.bootId === validRecovery.bootId
     && sameOrder(record.captureIds, validRecovery.captureIds)
-    && record.captureIds.every((captureId) => acknowledgementsByCapture.has(captureId))
+    && evidenceOrder(validRecovery, record) < 0
+    && record.captureIds.every((captureId) => {
+      const acknowledged = acknowledgementsByCapture.get(captureId);
+      return acknowledged !== undefined && evidenceOrder(acknowledged, record) < 0;
+    })
   );
   if (validRecovery && validDrain) {
     requirements["ordered-drain"] = {
@@ -461,7 +486,11 @@ export function reduceRehearsal(input: {
 
   const delivery = records.find(
     (record): record is Extract<RehearsalEvidence, { kind: "delivery-observed" }> =>
-      record.kind === "delivery-observed" && acknowledgementsByKey.has(record.photoKey),
+      record.kind === "delivery-observed"
+      && (
+        acknowledgementsByKey.has(record.photoKey)
+        && evidenceOrder(acknowledgementsByKey.get(record.photoKey)!, record) < 0
+      ),
   );
   if (delivery) {
     requirements["public-delivery"] = {
@@ -472,15 +501,23 @@ export function reduceRehearsal(input: {
 
   const designations = records.filter(
     (record): record is Extract<RehearsalEvidence, { kind: "canary-designated" }> =>
-      record.kind === "canary-designated" && acknowledgementsByKey.has(record.photoKey),
+      record.kind === "canary-designated"
+      && acknowledgementsByKey.has(record.photoKey)
+      && evidenceOrder(acknowledgementsByKey.get(record.photoKey)!, record) < 0,
   );
   const deletedCanary = records.find(
     (record): record is Extract<RehearsalEvidence, { kind: "canary-deleted" }> =>
       record.kind === "canary-deleted"
-      && designations.some((designation) => designation.photoKey === record.photoKey),
+      && designations.some((designation) =>
+        designation.photoKey === record.photoKey
+        && evidenceOrder(designation, record) < 0
+      ),
   );
   if (deletedCanary) {
-    const designation = designations.find(({ photoKey }) => photoKey === deletedCanary.photoKey)!;
+    const designation = designations.find((candidate) =>
+      candidate.photoKey === deletedCanary.photoKey
+      && evidenceOrder(candidate, deletedCanary) < 0
+    )!;
     requirements["canary-deleted"] = {
       complete: true,
       evidenceIds: [
@@ -502,20 +539,15 @@ export function reduceRehearsal(input: {
     if (record.kind === "manual-check") manualChecks[record.check] = true;
   }
 
-  const retained = new Set(records.flatMap((record) =>
-    record.kind === "photo-retained" ? [record.photoKey] : []
-  ));
-  const deleted = new Set(records.flatMap((record) =>
-    record.kind === "photo-deleted" ? [record.photoKey] : []
-  ));
+  const dispositionByKey = new Map<string, "retained" | "deleted">();
+  for (const record of records) {
+    if (record.kind === "photo-retained") dispositionByKey.set(record.photoKey, "retained");
+    if (record.kind === "photo-deleted") dispositionByKey.set(record.photoKey, "deleted");
+  }
   const trackedPhotos = [...acknowledgementsByCapture.values()].map((record) => {
     const disposition = deletedCanary?.photoKey === record.photoKey
       ? "canary-deleted" as const
-      : retained.has(record.photoKey)
-        ? "retained" as const
-        : deleted.has(record.photoKey)
-          ? "deleted" as const
-          : "pending" as const;
+      : dispositionByKey.get(record.photoKey) ?? "pending" as const;
     return {
       captureId: record.captureId,
       ...(record.frameKey ? { frameKey: record.frameKey } : {}),

From 6902975f4574ec664a548ab203a04e5c4e118193 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:59:48 +0800
Subject: [PATCH 096/105] feat: track authenticated rehearsal uploads

---
 app/[event]/booth-session/upload.test.ts |   2 +
 app/[event]/booth-session/upload.ts      |   1 +
 app/api/rehearsals/evidence/route.ts     |  14 ++
 app/api/rehearsals/handlers.test.ts      | 245 ++++++++++++++++++++
 app/api/rehearsals/handlers.ts           | 276 +++++++++++++++++++++++
 app/api/rehearsals/join/route.ts         |  14 ++
 app/api/rehearsals/route.ts              |  22 ++
 app/api/upload/handlers.ts               |  31 +++
 app/api/upload/route.test.ts             |  63 ++++++
 app/event-store.test.ts                  |  65 ++++++
 app/event-store.ts                       |  60 ++++-
 app/upload-contract.test.ts              |   7 +
 app/upload-contract.ts                   |  15 +-
 13 files changed, 809 insertions(+), 6 deletions(-)
 create mode 100644 app/api/rehearsals/evidence/route.ts
 create mode 100644 app/api/rehearsals/handlers.test.ts
 create mode 100644 app/api/rehearsals/handlers.ts
 create mode 100644 app/api/rehearsals/join/route.ts
 create mode 100644 app/api/rehearsals/route.ts

diff --git a/app/[event]/booth-session/upload.test.ts b/app/[event]/booth-session/upload.test.ts
index a608dfc..e5e605b 100644
--- a/app/[event]/booth-session/upload.test.ts
+++ b/app/[event]/booth-session/upload.test.ts
@@ -31,12 +31,14 @@ describe("outboxUploadHeaders", () => {
         frameKey: "square",
         configRevisionId: "release_1",
       },
+      rehearsalId: "018f0000-0000-4000-8000-000000000501",
     })).toEqual({
       "x-capture-id": "018f0000-0000-4000-8000-000000000001",
       "x-captured-at": "1753315200999",
       "x-capture-source": "framed",
       "x-frame-key": "square",
       "x-config-revision-id": "release_1",
+      "x-rehearsal-id": "018f0000-0000-4000-8000-000000000501",
     });
   });
 
diff --git a/app/[event]/booth-session/upload.ts b/app/[event]/booth-session/upload.ts
index efb8c50..ae9f1ea 100644
--- a/app/[event]/booth-session/upload.ts
+++ b/app/[event]/booth-session/upload.ts
@@ -17,6 +17,7 @@ export function outboxUploadHeaders(item: OutboxItem): Record<string, string> {
     source: item.metadata?.source,
     frameKey: item.metadata?.frameKey,
     configRevisionId: item.metadata?.configRevisionId,
+    rehearsalId: item.rehearsalId,
   });
 
   try {
diff --git a/app/api/rehearsals/evidence/route.ts b/app/api/rehearsals/evidence/route.ts
new file mode 100644
index 0000000..147a6f0
--- /dev/null
+++ b/app/api/rehearsals/evidence/route.ts
@@ -0,0 +1,14 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { postRehearsalEvidence } from "../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return postRehearsalEvidence(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/rehearsals/handlers.test.ts b/app/api/rehearsals/handlers.test.ts
new file mode 100644
index 0000000..129e2de
--- /dev/null
+++ b/app/api/rehearsals/handlers.test.ts
@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test";
+import { NextRequest } from "next/server";
+import { EventStore, InMemoryObjectStore } from "@/app/event-store";
+import { hashBoothKey } from "@/app/upload-auth";
+import {
+  getRehearsal,
+  postRehearsal,
+  postRehearsalEvidence,
+  postRehearsalJoin,
+  type RehearsalHandlerDeps,
+} from "./handlers";
+
+const ADMIN_KEY = "admin-key";
+const BOOTH_KEY = "booth-key";
+const REHEARSAL_ID = "018f0000-0000-4000-8000-000000000501";
+const EVIDENCE_ID = "018f0000-0000-4000-8000-000000000502";
+const CAPTURE_ID = "018f0000-0000-4000-8000-000000000503";
+const BOOT_ID = "018f0000-0000-4000-8000-000000000504";
+
+function deps(options: { adminKey?: string } = { adminKey: ADMIN_KEY }): RehearsalHandlerDeps {
+  return {
+    store: new EventStore(
+      new InMemoryObjectStore(),
+      new InMemoryObjectStore(),
+      "https://photos.example",
+      () => new Date("2026-07-24T00:00:00.000Z"),
+    ),
+    adminKey: options.adminKey,
+  };
+}
+
+function request(
+  path: string,
+  options: {
+    method?: string;
+    key?: string;
+    body?: unknown;
+  } = {},
+): NextRequest {
+  return new NextRequest(`https://app.test${path}`, {
+    method: options.method ?? "GET",
+    headers: {
+      ...(options.key ? { "x-booth-key": options.key } : {}),
+      ...(options.body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+  });
+}
+
+const failureEvidence = {
+  version: 1 as const,
+  id: EVIDENCE_ID,
+  rehearsalId: REHEARSAL_ID,
+  observedAt: 1_753_315_200_000,
+  kind: "network-failure" as const,
+  captureId: CAPTURE_ID,
+  bootId: BOOT_ID,
+  errorClass: "network" as const,
+};
+
+describe("rehearsal handlers", () => {
+  test("starts and reads only with Admin auth, failing closed without its secret", async () => {
+    const context = deps();
+    const denied = await postRehearsal(request("/api/rehearsals?event=launch", {
+      method: "POST",
+      body: { rehearsalId: REHEARSAL_ID },
+    }), context);
+    expect(denied.status).toBe(401);
+
+    const started = await postRehearsal(request("/api/rehearsals?event=launch", {
+      method: "POST",
+      key: ADMIN_KEY,
+      body: { rehearsalId: REHEARSAL_ID },
+    }), context);
+    expect(started.status).toBe(200);
+    expect(started.headers.get("Cache-Control")).toBe("no-store");
+    expect(await started.json()).toMatchObject({
+      rehearsal: {
+        id: REHEARSAL_ID,
+        configRevisionId: null,
+        frames: [],
+      },
+      serverTime: "2026-07-24T00:00:00.000Z",
+    });
+
+    const read = await getRehearsal(request(
+      `/api/rehearsals?event=launch&id=${REHEARSAL_ID}`,
+      { key: ADMIN_KEY },
+    ), context);
+    expect(read.status).toBe(200);
+    expect(await read.json()).toMatchObject({
+      rehearsal: {
+        session: { id: REHEARSAL_ID },
+        evidence: [],
+        summary: { status: "active", stale: false },
+      },
+    });
+
+    const disabled = await postRehearsal(request("/api/rehearsals?event=launch", {
+      method: "POST",
+      key: ADMIN_KEY,
+      body: { rehearsalId: REHEARSAL_ID },
+    }), deps({ adminKey: undefined }));
+    expect(disabled.status).toBe(503);
+  });
+
+  test("rejects canonical aliases and missing sessions", async () => {
+    const context = deps();
+    const alias = await postRehearsal(request("/api/rehearsals?event=Launch", {
+      method: "POST",
+      key: ADMIN_KEY,
+      body: { rehearsalId: REHEARSAL_ID },
+    }), context);
+    expect(alias.status).toBe(400);
+
+    const missing = await getRehearsal(request(
+      `/api/rehearsals?event=launch&id=${REHEARSAL_ID}`,
+      { key: ADMIN_KEY },
+    ), context);
+    expect(missing.status).toBe(404);
+  });
+
+  test("returns an allowlisted stale Booth join for matching Booth or Admin auth", async () => {
+    const context = deps();
+    const first = await context.store.saveConfigRevision("launch", {
+      config: {
+        frames: ["square"],
+        boothKeyHash: await hashBoothKey(BOOTH_KEY),
+      },
+      baseRevisionId: null,
+      mutationId: "018f0000-0000-4000-8000-000000000510",
+      boothKeyMutationFingerprint: "a".repeat(64),
+    });
+    await context.store.startRehearsal("launch", { rehearsalId: REHEARSAL_ID });
+    await context.store.saveConfigRevision("launch", {
+      config: { frames: ["strip"] },
+      baseRevisionId: first.revision.id,
+      mutationId: "018f0000-0000-4000-8000-000000000511",
+    });
+
+    const joined = await postRehearsalJoin(request("/api/rehearsals/join?event=launch", {
+      method: "POST",
+      key: BOOTH_KEY,
+      body: { rehearsalId: REHEARSAL_ID },
+    }), context);
+    expect(joined.status).toBe(200);
+    const body = await joined.json();
+    expect(body).toEqual({
+      rehearsal: {
+        id: REHEARSAL_ID,
+        startedAt: "2026-07-24T00:00:00.000Z",
+        configRevisionId: first.revision.id,
+        frames: ["square"],
+        stale: true,
+      },
+      serverTime: "2026-07-24T00:00:00.000Z",
+    });
+    expect(JSON.stringify(body)).not.toContain("boothKey");
+    expect(JSON.stringify(body)).not.toContain("events/launch/rehearsals");
+  });
+
+  test("allows Booth operational evidence but reserves dispositions and manual checks for Admin", async () => {
+    const context = deps();
+    await context.store.writeConfig("launch", {
+      frames: ["square"],
+      boothKeyHash: await hashBoothKey(BOOTH_KEY),
+    });
+    await context.store.startRehearsal("launch", { rehearsalId: REHEARSAL_ID });
+
+    const boothRecord = await postRehearsalEvidence(request(
+      `/api/rehearsals/evidence?event=launch&id=${REHEARSAL_ID}`,
+      { method: "POST", key: BOOTH_KEY, body: failureEvidence },
+    ), context);
+    expect(boothRecord.status).toBe(200);
+
+    const denied = await postRehearsalEvidence(request(
+      `/api/rehearsals/evidence?event=launch&id=${REHEARSAL_ID}`,
+      {
+        method: "POST",
+        key: BOOTH_KEY,
+        body: {
+          version: 1,
+          id: "018f0000-0000-4000-8000-000000000505",
+          rehearsalId: REHEARSAL_ID,
+          observedAt: 1_753_315_200_001,
+          kind: "manual-check",
+          check: "power",
+        },
+      },
+    ), context);
+    expect(denied.status).toBe(403);
+
+    const admin = await postRehearsalEvidence(request(
+      `/api/rehearsals/evidence?event=launch&id=${REHEARSAL_ID}`,
+      {
+        method: "POST",
+        key: ADMIN_KEY,
+        body: {
+          version: 1,
+          id: "018f0000-0000-4000-8000-000000000505",
+          rehearsalId: REHEARSAL_ID,
+          observedAt: 1_753_315_200_001,
+          kind: "manual-check",
+          check: "power",
+        },
+      },
+    ), context);
+    expect(admin.status).toBe(200);
+  });
+
+  test("rejects expanded evidence before any append and never accepts client upload acknowledgements", async () => {
+    const context = deps();
+    await context.store.startRehearsal("launch", { rehearsalId: REHEARSAL_ID });
+    const expanded = await postRehearsalEvidence(request(
+      `/api/rehearsals/evidence?event=launch&id=${REHEARSAL_ID}`,
+      {
+        method: "POST",
+        key: ADMIN_KEY,
+        body: { ...failureEvidence, error: "private diagnostic" },
+      },
+    ), context);
+    expect(expanded.status).toBe(400);
+
+    const fakeAck = await postRehearsalEvidence(request(
+      `/api/rehearsals/evidence?event=launch&id=${REHEARSAL_ID}`,
+      {
+        method: "POST",
+        key: ADMIN_KEY,
+        body: {
+          version: 1,
+          id: `upload-${CAPTURE_ID}`,
+          rehearsalId: REHEARSAL_ID,
+          observedAt: 1_753_315_200_000,
+          kind: "photo-acknowledged",
+          captureId: CAPTURE_ID,
+          capturedAt: 1_753_315_200_000,
+          photoKey: `launch/1753315200000-${CAPTURE_ID}.jpg`,
+        },
+      },
+    ), context);
+    expect(fakeAck.status).toBe(400);
+    expect((await context.store.readRehearsal("launch", REHEARSAL_ID)).evidence)
+      .toEqual([]);
+  });
+});
diff --git a/app/api/rehearsals/handlers.ts b/app/api/rehearsals/handlers.ts
new file mode 100644
index 0000000..3f0d4cd
--- /dev/null
+++ b/app/api/rehearsals/handlers.ts
@@ -0,0 +1,276 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  canonicalEvent,
+  EventStore,
+  InvalidEventSlugError,
+  InvalidStoredRehearsalError,
+  RehearsalConflictError,
+  RehearsalEvidenceLimitError,
+  RehearsalNotFoundError,
+} from "@/app/event-store";
+import {
+  isRehearsalId,
+  parseRehearsalEvidence,
+  reduceRehearsal,
+  type RehearsalEvidence,
+  type RehearsalEvidenceInput,
+} from "@/app/rehearsal";
+import { adminOk, boothOrAdminOk } from "@/app/upload-auth";
+
+export type RehearsalHandlerDeps = {
+  store: EventStore;
+  adminKey?: string;
+};
+
+type Role = "admin" | "booth";
+
+const BOOTH_EVIDENCE = new Set<RehearsalEvidence["kind"]>([
+  "booth-ready",
+  "network-failure",
+  "outbox-recovered",
+  "ordered-drain",
+  "outbox-empty",
+]);
+
+const json = (body: unknown, init?: ResponseInit) =>
+  NextResponse.json(body, {
+    ...init,
+    headers: { ...init?.headers, "Cache-Control": "no-store" },
+  });
+
+const errorResponse = (error: string, status: number, headers?: HeadersInit) =>
+  json({ error }, { status, headers });
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactQuery(
+  req: NextRequest,
+  allowed: readonly string[],
+  required: readonly string[],
+): Record<string, string | undefined> | NextResponse {
+  const params = req.nextUrl.searchParams;
+  const allowedSet = new Set(allowed);
+  if (
+    Array.from(params.keys()).some((key) => !allowedSet.has(key))
+    || allowed.some((key) => params.getAll(key).length > 1)
+    || required.some((key) => params.getAll(key).length !== 1)
+  ) {
+    return errorResponse("invalid rehearsal query", 400);
+  }
+  return Object.fromEntries(allowed.map((key) => [key, params.get(key) ?? undefined]));
+}
+
+function eventFrom(value: string | undefined): string | NextResponse {
+  try {
+    return canonicalEvent(value ?? null);
+  } catch (error) {
+    if (error instanceof InvalidEventSlugError) return errorResponse(error.message, 400);
+    throw error;
+  }
+}
+
+function authorizeAdmin(
+  req: NextRequest,
+  deps: RehearsalHandlerDeps,
+): NextResponse | null {
+  if (!deps.adminKey) {
+    return errorResponse("rehearsals disabled: no key configured", 503);
+  }
+  return adminOk(req.headers.get("x-booth-key") ?? "", deps.adminKey) === "ok"
+    ? null
+    : errorResponse("unauthorized", 401);
+}
+
+async function authorizeBoothOrAdmin(
+  req: NextRequest,
+  event: string,
+  deps: RehearsalHandlerDeps,
+): Promise<Role | NextResponse> {
+  if (!deps.adminKey) {
+    return errorResponse("rehearsals disabled: no key configured", 503);
+  }
+  const provided = req.headers.get("x-booth-key") ?? "";
+  if (adminOk(provided, deps.adminKey) === "ok") return "admin";
+  const config = await deps.store.readConfig(event);
+  return await boothOrAdminOk(provided, deps.adminKey, config?.boothKeyHash) === "ok"
+    ? "booth"
+    : errorResponse("unauthorized", 401);
+}
+
+async function parsedBody(req: NextRequest): Promise<unknown> {
+  return req.json().catch(() => null);
+}
+
+function parseEvidenceInput(
+  value: unknown,
+  event: string,
+  rehearsalId: string,
+): RehearsalEvidenceInput | null {
+  if (!isRecord(value) || "recordedAt" in value) return null;
+  const parsed = parseRehearsalEvidence({
+    ...value,
+    recordedAt: "2000-01-01T00:00:00.000Z",
+  }, event);
+  if (
+    !parsed
+    || parsed.rehearsalId !== rehearsalId
+    || !isRehearsalId(parsed.id)
+    || parsed.kind === "photo-acknowledged"
+  ) {
+    return null;
+  }
+  const { recordedAt: _recordedAt, ...input } = parsed;
+  return input;
+}
+
+async function readSummary(deps: RehearsalHandlerDeps, event: string, id?: string) {
+  const rehearsal = await deps.store.readRehearsal(event, id);
+  const config = await deps.store.readConfig(event);
+  return {
+    ...rehearsal,
+    summary: reduceRehearsal({
+      ...rehearsal,
+      currentRevisionId: config?.currentRevisionId ?? null,
+    }),
+  };
+}
+
+function mapStoreError(error: unknown): NextResponse | null {
+  if (error instanceof RehearsalNotFoundError) {
+    return errorResponse("rehearsal not found", 404);
+  }
+  if (error instanceof RehearsalConflictError) {
+    return errorResponse("rehearsal evidence conflict", 409);
+  }
+  if (error instanceof RehearsalEvidenceLimitError) {
+    return errorResponse("rehearsal evidence limit reached", 409);
+  }
+  if (error instanceof InvalidStoredRehearsalError) {
+    return errorResponse("rehearsal unavailable", 503);
+  }
+  if (error instanceof TypeError) {
+    return errorResponse("invalid rehearsal request", 400);
+  }
+  return null;
+}
+
+export async function postRehearsal(
+  req: NextRequest,
+  deps: RehearsalHandlerDeps,
+): Promise<NextResponse> {
+  const query = exactQuery(req, ["event"], ["event"]);
+  if (query instanceof NextResponse) return query;
+  const event = eventFrom(query.event);
+  if (event instanceof NextResponse) return event;
+  const value = await parsedBody(req);
+  if (
+    !isRecord(value)
+    || Object.keys(value).length !== 1
+    || !isRehearsalId(value.rehearsalId)
+  ) {
+    return errorResponse("invalid rehearsal request", 400);
+  }
+  const rejected = authorizeAdmin(req, deps);
+  if (rejected) return rejected;
+  try {
+    const session = await deps.store.startRehearsal(event, {
+      rehearsalId: value.rehearsalId,
+    });
+    return json({ rehearsal: session, serverTime: deps.store.serverTime() });
+  } catch (error) {
+    const mapped = mapStoreError(error);
+    if (mapped) return mapped;
+    throw error;
+  }
+}
+
+export async function getRehearsal(
+  req: NextRequest,
+  deps: RehearsalHandlerDeps,
+): Promise<NextResponse> {
+  const query = exactQuery(req, ["event", "id"], ["event"]);
+  if (query instanceof NextResponse) return query;
+  const event = eventFrom(query.event);
+  if (event instanceof NextResponse) return event;
+  if (query.id !== undefined && !isRehearsalId(query.id)) {
+    return errorResponse("invalid rehearsal ID", 400);
+  }
+  const rejected = authorizeAdmin(req, deps);
+  if (rejected) return rejected;
+  try {
+    return json({
+      rehearsal: await readSummary(deps, event, query.id),
+      serverTime: deps.store.serverTime(),
+    });
+  } catch (error) {
+    const mapped = mapStoreError(error);
+    if (mapped) return mapped;
+    throw error;
+  }
+}
+
+export async function postRehearsalJoin(
+  req: NextRequest,
+  deps: RehearsalHandlerDeps,
+): Promise<NextResponse> {
+  const query = exactQuery(req, ["event"], ["event"]);
+  if (query instanceof NextResponse) return query;
+  const event = eventFrom(query.event);
+  if (event instanceof NextResponse) return event;
+  const value = await parsedBody(req);
+  if (
+    !isRecord(value)
+    || Object.keys(value).length !== 1
+    || !isRehearsalId(value.rehearsalId)
+  ) {
+    return errorResponse("invalid rehearsal join", 400);
+  }
+  const role = await authorizeBoothOrAdmin(req, event, deps);
+  if (role instanceof NextResponse) return role;
+  try {
+    const { session } = await deps.store.readRehearsal(event, value.rehearsalId);
+    const config = await deps.store.readConfig(event);
+    return json({
+      rehearsal: {
+        id: session.id,
+        startedAt: session.startedAt,
+        configRevisionId: session.configRevisionId,
+        frames: [...session.frames],
+        stale: session.configRevisionId !== (config?.currentRevisionId ?? null),
+      },
+      serverTime: deps.store.serverTime(),
+    });
+  } catch (error) {
+    const mapped = mapStoreError(error);
+    if (mapped) return mapped;
+    throw error;
+  }
+}
+
+export async function postRehearsalEvidence(
+  req: NextRequest,
+  deps: RehearsalHandlerDeps,
+): Promise<NextResponse> {
+  const query = exactQuery(req, ["event", "id"], ["event", "id"]);
+  if (query instanceof NextResponse) return query;
+  const event = eventFrom(query.event);
+  if (event instanceof NextResponse) return event;
+  if (!isRehearsalId(query.id)) return errorResponse("invalid rehearsal ID", 400);
+  const input = parseEvidenceInput(await parsedBody(req), event, query.id);
+  if (!input) return errorResponse("invalid rehearsal evidence", 400);
+  const role = await authorizeBoothOrAdmin(req, event, deps);
+  if (role instanceof NextResponse) return role;
+  if (role === "booth" && !BOOTH_EVIDENCE.has(input.kind)) {
+    return errorResponse("Admin authorization required", 403);
+  }
+  try {
+    const result = await deps.store.appendRehearsalEvidence(event, query.id, input);
+    return json({ ...result, serverTime: deps.store.serverTime() });
+  } catch (error) {
+    const mapped = mapStoreError(error);
+    if (mapped) return mapped;
+    throw error;
+  }
+}
diff --git a/app/api/rehearsals/join/route.ts b/app/api/rehearsals/join/route.ts
new file mode 100644
index 0000000..85ef941
--- /dev/null
+++ b/app/api/rehearsals/join/route.ts
@@ -0,0 +1,14 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { postRehearsalJoin } from "../handlers";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(req: NextRequest) {
+  const { env } = getCloudflareContext();
+  return postRehearsalJoin(req, {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  });
+}
diff --git a/app/api/rehearsals/route.ts b/app/api/rehearsals/route.ts
new file mode 100644
index 0000000..ed0347a
--- /dev/null
+++ b/app/api/rehearsals/route.ts
@@ -0,0 +1,22 @@
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import { NextRequest } from "next/server";
+import { EventStore } from "@/app/event-store";
+import { getRehearsal, postRehearsal } from "./handlers";
+
+export const dynamic = "force-dynamic";
+
+function deps() {
+  const { env } = getCloudflareContext();
+  return {
+    store: EventStore.fromEnv(env),
+    adminKey: env.BOOTH_UPLOAD_KEY,
+  };
+}
+
+export async function GET(req: NextRequest) {
+  return getRehearsal(req, deps());
+}
+
+export async function POST(req: NextRequest) {
+  return postRehearsal(req, deps());
+}
diff --git a/app/api/upload/handlers.ts b/app/api/upload/handlers.ts
index c4581fc..a1892a0 100644
--- a/app/api/upload/handlers.ts
+++ b/app/api/upload/handlers.ts
@@ -3,7 +3,9 @@ import {
   canonicalEvent,
   EventStore,
   InvalidEventSlugError,
+  InvalidStoredRehearsalError,
   PhotoIndexWriteError,
+  RehearsalNotFoundError,
 } from "@/app/event-store";
 import { InvalidUploadHeadersError, parseUploadHeaders } from "@/app/upload-contract";
 import { boothOrAdminOk, isImage, MAX_UPLOAD_BYTES } from "@/app/upload-auth";
@@ -64,6 +66,20 @@ export async function handleUpload(req: NextRequest, deps: UploadHandlerDeps): P
   }
   if (auth !== "ok") return jsonError("unauthorized", 401);
 
+  if (intent.kind === "stable" && intent.rehearsalId) {
+    try {
+      await deps.store.readRehearsal(event, intent.rehearsalId);
+    } catch (error) {
+      if (error instanceof RehearsalNotFoundError) {
+        return jsonError("rehearsal unavailable", 409);
+      }
+      if (error instanceof InvalidStoredRehearsalError) {
+        return jsonError("rehearsal evidence unavailable", 503, { "Retry-After": "1" });
+      }
+      throw error;
+    }
+  }
+
   const body = await req.arrayBuffer();
   if (body.byteLength === 0) return jsonError("empty body", 400);
   if (body.byteLength > MAX_UPLOAD_BYTES) return jsonError("too large", 413);
@@ -73,6 +89,21 @@ export async function handleUpload(req: NextRequest, deps: UploadHandlerDeps): P
     const photo = await deps.store.putPhoto(event, body, {
       ...(intent.kind === "stable" ? { upload: intent } : {}),
     });
+    if (intent.kind === "stable" && intent.rehearsalId) {
+      try {
+        await deps.store.recordRehearsalUpload(
+          event,
+          intent.rehearsalId,
+          intent,
+          photo,
+        );
+      } catch {
+        return NextResponse.json(
+          { error: "rehearsal evidence unavailable", retryable: true },
+          { status: 503, headers: { "Retry-After": "1" } },
+        );
+      }
+    }
     // `url` remains first-class for older Booth clients; identity fields are
     // additive for stable clients and moderation/retry diagnostics.
     return NextResponse.json({ url: photo.url, key: photo.key, duplicate: photo.duplicate });
diff --git a/app/api/upload/route.test.ts b/app/api/upload/route.test.ts
index 22ecc83..15401ac 100644
--- a/app/api/upload/route.test.ts
+++ b/app/api/upload/route.test.ts
@@ -17,6 +17,7 @@ const ADMIN_KEY = "admin";
 const CAPTURE_ID = "018f0000-0000-4000-8000-000000000001";
 const CAPTURED_AT = "1753315200000";
 const JPEG = new Uint8Array([0xff, 0xd8, 0xff, 0xe0]);
+const REHEARSAL_ID = "018f0000-0000-4000-8000-000000000501";
 
 function request(
   event = "launch",
@@ -54,6 +55,10 @@ class FailPrivateWrites implements ObjectStore {
     this.failing = false;
   }
 
+  failWrites(): void {
+    this.failing = true;
+  }
+
   has(key: string): boolean {
     return this.inner.has(key);
   }
@@ -240,4 +245,62 @@ describe("upload route", () => {
     expect(response.status).toBe(200);
     expect(await response.json()).toMatchObject({ duplicate: false });
   });
+
+  test("acknowledges a tracked upload only after private rehearsal evidence exists", async () => {
+    const { deps } = memoryDeps();
+    await deps.store.startRehearsal("launch", { rehearsalId: REHEARSAL_ID });
+    const response = await handleUpload(request("launch", {
+      headers: stableHeaders({
+        "x-rehearsal-id": REHEARSAL_ID,
+        "x-capture-source": "framed",
+        "x-frame-key": "square",
+      }),
+    }), deps);
+
+    expect(response.status).toBe(200);
+    const photo = await response.json() as { key: string };
+    expect((await deps.store.readRehearsal("launch", REHEARSAL_ID)).evidence)
+      .toMatchObject([{
+        id: `upload-${CAPTURE_ID}`,
+        kind: "photo-acknowledged",
+        photoKey: photo.key,
+      }]);
+  });
+
+  test("rejects an unknown rehearsal before writing public photo bytes", async () => {
+    const { photos, deps } = memoryDeps();
+    const response = await handleUpload(request("launch", {
+      headers: stableHeaders({ "x-rehearsal-id": REHEARSAL_ID }),
+    }), deps);
+
+    expect(response.status).toBe(409);
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(0);
+  });
+
+  test("retries missing rehearsal evidence without duplicating the public image", async () => {
+    const state = new FailPrivateWrites(
+      `events/launch/rehearsals/${REHEARSAL_ID}/evidence/`,
+    );
+    const { photos, deps } = memoryDeps({ state });
+    await deps.store.startRehearsal("launch", { rehearsalId: REHEARSAL_ID });
+
+    const first = await handleUpload(request("launch", {
+      headers: stableHeaders({ "x-rehearsal-id": REHEARSAL_ID }),
+    }), deps);
+    expect(first.status).toBe(503);
+    expect(first.headers.get("Retry-After")).toBe("1");
+    expect(await first.json()).toEqual({
+      error: "rehearsal evidence unavailable",
+      retryable: true,
+    });
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+
+    state.allowWrites();
+    const retry = await handleUpload(request("launch", {
+      headers: stableHeaders({ "x-rehearsal-id": REHEARSAL_ID }),
+    }), deps);
+    expect(retry.status).toBe(200);
+    expect(await retry.json()).toMatchObject({ duplicate: true });
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(1);
+  });
 });
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index 2e41e52..f0f7355 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -627,6 +627,71 @@ describe("private rehearsal storage", () => {
     expect(latestRehearsalKey("launch")).toBe("events/launch/rehearsals/latest.json");
     expect("deleteRehearsal" in EventStore.prototype).toBeFalse();
   });
+
+  test("records one deterministic same-Event upload acknowledgement", async () => {
+    const store = new EventStore(
+      new InMemoryObjectStore(),
+      new InMemoryObjectStore(),
+      "https://photos.example",
+      () => new Date("2026-07-24T00:00:00.000Z"),
+    );
+    await store.startRehearsal("launch", { rehearsalId });
+    const upload = {
+      captureId,
+      capturedAt: 1_753_315_200_000,
+      source: "framed" as const,
+      frameKey: "square",
+      rehearsalId,
+    };
+    const photo = await store.putPhoto("launch", new Uint8Array([1]).buffer, { upload });
+
+    const first = await store.recordRehearsalUpload("launch", rehearsalId, upload, photo);
+    const retry = await store.recordRehearsalUpload("launch", rehearsalId, upload, {
+      key: photo.key,
+      duplicate: true,
+    });
+    expect(first).toMatchObject({
+      id: `upload-${captureId}`,
+      rehearsalId,
+      kind: "photo-acknowledged",
+      captureId,
+      capturedAt: upload.capturedAt,
+      frameKey: "square",
+      photoKey: photo.key,
+    });
+    expect(retry).toEqual(first);
+    expect((await store.readRehearsal("launch", rehearsalId)).evidence).toEqual([first]);
+
+    await expect(store.recordRehearsalUpload("launch", rehearsalId, upload, {
+      key: "launch/1753315200001-other.jpg",
+      duplicate: true,
+    })).rejects.toBeInstanceOf(RehearsalConflictError);
+  });
+
+  test("rejects missing and cross-Event upload sessions before attachment", async () => {
+    const store = new EventStore(
+      new InMemoryObjectStore(),
+      new InMemoryObjectStore(),
+      "https://photos.example",
+    );
+    await store.startRehearsal("launch", { rehearsalId });
+    const upload = {
+      captureId,
+      capturedAt: 1_753_315_200_000,
+      rehearsalId,
+    };
+    await expect(store.recordRehearsalUpload("other", rehearsalId, upload, {
+      key: "other/1753315200000-a.jpg",
+      duplicate: false,
+    })).rejects.toBeInstanceOf(RehearsalNotFoundError);
+    await expect(store.recordRehearsalUpload("launch", rehearsalId, {
+      ...upload,
+      rehearsalId: "018f0000-0000-4000-8000-000000000599",
+    }, {
+      key: "launch/1753315200000-a.jpg",
+      duplicate: false,
+    })).rejects.toBeInstanceOf(TypeError);
+  });
 });
 
 describe("canonical event identity", () => {
diff --git a/app/event-store.ts b/app/event-store.ts
index af9c276..d6091f7 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -613,6 +613,10 @@ export class EventStore {
     return `${base}/${key.split("/").map(encodeURIComponent).join("/")}`;
   }
 
+  serverTime(): string {
+    return this.now().toISOString();
+  }
+
   async readConfig(event: string): Promise<EventConfig | null> {
     try {
       const current = await this.readPrivateConfig(event);
@@ -1041,7 +1045,7 @@ export class EventStore {
     const claimed = await this.state.compareAndSwap(
       identityKey,
       null,
-      JSON.stringify({ version: 1, key, semantic }),
+      JSON.stringify({ version: 1, key, evidence: record }),
       jsonWriteOptions(),
     );
     if (!claimed) {
@@ -1066,6 +1070,36 @@ export class EventStore {
     return { evidence: record, idempotent: false };
   }
 
+  async recordRehearsalUpload(
+    event: string,
+    rehearsalId: string,
+    upload: StableUpload,
+    photo: Pick<PutPhotoResult, "key" | "duplicate">,
+  ): Promise<RehearsalEvidence> {
+    const canonical = canonicalEvent(event);
+    if (
+      upload.rehearsalId !== rehearsalId
+      || !isRehearsalId(rehearsalId)
+      || !isPhotoKey(canonical, photo.key)
+    ) {
+      throw new TypeError("invalid rehearsal upload");
+    }
+    const result = await this.appendRehearsalEvidence(canonical, rehearsalId, {
+      version: 1,
+      id: `upload-${upload.captureId}`,
+      rehearsalId,
+      observedAt: upload.capturedAt,
+      kind: "photo-acknowledged",
+      captureId: upload.captureId,
+      capturedAt: upload.capturedAt,
+      ...(upload.source === "framed" && upload.frameKey
+        ? { frameKey: upload.frameKey }
+        : {}),
+      photoKey: photo.key,
+    });
+    return result.evidence;
+  }
+
   private async finishExistingRehearsalEvidence(
     event: string,
     rehearsalId: string,
@@ -1085,12 +1119,30 @@ export class EventStore {
       || Object.keys(marker).length !== 3
       || marker.version !== 1
       || marker.key !== key
-      || marker.semantic !== semantic
     ) {
       throw new RehearsalConflictError(evidenceId);
     }
-    const object = await this.state.get(key);
-    if (!object) throw new InvalidStoredRehearsalError(event, rehearsalId);
+    const markerEvidence = parseRehearsalEvidence(marker.evidence, event);
+    if (
+      !markerEvidence
+      || markerEvidence.id !== evidenceId
+      || markerEvidence.rehearsalId !== rehearsalId
+      || rehearsalEvidenceSemantic(markerEvidence) !== semantic
+    ) {
+      throw new RehearsalConflictError(evidenceId);
+    }
+    let object = await this.state.get(key);
+    if (!object) {
+      const repaired = await this.state.compareAndSwap(
+        key,
+        null,
+        JSON.stringify(markerEvidence),
+        jsonWriteOptions(),
+      );
+      if (repaired) return { evidence: markerEvidence, idempotent: true };
+      object = await this.state.get(key);
+      if (!object) throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
     let value: unknown;
     try {
       value = await object.json<unknown>();
diff --git a/app/upload-contract.test.ts b/app/upload-contract.test.ts
index 713d892..98e39f6 100644
--- a/app/upload-contract.test.ts
+++ b/app/upload-contract.test.ts
@@ -20,6 +20,7 @@ describe("stable upload headers", () => {
       source: "framed" as const,
       frameKey: "square",
       configRevisionId: "018f0000-0000-7000-8000-000000000002",
+      rehearsalId: "018f0000-0000-4000-8000-000000000501",
     };
 
     expect(stableUploadHeaders(stable)).toEqual({
@@ -28,6 +29,7 @@ describe("stable upload headers", () => {
       "x-capture-source": "framed",
       "x-frame-key": "square",
       "x-config-revision-id": "018f0000-0000-7000-8000-000000000002",
+      "x-rehearsal-id": "018f0000-0000-4000-8000-000000000501",
     });
     expect(parseUploadHeaders(headers(stableUploadHeaders(stable)))).toEqual({ kind: "stable", ...stable });
   });
@@ -46,6 +48,9 @@ describe("stable upload headers", () => {
   test("rejects metadata without capture identity", () => {
     expect(() => parseUploadHeaders(headers({ "x-capture-source": "framed" })))
       .toThrow(InvalidUploadHeadersError);
+    expect(() => parseUploadHeaders(headers({
+      "x-rehearsal-id": "018f0000-0000-4000-8000-000000000501",
+    }))).toThrow(InvalidUploadHeadersError);
   });
 
   test("rejects non-lowercase UUID-v4 capture IDs", () => {
@@ -67,6 +72,8 @@ describe("stable upload headers", () => {
       { ...identity, "x-frame-key": "../frame" },
       { ...identity, "x-config-revision-id": "-revision" },
       { ...identity, "x-frame-key": "a".repeat(129) },
+      { ...identity, "x-rehearsal-id": "018F0000-0000-4000-8000-000000000501" },
+      { ...identity, "x-rehearsal-id": "../rehearsal" },
     ]) {
       expect(() => parseUploadHeaders(headers(invalid))).toThrow(InvalidUploadHeadersError);
     }
diff --git a/app/upload-contract.ts b/app/upload-contract.ts
index 5217bf9..8f43081 100644
--- a/app/upload-contract.ts
+++ b/app/upload-contract.ts
@@ -16,6 +16,7 @@ export type StableUpload = StableCaptureIdentity & {
   source?: CaptureSource;
   frameKey?: string;
   configRevisionId?: string;
+  rehearsalId?: string;
 };
 
 export type UploadIntent = { kind: "legacy" } | ({ kind: "stable" } & StableUpload);
@@ -26,7 +27,8 @@ type InvalidUploadHeadersCode =
   | "invalid_captured_at"
   | "invalid_capture_source"
   | "invalid_frame_key"
-  | "invalid_config_revision_id";
+  | "invalid_config_revision_id"
+  | "invalid_rehearsal_id";
 
 export class InvalidUploadHeadersError extends Error {
   constructor(readonly code: InvalidUploadHeadersCode, message: string) {
@@ -49,8 +51,12 @@ export function parseUploadHeaders(headers: Headers): UploadIntent {
   const source = headers.get("x-capture-source");
   const frameKey = headers.get("x-frame-key");
   const configRevisionId = headers.get("x-config-revision-id");
+  const rehearsalId = headers.get("x-rehearsal-id");
 
-  const hasMetadata = source !== null || frameKey !== null || configRevisionId !== null;
+  const hasMetadata = source !== null
+    || frameKey !== null
+    || configRevisionId !== null
+    || rehearsalId !== null;
 
   if (captureId === null && capturedAt === null) {
     if (hasMetadata) invalid("incomplete_capture_identity", "Capture metadata requires a capture identity.");
@@ -75,6 +81,9 @@ export function parseUploadHeaders(headers: Headers): UploadIntent {
   if (configRevisionId !== null && !SAFE_TOKEN.test(configRevisionId)) {
     invalid("invalid_config_revision_id", "Config revision ID is invalid.");
   }
+  if (rehearsalId !== null && !UUID_V4.test(rehearsalId)) {
+    invalid("invalid_rehearsal_id", "Rehearsal ID must be a lowercase UUID-v4.");
+  }
 
   return {
     kind: "stable",
@@ -83,6 +92,7 @@ export function parseUploadHeaders(headers: Headers): UploadIntent {
     ...(parsedSource ? { source: parsedSource } : {}),
     ...(frameKey !== null ? { frameKey } : {}),
     ...(configRevisionId !== null ? { configRevisionId } : {}),
+    ...(rehearsalId !== null ? { rehearsalId } : {}),
   };
 }
 
@@ -93,5 +103,6 @@ export function stableUploadHeaders(input: StableUpload): Record<string, string>
     ...(input.source ? { "x-capture-source": input.source } : {}),
     ...(input.frameKey ? { "x-frame-key": input.frameKey } : {}),
     ...(input.configRevisionId ? { "x-config-revision-id": input.configRevisionId } : {}),
+    ...(input.rehearsalId ? { "x-rehearsal-id": input.rehearsalId } : {}),
   };
 }

From 6ac67a54cc483793ee25b3fb83a356c8c03757df Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 22:58:29 +0800
Subject: [PATCH 097/105] feat: manage event presets in admin

---
 app/[event]/admin/admin-styles.test.ts        |  17 +
 app/[event]/admin/admin.module.css            |  44 +++
 .../admin/config-history-panel.test.tsx       |  29 ++
 app/[event]/admin/config-history-panel.tsx    |   9 +
 app/[event]/admin/config-mutation.test.ts     |  34 ++
 app/[event]/admin/config-mutation.ts          |  25 ++
 app/[event]/admin/page.tsx                    | 358 ++++++++++++++++--
 app/[event]/admin/preset-panel.test.tsx       | 132 +++++++
 app/[event]/admin/preset-panel.tsx            | 256 +++++++++++++
 app/[event]/admin/preset-state.test.ts        |  93 +++++
 app/[event]/admin/preset-state.ts             |  59 ++-
 app/i18n/catalog.test.ts                      |  10 +
 app/i18n/catalog.ts                           | 121 ++++++
 13 files changed, 1155 insertions(+), 32 deletions(-)
 create mode 100644 app/[event]/admin/preset-panel.test.tsx
 create mode 100644 app/[event]/admin/preset-panel.tsx

diff --git a/app/[event]/admin/admin-styles.test.ts b/app/[event]/admin/admin-styles.test.ts
index 71fd6c5..69443fb 100644
--- a/app/[event]/admin/admin-styles.test.ts
+++ b/app/[event]/admin/admin-styles.test.ts
@@ -16,3 +16,20 @@ test("configuration history is a horizontal square contact strip", async () => {
   expect(record).toContain("aspect-ratio: 1");
   expect(record).toContain("flex:");
 });
+
+test("preset actions remain touch sized and reflow as a call sheet", async () => {
+  const css = await Bun.file(`${import.meta.dir}/admin.module.css`).text();
+  const actions = declarationBlock(
+    css,
+    ".presetSave, .presetLibraryRow button, .presetList button, .presetConfirm button",
+  );
+  const workspace = declarationBlock(css, ".presetWorkspace");
+  const rtl = declarationBlock(css, ".presetPanel[dir=\"rtl\"]");
+
+  expect(actions).toContain("min-height: 44px");
+  expect(workspace).toContain("grid-template-columns");
+  expect(rtl).toContain("text-align: start");
+  expect(css).toContain("@media (max-width: 700px)");
+  expect(css).toContain("@media (forced-colors: active)");
+  expect(css).toContain("@media (prefers-reduced-motion: reduce)");
+});
diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index 5466524..2e33c47 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -57,6 +57,8 @@
 .revisionHeadline strong { font: 900 15px/1 "Arial Narrow", Arial, sans-serif; text-transform: uppercase; }
 .currentStamp { padding: 5px 7px 4px; color: var(--ink); background: var(--green); font: 900 9px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .1em; transform: rotate(-1deg); }
 .revisionDetails > code { display: block; max-width: 100%; margin-top: 7px; overflow: hidden; color: var(--ink); font: 9px/1 ui-monospace, monospace; text-overflow: ellipsis; white-space: nowrap; opacity: .62; }
+.revisionSource { margin-top: 8px; font: 800 10px/1.3 ui-monospace, monospace; overflow-wrap: anywhere; }
+.revisionSource code { font: inherit; }
 .revisionDelta { display: flex; flex-wrap: wrap; gap: 5px; margin-top: 10px; }
 .revisionDelta span { border: 1px solid var(--ink); padding: 4px 6px; color: var(--paper); background: var(--ink); font: 800 9px/1 ui-monospace, monospace; }
 .revisionDelta span[data-delta="added"] { color: var(--ink); background: var(--green); }
@@ -70,6 +72,46 @@
 .restoreConfirm button { border: 1px solid var(--paper); padding: 8px; color: var(--ink); background: var(--amber); font: 800 10px/1.2 system-ui, sans-serif; cursor: pointer; }
 .restoreConfirm button:last-child { color: var(--paper); background: var(--ink); }
 .restoreConfirm button:disabled { cursor: wait; opacity: .6; }
+.presetPanel { min-width: 0; border-block: 7px solid var(--ink); padding-block: 22px 26px; }
+.presetPanel[dir="rtl"] { text-align: start; }
+.presetHeading { display: grid; grid-template-columns: minmax(190px, .75fr) minmax(240px, 1fr); gap: 24px; align-items: end; }
+.presetHeading > div { display: flex; align-items: baseline; gap: 12px; }
+.presetHeading .cardNumber { color: var(--pink); }
+.presetHeading h2 { font: 900 clamp(32px, 4.5vw, 58px)/.82 Impact, "Arial Narrow", sans-serif; letter-spacing: -.025em; text-transform: uppercase; }
+.presetHeading > p { max-width: 54ch; font-size: 13px; line-height: 1.45; }
+.presetPrivacy { margin-top: 15px; border-inline-start: 7px solid var(--green); padding: 11px 13px; color: #fff; background: var(--ink); font: 800 12px/1.4 system-ui, sans-serif; }
+.presetWorkspace { display: grid; grid-template-columns: minmax(220px, .8fr) minmax(280px, 1.2fr); gap: 8px; margin-top: 8px; }
+.presetEditor { display: grid; grid-template-columns: 1fr; align-content: start; gap: 7px; border: 2px solid var(--ink); padding: 14px; background: #fff; }
+.presetEditor > label { margin-top: 5px; font: 800 10px/1 ui-monospace, monospace; letter-spacing: .07em; text-transform: uppercase; }
+.presetEditor input, .presetEditor select { min-height: 44px; min-width: 0; width: 100%; border: 1px solid var(--ink); padding: 9px 10px; color: var(--ink); background: #fff; font: 700 13px/1.2 system-ui, sans-serif; }
+.presetEditor input:disabled, .presetEditor select:disabled { cursor: wait; opacity: .58; }
+.presetLibraryRow { display: grid; grid-template-columns: minmax(0, 1fr) minmax(120px, auto); gap: 6px; }
+.presetSave, .presetLibraryRow button, .presetList button, .presetConfirm button { min-height: 44px; border: 2px solid var(--ink); padding: 10px 12px; color: var(--ink); background: var(--amber); font: 900 12px/1.15 system-ui, sans-serif; cursor: pointer; }
+.presetSave { margin-top: 7px; color: #fff; background: var(--pink); }
+.presetSave:disabled, .presetLibraryRow button:disabled, .presetList button:disabled, .presetConfirm button:disabled { cursor: wait; opacity: .58; }
+.presetSummary { min-width: 0; padding: 18px; color: #fff; background: var(--ink); }
+.presetSummary h3 { max-width: 12ch; color: var(--amber); font: 900 clamp(28px, 4vw, 48px)/.86 Impact, "Arial Narrow", sans-serif; letter-spacing: -.02em; text-transform: uppercase; }
+.presetSummary ul { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 18px; padding: 0; list-style: none; }
+.presetSummary li { min-width: 0; border: 1px solid #777; padding: 7px 8px; font: 800 10px/1.25 ui-monospace, monospace; overflow-wrap: anywhere; }
+.presetList { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 250px), 1fr)); gap: 7px; margin-top: 8px; padding: 0; list-style: none; }
+.presetList li { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 10px; align-items: center; border: 2px solid var(--ink); padding: 10px; background: #fff; }
+.presetList li[data-selected="true"] { box-shadow: inset 6px 0 var(--green); }
+.presetList li > div { min-width: 0; }
+.presetList strong, .presetList code { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.presetList strong { font: 900 15px/1.1 system-ui, sans-serif; }
+.presetList code { margin-top: 5px; color: #5d5b55; font: 10px/1.2 ui-monospace, monospace; }
+.presetConfirm { margin-top: 8px; border: 3px solid var(--ink); padding: 15px; background: #fff5d6; }
+.presetConfirm > p { font: 800 13px/1.4 system-ui, sans-serif; overflow-wrap: anywhere; }
+.presetConfirm .presetExact { margin-top: 7px; font: 800 11px/1.3 ui-monospace, monospace; }
+.presetConfirm .presetWarning { margin-top: 10px; border-inline-start: 6px solid #be124e; padding: 9px 11px; color: #8f1239; background: #ffe4e6; }
+.presetConfirm > div { display: flex; flex-wrap: wrap; gap: 7px; margin-top: 13px; }
+.presetConfirm > div button:first-child { color: #fff; background: var(--pink); }
+.presetConfirm > div button:last-child { background: #fff; }
+.presetEmpty, .presetLoadError { margin-top: 8px; border: 2px dashed #8c8880; padding: 16px; font: 800 12px/1.4 system-ui, sans-serif; }
+.presetLoadError { border-color: #be124e; color: #8f1239; background: #ffe4e6; }
+.presetStatus, .presetError { min-height: 1.45em; margin-top: 8px; font: 800 12px/1.45 system-ui, sans-serif; }
+.presetStatus { color: #08752f; }
+.presetError { color: #8f1239; }
 .sideCard, .linkCard { border: 2px solid var(--ink); padding: 17px; background: #fff; }.sideCard .cardNumber { color: var(--pink); display: block; margin-bottom: 16px; }.sideCard h2 { font-size: 30px; margin-bottom: 10px; }.sideCard p { margin-bottom: 16px; }
 .exportPanel { border: 3px solid var(--ink); padding: 17px; background: #fff; box-shadow: inset 0 7px var(--green); }
 .exportPanel .cardNumber { display: block; margin: 7px 0 14px; color: var(--pink); }
@@ -139,8 +181,10 @@
 .authPage { display: grid; place-items: center; padding: 20px; background: var(--ink); color: #fff; }.authCard { width: min(500px, 100%); border-top: 8px solid var(--pink); padding: clamp(25px, 5vw, 55px); background: #1a1a19; }.authCard h1 { margin: 25px 0; font: 900 clamp(58px, 10vw, 90px)/.78 Impact, sans-serif; text-transform: uppercase; }.authCard > p:not(.kicker) { color: #bbb; line-height: 1.4; margin-bottom: 28px; }.authCard label { display: block; margin-bottom: 8px; font: 800 11px/1 ui-monospace, monospace; text-transform: uppercase; }.authCard input { width: 100%; padding: 14px; border: 1px solid #777; background: #080808; color: #fff; font: 16px/1 ui-monospace, monospace; }.authCard button { width: 100%; margin-top: 10px; padding: 15px; border: 0; color: #fff; background: var(--pink); font-weight: 900; cursor: pointer; }
 .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .frameCard:focus-within { outline: 3px solid var(--amber); outline-offset: 3px; }
 @media (forced-colors: active) { .console button:focus-visible, .console a:focus-visible, .console input:focus-visible, .console select:focus-visible, .console textarea:focus-visible, .authPage button:focus-visible, .authPage input:focus-visible, .moderationDialog button:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; }.localeOptions label:has(input:checked), .experienceToggle:has(input:checked) { border: 2px solid Highlight; box-shadow: none; }.exportPanel { border: 3px solid CanvasText; box-shadow: none; }.exportPrimary, .exportSecondary { border: 2px solid ButtonText; } }
+@media (forced-colors: active) { .presetPanel, .presetEditor, .presetList li, .presetConfirm { border-color: CanvasText; }.presetPrivacy, .presetSummary { border: 2px solid CanvasText; }.presetList li[data-selected="true"] { border: 3px solid Highlight; box-shadow: none; }.presetWarning { border-color: Highlight; } }
 @media (max-width: 900px) { .layout { grid-template-columns: 1fr; }.sideColumn { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }.readiness { grid-template-columns: repeat(2, 1fr); }.railLabel { grid-row: span 2; }.sectionHead { grid-template-columns: 1fr; gap: 10px; }.boothOperationsHead { align-items: start; flex-direction: column; }.boothControlState { text-align: start; } }
 @media (max-width: 760px) { .moderationFilters { grid-template-columns: 1fr; }.moderationFilterActions { display: grid; grid-template-columns: 1fr 1fr; }.moderationRebuild { grid-template-columns: 1fr; }.moderationDialog { grid-template-columns: 1fr; }.moderationDialogHead, .moderationCleanup, .moderationDialogError, .moderationRemove, .moderationConfirm { grid-column: 1; } }
 @media (max-width: 600px) { .console { padding: 15px; }.header { align-items: start; flex-direction: column; }.headerActions { justify-content: flex-start; }.readiness { grid-template-columns: 1fr 1fr; }.railLabel { grid-row: auto; }.sideColumn { grid-template-columns: 1fr; }.filmRail { grid-template-columns: repeat(2, minmax(0, 1fr)); }.revisionRail { padding-right: 9px; padding-left: 9px; scroll-padding-inline: 9px; }.revisionRecord { flex-basis: min(78vw, 280px); scroll-margin-inline: 9px; }.contactSheet, .moderationGrid { grid-template-columns: repeat(2, minmax(0, 1fr)); }.linkCard { grid-template-columns: minmax(0, 1fr) 82px; }.linkCard img { width: 82px; height: 82px; }.boothControlBar { grid-template-columns: 1fr; }.boothActions { display: grid; grid-template-columns: 1fr 1fr; }.boothRoster { grid-template-columns: 1fr; } }
 @media (max-width: 600px) { .experiencePanel { grid-template-columns: 1fr; }.localeOptions { grid-template-columns: 1fr; }.experienceField { grid-template-columns: 1fr; gap: 6px; } }
+@media (max-width: 700px) { .presetHeading, .presetWorkspace { grid-template-columns: 1fr; }.presetLibraryRow { grid-template-columns: 1fr; }.presetList { grid-template-columns: 1fr; }.presetList li { grid-template-columns: 1fr; }.presetList button { width: 100%; }.presetConfirm > div { display: grid; grid-template-columns: 1fr; } }
 @media (prefers-reduced-motion: reduce) { .console *, .console *::before, .console *::after, .authPage *, .authPage *::before, .authPage *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; } }
diff --git a/app/[event]/admin/config-history-panel.test.tsx b/app/[event]/admin/config-history-panel.test.tsx
index eae0ca4..65d855d 100644
--- a/app/[event]/admin/config-history-panel.test.tsx
+++ b/app/[event]/admin/config-history-panel.test.tsx
@@ -146,3 +146,32 @@ test("history summaries make locale and capture settings visible", () => {
   expect(html).toContain("Countdown audio: on");
   expect(html).toContain('data-experience-changed="true"');
 });
+
+test("preset revisions name their exact source preset without bidi ambiguity", () => {
+  const html = renderToStaticMarkup(
+    <ConfigHistoryPanel
+      currentFrames={["one"]}
+      currentExperience={{ frames: ["one"] }}
+      currentRevisionId="018f0000-0000-7000-8000-000000000030"
+      revisions={[{
+        version: 1,
+        id: "018f0000-0000-7000-8000-000000000030",
+        createdAt: "2026-07-24T00:00:00.000Z",
+        parentRevisionId: null,
+        reason: "preset",
+        sourcePresetId: "launch-night",
+        config: { frames: ["one"] },
+      }]}
+      loading={false}
+      restoringRevisionId={null}
+      mutationBusy={false}
+      locale="ar"
+      error=""
+      onReload={() => {}}
+      onRestore={() => {}}
+    />,
+  );
+
+  expect(html).toContain("الإعداد المسبق المطبق");
+  expect(html).toContain("<bdi><code>launch-night</code></bdi>");
+});
diff --git a/app/[event]/admin/config-history-panel.tsx b/app/[event]/admin/config-history-panel.tsx
index 3fcee86..c12863e 100644
--- a/app/[event]/admin/config-history-panel.tsx
+++ b/app/[event]/admin/config-history-panel.tsx
@@ -5,6 +5,7 @@ import type { ConfigRevision, EventExperience } from "../../event-config";
 import { resolveEnabledLocales } from "../../i18n/locale";
 import {
   isSupportedLocale,
+  message,
   type SupportedLocale,
 } from "../../i18n/catalog";
 import styles from "./admin.module.css";
@@ -17,6 +18,7 @@ export type ConfigHistoryPanelProps = {
   loading: boolean;
   restoringRevisionId: string | null;
   mutationBusy: boolean;
+  locale?: SupportedLocale;
   error: string;
   onReload: () => void;
   onRestore: (revisionId: string) => void;
@@ -67,6 +69,7 @@ export function ConfigHistoryPanel({
   loading,
   restoringRevisionId,
   mutationBusy,
+  locale = "en",
   error,
   onReload,
   onRestore,
@@ -126,6 +129,12 @@ export function ConfigHistoryPanel({
                     <strong>{reasonLabel[revision.reason]}</strong>
                     {isCurrent && <span className={styles.currentStamp}>Current</span>}
                   </div>
+                  {revision.reason === "preset" && revision.sourcePresetId && (
+                    <p className={styles.revisionSource}>
+                      {message(locale, "presetSourceLabel")}{" "}
+                      <bdi><code>{revision.sourcePresetId}</code></bdi>
+                    </p>
+                  )}
                   <code title={revision.id}>{revision.id}</code>
                   <div className={styles.revisionDelta}>
                     <span>{revision.config.frames.length} Frame{revision.config.frames.length === 1 ? "" : "s"}</span>
diff --git a/app/[event]/admin/config-mutation.test.ts b/app/[event]/admin/config-mutation.test.ts
index a7250b0..9e5c7cf 100644
--- a/app/[event]/admin/config-mutation.test.ts
+++ b/app/[event]/admin/config-mutation.test.ts
@@ -5,6 +5,7 @@ import {
   getOrCreateRestoreRequest,
   parseConfigHistoryResponse,
   parseConfigMutationResponse,
+  parsePresetApplyResponse,
   rebaseConfigHistory,
   shouldClearRestoreRequest,
   type RestoreRequest,
@@ -289,3 +290,36 @@ test("strictly parses mutation responses before applying restored settings", ()
     idempotent: false,
   })).toBeNull();
 });
+
+test("strictly parses preset apply responses and their exact source", () => {
+  expect(parsePresetApplyResponse({
+    frames: ["one"],
+    hasBoothKey: true,
+    locales: ["en", "ar"],
+    defaultLocale: "ar",
+    currentRevisionId: SOURCE_REVISION,
+    sourcePresetId: "launch-night",
+    idempotent: false,
+  })).toMatchObject({
+    frames: ["one"],
+    sourcePresetId: "launch-night",
+    currentRevisionId: SOURCE_REVISION,
+  });
+
+  expect(parsePresetApplyResponse({
+    frames: ["one"],
+    hasBoothKey: true,
+    currentRevisionId: SOURCE_REVISION,
+    sourcePresetId: "../launch",
+    idempotent: false,
+  })).toBeNull();
+
+  expect(parsePresetApplyResponse({
+    frames: ["one"],
+    hasBoothKey: true,
+    boothKey: "must-not-cross-the-client-boundary",
+    currentRevisionId: SOURCE_REVISION,
+    sourcePresetId: "launch-night",
+    idempotent: false,
+  })).toBeNull();
+});
diff --git a/app/[event]/admin/config-mutation.ts b/app/[event]/admin/config-mutation.ts
index 66157b2..2dd27b5 100644
--- a/app/[event]/admin/config-mutation.ts
+++ b/app/[event]/admin/config-mutation.ts
@@ -7,6 +7,7 @@ import {
   type EventExperience,
   type PublicEventConfig,
 } from "../../event-config";
+import { isPresetId } from "../../event-preset";
 /*
  * Keep the runtime parsers in this client-safe helper: Admin responses cross
  * a network trust boundary even though their TypeScript interfaces are local.
@@ -34,6 +35,10 @@ export type ConfigMutationResponse = PublicEventConfig & {
   idempotent: boolean;
 };
 
+export type PresetApplyResponse = ConfigMutationResponse & {
+  sourcePresetId: string;
+};
+
 const EXPERIENCE_KEYS = [
   "frames",
   "locales",
@@ -177,6 +182,26 @@ export function parseConfigMutationResponse(
   };
 }
 
+export function parsePresetApplyResponse(
+  value: unknown
+): PresetApplyResponse | null {
+  if (
+    !isObject(value)
+    || !hasOnlyKeys(value, [
+      ...PUBLIC_CONFIG_KEYS,
+      "currentRevisionId",
+      "sourcePresetId",
+      "idempotent",
+    ])
+    || !isPresetId(value.sourcePresetId)
+  ) {
+    return null;
+  }
+  const { sourcePresetId, ...mutationValue } = value;
+  const mutation = parseConfigMutationResponse(mutationValue);
+  return mutation ? { ...mutation, sourcePresetId } : null;
+}
+
 export type EditableEventExperience = {
   frames: string[];
   locales: SupportedLocale[];
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index 0cf23cf..b7d7aad 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -5,10 +5,16 @@ import { useParams } from "next/navigation";
 import QRCode from "qrcode";
 import { TEMPLATES } from "../../templates";
 import type { ConfigRevision, PublicEventConfig } from "../../event-config";
-import { message, type SupportedLocale } from "../../i18n/catalog";
+import { isPresetId, parseEventPreset, type EventPreset } from "../../event-preset";
+import {
+  isSupportedLocale,
+  message,
+  type SupportedLocale,
+} from "../../i18n/catalog";
 import {
   deviceLocaleStorageKey,
   DocumentLocaleLease,
+  resolveEnabledLocales,
   resolveDeviceLocale,
 } from "../../i18n/locale";
 import type { ModerationPhoto } from "../../moderation";
@@ -42,6 +48,7 @@ import {
   removeModeratedPhoto,
   type ModerationFilters,
 } from "./moderation-state";
+import { PresetPanel } from "./preset-panel";
 import {
   buildConfigSaveBody,
   clearRestoreRequestAfterReconciliation,
@@ -49,10 +56,21 @@ import {
   getOrCreateRestoreRequest,
   parseConfigHistoryResponse,
   parseConfigMutationResponse,
+  parsePresetApplyResponse,
   rebaseConfigHistory,
   shouldClearRestoreRequest,
   type RestoreRequest,
 } from "./config-mutation";
+import {
+  buildPresetSaveBody,
+  clearPresetApplyAfterReconciliation,
+  getOrCreatePresetApply,
+  mergePresetPage,
+  parsePresetPageResponse,
+  reconcileAppliedPreset,
+  shouldClearPresetApply,
+  type PendingPresetApply,
+} from "./preset-state";
 import styles from "./admin.module.css";
 
 type AuthState = "missing" | "ready" | "invalid";
@@ -98,6 +116,17 @@ export default function Admin() {
   const [cleanupPending, setCleanupPending] = useState(false);
   const [deleting, setDeleting] = useState(false);
   const [saving, setSaving] = useState(false);
+  const [presets, setPresets] = useState<EventPreset[]>([]);
+  const [presetsLoading, setPresetsLoading] = useState(false);
+  const [presetsError, setPresetsError] = useState("");
+  const [selectedPresetId, setSelectedPresetId] = useState<string | null>(null);
+  const [presetIdDraft, setPresetIdDraft] = useState("");
+  const [presetLabelDraft, setPresetLabelDraft] = useState("");
+  const [presetSaving, setPresetSaving] = useState(false);
+  const [applyingPresetId, setApplyingPresetId] = useState<string | null>(null);
+  const [confirmingPresetId, setConfirmingPresetId] = useState<string | null>(null);
+  const [presetNotice, setPresetNotice] = useState("");
+  const [presetActionError, setPresetActionError] = useState("");
   const [notice, setNotice] = useState("");
   const [error, setError] = useState("");
   const [origin, setOrigin] = useState("");
@@ -123,11 +152,37 @@ export default function Admin() {
   const configMutationBusy = useRef(false);
   const pendingSaveMutationId = useRef<string | null>(null);
   const pendingRestoreRequests = useRef(new Map<string, RestoreRequest>());
+  const pendingPresetApplies = useRef(new Map<string, PendingPresetApply>());
 
   const boothUrl = `${origin}/${event}`;
   const liveUrl = `${boothUrl}/live`;
   const defaults = useMemo(() => Object.keys(TEMPLATES).filter((key) => !TEMPLATES[key].group), []);
-  const configBusy = saving || restoringRevisionId !== null;
+  const configBusy =
+    saving
+    || restoringRevisionId !== null
+    || presetSaving
+    || applyingPresetId !== null;
+  const currentExperience = useMemo(() => ({
+    frames: [...frames],
+    locales: [...locales],
+    defaultLocale,
+    ...(timeZone ? { timeZone } : {}),
+    capture: {
+      reviewEnabled,
+      autoAcceptSeconds,
+      countdownAudioDefault,
+    },
+    ...(gallery ? { gallery: { ...gallery } } : {}),
+  }), [
+    autoAcceptSeconds,
+    countdownAudioDefault,
+    defaultLocale,
+    frames,
+    gallery,
+    locales,
+    reviewEnabled,
+    timeZone,
+  ]);
   const clearPendingSave = () => {
     pendingSaveMutationId.current = null;
     setError((current) => current === CONFIG_CONFLICT_MESSAGE ? "" : current);
@@ -179,24 +234,27 @@ export default function Admin() {
     void QRCode.toDataURL(liveUrl, { width: 240, margin: 1 }).then(setLiveQr).catch(() => setLiveQr(""));
   }, [boothUrl, liveUrl, origin]);
 
+  const fetchConfigHistory = useCallback(async () => {
+    const response = await fetch(`/api/config/revisions?event=${encodeURIComponent(event)}`, {
+        cache: "no-store",
+        headers: { "x-booth-key": adminKey },
+    });
+    if (response.status === 401) {
+      sessionStorage.removeItem("adminKey");
+      setAuth("invalid");
+      throw new Error("That admin key was rejected.");
+    }
+    if (!response.ok) throw new Error(`Configuration history returned ${response.status}`);
+    const data = parseConfigHistoryResponse(await response.json());
+    if (!data) throw new Error("Configuration history had an unexpected shape");
+    return data;
+  }, [adminKey, event]);
+
   const loadConfig = useCallback(async () => {
     setConfigLoaded(false);
     setConfigError("");
     try {
-      const response = await fetch(`/api/config/revisions?event=${encodeURIComponent(event)}`, {
-        cache: "no-store",
-        headers: { "x-booth-key": adminKey },
-      });
-      if (response.status === 401) {
-        sessionStorage.removeItem("adminKey");
-        setAuth("invalid");
-        throw new Error("That admin key was rejected.");
-      }
-      if (!response.ok) throw new Error(`Configuration history returned ${response.status}`);
-      const data = parseConfigHistoryResponse(await response.json());
-      if (!data) {
-        throw new Error("Configuration history had an unexpected shape");
-      }
+      const data = await fetchConfigHistory();
       const rebased = rebaseConfigHistory(data, defaults, pendingSaveMutationId);
       setFrames(new Set(rebased.frames));
       setLocales(new Set(rebased.locales));
@@ -217,12 +275,53 @@ export default function Admin() {
       setCurrentRevisionId(rebased.currentRevisionId);
       setRevisions(rebased.revisions);
       setConfigLoaded(true);
-      return true;
+      return data;
     } catch (cause) {
       setConfigError(cause instanceof Error ? cause.message : "Config could not be loaded");
-      return false;
+      return null;
+    }
+  }, [defaults, fetchConfigHistory]);
+
+  const loadPresets = useCallback(async () => {
+    setPresetsLoading(true);
+    setPresetsError("");
+    try {
+      let cursor: string | null = null;
+      let merged: EventPreset[] = [];
+      const seen = new Set<string>();
+      do {
+        const query = new URLSearchParams({ limit: "100" });
+        if (cursor !== null) query.set("cursor", cursor);
+        const response = await fetch(`/api/presets?${query}`, {
+          cache: "no-store",
+          headers: { "x-booth-key": adminKey },
+        });
+        if (response.status === 401) {
+          invalidateAuth();
+          throw new Error("That admin key was rejected.");
+        }
+        if (!response.ok) throw new Error(`Presets returned ${response.status}`);
+        const page = parsePresetPageResponse(await response.json());
+        if (!page) throw new Error("Presets had an unexpected shape");
+        merged = mergePresetPage(merged, page.presets);
+        cursor = page.cursor;
+        if (cursor !== null) {
+          if (seen.has(cursor)) throw new Error("Presets returned a repeated cursor");
+          seen.add(cursor);
+        }
+      } while (cursor !== null);
+      setPresets(merged);
+      setPresetsError("");
+      return merged;
+    } catch (cause) {
+      setPresetsError(
+        cause instanceof Error ? cause.message : "Presets could not be loaded",
+      );
+      return null;
+    } finally {
+      setPresetsLoading(false);
     }
-  }, [adminKey, defaults, event]);
+  }, [adminKey, event]);
 
   const requestModerationPage = useCallback(async (input: {
     reset: boolean;
@@ -496,6 +595,11 @@ export default function Admin() {
     void loadConfig();
   }, [adminKey, auth, loadConfig]);
 
+  useEffect(() => {
+    if (auth !== "ready" || !adminKey) return;
+    void loadPresets();
+  }, [adminKey, auth, loadPresets]);
+
   useEffect(() => {
     const coordinator = boothCoordinator.current;
     if (auth !== "ready" || !adminKey) {
@@ -748,6 +852,171 @@ export default function Admin() {
     }
   };
 
+  const selectPreset = (presetId: string | null) => {
+    if (configMutationBusy.current) return;
+    setSelectedPresetId(presetId);
+    setConfirmingPresetId(null);
+    setPresetActionError("");
+    setPresetNotice("");
+    const selected = presets.find((preset) => preset.id === presetId);
+    setPresetIdDraft(selected?.id ?? "");
+    setPresetLabelDraft(selected?.label ?? "");
+  };
+
+  const savePreset = async () => {
+    if (!configLoaded || configMutationBusy.current) return;
+    const presetId = presetIdDraft.trim();
+    const label = presetLabelDraft.trim();
+    if (!isPresetId(presetId) || !label) {
+      setPresetActionError(message(defaultLocale, "presetGenericError"));
+      return;
+    }
+    const selected = presets.find((preset) => preset.id === selectedPresetId);
+    configMutationBusy.current = true;
+    setPresetSaving(true);
+    setPresetActionError("");
+    setPresetNotice("");
+    try {
+      const response = await fetch(
+        `/api/presets/${encodeURIComponent(presetId)}`,
+        {
+          method: "PUT",
+          cache: "no-store",
+          headers: {
+            "x-booth-key": adminKey,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(buildPresetSaveBody({
+            label,
+            expectedUpdatedAt: selected?.updatedAt ?? null,
+            experience: currentExperience,
+          })),
+        },
+      );
+      if (response.status === 401) {
+        invalidateAuth();
+        throw new Error("That admin key was rejected.");
+      }
+      if (response.status === 409) {
+        const latest = await loadPresets();
+        const refreshed = latest?.find((preset) => preset.id === presetId);
+        setSelectedPresetId(refreshed?.id ?? null);
+        setPresetIdDraft(refreshed?.id ?? "");
+        setPresetLabelDraft(refreshed?.label ?? "");
+        setPresetActionError(message(defaultLocale, "presetConflict"));
+        return;
+      }
+      if (!response.ok) throw new Error(`Preset save failed (${response.status})`);
+      const saved = parseEventPreset(await response.json());
+      if (!saved) throw new Error("Preset response had an unexpected shape");
+      setPresets((current) => mergePresetPage(current, [saved]));
+      setSelectedPresetId(saved.id);
+      setPresetIdDraft(saved.id);
+      setPresetLabelDraft(saved.label);
+      setPresetNotice(message(defaultLocale, "presetSaved", { preset: saved.label }));
+    } catch (cause) {
+      setPresetActionError(
+        cause instanceof Error
+          ? cause.message
+          : message(defaultLocale, "presetGenericError"),
+      );
+    } finally {
+      configMutationBusy.current = false;
+      setPresetSaving(false);
+    }
+  };
+
+  const applyPreset = async (presetId: string) => {
+    if (!configLoaded || configMutationBusy.current) return;
+    const preset = presets.find((item) => item.id === presetId);
+    if (!preset) return;
+    configMutationBusy.current = true;
+    const pending = pendingPresetApplies.current;
+    const request = getOrCreatePresetApply(
+      pending,
+      presetId,
+      currentRevisionId,
+      () => crypto.randomUUID(),
+    );
+    setApplyingPresetId(presetId);
+    setPresetActionError("");
+    setPresetNotice("");
+    try {
+      const response = await fetch(
+        `/api/presets/apply?event=${encodeURIComponent(event)}`,
+        {
+          method: "POST",
+          cache: "no-store",
+          headers: {
+            "x-booth-key": adminKey,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(request),
+        },
+      );
+      if (shouldClearPresetApply(response.status)) pending.delete(presetId);
+      if (response.status === 401) {
+        invalidateAuth();
+        throw new Error("That admin key was rejected.");
+      }
+      if (response.status === 409) {
+        await Promise.all([loadConfig(), loadPresets()]);
+        setConfirmingPresetId(null);
+        setPresetActionError(message(defaultLocale, "presetConflict"));
+        return;
+      }
+      if (!response.ok) throw new Error(`Preset apply failed (${response.status})`);
+      await clearPresetApplyAfterReconciliation(pending, request, async () => {
+        const applied = parsePresetApplyResponse(await response.json());
+        if (!applied) throw new Error("Preset response had an unexpected shape");
+        const history = await fetchConfigHistory();
+        const rebased = reconcileAppliedPreset({
+          response: applied,
+          history,
+          sourcePresetId: presetId,
+        });
+        setFrames(new Set(rebased.experience.frames));
+        const appliedLocales = resolveEnabledLocales(rebased.experience.locales);
+        setLocales(new Set(appliedLocales));
+        setDefaultLocale(
+          isSupportedLocale(rebased.experience.defaultLocale)
+          && appliedLocales.includes(rebased.experience.defaultLocale)
+            ? rebased.experience.defaultLocale
+            : "en",
+        );
+        setTimeZone(rebased.experience.timeZone);
+        setReviewEnabled(rebased.experience.capture?.reviewEnabled ?? true);
+        setAutoAcceptSeconds(rebased.experience.capture?.autoAcceptSeconds ?? 5);
+        setCountdownAudioDefault(
+          rebased.experience.capture?.countdownAudioDefault ?? false,
+        );
+        setGallery(rebased.experience.gallery);
+        setCurrentRevisionId(rebased.currentRevisionId);
+        setRevisions(history.revisions);
+        setHasBoothKey(rebased.hasBoothKey);
+        pendingSaveMutationId.current = null;
+        setConfigError("");
+        setConfigLoaded(true);
+        setBoothKey("");
+        setBoothKeySaved(false);
+        setCopied((current) => current === "key" ? "" : current);
+      });
+      setConfirmingPresetId(null);
+      setPresetNotice(message(defaultLocale, "presetApplied", {
+        preset: preset.label,
+      }));
+    } catch (cause) {
+      setPresetActionError(
+        cause instanceof Error
+          ? cause.message
+          : message(defaultLocale, "presetGenericError"),
+      );
+    } finally {
+      configMutationBusy.current = false;
+      setApplyingPresetId(null);
+    }
+  };
+
   const deletePhoto = async (photo: ModerationPhoto) => {
     setDeleting(true);
     setPhotosError("");
@@ -926,28 +1195,55 @@ export default function Admin() {
 
           <ConfigHistoryPanel
             currentFrames={[...frames]}
-            currentExperience={{
-              frames: [...frames],
-              locales: [...locales],
-              defaultLocale,
-              ...(timeZone ? { timeZone } : {}),
-              capture: {
-                reviewEnabled,
-                autoAcceptSeconds,
-                countdownAudioDefault,
-              },
-              ...(gallery ? { gallery } : {}),
-            }}
+            currentExperience={currentExperience}
             currentRevisionId={currentRevisionId}
             revisions={revisions}
             loading={!configLoaded && !configError}
             restoringRevisionId={restoringRevisionId}
             mutationBusy={configBusy}
+            locale={defaultLocale}
             error={configError}
             onReload={() => void loadConfig()}
             onRestore={(revisionId) => void restoreRevision(revisionId)}
           />
 
+          <PresetPanel
+            locale={defaultLocale}
+            event={event}
+            currentExperience={currentExperience}
+            presets={presets}
+            selectedPresetId={selectedPresetId}
+            presetIdDraft={presetIdDraft}
+            presetLabelDraft={presetLabelDraft}
+            loading={presetsLoading}
+            loadError={presetsError}
+            mutationBusy={configBusy || !configLoaded}
+            saving={presetSaving}
+            applyingPresetId={applyingPresetId}
+            confirmingPresetId={confirmingPresetId}
+            hasBoothKey={hasBoothKey}
+            successMessage={presetNotice}
+            errorMessage={presetActionError}
+            onPresetIdChange={(value) => {
+              setPresetIdDraft(value);
+              setPresetActionError("");
+            }}
+            onPresetLabelChange={(value) => {
+              setPresetLabelDraft(value);
+              setPresetActionError("");
+            }}
+            onSelectPreset={selectPreset}
+            onSave={() => void savePreset()}
+            onRequestApply={(presetId) => {
+              setConfirmingPresetId(presetId);
+              setPresetActionError("");
+              setPresetNotice("");
+            }}
+            onConfirmApply={(presetId) => void applyPreset(presetId)}
+            onCancelApply={() => setConfirmingPresetId(null)}
+            onReload={() => void loadPresets()}
+          />
+
           <BoothOperationsPanel
             records={boothRecords}
             cursor={boothCursor}
diff --git a/app/[event]/admin/preset-panel.test.tsx b/app/[event]/admin/preset-panel.test.tsx
new file mode 100644
index 0000000..c946fd3
--- /dev/null
+++ b/app/[event]/admin/preset-panel.test.tsx
@@ -0,0 +1,132 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { EventPreset } from "../../event-preset";
+import type { EventExperience } from "../../event-config";
+import { PresetPanel, type PresetPanelProps } from "./preset-panel";
+
+const currentExperience: EventExperience = {
+  frames: ["beacon", "birthday"],
+  locales: ["en", "zh-SG", "ar"],
+  defaultLocale: "ar",
+  timeZone: "Asia/Singapore",
+  capture: {
+    reviewEnabled: false,
+    autoAcceptSeconds: 8,
+    countdownAudioDefault: true,
+  },
+  gallery: {
+    title: "Launch night",
+    accentColor: "#ff357f",
+  },
+};
+
+const preset: EventPreset = {
+  version: 1,
+  id: "launch-night",
+  label: "Launch Night",
+  createdAt: "2026-07-24T00:00:00.000Z",
+  updatedAt: "2026-07-24T00:00:00.000Z",
+  config: currentExperience,
+};
+
+const props = (
+  overrides: Partial<PresetPanelProps> = {},
+): PresetPanelProps => ({
+  locale: "en",
+  event: "talent-beacon",
+  currentExperience,
+  presets: [preset],
+  selectedPresetId: null,
+  presetIdDraft: "",
+  presetLabelDraft: "",
+  loading: false,
+  loadError: "",
+  mutationBusy: false,
+  saving: false,
+  applyingPresetId: null,
+  confirmingPresetId: null,
+  hasBoothKey: true,
+  successMessage: "",
+  errorMessage: "",
+  onPresetIdChange: () => {},
+  onPresetLabelChange: () => {},
+  onSelectPreset: () => {},
+  onSave: () => {},
+  onRequestApply: () => {},
+  onConfirmApply: () => {},
+  onCancelApply: () => {},
+  onReload: () => {},
+  ...overrides,
+});
+
+test("renders labelled create fields and a complete safe experience summary", () => {
+  const html = renderToStaticMarkup(<PresetPanel {...props()} />);
+
+  expect(html).toContain('for="preset-id"');
+  expect(html).toContain('id="preset-id"');
+  expect(html).toContain('for="preset-label"');
+  expect(html).toContain('id="preset-label"');
+  expect(html).toContain("Save current setup as preset");
+  expect(html).toContain("2 frames");
+  expect(html).toContain("English, 简体中文, العربية");
+  expect(html).toContain("Default: العربية");
+  expect(html).toContain("Review: off");
+  expect(html).toContain("Auto-accept: 8s");
+  expect(html).toContain("Countdown audio: on");
+  expect(html).toContain("Asia/Singapore");
+  expect(html).toContain("Launch night");
+  expect(html).toContain("#ff357f");
+  expect(html).toContain("Create preset");
+  expect(html).toContain("Booth credentials are never copied into presets.");
+  expect(html).not.toMatch(/>Delete</);
+});
+
+test("renders update and explicit apply confirmation with RTL-safe exact IDs", () => {
+  const html = renderToStaticMarkup(
+    <PresetPanel
+      {...props({
+        locale: "ar",
+        selectedPresetId: preset.id,
+        presetIdDraft: preset.id,
+        presetLabelDraft: preset.label,
+        confirmingPresetId: preset.id,
+        hasBoothKey: false,
+      })}
+    />,
+  );
+
+  expect(html).toContain('dir="rtl"');
+  expect(html).toContain("تحديث الإعداد المسبق");
+  expect(html).toContain("talent-beacon");
+  expect(html).toContain("Launch Night");
+  expect(html).toContain("<bdi><code>launch-night</code></bdi>");
+  expect(html).toContain("لا يحتوي الحدث المستهدف على مفتاح كشك");
+  expect(html).toContain("تطبيق الإعداد المسبق");
+  expect(html).toContain("إلغاء");
+  expect(html).toContain('aria-live="polite"');
+  expect(html).toContain('role="alert"');
+  expect(html).not.toMatch(/>Delete</);
+});
+
+test("shares the mutation guard with Save, Restore, and Apply", () => {
+  const html = renderToStaticMarkup(
+    <PresetPanel
+      {...props({
+        selectedPresetId: preset.id,
+        presetIdDraft: preset.id,
+        presetLabelDraft: preset.label,
+        confirmingPresetId: preset.id,
+        mutationBusy: true,
+        saving: true,
+        applyingPresetId: preset.id,
+      })}
+    />,
+  );
+
+  const buttons = [...html.matchAll(/<button[^>]*>/g)].map(([button]) => button);
+  const inputs = [...html.matchAll(/<(?:input|select)[^>]*>/g)].map(([input]) => input);
+  expect(buttons.length).toBeGreaterThanOrEqual(4);
+  expect(buttons.every((button) => button.includes("disabled"))).toBe(true);
+  expect(inputs.every((input) => input.includes("disabled"))).toBe(true);
+  expect(html).toContain("Applying…");
+});
diff --git a/app/[event]/admin/preset-panel.tsx b/app/[event]/admin/preset-panel.tsx
new file mode 100644
index 0000000..8fdf6ff
--- /dev/null
+++ b/app/[event]/admin/preset-panel.tsx
@@ -0,0 +1,256 @@
+"use client";
+
+import type { EventExperience } from "../../event-config";
+import type { EventPreset } from "../../event-preset";
+import {
+  isSupportedLocale,
+  localeDirection,
+  message,
+  type SupportedLocale,
+} from "../../i18n/catalog";
+import { resolveEnabledLocales } from "../../i18n/locale";
+import styles from "./admin.module.css";
+
+const localeNames: Record<SupportedLocale, string> = {
+  en: "English",
+  "zh-SG": "简体中文",
+  ar: "العربية",
+};
+
+export type PresetPanelProps = {
+  locale: SupportedLocale;
+  event: string;
+  currentExperience: EventExperience;
+  presets: readonly EventPreset[];
+  selectedPresetId: string | null;
+  presetIdDraft: string;
+  presetLabelDraft: string;
+  loading: boolean;
+  loadError: string;
+  mutationBusy: boolean;
+  saving: boolean;
+  applyingPresetId: string | null;
+  confirmingPresetId: string | null;
+  hasBoothKey: boolean;
+  successMessage: string;
+  errorMessage: string;
+  onPresetIdChange: (value: string) => void;
+  onPresetLabelChange: (value: string) => void;
+  onSelectPreset: (presetId: string | null) => void;
+  onSave: () => void;
+  onRequestApply: (presetId: string) => void;
+  onConfirmApply: (presetId: string) => void;
+  onCancelApply: () => void;
+  onReload: () => void;
+};
+
+export function PresetPanel({
+  locale,
+  event,
+  currentExperience,
+  presets,
+  selectedPresetId,
+  presetIdDraft,
+  presetLabelDraft,
+  loading,
+  loadError,
+  mutationBusy,
+  saving,
+  applyingPresetId,
+  confirmingPresetId,
+  hasBoothKey,
+  successMessage,
+  errorMessage,
+  onPresetIdChange,
+  onPresetLabelChange,
+  onSelectPreset,
+  onSave,
+  onRequestApply,
+  onConfirmApply,
+  onCancelApply,
+  onReload,
+}: PresetPanelProps) {
+  const locales = resolveEnabledLocales(currentExperience.locales);
+  const defaultLocale =
+    isSupportedLocale(currentExperience.defaultLocale)
+    && locales.includes(currentExperience.defaultLocale)
+    ? currentExperience.defaultLocale
+    : "en";
+  const reviewEnabled = currentExperience.capture?.reviewEnabled ?? true;
+  const autoAcceptSeconds = currentExperience.capture?.autoAcceptSeconds ?? 5;
+  const audioEnabled = currentExperience.capture?.countdownAudioDefault ?? false;
+  const confirmingPreset = presets.find(({ id }) => id === confirmingPresetId);
+  const selectedPreset = presets.find(({ id }) => id === selectedPresetId);
+  const disabled = mutationBusy;
+
+  return (
+    <section
+      className={styles.presetPanel}
+      dir={localeDirection(locale)}
+      aria-labelledby="preset-panel-title"
+    >
+      <div className={styles.presetHeading}>
+        <div>
+          <span className={styles.cardNumber}>03</span>
+          <h2 id="preset-panel-title">{message(locale, "presetPanelTitle")}</h2>
+        </div>
+        <p>{message(locale, "presetPanelDescription")}</p>
+      </div>
+
+      <p className={styles.presetPrivacy}>{message(locale, "presetCredentialIsolation")}</p>
+
+      <div className={styles.presetWorkspace}>
+        <div className={styles.presetEditor}>
+          <label htmlFor="preset-library">{message(locale, "presetLibraryLabel")}</label>
+          <div className={styles.presetLibraryRow}>
+            <select
+              id="preset-library"
+              value={selectedPresetId ?? ""}
+              disabled={disabled}
+              onChange={(event) => onSelectPreset(event.target.value || null)}
+            >
+              <option value="">{message(locale, "presetSelectPlaceholder")}</option>
+              {presets.map((preset) => (
+                <option key={preset.id} value={preset.id}>{preset.label}</option>
+              ))}
+            </select>
+            <button type="button" disabled={disabled} onClick={onReload}>
+              {message(locale, "presetReloadAction")}
+            </button>
+          </div>
+
+          <label htmlFor="preset-id">{message(locale, "presetIdLabel")}</label>
+          <input
+            id="preset-id"
+            value={presetIdDraft}
+            disabled={disabled || selectedPreset !== undefined}
+            maxLength={64}
+            autoComplete="off"
+            onChange={(event) => onPresetIdChange(event.target.value)}
+          />
+          <label htmlFor="preset-label">{message(locale, "presetLabelLabel")}</label>
+          <input
+            id="preset-label"
+            value={presetLabelDraft}
+            disabled={disabled}
+            maxLength={80}
+            autoComplete="off"
+            onChange={(event) => onPresetLabelChange(event.target.value)}
+          />
+
+          <button
+            className={styles.presetSave}
+            type="button"
+            disabled={disabled || !presetIdDraft.trim() || !presetLabelDraft.trim()}
+            onClick={onSave}
+          >
+            {saving
+              ? message(locale, "presetSavingAction")
+              : message(
+                  locale,
+                  selectedPreset ? "presetUpdateAction" : "presetCreateAction",
+                )}
+          </button>
+        </div>
+
+        <div className={styles.presetSummary}>
+          <h3>{message(locale, "presetSaveSummaryTitle")}</h3>
+          <ul>
+            <li>{message(locale, "presetFramesSummary", {
+              count: currentExperience.frames.length,
+            })}</li>
+            <li>{message(locale, "presetLocalesSummary", {
+              locales: locales.map((item) => localeNames[item]).join(", "),
+            })}</li>
+            <li>{message(locale, "presetDefaultLocaleSummary", {
+              locale: localeNames[defaultLocale],
+            })}</li>
+            <li>{message(locale, "presetReviewSummary", {
+              state: message(locale, reviewEnabled ? "presetOn" : "presetOff"),
+            })}</li>
+            <li>{message(locale, "presetAutoAcceptSummary", {
+              seconds: autoAcceptSeconds,
+            })}</li>
+            <li>{message(locale, "presetAudioSummary", {
+              state: message(locale, audioEnabled ? "presetOn" : "presetOff"),
+            })}</li>
+            <li>{message(locale, "presetTimeZoneSummary", {
+              timeZone: currentExperience.timeZone ?? message(locale, "presetNotSet"),
+            })}</li>
+            <li>{message(locale, "presetGalleryTitleSummary", {
+              title: currentExperience.gallery?.title ?? message(locale, "presetNotSet"),
+            })}</li>
+            <li>{message(locale, "presetGalleryAccentSummary", {
+              color: currentExperience.gallery?.accentColor ?? message(locale, "presetNotSet"),
+            })}</li>
+          </ul>
+        </div>
+      </div>
+
+      {loading ? (
+        <p className={styles.presetEmpty}>{message(locale, "presetLoading")}</p>
+      ) : loadError ? (
+        <p className={styles.presetLoadError}>{message(locale, "presetLoadError")}</p>
+      ) : presets.length === 0 ? (
+        <p className={styles.presetEmpty}>{message(locale, "presetEmpty")}</p>
+      ) : (
+        <ul className={styles.presetList}>
+          {presets.map((preset) => (
+            <li key={preset.id} data-selected={preset.id === selectedPresetId}>
+              <div>
+                <strong>{preset.label}</strong>
+                <bdi><code>{preset.id}</code></bdi>
+              </div>
+              <button
+                type="button"
+                disabled={disabled}
+                onClick={() => onRequestApply(preset.id)}
+              >
+                {applyingPresetId === preset.id
+                  ? message(locale, "presetApplyingAction")
+                  : message(locale, "presetReviewApplyAction")}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {confirmingPreset && (
+        <div className={styles.presetConfirm} role="group" aria-label={message(
+          locale,
+          "presetApplyAction",
+        )}>
+          <p>{message(locale, "presetApplyConfirmation", {
+            event,
+            preset: confirmingPreset.label,
+          })}</p>
+          <p className={styles.presetExact}>
+            <bdi><code>{confirmingPreset.id}</code></bdi>
+          </p>
+          {!hasBoothKey && (
+            <p className={styles.presetWarning}>{message(locale, "presetMissingBoothKey")}</p>
+          )}
+          <div>
+            <button
+              type="button"
+              disabled={disabled}
+              onClick={() => onConfirmApply(confirmingPreset.id)}
+            >
+              {applyingPresetId === confirmingPreset.id
+                ? message(locale, "presetApplyingAction")
+                : message(locale, "presetApplyAction")}
+            </button>
+            <button type="button" disabled={disabled} onClick={onCancelApply}>
+              {message(locale, "presetCancelAction")}
+            </button>
+          </div>
+        </div>
+      )}
+
+      <p className={styles.presetStatus} aria-live="polite" aria-atomic="true">
+        {successMessage}
+      </p>
+      <p className={styles.presetError} role="alert">{errorMessage}</p>
+    </section>
+  );
+}
diff --git a/app/[event]/admin/preset-state.test.ts b/app/[event]/admin/preset-state.test.ts
index 7c18e5c..713a908 100644
--- a/app/[event]/admin/preset-state.test.ts
+++ b/app/[event]/admin/preset-state.test.ts
@@ -1,9 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import type { EventPreset } from "../../event-preset";
 import {
+  buildPresetSaveBody,
+  clearPresetApplyAfterReconciliation,
   getOrCreatePresetApply,
   mergePresetPage,
+  parsePresetPageResponse,
   reconcileAppliedPreset,
+  shouldClearPresetApply,
 } from "./preset-state";
 
 const preset = (id: string, label: string, updatedAt = "2026-07-24T00:00:00.000Z"): EventPreset => ({
@@ -15,6 +19,95 @@ const preset = (id: string, label: string, updatedAt = "2026-07-24T00:00:00.000Z
   config: { frames: [id] },
 });
 
+test("strictly parses paged preset responses before merging them", () => {
+  const value = preset("launch", "Launch");
+  expect(parsePresetPageResponse({
+    presets: [value],
+    cursor: "opaque-cursor",
+  })).toEqual({
+    presets: [value],
+    cursor: "opaque-cursor",
+  });
+  expect(parsePresetPageResponse({
+    presets: [{ ...value, boothKey: "never" }],
+    cursor: null,
+  })).toBeNull();
+  expect(parsePresetPageResponse({
+    presets: [value],
+    cursor: 4,
+  })).toBeNull();
+});
+
+test("builds preset saves from the complete safe experience only", () => {
+  const body = buildPresetSaveBody({
+    label: "Launch",
+    expectedUpdatedAt: null,
+    experience: {
+      frames: ["square"],
+      locales: ["en", "ar"],
+      defaultLocale: "ar",
+      timeZone: "Asia/Singapore",
+      capture: {
+        reviewEnabled: false,
+        autoAcceptSeconds: 9,
+        countdownAudioDefault: true,
+      },
+      gallery: { title: "Night", accentColor: "#112233" },
+    },
+  });
+
+  expect(body).toEqual({
+    label: "Launch",
+    expectedUpdatedAt: null,
+    config: {
+      frames: ["square"],
+      locales: ["en", "ar"],
+      defaultLocale: "ar",
+      timeZone: "Asia/Singapore",
+      capture: {
+        reviewEnabled: false,
+        autoAcceptSeconds: 9,
+        countdownAudioDefault: true,
+      },
+      gallery: { title: "Night", accentColor: "#112233" },
+    },
+  });
+  expect(JSON.stringify(body)).not.toContain("booth");
+  expect(JSON.stringify(body)).not.toContain("revision");
+});
+
+test("retains ambiguous apply tuples until history reconciliation succeeds", async () => {
+  const pending = new Map();
+  const request = getOrCreatePresetApply(
+    pending,
+    "launch",
+    null,
+    () => "018f0000-0000-7000-8000-000000000030",
+  );
+
+  for (const failedStep of ["response parse", "history refresh"]) {
+    await expect(clearPresetApplyAfterReconciliation(
+      pending,
+      request,
+      async () => {
+        throw new Error(failedStep);
+      },
+    )).rejects.toThrow(failedStep);
+    expect(pending.get("launch")).toBe(request);
+  }
+  await clearPresetApplyAfterReconciliation(pending, request, async () => {});
+  expect(pending.has("launch")).toBe(false);
+});
+
+test("only definitive apply failures clear the retained tuple", () => {
+  for (const status of [400, 401, 404, 409]) {
+    expect(shouldClearPresetApply(status)).toBe(true);
+  }
+  for (const status of [0, 200, 408, 425, 429, 500, 503]) {
+    expect(shouldClearPresetApply(status)).toBe(false);
+  }
+});
+
 describe("Admin preset state", () => {
   test("deduplicates exact IDs, keeps updates, and globally orders label then ID", () => {
     expect(mergePresetPage(
diff --git a/app/[event]/admin/preset-state.ts b/app/[event]/admin/preset-state.ts
index e5bde44..793764d 100644
--- a/app/[event]/admin/preset-state.ts
+++ b/app/[event]/admin/preset-state.ts
@@ -1,5 +1,9 @@
 import type { EventExperience, PublicEventConfig } from "../../event-config";
-import type { EventPreset } from "../../event-preset";
+import {
+  parseEventPreset,
+  serializePresetExperience,
+  type EventPreset,
+} from "../../event-preset";
 import type { ConfigHistoryResponse } from "./config-mutation";
 
 export type PendingPresetApply = Readonly<{
@@ -8,6 +12,44 @@ export type PendingPresetApply = Readonly<{
   baseRevisionId: string | null;
 }>;
 
+export type PresetPageResponse = {
+  presets: EventPreset[];
+  cursor: string | null;
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function parsePresetPageResponse(value: unknown): PresetPageResponse | null {
+  if (
+    !isObject(value)
+    || Object.keys(value).some((key) => key !== "presets" && key !== "cursor")
+    || !Array.isArray(value.presets)
+    || (value.cursor !== null && typeof value.cursor !== "string")
+  ) {
+    return null;
+  }
+  const presets = value.presets.map(parseEventPreset);
+  if (presets.some((preset) => preset === null)) return null;
+  return {
+    presets: presets as EventPreset[],
+    cursor: value.cursor,
+  };
+}
+
+export function buildPresetSaveBody(input: {
+  label: string;
+  expectedUpdatedAt: string | null;
+  experience: EventExperience;
+}) {
+  return {
+    label: input.label,
+    config: serializePresetExperience(input.experience),
+    expectedUpdatedAt: input.expectedUpdatedAt,
+  };
+}
+
 export function mergePresetPage(
   current: readonly EventPreset[],
   incoming: readonly EventPreset[],
@@ -44,6 +86,21 @@ export function getOrCreatePresetApply(
   return created;
 }
 
+export function shouldClearPresetApply(status: number): boolean {
+  return [400, 401, 404, 409].includes(status);
+}
+
+export async function clearPresetApplyAfterReconciliation(
+  pending: Map<string, PendingPresetApply>,
+  request: PendingPresetApply,
+  reconcile: () => Promise<void>,
+): Promise<void> {
+  await reconcile();
+  if (pending.get(request.presetId) === request) {
+    pending.delete(request.presetId);
+  }
+}
+
 export function reconcileAppliedPreset(input: {
   response: PublicEventConfig & { currentRevisionId: string };
   history: ConfigHistoryResponse;
diff --git a/app/i18n/catalog.test.ts b/app/i18n/catalog.test.ts
index 9a71a46..2e2edb1 100644
--- a/app/i18n/catalog.test.ts
+++ b/app/i18n/catalog.test.ts
@@ -67,4 +67,14 @@ describe("guest message catalogs", () => {
     expect(message("ar", "moderationOpenPhoto", { filename: "photo.jpg" }))
       .toContain("photo.jpg");
   });
+
+  test("localizes the complete preset workflow in every supported locale", () => {
+    expect(message("en", "presetPanelTitle")).toBe("Event presets");
+    expect(message("zh-SG", "presetCreateAction")).toBe("创建预设");
+    expect(message("ar", "presetApplyAction")).toBe("تطبيق الإعداد المسبق");
+    expect(message("ar", "presetApplyConfirmation", {
+      event: "launch",
+      preset: "Night",
+    })).toContain("launch");
+  });
 });
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
index 8263867..b875c9c 100644
--- a/app/i18n/catalog.ts
+++ b/app/i18n/catalog.ts
@@ -124,6 +124,48 @@ export const englishMessages = {
   moderationCleanupPending:
     "The public photo is already deleted. Private cleanup is pending; do not retry the public deletion.",
   moderationDeleteError: "Photo could not be deleted.",
+  presetPanelTitle: "Event presets",
+  presetPanelDescription:
+    "Reuse the guest experience without copying Event identity or Booth credentials.",
+  presetIdLabel: "Preset ID",
+  presetLabelLabel: "Preset label",
+  presetLibraryLabel: "Saved presets",
+  presetSelectPlaceholder: "Create a new preset",
+  presetSaveSummaryTitle: "Save current setup as preset",
+  presetFramesSummary: "{count} frames",
+  presetLocalesSummary: "Languages: {locales}",
+  presetDefaultLocaleSummary: "Default: {locale}",
+  presetReviewSummary: "Review: {state}",
+  presetAutoAcceptSummary: "Auto-accept: {seconds}s",
+  presetAudioSummary: "Countdown audio: {state}",
+  presetTimeZoneSummary: "Time zone: {timeZone}",
+  presetGalleryTitleSummary: "Gallery: {title}",
+  presetGalleryAccentSummary: "Gallery accent: {color}",
+  presetOn: "on",
+  presetOff: "off",
+  presetNotSet: "Not set",
+  presetCreateAction: "Create preset",
+  presetUpdateAction: "Update preset",
+  presetSavingAction: "Saving preset…",
+  presetReviewApplyAction: "Review apply",
+  presetApplyAction: "Apply preset",
+  presetApplyingAction: "Applying…",
+  presetCancelAction: "Cancel",
+  presetReloadAction: "Reload presets",
+  presetLoading: "Loading presets…",
+  presetEmpty: "No presets yet. Save the current setup to create one.",
+  presetLoadError: "Presets could not be loaded. Other Admin controls remain available.",
+  presetApplyConfirmation:
+    "Apply preset {preset} to Event {event}? This replaces the safe guest experience.",
+  presetCredentialIsolation: "Booth credentials are never copied into presets.",
+  presetMissingBoothKey:
+    "The target Event has no Booth Key. Applying this preset will not add one.",
+  presetSaved: "Preset {preset} saved.",
+  presetApplied: "Applied preset {preset}.",
+  presetConflict:
+    "Presets or configuration changed. Review the latest versions before trying again.",
+  presetGenericError: "The preset action could not be completed. Retry when ready.",
+  presetSourceLabel: "Applied preset",
 } satisfies Record<string, string>;
 
 export type MessageKey = keyof typeof englishMessages;
@@ -240,6 +282,44 @@ export const chineseSingaporeMessages: Record<MessageKey, string> = {
   moderationDeleted: "照片已从公开活动中删除。",
   moderationCleanupPending: "公开照片已经删除。私有清理仍在进行；请勿再次删除公开照片。",
   moderationDeleteError: "无法删除照片。",
+  presetPanelTitle: "活动预设",
+  presetPanelDescription: "重复使用来宾体验，不复制活动身份或拍照亭凭据。",
+  presetIdLabel: "预设 ID",
+  presetLabelLabel: "预设名称",
+  presetLibraryLabel: "已保存的预设",
+  presetSelectPlaceholder: "创建新预设",
+  presetSaveSummaryTitle: "将当前设置保存为预设",
+  presetFramesSummary: "{count} 个相框",
+  presetLocalesSummary: "语言：{locales}",
+  presetDefaultLocaleSummary: "默认：{locale}",
+  presetReviewSummary: "照片检查：{state}",
+  presetAutoAcceptSummary: "自动接受：{seconds} 秒",
+  presetAudioSummary: "倒计时声音：{state}",
+  presetTimeZoneSummary: "时区：{timeZone}",
+  presetGalleryTitleSummary: "相册：{title}",
+  presetGalleryAccentSummary: "相册强调色：{color}",
+  presetOn: "开启",
+  presetOff: "关闭",
+  presetNotSet: "未设置",
+  presetCreateAction: "创建预设",
+  presetUpdateAction: "更新预设",
+  presetSavingAction: "正在保存预设…",
+  presetReviewApplyAction: "检查并应用",
+  presetApplyAction: "应用预设",
+  presetApplyingAction: "正在应用…",
+  presetCancelAction: "取消",
+  presetReloadAction: "重新加载预设",
+  presetLoading: "正在加载预设…",
+  presetEmpty: "尚无预设。保存当前设置即可创建。",
+  presetLoadError: "无法加载预设。其他管理员控件仍可使用。",
+  presetApplyConfirmation: "将预设 {preset} 应用于活动 {event}？这会替换安全的来宾体验。",
+  presetCredentialIsolation: "拍照亭凭据绝不会复制到预设中。",
+  presetMissingBoothKey: "目标活动没有拍照亭密钥。应用此预设不会添加密钥。",
+  presetSaved: "预设 {preset} 已保存。",
+  presetApplied: "已应用预设 {preset}。",
+  presetConflict: "预设或配置已更改。请检查最新版本后重试。",
+  presetGenericError: "无法完成预设操作。准备好后请重试。",
+  presetSourceLabel: "应用的预设",
 };
 
 export const arabicMessages: Record<MessageKey, string> = {
@@ -365,6 +445,47 @@ export const arabicMessages: Record<MessageKey, string> = {
   moderationCleanupPending:
     "الصورة العامة محذوفة بالفعل. التنظيف الخاص معلّق؛ لا تعاود حذف الصورة العامة.",
   moderationDeleteError: "تعذر حذف الصورة.",
+  presetPanelTitle: "إعدادات الحدث المسبقة",
+  presetPanelDescription:
+    "أعد استخدام تجربة الضيوف دون نسخ هوية الحدث أو بيانات اعتماد الكشك.",
+  presetIdLabel: "معرّف الإعداد المسبق",
+  presetLabelLabel: "اسم الإعداد المسبق",
+  presetLibraryLabel: "الإعدادات المسبقة المحفوظة",
+  presetSelectPlaceholder: "إنشاء إعداد مسبق جديد",
+  presetSaveSummaryTitle: "حفظ الإعداد الحالي كإعداد مسبق",
+  presetFramesSummary: "{count} إطارات",
+  presetLocalesSummary: "اللغات: {locales}",
+  presetDefaultLocaleSummary: "الافتراضية: {locale}",
+  presetReviewSummary: "المراجعة: {state}",
+  presetAutoAcceptSummary: "القبول التلقائي: {seconds} ث",
+  presetAudioSummary: "صوت العد التنازلي: {state}",
+  presetTimeZoneSummary: "المنطقة الزمنية: {timeZone}",
+  presetGalleryTitleSummary: "المعرض: {title}",
+  presetGalleryAccentSummary: "لون المعرض: {color}",
+  presetOn: "مفعّل",
+  presetOff: "متوقف",
+  presetNotSet: "غير محدد",
+  presetCreateAction: "إنشاء إعداد مسبق",
+  presetUpdateAction: "تحديث الإعداد المسبق",
+  presetSavingAction: "جارٍ حفظ الإعداد المسبق…",
+  presetReviewApplyAction: "مراجعة التطبيق",
+  presetApplyAction: "تطبيق الإعداد المسبق",
+  presetApplyingAction: "جارٍ التطبيق…",
+  presetCancelAction: "إلغاء",
+  presetReloadAction: "إعادة تحميل الإعدادات المسبقة",
+  presetLoading: "جارٍ تحميل الإعدادات المسبقة…",
+  presetEmpty: "لا توجد إعدادات مسبقة بعد. احفظ الإعداد الحالي لإنشاء واحد.",
+  presetLoadError: "تعذر تحميل الإعدادات المسبقة. تبقى أدوات الإدارة الأخرى متاحة.",
+  presetApplyConfirmation:
+    "هل تريد تطبيق الإعداد المسبق {preset} على الحدث {event}؟ سيستبدل ذلك تجربة الضيوف الآمنة.",
+  presetCredentialIsolation: "لا تُنسخ بيانات اعتماد الكشك أبدًا إلى الإعدادات المسبقة.",
+  presetMissingBoothKey:
+    "لا يحتوي الحدث المستهدف على مفتاح كشك. لن يضيف تطبيق هذا الإعداد المسبق مفتاحًا.",
+  presetSaved: "تم حفظ الإعداد المسبق {preset}.",
+  presetApplied: "تم تطبيق الإعداد المسبق {preset}.",
+  presetConflict: "تغيّرت الإعدادات المسبقة أو التكوين. راجع أحدث الإصدارات قبل المحاولة.",
+  presetGenericError: "تعذر إكمال إجراء الإعداد المسبق. أعد المحاولة عندما تكون جاهزًا.",
+  presetSourceLabel: "الإعداد المسبق المطبق",
 };
 
 const catalogs: Record<SupportedLocale, Record<MessageKey, string>> = {

From ba99180030c675c885b463ccb1d2a7f39822c5aa Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:03:25 +0800
Subject: [PATCH 098/105] fix: preserve preset edit concurrency

---
 app/[event]/admin/page.tsx | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index b7d7aad..3bb00de 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -120,6 +120,7 @@ export default function Admin() {
   const [presetsLoading, setPresetsLoading] = useState(false);
   const [presetsError, setPresetsError] = useState("");
   const [selectedPresetId, setSelectedPresetId] = useState<string | null>(null);
+  const [selectedPresetUpdatedAt, setSelectedPresetUpdatedAt] = useState<string | null>(null);
   const [presetIdDraft, setPresetIdDraft] = useState("");
   const [presetLabelDraft, setPresetLabelDraft] = useState("");
   const [presetSaving, setPresetSaving] = useState(false);
@@ -859,6 +860,7 @@ export default function Admin() {
     setPresetActionError("");
     setPresetNotice("");
     const selected = presets.find((preset) => preset.id === presetId);
+    setSelectedPresetUpdatedAt(selected?.updatedAt ?? null);
     setPresetIdDraft(selected?.id ?? "");
     setPresetLabelDraft(selected?.label ?? "");
   };
@@ -871,7 +873,6 @@ export default function Admin() {
       setPresetActionError(message(defaultLocale, "presetGenericError"));
       return;
     }
-    const selected = presets.find((preset) => preset.id === selectedPresetId);
     configMutationBusy.current = true;
     setPresetSaving(true);
     setPresetActionError("");
@@ -888,7 +889,10 @@ export default function Admin() {
           },
           body: JSON.stringify(buildPresetSaveBody({
             label,
-            expectedUpdatedAt: selected?.updatedAt ?? null,
+            // Keep the compare-and-set token paired with the draft the
+            // operator actually opened. Background reloads must not silently
+            // advance it past another operator's edit.
+            expectedUpdatedAt: selectedPresetUpdatedAt,
             experience: currentExperience,
           })),
         },
@@ -901,6 +905,7 @@ export default function Admin() {
         const latest = await loadPresets();
         const refreshed = latest?.find((preset) => preset.id === presetId);
         setSelectedPresetId(refreshed?.id ?? null);
+        setSelectedPresetUpdatedAt(refreshed?.updatedAt ?? null);
         setPresetIdDraft(refreshed?.id ?? "");
         setPresetLabelDraft(refreshed?.label ?? "");
         setPresetActionError(message(defaultLocale, "presetConflict"));
@@ -911,15 +916,12 @@ export default function Admin() {
       if (!saved) throw new Error("Preset response had an unexpected shape");
       setPresets((current) => mergePresetPage(current, [saved]));
       setSelectedPresetId(saved.id);
+      setSelectedPresetUpdatedAt(saved.updatedAt);
       setPresetIdDraft(saved.id);
       setPresetLabelDraft(saved.label);
       setPresetNotice(message(defaultLocale, "presetSaved", { preset: saved.label }));
-    } catch (cause) {
-      setPresetActionError(
-        cause instanceof Error
-          ? cause.message
-          : message(defaultLocale, "presetGenericError"),
-      );
+    } catch {
+      setPresetActionError(message(defaultLocale, "presetGenericError"));
     } finally {
       configMutationBusy.current = false;
       setPresetSaving(false);
@@ -1005,12 +1007,8 @@ export default function Admin() {
       setPresetNotice(message(defaultLocale, "presetApplied", {
         preset: preset.label,
       }));
-    } catch (cause) {
-      setPresetActionError(
-        cause instanceof Error
-          ? cause.message
-          : message(defaultLocale, "presetGenericError"),
-      );
+    } catch {
+      setPresetActionError(message(defaultLocale, "presetGenericError"));
     } finally {
       configMutationBusy.current = false;
       setApplyingPresetId(null);

From 8e1d513d87a9e63b6e8532a4b244103d336c64e0 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:07:35 +0800
Subject: [PATCH 099/105] test: cover admin moderation browser journeys

---
 tests/gallery-moderation.spec.ts | 342 +++++++++++++++++++++++++++++++
 1 file changed, 342 insertions(+)

diff --git a/tests/gallery-moderation.spec.ts b/tests/gallery-moderation.spec.ts
index 5577838..4598ec1 100644
--- a/tests/gallery-moderation.spec.ts
+++ b/tests/gallery-moderation.spec.ts
@@ -2,6 +2,8 @@ import AxeBuilder from "@axe-core/playwright";
 import { expect, test, type BrowserContext, type Page } from "@playwright/test";
 
 const EVENT = "gallery-browser";
+const ADMIN_EVENT = "moderation-browser";
+const ADMIN_KEY = "browser-admin-secret";
 const PIXEL =
   "data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=";
 const first = {
@@ -19,6 +21,49 @@ const third = {
   url: PIXEL,
   uploadedAt: "2026-07-24T00:00:03.000Z",
 };
+const moderationFirst = {
+  key: `${ADMIN_EVENT}/1753315200004-first.jpg`,
+  url: PIXEL,
+  uploadedAt: "2026-07-24T00:00:04.000Z",
+  capturedAt: 1753315200004,
+  source: "framed",
+  frameKey: "square",
+};
+const moderationSecond = {
+  key: `${ADMIN_EVENT}/1753315200003-second.jpg`,
+  url: PIXEL,
+  uploadedAt: "2026-07-24T00:00:03.000Z",
+  capturedAt: 1753315200003,
+  source: "camera-fallback",
+};
+const moderationThird = {
+  key: `${ADMIN_EVENT}/1753315200002-third.jpg`,
+  url: PIXEL,
+  uploadedAt: "2026-07-24T00:00:02.000Z",
+  capturedAt: 1753315200002,
+};
+const moderationFiltered = {
+  key: `${ADMIN_EVENT}/1753315200005-filtered.jpg`,
+  url: PIXEL,
+  uploadedAt: "2026-07-24T00:00:05.000Z",
+  capturedAt: 1753315200005,
+};
+
+type ModerationApiRequest = {
+  method: string;
+  pathname: string;
+  key: string;
+  search: string;
+};
+
+type ModerationFixture = {
+  requests: ModerationApiRequest[];
+  deletedKeys: Set<string>;
+  cleanupPending: boolean;
+  delayedCursor: boolean;
+  rebuildCalls: number;
+  locale: "en" | "ar";
+};
 
 async function seriousA11yViolations(page: Page) {
   return (await new AxeBuilder({ page }).analyze()).violations.filter(
@@ -26,6 +71,14 @@ async function seriousA11yViolations(page: Page) {
   );
 }
 
+async function seriousStructuralA11yViolations(page: Page) {
+  return (await new AxeBuilder({ page }).analyze()).violations.filter(
+    ({ id, impact }) =>
+      id !== "color-contrast"
+      && (impact === "serious" || impact === "critical"),
+  );
+}
+
 async function installGalleryRoutes(
   context: BrowserContext,
   options: { delayedFeed?: boolean } = {},
@@ -70,6 +123,136 @@ async function installGalleryRoutes(
   };
 }
 
+async function installModerationRoutes(
+  context: BrowserContext,
+  fixture: ModerationFixture,
+) {
+  await context.route("**/api/**", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    const key = request.headers()["x-booth-key"] ?? "";
+    fixture.requests.push({
+      method: request.method(),
+      pathname: url.pathname,
+      key,
+      search: url.search,
+    });
+
+    if (url.pathname === "/api/health") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          upload: { status: "up", detail: "fixture" },
+          live: { status: "up", detail: "fixture" },
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/config/revisions") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          config: {
+            frames: ["square"],
+            hasBoothKey: true,
+            locales: ["en", "zh-SG", "ar"],
+            defaultLocale: fixture.locale,
+            timeZone: "Asia/Singapore",
+          },
+          currentRevisionId: null,
+          revisions: [],
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/booth-state") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          version: 1,
+          paused: false,
+          updatedAt: "2026-07-24T12:00:00.000Z",
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/booths") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ booths: [], cursor: null }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/moderation/photos/rebuild") {
+      fixture.rebuildCalls += 1;
+      const complete = fixture.rebuildCalls >= 2;
+      await route.fulfill({
+        status: complete ? 200 : 202,
+        contentType: "application/json",
+        body: JSON.stringify({
+          complete,
+          scanned: complete ? 500 : 250,
+          indexed: complete ? 498 : 249,
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/moderation/photos") {
+      const cursor = url.searchParams.get("cursor");
+      if (cursor === "page-2" && fixture.delayedCursor) {
+        await new Promise((resolve) => setTimeout(resolve, 650));
+      }
+      const candidates = url.searchParams.has("from")
+        ? [moderationFiltered]
+        : cursor === "page-2"
+          ? [moderationThird]
+          : [moderationFirst, moderationSecond];
+      const photos = candidates.filter(
+        (photo) => !fixture.deletedKeys.has(photo.key),
+      );
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          photos,
+          nextCursor: cursor || url.searchParams.has("from") ? null : "page-2",
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/photos" && request.method() === "DELETE") {
+      const exactKey = url.searchParams.get("key") ?? "";
+      fixture.deletedKeys.add(exactKey);
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          deleted: true,
+          key: exactKey,
+          cleanupPending: fixture.cleanupPending,
+        }),
+      });
+      return;
+    }
+    throw new Error(
+      `Unexpected Admin API request: ${request.method()} ${url.pathname}`,
+    );
+  });
+}
+
+async function unlockModeration(page: Page, heading = "Event moderation") {
+  await page.goto(`/${ADMIN_EVENT}/admin`);
+  const input = page.getByLabel("Admin key");
+  await input.fill(ADMIN_KEY);
+  await input.press("Enter");
+  await expect(page.getByRole("heading", { name: ADMIN_EVENT })).toBeVisible();
+  await expect(page.getByRole("heading", { name: heading })).toBeVisible();
+}
+
 test("phone browse opens an exact deep link before its slow feed and restores URL/focus", async ({
   context,
   page,
@@ -145,3 +328,162 @@ test("projector retains photos across feed errors, retries, and exposes the brow
   expect(maximumActive).toBe(1);
   expect(await seriousA11yViolations(page)).toEqual([]);
 });
+
+test("Admin moderation rejects a stale page after filtering and restores dialog focus", async ({
+  context,
+  page,
+}) => {
+  const fixture: ModerationFixture = {
+    requests: [],
+    deletedKeys: new Set(),
+    cleanupPending: false,
+    delayedCursor: true,
+    rebuildCalls: 0,
+    locale: "en",
+  };
+  await installModerationRoutes(context, fixture);
+  await unlockModeration(page);
+
+  await expect(page.getByText("2 photos loaded")).toBeVisible();
+  await page.getByRole("button", { name: "Load more" }).click();
+  await expect.poll(() =>
+    fixture.requests.some(({ pathname, search }) =>
+      pathname === "/api/moderation/photos" && search.includes("cursor=page-2")
+    )
+  ).toBe(true);
+
+  await page.getByLabel("From").fill("2026-07-24T00:00");
+  await page.getByRole("button", { name: "Apply filters" }).click();
+  await expect(
+    page.getByRole("button", { name: "Open photo 1753315200005-filtered.jpg" }),
+  ).toBeVisible();
+  await page.waitForTimeout(800);
+  await expect(page.getByText("1 photos loaded")).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "Open photo 1753315200002-third.jpg" }),
+  ).toHaveCount(0);
+
+  const filteredRequest = fixture.requests.find(
+    ({ pathname, search }) =>
+      pathname === "/api/moderation/photos" && search.includes("from="),
+  );
+  expect(filteredRequest?.key).toBe(ADMIN_KEY);
+  expect(filteredRequest?.search).toContain(`event=${ADMIN_EVENT}`);
+  expect(filteredRequest?.search).not.toContain(ADMIN_KEY);
+
+  await page.getByRole("button", { name: "Clear filters" }).click();
+  await expect(page.getByText("2 photos loaded")).toBeVisible();
+  const firstTile = page.getByRole("button", {
+    name: "Open photo 1753315200004-first.jpg",
+  });
+  await firstTile.focus();
+  await firstTile.click();
+  const dialog = page.getByRole("dialog", { name: "Inspect photo" });
+  await expect(dialog).toBeVisible();
+  await expect(dialog.getByRole("button", { name: "Close" })).toBeFocused();
+  await page.keyboard.press("ArrowRight");
+  await expect(dialog.getByText("Photo 2 of 2 loaded")).toBeVisible();
+  await expect(dialog.getByText("1753315200003-second.jpg")).toBeVisible();
+  await page.keyboard.press("ArrowLeft");
+  await expect(dialog.getByText("Photo 1 of 2 loaded")).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(dialog).toHaveCount(0);
+  await expect(firstTile).toBeFocused();
+  expect(await seriousStructuralA11yViolations(page)).toEqual([]);
+});
+
+test("Admin exact deletion does not repeat public removal and rebuild advances one batch per click", async ({
+  context,
+  page,
+}) => {
+  const fixture: ModerationFixture = {
+    requests: [],
+    deletedKeys: new Set(),
+    cleanupPending: true,
+    delayedCursor: false,
+    rebuildCalls: 0,
+    locale: "en",
+  };
+  await installModerationRoutes(context, fixture);
+  await unlockModeration(page);
+  await expect(page.getByText("2 photos loaded")).toBeVisible();
+
+  await page.getByRole("button", {
+    name: "Open photo 1753315200004-first.jpg",
+  }).click();
+  const dialog = page.getByRole("dialog", { name: "Inspect photo" });
+  await dialog.getByRole("button", { name: "Remove photo" }).click();
+  await expect(dialog.getByText(moderationFirst.key, { exact: true })).toBeVisible();
+  await dialog.getByRole("button", { name: "Confirm exact deletion" }).click();
+  await expect(dialog.getByText(/public photo is already deleted/i)).toBeVisible();
+  await expect(dialog.getByRole("button", { name: "Remove photo" })).toHaveCount(0);
+  await expect(page.getByRole("button", {
+    name: "Open photo 1753315200004-first.jpg",
+  })).toHaveCount(0);
+  await page.waitForTimeout(100);
+
+  const deletionRequests = () => fixture.requests.filter(
+    ({ method, pathname }) => method === "DELETE" && pathname === "/api/photos",
+  );
+  expect(deletionRequests()).toEqual([{
+    method: "DELETE",
+    pathname: "/api/photos",
+    key: ADMIN_KEY,
+    search:
+      `?event=${ADMIN_EVENT}&key=${encodeURIComponent(moderationFirst.key)}`,
+  }]);
+  await dialog.getByRole("button", { name: "Close" }).click();
+  expect(deletionRequests()).toHaveLength(1);
+
+  await page.getByRole("button", { name: "Start rebuild" }).click();
+  await expect(page.getByText("Scanned 250; indexed 249.")).toBeVisible();
+  await page.waitForTimeout(100);
+  expect(fixture.rebuildCalls).toBe(1);
+  await page.getByRole("button", { name: "Continue rebuild" }).click();
+  await expect(page.getByText("Index rebuild complete.")).toBeVisible();
+  expect(fixture.rebuildCalls).toBe(2);
+  const rebuildRequests = fixture.requests.filter(
+    ({ method, pathname }) =>
+      method === "POST" && pathname === "/api/moderation/photos/rebuild",
+  );
+  expect(rebuildRequests).toHaveLength(2);
+  expect(rebuildRequests.every(({ key, search }) =>
+    key === ADMIN_KEY && search === `?event=${ADMIN_EVENT}`
+  )).toBe(true);
+});
+
+test("Arabic moderation remains keyboard-usable at 200% in forced colors", async ({
+  context,
+  page,
+}) => {
+  const fixture: ModerationFixture = {
+    requests: [],
+    deletedKeys: new Set(),
+    cleanupPending: false,
+    delayedCursor: false,
+    rebuildCalls: 0,
+    locale: "ar",
+  };
+  await installModerationRoutes(context, fixture);
+  await page.emulateMedia({ forcedColors: "active", reducedMotion: "reduce" });
+  await unlockModeration(page, "إشراف صور الفعالية");
+  await page.evaluate(() => {
+    document.documentElement.style.zoom = "2";
+  });
+
+  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");
+  const tile = page.getByRole("button", {
+    name: "افتح الصورة 1753315200004-first.jpg",
+  });
+  await tile.scrollIntoViewIfNeeded();
+  await tile.focus();
+  await page.keyboard.press("Enter");
+  const dialog = page.getByRole("dialog", { name: "افحص الصورة" });
+  await expect(dialog).toBeVisible();
+  await expect(dialog.getByRole("button", { name: "إغلاق" })).toBeFocused();
+  await page.keyboard.press("Escape");
+  await expect(dialog).toHaveCount(0);
+  await expect(tile).toBeFocused();
+  await expect(page.getByRole("button", { name: "ابدأ إعادة البناء" })).toBeVisible();
+  expect(await seriousStructuralA11yViolations(page)).toEqual([]);
+});

From 0072cbea98b1223946bedd155e29365c61b0c4cb Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:14:49 +0800
Subject: [PATCH 100/105] feat: guide durable real-device rehearsals

---
 app/[event]/admin/admin.module.css            |  45 +++
 app/[event]/admin/page.tsx                    |   9 +
 app/[event]/admin/rehearsal-panel.test.tsx    |  21 ++
 app/[event]/admin/rehearsal-panel.tsx         | 342 ++++++++++++++++++
 .../booth-session/rehearsal-client.test.ts    | 106 ++++++
 app/[event]/booth-session/rehearsal-client.ts | 250 +++++++++++++
 .../rehearsal-evidence-outbox.test.ts         |  71 ++++
 .../rehearsal-evidence-outbox.ts              | 122 +++++++
 app/[event]/booth-session/session.test.ts     |  68 ++++
 app/[event]/booth-session/session.ts          |  26 ++
 app/[event]/booth.module.css                  |  38 ++
 app/[event]/page.tsx                          | 119 +++++-
 app/[event]/rehearsal-status.test.tsx         |  30 ++
 app/[event]/rehearsal-status.tsx              |  53 +++
 app/i18n/catalog.ts                           | 150 ++++++++
 15 files changed, 1447 insertions(+), 3 deletions(-)
 create mode 100644 app/[event]/admin/rehearsal-panel.test.tsx
 create mode 100644 app/[event]/admin/rehearsal-panel.tsx
 create mode 100644 app/[event]/booth-session/rehearsal-client.test.ts
 create mode 100644 app/[event]/booth-session/rehearsal-client.ts
 create mode 100644 app/[event]/booth-session/rehearsal-evidence-outbox.test.ts
 create mode 100644 app/[event]/booth-session/rehearsal-evidence-outbox.ts
 create mode 100644 app/[event]/rehearsal-status.test.tsx
 create mode 100644 app/[event]/rehearsal-status.tsx

diff --git a/app/[event]/admin/admin.module.css b/app/[event]/admin/admin.module.css
index 2e33c47..1229d88 100644
--- a/app/[event]/admin/admin.module.css
+++ b/app/[event]/admin/admin.module.css
@@ -188,3 +188,48 @@
 @media (max-width: 600px) { .experiencePanel { grid-template-columns: 1fr; }.localeOptions { grid-template-columns: 1fr; }.experienceField { grid-template-columns: 1fr; gap: 6px; } }
 @media (max-width: 700px) { .presetHeading, .presetWorkspace { grid-template-columns: 1fr; }.presetLibraryRow { grid-template-columns: 1fr; }.presetList { grid-template-columns: 1fr; }.presetList li { grid-template-columns: 1fr; }.presetList button { width: 100%; }.presetConfirm > div { display: grid; grid-template-columns: 1fr; } }
 @media (prefers-reduced-motion: reduce) { .console *, .console *::before, .console *::after, .authPage *, .authPage *::before, .authPage *::after { scroll-behavior: auto !important; animation: none !important; transition: none !important; } }
+
+.rehearsalPanel { border-block: 3px solid var(--ink); padding-block: 20px; }
+.rehearsalHead { display: flex; align-items: flex-start; justify-content: space-between; gap: 18px; }
+.rehearsalHead span { color: var(--pink); font: 800 10px/1 ui-monospace, monospace; text-transform: uppercase; }
+.rehearsalHead h2 { margin-top: 8px; font: 900 clamp(30px, 4vw, 52px)/.9 Impact, "Arial Narrow", sans-serif; text-transform: uppercase; }
+.rehearsalHead p { max-width: 60ch; margin-top: 8px; font-size: 13px; line-height: 1.4; }
+.rehearsalHead button, .rehearsalPanel button { min-height: 44px; border: 2px solid var(--ink); padding: 10px 12px; color: var(--ink); background: var(--amber); font: 800 11px/1.15 system-ui, sans-serif; cursor: pointer; }
+.rehearsalPanel button:disabled { cursor: wait; opacity: .55; }
+.rehearsalConfirm { max-width: 260px; border: 2px solid var(--ink); padding: 10px; background: #fff; }
+.rehearsalConfirm button { margin: 7px 7px 0 0; }
+.rehearsalLive { min-height: 20px; margin-top: 9px; color: #8f1239; font-weight: 800; }
+.rehearsalIdentity { display: grid; grid-template-columns: minmax(0, 1fr) 120px; gap: 14px; margin-top: 10px; border: 2px solid var(--ink); padding: 13px; color: #fff; background: var(--ink); }
+.rehearsalIdentity strong, .rehearsalIdentity code, .rehearsalIdentity a { display: block; overflow-wrap: anywhere; }
+.rehearsalIdentity code { margin-block: 8px; color: var(--amber); font-size: 10px; }
+.rehearsalIdentity a { color: #fff; font-size: 12px; }
+.rehearsalIdentity img { width: 120px; height: 120px; padding: 5px; background: #fff; }
+.rehearsalRequirements { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 7px; margin: 12px 0; padding: 0; list-style: none; }
+.rehearsalRequirements li { border-inline-start: 7px solid var(--pink); padding: 10px; background: #fff; font-weight: 800; }
+.rehearsalRequirements li[data-complete="true"] { border-color: var(--green); }
+.rehearsalRequirements li span { margin-inline-end: 8px; }
+.rehearsalManual { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; border: 2px solid var(--ink); padding: 12px; }
+.rehearsalManual legend { padding-inline: 7px; font-weight: 900; }
+.rehearsalManual label { display: flex; min-height: 44px; align-items: center; gap: 9px; padding: 7px; background: #fff; font-size: 12px; font-weight: 700; }
+.rehearsalManual input { inline-size: 22px; block-size: 22px; }
+.rehearsalPhotos { margin-top: 14px; }
+.rehearsalPhotos h3 { font: 900 22px/1 Impact, sans-serif; text-transform: uppercase; }
+.rehearsalPhotos ul { display: grid; gap: 8px; margin-top: 8px; padding: 0; list-style: none; }
+.rehearsalPhotos li { position: relative; border: 2px solid var(--ink); padding: 11px; background: #fff; }
+.rehearsalPhotos li > bdi, .rehearsalPhotos li > span { display: block; }
+.rehearsalPhotos code { overflow-wrap: anywhere; font-size: 10px; }
+.rehearsalPhotos li > div { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 9px; }
+.rehearsalDeleteConfirm { border: 2px solid var(--pink); padding: 12px; color: #fff; background: var(--ink); }
+.rehearsalDeleteConfirm strong, .rehearsalDeleteConfirm span, .rehearsalDeleteConfirm bdi { flex-basis: 100%; }
+.rehearsalDeleteConfirm code { color: var(--amber); }
+.rehearsalAbandon { width: 100%; margin-top: 10px; border-style: dashed !important; background: #fff !important; }
+
+@media (forced-colors: active) {
+  .rehearsalPanel button:focus-visible, .rehearsalPanel input:focus-visible, .rehearsalPanel a:focus-visible { outline: 3px solid Highlight !important; outline-offset: 3px; }
+  .rehearsalIdentity, .rehearsalDeleteConfirm { border-color: CanvasText; background: Canvas; color: CanvasText; }
+}
+@media (max-width: 600px) {
+  .rehearsalHead { flex-direction: column; }
+  .rehearsalIdentity { grid-template-columns: 1fr; }
+  .rehearsalRequirements, .rehearsalManual { grid-template-columns: 1fr; }
+}
diff --git a/app/[event]/admin/page.tsx b/app/[event]/admin/page.tsx
index 3bb00de..5338e4a 100644
--- a/app/[event]/admin/page.tsx
+++ b/app/[event]/admin/page.tsx
@@ -35,6 +35,7 @@ import {
 import { BoothOperationsPanel } from "./booth-operations-panel";
 import { ConfigHistoryPanel } from "./config-history-panel";
 import { ExportPanel } from "./export-panel";
+import { RehearsalPanel } from "./rehearsal-panel";
 import { ModerationDialog } from "./moderation-dialog";
 import {
   ModerationPanel,
@@ -1261,6 +1262,14 @@ export default function Admin() {
             onResume={() => void updateBoothOperationalState(false)}
           />
 
+          <RehearsalPanel
+            event={event}
+            adminKey={adminKey}
+            locale={uiLocale}
+            origin={origin}
+            onUnauthorized={invalidateAuth}
+          />
+
           <ModerationPanel
             locale={uiLocale}
             photos={photos}
diff --git a/app/[event]/admin/rehearsal-panel.test.tsx b/app/[event]/admin/rehearsal-panel.test.tsx
new file mode 100644
index 0000000..def2093
--- /dev/null
+++ b/app/[event]/admin/rehearsal-panel.test.tsx
@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { RehearsalPanel } from "./rehearsal-panel";
+
+test("renders an accessible localized start surface without exposing the Admin Key", () => {
+  const html = renderToStaticMarkup(
+    <RehearsalPanel
+      event="launch"
+      adminKey="never-render-this-secret"
+      locale="zh-SG"
+      origin="https://booth.example"
+      onUnauthorized={() => {}}
+    />,
+  );
+  expect(html).toContain('aria-labelledby="rehearsal-panel-title"');
+  expect(html).toContain('aria-live="polite"');
+  expect(html).toContain("真实设备演练");
+  expect(html).toContain("开始演练");
+  expect(html).not.toContain("never-render-this-secret");
+  expect(html).not.toMatch(/cleanup all|bulk delete/i);
+});
diff --git a/app/[event]/admin/rehearsal-panel.tsx b/app/[event]/admin/rehearsal-panel.tsx
new file mode 100644
index 0000000..955fbc0
--- /dev/null
+++ b/app/[event]/admin/rehearsal-panel.tsx
@@ -0,0 +1,342 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import QRCode from "qrcode";
+import {
+  type ManualCheck,
+  type RehearsalEvidenceInput,
+  type RehearsalRequirement,
+  type RehearsalSession,
+  type RehearsalSummary,
+} from "../../rehearsal";
+import { message, type SupportedLocale } from "../../i18n/catalog";
+import styles from "./admin.module.css";
+
+type RehearsalView = {
+  session: RehearsalSession;
+  summary: RehearsalSummary;
+};
+type WithoutEvidenceEnvelope<T> = T extends unknown
+  ? Omit<T, "version" | "id" | "rehearsalId" | "observedAt">
+  : never;
+type EvidenceFields = WithoutEvidenceEnvelope<RehearsalEvidenceInput>;
+
+const requirements: RehearsalRequirement[] = [
+  "booth-ready", "frames-covered", "two-network-failures", "reload-recovered",
+  "ordered-drain", "public-delivery", "canary-deleted", "outbox-empty",
+];
+const manualChecks: ManualCheck[] = [
+  "composition", "projector", "power", "charging", "backup-network",
+];
+
+const requirementKeys: Record<RehearsalRequirement, Parameters<typeof message>[1]> = {
+  "booth-ready": "rehearsalReqBoothReady",
+  "frames-covered": "rehearsalReqFrames",
+  "two-network-failures": "rehearsalReqFailures",
+  "reload-recovered": "rehearsalReqReload",
+  "ordered-drain": "rehearsalReqDrain",
+  "public-delivery": "rehearsalReqDelivery",
+  "canary-deleted": "rehearsalReqCanary",
+  "outbox-empty": "rehearsalReqEmpty",
+};
+const manualKeys: Record<ManualCheck, Parameters<typeof message>[1]> = {
+  composition: "rehearsalManualComposition",
+  projector: "rehearsalManualProjector",
+  power: "rehearsalManualPower",
+  charging: "rehearsalManualCharging",
+  "backup-network": "rehearsalManualBackup",
+};
+
+export function RehearsalPanel({
+  event,
+  adminKey,
+  locale,
+  origin,
+  onUnauthorized,
+}: {
+  event: string;
+  adminKey: string;
+  locale: SupportedLocale;
+  origin: string;
+  onUnauthorized: () => void;
+}) {
+  const [view, setView] = useState<RehearsalView | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [busy, setBusy] = useState("");
+  const [error, setError] = useState("");
+  const [confirmStart, setConfirmStart] = useState(false);
+  const [confirmDelete, setConfirmDelete] = useState<string | null>(null);
+  const [qr, setQr] = useState("");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const readInFlight = useRef(false);
+  const stopped = useRef(false);
+  const confirmedCanaryDeletes = useRef(new Map<string, boolean>());
+  const deleteTrigger = useRef<HTMLButtonElement | null>(null);
+
+  const label = useCallback(
+    (key: Parameters<typeof message>[1], values?: Record<string, string | number>) =>
+      message(locale, key, values),
+    [locale],
+  );
+  const rehearsalUrl = view && origin
+    ? `${origin}/${event}?rehearsal=${encodeURIComponent(view.session.id)}`
+    : "";
+
+  const request = useCallback(async (url: string, init?: RequestInit) => {
+    const response = await fetch(url, {
+      cache: "no-store",
+      ...init,
+      headers: {
+        ...init?.headers,
+        "x-booth-key": adminKey,
+      },
+    });
+    if (response.status === 401) {
+      onUnauthorized();
+      throw new Error(label("rehearsalUnauthorized"));
+    }
+    return response;
+  }, [adminKey, label, onUnauthorized]);
+
+  const load = useCallback(async () => {
+    if (readInFlight.current) return;
+    readInFlight.current = true;
+    if (timer.current) clearTimeout(timer.current);
+    try {
+      const response = await request(`/api/rehearsals?event=${encodeURIComponent(event)}`);
+      if (response.status === 404) {
+        if (!stopped.current) setView(null);
+        return;
+      }
+      if (!response.ok) throw new Error(label("rehearsalLoadError"));
+      const payload = await response.json() as { rehearsal?: RehearsalView };
+      if (!payload.rehearsal?.session || !payload.rehearsal.summary) {
+        throw new Error(label("rehearsalLoadError"));
+      }
+      if (!stopped.current) {
+        setView(payload.rehearsal);
+        setError("");
+      }
+    } catch (cause) {
+      if (!stopped.current) setError(cause instanceof Error ? cause.message : label("rehearsalLoadError"));
+    } finally {
+      readInFlight.current = false;
+      if (!stopped.current) {
+        setLoading(false);
+        timer.current = setTimeout(() => void load(), 5_000);
+      }
+    }
+  }, [event, label, request]);
+
+  useEffect(() => {
+    stopped.current = false;
+    void load();
+    return () => {
+      stopped.current = true;
+      if (timer.current) clearTimeout(timer.current);
+    };
+  }, [load]);
+
+  useEffect(() => {
+    if (!rehearsalUrl) { setQr(""); return; }
+    void QRCode.toDataURL(rehearsalUrl, { width: 200, margin: 1 }).then(setQr).catch(() => setQr(""));
+  }, [rehearsalUrl]);
+
+  const start = async () => {
+    setBusy("start"); setError("");
+    try {
+      const id = crypto.randomUUID();
+      const response = await request(`/api/rehearsals?event=${encodeURIComponent(event)}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ rehearsalId: id }),
+      });
+      if (!response.ok) throw new Error(label("rehearsalStartError"));
+      setConfirmStart(false);
+      await load();
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : label("rehearsalStartError"));
+    } finally { setBusy(""); }
+  };
+
+  const append = async (
+    fields: EvidenceFields,
+  ) => {
+    if (!view) return;
+    const response = await request(
+      `/api/rehearsals/evidence?event=${encodeURIComponent(event)}&id=${encodeURIComponent(view.session.id)}`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          version: 1,
+          id: crypto.randomUUID(),
+          rehearsalId: view.session.id,
+          observedAt: Date.now(),
+          ...fields,
+        }),
+      },
+    );
+    if (!response.ok) throw new Error(label("rehearsalActionError"));
+    await load();
+  };
+
+  const disposition = async (photoKey: string, action: "retain" | "delete") => {
+    setBusy(`${action}:${photoKey}`); setError("");
+    try {
+      if (action === "delete") {
+        const query = new URLSearchParams({ event, key: photoKey });
+        const response = await request(`/api/photos?${query}`, { method: "DELETE" });
+        if (!response.ok) throw new Error(label("rehearsalActionError"));
+      }
+      await append({ kind: action === "retain" ? "photo-retained" : "photo-deleted", photoKey });
+      setConfirmDelete(null);
+      requestAnimationFrame(() => deleteTrigger.current?.focus());
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : label("rehearsalActionError"));
+    } finally { setBusy(""); }
+  };
+
+  const observeDelivery = async (photoKey: string) => {
+    setBusy("delivery"); setError("");
+    try {
+      const response = await fetch(`/api/photos?event=${encodeURIComponent(event)}`, { cache: "no-store" });
+      if (!response.ok) throw new Error(label("rehearsalDeliveryError"));
+      const payload = await response.json() as { photos?: { key: string; url: string }[] };
+      const exact = payload.photos?.find((photo) => photo.key === photoKey);
+      if (!exact) throw new Error(label("rehearsalDeliveryError"));
+      const image = await fetch(exact.url, { cache: "no-store" });
+      if (!image.ok || (await image.arrayBuffer()).byteLength === 0) {
+        throw new Error(label("rehearsalDeliveryError"));
+      }
+      await append({ kind: "delivery-observed", photoKey, feedObserved: true, publicImageObserved: true });
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : label("rehearsalDeliveryError"));
+    } finally { setBusy(""); }
+  };
+
+  const deleteCanary = async (photoKey: string) => {
+    setBusy("canary"); setError("");
+    try {
+      let cleanupPending = confirmedCanaryDeletes.current.get(photoKey);
+      if (cleanupPending === undefined) {
+        await append({ kind: "canary-designated", photoKey });
+        const query = new URLSearchParams({ event, key: photoKey });
+        const response = await request(`/api/photos?${query}`, { method: "DELETE" });
+        const result = await response.json() as { deleted?: boolean; cleanupPending?: boolean };
+        if (!response.ok || result.deleted !== true) throw new Error(label("rehearsalActionError"));
+        cleanupPending = result.cleanupPending === true;
+        confirmedCanaryDeletes.current.set(photoKey, cleanupPending);
+      }
+      await append({ kind: "canary-deleted", photoKey, cleanupPending });
+      confirmedCanaryDeletes.current.delete(photoKey);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : label("rehearsalActionError"));
+    } finally { setBusy(""); }
+  };
+
+  return (
+    <section className={styles.rehearsalPanel} aria-labelledby="rehearsal-panel-title">
+      <div className={styles.rehearsalHead}>
+        <div>
+          <span>04 / {label("rehearsalOperatorContext")}</span>
+          <h2 id="rehearsal-panel-title">{label("rehearsalAdminTitle")}</h2>
+          <p>{label("rehearsalAdminIntro")}</p>
+        </div>
+        {!confirmStart ? (
+          <button type="button" onClick={() => setConfirmStart(true)}>
+            {view ? label("rehearsalStartNew") : label("rehearsalStart")}
+          </button>
+        ) : (
+          <div className={styles.rehearsalConfirm}>
+            <p>{label("rehearsalStartConfirm")}</p>
+            <button type="button" disabled={busy === "start"} onClick={() => void start()}>
+              {busy === "start" ? label("rehearsalWorking") : label("rehearsalConfirm")}
+            </button>
+            <button type="button" onClick={() => setConfirmStart(false)}>{label("moderationCancel")}</button>
+          </div>
+        )}
+      </div>
+      <p className={styles.rehearsalLive} role="status" aria-live="polite">
+        {loading ? label("rehearsalLoading") : error}
+      </p>
+      {view && (
+        <>
+          <div className={styles.rehearsalIdentity}>
+            <div>
+              <strong>{view.summary.status === "stale" ? label("rehearsalStale") : label("rehearsalStatus", { status: view.summary.status })}</strong>
+              <bdi><code>{view.session.id}</code></bdi>
+              <a href={rehearsalUrl}>{rehearsalUrl}</a>
+            </div>
+            {qr && <img src={qr} alt={label("rehearsalQrAlt")} />}
+          </div>
+          <ol className={styles.rehearsalRequirements}>
+            {requirements.map((requirement) => (
+              <li key={requirement} data-complete={view.summary.requirements[requirement].complete}>
+                <span aria-hidden="true">{view.summary.requirements[requirement].complete ? "✓" : "○"}</span>
+                {label(requirementKeys[requirement])}
+              </li>
+            ))}
+          </ol>
+          <fieldset className={styles.rehearsalManual}>
+            <legend>{label("rehearsalManualTitle")}</legend>
+            {manualChecks.map((check) => (
+              <label key={check}>
+                <input
+                  type="checkbox"
+                  checked={view.summary.manualChecks[check]}
+                  disabled={view.summary.manualChecks[check] || Boolean(busy)}
+                  onChange={() => void append({ kind: "manual-check", check })}
+                />
+                {label(manualKeys[check])}
+              </label>
+            ))}
+          </fieldset>
+          <div className={styles.rehearsalPhotos}>
+            <h3>{label("rehearsalTrackedPhotos")}</h3>
+            {view.summary.trackedPhotos.length === 0 ? <p>{label("rehearsalNoPhotos")}</p> : (
+              <ul>
+                {view.summary.trackedPhotos.map((photo) => (
+                  <li key={photo.photoKey}>
+                    <bdi><code>{photo.photoKey}</code></bdi>
+                    <span>{photo.disposition}</span>
+                    {photo.disposition === "pending" && (
+                      <div>
+                        <button type="button" disabled={Boolean(busy)} onClick={() => void observeDelivery(photo.photoKey)}>
+                          {label("rehearsalObserveDelivery")}
+                        </button>
+                        <button type="button" disabled={Boolean(busy)} onClick={() => void deleteCanary(photo.photoKey)}>
+                          {label("rehearsalUseCanary")}
+                        </button>
+                        <button type="button" disabled={Boolean(busy)} onClick={() => void disposition(photo.photoKey, "retain")}>
+                          {label("rehearsalRetain")}
+                        </button>
+                        <button ref={deleteTrigger} type="button" disabled={Boolean(busy)} onClick={() => setConfirmDelete(photo.photoKey)}>
+                          {label("rehearsalDeleteExact")}
+                        </button>
+                      </div>
+                    )}
+                    {confirmDelete === photo.photoKey && (
+                      <div className={styles.rehearsalDeleteConfirm} role="alertdialog" aria-modal="true">
+                        <strong>{label("rehearsalDeleteConfirm")}</strong>
+                        <span>{photo.photoKey.slice(photo.photoKey.indexOf("/") + 1)}</span>
+                        <bdi><code>{photo.photoKey}</code></bdi>
+                        <button type="button" onClick={() => void disposition(photo.photoKey, "delete")}>{label("moderationConfirmDelete")}</button>
+                        <button type="button" onClick={() => setConfirmDelete(null)}>{label("moderationCancel")}</button>
+                      </div>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+          {view.summary.status === "active" || view.summary.status === "stale" ? (
+            <button className={styles.rehearsalAbandon} type="button" disabled={Boolean(busy)} onClick={() => void append({ kind: "abandoned" })}>
+              {label("rehearsalAbandon")}
+            </button>
+          ) : null}
+        </>
+      )}
+    </section>
+  );
+}
diff --git a/app/[event]/booth-session/rehearsal-client.test.ts b/app/[event]/booth-session/rehearsal-client.test.ts
new file mode 100644
index 0000000..a8e1d74
--- /dev/null
+++ b/app/[event]/booth-session/rehearsal-client.test.ts
@@ -0,0 +1,106 @@
+import { expect, test } from "bun:test";
+import type { OutboxItem } from "./outbox";
+import { RehearsalClient } from "./rehearsal-client";
+import { MemoryRehearsalEvidenceOutbox } from "./rehearsal-evidence-outbox";
+
+const rehearsalId = "018f0000-0000-4000-8000-000000000501";
+const ids = Array.from({ length: 20 }, (_, index) =>
+  `018f0000-0000-4000-8000-${String(index + 1).padStart(12, "0")}`);
+
+test("joins before evidence and persists only network-class failures for exact rehearsal rows", async () => {
+  const calls: Array<{ url: string; body: unknown }> = [];
+  let next = 0;
+  const outbox = new MemoryRehearsalEvidenceOutbox();
+  const client = new RehearsalClient({
+    event: "launch",
+    rehearsalId,
+    key: () => "booth-key",
+    outbox,
+    makeId: () => ids[next++],
+    now: () => 1_753_315_200_000 + next,
+    fetch: async (input, init) => {
+      const url = String(input);
+      calls.push({ url, body: init?.body ? JSON.parse(String(init.body)) : null });
+      if (url.includes("/join")) {
+        return Response.json({
+          rehearsal: {
+            version: 1,
+            id: rehearsalId,
+            startedAt: "2026-07-24T00:00:00.000Z",
+            configRevisionId: null,
+            frames: ["square"],
+            stale: false,
+          },
+        });
+      }
+      throw new Error("offline");
+    },
+  });
+  const item: OutboxItem = {
+    id: ids[15],
+    event: "launch",
+    blob: new Blob(["photo"]),
+    createdAt: 1_753_315_200_000,
+    attempts: 1,
+    rehearsalId,
+  };
+
+  await client.join();
+  await client.recordUploadFailure(item, { kind: "retryable", errorClass: "network" });
+  await client.recordUploadFailure({ ...item, id: ids[16], rehearsalId: undefined }, { kind: "retryable", errorClass: "timeout" });
+  await client.recordUploadFailure({ ...item, id: ids[17] }, { kind: "auth", errorClass: "auth" });
+  const rows = await outbox.list("launch", rehearsalId);
+
+  expect(calls[0].url).toContain("/join");
+  expect(rows).toHaveLength(1);
+  expect(rows[0].attempts).toBe(1);
+  expect(rows[0].evidence).toMatchObject({
+    kind: "network-failure",
+    captureId: ids[15],
+    errorClass: "network",
+  });
+});
+
+test("tags only active non-stale captures and records exact recovered order", async () => {
+  let next = 0;
+  const bodies: unknown[] = [];
+  const client = new RehearsalClient({
+    event: "launch",
+    rehearsalId,
+    key: () => "booth-key",
+    previousBootId: ids[18],
+    makeId: () => ids[next++],
+    now: () => 1_753_315_200_000 + next,
+    fetch: async (input, init) => {
+      if (String(input).includes("/join")) {
+        return Response.json({
+          rehearsal: {
+            version: 1,
+            id: rehearsalId,
+            startedAt: "2026-07-24T00:00:00.000Z",
+            configRevisionId: null,
+            frames: [],
+            stale: false,
+          },
+        });
+      }
+      bodies.push(JSON.parse(String(init?.body)));
+      return Response.json({ idempotent: false });
+    },
+  });
+  await client.join();
+  expect(client.rehearsalIdForNewCapture()).toBe(rehearsalId);
+  await client.recordRecovery([
+    { id: ids[15], event: "launch", blob: new Blob(), createdAt: 1, attempts: 0, rehearsalId },
+    { id: ids[16], event: "launch", blob: new Blob(), createdAt: 2, attempts: 0, rehearsalId },
+  ]);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  client.stop();
+
+  expect(client.rehearsalIdForNewCapture()).toBeUndefined();
+  expect(bodies).toContainEqual(expect.objectContaining({
+    kind: "outbox-recovered",
+    previousBootId: ids[18],
+    captureIds: [ids[15], ids[16]],
+  }));
+});
diff --git a/app/[event]/booth-session/rehearsal-client.ts b/app/[event]/booth-session/rehearsal-client.ts
new file mode 100644
index 0000000..5bb450c
--- /dev/null
+++ b/app/[event]/booth-session/rehearsal-client.ts
@@ -0,0 +1,250 @@
+import type {
+  RehearsalEvidenceInput,
+  RehearsalSession,
+} from "../../rehearsal";
+import type { OutboxItem } from "./outbox";
+import type { ClassifiedFailure } from "./session";
+import {
+  createRehearsalEvidenceOutbox,
+  type RehearsalEvidenceOutbox,
+} from "./rehearsal-evidence-outbox";
+
+export type JoinedRehearsal = RehearsalSession & { stale: boolean };
+
+export type RehearsalClientState = {
+  rehearsal: JoinedRehearsal | null;
+  pendingEvidence: number;
+  durable: boolean;
+  error: string | null;
+};
+
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type WithoutEvidenceEnvelope<T> = T extends unknown
+  ? Omit<T, "version" | "id" | "rehearsalId" | "observedAt">
+  : never;
+type EvidenceFields = WithoutEvidenceEnvelope<RehearsalEvidenceInput>;
+
+export class RehearsalClient {
+  readonly bootId: string;
+  private state: RehearsalClientState;
+  private active = true;
+  private recoveredIds: string[] = [];
+  private acknowledgedRecovered = new Set<string>();
+  private drainRecorded = false;
+  private emptyRecorded = false;
+  private readinessRecorded = false;
+  private draining: Promise<void> | null = null;
+  private listeners = new Set<(state: RehearsalClientState) => void>();
+
+  constructor(private readonly options: {
+    event: string;
+    rehearsalId: string;
+    key: () => string;
+    outbox?: RehearsalEvidenceOutbox;
+    fetch?: FetchLike;
+    makeId?: () => string;
+    now?: () => number;
+    previousBootId?: string | null;
+  }) {
+    this.outbox = options.outbox ?? createRehearsalEvidenceOutbox();
+    this.fetcher = options.fetch ?? fetch;
+    this.makeId = options.makeId ?? (() => crypto.randomUUID());
+    this.now = options.now ?? Date.now;
+    this.bootId = this.makeId();
+    this.state = {
+      rehearsal: null,
+      pendingEvidence: 0,
+      durable: this.outbox.isDurable(),
+      error: null,
+    };
+  }
+
+  private readonly outbox: RehearsalEvidenceOutbox;
+  private readonly fetcher: FetchLike;
+  private readonly makeId: () => string;
+  private readonly now: () => number;
+
+  subscribe(listener: (state: RehearsalClientState) => void) {
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => this.listeners.delete(listener);
+  }
+
+  snapshot() { return this.state; }
+  rehearsalIdForNewCapture() {
+    return this.active && this.state.rehearsal && !this.state.rehearsal.stale
+      ? this.options.rehearsalId
+      : undefined;
+  }
+
+  private publish(next: Partial<RehearsalClientState>) {
+    this.state = { ...this.state, ...next, durable: this.outbox.isDurable() };
+    for (const listener of this.listeners) {
+      try { listener(this.state); } catch { /* UI-only */ }
+    }
+  }
+
+  async join() {
+    const response = await this.fetcher(
+      `/api/rehearsals/join?event=${encodeURIComponent(this.options.event)}`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-booth-key": this.options.key(),
+        },
+        body: JSON.stringify({ rehearsalId: this.options.rehearsalId }),
+      },
+    );
+    if (!response.ok) throw new Error(`Rehearsal join returned ${response.status}`);
+    const payload = await response.json() as { rehearsal?: JoinedRehearsal };
+    if (!payload.rehearsal || payload.rehearsal.id !== this.options.rehearsalId) {
+      throw new Error("Rehearsal join response was invalid");
+    }
+    this.publish({ rehearsal: payload.rehearsal, error: null });
+    await this.refreshPending();
+  }
+
+  async recordReadiness(input: {
+    deviceId: string;
+    cameraReady: boolean;
+    durableStorage: boolean;
+  }) {
+    if (
+      this.readinessRecorded
+      || !this.state.rehearsal
+      || !input.cameraReady
+      || !input.durableStorage
+    ) return;
+    this.readinessRecorded = true;
+    await this.queue({
+      kind: "booth-ready",
+      deviceId: input.deviceId,
+      bootId: this.bootId,
+      cameraReady: true,
+      durableStorage: true,
+    });
+  }
+
+  async recordUploadFailure(item: OutboxItem, failure: ClassifiedFailure) {
+    if (
+      item.rehearsalId !== this.options.rehearsalId
+      || failure.kind !== "retryable"
+      || (failure.errorClass !== "network" && failure.errorClass !== "timeout")
+    ) return;
+    await this.queue({
+      kind: "network-failure",
+      captureId: item.id,
+      bootId: this.bootId,
+      errorClass: failure.errorClass,
+    });
+  }
+
+  async recordRecovery(items: readonly OutboxItem[]) {
+    const rows = items.filter((item) => item.rehearsalId === this.options.rehearsalId);
+    if (!rows.length || !this.options.previousBootId || this.options.previousBootId === this.bootId) return;
+    this.recoveredIds = rows.map((item) => item.id);
+    await this.queue({
+      kind: "outbox-recovered",
+      previousBootId: this.options.previousBootId,
+      bootId: this.bootId,
+      captureIds: [...this.recoveredIds],
+    });
+  }
+
+  async recordAcknowledgement(item: OutboxItem) {
+    if (item.rehearsalId !== this.options.rehearsalId) return;
+    if (this.recoveredIds.includes(item.id)) this.acknowledgedRecovered.add(item.id);
+    if (
+      !this.drainRecorded
+      && this.recoveredIds.length > 0
+      && this.recoveredIds.every((id) => this.acknowledgedRecovered.has(id))
+    ) {
+      this.drainRecorded = true;
+      await this.queue({
+        kind: "ordered-drain",
+        bootId: this.bootId,
+        captureIds: [...this.recoveredIds],
+      });
+    }
+  }
+
+  async recordEmptyOutbox() {
+    if (this.emptyRecorded) return;
+    this.emptyRecorded = true;
+    await this.queue({
+      kind: "outbox-empty",
+      bootId: this.bootId,
+      pendingCount: 0,
+    });
+  }
+
+  async drainEvidence() {
+    if (this.draining) return this.draining;
+    const run = this.drainEvidenceRows().finally(() => {
+      if (this.draining === run) this.draining = null;
+    });
+    this.draining = run;
+    return run;
+  }
+
+  private async drainEvidenceRows() {
+    const rows = await this.outbox.list(this.options.event, this.options.rehearsalId);
+    this.publish({ pendingEvidence: rows.length });
+    for (const row of rows) {
+      try {
+        const response = await this.fetcher(
+          `/api/rehearsals/evidence?event=${encodeURIComponent(this.options.event)}&id=${encodeURIComponent(this.options.rehearsalId)}`,
+          {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "x-booth-key": this.options.key(),
+            },
+            body: JSON.stringify(row.evidence),
+          },
+        );
+        if (!response.ok) throw new Error(`Evidence returned ${response.status}`);
+        await this.outbox.remove(row.id);
+      } catch (cause) {
+        await this.outbox.put({ ...row, attempts: row.attempts + 1 });
+        this.publish({
+          error: cause instanceof Error ? cause.message : String(cause),
+          pendingEvidence: (await this.outbox.list(this.options.event, this.options.rehearsalId)).length,
+        });
+        return;
+      }
+    }
+    this.publish({ pendingEvidence: 0, error: null });
+  }
+
+  stop() { this.active = false; }
+
+  private async queue(
+    fields: EvidenceFields,
+  ) {
+    const id = this.makeId();
+    const evidence = {
+      version: 1,
+      id,
+      rehearsalId: this.options.rehearsalId,
+      observedAt: this.now(),
+      ...fields,
+    } as RehearsalEvidenceInput;
+    await this.outbox.put({
+      id,
+      event: this.options.event,
+      rehearsalId: this.options.rehearsalId,
+      createdAt: evidence.observedAt,
+      attempts: 0,
+      evidence,
+    });
+    await this.refreshPending();
+    void this.drainEvidence();
+  }
+
+  private async refreshPending() {
+    const pending = await this.outbox.list(this.options.event, this.options.rehearsalId);
+    this.publish({ pendingEvidence: pending.length });
+  }
+}
diff --git a/app/[event]/booth-session/rehearsal-evidence-outbox.test.ts b/app/[event]/booth-session/rehearsal-evidence-outbox.test.ts
new file mode 100644
index 0000000..8903e1c
--- /dev/null
+++ b/app/[event]/booth-session/rehearsal-evidence-outbox.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createRehearsalEvidenceOutbox,
+  MemoryRehearsalEvidenceOutbox,
+  type PendingRehearsalEvidence,
+} from "./rehearsal-evidence-outbox";
+
+const rehearsalA = "018f0000-0000-4000-8000-000000000501";
+const rehearsalB = "018f0000-0000-4000-8000-000000000502";
+
+function row(id: string, event: string, rehearsalId: string, createdAt: number): PendingRehearsalEvidence {
+  return {
+    id,
+    event,
+    rehearsalId,
+    createdAt,
+    attempts: 2,
+    evidence: {
+      version: 1,
+      id,
+      rehearsalId,
+      observedAt: createdAt,
+      kind: "abandoned",
+    },
+  };
+}
+
+describe("rehearsal evidence outbox", () => {
+  test("orders rows and isolates exact Event and rehearsal identities", async () => {
+    const store = new MemoryRehearsalEvidenceOutbox();
+    await store.put(row("018f0000-0000-4000-8000-000000000513", "launch", rehearsalA, 1_753_315_200_003));
+    await store.put(row("018f0000-0000-4000-8000-000000000511", "launch", rehearsalA, 1_753_315_200_001));
+    await store.put(row("018f0000-0000-4000-8000-000000000512", "other", rehearsalA, 1_753_315_200_002));
+    await store.put(row("018f0000-0000-4000-8000-000000000514", "launch", rehearsalB, 1_753_315_200_004));
+
+    expect((await store.list("launch", rehearsalA)).map(({ id, attempts }) => [id, attempts]))
+      .toEqual([
+        ["018f0000-0000-4000-8000-000000000511", 2],
+        ["018f0000-0000-4000-8000-000000000513", 2],
+      ]);
+    await store.remove("018f0000-0000-4000-8000-000000000511");
+    expect((await store.list("launch", rehearsalA)).map(({ id }) => id))
+      .toEqual(["018f0000-0000-4000-8000-000000000513"]);
+    expect(store.isDurable()).toBeFalse();
+  });
+
+  test("opens only the separate rehearsal database and visibly degrades on failure", async () => {
+    const opens: Array<[string, number | undefined]> = [];
+    const factory = {
+      open(name: string, version?: number) {
+        opens.push([name, version]);
+        const request = {
+          error: new DOMException("denied"),
+          onupgradeneeded: null,
+          onsuccess: null,
+          onerror: null as null | (() => void),
+          onblocked: null,
+        };
+        queueMicrotask(() => request.onerror?.());
+        return request;
+      },
+    } as unknown as IDBFactory;
+    const store = createRehearsalEvidenceOutbox(factory);
+    await store.put(row("018f0000-0000-4000-8000-000000000511", "launch", rehearsalA, 1_753_315_200_001));
+
+    expect(opens).toEqual([["ipad-webbooth-rehearsal", 1]]);
+    expect(opens.flat().join(" ")).not.toContain("photo-outbox");
+    expect(store.isDurable()).toBeFalse();
+    expect(await store.list("launch", rehearsalA)).toHaveLength(1);
+  });
+});
diff --git a/app/[event]/booth-session/rehearsal-evidence-outbox.ts b/app/[event]/booth-session/rehearsal-evidence-outbox.ts
new file mode 100644
index 0000000..c2b1a0d
--- /dev/null
+++ b/app/[event]/booth-session/rehearsal-evidence-outbox.ts
@@ -0,0 +1,122 @@
+import type { RehearsalEvidenceInput } from "../../rehearsal";
+
+export type PendingRehearsalEvidence = {
+  id: string;
+  event: string;
+  rehearsalId: string;
+  createdAt: number;
+  attempts: number;
+  evidence: RehearsalEvidenceInput;
+};
+
+export interface RehearsalEvidenceOutbox {
+  isDurable(): boolean;
+  list(event: string, rehearsalId: string): Promise<PendingRehearsalEvidence[]>;
+  put(item: PendingRehearsalEvidence): Promise<void>;
+  remove(id: string): Promise<void>;
+}
+
+export class MemoryRehearsalEvidenceOutbox implements RehearsalEvidenceOutbox {
+  private readonly rows = new Map<string, PendingRehearsalEvidence>();
+  isDurable() { return false; }
+  async list(event: string, rehearsalId: string) {
+    return [...this.rows.values()]
+      .filter((row) => row.event === event && row.rehearsalId === rehearsalId)
+      .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+  }
+  async put(item: PendingRehearsalEvidence) { this.rows.set(item.id, item); }
+  async remove(id: string) { this.rows.delete(id); }
+}
+
+class IndexedDbRehearsalEvidenceOutbox implements RehearsalEvidenceOutbox {
+  private readonly db: Promise<IDBDatabase>;
+  isDurable() { return true; }
+
+  constructor(factory: IDBFactory) {
+    this.db = new Promise((resolve, reject) => {
+      const request = factory.open("ipad-webbooth-rehearsal", 1);
+      request.onupgradeneeded = () => {
+        if (!request.result.objectStoreNames.contains("evidence-outbox")) {
+          request.result.createObjectStore("evidence-outbox", { keyPath: "id" });
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error ?? new Error("Could not open rehearsal evidence outbox"));
+      request.onblocked = () => reject(new Error("Rehearsal evidence outbox upgrade was blocked"));
+    });
+  }
+
+  private async request<T>(
+    mode: IDBTransactionMode,
+    run: (store: IDBObjectStore) => IDBRequest<T>,
+  ): Promise<T> {
+    const db = await this.db;
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction("evidence-outbox", mode);
+      const request = run(transaction.objectStore("evidence-outbox"));
+      let result!: T;
+      request.onsuccess = () => { result = request.result; };
+      request.onerror = () => reject(request.error ?? new Error("Rehearsal evidence request failed"));
+      transaction.oncomplete = () => resolve(result);
+      transaction.onerror = () => reject(transaction.error ?? new Error("Rehearsal evidence transaction failed"));
+      transaction.onabort = () => reject(transaction.error ?? new Error("Rehearsal evidence transaction aborted"));
+    });
+  }
+
+  async list(event: string, rehearsalId: string) {
+    const rows = await this.request<PendingRehearsalEvidence[]>("readonly", (store) => store.getAll());
+    return rows
+      .filter((row) => row.event === event && row.rehearsalId === rehearsalId)
+      .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+  }
+  async put(item: PendingRehearsalEvidence) {
+    await this.request("readwrite", (store) => store.put(item));
+  }
+  async remove(id: string) {
+    await this.request("readwrite", (store) => store.delete(id));
+  }
+}
+
+export function createRehearsalEvidenceOutbox(
+  factory: IDBFactory | null = typeof indexedDB === "undefined" ? null : indexedDB,
+): RehearsalEvidenceOutbox {
+  const memory = new MemoryRehearsalEvidenceOutbox();
+  if (!factory) return memory;
+  const durable = new IndexedDbRehearsalEvidenceOutbox(factory);
+  let degraded = false;
+  const fallback = async <T>(durableWork: () => Promise<T>, memoryWork: () => Promise<T>) => {
+    if (degraded) return memoryWork();
+    try {
+      return await durableWork();
+    } catch {
+      degraded = true;
+      return memoryWork();
+    }
+  };
+  return {
+    isDurable: () => !degraded,
+    list: (event, rehearsalId) => fallback(async () => {
+      const rows = await durable.list(event, rehearsalId);
+      await Promise.all(rows.map((row) => memory.put(row)));
+      return rows;
+    }, () => memory.list(event, rehearsalId)),
+    put: async (item) => {
+      await memory.put(item);
+      await fallback(() => durable.put(item), () => Promise.resolve());
+    },
+    remove: async (id) => {
+      if (degraded) {
+        await memory.remove(id);
+        return;
+      }
+      try {
+        await durable.remove(id);
+        await memory.remove(id);
+      } catch {
+        degraded = true;
+        // Keep the mirrored row: a failed durable acknowledgement must remain
+        // visible to this page and is safe to retry by stable evidence ID.
+      }
+    },
+  };
+}
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index e9512f5..373d233 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -117,6 +117,74 @@ function versionOneIndexedDb(rows: OutboxItem[]) {
 }
 
 describe("BoothSession outbox", () => {
+  test("isolates observer callbacks after durable acknowledgement and failure writes", async () => {
+    const events: string[] = [];
+    class ObservedStore extends MemoryOutboxStore {
+      override async remove(id: string) {
+        await super.remove(id);
+        events.push(`removed:${id}`);
+      }
+      override async markFailure(item: OutboxItem, ownerId: string, now: number) {
+        const saved = await super.markFailure(item, ownerId, now);
+        if (saved) events.push(`failed:${item.id}:${item.attempts}`);
+        return saved;
+      }
+    }
+    const successStore = new ObservedStore();
+    const success = new BoothSession(
+      "party",
+      successStore,
+      async () => ({ url: "/photo", key: "party/current.jpg" }),
+      undefined,
+      () => "018f0000-0000-4000-8000-000000000501",
+      () => 1_753_315_200_000,
+      {
+        observer: {
+          onAcknowledged: (item) => {
+            events.push(`observed:${item.id}`);
+            throw new Error("observer is isolated");
+          },
+        },
+      },
+    );
+    await success.enqueueCapture(async () => photo("current"), {
+      metadata: { source: "framed", frameKey: "square" },
+    });
+    await success.process();
+
+    const failureStore = new ObservedStore();
+    const failure = new BoothSession(
+      "party",
+      failureStore,
+      async () => { throw new TypeError("offline"); },
+      undefined,
+      () => "018f0000-0000-4000-8000-000000000502",
+      () => 1_753_315_200_100,
+      {
+        ownerId: "observer-owner",
+        observer: {
+          onUploadFailure: (item, classified) => {
+            events.push(`observed-failure:${item.id}:${classified.kind}`);
+            throw new Error("observer is isolated");
+          },
+        },
+      },
+    );
+    await failure.enqueueCapture(async () => photo("offline"), {
+      metadata: { source: "camera-fallback" },
+    });
+    await failure.process();
+
+    expect(events).toEqual([
+      "removed:018f0000-0000-4000-8000-000000000501",
+      "observed:018f0000-0000-4000-8000-000000000501",
+      "failed:018f0000-0000-4000-8000-000000000502:1",
+      "observed-failure:018f0000-0000-4000-8000-000000000502:retryable",
+    ]);
+    expect(await successStore.list("party")).toEqual([]);
+    expect((await failureStore.list("party"))[0].attempts).toBe(1);
+  });
+
   test("acknowledges the exact stored item and response only after exact-row removal", async () => {
     const itemWasRemoved: boolean[] = [];
     const acknowledgements: UploadAcknowledgement[] = [];
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index 10b5c3e..f7aaedd 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -19,6 +19,16 @@ export type OnAcknowledged = (
   acknowledgement: UploadAcknowledgement,
 ) => void;
 
+export type ClassifiedFailure = {
+  kind: "retryable" | "permanent" | "auth";
+  errorClass: import("./retry-policy").UploadErrorClass;
+};
+
+export type BoothSessionObserver = {
+  onAcknowledged?: (item: OutboxItem, result: UploadResult) => void | Promise<void>;
+  onUploadFailure?: (item: OutboxItem, failure: ClassifiedFailure) => void | Promise<void>;
+};
+
 export type EnqueueCaptureOptions = {
   signal?: AbortSignal;
   metadata: Omit<CaptureMetadata, "capturedAt">;
@@ -30,6 +40,7 @@ export type BoothSessionOptions = {
   leaseTtlMs?: number;
   random?: () => number;
   onAuthRequired?: (itemId: string) => void | Promise<void>;
+  observer?: BoothSessionObserver;
   setTimer?: (callback: () => void, delayMs: number) => unknown;
   clearTimer?: (timer: unknown) => void;
 };
@@ -54,6 +65,7 @@ export class BoothSession {
   private readonly leaseTtlMs: number;
   private readonly random: () => number;
   private readonly onAuthRequired: (itemId: string) => void | Promise<void>;
+  private readonly observer: BoothSessionObserver;
   private readonly setTimer: (callback: () => void, delayMs: number) => unknown;
   private readonly clearTimer: (timer: unknown) => void;
 
@@ -70,6 +82,7 @@ export class BoothSession {
     this.leaseTtlMs = options.leaseTtlMs ?? 30_000;
     this.random = options.random ?? Math.random;
     this.onAuthRequired = options.onAuthRequired ?? (() => {});
+    this.observer = options.observer ?? {};
     this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
     this.clearTimer = options.clearTimer ?? ((timer) => clearTimeout(timer as ReturnType<typeof setTimeout>));
   }
@@ -303,6 +316,11 @@ export class BoothSession {
       } catch {
         // The next state publication still reconciles the Booth UI.
       }
+      try {
+        this.observer.onAcknowledged?.(item, result);
+      } catch {
+        // Operational evidence cannot affect an acknowledged photo queue row.
+      }
 
       if (this.stopRequested) return;
 
@@ -370,6 +388,14 @@ export class BoothSession {
       }
       return;
     }
+    try {
+      await this.observer.onUploadFailure?.(failed, {
+        kind: failed.failureKind ?? "permanent",
+        errorClass: failed.errorClass ?? "unknown",
+      });
+    } catch {
+      // Operational evidence cannot affect the already-persisted failure row.
+    }
     this.retryAt = disposition.kind === "retryable" ? failed.nextAttemptAt ?? null : null;
     this.publish({
       status: "failed",
diff --git a/app/[event]/booth.module.css b/app/[event]/booth.module.css
index 07810c3..d80aaa1 100644
--- a/app/[event]/booth.module.css
+++ b/app/[event]/booth.module.css
@@ -1041,3 +1041,41 @@
     transform: none;
   }
 }
+
+.rehearsalStatus {
+  position: fixed;
+  inset-block-start: 12px;
+  inset-inline-start: 12px;
+  z-index: 35;
+  width: min(390px, calc(100vw - 24px));
+  max-height: calc(100dvh - 24px);
+  overflow: auto;
+  border: 3px solid #fff;
+  padding: 14px;
+  color: #fff;
+  background: rgba(12, 12, 12, .94);
+  box-shadow: 7px 7px 0 #c51651;
+}
+.rehearsalStatus > div:first-child p {
+  color: #ffd544;
+  font: 800 10px/1 ui-monospace, monospace;
+  text-transform: uppercase;
+}
+.rehearsalStatus h2 { margin-block: 6px; font: 900 25px/1 system-ui, sans-serif; }
+.rehearsalStatus code { overflow-wrap: anywhere; font-size: 10px; }
+.rehearsalStatus dl { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; margin-block: 12px; }
+.rehearsalStatus dl div { border: 1px solid #777; padding: 8px; }
+.rehearsalStatus dt { color: #bbb; font-size: 10px; }
+.rehearsalStatus dd { margin-top: 4px; font-weight: 800; }
+.rehearsalStatus > p { margin-block: 10px; font-size: 12px; line-height: 1.4; }
+.rehearsalStatus .rehearsalWarning { border-inline-start: 5px solid #ffd544; padding: 9px; color: #111; background: #ffd544; }
+.rehearsalStatus button { min-width: 44px; min-height: 44px; width: 100%; border: 2px solid #fff; color: #fff; background: #c51651; font-weight: 900; cursor: pointer; }
+.rehearsalStatus button:focus-visible { outline: 3px solid #ffd544; outline-offset: 3px; }
+
+@media (forced-colors: active) {
+  .rehearsalStatus { border-color: CanvasText; background: Canvas; color: CanvasText; box-shadow: none; }
+  .rehearsalStatus button:focus-visible { outline-color: Highlight; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .rehearsalStatus, .rehearsalStatus * { animation: none !important; transition: none !important; }
+}
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 0ace1b9..3c9a0d3 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -17,7 +17,7 @@ import {
   encodeCanvas,
 } from "../templates";
 import { frameLabel } from "../frame-packs/catalog";
-import { createOutboxStore, type OutboxItem } from "./booth-session/outbox";
+import { createOutboxStore, type OutboxItem, type OutboxStore } from "./booth-session/outbox";
 import {
   BoothSession,
   runCaptureSequence,
@@ -93,6 +93,11 @@ import {
   type SupportedLocale,
 } from "../i18n/catalog";
 import type { EventExperience } from "../event-config";
+import {
+  RehearsalClient,
+  type RehearsalClientState,
+} from "./booth-session/rehearsal-client";
+import { RehearsalStatus } from "./rehearsal-status";
 
 type Status = "starting" | "picking" | "ready" | "denied" | "running";
 type OperationalState = BoothOperationalClientState;
@@ -104,6 +109,13 @@ const INITIAL_UPLOAD_STATE: UploadState = {
   durable: true,
 };
 
+const INITIAL_REHEARSAL_STATE: RehearsalClientState = {
+  rehearsal: null,
+  pendingEvidence: 0,
+  durable: true,
+  error: null,
+};
+
 function uploadErrorClass(status: number): UploadErrorClass {
   if (status === 401) return "auth";
   if (status === 408 || status === 425 || status === 429) return "timeout";
@@ -163,6 +175,8 @@ export default function Booth() {
   const shutterRef = useRef<HTMLButtonElement>(null);
   const streamRef = useRef<MediaStream | null>(null);
   const sessionRef = useRef<BoothSession | null>(null);
+  const photoOutboxRef = useRef<OutboxStore | null>(null);
+  const rehearsalClientRef = useRef<RehearsalClient | null>(null);
   const statePollerRef = useRef<BoothStatePoller | null>(null);
   const heartbeatReporterRef = useRef<BoothHeartbeatReporter | null>(null);
   const captureRef = useRef<AbortController | null>(null);
@@ -217,6 +231,9 @@ export default function Booth() {
   const [wakeState, setWakeState] =
     useState<WakeRequestState | "idle">("idle");
   const [durableHandoffActive, setDurableHandoffActive] = useState(false);
+  const [requestedRehearsalId, setRequestedRehearsalId] = useState<string | null>(null);
+  const [rehearsalState, setRehearsalState] =
+    useState<RehearsalClientState>(INITIAL_REHEARSAL_STATE);
   // Frames remain unavailable until authenticated preflight returns the safe
   // Event experience. `null` is never shown while the Booth is locked.
   const [enabled, setEnabled] = useState<string[] | null>(null);
@@ -235,6 +252,10 @@ export default function Booth() {
     [locale],
   );
 
+  useEffect(() => {
+    setRequestedRehearsalId(new URL(window.location.href).searchParams.get("rehearsal"));
+  }, [event]);
+
   const startCamera = useCallback(async () => {
     if (operationalRef.current.paused || unmountedRef.current) return;
     const request = ++cameraRequestRef.current;
@@ -562,15 +583,30 @@ export default function Booth() {
         )
       );
     };
+    const photoOutbox = createOutboxStore();
+    photoOutboxRef.current = photoOutbox;
     session = new BoothSession(
       event,
-      createOutboxStore(),
+      photoOutbox,
       uploadOne,
       acknowledge,
       undefined,
       undefined,
       {
         onAuthRequired: (itemId) => lifecycle.authRequired(session, itemId),
+        observer: {
+          onAcknowledged: (item) => {
+            const client = rehearsalClientRef.current;
+            if (!client) return;
+            void client.recordAcknowledgement(item).then(async () => {
+              const remaining = await photoOutbox.list(event);
+              if (remaining.length === 0) await client.recordEmptyOutbox();
+            });
+          },
+          onUploadFailure: (item, failure) => {
+            void rehearsalClientRef.current?.recordUploadFailure(item, failure);
+          },
+        },
       }
     );
     sessionRef.current = session;
@@ -596,9 +632,13 @@ export default function Booth() {
     const reconsiderConnectivity = () => {
       setOnline(navigator.onLine);
       void session.reconsider("connectivity");
+      void rehearsalClientRef.current?.drainEvidence();
     };
     const reconsiderForeground = () => {
-      if (document.visibilityState === "visible") void session.reconsider("foreground");
+      if (document.visibilityState === "visible") {
+        void session.reconsider("foreground");
+        void rehearsalClientRef.current?.drainEvidence();
+      }
     };
     window.addEventListener("online", reconsiderConnectivity);
     window.addEventListener("offline", reconsiderConnectivity);
@@ -610,6 +650,7 @@ export default function Booth() {
       window.removeEventListener("offline", reconsiderConnectivity);
       document.removeEventListener("visibilitychange", reconsiderForeground);
       if (sessionRef.current === session) sessionRef.current = null;
+      if (photoOutboxRef.current === photoOutbox) photoOutboxRef.current = null;
       stopBoothOperationalClients(poller, reporter);
       if (credentialRef.current === credential) credentialRef.current = null;
       if (statePollerRef.current === poller) statePollerRef.current = null;
@@ -618,6 +659,63 @@ export default function Booth() {
     };
   }, [applyOperationalState, event, lifecycle]);
 
+  useEffect(() => {
+    if (
+      accessState !== "ready"
+      || !requestedRehearsalId
+      || !credentialRef.current?.key
+      || !photoOutboxRef.current
+    ) return;
+    let cancelled = false;
+    const storageKey = `webbooth:${event}:rehearsal:${requestedRehearsalId}:boot`;
+    let previousBootId: string | null = null;
+    try { previousBootId = window.sessionStorage.getItem(storageKey); } catch { /* restricted storage */ }
+    const client = new RehearsalClient({
+      event,
+      rehearsalId: requestedRehearsalId,
+      key: () => credentialRef.current?.key ?? "",
+      previousBootId,
+    });
+    rehearsalClientRef.current = client;
+    const unsubscribe = client.subscribe((next) => {
+      if (!cancelled) setRehearsalState(next);
+    });
+    void (async () => {
+      try {
+        await client.join();
+        if (cancelled) return;
+        try { window.sessionStorage.setItem(storageKey, client.bootId); } catch { /* restricted storage */ }
+        const recovered = await photoOutboxRef.current?.list(event) ?? [];
+        await client.recordRecovery(recovered);
+        await client.drainEvidence();
+      } catch (cause) {
+        if (!cancelled) {
+          setError(cause instanceof Error ? cause.message : label("rehearsalJoinError"));
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+      unsubscribe();
+      client.stop();
+      if (rehearsalClientRef.current === client) rehearsalClientRef.current = null;
+      setRehearsalState(INITIAL_REHEARSAL_STATE);
+    };
+  }, [accessState, event, label, requestedRehearsalId]);
+
+  useEffect(() => {
+    if (
+      !rehearsalState.rehearsal
+      || (status !== "picking" && status !== "ready" && status !== "running")
+      || !deviceIdRef.current
+    ) return;
+    void rehearsalClientRef.current?.recordReadiness({
+      deviceId: deviceIdRef.current,
+      cameraReady: true,
+      durableStorage: uploadState.durable,
+    });
+  }, [rehearsalState.rehearsal, status, uploadState.durable]);
+
   useEffect(() => {
     const reporter = heartbeatReporterRef.current;
     if (!reporter || !deviceIdRef.current || !sessionStartedAtRef.current) return;
@@ -693,6 +791,7 @@ export default function Booth() {
             source: candidate.source,
             ...(candidate.frameKey ? { frameKey: candidate.frameKey } : {}),
           },
+          rehearsalId: rehearsalClientRef.current?.rehearsalIdForNewCapture(),
         },
       );
       if (
@@ -991,6 +1090,20 @@ export default function Booth() {
     <>
       <link rel="manifest" href={`/${event}/manifest.webmanifest`} />
       <main className={styles.booth}>
+      <RehearsalStatus
+        locale={locale}
+        state={rehearsalState}
+        currentFrame={mode}
+        onLeave={() => {
+          rehearsalClientRef.current?.stop();
+          rehearsalClientRef.current = null;
+          setRequestedRehearsalId(null);
+          setRehearsalState(INITIAL_REHEARSAL_STATE);
+          const url = new URL(window.location.href);
+          url.searchParams.delete("rehearsal");
+          window.history.replaceState(null, "", url);
+        }}
+      />
       {/* framed box is exactly the slot's aspect at the largest size that fits,
           so the cover-cropped preview is edge-to-edge what composite() captures */}
       <video
diff --git a/app/[event]/rehearsal-status.test.tsx b/app/[event]/rehearsal-status.test.tsx
new file mode 100644
index 0000000..0882a95
--- /dev/null
+++ b/app/[event]/rehearsal-status.test.tsx
@@ -0,0 +1,30 @@
+import { expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+import { RehearsalStatus } from "./rehearsal-status";
+
+test("renders localized stale, durability, exact ID, queue and leave guidance", () => {
+  const html = renderToStaticMarkup(
+    <RehearsalStatus
+      locale="ar"
+      state={{
+        rehearsal: {
+          version: 1,
+          id: "018f0000-0000-4000-8000-000000000501",
+          startedAt: "2026-07-24T00:00:00.000Z",
+          configRevisionId: null,
+          frames: ["square"],
+          stale: true,
+        },
+        pendingEvidence: 3,
+        durable: false,
+        error: null,
+      }}
+      currentFrame="square"
+      onLeave={() => {}}
+    />,
+  );
+  expect(html).toContain('role="alert"');
+  expect(html).toContain("<bdi><code>018f0000");
+  expect(html).toContain(">3</dd>");
+  expect(html).toContain("مغادرة البروفة");
+});
diff --git a/app/[event]/rehearsal-status.tsx b/app/[event]/rehearsal-status.tsx
new file mode 100644
index 0000000..d5701d7
--- /dev/null
+++ b/app/[event]/rehearsal-status.tsx
@@ -0,0 +1,53 @@
+"use client";
+
+import type { SupportedLocale } from "../i18n/catalog";
+import { message } from "../i18n/catalog";
+import type { RehearsalClientState } from "./booth-session/rehearsal-client";
+import styles from "./booth.module.css";
+
+export function RehearsalStatus({
+  locale,
+  state,
+  currentFrame,
+  onLeave,
+}: {
+  locale: SupportedLocale;
+  state: RehearsalClientState;
+  currentFrame: string | null;
+  onLeave: () => void;
+}) {
+  const rehearsal = state.rehearsal;
+  if (!rehearsal) return null;
+  const covered = currentFrame ? rehearsal.frames.includes(currentFrame) : false;
+  return (
+    <aside className={styles.rehearsalStatus} aria-labelledby="rehearsal-status-title">
+      <div>
+        <p>{message(locale, "rehearsalOperatorContext")}</p>
+        <h2 id="rehearsal-status-title">{message(locale, "rehearsalBoothTitle")}</h2>
+        <bdi><code>{rehearsal.id}</code></bdi>
+      </div>
+      {rehearsal.stale && (
+        <p className={styles.rehearsalWarning} role="alert">
+          {message(locale, "rehearsalStaleBooth")}
+        </p>
+      )}
+      <dl>
+        <div>
+          <dt>{message(locale, "rehearsalFrameCoverage")}</dt>
+          <dd>{covered ? message(locale, "rehearsalCovered") : message(locale, "rehearsalNeedsCapture")}</dd>
+        </div>
+        <div>
+          <dt>{message(locale, "rehearsalPendingEvidence")}</dt>
+          <dd>{state.pendingEvidence}</dd>
+        </div>
+      </dl>
+      {!state.durable && (
+        <p className={styles.rehearsalWarning} role="alert">
+          {message(locale, "rehearsalEvidenceNotDurable")}
+        </p>
+      )}
+      <p>{message(locale, rehearsal.stale ? "rehearsalDrainGuidance" : "rehearsalNextStep")}</p>
+      <button type="button" onClick={onLeave}>{message(locale, "rehearsalLeave")}</button>
+    </aside>
+  );
+}
diff --git a/app/i18n/catalog.ts b/app/i18n/catalog.ts
index b875c9c..f5cb634 100644
--- a/app/i18n/catalog.ts
+++ b/app/i18n/catalog.ts
@@ -166,6 +166,56 @@ export const englishMessages = {
     "Presets or configuration changed. Review the latest versions before trying again.",
   presetGenericError: "The preset action could not be completed. Retry when ready.",
   presetSourceLabel: "Applied preset",
+  rehearsalOperatorContext: "Guided rehearsal",
+  rehearsalBoothTitle: "Rehearsal active",
+  rehearsalStaleBooth: "Configuration changed. Do not take new rehearsal photos; let pending photos and evidence finish uploading.",
+  rehearsalFrameCoverage: "Current frame",
+  rehearsalCovered: "Covered",
+  rehearsalNeedsCapture: "Needs a rehearsal capture",
+  rehearsalPendingEvidence: "Evidence waiting",
+  rehearsalEvidenceNotDurable: "Rehearsal evidence storage is not durable. Do not reload until it uploads.",
+  rehearsalDrainGuidance: "Keep this page open until both queues are empty, then start a new rehearsal.",
+  rehearsalNextStep: "Capture each enabled frame, test two offline failures, then reload and let the queues drain in order.",
+  rehearsalLeave: "Leave rehearsal",
+  rehearsalJoinError: "This rehearsal could not be joined.",
+  rehearsalAdminTitle: "Real-device rehearsal",
+  rehearsalAdminIntro: "Prove the target iPad, projector, network recovery, public delivery, and one exact moderation deletion.",
+  rehearsalUnauthorized: "The Admin Key was rejected.",
+  rehearsalLoadError: "Rehearsal status could not be loaded.",
+  rehearsalStartError: "The rehearsal could not be started.",
+  rehearsalActionError: "That rehearsal action did not finish.",
+  rehearsalDeliveryError: "The exact photo was not available from both the public feed and public image URL.",
+  rehearsalStart: "Start rehearsal",
+  rehearsalStartNew: "Start new rehearsal",
+  rehearsalStartConfirm: "Start an immutable rehearsal from the current configuration?",
+  rehearsalWorking: "Working…",
+  rehearsalConfirm: "Confirm start",
+  rehearsalLoading: "Loading rehearsal status…",
+  rehearsalStale: "Stale — start a new rehearsal",
+  rehearsalStatus: "Status: {status}",
+  rehearsalQrAlt: "Scan to join this rehearsal on the Booth",
+  rehearsalReqBoothReady: "Booth camera and durable storage ready",
+  rehearsalReqFrames: "Every enabled frame captured",
+  rehearsalReqFailures: "Two distinct network failures recorded",
+  rehearsalReqReload: "Pending photos recovered after reload",
+  rehearsalReqDrain: "Recovered photos drained in order",
+  rehearsalReqDelivery: "Exact public feed and image delivery observed",
+  rehearsalReqCanary: "One designated exact canary deleted",
+  rehearsalReqEmpty: "Photo Outbox confirmed empty",
+  rehearsalManualTitle: "Physical checks",
+  rehearsalManualComposition: "Printed/composited framing checked on the real iPad",
+  rehearsalManualProjector: "Projector layout and manual-scroll pause checked",
+  rehearsalManualPower: "Auto-Lock and installed-mode behavior checked",
+  rehearsalManualCharging: "Power and charging arrangement checked",
+  rehearsalManualBackup: "Backup network recovery checked",
+  rehearsalTrackedPhotos: "Tracked rehearsal photos",
+  rehearsalNoPhotos: "No acknowledged rehearsal photos yet.",
+  rehearsalObserveDelivery: "Observe public delivery",
+  rehearsalUseCanary: "Delete as exact canary",
+  rehearsalRetain: "Retain photo",
+  rehearsalDeleteExact: "Delete exact photo",
+  rehearsalDeleteConfirm: "Delete only this complete object key?",
+  rehearsalAbandon: "Abandon rehearsal without cleanup",
 } satisfies Record<string, string>;
 
 export type MessageKey = keyof typeof englishMessages;
@@ -320,6 +370,56 @@ export const chineseSingaporeMessages: Record<MessageKey, string> = {
   presetConflict: "预设或配置已更改。请检查最新版本后重试。",
   presetGenericError: "无法完成预设操作。准备好后请重试。",
   presetSourceLabel: "应用的预设",
+  rehearsalOperatorContext: "引导式演练",
+  rehearsalBoothTitle: "演练进行中",
+  rehearsalStaleBooth: "配置已更改。请勿拍摄新的演练照片；让待处理照片和证据继续上传。",
+  rehearsalFrameCoverage: "当前相框",
+  rehearsalCovered: "已覆盖",
+  rehearsalNeedsCapture: "需要演练拍摄",
+  rehearsalPendingEvidence: "待上传证据",
+  rehearsalEvidenceNotDurable: "演练证据存储不可持久保存。上传完成前请勿重新载入。",
+  rehearsalDrainGuidance: "请保持此页面开启，直到两个队列均为空，然后开始新的演练。",
+  rehearsalNextStep: "拍摄每个已启用相框，测试两次断网失败，然后重新载入并按顺序清空队列。",
+  rehearsalLeave: "退出演练",
+  rehearsalJoinError: "无法加入此演练。",
+  rehearsalAdminTitle: "真实设备演练",
+  rehearsalAdminIntro: "验证目标 iPad、投影、网络恢复、公开交付及一次精确审核删除。",
+  rehearsalUnauthorized: "管理员密钥被拒绝。",
+  rehearsalLoadError: "无法载入演练状态。",
+  rehearsalStartError: "无法开始演练。",
+  rehearsalActionError: "演练操作未完成。",
+  rehearsalDeliveryError: "无法同时从公开照片流和公开图片网址取得该精确照片。",
+  rehearsalStart: "开始演练",
+  rehearsalStartNew: "开始新演练",
+  rehearsalStartConfirm: "是否以当前配置开始不可变的演练？",
+  rehearsalWorking: "处理中…",
+  rehearsalConfirm: "确认开始",
+  rehearsalLoading: "正在载入演练状态…",
+  rehearsalStale: "已过时 — 请开始新演练",
+  rehearsalStatus: "状态：{status}",
+  rehearsalQrAlt: "扫描以在拍照亭加入此演练",
+  rehearsalReqBoothReady: "拍照亭相机和持久存储已就绪",
+  rehearsalReqFrames: "已拍摄所有启用的相框",
+  rehearsalReqFailures: "已记录两次不同的网络失败",
+  rehearsalReqReload: "重新载入后已恢复待处理照片",
+  rehearsalReqDrain: "已按顺序上传恢复的照片",
+  rehearsalReqDelivery: "已观察精确公开照片流和图片交付",
+  rehearsalReqCanary: "已删除一个指定的精确测试照片",
+  rehearsalReqEmpty: "已确认照片队列为空",
+  rehearsalManualTitle: "实体检查",
+  rehearsalManualComposition: "已在真实 iPad 检查合成取景",
+  rehearsalManualProjector: "已检查投影布局和手动滚动暂停",
+  rehearsalManualPower: "已检查自动锁定和安装模式",
+  rehearsalManualCharging: "已检查供电和充电安排",
+  rehearsalManualBackup: "已检查备用网络恢复",
+  rehearsalTrackedPhotos: "已追踪的演练照片",
+  rehearsalNoPhotos: "尚无已确认的演练照片。",
+  rehearsalObserveDelivery: "观察公开交付",
+  rehearsalUseCanary: "作为精确测试照片删除",
+  rehearsalRetain: "保留照片",
+  rehearsalDeleteExact: "删除精确照片",
+  rehearsalDeleteConfirm: "只删除此完整对象密钥？",
+  rehearsalAbandon: "放弃演练且不清理",
 };
 
 export const arabicMessages: Record<MessageKey, string> = {
@@ -486,6 +586,56 @@ export const arabicMessages: Record<MessageKey, string> = {
   presetConflict: "تغيّرت الإعدادات المسبقة أو التكوين. راجع أحدث الإصدارات قبل المحاولة.",
   presetGenericError: "تعذر إكمال إجراء الإعداد المسبق. أعد المحاولة عندما تكون جاهزًا.",
   presetSourceLabel: "الإعداد المسبق المطبق",
+  rehearsalOperatorContext: "بروفة موجّهة",
+  rehearsalBoothTitle: "البروفة نشطة",
+  rehearsalStaleBooth: "تغيّر الإعداد. لا تلتقط صور بروفة جديدة؛ اسمح للصور والأدلة المعلقة بإكمال الرفع.",
+  rehearsalFrameCoverage: "الإطار الحالي",
+  rehearsalCovered: "مغطّى",
+  rehearsalNeedsCapture: "يحتاج إلى لقطة بروفة",
+  rehearsalPendingEvidence: "أدلة بانتظار الرفع",
+  rehearsalEvidenceNotDurable: "تخزين أدلة البروفة غير دائم. لا تعِد التحميل قبل رفعها.",
+  rehearsalDrainGuidance: "أبقِ الصفحة مفتوحة حتى تفرغ القائمتان، ثم ابدأ بروفة جديدة.",
+  rehearsalNextStep: "التقط كل إطار مفعّل، واختبر فشلَي شبكة، ثم أعد التحميل ودع القوائم تُفرَّغ بالترتيب.",
+  rehearsalLeave: "مغادرة البروفة",
+  rehearsalJoinError: "تعذر الانضمام إلى هذه البروفة.",
+  rehearsalAdminTitle: "بروفة الجهاز الحقيقي",
+  rehearsalAdminIntro: "تحقق من الآيباد وجهاز العرض واستعادة الشبكة والتسليم العام وحذف مراجعة دقيق واحد.",
+  rehearsalUnauthorized: "رُفض مفتاح المسؤول.",
+  rehearsalLoadError: "تعذر تحميل حالة البروفة.",
+  rehearsalStartError: "تعذر بدء البروفة.",
+  rehearsalActionError: "لم يكتمل إجراء البروفة.",
+  rehearsalDeliveryError: "لم تتوفر الصورة الدقيقة من موجز الصور العام ورابط الصورة العام معًا.",
+  rehearsalStart: "بدء البروفة",
+  rehearsalStartNew: "بدء بروفة جديدة",
+  rehearsalStartConfirm: "بدء بروفة ثابتة من الإعداد الحالي؟",
+  rehearsalWorking: "جارٍ العمل…",
+  rehearsalConfirm: "تأكيد البدء",
+  rehearsalLoading: "جارٍ تحميل حالة البروفة…",
+  rehearsalStale: "قديمة — ابدأ بروفة جديدة",
+  rehearsalStatus: "الحالة: {status}",
+  rehearsalQrAlt: "امسح للانضمام إلى هذه البروفة في الكشك",
+  rehearsalReqBoothReady: "الكاميرا والتخزين الدائم جاهزان",
+  rehearsalReqFrames: "تم التقاط كل إطار مفعّل",
+  rehearsalReqFailures: "تم تسجيل فشلَي شبكة مختلفين",
+  rehearsalReqReload: "استعيدت الصور المعلقة بعد إعادة التحميل",
+  rehearsalReqDrain: "رُفعت الصور المستعادة بالترتيب",
+  rehearsalReqDelivery: "لوحظ الموجز العام وتسليم الصورة الدقيقة",
+  rehearsalReqCanary: "حُذفت صورة اختبار دقيقة معيّنة",
+  rehearsalReqEmpty: "تم تأكيد فراغ قائمة الصور",
+  rehearsalManualTitle: "فحوصات فعلية",
+  rehearsalManualComposition: "تم فحص التركيب على الآيباد الحقيقي",
+  rehearsalManualProjector: "تم فحص العرض وإيقاف التمرير اليدوي",
+  rehearsalManualPower: "تم فحص القفل التلقائي والوضع المثبّت",
+  rehearsalManualCharging: "تم فحص الطاقة والشحن",
+  rehearsalManualBackup: "تم فحص استعادة الشبكة الاحتياطية",
+  rehearsalTrackedPhotos: "صور البروفة المتتبعة",
+  rehearsalNoPhotos: "لا توجد صور بروفة مؤكدة بعد.",
+  rehearsalObserveDelivery: "مراقبة التسليم العام",
+  rehearsalUseCanary: "الحذف كصورة اختبار دقيقة",
+  rehearsalRetain: "الاحتفاظ بالصورة",
+  rehearsalDeleteExact: "حذف الصورة الدقيقة",
+  rehearsalDeleteConfirm: "حذف مفتاح الكائن الكامل هذا فقط؟",
+  rehearsalAbandon: "ترك البروفة دون تنظيف",
 };
 
 const catalogs: Record<SupportedLocale, Record<MessageKey, string>> = {

From 89a9536f17652d2b00a518359931eb52c3cba1d6 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:16:10 +0800
Subject: [PATCH 101/105] fix: harden rehearsal evidence ingestion

---
 app/api/upload/route.test.ts |  17 +++
 app/event-store.test.ts      |  91 +++++++++++++
 app/event-store.ts           | 246 +++++++++++++++++++++++++++++++++--
 app/rehearsal.ts             |   6 +-
 app/upload-contract.test.ts  |  11 ++
 app/upload-contract.ts       |   8 ++
 6 files changed, 363 insertions(+), 16 deletions(-)

diff --git a/app/api/upload/route.test.ts b/app/api/upload/route.test.ts
index 15401ac..8f8c23c 100644
--- a/app/api/upload/route.test.ts
+++ b/app/api/upload/route.test.ts
@@ -277,6 +277,23 @@ describe("upload route", () => {
     expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(0);
   });
 
+  test("rejects a tracked upload with an evidence-incompatible timestamp before writing public bytes", async () => {
+    const { photos, deps } = memoryDeps();
+    await deps.store.startRehearsal("launch", { rehearsalId: REHEARSAL_ID });
+
+    const response = await handleUpload(request("launch", {
+      headers: stableHeaders({
+        "x-captured-at": "0000000000000",
+        "x-rehearsal-id": REHEARSAL_ID,
+      }),
+    }), deps);
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({ error: "invalid_captured_at" });
+    expect((await photos.list({ prefix: "launch/" })).objects).toHaveLength(0);
+    expect((await deps.store.readRehearsal("launch", REHEARSAL_ID)).evidence).toEqual([]);
+  });
+
   test("retries missing rehearsal evidence without duplicating the public image", async () => {
     const state = new FailPrivateWrites(
       `events/launch/rehearsals/${REHEARSAL_ID}/evidence/`,
diff --git a/app/event-store.test.ts b/app/event-store.test.ts
index f0f7355..da55702 100644
--- a/app/event-store.test.ts
+++ b/app/event-store.test.ts
@@ -16,6 +16,7 @@ import {
   InvalidStoredRehearsalError,
   PresetConflictError,
   RehearsalConflictError,
+  RehearsalEvidenceLimitError,
   RehearsalNotFoundError,
   eventConfigKey,
   eventConfigMutationKey,
@@ -584,6 +585,96 @@ describe("private rehearsal storage", () => {
     })).rejects.toBeInstanceOf(RehearsalConflictError);
   });
 
+  test("gives one simultaneous exact evidence retry ownership of the append", async () => {
+    const store = new EventStore(
+      new InMemoryObjectStore(),
+      new InMemoryObjectStore(),
+      "https://photos.example",
+      () => new Date("2026-07-24T00:00:00.000Z"),
+    );
+    await store.startRehearsal("launch", { rehearsalId });
+    const input = {
+      version: 1 as const,
+      id: evidenceId,
+      rehearsalId,
+      observedAt: 1_753_315_200_000,
+      kind: "abandoned" as const,
+    };
+
+    const results = await Promise.all([
+      store.appendRehearsalEvidence("launch", rehearsalId, input),
+      store.appendRehearsalEvidence("launch", rehearsalId, input),
+    ]);
+
+    expect(results.map((result) => result.idempotent).sort()).toEqual([false, true]);
+    expect(results[0]!.evidence).toEqual(results[1]!.evidence);
+  });
+
+  test("atomically caps simultaneous distinct evidence appends at 512 records", async () => {
+    const state = new InMemoryObjectStore();
+    const store = new EventStore(
+      new InMemoryObjectStore(),
+      state,
+      "https://photos.example",
+      () => new Date("2026-07-24T00:00:00.000Z"),
+    );
+    await store.startRehearsal("launch", { rehearsalId });
+    for (let index = 0; index < 511; index += 1) {
+      const id = `018f0000-0000-4000-8000-${index.toString(16).padStart(12, "0")}`;
+      const observedAt = 1_753_315_200_000 + index;
+      state.set(
+        rehearsalEvidenceKey("launch", rehearsalId, observedAt, id),
+        JSON.stringify({
+          version: 1,
+          id,
+          rehearsalId,
+          observedAt,
+          recordedAt: new Date(1_753_315_200_000 + index).toISOString(),
+          kind: "abandoned",
+        }),
+      );
+    }
+    const contenders = [
+      {
+        version: 1 as const,
+        id: "018f0000-0000-4000-8000-000000000601",
+        rehearsalId,
+        observedAt: 1_753_315_201_000,
+        kind: "abandoned" as const,
+      },
+      {
+        version: 1 as const,
+        id: "018f0000-0000-4000-8000-000000000602",
+        rehearsalId,
+        observedAt: 1_753_315_201_001,
+        kind: "abandoned" as const,
+      },
+    ];
+
+    const results = await Promise.allSettled(
+      contenders.map((input) =>
+        store.appendRehearsalEvidence("launch", rehearsalId, input)
+      ),
+    );
+
+    const fulfilled = results.filter(
+      (result): result is PromiseFulfilledResult<Awaited<ReturnType<typeof store.appendRehearsalEvidence>>> =>
+        result.status === "fulfilled",
+    );
+    const rejected = results.filter(
+      (result): result is PromiseRejectedResult => result.status === "rejected",
+    );
+    expect(fulfilled).toHaveLength(1);
+    expect(rejected).toHaveLength(1);
+    expect(rejected[0]!.reason).toBeInstanceOf(RehearsalEvidenceLimitError);
+    expect((await store.readRehearsal("launch", rehearsalId)).evidence).toHaveLength(512);
+
+    const winner = fulfilled[0]!.value.evidence;
+    const retryInput = contenders.find((input) => input.id === winner.id)!;
+    expect(await store.appendRehearsalEvidence("launch", rehearsalId, retryInput))
+      .toEqual({ evidence: winner, idempotent: true });
+  });
+
   test("isolates Events and fails explicitly for missing or corrupt private records", async () => {
     const state = new InMemoryObjectStore();
     const store = new EventStore(new InMemoryObjectStore(), state, "https://photos.example");
diff --git a/app/event-store.ts b/app/event-store.ts
index d6091f7..48603e2 100644
--- a/app/event-store.ts
+++ b/app/event-store.ts
@@ -335,6 +335,15 @@ const rehearsalEvidenceIdentityKey = (
   rehearsalId: string,
   evidenceId: string,
 ) => `events/${canonicalEvent(event)}/rehearsals/${rehearsalId}/evidence-identities/${evidenceId}.json`;
+const rehearsalEvidenceIdentityPrefix = (event: string, rehearsalId: string) =>
+  `events/${canonicalEvent(event)}/rehearsals/${rehearsalId}/evidence-identities/`;
+const REHEARSAL_EVIDENCE_CAPACITY = 512;
+const rehearsalEvidenceSlotPrefix = (event: string, rehearsalId: string) =>
+  `events/${canonicalEvent(event)}/rehearsals/${rehearsalId}/evidence-slots/`;
+const rehearsalEvidenceSlotKey = (event: string, rehearsalId: string, slot: number) =>
+  `${rehearsalEvidenceSlotPrefix(event, rehearsalId)}${String(slot).padStart(3, "0")}.json`;
+const rehearsalEvidenceSlotsReadyKey = (event: string, rehearsalId: string) =>
+  `events/${canonicalEvent(event)}/rehearsals/${rehearsalId}/evidence-slots-ready.json`;
 export const legacyEventConfigKey = (event: string) => `_config/${event}.json`;
 export const eventPhotoPrefix = (event: string) => `${event}/`;
 export const stablePhotoKey = (event: string, id: StableCaptureIdentity) =>
@@ -981,10 +990,12 @@ export class EventStore {
       const page = await this.state.list({
         prefix: rehearsalEvidencePrefix(canonical, exactId),
         ...(cursor ? { cursor } : {}),
-        limit: Math.min(PAGE_SIZE, 513 - evidence.length),
+        limit: Math.min(PAGE_SIZE, REHEARSAL_EVIDENCE_CAPACITY + 1 - evidence.length),
       });
       for (const listed of page.objects) {
-        if (evidence.length >= 512) throw new RehearsalEvidenceLimitError();
+        if (evidence.length >= REHEARSAL_EVIDENCE_CAPACITY) {
+          throw new RehearsalEvidenceLimitError();
+        }
         const object = await this.state.get(listed.key);
         if (!object) throw new InvalidStoredRehearsalError(canonical, exactId);
         let value: unknown;
@@ -1029,45 +1040,77 @@ export class EventStore {
     const key = rehearsalEvidenceKey(canonical, rehearsalId, record.observedAt, record.id);
     const identityKey = rehearsalEvidenceIdentityKey(canonical, rehearsalId, record.id);
     const semantic = rehearsalEvidenceSemantic(record);
+    const current = await this.readRehearsal(canonical, rehearsalId);
+    await this.ensureRehearsalEvidenceSlotMigration(
+      canonical,
+      rehearsalId,
+      current.evidence,
+    );
+    const slot = await this.claimRehearsalEvidenceSlot(
+      canonical,
+      rehearsalId,
+      key,
+      record,
+      semantic,
+    );
+    const claimedRecord = slot.evidence;
+    const claimedKey = rehearsalEvidenceKey(
+      canonical,
+      rehearsalId,
+      claimedRecord.observedAt,
+      claimedRecord.id,
+    );
     const existingIdentity = await this.state.get(identityKey);
     if (existingIdentity) {
-      return this.finishExistingRehearsalEvidence(
+      const result = await this.finishExistingRehearsalEvidence(
         canonical,
         rehearsalId,
         record.id,
-        key,
+        claimedKey,
         semantic,
         existingIdentity,
       );
+      return { evidence: result.evidence, idempotent: slot.existing };
     }
-    const current = await this.readRehearsal(canonical, rehearsalId);
-    if (current.evidence.length >= 512) throw new RehearsalEvidenceLimitError();
     const claimed = await this.state.compareAndSwap(
       identityKey,
       null,
-      JSON.stringify({ version: 1, key, evidence: record }),
+      JSON.stringify({ version: 1, key: claimedKey, evidence: claimedRecord }),
       jsonWriteOptions(),
     );
     if (!claimed) {
       const raced = await this.state.get(identityKey);
       if (!raced) throw new RehearsalConflictError(record.id);
-      return this.finishExistingRehearsalEvidence(
+      const result = await this.finishExistingRehearsalEvidence(
         canonical,
         rehearsalId,
         record.id,
-        key,
+        claimedKey,
         semantic,
         raced,
       );
+      return { evidence: result.evidence, idempotent: slot.existing };
     }
     const created = await this.state.compareAndSwap(
-      key,
+      claimedKey,
       null,
-      JSON.stringify(record),
+      JSON.stringify(claimedRecord),
       jsonWriteOptions(),
     );
-    if (!created) throw new RehearsalConflictError(record.id);
-    return { evidence: record, idempotent: false };
+    if (!created) {
+      const identity = await this.state.get(identityKey);
+      if (!identity) throw new RehearsalConflictError(record.id);
+      const result = await this.finishExistingRehearsalEvidence(
+        canonical,
+        rehearsalId,
+        record.id,
+        claimedKey,
+        semantic,
+        identity,
+      );
+      return { evidence: result.evidence, idempotent: slot.existing };
+    }
+    return { evidence: claimedRecord, idempotent: slot.existing };
   }
 
   async recordRehearsalUpload(
@@ -1160,6 +1203,174 @@ export class EventStore {
     return { evidence, idempotent: true };
   }
 
+  private async ensureRehearsalEvidenceSlotMigration(
+    event: string,
+    rehearsalId: string,
+    evidence: RehearsalEvidence[],
+  ): Promise<void> {
+    const readyKey = rehearsalEvidenceSlotsReadyKey(event, rehearsalId);
+    const ready = await this.state.get(readyKey);
+    if (ready) {
+      await this.validateRehearsalEvidenceSlotsReady(event, rehearsalId, ready);
+      return;
+    }
+
+    for (const record of evidence) {
+      const key = rehearsalEvidenceKey(event, rehearsalId, record.observedAt, record.id);
+      await this.claimRehearsalEvidenceSlot(
+        event,
+        rehearsalId,
+        key,
+        record,
+        rehearsalEvidenceSemantic(record),
+      );
+    }
+
+    let cursor: string | undefined;
+    do {
+      const page = await this.state.list({
+        prefix: rehearsalEvidenceIdentityPrefix(event, rehearsalId),
+        ...(cursor ? { cursor } : {}),
+        limit: PAGE_SIZE,
+      });
+      for (const listed of page.objects) {
+        const object = await this.state.get(listed.key);
+        if (!object) throw new InvalidStoredRehearsalError(event, rehearsalId);
+        const marker = await this.readRehearsalEvidenceMarker(
+          event,
+          rehearsalId,
+          object,
+        );
+        if (
+          rehearsalEvidenceIdentityKey(event, rehearsalId, marker.evidence.id)
+          !== listed.key
+        ) {
+          throw new InvalidStoredRehearsalError(event, rehearsalId);
+        }
+        await this.claimRehearsalEvidenceSlot(
+          event,
+          rehearsalId,
+          marker.key,
+          marker.evidence,
+          rehearsalEvidenceSemantic(marker.evidence),
+        );
+      }
+      cursor = page.truncated ? page.cursor : undefined;
+      if (page.truncated && !cursor) {
+        throw new InvalidStoredRehearsalError(event, rehearsalId);
+      }
+    } while (cursor);
+
+    const marker = JSON.stringify({
+      version: 1,
+      capacity: REHEARSAL_EVIDENCE_CAPACITY,
+    });
+    const created = await this.state.compareAndSwap(
+      readyKey,
+      null,
+      marker,
+      jsonWriteOptions(),
+    );
+    if (!created) {
+      const raced = await this.state.get(readyKey);
+      if (!raced) throw new InvalidStoredRehearsalError(event, rehearsalId);
+      await this.validateRehearsalEvidenceSlotsReady(event, rehearsalId, raced);
+    }
+  }
+
+  private async validateRehearsalEvidenceSlotsReady(
+    event: string,
+    rehearsalId: string,
+    object: StoredObjectBody,
+  ): Promise<void> {
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    if (
+      !isRecord(value)
+      || Object.keys(value).length !== 2
+      || value.version !== 1
+      || value.capacity !== REHEARSAL_EVIDENCE_CAPACITY
+    ) {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+  }
+
+  private async claimRehearsalEvidenceSlot(
+    event: string,
+    rehearsalId: string,
+    key: string,
+    record: RehearsalEvidence,
+    semantic: string,
+  ): Promise<{ evidence: RehearsalEvidence; existing: boolean }> {
+    const start = rehearsalEvidenceSlotStart(record.id);
+    const marker = JSON.stringify({ version: 1, key, evidence: record });
+    for (let offset = 0; offset < REHEARSAL_EVIDENCE_CAPACITY; offset += 1) {
+      const slot = (start + offset) % REHEARSAL_EVIDENCE_CAPACITY;
+      const slotKey = rehearsalEvidenceSlotKey(event, rehearsalId, slot);
+      let object = await this.state.get(slotKey);
+      if (!object) {
+        const created = await this.state.compareAndSwap(
+          slotKey,
+          null,
+          marker,
+          jsonWriteOptions(),
+        );
+        if (created) return { evidence: record, existing: false };
+        object = await this.state.get(slotKey);
+        if (!object) throw new InvalidStoredRehearsalError(event, rehearsalId);
+      }
+      const stored = await this.readRehearsalEvidenceMarker(
+        event,
+        rehearsalId,
+        object,
+      );
+      if (stored.evidence.id !== record.id) continue;
+      if (
+        stored.key !== key
+        || rehearsalEvidenceSemantic(stored.evidence) !== semantic
+      ) {
+        throw new RehearsalConflictError(record.id);
+      }
+      return { evidence: stored.evidence, existing: true };
+    }
+    throw new RehearsalEvidenceLimitError();
+  }
+
+  private async readRehearsalEvidenceMarker(
+    event: string,
+    rehearsalId: string,
+    object: StoredObjectBody,
+  ): Promise<{ key: string; evidence: RehearsalEvidence }> {
+    let value: unknown;
+    try {
+      value = await object.json<unknown>();
+    } catch {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    if (
+      !isRecord(value)
+      || Object.keys(value).length !== 3
+      || value.version !== 1
+      || typeof value.key !== "string"
+    ) {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    const evidence = parseRehearsalEvidence(value.evidence, event);
+    if (
+      !evidence
+      || evidence.rehearsalId !== rehearsalId
+      || rehearsalEvidenceKey(event, rehearsalId, evidence.observedAt, evidence.id)
+        !== value.key
+    ) {
+      throw new InvalidStoredRehearsalError(event, rehearsalId);
+    }
+    return { key: value.key, evidence };
+  }
+
   private async readRehearsalSessionObject(
     event: string,
     rehearsalId: string,
@@ -2563,6 +2774,15 @@ function rehearsalEvidenceSemantic(evidence: RehearsalEvidence): string {
   return JSON.stringify(semantic);
 }
 
+function rehearsalEvidenceSlotStart(evidenceId: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < evidenceId.length; index += 1) {
+    hash ^= evidenceId.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0) % REHEARSAL_EVIDENCE_CAPACITY;
+}
+
 function configExperience(config: EventConfig): EventExperience {
   const { boothKeyHash: _boothKeyHash, currentRevisionId: _currentRevisionId, ...experience } = config;
   return experience;
diff --git a/app/rehearsal.ts b/app/rehearsal.ts
index 3aee0ff..6e61ff4 100644
--- a/app/rehearsal.ts
+++ b/app/rehearsal.ts
@@ -161,7 +161,7 @@ export function isRehearsalId(value: unknown): value is string {
   return isUuid(value);
 }
 
-function isTimestamp(value: unknown): value is number {
+export function isRehearsalTimestamp(value: unknown): value is number {
   return typeof value === "number"
     && Number.isSafeInteger(value)
     && value >= 1_000_000_000_000
@@ -251,7 +251,7 @@ export function parseRehearsalEvidence(
       )
     )
     || !isUuid(value.rehearsalId)
-    || !isTimestamp(value.observedAt)
+    || !isRehearsalTimestamp(value.observedAt)
     || !isStoredInstant(value.recordedAt)
   ) {
     return null;
@@ -296,7 +296,7 @@ export function parseRehearsalEvidence(
       if (
         !hasExactKeys(value, keys)
         || !isUuid(value.captureId)
-        || !isTimestamp(value.capturedAt)
+        || !isRehearsalTimestamp(value.capturedAt)
         || !isPhotoKey(value.photoKey, event)
         || (
           value.frameKey !== undefined
diff --git a/app/upload-contract.test.ts b/app/upload-contract.test.ts
index 98e39f6..322ae9d 100644
--- a/app/upload-contract.test.ts
+++ b/app/upload-contract.test.ts
@@ -38,6 +38,17 @@ describe("stable upload headers", () => {
     expect(parseUploadHeaders(headers({ "content-type": "image/jpeg" }))).toEqual({ kind: "legacy" });
   });
 
+  test("preserves the existing untracked stable timestamp contract", () => {
+    expect(parseUploadHeaders(headers({
+      ...identity,
+      "x-captured-at": "0000000000000",
+    }))).toEqual({
+      kind: "stable",
+      captureId: identity["x-capture-id"],
+      capturedAt: 0,
+    });
+  });
+
   test("rejects partial capture identity", () => {
     expect(() => parseUploadHeaders(headers({ "x-capture-id": identity["x-capture-id"] })))
       .toThrow(InvalidUploadHeadersError);
diff --git a/app/upload-contract.ts b/app/upload-contract.ts
index 8f43081..a953d51 100644
--- a/app/upload-contract.ts
+++ b/app/upload-contract.ts
@@ -1,3 +1,5 @@
+import { isRehearsalTimestamp } from "./rehearsal";
+
 export type CaptureSource = "framed" | "camera-fallback";
 
 export type CaptureMetadata = {
@@ -84,6 +86,12 @@ export function parseUploadHeaders(headers: Headers): UploadIntent {
   if (rehearsalId !== null && !UUID_V4.test(rehearsalId)) {
     invalid("invalid_rehearsal_id", "Rehearsal ID must be a lowercase UUID-v4.");
   }
+  if (rehearsalId !== null && !isRehearsalTimestamp(Number(capturedAt))) {
+    invalid(
+      "invalid_captured_at",
+      "Tracked captured-at must be compatible with rehearsal evidence.",
+    );
+  }
 
   return {
     kind: "stable",

From 78b92f66a32a7126745f11eb0300673fe5bb905e Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:20:43 +0800
Subject: [PATCH 102/105] fix: reconcile rehearsal recovery and deletion

---
 app/[event]/admin/rehearsal-panel.tsx     | 142 +++++++++++++++++++---
 app/[event]/booth-session/lifecycle.ts    |   8 +-
 app/[event]/booth-session/session.test.ts |  10 +-
 app/[event]/booth-session/session.ts      |   1 +
 app/[event]/page.tsx                      |  23 +++-
 5 files changed, 161 insertions(+), 23 deletions(-)

diff --git a/app/[event]/admin/rehearsal-panel.tsx b/app/[event]/admin/rehearsal-panel.tsx
index 955fbc0..fb8ceda 100644
--- a/app/[event]/admin/rehearsal-panel.tsx
+++ b/app/[event]/admin/rehearsal-panel.tsx
@@ -20,6 +20,10 @@ type WithoutEvidenceEnvelope<T> = T extends unknown
   ? Omit<T, "version" | "id" | "rehearsalId" | "observedAt">
   : never;
 type EvidenceFields = WithoutEvidenceEnvelope<RehearsalEvidenceInput>;
+type ConfirmedDeletion = {
+  kind: "canary" | "delete";
+  cleanupPending: boolean;
+};
 
 const requirements: RehearsalRequirement[] = [
   "booth-ready", "frames-covered", "two-network-failures", "reload-recovered",
@@ -66,11 +70,13 @@ export function RehearsalPanel({
   const [error, setError] = useState("");
   const [confirmStart, setConfirmStart] = useState(false);
   const [confirmDelete, setConfirmDelete] = useState<string | null>(null);
+  const [confirmCanary, setConfirmCanary] = useState<string | null>(null);
   const [qr, setQr] = useState("");
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const readInFlight = useRef(false);
   const stopped = useRef(false);
-  const confirmedCanaryDeletes = useRef(new Map<string, boolean>());
+  const confirmedDeletes = useRef(new Map<string, ConfirmedDeletion>());
+  const confirmedDeleteScope = useRef("");
   const deleteTrigger = useRef<HTMLButtonElement | null>(null);
 
   const label = useCallback(
@@ -181,15 +187,100 @@ export function RehearsalPanel({
     await load();
   };
 
+  const confirmedDeleteMap = () => {
+    if (!view) return confirmedDeletes.current;
+    const scope = `webbooth:${event}:rehearsal:${view.session.id}:confirmed-deletes`;
+    if (confirmedDeleteScope.current === scope) return confirmedDeletes.current;
+    confirmedDeleteScope.current = scope;
+    confirmedDeletes.current.clear();
+    try {
+      const stored = JSON.parse(window.localStorage.getItem(scope) ?? "[]") as unknown;
+      if (Array.isArray(stored)) {
+        for (const entry of stored) {
+          if (
+            Array.isArray(entry)
+            && entry.length === 3
+            && typeof entry[0] === "string"
+            && (entry[1] === "canary" || entry[1] === "delete")
+            && typeof entry[2] === "boolean"
+          ) {
+            confirmedDeletes.current.set(entry[0], {
+              kind: entry[1],
+              cleanupPending: entry[2],
+            });
+          }
+        }
+      }
+    } catch {
+      // The in-memory marker still prevents a repeated delete in this page.
+    }
+    return confirmedDeletes.current;
+  };
+
+  const persistConfirmedDeletes = () => {
+    if (!confirmedDeleteScope.current) return;
+    try {
+      window.localStorage.setItem(
+        confirmedDeleteScope.current,
+        JSON.stringify([...confirmedDeletes.current].map(([key, value]) => [
+          key,
+          value.kind,
+          value.cleanupPending,
+        ])),
+      );
+    } catch {
+      // Storage denial is visible operationally through a retained in-page marker.
+    }
+  };
+
+  const deletePublicPhoto = async (
+    photoKey: string,
+    kind: ConfirmedDeletion["kind"],
+  ) => {
+    const retained = confirmedDeleteMap().get(photoKey);
+    if (retained) {
+      if (retained.kind !== kind) throw new Error(label("rehearsalActionError"));
+      return retained.cleanupPending;
+    }
+    const query = new URLSearchParams({ event, key: photoKey });
+    const response = await request(`/api/photos?${query}`, { method: "DELETE" });
+    const result = await response.json() as {
+      deleted?: unknown;
+      cleanupPending?: unknown;
+      key?: unknown;
+    };
+    if (
+      !response.ok
+      || result.deleted !== true
+      || result.key !== photoKey
+      || typeof result.cleanupPending !== "boolean"
+    ) {
+      throw new Error(label("rehearsalActionError"));
+    }
+    const confirmed = {
+      kind,
+      cleanupPending: result.cleanupPending,
+    } satisfies ConfirmedDeletion;
+    confirmedDeleteMap().set(photoKey, confirmed);
+    persistConfirmedDeletes();
+    return confirmed.cleanupPending;
+  };
+
+  const clearConfirmedDelete = (photoKey: string) => {
+    confirmedDeleteMap().delete(photoKey);
+    persistConfirmedDeletes();
+  };
+
   const disposition = async (photoKey: string, action: "retain" | "delete") => {
     setBusy(`${action}:${photoKey}`); setError("");
     try {
       if (action === "delete") {
-        const query = new URLSearchParams({ event, key: photoKey });
-        const response = await request(`/api/photos?${query}`, { method: "DELETE" });
-        if (!response.ok) throw new Error(label("rehearsalActionError"));
+        await deletePublicPhoto(photoKey, "delete");
+      } else if (confirmedDeleteMap().has(photoKey)) {
+        throw new Error(label("rehearsalActionError"));
       }
       await append({ kind: action === "retain" ? "photo-retained" : "photo-deleted", photoKey });
+      if (action === "delete") clearConfirmedDelete(photoKey);
       setConfirmDelete(null);
       requestAnimationFrame(() => deleteTrigger.current?.focus());
     } catch (cause) {
@@ -218,18 +309,16 @@ export function RehearsalPanel({
   const deleteCanary = async (photoKey: string) => {
     setBusy("canary"); setError("");
     try {
-      let cleanupPending = confirmedCanaryDeletes.current.get(photoKey);
-      if (cleanupPending === undefined) {
+      const retained = confirmedDeleteMap().get(photoKey);
+      if (retained?.kind !== "canary") {
+        if (retained) throw new Error(label("rehearsalActionError"));
         await append({ kind: "canary-designated", photoKey });
-        const query = new URLSearchParams({ event, key: photoKey });
-        const response = await request(`/api/photos?${query}`, { method: "DELETE" });
-        const result = await response.json() as { deleted?: boolean; cleanupPending?: boolean };
-        if (!response.ok || result.deleted !== true) throw new Error(label("rehearsalActionError"));
-        cleanupPending = result.cleanupPending === true;
-        confirmedCanaryDeletes.current.set(photoKey, cleanupPending);
       }
+      const cleanupPending = await deletePublicPhoto(photoKey, "canary");
       await append({ kind: "canary-deleted", photoKey, cleanupPending });
-      confirmedCanaryDeletes.current.delete(photoKey);
+      clearConfirmedDelete(photoKey);
+      setConfirmCanary(null);
+      requestAnimationFrame(() => deleteTrigger.current?.focus());
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : label("rehearsalActionError"));
     } finally { setBusy(""); }
@@ -305,17 +394,40 @@ export function RehearsalPanel({
                         <button type="button" disabled={Boolean(busy)} onClick={() => void observeDelivery(photo.photoKey)}>
                           {label("rehearsalObserveDelivery")}
                         </button>
-                        <button type="button" disabled={Boolean(busy)} onClick={() => void deleteCanary(photo.photoKey)}>
+                        <button
+                          type="button"
+                          disabled={Boolean(busy)}
+                          onClick={(event) => {
+                            deleteTrigger.current = event.currentTarget;
+                            setConfirmCanary(photo.photoKey);
+                          }}
+                        >
                           {label("rehearsalUseCanary")}
                         </button>
                         <button type="button" disabled={Boolean(busy)} onClick={() => void disposition(photo.photoKey, "retain")}>
                           {label("rehearsalRetain")}
                         </button>
-                        <button ref={deleteTrigger} type="button" disabled={Boolean(busy)} onClick={() => setConfirmDelete(photo.photoKey)}>
+                        <button
+                          type="button"
+                          disabled={Boolean(busy)}
+                          onClick={(event) => {
+                            deleteTrigger.current = event.currentTarget;
+                            setConfirmDelete(photo.photoKey);
+                          }}
+                        >
                           {label("rehearsalDeleteExact")}
                         </button>
                       </div>
                     )}
+                    {confirmCanary === photo.photoKey && (
+                      <div className={styles.rehearsalDeleteConfirm} role="alertdialog" aria-modal="true">
+                        <strong>{label("rehearsalDeleteConfirm")}</strong>
+                        <span>{photo.photoKey.slice(photo.photoKey.indexOf("/") + 1)}</span>
+                        <bdi><code>{photo.photoKey}</code></bdi>
+                        <button type="button" onClick={() => void deleteCanary(photo.photoKey)}>{label("rehearsalUseCanary")}</button>
+                        <button type="button" onClick={() => setConfirmCanary(null)}>{label("moderationCancel")}</button>
+                      </div>
+                    )}
                     {confirmDelete === photo.photoKey && (
                       <div className={styles.rehearsalDeleteConfirm} role="alertdialog" aria-modal="true">
                         <strong>{label("rehearsalDeleteConfirm")}</strong>
diff --git a/app/[event]/booth-session/lifecycle.ts b/app/[event]/booth-session/lifecycle.ts
index 5605c43..f3ca72d 100644
--- a/app/[event]/booth-session/lifecycle.ts
+++ b/app/[event]/booth-session/lifecycle.ts
@@ -6,6 +6,7 @@ import {
   type EventExperience,
 } from "../../event-config";
 import type { BoothAccessState } from "./access";
+import type { OutboxItem } from "./outbox";
 
 export type BoothAccessFeedback =
   | "recovering"
@@ -29,6 +30,7 @@ export type BoothPreflightResult =
 
 export type BoothSessionRecovery = {
   authBlockedItemId: string | null;
+  items?: readonly OutboxItem[];
 };
 
 export interface BoothLifecycleSession {
@@ -61,7 +63,7 @@ type BoothLifecycleDependencies<Result> = {
   loadCredential: (event: string) => { key: string } | null;
   clearCredential: (event: string) => void;
   onReset: (event: string) => void;
-  onOutboxRecovered: () => void;
+  onOutboxRecovered: (recovery: BoothSessionRecovery) => void;
   onAccess: (state: BoothAccessState, feedback: BoothAccessFeedback) => void;
   onFrames: (frames: string[] | null) => void;
   onExperience?: (experience: EventExperience | null) => void;
@@ -151,14 +153,14 @@ export class BoothLifecycleCoordinator<Result> {
       recovery = await session.recover();
     } catch {
       if (!this.isCurrent(active)) return;
-      this.deps.onOutboxRecovered();
+      this.deps.onOutboxRecovered({ authBlockedItemId: null, items: [] });
       this.deps.onAccess("recovery-only", "network");
       return;
     }
     if (!this.isCurrent(active)) return;
     active.authBlockedItemId = recovery.authBlockedItemId;
 
-    this.deps.onOutboxRecovered();
+    this.deps.onOutboxRecovered(recovery);
     this.deps.onAccess("locked", "locked");
     const stored = this.deps.loadCredential(event);
     if (!stored) return;
diff --git a/app/[event]/booth-session/session.test.ts b/app/[event]/booth-session/session.test.ts
index 373d233..290ca07 100644
--- a/app/[event]/booth-session/session.test.ts
+++ b/app/[event]/booth-session/session.test.ts
@@ -808,7 +808,10 @@ describe("BoothSession outbox", () => {
 
     const recovery = await session.recover();
 
-    expect(recovery).toEqual({ authBlockedItemId: "persisted-auth" });
+    expect(recovery).toEqual({
+      authBlockedItemId: "persisted-auth",
+      items: before,
+    });
     expect(await store.list("party")).toEqual(before);
   });
 
@@ -839,7 +842,10 @@ describe("BoothSession outbox", () => {
 
     const recovery = await session.recover();
 
-    expect(recovery).toEqual({ authBlockedItemId: null });
+    expect(recovery).toEqual({
+      authBlockedItemId: null,
+      items: before,
+    });
     expect(await store.list("party")).toEqual(before);
   });
 
diff --git a/app/[event]/booth-session/session.ts b/app/[event]/booth-session/session.ts
index f7aaedd..5b63a90 100644
--- a/app/[event]/booth-session/session.ts
+++ b/app/[event]/booth-session/session.ts
@@ -116,6 +116,7 @@ export class BoothSession {
     return {
       authBlockedItemId:
         pending[0]?.failureKind === "auth" ? pending[0].id : null,
+      items: pending,
     };
   }
 
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 3c9a0d3..0d80cff 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -176,6 +176,7 @@ export default function Booth() {
   const streamRef = useRef<MediaStream | null>(null);
   const sessionRef = useRef<BoothSession | null>(null);
   const photoOutboxRef = useRef<OutboxStore | null>(null);
+  const recoveredOutboxItemsRef = useRef<readonly OutboxItem[]>([]);
   const rehearsalClientRef = useRef<RehearsalClient | null>(null);
   const statePollerRef = useRef<BoothStatePoller | null>(null);
   const heartbeatReporterRef = useRef<BoothHeartbeatReporter | null>(null);
@@ -370,6 +371,7 @@ export default function Booth() {
         ),
       onReset: () => {
         const initial = createBoothOperationalSessionState(Date.now());
+        recoveredOutboxItemsRef.current = [];
         documentLocaleRef.current?.restore(event);
         pauseBoundary.reset();
         clearFrame();
@@ -393,7 +395,10 @@ export default function Booth() {
         setOnline(navigator.onLine);
         setUploadState(INITIAL_UPLOAD_STATE);
       },
-      onOutboxRecovered: () => setOutboxRecovered(true),
+      onOutboxRecovered: (recovery) => {
+        recoveredOutboxItemsRef.current = recovery.items ?? [];
+        setOutboxRecovered(true);
+      },
       onAccess: (state, feedback) => {
         if (state === "locked" && feedback === "rejected-key") {
           clearFrame();
@@ -685,8 +690,18 @@ export default function Booth() {
         await client.join();
         if (cancelled) return;
         try { window.sessionStorage.setItem(storageKey, client.bootId); } catch { /* restricted storage */ }
-        const recovered = await photoOutboxRef.current?.list(event) ?? [];
+        const recovered = recoveredOutboxItemsRef.current;
         await client.recordRecovery(recovered);
+        // The Photo Outbox is intentionally allowed to drain as soon as
+        // authenticated preflight succeeds. Reconcile rows already removed
+        // before the rehearsal join so their recovery proof cannot race the
+        // uploader or be lost.
+        const remaining = await photoOutboxRef.current?.list(event) ?? [];
+        const remainingIds = new Set(remaining.map(({ id }) => id));
+        for (const item of recovered) {
+          if (!remainingIds.has(item.id)) await client.recordAcknowledgement(item);
+        }
+        if (remaining.length === 0) await client.recordEmptyOutbox();
         await client.drainEvidence();
       } catch (cause) {
         if (!cancelled) {
@@ -708,13 +723,15 @@ export default function Booth() {
       !rehearsalState.rehearsal
       || (status !== "picking" && status !== "ready" && status !== "running")
       || !deviceIdRef.current
+      || operational.paused
+      || !streamRef.current?.getVideoTracks().some((track) => track.readyState === "live")
     ) return;
     void rehearsalClientRef.current?.recordReadiness({
       deviceId: deviceIdRef.current,
       cameraReady: true,
       durableStorage: uploadState.durable,
     });
-  }, [rehearsalState.rehearsal, status, uploadState.durable]);
+  }, [operational.paused, rehearsalState.rehearsal, status, uploadState.durable]);
 
   useEffect(() => {
     const reporter = heartbeatReporterRef.current;

From 89a68d768091506bc71744b5cab9e8ef4f3ab9d5 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:18:47 +0800
Subject: [PATCH 103/105] test: cover preset and rehearsal operations

---
 tests/rehearsal-operations.spec.ts | 492 +++++++++++++++++++++++++++++
 1 file changed, 492 insertions(+)
 create mode 100644 tests/rehearsal-operations.spec.ts

diff --git a/tests/rehearsal-operations.spec.ts b/tests/rehearsal-operations.spec.ts
new file mode 100644
index 0000000..06e84b9
--- /dev/null
+++ b/tests/rehearsal-operations.spec.ts
@@ -0,0 +1,492 @@
+import { expect, test, type BrowserContext, type Page } from "@playwright/test";
+
+const EVENT = "rehearsal-browser";
+const ADMIN_KEY = "browser-admin-secret";
+const REHEARSAL_ID = "018f0000-0000-4000-8000-000000000401";
+const PIXEL =
+  "data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=";
+
+const experience = {
+  frames: ["square"],
+  locales: ["en"],
+  defaultLocale: "en",
+  timeZone: "Asia/Singapore",
+  capture: {
+    reviewEnabled: true,
+    autoAcceptSeconds: 5,
+    countdownAudioDefault: false,
+  },
+  gallery: {
+    title: "Launch gallery",
+    accentColor: "#4f46e5",
+  },
+};
+
+type RequestRecord = {
+  method: string;
+  pathname: string;
+  search: string;
+  key: string;
+  body: unknown;
+};
+
+type TrackedPhoto = {
+  captureId: string;
+  photoKey: string;
+  disposition: "pending" | "canary-deleted" | "retained" | "deleted";
+};
+
+type RehearsalFixture = {
+  locale: "en" | "ar";
+  requests: RequestRecord[];
+  presets: Array<{
+    version: 1;
+    id: string;
+    label: string;
+    createdAt: string;
+    updatedAt: string;
+    config: typeof experience;
+  }>;
+  view: ReturnType<typeof rehearsalView> | null;
+  appliedRevisionId: string | null;
+  appliedPresetId: string | null;
+};
+
+function rehearsalView(
+  status: "active" | "stale" = "active",
+  trackedPhotos: TrackedPhoto[] = [],
+) {
+  const incomplete = () => ({ complete: false, evidenceIds: [] as string[] });
+  return {
+    session: {
+      version: 1 as const,
+      id: REHEARSAL_ID,
+      startedAt: "2026-07-24T00:00:00.000Z",
+      configRevisionId: null,
+      frames: ["square"],
+    },
+    summary: {
+      status,
+      stale: status === "stale",
+      requirements: {
+        "booth-ready": incomplete(),
+        "frames-covered": incomplete(),
+        "two-network-failures": incomplete(),
+        "reload-recovered": incomplete(),
+        "ordered-drain": incomplete(),
+        "public-delivery": incomplete(),
+        "canary-deleted": incomplete(),
+        "outbox-empty": incomplete(),
+      },
+      manualChecks: {
+        composition: false,
+        projector: false,
+        power: false,
+        charging: false,
+        "backup-network": false,
+      },
+      trackedPhotos,
+      remainingExactKeys: trackedPhotos
+        .filter(({ disposition }) => disposition === "pending")
+        .map(({ photoKey }) => photoKey),
+    },
+  };
+}
+
+function updateDisposition(
+  fixture: RehearsalFixture,
+  photoKey: string,
+  disposition: TrackedPhoto["disposition"],
+) {
+  if (!fixture.view) return;
+  fixture.view = rehearsalView(
+    fixture.view.summary.status === "stale" ? "stale" : "active",
+    fixture.view.summary.trackedPhotos.map((photo) =>
+      photo.photoKey === photoKey ? { ...photo, disposition } : photo
+    ),
+  );
+}
+
+async function installAdminMocks(
+  context: BrowserContext,
+  fixture: RehearsalFixture,
+) {
+  await context.route("**/api/**", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    const body = request.postData()
+      ? request.postDataJSON() as unknown
+      : null;
+    fixture.requests.push({
+      method: request.method(),
+      pathname: url.pathname,
+      search: url.search,
+      key: request.headers()["x-booth-key"] ?? "",
+      body,
+    });
+
+    const json = (payload: unknown, status = 200) =>
+      route.fulfill({
+        status,
+        contentType: "application/json",
+        body: JSON.stringify(payload),
+      });
+
+    if (url.pathname === "/api/health") {
+      await json({
+        upload: { status: "up", detail: "fixture" },
+        live: { status: "up", detail: "fixture" },
+      });
+      return;
+    }
+    if (url.pathname === "/api/config/revisions") {
+      const preset = fixture.presets.find(({ id }) =>
+        id === fixture.appliedPresetId
+      );
+      const config = preset?.config ?? {
+        ...experience,
+        locales: [fixture.locale],
+        defaultLocale: fixture.locale,
+      };
+      await json({
+        config: { ...config, hasBoothKey: true },
+        currentRevisionId: fixture.appliedRevisionId,
+        revisions: fixture.appliedRevisionId && fixture.appliedPresetId
+          ? [{
+              version: 1,
+              id: fixture.appliedRevisionId,
+              createdAt: "2026-07-24T00:01:00.000Z",
+              parentRevisionId: null,
+              reason: "preset",
+              sourcePresetId: fixture.appliedPresetId,
+              config,
+            }]
+          : [],
+      });
+      return;
+    }
+    if (url.pathname === "/api/presets" && request.method() === "GET") {
+      await json({ presets: fixture.presets, cursor: null });
+      return;
+    }
+    if (
+      url.pathname.startsWith("/api/presets/")
+      && url.pathname !== "/api/presets/apply"
+      && request.method() === "PUT"
+    ) {
+      const input = body as { label: string; config: typeof experience };
+      const id = decodeURIComponent(url.pathname.slice("/api/presets/".length));
+      const saved = {
+        version: 1 as const,
+        id,
+        label: input.label,
+        createdAt: "2026-07-24T00:00:00.000Z",
+        updatedAt: "2026-07-24T00:00:00.000Z",
+        config: input.config,
+      };
+      fixture.presets = [
+        ...fixture.presets.filter((preset) => preset.id !== id),
+        saved,
+      ];
+      await json(saved);
+      return;
+    }
+    if (
+      url.pathname === "/api/presets/apply"
+      && request.method() === "POST"
+    ) {
+      const input = body as { presetId: string; mutationId: string };
+      const preset = fixture.presets.find(({ id }) => id === input.presetId);
+      if (!preset) {
+        await json({ error: "missing" }, 404);
+        return;
+      }
+      fixture.appliedRevisionId = input.mutationId;
+      fixture.appliedPresetId = input.presetId;
+      await json({
+        ...preset.config,
+        hasBoothKey: true,
+        currentRevisionId: input.mutationId,
+        sourcePresetId: input.presetId,
+        idempotent: false,
+      });
+      return;
+    }
+    if (url.pathname === "/api/booth-state") {
+      await json({
+        version: 1,
+        paused: false,
+        updatedAt: "2026-07-24T12:00:00.000Z",
+      });
+      return;
+    }
+    if (url.pathname === "/api/booths") {
+      await json({ booths: [], cursor: null });
+      return;
+    }
+    if (url.pathname === "/api/moderation/photos") {
+      await json({ photos: [], nextCursor: null });
+      return;
+    }
+    if (url.pathname === "/api/rehearsals" && request.method() === "GET") {
+      if (!fixture.view) {
+        await json({ error: "missing" }, 404);
+      } else {
+        await json({ rehearsal: fixture.view });
+      }
+      return;
+    }
+    if (url.pathname === "/api/rehearsals" && request.method() === "POST") {
+      fixture.view = rehearsalView("active", [
+        {
+          captureId: "capture-canary",
+          photoKey: `${EVENT}/1753315200003-canary.jpg`,
+          disposition: "pending",
+        },
+        {
+          captureId: "capture-retain",
+          photoKey: `${EVENT}/1753315200002-retain.jpg`,
+          disposition: "pending",
+        },
+        {
+          captureId: "capture-delete",
+          photoKey: `${EVENT}/1753315200001-delete.jpg`,
+          disposition: "pending",
+        },
+      ]);
+      await json({ rehearsal: fixture.view });
+      return;
+    }
+    if (
+      url.pathname === "/api/rehearsals/evidence"
+      && request.method() === "POST"
+    ) {
+      const evidence = body as {
+        kind: string;
+        photoKey?: string;
+      };
+      if (evidence.photoKey && evidence.kind === "canary-deleted") {
+        updateDisposition(fixture, evidence.photoKey, "canary-deleted");
+      }
+      if (evidence.photoKey && evidence.kind === "photo-retained") {
+        updateDisposition(fixture, evidence.photoKey, "retained");
+      }
+      if (evidence.photoKey && evidence.kind === "photo-deleted") {
+        updateDisposition(fixture, evidence.photoKey, "deleted");
+      }
+      await json({ accepted: true });
+      return;
+    }
+    if (url.pathname === "/api/photos" && request.method() === "DELETE") {
+      await json({
+        deleted: true,
+        key: url.searchParams.get("key"),
+        cleanupPending: false,
+      });
+      return;
+    }
+    if (url.pathname === "/api/photos" && request.method() === "GET") {
+      await json({
+        photos: fixture.view?.summary.trackedPhotos.map(({ photoKey }) => ({
+          key: photoKey,
+          url: PIXEL,
+        })) ?? [],
+        cursor: null,
+      });
+      return;
+    }
+    throw new Error(
+      `Unexpected Admin API request: ${request.method()} ${url.pathname}`,
+    );
+  });
+}
+
+async function unlock(page: Page) {
+  await page.goto(`/${EVENT}/admin`);
+  const input = page.getByLabel("Admin key");
+  await input.fill(ADMIN_KEY);
+  await input.press("Enter");
+  await expect(page.getByRole("heading", { name: EVENT })).toBeVisible();
+}
+
+function createFixture(
+  options: { locale?: "en" | "ar"; view?: RehearsalFixture["view"] } = {},
+): RehearsalFixture {
+  return {
+    locale: options.locale ?? "en",
+    requests: [],
+    presets: [{
+      version: 1,
+      id: "launch-night",
+      label: "Launch Night",
+      createdAt: "2026-07-24T00:00:00.000Z",
+      updatedAt: "2026-07-24T00:00:00.000Z",
+      config: experience,
+    }],
+    view: options.view ?? null,
+    appliedRevisionId: null,
+    appliedPresetId: null,
+  };
+}
+
+test("Admin saves a credential-free preset and confirms its exact application", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture();
+  await installAdminMocks(context, fixture);
+  await unlock(page);
+
+  await expect(page.getByText(
+    "Booth credentials are never copied into presets.",
+  )).toBeVisible();
+  await page.getByLabel("Preset ID").fill("after-party");
+  await page.getByLabel("Preset label").fill("After Party");
+  await page.getByRole("button", { name: "Create preset" }).click();
+  await expect(page.getByText("Preset After Party saved.")).toBeVisible();
+
+  const save = fixture.requests.find(({ method, pathname }) =>
+    method === "PUT" && pathname === "/api/presets/after-party"
+  );
+  expect(save?.key).toBe(ADMIN_KEY);
+  expect(save?.body).toMatchObject({
+    label: "After Party",
+    expectedUpdatedAt: null,
+  });
+  expect(JSON.stringify(save?.body)).not.toMatch(
+    /admin|boothKey|credential|secret/i,
+  );
+
+  const presetRow = page.getByRole("listitem").filter({
+    hasText: "After Party",
+  });
+  await presetRow.getByRole("button", { name: "Review apply" }).click();
+  const confirmation = page.getByRole("group", { name: "Apply preset" });
+  await expect(confirmation).toContainText(
+    `Apply preset After Party to Event ${EVENT}?`,
+  );
+  await expect(confirmation.getByText("after-party", { exact: true }))
+    .toBeVisible();
+  await confirmation.getByRole("button", { name: "Apply preset" }).click();
+  await expect(page.getByText("Applied preset After Party.")).toBeVisible();
+
+  const apply = fixture.requests.find(({ method, pathname }) =>
+    method === "POST" && pathname === "/api/presets/apply"
+  );
+  expect(apply?.key).toBe(ADMIN_KEY);
+  expect(apply?.search).toBe(`?event=${EVENT}`);
+  expect(apply?.body).toMatchObject({
+    presetId: "after-party",
+    baseRevisionId: null,
+  });
+  expect(JSON.stringify(apply?.body)).not.toContain(ADMIN_KEY);
+});
+
+test("guided rehearsal uses only exact tracked-photo dispositions", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture();
+  await installAdminMocks(context, fixture);
+  await unlock(page);
+
+  await expect(page.getByRole("heading", { name: "Real-device rehearsal" }))
+    .toBeVisible();
+  await page.getByRole("button", { name: "Start rehearsal" }).click();
+  await expect(page.getByText(
+    "Start an immutable rehearsal from the current configuration?",
+  )).toBeVisible();
+  await page.getByRole("button", { name: "Confirm start" }).click();
+  await expect(page.getByText("Status: active")).toBeVisible();
+  await expect(page.getByRole("link", {
+    name: `http://127.0.0.1:3100/${EVENT}?rehearsal=${REHEARSAL_ID}`,
+  })).toHaveAttribute(
+    "href",
+    `http://127.0.0.1:3100/${EVENT}?rehearsal=${REHEARSAL_ID}`,
+  );
+
+  const canaryKey = `${EVENT}/1753315200003-canary.jpg`;
+  const retainKey = `${EVENT}/1753315200002-retain.jpg`;
+  const deleteKey = `${EVENT}/1753315200001-delete.jpg`;
+
+  const canaryRow = page.getByRole("listitem").filter({ hasText: canaryKey });
+  await canaryRow.getByRole("button", {
+    name: "Delete as exact canary",
+  }).click();
+  await expect(canaryRow.getByText("canary-deleted", { exact: true }))
+    .toBeVisible();
+
+  const retainRow = page.getByRole("listitem").filter({ hasText: retainKey });
+  await retainRow.getByRole("button", { name: "Retain photo" }).click();
+  await expect(retainRow.getByText("retained", { exact: true })).toBeVisible();
+
+  const deleteRow = page.getByRole("listitem").filter({ hasText: deleteKey });
+  await deleteRow.getByRole("button", { name: "Delete exact photo" }).click();
+  const dialog = deleteRow.getByRole("alertdialog");
+  await expect(dialog).toContainText(deleteKey);
+  await dialog.getByRole("button", { name: "Confirm exact deletion" }).click();
+  await expect(deleteRow.getByText("deleted", { exact: true })).toBeVisible();
+
+  const deletes = fixture.requests.filter(({ method, pathname }) =>
+    method === "DELETE" && pathname === "/api/photos"
+  );
+  expect(deletes.map(({ key, search }) => ({ key, search }))).toEqual([
+    {
+      key: ADMIN_KEY,
+      search: `?event=${EVENT}&key=${encodeURIComponent(canaryKey)}`,
+    },
+    {
+      key: ADMIN_KEY,
+      search: `?event=${EVENT}&key=${encodeURIComponent(deleteKey)}`,
+    },
+  ]);
+  expect(deletes.every(({ search }) =>
+    new URLSearchParams(search).get("key")?.startsWith(`${EVENT}/`)
+  )).toBe(true);
+
+  const evidenceKinds = fixture.requests
+    .filter(({ pathname }) => pathname === "/api/rehearsals/evidence")
+    .map(({ body }) => (body as { kind: string }).kind);
+  expect(evidenceKinds).toEqual([
+    "canary-designated",
+    "canary-deleted",
+    "photo-retained",
+    "photo-deleted",
+  ]);
+});
+
+test("stale Arabic rehearsal remains keyboard-usable at 200% in forced colors", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture({
+    locale: "ar",
+    view: rehearsalView("stale"),
+  });
+  await installAdminMocks(context, fixture);
+  await page.emulateMedia({ forcedColors: "active", reducedMotion: "reduce" });
+  await unlock(page);
+  await page.evaluate(() => {
+    document.documentElement.style.zoom = "2";
+  });
+
+  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");
+  await expect(page.getByRole("heading", { name: "بروفة الجهاز الحقيقي" }))
+    .toBeVisible();
+  await expect(page.getByText("قديمة — ابدأ بروفة جديدة")).toBeVisible();
+  await expect(page.getByRole("link", {
+    name: `http://127.0.0.1:3100/${EVENT}?rehearsal=${REHEARSAL_ID}`,
+  })).toBeVisible();
+
+  const start = page.getByRole("button", { name: "بدء بروفة جديدة" });
+  await start.scrollIntoViewIfNeeded();
+  await start.focus();
+  await page.keyboard.press("Enter");
+  await expect(page.getByText("بدء بروفة ثابتة من الإعداد الحالي؟"))
+    .toBeVisible();
+  const cancel = page.getByRole("button", { name: "إلغاء" }).last();
+  await cancel.focus();
+  await page.keyboard.press("Enter");
+  await expect(page.getByText("بدء بروفة ثابتة من الإعداد الحالي؟"))
+    .toHaveCount(0);
+});

From 8b6ef00c26cad64496c01cc28a70c2dea0ea6574 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:24:18 +0800
Subject: [PATCH 104/105] test: verify destructive rehearsal recovery

---
 tests/rehearsal-operations.spec.ts | 39 +++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/tests/rehearsal-operations.spec.ts b/tests/rehearsal-operations.spec.ts
index 06e84b9..031d5d6 100644
--- a/tests/rehearsal-operations.spec.ts
+++ b/tests/rehearsal-operations.spec.ts
@@ -50,6 +50,7 @@ type RehearsalFixture = {
   view: ReturnType<typeof rehearsalView> | null;
   appliedRevisionId: string | null;
   appliedPresetId: string | null;
+  failEvidenceKindOnce: string | null;
 };
 
 function rehearsalView(
@@ -265,6 +266,11 @@ async function installAdminMocks(
         kind: string;
         photoKey?: string;
       };
+      if (fixture.failEvidenceKindOnce === evidence.kind) {
+        fixture.failEvidenceKindOnce = null;
+        await json({ error: "temporary" }, 503);
+        return;
+      }
       if (evidence.photoKey && evidence.kind === "canary-deleted") {
         updateDisposition(fixture, evidence.photoKey, "canary-deleted");
       }
@@ -304,8 +310,12 @@ async function installAdminMocks(
 async function unlock(page: Page) {
   await page.goto(`/${EVENT}/admin`);
   const input = page.getByLabel("Admin key");
-  await input.fill(ADMIN_KEY);
-  await input.press("Enter");
+  const heading = page.getByRole("heading", { name: EVENT, exact: true }).first();
+  await expect(input.or(heading)).toBeVisible();
+  if (await input.isVisible()) {
+    await input.fill(ADMIN_KEY);
+    await input.press("Enter");
+  }
   await expect(page.getByRole("heading", { name: EVENT })).toBeVisible();
 }
 
@@ -326,6 +336,7 @@ function createFixture(
     view: options.view ?? null,
     appliedRevisionId: null,
     appliedPresetId: null,
+    failEvidenceKindOnce: null,
   };
 }
 
@@ -410,10 +421,31 @@ test("guided rehearsal uses only exact tracked-photo dispositions", async ({
   const deleteKey = `${EVENT}/1753315200001-delete.jpg`;
 
   const canaryRow = page.getByRole("listitem").filter({ hasText: canaryKey });
+  fixture.failEvidenceKindOnce = "canary-deleted";
   await canaryRow.getByRole("button", {
     name: "Delete as exact canary",
   }).click();
-  await expect(canaryRow.getByText("canary-deleted", { exact: true }))
+  const canaryDialog = canaryRow.getByRole("alertdialog");
+  await expect(canaryDialog).toContainText(canaryKey);
+  await canaryDialog.getByRole("button", {
+    name: "Delete as exact canary",
+  }).click();
+  await expect(page.getByText("That rehearsal action did not finish."))
+    .toBeVisible();
+
+  // A confirmed public delete survives page reload. Retrying finalizes only
+  // the private evidence and must never issue the exact DELETE again.
+  await unlock(page);
+  const recoveredCanaryRow = page.getByRole("listitem").filter({
+    hasText: canaryKey,
+  });
+  await recoveredCanaryRow.getByRole("button", {
+    name: "Delete as exact canary",
+  }).click();
+  await recoveredCanaryRow.getByRole("alertdialog").getByRole("button", {
+    name: "Delete as exact canary",
+  }).click();
+  await expect(recoveredCanaryRow.getByText("canary-deleted", { exact: true }))
     .toBeVisible();
 
   const retainRow = page.getByRole("listitem").filter({ hasText: retainKey });
@@ -450,6 +482,7 @@ test("guided rehearsal uses only exact tracked-photo dispositions", async ({
   expect(evidenceKinds).toEqual([
     "canary-designated",
     "canary-deleted",
+    "canary-deleted",
     "photo-retained",
     "photo-deleted",
   ]);

From 39b7e512f9de9f2c69e416f0d1922ed14d8e6304 Mon Sep 17 00:00:00 2001
From: EdmundLimBoEn <limboenedmund@gmail.com>
Date: Fri, 24 Jul 2026 23:34:05 +0800
Subject: [PATCH 105/105] fix: gate and reconcile guided rehearsals

---
 app/[event]/admin/rehearsal-panel.tsx         |  27 +++++
 app/[event]/booth-session/rehearsal-client.ts |   4 +-
 app/[event]/page.tsx                          |  39 ++++++-
 tests/gallery-moderation.spec.ts              |  16 +++
 tests/guest-capture.spec.ts                   | 107 +++++++++++++++++-
 tests/post-event-package.spec.ts              |  24 ++++
 tests/rehearsal-operations.spec.ts            |  18 ++-
 7 files changed, 224 insertions(+), 11 deletions(-)

diff --git a/app/[event]/admin/rehearsal-panel.tsx b/app/[event]/admin/rehearsal-panel.tsx
index fb8ceda..312afcd 100644
--- a/app/[event]/admin/rehearsal-panel.tsx
+++ b/app/[event]/admin/rehearsal-panel.tsx
@@ -243,7 +243,34 @@ export function RehearsalPanel({
       return retained.cleanupPending;
     }
     const query = new URLSearchParams({ event, key: photoKey });
+    // Reconcile public truth before mutating. If a prior DELETE succeeded but
+    // its response or local marker was lost, the exact read returns 404 and
+    // we finalize private evidence without ever issuing DELETE again.
+    const current = await request(`/api/photo?${query}`);
+    if (current.status === 404) {
+      const alreadyAbsent = {
+        kind,
+        cleanupPending: true,
+      } satisfies ConfirmedDeletion;
+      confirmedDeleteMap().set(photoKey, alreadyAbsent);
+      persistConfirmedDeletes();
+      return alreadyAbsent.cleanupPending;
+    }
+    if (!current.ok) throw new Error(label("rehearsalActionError"));
+    const currentPhoto = await current.json() as { key?: unknown };
+    if (currentPhoto.key !== photoKey) {
+      throw new Error(label("rehearsalActionError"));
+    }
     const response = await request(`/api/photos?${query}`, { method: "DELETE" });
+    if (response.status === 404) {
+      const concurrentlyAbsent = {
+        kind,
+        cleanupPending: true,
+      } satisfies ConfirmedDeletion;
+      confirmedDeleteMap().set(photoKey, concurrentlyAbsent);
+      persistConfirmedDeletes();
+      return concurrentlyAbsent.cleanupPending;
+    }
     const result = await response.json() as {
       deleted?: unknown;
       cleanupPending?: unknown;
diff --git a/app/[event]/booth-session/rehearsal-client.ts b/app/[event]/booth-session/rehearsal-client.ts
index 5bb450c..b86dc40 100644
--- a/app/[event]/booth-session/rehearsal-client.ts
+++ b/app/[event]/booth-session/rehearsal-client.ts
@@ -47,7 +47,9 @@ export class RehearsalClient {
     previousBootId?: string | null;
   }) {
     this.outbox = options.outbox ?? createRehearsalEvidenceOutbox();
-    this.fetcher = options.fetch ?? fetch;
+    // Do not retain Window.fetch as a bare method: WebKit requires its Window
+    // receiver. The wrapper also keeps injected test fetchers unchanged.
+    this.fetcher = options.fetch ?? ((input, init) => fetch(input, init));
     this.makeId = options.makeId ?? (() => crypto.randomUUID());
     this.now = options.now ?? Date.now;
     this.bootId = this.makeId();
diff --git a/app/[event]/page.tsx b/app/[event]/page.tsx
index 0d80cff..52b5901 100644
--- a/app/[event]/page.tsx
+++ b/app/[event]/page.tsx
@@ -233,6 +233,8 @@ export default function Booth() {
     useState<WakeRequestState | "idle">("idle");
   const [durableHandoffActive, setDurableHandoffActive] = useState(false);
   const [requestedRehearsalId, setRequestedRehearsalId] = useState<string | null>(null);
+  const [rehearsalQueryReady, setRehearsalQueryReady] = useState(false);
+  const requestedRehearsalIdRef = useRef<string | null>(null);
   const [rehearsalState, setRehearsalState] =
     useState<RehearsalClientState>(INITIAL_REHEARSAL_STATE);
   // Frames remain unavailable until authenticated preflight returns the safe
@@ -254,9 +256,16 @@ export default function Booth() {
   );
 
   useEffect(() => {
-    setRequestedRehearsalId(new URL(window.location.href).searchParams.get("rehearsal"));
+    const requested = new URL(window.location.href).searchParams.get("rehearsal");
+    requestedRehearsalIdRef.current = requested;
+    setRequestedRehearsalId(requested);
+    setRehearsalQueryReady(true);
   }, [event]);
 
+  const rehearsalCaptureAllowed = useCallback(() =>
+    requestedRehearsalIdRef.current === null
+    || Boolean(rehearsalClientRef.current?.rehearsalIdForNewCapture()), []);
+
   const startCamera = useCallback(async () => {
     if (operationalRef.current.paused || unmountedRef.current) return;
     const request = ++cameraRequestRef.current;
@@ -342,10 +351,10 @@ export default function Booth() {
       clearFrame,
       stopCamera,
       startCamera: () => {
-        void startCamera();
+        if (rehearsalCaptureAllowed()) void startCamera();
       },
     }),
-    [clearFrame, startCamera, stopCamera]
+    [clearFrame, rehearsalCaptureAllowed, startCamera, stopCamera]
   );
 
   const applyOperationalState = useCallback((next: OperationalState) => {
@@ -471,7 +480,9 @@ export default function Booth() {
           reporter.start();
         }
         statePollerRef.current?.start();
-        if (!operationalRef.current.paused) void startCamera();
+        if (!operationalRef.current.paused && rehearsalCaptureAllowed()) {
+          void startCamera();
+        }
       },
       onCameraStop: () => {
         statePollerRef.current?.stop();
@@ -555,6 +566,7 @@ export default function Booth() {
   }, []);
 
   useEffect(() => {
+    if (!rehearsalQueryReady) return;
     const credential: BoothCredentialHolder = { key: "" };
     credentialRef.current = credential;
     const uploadOne = async (item: OutboxItem) => {
@@ -662,7 +674,14 @@ export default function Booth() {
       if (heartbeatReporterRef.current === reporter) heartbeatReporterRef.current = null;
       void lifecycle.leaveEvent(session);
     };
-  }, [applyOperationalState, event, lifecycle]);
+  }, [
+    applyOperationalState,
+    event,
+    lifecycle,
+    rehearsalCaptureAllowed,
+    rehearsalQueryReady,
+    startCamera,
+  ]);
 
   useEffect(() => {
     if (
@@ -703,6 +722,12 @@ export default function Booth() {
         }
         if (remaining.length === 0) await client.recordEmptyOutbox();
         await client.drainEvidence();
+        if (
+          client.rehearsalIdForNewCapture()
+          && !operationalRef.current.paused
+        ) {
+          void startCamera();
+        }
       } catch (cause) {
         if (!cancelled) {
           setError(cause instanceof Error ? cause.message : label("rehearsalJoinError"));
@@ -716,7 +741,7 @@ export default function Booth() {
       if (rehearsalClientRef.current === client) rehearsalClientRef.current = null;
       setRehearsalState(INITIAL_REHEARSAL_STATE);
     };
-  }, [accessState, event, label, requestedRehearsalId]);
+  }, [accessState, event, label, requestedRehearsalId, startCamera]);
 
   useEffect(() => {
     if (
@@ -1114,11 +1139,13 @@ export default function Booth() {
         onLeave={() => {
           rehearsalClientRef.current?.stop();
           rehearsalClientRef.current = null;
+          requestedRehearsalIdRef.current = null;
           setRequestedRehearsalId(null);
           setRehearsalState(INITIAL_REHEARSAL_STATE);
           const url = new URL(window.location.href);
           url.searchParams.delete("rehearsal");
           window.history.replaceState(null, "", url);
+          if (!operationalRef.current.paused) void startCamera();
         }}
       />
       {/* framed box is exactly the slot's aspect at the largest size that fits,
diff --git a/tests/gallery-moderation.spec.ts b/tests/gallery-moderation.spec.ts
index 4598ec1..0073966 100644
--- a/tests/gallery-moderation.spec.ts
+++ b/tests/gallery-moderation.spec.ts
@@ -238,6 +238,22 @@ async function installModerationRoutes(
       });
       return;
     }
+    if (url.pathname === "/api/presets") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ presets: [], cursor: null }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/rehearsals") {
+      await route.fulfill({
+        status: 404,
+        contentType: "application/json",
+        body: JSON.stringify({ error: "missing" }),
+      });
+      return;
+    }
     throw new Error(
       `Unexpected Admin API request: ${request.method()} ${url.pathname}`,
     );
diff --git a/tests/guest-capture.spec.ts b/tests/guest-capture.spec.ts
index 8ddbe25..49c8915 100644
--- a/tests/guest-capture.spec.ts
+++ b/tests/guest-capture.spec.ts
@@ -8,6 +8,7 @@ import {
 
 const EVENT = "guest-capture";
 const BOOTH_KEY = "guest-key";
+const REHEARSAL_ID = "018f0000-0000-4000-8000-000000000411";
 const LOCALE_KEY = `boothLocale:${EVENT}`;
 
 type HeldUpload = {
@@ -25,6 +26,9 @@ type GuestFixture = {
   photoKeys: Map<string, string>;
   externalRequests: string[];
   pageErrors: string[];
+  rehearsal: "active" | "stale" | null;
+  holdRehearsalJoin: boolean;
+  heldRehearsalJoins: Route[];
   experience: {
     frames: string[];
     locales: string[];
@@ -44,6 +48,7 @@ type GuestBrowserState = {
   failNextEncoding: boolean;
   audioStarts: number;
   bitmapCloses: number;
+  getUserMediaCalls: number;
   online: boolean;
 };
 
@@ -60,6 +65,9 @@ function createFixture(
     photoKeys: new Map(),
     externalRequests: [],
     pageErrors: [],
+    rehearsal: null,
+    holdRehearsalJoin: false,
+    heldRehearsalJoins: [],
     experience: {
       frames: ["square", "beacon"],
       locales: ["en", "zh-SG", "ar"],
@@ -109,6 +117,7 @@ async function installGuestMocks(
       failNextEncoding: false,
       audioStarts: 0,
       bitmapCloses: 0,
+      getUserMediaCalls: 0,
       online: true,
     };
     Object.defineProperty(window, "__guestCaptureTest", {
@@ -206,6 +215,7 @@ async function installGuestMocks(
     Object.defineProperty(mediaDevices, "getUserMedia", {
       configurable: true,
       value: async () => {
+        state.getUserMediaCalls += 1;
         if (camera === "denied") {
           throw new DOMException("camera denied by browser fixture", "NotAllowedError");
         }
@@ -325,6 +335,38 @@ async function installGuestMocks(
       return;
     }
 
+    if (url.pathname === "/api/rehearsals/join") {
+      if (fixture.holdRehearsalJoin) {
+        fixture.heldRehearsalJoins.push(route);
+        return;
+      }
+      const body = request.postDataJSON() as { rehearsalId?: string };
+      await route.fulfill({
+        status: fixture.rehearsal ? 200 : 404,
+        contentType: "application/json",
+        body: JSON.stringify(fixture.rehearsal ? {
+          rehearsal: {
+            version: 1,
+            id: body.rehearsalId,
+            startedAt: "2026-07-24T00:00:00.000Z",
+            configRevisionId: null,
+            frames: fixture.experience.frames,
+            stale: fixture.rehearsal === "stale",
+          },
+        } : { error: "missing" }),
+      });
+      return;
+    }
+
+    if (url.pathname === "/api/rehearsals/evidence") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ accepted: true }),
+      });
+      return;
+    }
+
     if (url.pathname === "/api/booths") {
       await route.fulfill({
         status: 200,
@@ -380,6 +422,15 @@ async function installGuestMocks(
       return;
     }
 
+    if (url.pathname === "/api/photos") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ photos: [], cursor: null }),
+      });
+      return;
+    }
+
     if (url.pathname.startsWith("/mock-photo/")) {
       await route.fulfill({
         status: 200,
@@ -570,8 +621,9 @@ test("WebKit reviews the exact one-shot and multi-shot canvas before one durable
   const directPagePromise = context.waitForEvent("page");
   await link.click();
   const directPage = await directPagePromise;
-  await expect(directPage.getByRole("heading", { name: "Your photo is ready" })).toBeVisible();
-  await expect(directPage.getByRole("img", { name: "Photo preview" })).toHaveAttribute(
+  await expect(directPage.getByRole("heading", { name: "Event photos" })).toBeVisible();
+  await expect(directPage.getByRole("dialog", { name: "Event photo" })).toBeVisible();
+  await expect(directPage.getByRole("img", { name: "Event photo" })).toHaveAttribute(
     "src",
     `/mock-photo/${firstCaptureId}.jpg`,
   );
@@ -599,6 +651,57 @@ test("WebKit reviews the exact one-shot and multi-shot canvas before one durable
   expect(fixture.pageErrors).toEqual([]);
 });
 
+test("rehearsal join gates the camera and new captures", async ({
+  context,
+  page,
+}) => {
+  const fixture = createFixture();
+  fixture.rehearsal = "active";
+  fixture.holdRehearsalJoin = true;
+  await installGuestMocks(context, fixture);
+
+  await page.goto(`/${EVENT}?rehearsal=${REHEARSAL_ID}`);
+  await page.getByLabel("Booth Key").fill(BOOTH_KEY);
+  await page.getByRole("button", { name: "Unlock Booth" }).click();
+  await expect.poll(() => fixture.heldRehearsalJoins.length).toBe(1);
+  expect((await browserState(page)).getUserMediaCalls).toBe(0);
+
+  fixture.holdRehearsalJoin = false;
+  await fixture.heldRehearsalJoins.shift()!.fulfill({
+    status: 200,
+    contentType: "application/json",
+    body: JSON.stringify({
+      rehearsal: {
+        version: 1,
+        id: REHEARSAL_ID,
+        startedAt: "2026-07-24T00:00:00.000Z",
+        configRevisionId: null,
+        frames: fixture.experience.frames,
+        stale: false,
+      },
+    }),
+  });
+
+  await expect(page.getByRole("heading", { name: "Rehearsal active" }))
+    .toBeVisible();
+  await expect.poll(async () => (await browserState(page)).getUserMediaCalls)
+    .toBe(1);
+  await expect(page.getByRole("heading", { name: "Pick a style" })).toBeVisible();
+});
+
+test("a stale rehearsal blocks new camera work", async ({ context, page }) => {
+  const fixture = createFixture();
+  fixture.rehearsal = "stale";
+  await installGuestMocks(context, fixture);
+
+  await page.goto(`/${EVENT}?rehearsal=${REHEARSAL_ID}`);
+  await page.getByLabel("Booth Key").fill(BOOTH_KEY);
+  await page.getByRole("button", { name: "Unlock Booth" }).click();
+
+  await expect(page.getByText(/Configuration changed/)).toBeVisible();
+  expect((await browserState(page)).getUserMediaCalls).toBe(0);
+});
+
 test("WebKit fences encode races and keeps the newer handoff during delayed recovery", async ({
   context,
   page,
diff --git a/tests/post-event-package.spec.ts b/tests/post-event-package.spec.ts
index 057498f..a2ade21 100644
--- a/tests/post-event-package.spec.ts
+++ b/tests/post-event-package.spec.ts
@@ -104,6 +104,30 @@ async function installAdminMocks(
       });
       return;
     }
+    if (url.pathname === "/api/presets") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ presets: [], cursor: null }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/rehearsals") {
+      await route.fulfill({
+        status: 404,
+        contentType: "application/json",
+        body: JSON.stringify({ error: "missing" }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/moderation/photos") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ photos: [], nextCursor: null }),
+      });
+      return;
+    }
     throw new Error(`Unexpected Admin API request: ${request.method()} ${url.pathname}`);
   });
 }
diff --git a/tests/rehearsal-operations.spec.ts b/tests/rehearsal-operations.spec.ts
index 031d5d6..1811bbc 100644
--- a/tests/rehearsal-operations.spec.ts
+++ b/tests/rehearsal-operations.spec.ts
@@ -51,6 +51,7 @@ type RehearsalFixture = {
   appliedRevisionId: string | null;
   appliedPresetId: string | null;
   failEvidenceKindOnce: string | null;
+  deletedPhotoKeys: Set<string>;
 };
 
 function rehearsalView(
@@ -284,6 +285,7 @@ async function installAdminMocks(
       return;
     }
     if (url.pathname === "/api/photos" && request.method() === "DELETE") {
+      fixture.deletedPhotoKeys.add(url.searchParams.get("key") ?? "");
       await json({
         deleted: true,
         key: url.searchParams.get("key"),
@@ -291,6 +293,15 @@ async function installAdminMocks(
       });
       return;
     }
+    if (url.pathname === "/api/photo" && request.method() === "GET") {
+      const key = url.searchParams.get("key") ?? "";
+      if (fixture.deletedPhotoKeys.has(key)) {
+        await json({ error: "missing" }, 404);
+      } else {
+        await json({ key, url: PIXEL, uploadedAt: "2026-07-24T00:00:00.000Z" });
+      }
+      return;
+    }
     if (url.pathname === "/api/photos" && request.method() === "GET") {
       await json({
         photos: fixture.view?.summary.trackedPhotos.map(({ photoKey }) => ({
@@ -337,6 +348,7 @@ function createFixture(
     appliedRevisionId: null,
     appliedPresetId: null,
     failEvidenceKindOnce: null,
+    deletedPhotoKeys: new Set(),
   };
 }
 
@@ -433,8 +445,9 @@ test("guided rehearsal uses only exact tracked-photo dispositions", async ({
   await expect(page.getByText("That rehearsal action did not finish."))
     .toBeVisible();
 
-  // A confirmed public delete survives page reload. Retrying finalizes only
-  // the private evidence and must never issue the exact DELETE again.
+  // Even if browser storage is cleared, exact public truth reconciles a lost
+  // confirmation after reload without issuing the DELETE again.
+  await page.evaluate(() => window.localStorage.clear());
   await unlock(page);
   const recoveredCanaryRow = page.getByRole("listitem").filter({
     hasText: canaryKey,
@@ -482,6 +495,7 @@ test("guided rehearsal uses only exact tracked-photo dispositions", async ({
   expect(evidenceKinds).toEqual([
     "canary-designated",
     "canary-deleted",
+    "canary-designated",
     "canary-deleted",
     "photo-retained",
     "photo-deleted",