Bump firmware to 1.2.0

The web UI grows into the multi-frame world: a left sidebar lists the
user's frames (with an online dot driven by the same overdue math as
the Device panel; collapsible off-canvas with a hamburger on mobile),
and each frame gets three tabs -- Photos (album picker, now displaying,
the drag-to-reorder upcoming grid), Configuration (name/order/
orientation/refresh/quiet hours/timezone/smart crop + the firmware
card), and Stats (device telemetry, lifetime counters, battery chart).
Settings and Admin adopt the same shell. / becomes a routing hub:
first frame, empty-state onboarding page, setup/login, or the
manage-QR redirect.

The JSON API moves to /api/frames/{id}/... behind require_frame_view /
require_frame_control: any linked user (admins see all) can view; 404
for frames outside your view so ids aren't confirmed; mutations 409
with the holder's name unless you hold the soft control lock, and
POST take-control always flips it to you. Config saves are now partial
updates -- each tab posts only its own fields (checkboxes always sent
explicitly), so the split forms can't clobber each other.

All CSS moves to static/theme.css and the old 680-line inline script
block splits into static/*.js -- the Pointer Events drag-drop state
machine and the canvas battery chart ported intact, not rewritten. The
CSRF fetch wrapper now reads a <meta> tag. No build step, still vanilla.

Verified end-to-end: page/static/API suites, control-lock handoff in
both directions, partial-save field preservation, non-admin frame
isolation, and the legacy-device curl suite (still byte-identical
responses for the deployed frame).

firmware/README.md

@@ -121,8 +121,14 @@ two-step setup screen:
 The config page asks for your home WiFi SSID/password, the "Tools
 Server" address (`host:port` of the [server](../server/) -- **not** your
 Immich server; see below for the `https://` form), and an optional
-"Access Token" (see below). Saving reboots the device, which then
-connects to your home network and starts its normal fetch/sleep cycle.
+"Access Token" (see below -- usually blank). Saving hands your browser
+off to the server's claim page (after ~7 seconds, giving your phone
+time to rejoin its normal WiFi while the device reboots) so the frame
+gets linked to your account; the device meanwhile connects to your home
+network and starts its normal fetch/sleep cycle. The frame identifies
+itself to the server by `?id=` (derived from its WiFi MAC) on every
+request, and the server issues it a private per-frame token on first
+contact -- no manual token handling involved.
 
 ## HTTP vs HTTPS
 
@@ -179,15 +185,16 @@ perfectly valid cert for a different name.
 
 ## Access token
 
-If the server has `MANAGEMENT_TOKEN` set (see
-[`server/README.md`](../server/README.md)), it requires that same value
-on every request -- the web UI *and* every device-facing request the
-frame itself makes. Paste it into the captive portal's "Access Token"
-field and the device sends it (`?token=...`) on every request
-automatically, and bakes it into the manage-menu/share QR codes so
-scanning them just works too. Leave it blank if the server has no
-`MANAGEMENT_TOKEN` configured -- the default, unauthenticated-on-a-
-trusted-LAN behavior from before.
+Usually blank. Current servers issue each frame its own private token
+automatically on first contact (delivered via `GET /frame/config`,
+persisted in NVS, preferred by `build_url()` from then on -- and baked
+into the manage-menu/share QR codes so scanning them just works). The
+captive portal's "Access Token" field only matters when pointing this
+firmware at an *older* (pre-multi-frame) server whose `MANAGEMENT_TOKEN`
+is set: paste that shared value and the device sends it (`?token=...`)
+until a newer server replaces it with a per-frame one. Re-provisioning
+clears any stored per-frame token -- a fresh identity handshake with
+whatever server you point it at next.
 
 ## Skipping to the next photo
 

firmware/main/Kconfig.projbuild

@@ -1,5 +1,20 @@
 menu "ESPresso Frame Configuration"
 
+    config FRAME_BOARD_NAME
+        string "Board variant name, reported to the server"
+        default "devkit"
+        help
+            Sent as the X-Frame-Board request header on every
+            GET /frame/config poll, so the server can learn which board
+            this device is and automatically fetch the right OTA build
+            from a configured Gitea repo's releases -- no manual "which
+            board" picker in the web UI. Must match one of the asset
+            names .gitea/workflows/firmware-release-build.yml publishes
+            (firmware-<name>.bin): "devkit" (this default, for the
+            plain ESP32-C6-DevKitC-1 build) or "xiao" (set via
+            sdkconfig.xiao for the Seeed XIAO ESP32-C6 build -- see
+            build_for_board.sh).
+
     config FRAME_XIAO_ANTENNA_INIT
         bool "Select onboard antenna on Seeed XIAO ESP32-C6 (RF switch init)"
         default n

firmware/main/frame_client.c

@@ -99,11 +99,14 @@ static void save_wifi_cache(esp_netif_t *netif)
  * normally a bare "host:port", defaulting to plain http; it may instead
  * carry an explicit "http://" or "https://" prefix to pick the scheme,
  * e.g. "https://frame.example.com" if a reverse proxy is terminating
- * TLS in front of the tools server. The token, once the server has
- * MANAGEMENT_TOKEN set, is required on every request the server
- * receives (device-facing endpoints included, not just the web UI) --
- * this is the one chokepoint all of them go through, so every caller
- * gets it for free instead of needing to remember to add it. */
+ * TLS in front of the tools server. Every URL carries ?id= (the device's
+ * MAC-derived identity -- how a multi-frame server tells frames apart
+ * and how an unknown frame self-registers) plus &token=: the server-
+ * issued per-frame device token once one has been delivered via
+ * /frame/config, else the provisioned access token (the legacy shared
+ * secret, also what a pre-multi-frame server still expects). This is
+ * the one chokepoint all requests go through, so every caller gets both
+ * for free instead of needing to remember to add them. */
 static void build_url(char *out, size_t out_size, const frame_config_t *cfg, const char *path)
 {
     const char *toolsserver = cfg->toolsserver;
@@ -113,8 +116,16 @@ static void build_url(char *out, size_t out_size, const frame_config_t *cfg, con
     } else {
         len = (size_t)snprintf(out, out_size, "http://%s/%s", toolsserver, path);
     }
-    if (cfg->access_token[0] != '\0' && len < out_size) {
-        snprintf(out + len, out_size - len, "?token=%s", cfg->access_token);
+
+    char device_id[FRAME_DEVICE_ID_LEN + 1];
+    frame_device_id_get(device_id, sizeof(device_id));
+    if (len < out_size) {
+        len += (size_t)snprintf(out + len, out_size - len, "?id=%s", device_id);
+    }
+
+    const char *token = cfg->device_token[0] != '\0' ? cfg->device_token : cfg->access_token;
+    if (token[0] != '\0' && len < out_size) {
+        snprintf(out + len, out_size - len, "&token=%s", token);
     }
 }
 
@@ -266,6 +277,11 @@ typedef struct {
     bool reachable;
     uint32_t refresh_interval_s; /* CONFIG_FRAME_SLEEP_INTERVAL_S if absent/unparseable */
     char firmware_version[32];   /* server's uploaded OTA image version; empty if none/unreachable */
+    /* Per-frame token the server pushes until this device has
+     * authenticated with it once; empty when absent. Persisted via
+     * frame_config_set_device_token() and used by build_url() from the
+     * next request on. */
+    char device_token[FRAME_CFG_TOKEN_MAX_LEN + 1];
 } frame_server_config_t;
 
 /* Finds the first integer value associated with "key" in a small JSON
@@ -342,9 +358,13 @@ static bool json_extract_string(const char *json, const char *key, char *out, si
 /* GETs the server's /frame/config -- doubles as both the reachability
  * check (any completed HTTP response means the socket-level connection
  * succeeded), the source of the server-configurable refresh interval,
- * and (via the X-Frame-Version request header / firmware_version
- * response field) the device's OTA update check -- piggybacked on a
- * request already made every wake, no extra round trip. */
+ * and (via the X-Frame-Version/X-Frame-Board request headers and
+ * firmware_version response field) the device's OTA update check --
+ * piggybacked on a request already made every wake, no extra round
+ * trip. X-Frame-Board lets the server learn which board this device is
+ * (CONFIG_FRAME_BOARD_NAME) so it can pick the right Gitea release
+ * asset itself, instead of a user manually selecting a board in the
+ * web UI. */
 static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
 {
     frame_server_config_t result = {
@@ -352,6 +372,7 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
         .refresh_interval_s = CONFIG_FRAME_SLEEP_INTERVAL_S,
     };
     result.firmware_version[0] = '\0';
+    result.device_token[0] = '\0';
 
     char url[256];
     build_url(url, sizeof(url), cfg, "frame/config");
@@ -364,6 +385,7 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
     };
     esp_http_client_handle_t client = esp_http_client_init(&config);
     esp_http_client_set_header(client, "X-Frame-Version", esp_app_get_description()->version);
+    esp_http_client_set_header(client, "X-Frame-Board", CONFIG_FRAME_BOARD_NAME);
 
     esp_err_t err = esp_http_client_open(client, 0);
     if (err != ESP_OK) {
@@ -375,7 +397,10 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
     esp_http_client_fetch_headers(client);
     result.reachable = true;
 
-    char body[256];
+    /* 512 (was 256): the response also carries "device_token" during the
+     * one-time identity handshake -- worst case is still well under half
+     * of this, the rest is headroom for future fields. */
+    char body[512];
     int total = 0;
     int n;
     while (total < (int)sizeof(body) - 1 &&
@@ -395,6 +420,7 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
                  (int)result.refresh_interval_s);
     }
     json_extract_string(body, "firmware_version", result.firmware_version, sizeof(result.firmware_version));
+    json_extract_string(body, "device_token", result.device_token, sizeof(result.device_token));
 
     return result;
 }
@@ -947,6 +973,20 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
         frame_server_config_t server_cfg = fetch_frame_config(cfg);
         sleep_seconds = server_cfg.reachable ? server_cfg.refresh_interval_s : CONFIG_FRAME_RETRY_INTERVAL_S;
 
+        /* One-time identity handshake: the server pushes this frame's
+         * own token until we've authenticated with it once. Persist it
+         * and use it immediately (the OTA below is part of this same
+         * cycle) via a local working copy -- cfg itself is const. */
+        frame_config_t updated_cfg;
+        if (server_cfg.device_token[0] != '\0' &&
+            strcmp(server_cfg.device_token, cfg->device_token) != 0) {
+            frame_config_set_device_token(server_cfg.device_token);
+            updated_cfg = *cfg;
+            snprintf(updated_cfg.device_token, sizeof(updated_cfg.device_token), "%s",
+                     server_cfg.device_token);
+            cfg = &updated_cfg;
+        }
+
         /* Last, deliberately -- the photo's already on screen and the
          * battery report already sent, so a reboot here (whether OTA
          * succeeds or the device is mid-update) never loses either. */

firmware/main/ota_update.c

@@ -17,7 +17,7 @@ static const char *TAG = "ota_update";
 #define OTA_HTTP_TIMEOUT_MS 30000
 
 /* Built the same way as every other tools-server URL -- scheme/cert/
- * token handling all come from build_url()'s conventions. Duplicated
+ * id/token handling all come from build_url()'s conventions. Duplicated
  * tiny helper rather than exporting frame_client.c's static build_url();
  * kept byte-identical in behavior (see frame_client.c). */
 static void build_ota_url(char *out, size_t out_size, const frame_config_t *cfg)
@@ -29,8 +29,16 @@ static void build_ota_url(char *out, size_t out_size, const frame_config_t *cfg)
     } else {
         len = (size_t)snprintf(out, out_size, "http://%s/frame/firmware", toolsserver);
     }
-    if (cfg->access_token[0] != '\0' && len < out_size) {
-        snprintf(out + len, out_size - len, "?token=%s", cfg->access_token);
+
+    char device_id[FRAME_DEVICE_ID_LEN + 1];
+    frame_device_id_get(device_id, sizeof(device_id));
+    if (len < out_size) {
+        len += (size_t)snprintf(out + len, out_size - len, "?id=%s", device_id);
+    }
+
+    const char *token = cfg->device_token[0] != '\0' ? cfg->device_token : cfg->access_token;
+    if (token[0] != '\0' && len < out_size) {
+        snprintf(out + len, out_size - len, "&token=%s", token);
     }
 }
 

firmware/main/root.html

@@ -98,10 +98,14 @@
             </div>
 
             <div class="input-group">
-                <label for="access_token">Access Token (optional)</label>
-                <input type="text" id="access_token" name="access_token" placeholder="only if the server's MANAGEMENT_TOKEN is set" maxlength="64">
+                <label for="access_token">Access Token (optional &mdash; only for older servers)</label>
+                <input type="text" id="access_token" name="access_token" placeholder="usually blank; current servers issue one automatically" maxlength="64">
             </div>
 
+            <p style="font-size: 13px; color: #555;">After saving, this page will
+                take you to the server to claim your frame &mdash; reconnect to
+                your normal WiFi if it doesn't happen automatically.</p>
+
             <button type="submit">Submit</button>
 
         </form>

firmware/main/wifi_provisioning.c

@@ -83,10 +83,39 @@ esp_err_t frame_config_load(frame_config_t *out)
         return token_err;
     }
 
+    /* Optional: absent until the server has pushed a per-frame token
+     * (see frame_config_set_device_token). */
+    len = sizeof(out->device_token);
+    token_err = nvs_get_str(handle, "device_token", out->device_token, &len);
+    if (token_err != ESP_OK && token_err != ESP_ERR_NVS_NOT_FOUND) {
+        nvs_close(handle);
+        return token_err;
+    }
+
     nvs_close(handle);
     return ESP_OK;
 }
 
+void frame_device_id_get(char *out, size_t out_size)
+{
+    uint8_t mac[6] = {0};
+    ESP_ERROR_CHECK(esp_read_mac(mac, ESP_MAC_WIFI_STA));
+    snprintf(out, out_size, "%02x%02x%02x%02x%02x%02x",
+             mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
+}
+
+void frame_config_set_device_token(const char *token)
+{
+    nvs_handle_t handle;
+    if (nvs_open(NVS_NAMESPACE, NVS_READWRITE, &handle) != ESP_OK) {
+        return;
+    }
+    nvs_set_str(handle, "device_token", token);
+    nvs_commit(handle);
+    nvs_close(handle);
+    ESP_LOGI(TAG, "Stored server-issued device token");
+}
+
 esp_err_t frame_config_save(const frame_config_t *cfg)
 {
     nvs_handle_t handle;
@@ -106,6 +135,10 @@ esp_err_t frame_config_save(const frame_config_t *cfg)
         err = nvs_set_str(handle, "access_token", cfg->access_token);
     }
     if (err == ESP_OK) {
+        /* Re-provisioning restarts the identity handshake: the server
+         * (possibly a different one now) re-issues a device token when
+         * the frame next introduces itself. */
+        nvs_erase_key(handle, "device_token");
         /* Fresh (re)provisioning -- the next successful connection should
          * show the status screen again. */
         err = nvs_set_u8(handle, "connected_once", 0);
@@ -159,6 +192,7 @@ void frame_config_clear(void)
     nvs_erase_key(handle, "sta_pass");
     nvs_erase_key(handle, "toolsserver");
     nvs_erase_key(handle, "access_token");
+    nvs_erase_key(handle, "device_token");
     nvs_erase_key(handle, "connected_once");
     nvs_commit(handle);
     nvs_close(handle);
@@ -412,8 +446,35 @@ static esp_err_t save_config_post_handler(httpd_req_t *req)
     ESP_LOGI(TAG, "Saved config: ssid='%s' toolsserver='%s' access_token=%s", cfg.sta_ssid, cfg.toolsserver,
              strlen(cfg.access_token) ? "set" : "none");
 
-    static const char resp[] =
-        "<html><body><h3>Saved. Restarting and connecting to your WiFi...</h3></body></html>";
+    /* The success page hands the browser off to the server's claim page,
+     * carrying this device's id -- how a frame gets linked to a user
+     * account. The ~7s delay covers the phone dropping this softAP (the
+     * device reboots right after this response) and rejoining its normal
+     * WiFi before the redirect fires; the visible link is the fallback
+     * if the phone loses that race. Scheme handling matches
+     * frame_client.c's build_url(): a bare host gets http://. */
+    char device_id[FRAME_DEVICE_ID_LEN + 1];
+    frame_device_id_get(device_id, sizeof(device_id));
+
+    char claim_url[FRAME_CFG_SERVER_MAX_LEN + 64];
+    const char *scheme = "";
+    if (strncmp(cfg.toolsserver, "http://", 7) != 0 && strncmp(cfg.toolsserver, "https://", 8) != 0) {
+        scheme = "http://";
+    }
+    snprintf(claim_url, sizeof(claim_url), "%s%s/claim?device_id=%s", scheme, cfg.toolsserver, device_id);
+
+    char resp[1024];
+    snprintf(resp, sizeof(resp),
+             "<!doctype html><html><head>"
+             "<meta http-equiv=\"refresh\" content=\"7;url=%s\">"
+             "<style>body{font-family:sans-serif;text-align:center;padding:2em}</style></head>"
+             "<body><h3>Saved &mdash; the frame is restarting</h3>"
+             "<p>Reconnect to your normal WiFi. You'll be taken to the claim page "
+             "in a few seconds&hellip;</p>"
+             "<p><a href=\"%s\">Continue to claim your frame</a></p>"
+             "<script>setTimeout(function(){location.href=%c%s%c},7000)</script>"
+             "</body></html>",
+             claim_url, claim_url, '"', claim_url, '"');
     httpd_resp_set_type(req, "text/html");
     httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
 

firmware/main/wifi_provisioning.h

@@ -11,13 +11,37 @@
 #define FRAME_CFG_TOKEN_MAX_LEN 64
 #define FRAME_AP_PASSWORD_LEN 10
 
+#define FRAME_DEVICE_ID_LEN 12 /* 6-byte STA MAC as lowercase hex */
+
 typedef struct {
     char sta_ssid[FRAME_CFG_SSID_MAX_LEN + 1];
     char sta_password[FRAME_CFG_PASSWORD_MAX_LEN + 1];
     char toolsserver[FRAME_CFG_SERVER_MAX_LEN + 1];
-    char access_token[FRAME_CFG_TOKEN_MAX_LEN + 1]; /* optional; matches the server's MANAGEMENT_TOKEN */
+    char access_token[FRAME_CFG_TOKEN_MAX_LEN + 1]; /* optional; legacy shared MANAGEMENT_TOKEN */
+    /* Per-frame token issued by the server via GET /frame/config after
+     * this device first introduces itself by id -- preferred over
+     * access_token once present (see frame_client.c's build_url). Not
+     * set at the captive portal; empty until the server pushes one. */
+    char device_token[FRAME_CFG_TOKEN_MAX_LEN + 1];
 } frame_config_t;
 
+/**
+ * This device's stable identity as reported to the server (?id= on every
+ * request): the full 6-byte STA MAC as 12 lowercase hex chars. Derived
+ * from the same MAC the provisioning AP SSID suffix comes from; never
+ * stored. out must hold at least FRAME_DEVICE_ID_LEN + 1 bytes.
+ */
+void frame_device_id_get(char *out, size_t out_size);
+
+/**
+ * Persists (only) the server-issued per-frame device token -- called
+ * from the wake cycle when GET /frame/config delivers one. Deliberately
+ * touches nothing else: unlike frame_config_save() it must not reset
+ * the connected-once flag or invalidate the WiFi fast-connect cache,
+ * since nothing about the network changed.
+ */
+void frame_config_set_device_token(const char *token);
+
 /**
  * Loads the saved home-network config from NVS.
  * Returns ESP_ERR_NVS_NOT_FOUND if the device has never been provisioned.

firmware/sdkconfig.xiao

@@ -8,6 +8,8 @@ CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
 CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_xiao.csv"
 CONFIG_PARTITION_TABLE_FILENAME="partitions_xiao.csv"
 
+CONFIG_FRAME_BOARD_NAME="xiao"
+
 # Powers the XIAO's RF switch and selects its onboard antenna -- without
 # this the softAP/STA radio doesn't reliably reach the antenna at all.
 # See the Kconfig help text (FRAME_XIAO_ANTENNA_INIT) for why.

firmware/version.txt

@@ -1 +1 @@
-1.1.1
+1.2.0

server/README.md

@@ -8,214 +8,161 @@ algorithm itself -- it just streams the response straight to the panel.
 
 ## Setup
 
-1. **Get an Immich API key**: in Immich, go to Account Settings -> API Keys
-   -> New API Key. Needs read access to albums/assets/faces, plus
-   `sharedLink.create` (for the manage overlay's "scan to download" QR,
-   which creates a temporary public share link) -- a plain read-only key
-   will 403 on that one specific feature while everything else works.
-2. **Copy the compose file and fill in your Immich details**:
+1. **Copy the compose file and run the server**:
    ```
    cp docker-compose.yml.example docker-compose.yml
-   ```
-   Edit `docker-compose.yml` and set `IMMICH_URL`/`IMMICH_API_KEY` under
-   `environment:`. `docker-compose.yml` is gitignored (it'll hold your real
-   API key) -- `docker-compose.yml.example` is the one that's committed.
-3. **Run the server**:
-   ```
    docker compose up -d
    ```
-4. Open `http://<this-machine>:8420/` in a browser, click **Load Albums**,
-   pick one, and **Save**. (The Immich URL/API key fields will already be
-   populated from the environment; changing them in the UI has no effect
-   as long as the env vars are set -- they win on every load.)
-5. On the ESP32's captive portal setup form, set the **Tools Server** field
-   to `<this-machine>:8420`. This server always speaks plain HTTP itself --
-   for HTTPS, put a TLS-terminating reverse proxy (e.g. nginx) in front of
-   it and enter the proxy's `https://` address instead (see
-   `firmware/README.md`'s HTTPS section for what the ESP32 side needs).
-6. **Optional: set `MANAGEMENT_TOKEN`** in `docker-compose.yml` to gate
-   the *entire server* -- the web UI (`/`, `/api/*`) and every
-   device-facing `/frame/*` endpoint -- behind a shared secret (leave
-   unset to keep it all open, the previous default -- fine on a trusted
-   LAN). If set, paste the same value into the ESP32's captive portal
-   setup form's **Access Token** field: the device then sends it on
-   every request it makes, and the manage-menu/share QR codes embed it
-   automatically (`?token=...`) so scanning them just works. Visiting
-   the web UI without a valid token in the URL shows a plain token-entry
-   prompt instead of the config UI; `/health` stays open regardless
-   (pure liveness, nothing sensitive in it).
-7. **Optional: auto-update firmware from Gitea releases.** If you're
+2. **First-run setup**: open `http://<this-machine>:8420/` -- you'll be
+   walked through creating the admin account. Every user has their own
+   login; the admin can enroll more from the Admin page (family members
+   can also self-enroll through the frame-claim flow, below).
+3. **Connect your Immich library** (per user, in Settings): your Immich
+   URL and an API key. The key needs read access to
+   albums/assets/faces, plus `sharedLink.create` (for the on-frame
+   "scan to download" QR, which creates a temporary public share link)
+   -- a plain read-only key will 403 on that one feature while
+   everything else works. Frames you own pull from *your* library.
+   (`IMMICH_URL`/`IMMICH_API_KEY` env vars in `docker-compose.yml` still
+   work as an operator-level fallback and seed the first admin's
+   settings when migrating an older deployment.)
+4. **Provision a frame**: power it on, join its `ESPRESSO_XXXXXX` WiFi
+   (instructions show on the panel), fill in your WiFi details and this
+   server's address (**Tools Server**, e.g. `<this-machine>:8420`).
+   After saving, your browser is redirected to this server's claim page
+   and the frame links to your account -- creating an account on the
+   spot if you don't have one (a valid frame is the invitation). The
+   server speaks plain HTTP itself -- for HTTPS, put a TLS-terminating
+   reverse proxy in front and enter the proxy's `https://` address
+   instead (see `firmware/README.md`'s HTTPS section).
+5. **Each frame gets its own device token automatically** -- the server
+   issues it on the frame's first check-in, so there's nothing to
+   configure. The captive portal's **Access Token** field only matters
+   when pointing new firmware at an old (pre-multi-frame) server.
+   `MANAGEMENT_TOKEN` in `docker-compose.yml` is likewise now only the
+   *migration* credential: a frame flashed with pre-multi-frame
+   firmware authenticates with it until it's updated and bound (the
+   Admin page shows the migration state per frame and a "Close legacy
+   window" button for when it's done).
+6. **Optional: auto-update firmware from Gitea releases.** If you're
    pushing this repo to a Gitea instance, `.gitea/workflows/firmware-release-build.yml`
    builds both supported boards and publishes them as release assets
    (`firmware-xiao.bin`/`firmware-devkit.bin`) whenever `firmware/version.txt`
-   changes on `main`. In the web UI's Settings form, set **Firmware Gitea
-   repo URL** to that repo (e.g. `https://git.example.com/owner/repo`) and
-   pick the frame's **board**; if the repo is private, also set
-   `GITEA_FIRMWARE_TOKEN` (a read-only PAT) in `docker-compose.yml`. The
-   server then periodically checks for a newer release and either shows
-   an "Update frame" button or, with **Automatically apply updates**
-   checked, stages it itself -- either way the frame only actually
-   updates on its own next wake (see `POST /api/firmware` above).
+   changes on `main`. In a frame's **Configuration** tab, set the
+   **Gitea repo URL**; if the repo is private, also set
+   `GITEA_FIRMWARE_TOKEN` (a read-only PAT) in `docker-compose.yml`.
+   Which board's build to fetch is learned from the frame itself (its
+   `X-Frame-Board` header) -- nothing to pick by hand. The server then
+   periodically checks for a newer release and either shows an "Update
+   frame" button or, with **Automatically apply updates** checked,
+   stages it itself -- either way the frame only actually updates on
+   its own next wake.
+
+## Users, frames, and control
+
+- **Users** log in with a session cookie; passwords are scrypt-hashed;
+  mutating requests are CSRF-protected. Sign-up paths: first-run setup
+  (admin #1), admin enrollment (Admin page), or the claim flow (a valid
+  unclaimed frame's `device_id` gates self-service signup).
+- **Frames** identify themselves by `?id=` (MAC-derived) on every
+  request and authenticate with a per-frame device token the server
+  issues at first check-in. Unknown frames self-register as unclaimed;
+  claiming (via `/claim?device_id=...`) sets the owner -- whose Immich
+  library the frame renders from -- and links the account. Admins can
+  link additional users to any frame; every linked user sees it in
+  their sidebar.
+- **Control** is a soft lock per frame: everyone linked can *view*;
+  changing settings/queue requires holding control, and "Take control"
+  always succeeds (the 409 error names the current holder). The
+  physical buttons on the frame ignore all of this.
+- **The on-frame manage QR** opens a limited no-login page (`/m/<token>`):
+  view current + upcoming, "show next", advance, back -- nothing else.
+  The share QR stays public (it creates a 30-minute Immich share link
+  for exactly the photo shown).
 
 ## Endpoints
 
-- `GET /` -- config UI (album, order, refresh interval, face-aware crop
-  toggle, upcoming-photos count, now-displaying + drag-to-reorder
-  upcoming grid -- not Immich URL/API key, see Setup above)
-- `GET /api/albums` -- lists Immich albums (used by the config UI)
-- `POST /api/config` -- saves
-  album/order/orientation/refresh_interval_s/smart_crop_faces/queue_target_len/quiet_hours_*/timezone.
-  `orientation` (`landscape`, `portrait`, `landscape_flipped`,
-  `portrait_flipped`) matches how the frame is physically hung: photos
-  are composed/cropped for that shape (portrait crops at 480x800), then
-  rotated into the panel's native 800x480 byte layout server-side --
-  the device never knows. Note the device-side manage-menu overlay
-  (QRs, text, battery indicator, face labels) still renders in native
-  panel orientation, so on a portrait-hung frame it appears rotated
-  90° to the viewer -- QR codes scan fine at any rotation, but the text
-  reads sideways. A known limitation, not planned to change soon.
-  `quiet_hours_enabled`/`quiet_hours_start`/`quiet_hours_end`
-  (`"HH:MM"`, may wrap past midnight, e.g. `22:00`-`07:00`) don't touch
-  the device at all -- purely a server decision about what
-  `refresh_interval_s` to hand back from `GET /frame/config` below,
-  computed in `_effective_refresh_interval_s`. Interpreted in the
-  `timezone` set from the web UI's "Timezone" dropdown (an IANA zone
-  name, e.g. `America/New_York`; defaults to `UTC`) -- no
-  docker-compose.yml edit or container restart needed to change it. The
-  device can still land one wake right
-  at the start of the window (nothing server-side can prevent that
-  without touching the firmware, since the device doesn't know wall-clock
-  time), but from that wake on it's told to sleep exactly until the
-  window ends. The "overdue" indicator in `/api/queue`'s `device` object
-  also accounts for this -- it won't falsely flag a device that's
-  legitimately sleeping through a long quiet-hours window
-- `GET /frame/image` -- returns the current photo pre-processed into the
-  panel's raw 800x480, 4-bit-per-pixel, 2-pixels-per-byte format
+Pages: `/` (routing hub), `/setup`, `/login`, `/claim`, `/settings`,
+`/admin`, `/frames/{id}` (Photos), `/frames/{id}/config`,
+`/frames/{id}/stats`, `/m/{manage_token}`.
+
+### Device protocol (`/frame/*` -- paths frozen; auth = `?id=` + `?token=`)
+
+- `GET /frame/image` -- the frame's current image, pre-processed into
+  the panel's raw 800x480, 4-bit-per-pixel, 2-pixels-per-byte format
   (`application/octet-stream`, exactly 192,000 bytes). **Side-effect-free**
-  by default: it only actually advances to the next photo once
-  `refresh_interval_s` has elapsed since the current one was set, so
-  calling it repeatedly (e.g. the device rebooting unexpectedly) just
-  redisplays the same photo instead of skipping ahead.
-- `POST /frame/advance` -- forces an immediate advance to the next photo,
-  ignoring `refresh_interval_s`, and resets the interval clock from now.
-  Same response shape as `/frame/image`. Used by the device's next-photo
-  button (see `firmware/README.md`). Every photo actually displayed this
-  way (or via the normal timer-based advance) is pushed onto a bounded
-  history (`app/photo_queue.py`, last 20) that `/frame/back` below can
-  return to.
-- `POST /frame/back` -- returns to the previously-current photo (the
-  exact mirror of `/frame/advance`), and resets the interval clock from
-  now. A no-op (still 200, same photo) if there's no history yet.
-  Pressing advance afterwards returns to where you were before going
-  back -- it displaces the current photo onto the front of the upcoming
-  queue rather than discarding it. Same response shape as
-  `/frame/image`. Used by the device's back-photo button.
-- `GET /frame/config` -- `{"refresh_interval_s": ..., "firmware_version": "1.2.3" | null}`,
-  polled by the frame each wake alongside its reachability check.
-  `firmware_version` is whatever's currently uploaded via
-  `POST /api/firmware` below (`null` if nothing's been uploaded) -- the
-  device compares it against its own running version
-  (`esp_app_get_description()->version`, sent as an `X-Frame-Version`
-  request header, stored as `device_firmware_version`) to decide whether
-  to OTA
-- `GET /frame/photo-info` -- `{"asset_id": ..., "location_line1": ... |
-  null, "location_line2": ... | null, "taken_at": ... | null}` for the
-  current photo (same idempotent current-photo semantics as
-  `/frame/image`). `location_line1`/`location_line2` are `city` /
-  `state-or-country` if Immich reverse-geocoded the photo's GPS EXIF
-  (both `null` if not) -- for US/Canada, the region line is the
-  abbreviated state/province (`"CA"`, `"ON"`); elsewhere it's the full
-  country name. `taken_at` is `MM/DD/YY` from the photo's EXIF capture
-  date, else `null`. Used by the device's manage button to build its
-  overlay text
-- `GET /frame/share/{asset_id}` -- creates a 30-minute public, view-only
-  Immich share link for `asset_id` and redirects (302) to it. Only works
-  for the photo currently showing or in the upcoming queue on this frame
-  -- not any arbitrary Immich asset. The link is created on first hit
-  (i.e. when someone actually scans the manage overlay's share QR), not
-  when the button's pressed, so the 30-minute window starts when it's
-  actually used
-- `GET /frame/face-labels` -- `{"count": N, "name_0": ..., "x_0": ...,
-  "y_0": ..., ...}` (up to 4 slots) -- named people from Immich's face
-  recognition, positioned in final 800x480 frame pixel space. Only faces
-  Immich already has an identified name for are included (no face
-  detection/recognition happens in this project, see
-  `app/face_labels.py`); `count: 0` if none are named. Used by the
-  device manage button's escalated second menu level
-- `POST /frame/battery` -- `{"percent": 0-100}`; the device's last
-  battery reading, stored with a timestamp plus two histories: a
-  per-discharge-cycle one (reset whenever a report jumps up enough to
-  look like a recharge) feeding the "on battery for"/estimate numbers,
-  and a permanent, never-reset log (capped at `BATTERY_LOG_MAX`, ~2
-  years at hourly reports) feeding the web UI's battery graph. Only sent
-  when the device is actually running on battery (see
-  `firmware/README.md`'s Battery section) -- a frame on mains power
-  never reports
-- `GET /api/battery-log` -- `{"log": [[timestamp, percent], ...]}`, the
-  full permanent battery history above; used by the web UI's "Battery
-  history" chart
-- `GET /api/stats` -- lifetime, never-reset counters: `first_seen`,
-  `device_wakes`, `photos_displayed`, `photos_removed`,
-  `battery_reports`, `recharge_cycles`, `ota_updates_applied`,
-  `config_saves` (see `FrameStats` in `app/config.py`). Purely
-  informational -- nothing else reads these back -- shown in a
-  collapsed "Stats" section in the web UI
-- `POST /api/firmware` -- multipart upload (`file`) of a built
-  `espresso_frame.bin`. Parses the embedded `esp_app_desc_t` (rejects
-  anything that isn't a valid image for this project) and stores it as
-  the available firmware; devices pick it up via `GET /frame/config`
-  above on their next wake
-- `GET /frame/firmware` -- streams back whatever was last uploaded via
-  `POST /api/firmware`, for the device's OTA fetch. 404 if nothing's
-  been uploaded yet
-- `GET /api/firmware/check` -- throttled (`gitea_releases.UPDATE_CHECK_INTERVAL_S`,
-  15 min) check of the configured Gitea repo's latest release for the
-  frame's board variant. `{"enabled": false}` if no repo URL is
-  configured; otherwise `{"enabled": true, "latest_version": "1.2.3" | null,
-  "staged_version": "1.2.2" | null, "update_available": bool}`. If
-  "Automatically apply updates" is on and a newer release is found, this
-  call also stages it immediately (same effect as a manual upload) --
-  otherwise the web UI shows an "Update frame" button
-- `POST /api/firmware/apply-latest` -- the "Update frame" button: pulls
-  and stages the latest Gitea release right now, bypassing the check
-  throttle. 404 if no repo is configured, has no releases, or the latest
-  release has no asset for the configured board variant
-- `GET /api/queue` -- `{"current": {...} | null, "upcoming": [...],
-  "device": {"last_seen": ts | null, "overdue": bool,
-  "firmware_version": "1.2.3" | null, "firmware_available": "1.2.4" | null,
-  "battery": {"percent": N, "as_of": ts} | null, "on_battery_since": ts | null,
-  "battery_estimate_s": N | null}}`, each queue entry an asset id +
-  thumbnail URL; used by the config UI's "Device" panel
-- `POST /api/queue/reorder` -- reorders the upcoming queue; body is
-  `{"queue": [asset_id, ...]}`. Tolerant of drift from the queue having
-  changed server-side since the client's last fetch (e.g. a top-up/trim)
-  -- unrecognized IDs in the body are dropped, and any currently-queued
-  photo missing from the body is appended rather than lost, instead of
-  rejecting the whole request
-- `POST /api/queue/promote` -- moves one photo to the front of the queue;
-  body is `{"asset_id": "..."}`. Used by "Show next" in the web UI --
-  unlike `/reorder`, doesn't depend on the client knowing the queue's
-  full current order, so it can't fail from staleness
-- `POST /api/queue/remove` -- permanently excludes a photo from this
-  frame's rotation; body is `{"asset_id": "..."}`. Doesn't touch Immich
-  or the album -- the photo just stops being selected by this frame
-  again (`app/photo_queue.py`'s `excluded_asset_ids`/`remove_from_rotation()`).
-  Works on the current photo too, in which case it immediately advances
-  to a different one (without recording the removed photo in history --
-  going back to a photo you just removed wouldn't make sense). Used by
-  the "×" button in the web UI on both the current-photo thumbnail and
-  each upcoming card
-- `GET /api/photo-thumbnail/{asset_id}` -- proxies an Immich thumbnail so
-  the browser never needs the Immich API key directly
-- `GET /health` -- liveness check
+  by default: it only actually advances once `refresh_interval_s` has
+  elapsed since the current photo was set, so an unexpected reboot just
+  redisplays the same photo. An unclaimed or not-yet-configured frame
+  gets a rendered instruction placeholder (with a claim QR) instead of
+  an error, so a fresh device never error-loops.
+- `POST /frame/advance` / `POST /frame/back` -- the next/back photo
+  buttons: force an immediate move (mirror images of each other; back
+  pops a bounded 20-entry history and pushes the displaced photo onto
+  the front of the queue). Same response shape as `/frame/image`.
+- `GET /frame/config` -- `{"refresh_interval_s": ..., "firmware_version":
+  ... | null, "device_token": ...?}`, polled each wake. Captures the
+  `X-Frame-Version`/`X-Frame-Board` headers (running firmware + board
+  variant). `device_token` appears only during the one-time identity
+  handshake -- until the device authenticates with its issued token
+  once -- and the flat firmware parser's 512-byte buffer bounds how big
+  this response may grow.
+- `GET /frame/photo-info` -- location/date overlay text for the manage
+  menu (city + abbreviated US/CAN region or country, `MM/DD/YY`).
+- `GET /frame/share/{asset_id}` -- creates a 30-minute public Immich
+  share link and 302s to it; scoped to the photo currently showing or
+  queued on *this* frame only.
+- `GET /frame/face-labels` -- up to 4 named faces with 800x480
+  positions, flattened (`name_0`/`x_0`/`y_0`, ...) for the device's
+  flat-scalar parser.
+- `POST /frame/battery` -- `{"percent": 0-100}`; per-discharge-cycle
+  history (feeds the runtime estimate) plus a permanent per-frame
+  battery log (the Stats chart). Only sent on battery power.
+- `GET /frame/firmware` -- streams the frame's staged OTA image.
+
+### Web API (`/api/frames/{id}/...` -- session auth; *view* for reads, *control* for writes)
+
+- `GET  .../queue` -- current + upcoming (each entry id + thumbnail
+  URL), the control state (`{"controller": name, "you": bool}`), and
+  the device telemetry block (`last_seen`, `overdue` -- quiet-hours
+  aware -- firmware versions, battery + runtime estimate).
+- `POST .../queue/reorder|promote|remove` -- reorder is drift-tolerant
+  (stale ids dropped, missing ids appended); promote is "Show next";
+  remove permanently excludes from this frame's rotation (never touches
+  Immich) and advances if it was current.
+- `GET  .../albums` -- the owner's Immich albums.
+- `POST .../config` -- **partial** update: only provided fields change
+  (`name`, `album_id` -- resets queue/history on change --, `order`,
+  `refresh_interval_s`, `smart_crop_faces`, `queue_target_len`,
+  `orientation` (composed logically then rotated server-side; the
+  on-device manage overlay still renders native, a known limitation),
+  `quiet_hours_*` + `timezone` (a pure server-side decision shaping
+  what `refresh_interval_s` gets handed to the device),
+  `firmware_update_repo_url`, `firmware_auto_update`).
+- `POST .../take-control` -- always succeeds for a linked user.
+- `GET  .../stats`, `GET .../battery-log`, `GET .../thumbnail/{asset_id}`.
+- `POST .../firmware` (manual .bin upload, esp_app_desc_t-validated),
+  `GET .../firmware/check` (throttled 15 min; `?force=true` bypasses),
+  `POST .../firmware/apply-latest`.
+
+### Manage-QR API (`/api/m/{manage_token}/...` -- token in path, no login)
+
+- `GET queue`, `POST promote`, `POST advance`, `POST back`,
+  `GET thumbnail/{asset_id}` (scoped to this frame's current/queued
+  photos). Nothing else.
+
+- `GET /health` -- liveness check, always open.
 
 ## Notes
 
-- Album/order/refresh-interval/current photo/upcoming queue/etc. are
-  stored in `./data/config.json` on the host via the compose volume
-  mount. Immich URL/API key are too if set via the web UI, but
-  `IMMICH_URL`/`IMMICH_API_KEY` env vars (see Setup above) always take
-  precedence when present.
+- All state (settings, current photo, upcoming queue, battery history,
+  stats) lives in a SQLite database at `./data/espresso.db` on the host
+  via the compose volume mount (`DATABASE_URL` env var to override --
+  any SQLAlchemy URL works, so a future move to Postgres is a config
+  change). A pre-database deployment's `./data/config.json` is imported
+  automatically on first boot (it becomes frame #1) and left untouched
+  afterwards as the rollback path. `IMMICH_URL`/`IMMICH_API_KEY` env
+  vars (see Setup above) still take precedence when present.
 - The upcoming queue is a bounded lookahead, not the whole album --
   "Upcoming photos to show" in the config UI (`queue_target_len`, 5-50,
   default 20) controls its size and takes effect immediately (the queue
@@ -224,15 +171,13 @@ algorithm itself -- it just streams the response straight to the panel.
   in sequential or shuffle order per the Order setting. Dragging photos
   in the web UI (or using "Show next") only rearranges what's already in
   that lookahead; it doesn't add or remove photos from the album.
-- Every endpoint except `/` and `/health` -- the web UI's `/api/*` and
-  every device-facing `/frame/*` -- requires `?token=` (or the
-  `mgmt_token` cookie the web UI sets after a valid one) once
-  `MANAGEMENT_TOKEN` is set (see Setup above); unset, everything stays
-  open like before, which is still fine on a trusted home LAN. `/frame/share`
-  additionally stays scoped to only ever create a link for a photo this
-  frame is actually showing or has queued, not any Immich asset ID
-  someone might guess -- a second layer a leaked token alone wouldn't
-  bypass.
+- Auth in one breath: browsers use sessions (+CSRF), devices use
+  per-frame tokens (`?id=` + `?token=`), the manage QR uses its own
+  limited token, and `MANAGEMENT_TOKEN` survives only as the migration
+  credential for pre-multi-frame firmware. `/frame/share` stays scoped
+  to photos this frame is actually showing or has queued, not any
+  Immich asset ID someone might guess -- a second layer a leaked device
+  token alone wouldn't bypass.
 - The 6-color palette RGB values in `app/image_pipeline.py` are
   approximations, not measured values (Waveshare doesn't publish exact
   color primaries for this panel) -- tune them once you can compare a

server/app/auth.py

@@ -0,0 +1,353 @@
+"""Authentication: password hashing, user sessions + CSRF, the legacy
+shared-token gate, and device resolution.
+
+Three independent credential classes:
+- User sessions (cookie "session", server-side sessions table, per-
+  session CSRF token required on mutating requests) -- humans.
+- The legacy shared MANAGEMENT_TOKEN (env-only). Still accepted on
+  browser routes so the deployed frame's on-panel manage QR (which
+  embeds ?token=) keeps working until Phase C replaces it with the
+  limited /m/ page; CSRF doesn't apply to it (it's explicit per-request
+  credential, not an ambient cookie a cross-site request could ride).
+- Device credentials (?id= + ?token=, see require_device below).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+import os
+import secrets
+import time
+
+from fastapi import Depends, HTTPException, Request
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .db import get_db
+from .migration import new_device_token, new_manage_token
+from .models import Frame, PendingClaim, User, UserFrame, UserSession
+
+logger = logging.getLogger(__name__)
+
+MANAGEMENT_TOKEN_COOKIE = "mgmt_token"
+SESSION_COOKIE = "session"
+SESSION_LIFETIME_S = 30 * 86400
+SESSION_REFRESH_BELOW_S = 15 * 86400  # rolling expiry: extend when under this much left
+
+# stdlib scrypt instead of a passlib/argon2 dependency: zero new deps,
+# and the parameters are baked into each stored hash so they can be
+# raised later without invalidating existing ones.
+_SCRYPT_N = 16384
+_SCRYPT_R = 8
+_SCRYPT_P = 1
+
+
+def hash_password(password: str) -> str:
+    salt = os.urandom(16)
+    digest = hashlib.scrypt(
+        password.encode(), salt=salt, n=_SCRYPT_N, r=_SCRYPT_R, p=_SCRYPT_P
+    )
+    return f"scrypt${_SCRYPT_N}${_SCRYPT_R}${_SCRYPT_P}${salt.hex()}${digest.hex()}"
+
+
+def verify_password(password: str, stored: str) -> bool:
+    try:
+        scheme, n, r, p, salt_hex, hash_hex = stored.split("$")
+        if scheme != "scrypt":
+            return False
+        digest = hashlib.scrypt(
+            password.encode(), salt=bytes.fromhex(salt_hex), n=int(n), r=int(r), p=int(p)
+        )
+        return hmac.compare_digest(digest.hex(), hash_hex)
+    except (ValueError, AttributeError):
+        return False
+
+
+def _hash_session_token(value: str) -> str:
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+def create_session(db: Session, user: User) -> tuple[str, UserSession]:
+    """Returns (cookie_value, session row). Only the sha256 of the cookie
+    value is stored, so a leaked database doesn't yield usable cookies."""
+    cookie_value = secrets.token_urlsafe(32)
+    now = time.time()
+    session = UserSession(
+        token_hash=_hash_session_token(cookie_value),
+        user_id=user.id,
+        csrf_token=secrets.token_urlsafe(32),
+        created_at=now,
+        expires_at=now + SESSION_LIFETIME_S,
+    )
+    db.add(session)
+    # Opportunistic prune -- no background scheduler in this project.
+    for stale in db.scalars(select(UserSession).where(UserSession.expires_at < now)):
+        db.delete(stale)
+    db.commit()
+    return cookie_value, session
+
+
+def destroy_session(db: Session, request: Request) -> None:
+    cookie_value = request.cookies.get(SESSION_COOKIE)
+    if not cookie_value:
+        return
+    session = db.scalars(
+        select(UserSession).where(UserSession.token_hash == _hash_session_token(cookie_value))
+    ).first()
+    if session is not None:
+        db.delete(session)
+        db.commit()
+
+
+def current_session(request: Request, db: Session) -> UserSession | None:
+    cookie_value = request.cookies.get(SESSION_COOKIE)
+    if not cookie_value:
+        return None
+    session = db.scalars(
+        select(UserSession).where(UserSession.token_hash == _hash_session_token(cookie_value))
+    ).first()
+    now = time.time()
+    if session is None or session.expires_at < now:
+        return None
+    if session.expires_at - now < SESSION_REFRESH_BELOW_S:
+        session.expires_at = now + SESSION_LIFETIME_S
+        db.commit()
+    return session
+
+
+def current_user(request: Request, db: Session) -> User | None:
+    session = current_session(request, db)
+    if session is None:
+        return None
+    return db.get(User, session.user_id)
+
+
+def users_exist(db: Session) -> bool:
+    return db.scalars(select(User).limit(1)).first() is not None
+
+
+def _csrf_ok(request: Request, session: UserSession) -> bool:
+    supplied = request.headers.get("X-CSRF-Token") or ""
+    return hmac.compare_digest(supplied, session.csrf_token)
+
+
+def require_user_api(request: Request, db: Session = Depends(get_db)) -> User:
+    """JSON-API dependency: a logged-in user, with CSRF enforced on
+    mutating methods (the session rides an ambient cookie; the CSRF
+    header is what proves the request came from our own JS, not a
+    cross-site form)."""
+    session = current_session(request, db)
+    if session is None:
+        raise HTTPException(401, "Not logged in")
+    if request.method not in ("GET", "HEAD", "OPTIONS") and not _csrf_ok(request, session):
+        raise HTTPException(403, "Missing or invalid CSRF token")
+    user = db.get(User, session.user_id)
+    if user is None:
+        raise HTTPException(401, "Not logged in")
+    return user
+
+
+def require_admin_api(request: Request, db: Session = Depends(get_db)) -> User:
+    user = require_user_api(request, db)
+    if not user.is_admin:
+        raise HTTPException(403, "Admin only")
+    return user
+
+
+def user_frames(db: Session, user: User) -> list[Frame]:
+    """The frames this user sees in their sidebar: linked ones, or all of
+    them for an admin (admins are the household operators -- they see
+    unclaimed/new frames too, that's how those get adopted)."""
+    if user.is_admin:
+        return list(db.scalars(select(Frame).order_by(Frame.id)))
+    return list(
+        db.scalars(
+            select(Frame)
+            .join(UserFrame, UserFrame.frame_id == Frame.id)
+            .where(UserFrame.user_id == user.id)
+            .order_by(Frame.id)
+        )
+    )
+
+
+def can_view_frame(db: Session, user: User, frame: Frame) -> bool:
+    return user.is_admin or db.get(UserFrame, (user.id, frame.id)) is not None
+
+
+def require_frame_view(
+    frame_id: int, request: Request, db: Session = Depends(get_db)
+) -> Frame:
+    """JSON-API dependency: a logged-in user who is linked to this frame
+    (or an admin). 404 -- not 403 -- for frames outside the user's view,
+    so the API doesn't confirm which frame ids exist."""
+    user = require_user_api(request, db)
+    frame = db.get(Frame, frame_id)
+    if frame is None or not can_view_frame(db, user, frame):
+        raise HTTPException(404, "No such frame")
+    return frame
+
+
+def require_frame_control(
+    frame_id: int, request: Request, db: Session = Depends(get_db)
+) -> Frame:
+    """View access plus the soft control lock: only the user currently
+    holding control may mutate settings/queue. The 409 payload names the
+    holder so the UI can offer "take control" instead of a dead end.
+    Physical device buttons don't go through this -- device actions are
+    device actions."""
+    user = require_user_api(request, db)
+    frame = db.get(Frame, frame_id)
+    if frame is None or not can_view_frame(db, user, frame):
+        raise HTTPException(404, "No such frame")
+    if frame.controlled_by_user_id != user.id:
+        holder = frame.controlled_by
+        raise HTTPException(
+            409,
+            {
+                "error": "not_controller",
+                "holder": (holder.display_name or holder.username) if holder else None,
+            },
+        )
+    return frame
+
+
+def management_token() -> str:
+    """The legacy shared secret. Env-only, never stored -- same as the old
+    server, where the env var overrode anything on disk on every load."""
+    return os.environ.get("MANAGEMENT_TOKEN", "")
+
+
+def browser_token_valid(request: Request) -> bool:
+    """The legacy shared-token check. No MANAGEMENT_TOKEN configured means
+    token-holders don't exist -- but unlike Phase A this no longer means
+    "open": once users exist, sessions are the primary gate and this is
+    only the compatibility path for the deployed frame's manage QR
+    (?token=) until Phase C. Empty token => not valid (sessions rule)."""
+    token = management_token()
+    if not token:
+        return False
+    supplied = request.query_params.get("token") or request.cookies.get(MANAGEMENT_TOKEN_COOKIE)
+    return supplied is not None and supplied == token
+
+
+def require_browser(request: Request, db: Session = Depends(get_db)) -> User | None:
+    """Dependency for the web UI's /api/* routes: a real user session
+    (CSRF-checked on mutations, returns the User), or the legacy shared
+    token (returns None -- token bearers act as an anonymous operator,
+    exactly the pre-user model). While NO users exist yet (fresh install
+    or freshly migrated, before /setup has been run) the API stays open
+    if no MANAGEMENT_TOKEN is set -- the Phase A/legacy behavior --
+    since there's nobody to log in as yet."""
+    session = current_session(request, db)
+    if session is not None:
+        if request.method not in ("GET", "HEAD", "OPTIONS") and not _csrf_ok(request, session):
+            raise HTTPException(403, "Missing or invalid CSRF token")
+        user = db.get(User, session.user_id)
+        if user is not None:
+            return user
+    if browser_token_valid(request):
+        return None
+    if not users_exist(db) and not management_token():
+        return None
+    raise HTTPException(401, "Not logged in")
+
+
+def _register_frame(db: Session, device_id: str) -> Frame:
+    """A device id we've never seen: self-register it as an unclaimed
+    frame (this fires from ANY /frame/* route -- the wake cycle hits
+    /frame/image before /frame/config). If a user already submitted a
+    claim for this id (they beat the device to the server after
+    provisioning), attach it now."""
+    frame = Frame(
+        name=f"Frame {device_id[-6:]}",
+        device_id=device_id,
+        device_token=new_device_token(),
+        manage_token=new_manage_token(),
+        created_at=time.time(),
+    )
+    db.add(frame)
+    db.flush()
+
+    now = time.time()
+    # Opportunistically prune expired claims while we're here.
+    for stale in db.scalars(select(PendingClaim).where(PendingClaim.expires_at < now)):
+        db.delete(stale)
+
+    pending = db.get(PendingClaim, device_id)
+    if pending is not None and pending.expires_at >= now:
+        frame.owner_user_id = pending.user_id
+        frame.claimed_at = now
+        db.add(UserFrame(user_id=pending.user_id, frame_id=frame.id))
+        db.delete(pending)
+        logger.info("Frame %s self-registered and attached pending claim by user %d",
+                    device_id, pending.user_id)
+    else:
+        logger.info("Frame %s self-registered (unclaimed)", device_id)
+    return frame
+
+
+def require_device(request: Request, db: Session = Depends(get_db)) -> Frame:
+    """Resolves and authenticates the frame behind a /frame/* request.
+
+    New firmware sends ?id=<12-hex-mac>&token=<per-frame device token>.
+    Deployed legacy firmware sends only ?token=<shared MANAGEMENT_TOKEN>
+    (or nothing, on an open server) -- those requests resolve to the
+    unique legacy_token_enabled frame for as long as that migration
+    window stays open. The first id-bearing request arriving with legacy
+    credentials while the legacy frame has no device_id yet BINDS that id
+    to it -- that's the moment the deployed frame comes back up on new
+    firmware after its OTA, and it must not register as a second frame.
+    """
+    device_id = request.query_params.get("id", "").strip().lower()
+    token = request.query_params.get("token", "")
+    legacy = management_token()
+    legacy_ok = not legacy or token == legacy
+
+    if device_id:
+        frame = db.scalars(select(Frame).where(Frame.device_id == device_id)).first()
+        if frame is None:
+            legacy_frame = db.scalars(
+                select(Frame).where(Frame.legacy_token_enabled == True)  # noqa: E712
+            ).first()
+            if legacy_frame is not None and legacy_frame.device_id is None and legacy_ok:
+                legacy_frame.device_id = device_id
+                frame = legacy_frame
+                logger.info("Bound device id %s to legacy frame #%d", device_id, frame.id)
+            else:
+                frame = _register_frame(db, device_id)
+        else:
+            token_ok = bool(token) and token == frame.device_token
+            if token_ok and not frame.device_token_ack:
+                frame.device_token_ack = True
+                logger.info("Frame #%d acknowledged its device token", frame.id)
+            if not token_ok:
+                if frame.legacy_token_enabled and legacy_ok:
+                    pass
+                elif not frame.device_token_ack:
+                    # Handshake window: the device registered but hasn't
+                    # received its token yet (the wake cycle fetches the
+                    # image BEFORE polling /frame/config, where the token
+                    # is delivered) -- the id stays the credential, same
+                    # trust level as the open registration that created
+                    # the row. Closes permanently on the first
+                    # authenticated request.
+                    pass
+                else:
+                    raise HTTPException(401, "Missing or invalid access token")
+    else:
+        if not legacy_ok:
+            raise HTTPException(401, "Missing or invalid access token")
+        frame = db.scalars(
+            select(Frame).where(Frame.legacy_token_enabled == True)  # noqa: E712
+        ).first()
+        if frame is None:
+            # Nothing to resolve a no-id request to. migration.py always
+            # creates frame #1 at startup, so this only happens if it was
+            # deleted -- treat like an unknown device.
+            raise HTTPException(401, "No frame accepts legacy credentials")
+
+    frame.last_seen = time.time()
+    db.commit()
+    return frame

server/app/config.py

@@ -1,134 +1,85 @@
-"""JSON-file-backed config: Immich connection, selected album, and cursor
-state (which photo /frame/image serves next)."""
+"""LEGACY config.json model -- kept only so migration.py can import an
+existing single-frame deployment's state into the database on first
+boot. Nothing else should import this module; runtime state lives in
+SQLite (see models.py/db.py).
+
+The file at CONFIG_PATH is deliberately never modified or deleted by the
+migration: it's the rollback path (redeploying the pre-database server
+image picks it right back up).
+"""
 
 from __future__ import annotations
 
 import json
 import os
-from contextlib import contextmanager
 from pathlib import Path
-from threading import RLock
-from typing import Iterator
 
 from pydantic import BaseModel
 
 CONFIG_PATH = Path(os.environ.get("CONFIG_PATH", "/data/config.json"))
 
-# Reentrant so load()/save() can each take it internally for their own I/O
-# while a caller also holds it for a whole locked() span (see below).
-_lock = RLock()
-
 
 class FrameStats(BaseModel):
-    """Cumulative, lifetime counters -- purely informational, never read
-    back to drive any behavior, so there's no harm in them being a little
-    approximate at the edges. Shown in a collapsed "Stats" section in the
-    web UI (GET /api/stats). Never reset except by deleting config.json."""
-    first_seen: float = 0.0  # first time this frame ever checked in
-    device_wakes: int = 0  # wake cycles, counted once each via GET /frame/config
-    photos_displayed: int = 0  # times the current photo actually changed (any cause)
-    photos_removed: int = 0  # times a photo was permanently excluded from rotation
-    battery_reports: int = 0  # POST /frame/battery calls
-    recharge_cycles: int = 0  # times a battery recharge was detected
-    ota_updates_applied: int = 0  # times the device's reported firmware version changed
-    config_saves: int = 0  # POST /api/config calls
+    first_seen: float = 0.0
+    device_wakes: int = 0
+    photos_displayed: int = 0
+    photos_removed: int = 0
+    battery_reports: int = 0
+    recharge_cycles: int = 0
+    ota_updates_applied: int = 0
+    config_saves: int = 0
 
 
 class FrameConfig(BaseModel):
     immich_url: str = ""
     immich_api_key: str = ""
-    management_token: str = ""  # gates the web UI (see main.py); empty = no gate, open on trusted LAN
+    management_token: str = ""
     album_id: str = ""
-    order: str = "sequential"  # or "shuffle"
+    order: str = "sequential"
     refresh_interval_s: int = 3600
-    # Quiet hours: no point waking the device overnight just to swap a
-    # photo nobody's looking at. Times are "HH:MM" interpreted in
-    # `timezone` below and may wrap past midnight (e.g. start=22:00,
-    # end=07:00). Purely a server-side decision -- the device is unaware,
-    # it just gets told a longer refresh_interval_s by GET /frame/config
-    # while quiet hours are in effect (see main.py's
-    # _effective_refresh_interval_s).
     quiet_hours_enabled: bool = False
     quiet_hours_start: str = "22:00"
     quiet_hours_end: str = "07:00"
-    # IANA zone name (e.g. "America/New_York") quiet_hours_start/end are
-    # interpreted in. Set from the web UI rather than the container's TZ
-    # environment variable, so it survives container recreation and
-    # doesn't need a docker-compose.yml edit to change.
     timezone: str = "UTC"
     smart_crop_faces: bool = True
-    # How the physical frame is hung: landscape (native), portrait,
-    # landscape_flipped, portrait_flipped. Purely a server-side render
-    # decision -- the device always receives native 800x480 bytes.
     orientation: str = "landscape"
 
-    # Current photo + upcoming queue (see app/photo_queue.py). current_asset_set_at
-    # is what lets the server decide "has it been long enough to advance" on its
-    # own clock, independent of how/why the device asked for a photo.
     current_asset_id: str = ""
     current_asset_set_at: float = 0.0
     queue: list[str] = []
-    queue_cursor: int = 0  # internal bookkeeping for sequential queue top-up; not user-facing
-    queue_target_len: int = 20  # how many upcoming photos to keep queued/shown in the web UI
-    history: list[str] = []  # bounded stack of previously-current asset ids, most recent last
-    excluded_asset_ids: list[str] = []  # permanently removed from this frame's rotation (not deleted from Immich)
+    queue_cursor: int = 0
+    queue_target_len: int = 20
+    history: list[str] = []
+    excluded_asset_ids: list[str] = []
 
-    # Last battery report from the device (POST /frame/battery); -1 = never
-    # reported / not battery-powered. battery_as_of mirrors the
-    # current_asset_set_at timestamp pattern.
     battery_percent: int = -1
     battery_as_of: float = 0.0
-    # [timestamp, percent] pairs for the CURRENT discharge cycle only --
-    # reset whenever a report jumps up enough to indicate a recharge (see
-    # main.py). Feeds the "on battery for" and "estimated remaining"
-    # numbers in the web UI's Device panel.
     battery_history: list = []
-    # Every report ever received, never reset by a recharge -- the
-    # permanent record behind the web UI's battery history graph. Capped
-    # generously (not a real limit at realistic report rates, just a
-    # safety bound), unlike battery_history above which is deliberately
-    # scoped to one cycle.
     battery_log: list = []
 
-    # Device liveness/telemetry: last_seen is touched by every /frame/*
-    # request; device_firmware_version comes from the X-Frame-Version
-    # header the device sends with its config poll.
     last_seen: float = 0.0
     device_firmware_version: str = ""
-    # Version parsed out of the most recently uploaded OTA image
-    # (POST /api/firmware); "" = none uploaded yet.
+    device_board_variant: str = ""
     firmware_available_version: str = ""
-
-    # Gitea-hosted firmware auto-update (see app/gitea_releases.py).
-    # repo_url empty = feature off, no Gitea calls made at all.
-    # board_variant picks which release asset to pull -- must match one of
-    # the names .gitea/workflows/firmware-release-build.yml publishes
-    # (firmware-<board_variant>.bin).
-    firmware_update_repo_url: str = ""  # e.g. "https://git.example.com/owner/repo"
-    firmware_board_variant: str = "xiao"  # "xiao" or "devkit"
-    firmware_auto_update: bool = False  # pull+stage a newer release with no button click
-    # Optional Gitea PAT (read-only access is enough) for a private repo's
-    # releases; blank is fine for a public repo. GITEA_FIRMWARE_TOKEN env
-    # var overrides, mirroring MANAGEMENT_TOKEN below -- never exposed to
-    # the web UI template or any JSON response.
+    firmware_update_repo_url: str = ""
+    firmware_auto_update: bool = False
     firmware_update_token: str = ""
-    firmware_update_checked_at: float = 0.0  # throttle bookkeeping, see gitea_releases.UPDATE_CHECK_INTERVAL_S
-    firmware_gitea_latest_version: str = ""  # latest release's version, from its tag name
+    firmware_update_checked_at: float = 0.0
+    firmware_gitea_latest_version: str = ""
 
     stats: FrameStats = FrameStats()
 
 
 def load() -> FrameConfig:
-    with _lock:
-        if not CONFIG_PATH.exists():
-            cfg = FrameConfig()
-        else:
-            cfg = FrameConfig(**json.loads(CONFIG_PATH.read_text()))
+    """Reads the legacy file with the same env-override behavior the old
+    server applied on every load -- which is exactly how env-configured
+    IMMICH_URL/IMMICH_API_KEY get baked into the database at migration
+    time even though they were never written to the file itself."""
+    if not CONFIG_PATH.exists():
+        cfg = FrameConfig()
+    else:
+        cfg = FrameConfig(**json.loads(CONFIG_PATH.read_text()))
 
-    # IMMICH_URL/IMMICH_API_KEY/MANAGEMENT_TOKEN/GITEA_FIRMWARE_TOKEN set in
-    # the environment (e.g. docker-compose.yml, see
-    # docker-compose.yml.example) take precedence over whatever's saved in
-    # CONFIG_PATH, so credentials never need to go through the web UI.
     env_url = os.environ.get("IMMICH_URL")
     env_key = os.environ.get("IMMICH_API_KEY")
     env_token = os.environ.get("MANAGEMENT_TOKEN")
@@ -143,22 +94,3 @@ def load() -> FrameConfig:
         cfg.firmware_update_token = env_gitea_token
 
     return cfg
-
-
-def save(cfg: FrameConfig) -> None:
-    with _lock:
-        CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
-        CONFIG_PATH.write_text(cfg.model_dump_json(indent=2))
-
-
-@contextmanager
-def locked() -> Iterator[None]:
-    """Serializes an entire load-mutate-save cycle. load()/save() each
-    only lock their own I/O, which isn't enough by itself: uvicorn
-    dispatches sync routes to a thread pool, so two concurrent requests
-    (e.g. the device's own poll landing alongside a web UI edit) can each
-    load() the same on-disk state and the second save() silently clobber
-    the first's changes. Route handlers that mutate config should wrap
-    their whole load/mutate/save span in this."""
-    with _lock:
-        yield

server/app/db.py

@@ -0,0 +1,88 @@
+"""Engine, sessions, and the per-frame lock that replaces the old
+whole-config.json RLock.
+
+Single uvicorn worker (see Dockerfile) -- handlers are sync and run in
+the threadpool, so this is ordinary multi-threading in one process: the
+same regime the old config.locked() RLock handled, now scoped per frame.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from contextlib import contextmanager
+from typing import Iterator
+
+from sqlalchemy import create_engine, event
+from sqlalchemy.orm import Session, sessionmaker
+
+from .models import Frame
+
+DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:////data/espresso.db")
+
+_is_sqlite = DATABASE_URL.startswith("sqlite")
+
+engine = create_engine(
+    DATABASE_URL,
+    connect_args={"check_same_thread": False} if _is_sqlite else {},
+)
+
+if _is_sqlite:
+
+    @event.listens_for(engine, "connect")
+    def _sqlite_pragmas(dbapi_connection, _record):
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.execute("PRAGMA busy_timeout=5000")
+        cursor.close()
+
+
+# expire_on_commit=False so a Frame resolved by the require_device
+# dependency (which commits its last_seen touch) stays usable in the
+# route handler without a re-select per attribute. Freshness inside
+# mutation spans is handled explicitly by frame_locked()'s refresh.
+SessionLocal = sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)
+
+
+def get_db() -> Iterator[Session]:
+    """FastAPI dependency: one session per request (FastAPI caches the
+    dependency, so require_device and the route handler share it)."""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+# One lock per frame id, created on demand. Guarded by a module lock so
+# two threads can't race to create different Lock objects for the same
+# frame (which would defeat the whole point).
+_frame_locks: dict[int, threading.Lock] = {}
+_frame_locks_guard = threading.Lock()
+
+
+def _get_lock(frame_id: int) -> threading.Lock:
+    with _frame_locks_guard:
+        lock = _frame_locks.get(frame_id)
+        if lock is None:
+            lock = threading.Lock()
+            _frame_locks[frame_id] = lock
+        return lock
+
+
+@contextmanager
+def frame_locked(db: Session, frame_id: int) -> Iterator[Frame]:
+    """Serializes a whole read-modify-write span on one frame -- the
+    direct successor of the old config.locked(). The refresh() inside the
+    lock is what makes it correct: without it the session could hold
+    attribute state read *before* another thread's committed write, and
+    saving would silently clobber it (the same lost-update race the old
+    pattern's 're-read inside the lock' comment guarded against)."""
+    with _get_lock(frame_id):
+        frame = db.get(Frame, frame_id)
+        if frame is None:
+            raise LookupError(f"Frame {frame_id} does not exist")
+        db.refresh(frame)
+        yield frame
+        db.commit()

server/app/firmware.py

@@ -1,7 +1,8 @@
-"""Local firmware image storage + esp_app_desc_t parsing. Shared by the
-manual upload path (POST /api/firmware) and the Gitea auto-update path
-(see gitea_releases.py) -- both end up writing the same firmware.bin slot
-that GET /frame/firmware streams to the device."""
+"""Per-frame firmware image storage + esp_app_desc_t parsing. Shared by
+the manual upload path and the Gitea auto-update path -- both end up
+writing the same per-frame slot that GET /frame/firmware streams to the
+device. The migration moves the old single /data/firmware.bin into frame
+#1's slot."""
 
 from __future__ import annotations
 
@@ -18,8 +19,8 @@ APP_DESC_MAGIC = 0xABCD5432
 EXPECTED_PROJECT_NAME = "espresso_frame"
 
 
-def firmware_path():
-    return config.CONFIG_PATH.parent / "firmware.bin"
+def firmware_path(frame_id: int):
+    return config.CONFIG_PATH.parent / "firmware" / f"{frame_id}.bin"
 
 
 def parse_app_version(data: bytes) -> str:

server/app/image_pipeline.py

@@ -174,7 +174,15 @@ def render_frame(source: Image.Image, faces: list[dict] | None = None,
     else:
         fitted = ImageOps.fit(fitted, (logical_w, logical_h), method=Image.LANCZOS)
 
-    quantized = fitted.quantize(palette=_PALETTE_IMAGE, dither=Image.Dither.FLOYDSTEINBERG)
+    return _quantize_and_pack(fitted, orientation)
+
+
+def _quantize_and_pack(logical_img: Image.Image, orientation: str) -> bytes:
+    """The shared back half of rendering: 6-color Floyd-Steinberg
+    quantization, rotation into native panel space, and 2-pixels/byte
+    packing. Takes an RGB image already composed at logical_render_size()
+    for the orientation."""
+    quantized = logical_img.quantize(palette=_PALETTE_IMAGE, dither=Image.Dither.FLOYDSTEINBERG)
     transpose = ORIENTATION_TRANSPOSE.get(orientation)
     if transpose is not None:
         quantized = quantized.transpose(transpose)
@@ -190,3 +198,52 @@ def render_frame(source: Image.Image, faces: list[dict] | None = None,
             i += 1
 
     return bytes(out)
+
+
+def render_placeholder(lines: list[str], qr_url: str | None = None,
+                       orientation: str = "landscape") -> bytes:
+    """A readable full-panel message (plus an optional QR code) in the
+    same packed format as render_frame -- what /frame/image serves for a
+    frame that isn't claimed or configured yet, so a fresh device shows
+    instructions instead of an error screen and never error-loops."""
+    from PIL import ImageDraw, ImageFont
+
+    logical_w, logical_h = logical_render_size(orientation)
+    img = Image.new("RGB", (logical_w, logical_h), (255, 255, 255))
+    draw = ImageDraw.Draw(img)
+
+    title_font = ImageFont.load_default(size=34)
+    body_font = ImageFont.load_default(size=24)
+
+    qr_img = None
+    if qr_url:
+        import qrcode
+
+        qr = qrcode.QRCode(border=1, box_size=1)
+        qr.add_data(qr_url)
+        qr.make(fit=True)
+        raw = qr.make_image().get_image().convert("RGB")
+        # Integer upscale with NEAREST keeps modules crisp on the panel.
+        target = 220
+        scale = max(1, target // raw.width)
+        qr_img = raw.resize((raw.width * scale, raw.height * scale), Image.NEAREST)
+
+    # Vertical layout: text block, then QR under it, centered as a group.
+    line_heights = []
+    for i, line in enumerate(lines):
+        font = title_font if i == 0 else body_font
+        bbox = draw.textbbox((0, 0), line, font=font)
+        line_heights.append((line, font, bbox[2] - bbox[0], bbox[3] - bbox[1]))
+    gap = 14
+    text_h = sum(h for _, _, _, h in line_heights) + gap * (len(line_heights) - 1 if line_heights else 0)
+    total_h = text_h + (qr_img.height + 28 if qr_img else 0)
+    y = max(20, (logical_h - total_h) // 2)
+
+    for line, font, w, h in line_heights:
+        draw.text(((logical_w - w) // 2, y), line, fill=(0, 0, 0), font=font)
+        y += h + gap
+
+    if qr_img:
+        img.paste(qr_img, ((logical_w - qr_img.width) // 2, y + 14))
+
+    return _quantize_and_pack(img, orientation)

server/app/main.py

@@ -1,199 +1,53 @@
-"""ESPresso Frame server: pulls photos from Immich, pre-processes them for
-the panel, and serves the ESP32 a ready-to-display frame."""
+"""ESPresso Frame server: pulls photos from Immich, pre-processes them
+for the panel, and serves ESP32 frames ready-to-display images.
+
+This module is assembly only -- routes live in app/routers/:
+  device.py       the firmware-facing /frame/* protocol (paths frozen)
+  api_frames.py   the web UI's JSON API, /api/frames/{id}/...
+  frame_pages.py  the per-frame Photos/Configuration/Stats pages
+  pages.py        setup/login/claim/settings/admin
+  manage.py       the limited manage-QR surface (/m/, /api/m/)
+Storage is SQLite via models.py/db.py; migration.py imports a
+pre-database config.json deployment on first boot."""
 
 from __future__ import annotations
 
-import io
 import logging
-import time
-from datetime import datetime, timedelta
-from zoneinfo import ZoneInfo, available_timezones
 
-import httpx
-from fastapi import Depends, FastAPI, File, HTTPException, Form, Request, UploadFile
-from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse, Response
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
-from PIL import Image
-from pydantic import BaseModel
+from sqlalchemy import select
 
-from . import config, gitea_releases, photo_queue
-from .face_labels import compute_face_labels
-from .firmware import firmware_path, parse_app_version
-from .image_pipeline import render_frame
-from .immich_client import ImmichClient
+from . import migration
+from .auth import (
+    browser_token_valid,
+    current_user,
+    management_token,
+    user_frames,
+    users_exist,
+)
+from .db import SessionLocal
+from .models import Frame
+from .routers import api_frames, device, frame_pages, manage, pages
+from .routers.common import shell_context
 
 logger = logging.getLogger(__name__)
 
+# Schema + legacy-config import, before the first request is served.
+migration.run_migrations()
+
 app = FastAPI(title="ESPresso Frame Server")
 templates = Jinja2Templates(directory="app/templates")
 
-MIN_REFRESH_INTERVAL_S = 60
-MAX_REFRESH_INTERVAL_S = 86400
-MIN_QUEUE_TARGET_LEN = 5
-MAX_QUEUE_TARGET_LEN = 5000
+app.mount("/static", StaticFiles(directory="app/static"), name="static")
 
-ORIENTATIONS = ("landscape", "portrait", "landscape_flipped", "portrait_flipped")
-
-# Populated once from the OS's zoneinfo database (installed via the
-# `tzdata` apt package in the Dockerfile) and offered as a <select> in the
-# web UI's "Timezone" field -- see api_config_save/index below.
-ALL_TIMEZONES = sorted(available_timezones())
-
-MANAGEMENT_TOKEN_COOKIE = "mgmt_token"
-
-# Battery-history / estimate tuning (see /frame/battery and _battery_estimate).
-BATTERY_HISTORY_MAX = 500  # ~20 days at hourly reports
-BATTERY_LOG_MAX = 20000  # ~2 years at hourly reports -- see FrameConfig.battery_log
-RECHARGE_JUMP_PCT = 5  # a report this much above the previous one = battery was recharged
-MIN_ESTIMATE_SPAN_S = 2 * 3600  # need at least this much observed time...
-MIN_ESTIMATE_DROP_PCT = 2  # ...and this much observed drop before estimating
-
-# "Overdue" threshold multiplier: the device should check in roughly every
-# refresh_interval_s; give it half again as long before flagging it.
-OVERDUE_FACTOR = 1.5
-
-
-def _valid_hhmm(s: str) -> bool:
-    try:
-        datetime.strptime(s, "%H:%M")
-        return True
-    except ValueError:
-        return False
-
-
-def _zoneinfo(name: str) -> ZoneInfo:
-    """Falls back to UTC for an unrecognized zone name -- defensive only;
-    api_config_save already validates against ALL_TIMEZONES before saving,
-    so this only matters for a config.json hand-edited or written by an
-    older version of this file."""
-    try:
-        return ZoneInfo(name)
-    except Exception:
-        return ZoneInfo("UTC")
-
-
-def _quiet_hours_state(now: datetime, start_str: str, end_str: str) -> tuple[bool, datetime | None]:
-    """Whether `now` falls inside the quiet-hours window, and the next
-    boundary: if inside, when it ends; if outside, when it next starts.
-    Handles a window that wraps past midnight (e.g. 22:00-07:00). Returns
-    (False, None) for a degenerate window (start == end)."""
-    sh, sm = (int(x) for x in start_str.split(":"))
-    eh, em = (int(x) for x in end_str.split(":"))
-    start = now.replace(hour=sh, minute=sm, second=0, microsecond=0)
-    end = now.replace(hour=eh, minute=em, second=0, microsecond=0)
-
-    if start == end:
-        return False, None
-
-    if start < end:
-        # Same-day window, e.g. 13:00-15:00. End is exclusive, so being
-        # exactly at `end` counts as already outside the window.
-        if start <= now < end:
-            return True, end
-        if now < start:
-            return False, start
-        return False, start + timedelta(days=1)
-
-    # Wraps midnight, e.g. 22:00-07:00.
-    if now >= start:
-        return True, end + timedelta(days=1)
-    if now < end:
-        return True, end
-    return False, start
-
-
-def _quiet_hours_span_s(start_str: str, end_str: str) -> int:
-    """Duration of the quiet-hours window in seconds, wrap-aware."""
-    sh, sm = (int(x) for x in start_str.split(":"))
-    eh, em = (int(x) for x in end_str.split(":"))
-    span_min = ((eh * 60 + em) - (sh * 60 + sm)) % (24 * 60)
-    return span_min * 60
-
-
-def _effective_refresh_interval_s(cfg: config.FrameConfig) -> int:
-    """The refresh interval actually handed to the device: its configured
-    value, unless quiet hours are enabled, in which case it's clamped so
-    the device sleeps through the whole window instead of waking inside
-    it. A device already mid-sleep when quiet hours begin can still land
-    one wake inside the window (nothing server-side can prevent that
-    without touching the firmware) -- but from that wake on, it's told to
-    sleep exactly until the window ends."""
-    if not cfg.quiet_hours_enabled:
-        return cfg.refresh_interval_s
-    now = datetime.now(_zoneinfo(cfg.timezone))
-    in_quiet, boundary = _quiet_hours_state(now, cfg.quiet_hours_start, cfg.quiet_hours_end)
-    if boundary is None:
-        return cfg.refresh_interval_s
-    seconds_to_boundary = max(1, int((boundary - now).total_seconds()))
-    if in_quiet:
-        return seconds_to_boundary
-    return min(cfg.refresh_interval_s, seconds_to_boundary)
-
-
-def _in_quiet_hours(cfg: config.FrameConfig) -> bool:
-    """Whether quiet hours are in effect right now -- separate from
-    _effective_refresh_interval_s, which only shapes what the *device* is
-    told to sleep for. This instead gates photo_queue.get_current()'s
-    time-based advance, since that check runs independent of the device
-    (also triggered by the web UI's /api/queue, e.g. an open browser tab
-    polling overnight) and would otherwise happily advance the current
-    photo mid-quiet-hours on raw elapsed time alone."""
-    if not cfg.quiet_hours_enabled:
-        return False
-    now = datetime.now(_zoneinfo(cfg.timezone))
-    in_quiet, _ = _quiet_hours_state(now, cfg.quiet_hours_start, cfg.quiet_hours_end)
-    return in_quiet
-
-
-def _max_expected_gap_s(cfg: config.FrameConfig) -> int:
-    """Longest gap between wakes the device might legitimately have --
-    normally just refresh_interval_s, but quiet hours can make the real
-    gap much longer, and the "overdue" check (see api_queue) shouldn't
-    mistake a device quietly sleeping through the night for a dead one."""
-    gap = cfg.refresh_interval_s
-    if cfg.quiet_hours_enabled:
-        gap = max(gap, _quiet_hours_span_s(cfg.quiet_hours_start, cfg.quiet_hours_end))
-    return gap
-
-
-def _touch_last_seen() -> None:
-    """Records that the device just made contact. Called by every
-    /frame/* route -- a handful of extra config writes per wake cycle,
-    which is nothing at hourly wakes."""
-    with config.locked():
-        cfg = config.load()
-        cfg.last_seen = time.time()
-        config.save(cfg)
-
-
-def _token_valid(request: Request, cfg: config.FrameConfig) -> bool:
-    """No management_token configured (MANAGEMENT_TOKEN env var, see
-    docker-compose.yml.example) means the whole server stays open on a
-    trusted LAN, matching this project's original default. Once one's
-    set, a request is authorized by either a ?token= query param (what
-    the ESP32 sends on every device request, and what the manage-menu/
-    share QR codes embed for a human scanning them) or the cookie
-    index() sets after a valid query-param hit (so the web UI's own
-    fetch()/<img> calls, which carry no query string, stay authorized
-    for the rest of that browsing visit)."""
-    if not cfg.management_token:
-        return True
-    supplied = request.query_params.get("token") or request.cookies.get(MANAGEMENT_TOKEN_COOKIE)
-    return supplied is not None and supplied == cfg.management_token
-
-
-def require_access_token(request: Request) -> None:
-    """Dependency for every route except / and /health: the web UI's
-    /api/* and every device-facing /frame/*. index() handles the
-    unauthorized case itself (a friendlier HTML prompt, not a bare 401)
-    since that's the one route a human is actually meant to land on with
-    no token yet; the ESP32 sends its token as ?token= on every request
-    it makes (see frame_client.c's build_url()), so device endpoints
-    just 401 outright on a missing/wrong one. /health stays open -- it
-    reveals nothing but process liveness, and gating it would break
-    plain infra/uptime monitoring for no real security benefit."""
-    if not _token_valid(request, config.load()):
-        raise HTTPException(401, "Missing or invalid access token")
+app.include_router(device.router)
+app.include_router(api_frames.router)
+app.include_router(frame_pages.router)
+app.include_router(pages.router)
+app.include_router(manage.router)
 
 
 @app.get("/health")
@@ -201,695 +55,53 @@ def health() -> dict:
     return {"status": "ok"}
 
 
-@app.get("/frame/config", dependencies=[Depends(require_access_token)])
-def frame_config(request: Request):
-    """Device-facing settings, polled by the frame alongside its
-    reachability check. Always returns 200 with current settings
-    (defaults if nothing's been saved yet) -- no Immich-configured gate,
-    since this doubles as the "is the server up" signal. Also captures
-    the device's running firmware version (X-Frame-Version header) and
-    advertises the uploaded OTA image's version, so the device's update
-    check costs zero extra round trips."""
-    reported_version = request.headers.get("X-Frame-Version", "")
-    with config.locked():
-        cfg = config.load()
-        cfg.last_seen = time.time()
-        if cfg.stats.first_seen == 0:
-            cfg.stats.first_seen = cfg.last_seen
-        cfg.stats.device_wakes += 1
-        if reported_version:
-            if cfg.device_firmware_version and reported_version != cfg.device_firmware_version:
-                cfg.stats.ota_updates_applied += 1
-            cfg.device_firmware_version = reported_version
-        config.save(cfg)
-    return {
-        "refresh_interval_s": _effective_refresh_interval_s(cfg),
-        "firmware_version": cfg.firmware_available_version or None,
-    }
+def _device_credential_redirect(request: Request, db, allow_legacy: bool) -> str | None:
+    """The on-frame manage QR points at the server root with the device's
+    own credentials (new firmware: ?id=&token=; deployed firmware:
+    ?token=<legacy shared token>). Those scans get the frame's limited
+    manage page -- never the full UI, which requires a login.
+    allow_legacy is False before /setup has run: at that point a bare
+    ?token= hit is the admin coming through the token prompt to do
+    first-run setup, not a QR scan."""
+    device_id = request.query_params.get("id", "").strip().lower()
+    token = request.query_params.get("token", "")
+    if device_id and token:
+        frame = db.scalars(select(Frame).where(Frame.device_id == device_id)).first()
+        if frame is not None and token == frame.device_token:
+            return f"/m/{frame.manage_token}"
+    if allow_legacy and token and management_token() and token == management_token():
+        frame = db.scalars(
+            select(Frame).where(Frame.legacy_token_enabled == True)  # noqa: E712
+        ).first()
+        if frame is not None:
+            return f"/m/{frame.manage_token}"
+    return None
 
 
 @app.get("/", response_class=HTMLResponse)
 def index(request: Request):
-    cfg = config.load()
-    if not _token_valid(request, cfg):
-        supplied = request.query_params.get("token")
-        return templates.TemplateResponse(
-            "token_prompt.html", {"request": request, "wrong": supplied is not None}
-        )
-
-    response = templates.TemplateResponse(
-        "index.html", {"request": request, "cfg": cfg, "timezones": ALL_TIMEZONES}
-    )
-    supplied = request.query_params.get("token")
-    if cfg.management_token and supplied == cfg.management_token:
-        # Query-param access (typically the manage-menu QR code) earns a
-        # cookie so the rest of this visit's fetch()/<img> calls -- which
-        # never carry the query string -- stay authorized too.
-        response.set_cookie(
-            MANAGEMENT_TOKEN_COOKIE, supplied, max_age=86400 * 365, httponly=True, samesite="lax"
-        )
-    return response
-
-
-@app.get("/api/albums", dependencies=[Depends(require_access_token)])
-def api_albums():
-    cfg = config.load()
-    if not cfg.immich_url or not cfg.immich_api_key:
-        raise HTTPException(400, "Immich URL/API key not configured yet")
-    try:
-        albums = ImmichClient(cfg.immich_url, cfg.immich_api_key).list_albums()
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not reach Immich at {cfg.immich_url}: {e}") from e
-    return [{"id": a["id"], "name": a["albumName"], "count": a.get("assetCount", 0)} for a in albums]
-
-
-@app.post("/api/config", dependencies=[Depends(require_access_token)])
-def api_config_save(
-    album_id: str = Form(""),
-    order: str = Form("sequential"),
-    refresh_interval_s: int = Form(3600),
-    smart_crop_faces: bool = Form(True),
-    queue_target_len: int = Form(20),
-    orientation: str = Form("landscape"),
-    quiet_hours_enabled: bool = Form(False),
-    quiet_hours_start: str = Form("22:00"),
-    quiet_hours_end: str = Form("07:00"),
-    timezone: str = Form("UTC"),
-    firmware_update_repo_url: str = Form(""),
-    firmware_board_variant: str = Form("xiao"),
-    firmware_auto_update: bool = Form(False),
-):
-    # Immich URL/API key/Gitea token are env-var only (IMMICH_URL/
-    # IMMICH_API_KEY/GITEA_FIRMWARE_TOKEN, see docker-compose.yml.example)
-    # -- config.load() already applies them, and this handler doesn't touch
-    # cfg.immich_url/immich_api_key/firmware_update_token at all, so
-    # there's nothing here that could overwrite or clear them.
-    with config.locked():
-        cfg = config.load()
-        if album_id != cfg.album_id:
-            # A newly selected album starts clean -- the old current photo and
-            # queue don't mean anything in the new album's context.
-            cfg.current_asset_id = ""
-            cfg.current_asset_set_at = 0.0
-            cfg.queue = []
-            cfg.queue_cursor = 0
-            cfg.history = []
-            cfg.excluded_asset_ids = []
-        cfg.album_id = album_id
-        cfg.order = order if order in ("sequential", "shuffle") else "sequential"
-        cfg.refresh_interval_s = max(MIN_REFRESH_INTERVAL_S, min(MAX_REFRESH_INTERVAL_S, refresh_interval_s))
-        cfg.smart_crop_faces = smart_crop_faces
-        cfg.queue_target_len = max(MIN_QUEUE_TARGET_LEN, min(MAX_QUEUE_TARGET_LEN, queue_target_len))
-        cfg.orientation = orientation if orientation in ORIENTATIONS else "landscape"
-        cfg.quiet_hours_enabled = quiet_hours_enabled
-        if _valid_hhmm(quiet_hours_start):
-            cfg.quiet_hours_start = quiet_hours_start
-        if _valid_hhmm(quiet_hours_end):
-            cfg.quiet_hours_end = quiet_hours_end
-        if timezone in ALL_TIMEZONES:
-            cfg.timezone = timezone
-        cfg.firmware_update_repo_url = firmware_update_repo_url.strip()
-        cfg.firmware_board_variant = firmware_board_variant if firmware_board_variant in ("xiao", "devkit") else "xiao"
-        cfg.firmware_auto_update = firmware_auto_update
-        cfg.stats.config_saves += 1
-        config.save(cfg)
-    return {"status": "saved"}
-
-
-@app.get("/api/stats", dependencies=[Depends(require_access_token)])
-def api_stats():
-    return config.load().stats.model_dump()
-
-
-def _require_configured(cfg: config.FrameConfig) -> None:
-    if not cfg.immich_url or not cfg.immich_api_key:
-        raise HTTPException(400, "Immich URL/API key not configured yet")
-    if not cfg.album_id:
-        raise HTTPException(400, "No album configured yet")
-
-
-def _list_assets(client: ImmichClient, cfg: config.FrameConfig) -> list[dict]:
-    try:
-        assets = client.list_album_assets(cfg.album_id)
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not reach Immich at {cfg.immich_url}: {e}") from e
-    if not assets:
-        raise HTTPException(404, "Album has no photos")
-    return assets
-
-
-def _render_asset(client: ImmichClient, cfg: config.FrameConfig, asset_id: str) -> bytes:
-    try:
-        jpeg_bytes = client.download_asset_preview(asset_id)
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not download asset from Immich: {e}") from e
-
-    faces = None
-    if cfg.smart_crop_faces:
-        try:
-            faces = client.get_asset_faces(asset_id)
-        except httpx.HTTPError as e:
-            # A faces lookup hiccup shouldn't block showing a photo at
-            # all -- just fall back to a plain center-crop this cycle.
-            logger.warning("Could not fetch faces for asset %s: %s", asset_id, e)
-
-    source = Image.open(io.BytesIO(jpeg_bytes))
-    return render_frame(source, faces=faces, orientation=cfg.orientation)
-
-
-@app.get("/frame/image", dependencies=[Depends(require_access_token)])
-def frame_image():
-    """Returns the current photo. Idempotent: only actually advances to
-    the next photo once refresh_interval_s has elapsed since the current
-    one was set (see app/photo_queue.py) -- safe to call as often as the
-    device wants, including after an unplanned reboot, without skipping
-    ahead in the album."""
-    _touch_last_seen()
-    cfg = config.load()
-    _require_configured(cfg)
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    assets = _list_assets(client, cfg)
-
-    with config.locked():
-        cfg = config.load()  # re-read: state may have changed since the unlocked read above
-        if photo_queue.get_current(cfg, assets, in_quiet_hours=_in_quiet_hours(cfg)):
-            config.save(cfg)
-
-    return Response(content=_render_asset(client, cfg, cfg.current_asset_id), media_type="application/octet-stream")
-
-
-@app.post("/frame/advance", dependencies=[Depends(require_access_token)])
-def frame_advance():
-    """Forces an immediate advance to the next photo, ignoring
-    refresh_interval_s, and resets the interval clock from now. Used by
-    the device's next-photo button."""
-    _touch_last_seen()
-    cfg = config.load()
-    _require_configured(cfg)
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    assets = _list_assets(client, cfg)
-
-    with config.locked():
-        cfg = config.load()  # re-read: state may have changed since the unlocked read above
-        photo_queue.advance_forced(cfg, assets)
-        config.save(cfg)
-
-    return Response(content=_render_asset(client, cfg, cfg.current_asset_id), media_type="application/octet-stream")
-
-
-@app.post("/frame/back", dependencies=[Depends(require_access_token)])
-def frame_back():
-    """Returns to the previously-current photo (the mirror image of
-    /frame/advance -- see photo_queue.back_forced()), and resets the
-    interval clock from now. A no-op (still 200, current photo
-    unchanged) if there's no history to go back to -- same "always
-    returns something displayable" contract as /frame/advance, rather
-    than erroring. Used by the device's back-photo button."""
-    _touch_last_seen()
-    cfg = config.load()
-    _require_configured(cfg)
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    assets = _list_assets(client, cfg)
-
-    with config.locked():
-        cfg = config.load()  # re-read: state may have changed since the unlocked read above
-        photo_queue.back_forced(cfg, assets)
-        config.save(cfg)
-
-    return Response(content=_render_asset(client, cfg, cfg.current_asset_id), media_type="application/octet-stream")
-
-
-class BatteryReport(BaseModel):
-    percent: int
-
-
-@app.post("/frame/battery", dependencies=[Depends(require_access_token)])
-def frame_battery(body: BatteryReport):
-    """Battery level reported by the device (only when running on battery
-    -- it stays silent on mains, where the charging voltage would read
-    misleadingly full). Stored with a timestamp plus a per-discharge-
-    cycle history that feeds the Device panel's "on battery for" and
-    "estimated remaining" numbers."""
-    if not 0 <= body.percent <= 100:
-        raise HTTPException(400, "percent must be 0-100")
-    now = time.time()
-    with config.locked():
-        cfg = config.load()
-        cfg.stats.battery_reports += 1
-        if cfg.battery_history and body.percent >= cfg.battery_history[-1][1] + RECHARGE_JUMP_PCT:
-            # Percent jumped up meaningfully -- the battery was recharged
-            # (or swapped). Start a fresh discharge cycle so runtime and
-            # discharge-rate estimates never span a charge.
-            cfg.battery_history = []
-            cfg.stats.recharge_cycles += 1
-        cfg.battery_history.append([now, body.percent])
-        cfg.battery_history = cfg.battery_history[-BATTERY_HISTORY_MAX:]
-        cfg.battery_log.append([now, body.percent])
-        cfg.battery_log = cfg.battery_log[-BATTERY_LOG_MAX:]
-        cfg.battery_percent = body.percent
-        cfg.battery_as_of = now
-        cfg.last_seen = now
-        config.save(cfg)
-    return {"status": "saved"}
-
-
-@app.post("/api/firmware", dependencies=[Depends(require_access_token)])
-def api_firmware_upload(file: UploadFile = File(...)):
-    """Uploads a firmware image for OTA. The version is parsed out of the
-    image itself (esp_app_desc_t) rather than trusted from a filename or
-    form field, and the project name is checked so an unrelated .bin
-    can't be pushed to the frame by mistake."""
-    data = file.file.read()
-    version = parse_app_version(data)
-    firmware_path().write_bytes(data)
-    with config.locked():
-        cfg = config.load()
-        cfg.firmware_available_version = version
-        config.save(cfg)
-    return {"status": "saved", "version": version, "size": len(data)}
-
-
-@app.get("/frame/firmware", dependencies=[Depends(require_access_token)])
-def frame_firmware():
-    """The uploaded OTA image, streamed to the device (esp_https_ota).
-    404 until something has been uploaded."""
-    _touch_last_seen()
-    path = firmware_path()
-    if not path.exists():
-        raise HTTPException(404, "No firmware uploaded")
-    return FileResponse(path, media_type="application/octet-stream")
-
-
-def _fetch_latest_release(cfg: config.FrameConfig) -> dict | None:
-    try:
-        return gitea_releases.fetch_latest_release(cfg.firmware_update_repo_url, cfg.firmware_update_token)
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not reach Gitea at {cfg.firmware_update_repo_url}: {e}") from e
-
-
-def _apply_gitea_update(cfg: config.FrameConfig) -> str:
-    """Downloads the configured Gitea repo's latest release asset for this
-    frame's board variant and stages it exactly like a manual
-    POST /api/firmware upload would. Network I/O happens before the lock
-    is taken, matching the load/mutate/save concurrency pattern used
-    elsewhere (see config.locked())."""
-    release = _fetch_latest_release(cfg)
-    if not release:
-        raise HTTPException(404, "No releases found in the configured Gitea repo")
-    asset_name = gitea_releases.asset_name_for_board(cfg.firmware_board_variant)
-    asset_url = release["assets"].get(asset_name)
-    if not asset_url:
-        raise HTTPException(404, f"Latest release has no '{asset_name}' asset")
-    try:
-        data = gitea_releases.download_asset(asset_url, cfg.firmware_update_token)
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not download '{asset_name}' from Gitea: {e}") from e
-    version = parse_app_version(data)  # same validation the manual upload path applies
-    firmware_path().write_bytes(data)
-    with config.locked():
-        cfg = config.load()
-        cfg.firmware_available_version = version
-        cfg.firmware_gitea_latest_version = version
-        cfg.firmware_update_checked_at = time.time()
-        config.save(cfg)
-    return version
-
-
-@app.get("/api/firmware/check", dependencies=[Depends(require_access_token)])
-def api_firmware_check():
-    """Throttled check of the configured Gitea repo's latest release
-    (gitea_releases.UPDATE_CHECK_INTERVAL_S) -- cheap, since it only reads
-    the release's tag name, not its binaries. If firmware_auto_update is
-    on and a newer version is found, applies it immediately; otherwise
-    just reports it so the web UI can offer the "Update frame" button."""
-    cfg = config.load()
-    if not cfg.firmware_update_repo_url:
-        return {"enabled": False}
-
-    now = time.time()
-    if now - cfg.firmware_update_checked_at >= gitea_releases.UPDATE_CHECK_INTERVAL_S:
-        # Deliberately not updated on failure (see below) -- checked_at only
-        # advances on a successful reach, so a Gitea outage gets retried
-        # every poll instead of waiting out the full throttle interval.
-        release = _fetch_latest_release(cfg)
-        with config.locked():
-            cfg = config.load()  # re-read: state may have changed since the unlocked read above
-            cfg.firmware_update_checked_at = now
-            if release:
-                cfg.firmware_gitea_latest_version = release["version"]
-            config.save(cfg)
-        cfg = config.load()
-
-    update_available = bool(
-        cfg.firmware_gitea_latest_version
-    ) and cfg.firmware_gitea_latest_version != cfg.firmware_available_version
-    if update_available and cfg.firmware_auto_update:
-        _apply_gitea_update(cfg)
-        cfg = config.load()
-        update_available = False
-
-    return {
-        "enabled": True,
-        "latest_version": cfg.firmware_gitea_latest_version or None,
-        "staged_version": cfg.firmware_available_version or None,
-        "update_available": update_available,
-    }
-
-
-@app.post("/api/firmware/apply-latest", dependencies=[Depends(require_access_token)])
-def api_firmware_apply_latest():
-    """The "Update frame" button: applies the latest Gitea release right
-    now, bypassing the check throttle -- this is an explicit user action,
-    not a background poll."""
-    cfg = config.load()
-    if not cfg.firmware_update_repo_url:
-        raise HTTPException(400, "No Gitea firmware repo configured")
-    version = _apply_gitea_update(cfg)
-    return {"status": "saved", "version": version}
-
-
-def _battery_estimate_s(cfg: config.FrameConfig) -> int | None:
-    """Linear remaining-time estimate from the current discharge cycle's
-    observed rate, or None when there's not enough signal to be honest
-    about (too little time observed, or too little drop -- a flat line
-    extrapolates to garbage)."""
-    hist = cfg.battery_history
-    if len(hist) < 2:
-        return None
-    first_ts, first_pct = hist[0]
-    last_ts, last_pct = hist[-1]
-    span = last_ts - first_ts
-    drop = first_pct - last_pct
-    if span < MIN_ESTIMATE_SPAN_S or drop < MIN_ESTIMATE_DROP_PCT:
-        return None
-    rate = drop / span  # percent per second
-    return int(last_pct / rate)
-
-
-LOCATION_LINE_MAX_LEN = 14
-
-US_STATE_ABBR = {
-    "alabama": "AL", "alaska": "AK", "arizona": "AZ", "arkansas": "AR", "california": "CA",
-    "colorado": "CO", "connecticut": "CT", "delaware": "DE", "florida": "FL", "georgia": "GA",
-    "hawaii": "HI", "idaho": "ID", "illinois": "IL", "indiana": "IN", "iowa": "IA",
-    "kansas": "KS", "kentucky": "KY", "louisiana": "LA", "maine": "ME", "maryland": "MD",
-    "massachusetts": "MA", "michigan": "MI", "minnesota": "MN", "mississippi": "MS", "missouri": "MO",
-    "montana": "MT", "nebraska": "NE", "nevada": "NV", "new hampshire": "NH", "new jersey": "NJ",
-    "new mexico": "NM", "new york": "NY", "north carolina": "NC", "north dakota": "ND", "ohio": "OH",
-    "oklahoma": "OK", "oregon": "OR", "pennsylvania": "PA", "rhode island": "RI", "south carolina": "SC",
-    "south dakota": "SD", "tennessee": "TN", "texas": "TX", "utah": "UT", "vermont": "VT",
-    "virginia": "VA", "washington": "WA", "west virginia": "WV", "wisconsin": "WI", "wyoming": "WY",
-    "district of columbia": "DC",
-}
-
-CA_PROVINCE_ABBR = {
-    "alberta": "AB", "british columbia": "BC", "manitoba": "MB", "new brunswick": "NB",
-    "newfoundland and labrador": "NL", "northwest territories": "NT", "nova scotia": "NS",
-    "nunavut": "NU", "ontario": "ON", "prince edward island": "PE", "quebec": "QC",
-    "saskatchewan": "SK", "yukon": "YT",
-}
-
-US_COUNTRY_NAMES = {"united states", "united states of america", "usa", "us"}
-CA_COUNTRY_NAMES = {"canada"}
-
-
-def _truncate(text: str, max_len: int) -> str:
-    if len(text) <= max_len:
-        return text
-    return text[: max_len - 3] + "..."
-
-
-def _format_location(exif: dict) -> tuple[str, str] | None:
-    """Returns (city_line, region_line), each independently truncated to
-    fit its own corner-overlay line, or None if Immich hasn't geocoded
-    this photo. region_line is the abbreviated state/province for US/CAN
-    locations (e.g. "CA", "ON"), else the full country name."""
-    city = exif.get("city")
-    if not city:
-        return None
-
-    state = exif.get("state")
-    country = exif.get("country")
-    country_key = (country or "").strip().lower()
-
-    if state and country_key in US_COUNTRY_NAMES:
-        region = US_STATE_ABBR.get(state.strip().lower(), state)
-    elif state and country_key in CA_COUNTRY_NAMES:
-        region = CA_PROVINCE_ABBR.get(state.strip().lower(), state)
-    elif country:
-        region = country
-    elif state:
-        region = state
-    else:
-        region = ""
-
-    return _truncate(city, LOCATION_LINE_MAX_LEN), _truncate(region, LOCATION_LINE_MAX_LEN)
-
-
-def _format_taken_at(exif: dict) -> str | None:
-    raw = exif.get("dateTimeOriginal")
-    if not raw:
-        return None
-    try:
-        return datetime.fromisoformat(raw.replace("Z", "+00:00")).strftime("%m/%d/%y")
-    except ValueError:
-        return None
-
-
-@app.get("/frame/photo-info", dependencies=[Depends(require_access_token)])
-def frame_photo_info():
-    """Location/date-taken text for the manage-button overlay, plus the
-    asset id used to build the share-QR's target URL. Read-only, same
-    idempotent current-photo semantics as /frame/image -- doesn't advance
-    anything."""
-    _touch_last_seen()
-    cfg = config.load()
-    _require_configured(cfg)
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    assets = _list_assets(client, cfg)
-
-    with config.locked():
-        cfg = config.load()  # re-read: state may have changed since the unlocked read above
-        if photo_queue.get_current(cfg, assets, in_quiet_hours=_in_quiet_hours(cfg)):
-            config.save(cfg)
-
-    if not cfg.current_asset_id:
-        raise HTTPException(404, "No current photo")
-
-    try:
-        asset = client.get_asset(cfg.current_asset_id)
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not reach Immich: {e}") from e
-
-    exif = asset.get("exifInfo") or {}
-    location = _format_location(exif)
-    return {
-        "asset_id": cfg.current_asset_id,
-        "location_line1": location[0] if location else None,
-        "location_line2": location[1] if location and location[1] else None,
-        "taken_at": _format_taken_at(exif),
-    }
-
-
-@app.get("/frame/share/{asset_id}", dependencies=[Depends(require_access_token)])
-def frame_share(asset_id: str):
-    """Creates a 30-minute public Immich share link for asset_id and
-    redirects to it -- what the manage overlay's bottom-left QR code
-    points to (the firmware bakes ?token= into that QR the same way it
-    does for the management QR, see frame_client.c's build_url()). The
-    link is created lazily, when this actually gets hit (i.e. when
-    someone scans it), not when the manage button was pressed, so the
-    30-minute window starts when it's actually used. Also scoped to the
-    photo currently showing or queued -- not any arbitrary Immich asset
-    id -- as a second layer even a leaked token wouldn't bypass."""
-    _touch_last_seen()
-    cfg = config.load()
-    _require_configured(cfg)
-
-    if asset_id != cfg.current_asset_id and asset_id not in cfg.queue:
-        raise HTTPException(404, "That photo isn't currently showing or queued on this frame")
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    try:
-        share_url = client.create_share_link(asset_id, expires_in_s=1800)
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not create share link: {e}") from e
-
-    return RedirectResponse(share_url)
-
-
-@app.get("/frame/face-labels", dependencies=[Depends(require_access_token)])
-def frame_face_labels():
-    """Named-face positions for the manage button's escalated "level 2"
-    menu -- who's in the current photo, per Immich's own face
-    recognition (no detection/recognition happens here, see
-    app/face_labels.py). Response is a flattened, fixed-slot shape
-    (name_0/x_0/y_0, name_1/x_1/y_1, ...) rather than a JSON array, so
-    the device's hand-rolled parser can read it with the same flat-
-    scalar helpers it already has, instead of needing a real array
-    parser. Empty (count: 0) if no faces are named, or if anything about
-    fetching them fails -- this is a "nice to have" addition to the
-    overlay, not worth failing the whole menu over."""
-    _touch_last_seen()
-    cfg = config.load()
-    _require_configured(cfg)
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    assets = _list_assets(client, cfg)
-
-    with config.locked():
-        cfg = config.load()  # re-read: state may have changed since the unlocked read above
-        if photo_queue.get_current(cfg, assets, in_quiet_hours=_in_quiet_hours(cfg)):
-            config.save(cfg)
-
-    if not cfg.current_asset_id:
-        return {"count": 0}
-
-    try:
-        faces = client.get_asset_faces(cfg.current_asset_id)
-    except httpx.HTTPError as e:
-        logger.warning("Could not fetch faces for asset %s: %s", cfg.current_asset_id, e)
-        return {"count": 0}
-
-    if not any((face.get("person") or {}).get("name") for face in faces):
-        return {"count": 0}  # skip the extra preview download in the common no-named-faces case
-
-    try:
-        preview_bytes = client.download_asset_preview(cfg.current_asset_id)
-    except httpx.HTTPError as e:
-        logger.warning("Could not download asset %s for face-label mapping: %s", cfg.current_asset_id, e)
-        return {"count": 0}
-
-    labels = compute_face_labels(preview_bytes, faces, cfg.smart_crop_faces, cfg.orientation)
-
-    result: dict[str, object] = {"count": len(labels)}
-    for i, label in enumerate(labels):
-        result[f"name_{i}"] = label["name"]
-        result[f"x_{i}"] = label["x"]
-        result[f"y_{i}"] = label["y"]
-    return result
-
-
-@app.get("/api/queue", dependencies=[Depends(require_access_token)])
-def api_queue():
-    cfg = config.load()
-    _require_configured(cfg)
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    assets = _list_assets(client, cfg)
-
-    with config.locked():
-        cfg = config.load()  # re-read: state may have changed since the unlocked read above
-        current_changed = photo_queue.get_current(cfg, assets, in_quiet_hours=_in_quiet_hours(cfg))
-        queue_before = list(cfg.queue)
-        photo_queue.sync_queue_length(cfg, assets)
-        if current_changed or cfg.queue != queue_before:
-            config.save(cfg)
-
-    def entry(asset_id: str) -> dict:
-        return {"id": asset_id, "thumbnail_url": f"/api/photo-thumbnail/{asset_id}"}
-
-    now = time.time()
-    return {
-        "current": entry(cfg.current_asset_id) if cfg.current_asset_id else None,
-        "upcoming": [entry(asset_id) for asset_id in cfg.queue],
-        "device": {
-            "last_seen": cfg.last_seen or None,
-            "overdue": bool(cfg.last_seen and now - cfg.last_seen > _max_expected_gap_s(cfg) * OVERDUE_FACTOR),
-            "firmware_version": cfg.device_firmware_version or None,
-            "firmware_available": cfg.firmware_available_version or None,
-            "battery": (
-                {"percent": cfg.battery_percent, "as_of": cfg.battery_as_of}
-                if cfg.battery_percent >= 0
-                else None
-            ),
-            "on_battery_since": cfg.battery_history[0][0] if cfg.battery_history else None,
-            "battery_estimate_s": _battery_estimate_s(cfg),
-        },
-    }
-
-
-@app.get("/api/battery-log", dependencies=[Depends(require_access_token)])
-def api_battery_log():
-    cfg = config.load()
-    return {"log": cfg.battery_log}
-
-
-class QueueReorderRequest(BaseModel):
-    queue: list[str]
-
-
-@app.post("/api/queue/reorder", dependencies=[Depends(require_access_token)])
-def api_queue_reorder(body: QueueReorderRequest):
-    """Applies the client's requested order, tolerating drift between the
-    browser's last-fetched snapshot and the server's current queue (e.g.
-    a top-up/trim landed in between) instead of hard-rejecting: any ID
-    the client sent that's no longer actually queued is dropped, and any
-    ID the server has that the client didn't know about is appended
-    rather than lost."""
-    with config.locked():
-        cfg = config.load()
-        current_set = set(cfg.queue)
-        reordered = [asset_id for asset_id in body.queue if asset_id in current_set]
-        reordered += [asset_id for asset_id in cfg.queue if asset_id not in set(reordered)]
-        cfg.queue = reordered
-        config.save(cfg)
-    return {"status": "saved"}
-
-
-class QueuePromoteRequest(BaseModel):
-    asset_id: str
-
-
-@app.post("/api/queue/promote", dependencies=[Depends(require_access_token)])
-def api_queue_promote(body: QueuePromoteRequest):
-    """Moves a single photo to the front of the queue -- "Show next" in
-    the web UI. Unlike /api/queue/reorder, this doesn't depend on the
-    client supplying a full, exactly-current snapshot of the queue at
-    all, so it can't fail due to the queue having shifted server-side
-    since the browser's last fetch."""
-    with config.locked():
-        cfg = config.load()
-        if body.asset_id not in cfg.queue:
-            raise HTTPException(400, "That photo is no longer in the upcoming queue")
-        cfg.queue = [body.asset_id] + [asset_id for asset_id in cfg.queue if asset_id != body.asset_id]
-        config.save(cfg)
-    return {"status": "saved"}
-
-
-class QueueRemoveRequest(BaseModel):
-    asset_id: str
-
-
-@app.post("/api/queue/remove", dependencies=[Depends(require_access_token)])
-def api_queue_remove(body: QueueRemoveRequest):
-    """Permanently removes a photo from this frame's rotation -- "Remove"
-    in the web UI, on either an upcoming card or the current photo. Does
-    NOT touch Immich or the album itself; see photo_queue.remove_from_rotation()."""
-    cfg = config.load()
-    _require_configured(cfg)
-
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    assets = _list_assets(client, cfg)
-
-    with config.locked():
-        cfg = config.load()  # re-read: state may have changed since the unlocked read above
-        photo_queue.remove_from_rotation(cfg, assets, body.asset_id)
-        config.save(cfg)
-    return {"status": "removed"}
-
-
-@app.get("/api/photo-thumbnail/{asset_id}", dependencies=[Depends(require_access_token)])
-def api_photo_thumbnail(asset_id: str):
-    cfg = config.load()
-    _require_configured(cfg)
-    client = ImmichClient(cfg.immich_url, cfg.immich_api_key)
-    try:
-        content, content_type = client.download_asset_thumbnail(asset_id)
-    except httpx.HTTPError as e:
-        raise HTTPException(502, f"Could not download thumbnail from Immich: {e}") from e
-    return Response(content=content, media_type=content_type)
+    """Routing hub: manage-QR scans go to the limited manage page, users
+    land on their first frame (or an empty-state page), and everyone
+    else is walked through setup/login."""
+    with SessionLocal() as db:
+        have_users = users_exist(db)
+        manage_redirect = _device_credential_redirect(request, db, allow_legacy=have_users)
+        if manage_redirect is not None:
+            return RedirectResponse(manage_redirect, status_code=303)
+
+        user = current_user(request, db)
+        if user is None:
+            if not have_users:
+                if management_token() and not browser_token_valid(request):
+                    supplied = request.query_params.get("token")
+                    return templates.TemplateResponse(
+                        "token_prompt.html", {"request": request, "wrong": supplied is not None}
+                    )
+                # Pre-setup: reachable (optionally token-gated), nudge setup.
+                return RedirectResponse("/setup", status_code=303)
+            return RedirectResponse("/login", status_code=303)
+
+        frames = user_frames(db, user)
+        if frames:
+            return RedirectResponse(f"/frames/{frames[0].id}", status_code=303)
+        return templates.TemplateResponse("frames_empty.html", shell_context(request, db, user))

server/app/migration.py

@@ -0,0 +1,146 @@
+"""Schema versioning + one-time import of a legacy config.json deployment.
+
+Hand-rolled on purpose (vs alembic): single worker, single SQLite file,
+~30 lines of runner. Each migration is (version, fn(connection)); v1 is
+just create_all. DDL stays dialect-neutral so a future move to Postgres
+is a DATABASE_URL change, not a rewrite.
+
+Run at import time from main.py, before any request is served.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+import shutil
+import time
+
+from sqlalchemy import select, text
+
+from . import config
+from .db import SessionLocal, engine
+from .models import Base, BatteryLog, Frame
+
+logger = logging.getLogger(__name__)
+
+
+def _migration_1(conn) -> None:
+    Base.metadata.create_all(bind=conn)
+
+
+MIGRATIONS = [
+    (1, _migration_1),
+]
+
+
+def run_migrations() -> None:
+    with engine.begin() as conn:
+        conn.execute(text("CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL)"))
+        row = conn.execute(text("SELECT version FROM schema_version")).fetchone()
+        current = row[0] if row else 0
+        for version, fn in MIGRATIONS:
+            if version > current:
+                logger.info("Applying schema migration %d", version)
+                fn(conn)
+                if row is None:
+                    conn.execute(
+                        text("INSERT INTO schema_version (version) VALUES (:v)"), {"v": version}
+                    )
+                    row = (version,)
+                else:
+                    conn.execute(text("UPDATE schema_version SET version = :v"), {"v": version})
+    _ensure_frame_one()
+
+
+def new_device_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def new_manage_token() -> str:
+    return secrets.token_urlsafe(16)
+
+
+def _ensure_frame_one() -> None:
+    """First boot only (frames table empty): create frame #1 -- imported
+    verbatim from a legacy config.json if one exists, otherwise fresh
+    defaults. Either way it's the legacy-token frame: the deployed
+    firmware sends no device id and (at most) the shared MANAGEMENT_TOKEN,
+    and require_device resolves those requests here. The frames-nonempty
+    guard makes this idempotent; config.json is left untouched as the
+    rollback path."""
+    with SessionLocal() as db:
+        if db.scalars(select(Frame).limit(1)).first() is not None:
+            return
+
+        cfg = config.load()  # all defaults if the file doesn't exist
+        had_file = config.CONFIG_PATH.exists()
+
+        frame = Frame(
+            name="Frame 1",
+            device_id=None,
+            device_token=new_device_token(),
+            manage_token=new_manage_token(),
+            legacy_token_enabled=True,
+            created_at=time.time(),
+            immich_url=cfg.immich_url,
+            immich_api_key=cfg.immich_api_key,
+            album_id=cfg.album_id,
+            order=cfg.order,
+            refresh_interval_s=cfg.refresh_interval_s,
+            quiet_hours_enabled=cfg.quiet_hours_enabled,
+            quiet_hours_start=cfg.quiet_hours_start,
+            quiet_hours_end=cfg.quiet_hours_end,
+            timezone=cfg.timezone,
+            smart_crop_faces=cfg.smart_crop_faces,
+            orientation=cfg.orientation,
+            queue_target_len=cfg.queue_target_len,
+            current_asset_id=cfg.current_asset_id,
+            current_asset_set_at=cfg.current_asset_set_at,
+            queue=list(cfg.queue),
+            queue_cursor=cfg.queue_cursor,
+            history=list(cfg.history),
+            excluded_asset_ids=list(cfg.excluded_asset_ids),
+            battery_percent=cfg.battery_percent,
+            battery_as_of=cfg.battery_as_of,
+            battery_history=[list(pair) for pair in cfg.battery_history],
+            last_seen=cfg.last_seen,
+            device_firmware_version=cfg.device_firmware_version,
+            device_board_variant=cfg.device_board_variant,
+            firmware_available_version=cfg.firmware_available_version,
+            firmware_update_repo_url=cfg.firmware_update_repo_url,
+            firmware_auto_update=cfg.firmware_auto_update,
+            firmware_update_token=cfg.firmware_update_token,
+            firmware_update_checked_at=cfg.firmware_update_checked_at,
+            firmware_gitea_latest_version=cfg.firmware_gitea_latest_version,
+            stats_first_seen=cfg.stats.first_seen,
+            stats_device_wakes=cfg.stats.device_wakes,
+            stats_photos_displayed=cfg.stats.photos_displayed,
+            stats_photos_removed=cfg.stats.photos_removed,
+            stats_battery_reports=cfg.stats.battery_reports,
+            stats_recharge_cycles=cfg.stats.recharge_cycles,
+            stats_ota_updates_applied=cfg.stats.ota_updates_applied,
+            stats_config_saves=cfg.stats.config_saves,
+        )
+        db.add(frame)
+        db.flush()  # assign frame.id for the battery log rows
+
+        for pair in cfg.battery_log:
+            db.add(BatteryLog(frame_id=frame.id, ts=pair[0], percent=pair[1]))
+
+        db.commit()
+
+        # The single legacy firmware slot becomes frame #1's per-frame slot.
+        legacy_bin = config.CONFIG_PATH.parent / "firmware.bin"
+        if legacy_bin.exists():
+            per_frame_dir = config.CONFIG_PATH.parent / "firmware"
+            per_frame_dir.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(legacy_bin, per_frame_dir / f"{frame.id}.bin")
+
+        if had_file:
+            logger.info(
+                "Imported legacy config.json as frame #%d (%d battery log entries)",
+                frame.id,
+                len(cfg.battery_log),
+            )
+        else:
+            logger.info("Fresh install: created default frame #%d", frame.id)

server/app/models.py

@@ -0,0 +1,205 @@
+"""SQLAlchemy models: users, sessions, frames, links, claims, battery log.
+
+One deliberately WIDE `frames` row per frame (settings + state + telemetry
++ stats together): every device request touches exactly one row, so the
+per-frame lock in db.frame_locked() keeps the old whole-config-lock
+semantics trivially correct, and SQLite doesn't care about row width.
+
+The queue/history/excluded/battery_history columns are MutableList-mapped
+JSON: photo_queue.py mutates them in place (pop/append/insert), which a
+plain JSON column would silently not persist -- MutableList marks the row
+dirty on in-place changes.
+
+The ORM attribute for the photo ordering setting is `order` (matching the
+old FrameConfig field name so photo_queue.py ports unchanged) but the
+column is named photo_order to stay clear of the SQL keyword.
+"""
+
+from __future__ import annotations
+
+import time
+
+from sqlalchemy import JSON, Boolean, Float, ForeignKey, Index, Integer, String
+from sqlalchemy.ext.mutable import MutableList
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    # Normalized to lowercase in code before insert/lookup -- portable
+    # case-insensitive uniqueness without SQLite-only COLLATE NOCASE.
+    username: Mapped[str] = mapped_column(String, unique=True)
+    display_name: Mapped[str] = mapped_column(String, default="")
+    # Pluggable identity: "local" now; an OIDC provider later would set
+    # provider_subject and leave password_hash NULL.
+    identity_provider: Mapped[str] = mapped_column(String, default="local")
+    provider_subject: Mapped[str] = mapped_column(String, default="")
+    password_hash: Mapped[str | None] = mapped_column(String, nullable=True)
+    is_admin: Mapped[bool] = mapped_column(Boolean, default=False)
+    immich_url: Mapped[str] = mapped_column(String, default="")
+    immich_api_key: Mapped[str] = mapped_column(String, default="")
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+
+    __table_args__ = (
+        Index(
+            "ix_users_provider_subject",
+            "identity_provider",
+            "provider_subject",
+            unique=True,
+            sqlite_where=provider_subject != "",
+        ),
+    )
+
+
+class UserSession(Base):
+    __tablename__ = "sessions"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    token_hash: Mapped[str] = mapped_column(String, unique=True)  # sha256 hex of cookie value
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    csrf_token: Mapped[str] = mapped_column(String)
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+    expires_at: Mapped[float] = mapped_column(Float, index=True)
+
+    user: Mapped[User] = relationship()
+
+
+class Frame(Base):
+    __tablename__ = "frames"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    # 12 lowercase hex chars of the device's full STA MAC. NULL only for
+    # the migrated legacy frame until its device first reports an id.
+    device_id: Mapped[str | None] = mapped_column(String, unique=True, nullable=True)
+    name: Mapped[str] = mapped_column(String, default="")
+    # Renderer dispatch seam for future calendar/canva modes -- only
+    # "photos" is registered today (see routers/device.py RENDERERS).
+    mode: Mapped[str] = mapped_column(String, default="photos")
+    # Whose Immich library this frame pulls from; NULL = unclaimed.
+    owner_user_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    # "Take control" soft lock -- only this user may mutate settings/queue.
+    controlled_by_user_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    device_token: Mapped[str] = mapped_column(String)
+    # Device has authenticated with device_token at least once -- stop
+    # pushing it in /frame/config responses.
+    device_token_ack: Mapped[bool] = mapped_column(Boolean, default=False)
+    manage_token: Mapped[str] = mapped_column(String, unique=True)
+    # Migration window: this frame also accepts the legacy shared
+    # MANAGEMENT_TOKEN (and no-id requests resolve to it). Only ever the
+    # migrated frame #1; cleared from /admin once the device is on
+    # per-frame auth.
+    legacy_token_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
+    claimed_at: Mapped[float | None] = mapped_column(Float, nullable=True)
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+
+    # Migration staging only: Immich creds imported from the legacy
+    # config.json/env live here until /setup copies them to admin #1.
+    # Runtime resolution prefers owner creds, then env, then these (see
+    # routers/common.py immich_creds()).
+    immich_url: Mapped[str] = mapped_column(String, default="")
+    immich_api_key: Mapped[str] = mapped_column(String, default="")
+
+    # -- settings (attribute names match the old FrameConfig fields) --
+    album_id: Mapped[str] = mapped_column(String, default="")
+    order: Mapped[str] = mapped_column("photo_order", String, default="sequential")
+    refresh_interval_s: Mapped[int] = mapped_column(Integer, default=3600)
+    quiet_hours_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
+    quiet_hours_start: Mapped[str] = mapped_column(String, default="22:00")
+    quiet_hours_end: Mapped[str] = mapped_column(String, default="07:00")
+    timezone: Mapped[str] = mapped_column(String, default="UTC")
+    smart_crop_faces: Mapped[bool] = mapped_column(Boolean, default=True)
+    orientation: Mapped[str] = mapped_column(String, default="landscape")
+    queue_target_len: Mapped[int] = mapped_column(Integer, default=20)
+
+    # -- state --
+    current_asset_id: Mapped[str] = mapped_column(String, default="")
+    current_asset_set_at: Mapped[float] = mapped_column(Float, default=0.0)
+    queue: Mapped[list] = mapped_column(MutableList.as_mutable(JSON), default=list)
+    queue_cursor: Mapped[int] = mapped_column(Integer, default=0)
+    history: Mapped[list] = mapped_column(MutableList.as_mutable(JSON), default=list)
+    excluded_asset_ids: Mapped[list] = mapped_column(MutableList.as_mutable(JSON), default=list)
+
+    # -- telemetry --
+    battery_percent: Mapped[int] = mapped_column(Integer, default=-1)
+    battery_as_of: Mapped[float] = mapped_column(Float, default=0.0)
+    # Current discharge cycle only (reset on recharge detection); the
+    # permanent record is the battery_log table.
+    battery_history: Mapped[list] = mapped_column(MutableList.as_mutable(JSON), default=list)
+    last_seen: Mapped[float] = mapped_column(Float, default=0.0)
+    device_firmware_version: Mapped[str] = mapped_column(String, default="")
+    device_board_variant: Mapped[str] = mapped_column(String, default="")
+
+    # -- firmware / OTA (per frame; image lives at /data/firmware/<id>.bin) --
+    firmware_available_version: Mapped[str] = mapped_column(String, default="")
+    firmware_update_repo_url: Mapped[str] = mapped_column(String, default="")
+    firmware_auto_update: Mapped[bool] = mapped_column(Boolean, default=False)
+    firmware_update_token: Mapped[str] = mapped_column(String, default="")
+    firmware_update_checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    firmware_gitea_latest_version: Mapped[str] = mapped_column(String, default="")
+
+    # -- stats (flattened from the old nested FrameStats) --
+    stats_first_seen: Mapped[float] = mapped_column(Float, default=0.0)
+    stats_device_wakes: Mapped[int] = mapped_column(Integer, default=0)
+    stats_photos_displayed: Mapped[int] = mapped_column(Integer, default=0)
+    stats_photos_removed: Mapped[int] = mapped_column(Integer, default=0)
+    stats_battery_reports: Mapped[int] = mapped_column(Integer, default=0)
+    stats_recharge_cycles: Mapped[int] = mapped_column(Integer, default=0)
+    stats_ota_updates_applied: Mapped[int] = mapped_column(Integer, default=0)
+    stats_config_saves: Mapped[int] = mapped_column(Integer, default=0)
+
+    owner: Mapped[User | None] = relationship(foreign_keys=[owner_user_id])
+    controlled_by: Mapped[User | None] = relationship(foreign_keys=[controlled_by_user_id])
+
+
+class UserFrame(Base):
+    """A user linked to a frame: sees it in their sidebar, may view its
+    pages, and may take control. Ownership (whose Immich creds the frame
+    renders from) is frames.owner_user_id, separate from linking."""
+
+    __tablename__ = "user_frames"
+
+    user_id: Mapped[int] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), primary_key=True
+    )
+    frame_id: Mapped[int] = mapped_column(
+        ForeignKey("frames.id", ondelete="CASCADE"), primary_key=True
+    )
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+
+
+class PendingClaim(Base):
+    """A claim submitted before the frame's first check-in (the user beat
+    the device to the server after provisioning). Attached automatically
+    when a device with this id self-registers; expired rows are pruned
+    opportunistically."""
+
+    __tablename__ = "pending_claims"
+
+    device_id: Mapped[str] = mapped_column(String, primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+    expires_at: Mapped[float] = mapped_column(Float)
+
+
+class BatteryLog(Base):
+    """Every battery report ever, per frame -- the permanent record behind
+    the battery history chart (was a 20k-entry JSON array in config.json)."""
+
+    __tablename__ = "battery_log"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    frame_id: Mapped[int] = mapped_column(ForeignKey("frames.id", ondelete="CASCADE"))
+    ts: Mapped[float] = mapped_column(Float)
+    percent: Mapped[int] = mapped_column(Integer)
+
+    __table_args__ = (Index("ix_battery_log_frame_ts", "frame_id", "ts"),)

server/app/photo_queue.py

@@ -34,12 +34,12 @@ from __future__ import annotations
 import random
 import time
 
-from .config import FrameConfig
+from .models import Frame
 
 HISTORY_MAX_LEN = 20
 
 
-def _top_up(cfg: FrameConfig, assets: list[dict]) -> None:
+def _top_up(cfg: Frame, assets: list[dict]) -> None:
     valid_ids = {a["id"] for a in assets}
     excluded_ids = set(cfg.excluded_asset_ids)
     cfg.queue = [asset_id for asset_id in cfg.queue if asset_id in valid_ids and asset_id not in excluded_ids]
@@ -85,7 +85,7 @@ def _top_up(cfg: FrameConfig, assets: list[dict]) -> None:
     cfg.queue_cursor = (cfg.queue_cursor + i + 1) % n
 
 
-def advance_forced(cfg: FrameConfig, assets: list[dict]) -> None:
+def advance_forced(cfg: Frame, assets: list[dict]) -> None:
     """Unconditionally moves to the next photo, ignoring elapsed time, and
     resets the interval clock from now. Used by the explicit next-photo
     action (POST /frame/advance) and by get_current() once the refresh
@@ -105,7 +105,7 @@ def advance_forced(cfg: FrameConfig, assets: list[dict]) -> None:
         # only asset is already current) -- keep showing what we have.
         cfg.current_asset_id = assets[0]["id"]
     cfg.current_asset_set_at = time.time()
-    cfg.stats.photos_displayed += 1
+    cfg.stats_photos_displayed += 1
     # Refill back up to queue_target_len now that current_asset_id has
     # changed -- otherwise the queue is left one short until the *next*
     # advance, since the pop above consumes one of the items _top_up just
@@ -113,7 +113,7 @@ def advance_forced(cfg: FrameConfig, assets: list[dict]) -> None:
     _top_up(cfg, assets)
 
 
-def back_forced(cfg: FrameConfig, assets: list[dict]) -> bool:
+def back_forced(cfg: Frame, assets: list[dict]) -> bool:
     """Unconditionally moves to the previously-current photo, the mirror
     image of advance_forced() -- pops the most recent entry off history,
     pushes the photo it's replacing onto the front of queue (so pressing
@@ -132,12 +132,12 @@ def back_forced(cfg: FrameConfig, assets: list[dict]) -> bool:
             cfg.queue.insert(0, cfg.current_asset_id)
         cfg.current_asset_id = previous_id
         cfg.current_asset_set_at = time.time()
-        cfg.stats.photos_displayed += 1
+        cfg.stats_photos_displayed += 1
         return True
     return False
 
 
-def remove_from_rotation(cfg: FrameConfig, assets: list[dict], asset_id: str) -> bool:
+def remove_from_rotation(cfg: Frame, assets: list[dict], asset_id: str) -> bool:
     """Permanently excludes asset_id from this frame's rotation (see the
     module docstring) -- doesn't touch Immich, just this frame's own
     selection. Scrubs it out of queue and history too, so it can't
@@ -149,7 +149,7 @@ def remove_from_rotation(cfg: FrameConfig, assets: list[dict], asset_id: str) ->
     changed as a result."""
     if asset_id not in cfg.excluded_asset_ids:
         cfg.excluded_asset_ids.append(asset_id)
-        cfg.stats.photos_removed += 1
+        cfg.stats_photos_removed += 1
     cfg.queue = [a for a in cfg.queue if a != asset_id]
     cfg.history = [a for a in cfg.history if a != asset_id]
 
@@ -167,12 +167,12 @@ def remove_from_rotation(cfg: FrameConfig, assets: list[dict], asset_id: str) ->
         remaining = [a["id"] for a in assets if a["id"] not in excluded_ids]
         cfg.current_asset_id = remaining[0] if remaining else ""
     cfg.current_asset_set_at = time.time()
-    cfg.stats.photos_displayed += 1
+    cfg.stats_photos_displayed += 1
     _top_up(cfg, assets)
     return True
 
 
-def sync_queue_length(cfg: FrameConfig, assets: list[dict]) -> None:
+def sync_queue_length(cfg: Frame, assets: list[dict]) -> None:
     """Tops up or trims cfg.queue to match cfg.queue_target_len without
     otherwise touching current_asset_id. Used by GET /api/queue so a
     change to the "upcoming photos to show" setting takes effect on page
@@ -180,7 +180,7 @@ def sync_queue_length(cfg: FrameConfig, assets: list[dict]) -> None:
     _top_up(cfg, assets)
 
 
-def get_current(cfg: FrameConfig, assets: list[dict], in_quiet_hours: bool = False) -> bool:
+def get_current(cfg: Frame, assets: list[dict], in_quiet_hours: bool = False) -> bool:
     """Time-based, idempotent path used by GET /frame/image. Advances only
     if the current photo is unset/invalid or refresh_interval_s has
     elapsed since it was set. Returns whether it changed anything, so the

server/app/quiet_hours.py

@@ -0,0 +1,117 @@
+"""Quiet-hours math, extracted verbatim from the old main.py. Everything
+takes the frame-like object duck-typed on quiet_hours_enabled/start/end,
+timezone, and refresh_interval_s -- both the old FrameConfig and the
+Frame ORM model satisfy it."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo, available_timezones
+
+# Populated once from the OS's zoneinfo database (installed via the
+# `tzdata` apt package in the Dockerfile) and offered as a <select> in the
+# web UI's "Timezone" field.
+ALL_TIMEZONES = sorted(available_timezones())
+
+
+def valid_hhmm(s: str) -> bool:
+    try:
+        datetime.strptime(s, "%H:%M")
+        return True
+    except ValueError:
+        return False
+
+
+def _zoneinfo(name: str) -> ZoneInfo:
+    """Falls back to UTC for an unrecognized zone name -- defensive only;
+    the config-save route validates against ALL_TIMEZONES before saving,
+    so this only matters for state hand-edited or written by an older
+    version of this code."""
+    try:
+        return ZoneInfo(name)
+    except Exception:
+        return ZoneInfo("UTC")
+
+
+def _quiet_hours_state(now: datetime, start_str: str, end_str: str) -> tuple[bool, datetime | None]:
+    """Whether `now` falls inside the quiet-hours window, and the next
+    boundary: if inside, when it ends; if outside, when it next starts.
+    Handles a window that wraps past midnight (e.g. 22:00-07:00). Returns
+    (False, None) for a degenerate window (start == end)."""
+    sh, sm = (int(x) for x in start_str.split(":"))
+    eh, em = (int(x) for x in end_str.split(":"))
+    start = now.replace(hour=sh, minute=sm, second=0, microsecond=0)
+    end = now.replace(hour=eh, minute=em, second=0, microsecond=0)
+
+    if start == end:
+        return False, None
+
+    if start < end:
+        # Same-day window, e.g. 13:00-15:00. End is exclusive, so being
+        # exactly at `end` counts as already outside the window.
+        if start <= now < end:
+            return True, end
+        if now < start:
+            return False, start
+        return False, start + timedelta(days=1)
+
+    # Wraps midnight, e.g. 22:00-07:00.
+    if now >= start:
+        return True, end + timedelta(days=1)
+    if now < end:
+        return True, end
+    return False, start
+
+
+def _quiet_hours_span_s(start_str: str, end_str: str) -> int:
+    """Duration of the quiet-hours window in seconds, wrap-aware."""
+    sh, sm = (int(x) for x in start_str.split(":"))
+    eh, em = (int(x) for x in end_str.split(":"))
+    span_min = ((eh * 60 + em) - (sh * 60 + sm)) % (24 * 60)
+    return span_min * 60
+
+
+def effective_refresh_interval_s(cfg) -> int:
+    """The refresh interval actually handed to the device: its configured
+    value, unless quiet hours are enabled, in which case it's clamped so
+    the device sleeps through the whole window instead of waking inside
+    it. A device already mid-sleep when quiet hours begin can still land
+    one wake inside the window (nothing server-side can prevent that
+    without touching the firmware) -- but from that wake on, it's told to
+    sleep exactly until the window ends."""
+    if not cfg.quiet_hours_enabled:
+        return cfg.refresh_interval_s
+    now = datetime.now(_zoneinfo(cfg.timezone))
+    in_quiet, boundary = _quiet_hours_state(now, cfg.quiet_hours_start, cfg.quiet_hours_end)
+    if boundary is None:
+        return cfg.refresh_interval_s
+    seconds_to_boundary = max(1, int((boundary - now).total_seconds()))
+    if in_quiet:
+        return seconds_to_boundary
+    return min(cfg.refresh_interval_s, seconds_to_boundary)
+
+
+def in_quiet_hours(cfg) -> bool:
+    """Whether quiet hours are in effect right now -- separate from
+    effective_refresh_interval_s, which only shapes what the *device* is
+    told to sleep for. This instead gates photo_queue.get_current()'s
+    time-based advance, since that check runs independent of the device
+    (also triggered by the web UI's queue endpoint, e.g. an open browser
+    tab polling overnight) and would otherwise happily advance the
+    current photo mid-quiet-hours on raw elapsed time alone."""
+    if not cfg.quiet_hours_enabled:
+        return False
+    now = datetime.now(_zoneinfo(cfg.timezone))
+    in_quiet, _ = _quiet_hours_state(now, cfg.quiet_hours_start, cfg.quiet_hours_end)
+    return in_quiet
+
+
+def max_expected_gap_s(cfg) -> int:
+    """Longest gap between wakes the device might legitimately have --
+    normally just refresh_interval_s, but quiet hours can make the real
+    gap much longer, and the "overdue" check shouldn't mistake a device
+    quietly sleeping through the night for a dead one."""
+    gap = cfg.refresh_interval_s
+    if cfg.quiet_hours_enabled:
+        gap = max(gap, _quiet_hours_span_s(cfg.quiet_hours_start, cfg.quiet_hours_end))
+    return gap

server/app/routers/api_frames.py

@@ -0,0 +1,410 @@
+"""The web UI's JSON API, namespaced per frame: /api/frames/{id}/...
+
+Auth: session-only (require_frame_view for reads, require_frame_control
+for mutations -- the "take control" soft lock). The limited manage-QR
+surface lives separately under /api/m/ (routers/manage.py), and device
+traffic under /frame/* (routers/device.py).
+
+Config saves are PARTIAL updates: each page's form posts only its own
+fields (the old single Settings form split across the Photos and
+Configuration tabs), so every field is optional and only provided ones
+are touched. Checkboxes are sent explicitly as "true"/"false" strings by
+the page JS -- an absent field means "not this form's field", never
+"unchecked".
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+import httpx
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import Response
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .. import gitea_releases, photo_queue, quiet_hours
+from ..auth import require_frame_control, require_frame_view, require_user_api
+from ..db import frame_locked, get_db
+from ..firmware import firmware_path, parse_app_version
+from ..models import BatteryLog, Frame
+from .common import (
+    OVERDUE_FACTOR,
+    battery_estimate_s,
+    immich_client_for,
+    immich_creds,
+    list_assets,
+    require_configured,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+MIN_REFRESH_INTERVAL_S = 60
+MAX_REFRESH_INTERVAL_S = 86400
+MIN_QUEUE_TARGET_LEN = 5
+MAX_QUEUE_TARGET_LEN = 5000
+
+ORIENTATIONS = ("landscape", "portrait", "landscape_flipped", "portrait_flipped")
+
+
+@router.get("/api/frames/{frame_id}/albums")
+def api_albums(frame: Frame = Depends(require_frame_view)):
+    url, key = immich_creds(frame)
+    if not url or not key:
+        raise HTTPException(400, "The frame owner hasn't set up their Immich connection yet (Settings)")
+    try:
+        albums = immich_client_for(frame).list_albums()
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not reach Immich at {url}: {e}") from e
+    return [{"id": a["id"], "name": a["albumName"], "count": a.get("assetCount", 0)} for a in albums]
+
+
+@router.post("/api/frames/{frame_id}/config")
+def api_config_save(
+    name: str | None = Form(None),
+    album_id: str | None = Form(None),
+    order: str | None = Form(None),
+    refresh_interval_s: int | None = Form(None),
+    smart_crop_faces: bool | None = Form(None),
+    queue_target_len: int | None = Form(None),
+    orientation: str | None = Form(None),
+    quiet_hours_enabled: bool | None = Form(None),
+    quiet_hours_start: str | None = Form(None),
+    quiet_hours_end: str | None = Form(None),
+    timezone: str | None = Form(None),
+    firmware_update_repo_url: str | None = Form(None),
+    firmware_auto_update: bool | None = Form(None),
+    frame: Frame = Depends(require_frame_control),
+    db: Session = Depends(get_db),
+):
+    with frame_locked(db, frame.id) as cfg:
+        if name is not None:
+            cfg.name = name.strip()[:64] or cfg.name
+        if album_id is not None and album_id != cfg.album_id:
+            # A newly selected album starts clean -- the old current photo
+            # and queue don't mean anything in the new album's context.
+            cfg.current_asset_id = ""
+            cfg.current_asset_set_at = 0.0
+            cfg.queue = []
+            cfg.queue_cursor = 0
+            cfg.history = []
+            cfg.excluded_asset_ids = []
+            cfg.album_id = album_id
+        if order is not None:
+            cfg.order = order if order in ("sequential", "shuffle") else "sequential"
+        if refresh_interval_s is not None:
+            cfg.refresh_interval_s = max(
+                MIN_REFRESH_INTERVAL_S, min(MAX_REFRESH_INTERVAL_S, refresh_interval_s)
+            )
+        if smart_crop_faces is not None:
+            cfg.smart_crop_faces = smart_crop_faces
+        if queue_target_len is not None:
+            cfg.queue_target_len = max(MIN_QUEUE_TARGET_LEN, min(MAX_QUEUE_TARGET_LEN, queue_target_len))
+        if orientation is not None:
+            cfg.orientation = orientation if orientation in ORIENTATIONS else "landscape"
+        if quiet_hours_enabled is not None:
+            cfg.quiet_hours_enabled = quiet_hours_enabled
+        if quiet_hours_start is not None and quiet_hours.valid_hhmm(quiet_hours_start):
+            cfg.quiet_hours_start = quiet_hours_start
+        if quiet_hours_end is not None and quiet_hours.valid_hhmm(quiet_hours_end):
+            cfg.quiet_hours_end = quiet_hours_end
+        if timezone is not None and timezone in quiet_hours.ALL_TIMEZONES:
+            cfg.timezone = timezone
+        if firmware_update_repo_url is not None:
+            cfg.firmware_update_repo_url = firmware_update_repo_url.strip()
+        if firmware_auto_update is not None:
+            cfg.firmware_auto_update = firmware_auto_update
+        cfg.stats_config_saves += 1
+    return {"status": "saved"}
+
+
+@router.post("/api/frames/{frame_id}/take-control")
+def api_take_control(
+    request: Request, frame: Frame = Depends(require_frame_view), db: Session = Depends(get_db)
+):
+    """Always succeeds for any linked user -- the lock is deliberately
+    soft. The previous holder just sees who has it now."""
+    user = require_user_api(request, db)
+    previous = frame.controlled_by
+    frame.controlled_by_user_id = user.id
+    db.commit()
+    logger.info("User '%s' took control of frame #%d (from %s)", user.username, frame.id,
+                previous.username if previous else "nobody")
+    return {"status": "saved", "controller": user.display_name or user.username}
+
+
+@router.get("/api/frames/{frame_id}/stats")
+def api_stats(frame: Frame = Depends(require_frame_view)):
+    return {
+        "first_seen": frame.stats_first_seen,
+        "device_wakes": frame.stats_device_wakes,
+        "photos_displayed": frame.stats_photos_displayed,
+        "photos_removed": frame.stats_photos_removed,
+        "battery_reports": frame.stats_battery_reports,
+        "recharge_cycles": frame.stats_recharge_cycles,
+        "ota_updates_applied": frame.stats_ota_updates_applied,
+        "config_saves": frame.stats_config_saves,
+    }
+
+
+@router.get("/api/frames/{frame_id}/queue")
+def api_queue(
+    request: Request, frame: Frame = Depends(require_frame_view), db: Session = Depends(get_db)
+):
+    user = require_user_api(request, db)
+    require_configured(frame)
+
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as cfg:
+        photo_queue.get_current(cfg, assets, in_quiet_hours=quiet_hours.in_quiet_hours(cfg))
+        photo_queue.sync_queue_length(cfg, assets)
+        snapshot = {
+            "current_asset_id": cfg.current_asset_id,
+            "queue": list(cfg.queue),
+            "last_seen": cfg.last_seen,
+            "overdue_gap": quiet_hours.max_expected_gap_s(cfg) * OVERDUE_FACTOR,
+            "firmware_version": cfg.device_firmware_version,
+            "firmware_available": cfg.firmware_available_version,
+            "battery_percent": cfg.battery_percent,
+            "battery_as_of": cfg.battery_as_of,
+            "on_battery_since": cfg.battery_history[0][0] if cfg.battery_history else None,
+            "battery_estimate_s": battery_estimate_s(cfg),
+            "controller_id": cfg.controlled_by_user_id,
+            "controller": (
+                (cfg.controlled_by.display_name or cfg.controlled_by.username)
+                if cfg.controlled_by
+                else None
+            ),
+        }
+
+    def entry(asset_id: str) -> dict:
+        return {"id": asset_id, "thumbnail_url": f"/api/frames/{frame.id}/thumbnail/{asset_id}"}
+
+    now = time.time()
+    return {
+        "current": entry(snapshot["current_asset_id"]) if snapshot["current_asset_id"] else None,
+        "upcoming": [entry(asset_id) for asset_id in snapshot["queue"]],
+        "control": {
+            "controller": snapshot["controller"],
+            "you": snapshot["controller_id"] == user.id,
+        },
+        "device": {
+            "last_seen": snapshot["last_seen"] or None,
+            "overdue": bool(
+                snapshot["last_seen"] and now - snapshot["last_seen"] > snapshot["overdue_gap"]
+            ),
+            "firmware_version": snapshot["firmware_version"] or None,
+            "firmware_available": snapshot["firmware_available"] or None,
+            "battery": (
+                {"percent": snapshot["battery_percent"], "as_of": snapshot["battery_as_of"]}
+                if snapshot["battery_percent"] >= 0
+                else None
+            ),
+            "on_battery_since": snapshot["on_battery_since"],
+            "battery_estimate_s": snapshot["battery_estimate_s"],
+        },
+    }
+
+
+@router.get("/api/frames/{frame_id}/battery-log")
+def api_battery_log(frame: Frame = Depends(require_frame_view), db: Session = Depends(get_db)):
+    rows = db.execute(
+        select(BatteryLog.ts, BatteryLog.percent)
+        .where(BatteryLog.frame_id == frame.id)
+        .order_by(BatteryLog.ts)
+    ).all()
+    return {"log": [[ts, percent] for ts, percent in rows]}
+
+
+class QueueReorderRequest(BaseModel):
+    queue: list[str]
+
+
+@router.post("/api/frames/{frame_id}/queue/reorder")
+def api_queue_reorder(
+    body: QueueReorderRequest,
+    frame: Frame = Depends(require_frame_control),
+    db: Session = Depends(get_db),
+):
+    """Applies the client's requested order, tolerating drift between the
+    browser's last-fetched snapshot and the server's current queue (e.g.
+    a top-up/trim landed in between) instead of hard-rejecting: any ID
+    the client sent that's no longer actually queued is dropped, and any
+    ID the server has that the client didn't know about is appended
+    rather than lost."""
+    with frame_locked(db, frame.id) as cfg:
+        current_set = set(cfg.queue)
+        reordered = [asset_id for asset_id in body.queue if asset_id in current_set]
+        reordered += [asset_id for asset_id in cfg.queue if asset_id not in set(reordered)]
+        cfg.queue = reordered
+    return {"status": "saved"}
+
+
+class QueuePromoteRequest(BaseModel):
+    asset_id: str
+
+
+@router.post("/api/frames/{frame_id}/queue/promote")
+def api_queue_promote(
+    body: QueuePromoteRequest,
+    frame: Frame = Depends(require_frame_control),
+    db: Session = Depends(get_db),
+):
+    """Moves a single photo to the front of the queue -- "Show next".
+    Unlike reorder, doesn't depend on the client knowing the queue's
+    exact current order, so it can't fail from staleness."""
+    with frame_locked(db, frame.id) as cfg:
+        if body.asset_id not in cfg.queue:
+            raise HTTPException(400, "That photo is no longer in the upcoming queue")
+        cfg.queue = [body.asset_id] + [asset_id for asset_id in cfg.queue if asset_id != body.asset_id]
+    return {"status": "saved"}
+
+
+class QueueRemoveRequest(BaseModel):
+    asset_id: str
+
+
+@router.post("/api/frames/{frame_id}/queue/remove")
+def api_queue_remove(
+    body: QueueRemoveRequest,
+    frame: Frame = Depends(require_frame_control),
+    db: Session = Depends(get_db),
+):
+    """Permanently removes a photo from this frame's rotation. Does NOT
+    touch Immich or the album itself; see photo_queue.remove_from_rotation()."""
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as cfg:
+        photo_queue.remove_from_rotation(cfg, assets, body.asset_id)
+    return {"status": "removed"}
+
+
+@router.get("/api/frames/{frame_id}/thumbnail/{asset_id}")
+def api_thumbnail(asset_id: str, frame: Frame = Depends(require_frame_view)):
+    require_configured(frame)
+    client = immich_client_for(frame)
+    try:
+        content, content_type = client.download_asset_thumbnail(asset_id)
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not download thumbnail from Immich: {e}") from e
+    return Response(content=content, media_type=content_type)
+
+
+@router.post("/api/frames/{frame_id}/firmware")
+def api_firmware_upload(
+    file: UploadFile = File(...),
+    frame: Frame = Depends(require_frame_control),
+    db: Session = Depends(get_db),
+):
+    """Uploads a firmware image for OTA. The version is parsed out of the
+    image itself (esp_app_desc_t) rather than trusted from a filename or
+    form field, and the project name is checked so an unrelated .bin
+    can't be pushed to the frame by mistake."""
+    data = file.file.read()
+    version = parse_app_version(data)
+    path = firmware_path(frame.id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    with frame_locked(db, frame.id) as cfg:
+        cfg.firmware_available_version = version
+    return {"status": "saved", "version": version, "size": len(data)}
+
+
+def _fetch_latest_release(frame: Frame) -> dict | None:
+    try:
+        return gitea_releases.fetch_latest_release(
+            frame.firmware_update_repo_url, frame.firmware_update_token
+        )
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not reach Gitea at {frame.firmware_update_repo_url}: {e}") from e
+
+
+def _apply_gitea_update(db: Session, frame: Frame) -> str:
+    """Downloads the configured Gitea repo's latest release asset for this
+    frame's board variant (learned from the device's X-Frame-Board
+    header, never picked by hand) and stages it exactly like a manual
+    upload. Network I/O happens before the lock is taken."""
+    if not frame.device_board_variant:
+        raise HTTPException(400, "The frame hasn't checked in yet -- can't tell which board's build to fetch")
+    release = _fetch_latest_release(frame)
+    if not release:
+        raise HTTPException(404, "No releases found in the configured Gitea repo")
+    asset_name = gitea_releases.asset_name_for_board(frame.device_board_variant)
+    asset_url = release["assets"].get(asset_name)
+    if not asset_url:
+        raise HTTPException(404, f"Latest release has no '{asset_name}' asset")
+    try:
+        data = gitea_releases.download_asset(asset_url, frame.firmware_update_token)
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not download '{asset_name}' from Gitea: {e}") from e
+    version = parse_app_version(data)  # same validation the manual upload path applies
+    path = firmware_path(frame.id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    with frame_locked(db, frame.id) as cfg:
+        cfg.firmware_available_version = version
+        cfg.firmware_gitea_latest_version = version
+        cfg.firmware_update_checked_at = time.time()
+    return version
+
+
+@router.get("/api/frames/{frame_id}/firmware/check")
+def api_firmware_check(
+    force: bool = False, frame: Frame = Depends(require_frame_view), db: Session = Depends(get_db)
+):
+    """Throttled check of the configured Gitea repo's latest release
+    (gitea_releases.UPDATE_CHECK_INTERVAL_S). If firmware_auto_update is
+    on and a newer version is found, applies it immediately; otherwise
+    just reports it so the UI can offer the "Update frame" button.
+    force=true (the "Check now" button) bypasses the throttle."""
+    if not frame.firmware_update_repo_url:
+        return {"enabled": False}
+
+    now = time.time()
+    if force or now - frame.firmware_update_checked_at >= gitea_releases.UPDATE_CHECK_INTERVAL_S:
+        # checked_at only advances on a successful reach, so a Gitea
+        # outage gets retried every poll instead of waiting out the full
+        # throttle interval.
+        release = _fetch_latest_release(frame)
+        with frame_locked(db, frame.id) as cfg:
+            cfg.firmware_update_checked_at = now
+            if release:
+                cfg.firmware_gitea_latest_version = release["version"]
+
+    update_available = (
+        bool(frame.firmware_gitea_latest_version)
+        and frame.firmware_gitea_latest_version != frame.firmware_available_version
+        and bool(frame.device_board_variant)
+    )
+    if update_available and frame.firmware_auto_update:
+        _apply_gitea_update(db, frame)
+        update_available = False
+
+    return {
+        "enabled": True,
+        "board": frame.device_board_variant or None,
+        "latest_version": frame.firmware_gitea_latest_version or None,
+        "staged_version": frame.firmware_available_version or None,
+        "update_available": update_available,
+    }
+
+
+@router.post("/api/frames/{frame_id}/firmware/apply-latest")
+def api_firmware_apply_latest(
+    frame: Frame = Depends(require_frame_control), db: Session = Depends(get_db)
+):
+    """The "Update frame" button: applies the latest Gitea release right
+    now, bypassing the check throttle -- an explicit user action, not a
+    background poll."""
+    if not frame.firmware_update_repo_url:
+        raise HTTPException(400, "No Gitea firmware repo configured")
+    version = _apply_gitea_update(db, frame)
+    return {"status": "saved", "version": version}

server/app/routers/common.py

@@ -0,0 +1,134 @@
+"""Helpers shared by the device and browser routers."""
+
+from __future__ import annotations
+
+import io
+import logging
+import os
+
+import httpx
+from fastapi import HTTPException
+from PIL import Image
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from ..image_pipeline import render_frame
+from ..immich_client import ImmichClient
+from ..models import Frame
+
+logger = logging.getLogger(__name__)
+
+# Battery-history / estimate tuning (see /frame/battery and battery_estimate_s).
+BATTERY_HISTORY_MAX = 500  # ~20 days at hourly reports
+BATTERY_LOG_MAX = 20000  # ~2 years at hourly reports -- cap on the battery_log table per frame
+RECHARGE_JUMP_PCT = 5  # a report this much above the previous one = battery was recharged
+MIN_ESTIMATE_SPAN_S = 2 * 3600  # need at least this much observed time...
+MIN_ESTIMATE_DROP_PCT = 2  # ...and this much observed drop before estimating
+
+# "Overdue" threshold multiplier: the device should check in roughly every
+# refresh_interval_s; give it half again as long before flagging it.
+OVERDUE_FACTOR = 1.5
+
+
+def immich_creds(frame: Frame) -> tuple[str, str]:
+    """Which Immich this frame renders from. Owner's creds once the frame
+    is claimed (Phase B+); env vars as the operator-level fallback (the
+    pre-redesign source of truth); the frame's own staging columns last
+    (populated by the config.json migration for exactly the case where
+    the old file held creds but the env no longer does)."""
+    owner = frame.owner
+    if owner is not None and owner.immich_url and owner.immich_api_key:
+        return owner.immich_url, owner.immich_api_key
+    env_url = os.environ.get("IMMICH_URL", "")
+    env_key = os.environ.get("IMMICH_API_KEY", "")
+    if env_url and env_key:
+        return env_url, env_key
+    return frame.immich_url, frame.immich_api_key
+
+
+def immich_client_for(frame: Frame) -> ImmichClient:
+    url, key = immich_creds(frame)
+    return ImmichClient(url, key)
+
+
+def require_configured(frame: Frame) -> None:
+    url, key = immich_creds(frame)
+    if not url or not key:
+        raise HTTPException(400, "Immich URL/API key not configured yet")
+    if not frame.album_id:
+        raise HTTPException(400, "No album configured yet")
+
+
+def list_assets(client: ImmichClient, frame: Frame) -> list[dict]:
+    try:
+        assets = client.list_album_assets(frame.album_id)
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not reach Immich: {e}") from e
+    if not assets:
+        raise HTTPException(404, "Album has no photos")
+    return assets
+
+
+def render_asset(client: ImmichClient, frame: Frame, asset_id: str) -> bytes:
+    try:
+        jpeg_bytes = client.download_asset_preview(asset_id)
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not download asset from Immich: {e}") from e
+
+    faces = None
+    if frame.smart_crop_faces:
+        try:
+            faces = client.get_asset_faces(asset_id)
+        except httpx.HTTPError as e:
+            # A faces lookup hiccup shouldn't block showing a photo at
+            # all -- just fall back to a plain center-crop this cycle.
+            logger.warning("Could not fetch faces for asset %s: %s", asset_id, e)
+
+    source = Image.open(io.BytesIO(jpeg_bytes))
+    return render_frame(source, faces=faces, orientation=frame.orientation)
+
+
+def battery_estimate_s(frame: Frame) -> int | None:
+    """Linear remaining-time estimate from the current discharge cycle's
+    observed rate, or None when there's not enough signal to be honest
+    about (too little time observed, or too little drop -- a flat line
+    extrapolates to garbage)."""
+    hist = frame.battery_history
+    if len(hist) < 2:
+        return None
+    first_ts, first_pct = hist[0]
+    last_ts, last_pct = hist[-1]
+    span = last_ts - first_ts
+    drop = first_pct - last_pct
+    if span < MIN_ESTIMATE_SPAN_S or drop < MIN_ESTIMATE_DROP_PCT:
+        return None
+    rate = drop / span  # percent per second
+    return int(last_pct / rate)
+
+
+def shell_context(request, db: Session, user, active_frame: Frame | None = None,
+                  active_nav: str | None = None) -> dict:
+    """Template context every app-shell (sidebar) page needs: the user's
+    frame list with an online indicator, the active highlights, and the
+    session's CSRF token. Import here (not auth) keeps the router
+    modules' template plumbing in one place."""
+    import time as _time
+
+    from .. import quiet_hours
+    from ..auth import current_session, user_frames
+
+    session = current_session(request, db)
+    frames = user_frames(db, user)
+    now = _time.time()
+    for f in frames:
+        # Same "not overdue" definition the Device panel uses.
+        gap = quiet_hours.max_expected_gap_s(f) * OVERDUE_FACTOR
+        f.recently_seen = bool(f.last_seen and now - f.last_seen <= gap)
+    return {
+        "request": request,
+        "user": user,
+        "csrf_token": session.csrf_token if session else None,
+        "sidebar_frames": frames,
+        "active_frame": active_frame,
+        "active_nav": active_nav,
+    }

server/app/routers/device.py

@@ -0,0 +1,404 @@
+"""Device-facing /frame/* routes. These paths are FROZEN -- they're baked
+into deployed firmware -- so multi-frame support changes only how the
+calling frame is resolved (see auth.require_device), never the paths or
+response key names the deployed flat parser depends on
+("refresh_interval_s", "firmware_version")."""
+
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import FileResponse, RedirectResponse, Response
+from pydantic import BaseModel
+from sqlalchemy import delete, func, select
+from sqlalchemy.orm import Session
+
+from .. import photo_queue, quiet_hours
+from ..auth import require_device
+from ..db import frame_locked, get_db
+from ..face_labels import compute_face_labels
+from ..firmware import firmware_path
+from ..image_pipeline import render_placeholder
+from ..models import BatteryLog, Frame
+from .common import (
+    BATTERY_HISTORY_MAX,
+    BATTERY_LOG_MAX,
+    RECHARGE_JUMP_PCT,
+    immich_client_for,
+    immich_creds,
+    list_assets,
+    render_asset,
+    require_configured,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _setup_placeholder(frame: Frame, request: Request) -> bytes:
+    """What an unclaimed or not-yet-configured frame displays instead of a
+    photo -- instructions with a QR, rendered at 200 so the device treats
+    it as a perfectly normal image and never error-loops. The URLs are
+    built from the request's own base URL: whatever address the device
+    reached us at is by definition an address that works on this
+    network."""
+    base = str(request.base_url).rstrip("/")
+    if frame.owner_user_id is None and frame.device_id:
+        claim_url = f"{base}/claim?device_id={frame.device_id}"
+        return render_placeholder(
+            ["This frame isn't claimed yet", "Scan to link it to your account:"],
+            qr_url=claim_url,
+            orientation=frame.orientation,
+        )
+    if frame.owner_user_id is None:
+        return render_placeholder(
+            ["Almost there!", f"Open {base} to finish setting up this frame."],
+            orientation=frame.orientation,
+        )
+    return render_placeholder(
+        ["Almost there!", "Pick an album for this frame:", base],
+        qr_url=base,
+        orientation=frame.orientation,
+    )
+
+
+def _frame_configured(frame: Frame) -> bool:
+    url, key = immich_creds(frame)
+    return bool(url and key and frame.album_id)
+
+
+# Renderer dispatch seam for future frame modes (calendar, canva, ...):
+# /frame/image looks up the frame's mode here. Only photos exists today.
+def _render_photos_mode(db: Session, frame: Frame, request: Request) -> bytes:
+    if not _frame_configured(frame):
+        return _setup_placeholder(frame, request)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as locked:
+        photo_queue.get_current(locked, assets, in_quiet_hours=quiet_hours.in_quiet_hours(locked))
+        asset_id = locked.current_asset_id
+
+    return render_asset(client, frame, asset_id)
+
+
+RENDERERS = {
+    "photos": _render_photos_mode,
+}
+
+
+@router.get("/frame/config")
+def frame_config(request: Request, frame: Frame = Depends(require_device), db: Session = Depends(get_db)):
+    """Device-facing settings, polled by the frame alongside its
+    reachability check. Always returns 200 with current settings -- no
+    Immich-configured gate, since this doubles as the "is the server up"
+    signal. Also captures the device's running firmware version and board
+    variant (X-Frame-Version/X-Frame-Board headers) and advertises the
+    available OTA image's version, so the device's update check costs
+    zero extra round trips."""
+    reported_version = request.headers.get("X-Frame-Version", "")
+    reported_board = request.headers.get("X-Frame-Board", "")
+    with frame_locked(db, frame.id) as locked:
+        if locked.stats_first_seen == 0:
+            locked.stats_first_seen = time.time()
+        locked.stats_device_wakes += 1
+        if reported_version:
+            if locked.device_firmware_version and reported_version != locked.device_firmware_version:
+                locked.stats_ota_updates_applied += 1
+            locked.device_firmware_version = reported_version
+        if reported_board:
+            locked.device_board_variant = reported_board
+
+        response = {
+            "refresh_interval_s": quiet_hours.effective_refresh_interval_s(locked),
+            "firmware_version": locked.firmware_available_version or None,
+        }
+        # Per-frame token push: only once the device has introduced itself
+        # by id (so the response to pure-legacy firmware stays byte-
+        # compatible with its 256-byte parse buffer), and only until the
+        # device has authenticated with the token once (device_token_ack).
+        if locked.device_id is not None and not locked.device_token_ack:
+            response["device_token"] = locked.device_token
+    return response
+
+
+@router.get("/frame/image")
+def frame_image(
+    request: Request, frame: Frame = Depends(require_device), db: Session = Depends(get_db)
+):
+    """Returns the frame's current image. For photos mode: idempotent --
+    only actually advances to the next photo once refresh_interval_s has
+    elapsed since the current one was set (see app/photo_queue.py) --
+    safe to call as often as the device wants, including after an
+    unplanned reboot, without skipping ahead in the album. An unclaimed/
+    unconfigured frame gets a rendered instruction placeholder (200, not
+    an error) so a fresh device never error-loops."""
+    renderer = RENDERERS.get(frame.mode, _render_photos_mode)
+    return Response(content=renderer(db, frame, request), media_type="application/octet-stream")
+
+
+@router.post("/frame/advance")
+def frame_advance(frame: Frame = Depends(require_device), db: Session = Depends(get_db)):
+    """Forces an immediate advance to the next photo, ignoring
+    refresh_interval_s, and resets the interval clock from now. Used by
+    the device's next-photo button."""
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as locked:
+        photo_queue.advance_forced(locked, assets)
+        asset_id = locked.current_asset_id
+
+    return Response(content=render_asset(client, frame, asset_id), media_type="application/octet-stream")
+
+
+@router.post("/frame/back")
+def frame_back(frame: Frame = Depends(require_device), db: Session = Depends(get_db)):
+    """Returns to the previously-current photo (the mirror image of
+    /frame/advance -- see photo_queue.back_forced()), and resets the
+    interval clock from now. A no-op (still 200, current photo
+    unchanged) if there's no history to go back to -- same "always
+    returns something displayable" contract as /frame/advance, rather
+    than erroring. Used by the device's back-photo button."""
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as locked:
+        photo_queue.back_forced(locked, assets)
+        asset_id = locked.current_asset_id
+
+    return Response(content=render_asset(client, frame, asset_id), media_type="application/octet-stream")
+
+
+class BatteryReport(BaseModel):
+    percent: int
+
+
+@router.post("/frame/battery")
+def frame_battery(
+    body: BatteryReport, frame: Frame = Depends(require_device), db: Session = Depends(get_db)
+):
+    """Battery level reported by the device (only when running on battery
+    -- it stays silent on mains, where the charging voltage would read
+    misleadingly full). Stored with a timestamp plus a per-discharge-
+    cycle history that feeds the Device panel's "on battery for" and
+    "estimated remaining" numbers; every report also lands in the
+    permanent battery_log table behind the history chart."""
+    if not 0 <= body.percent <= 100:
+        raise HTTPException(400, "percent must be 0-100")
+    now = time.time()
+    with frame_locked(db, frame.id) as locked:
+        locked.stats_battery_reports += 1
+        if locked.battery_history and body.percent >= locked.battery_history[-1][1] + RECHARGE_JUMP_PCT:
+            # Percent jumped up meaningfully -- the battery was recharged
+            # (or swapped). Start a fresh discharge cycle so runtime and
+            # discharge-rate estimates never span a charge.
+            locked.battery_history = []
+            locked.stats_recharge_cycles += 1
+        locked.battery_history.append([now, body.percent])
+        locked.battery_history = locked.battery_history[-BATTERY_HISTORY_MAX:]
+        locked.battery_percent = body.percent
+        locked.battery_as_of = now
+
+        db.add(BatteryLog(frame_id=locked.id, ts=now, percent=body.percent))
+        # Safety bound, not a real limit at realistic report rates --
+        # mirrors the old JSON list's cap.
+        count = db.scalar(select(func.count()).select_from(BatteryLog).where(BatteryLog.frame_id == locked.id))
+        if count is not None and count >= BATTERY_LOG_MAX:
+            cutoff_ids = select(BatteryLog.id).where(BatteryLog.frame_id == locked.id).order_by(
+                BatteryLog.ts
+            ).limit(count + 1 - BATTERY_LOG_MAX)
+            db.execute(delete(BatteryLog).where(BatteryLog.id.in_(cutoff_ids)))
+    return {"status": "saved"}
+
+
+@router.get("/frame/firmware")
+def frame_firmware(frame: Frame = Depends(require_device)):
+    """The frame's staged OTA image, streamed to the device
+    (esp_https_ota). 404 until something has been uploaded/fetched."""
+    path = firmware_path(frame.id)
+    if not path.exists():
+        raise HTTPException(404, "No firmware uploaded")
+    return FileResponse(path, media_type="application/octet-stream")
+
+
+LOCATION_LINE_MAX_LEN = 14
+
+US_STATE_ABBR = {
+    "alabama": "AL", "alaska": "AK", "arizona": "AZ", "arkansas": "AR", "california": "CA",
+    "colorado": "CO", "connecticut": "CT", "delaware": "DE", "florida": "FL", "georgia": "GA",
+    "hawaii": "HI", "idaho": "ID", "illinois": "IL", "indiana": "IN", "iowa": "IA",
+    "kansas": "KS", "kentucky": "KY", "louisiana": "LA", "maine": "ME", "maryland": "MD",
+    "massachusetts": "MA", "michigan": "MI", "minnesota": "MN", "mississippi": "MS", "missouri": "MO",
+    "montana": "MT", "nebraska": "NE", "nevada": "NV", "new hampshire": "NH", "new jersey": "NJ",
+    "new mexico": "NM", "new york": "NY", "north carolina": "NC", "north dakota": "ND", "ohio": "OH",
+    "oklahoma": "OK", "oregon": "OR", "pennsylvania": "PA", "rhode island": "RI", "south carolina": "SC",
+    "south dakota": "SD", "tennessee": "TN", "texas": "TX", "utah": "UT", "vermont": "VT",
+    "virginia": "VA", "washington": "WA", "west virginia": "WV", "wisconsin": "WI", "wyoming": "WY",
+    "district of columbia": "DC",
+}
+
+CA_PROVINCE_ABBR = {
+    "alberta": "AB", "british columbia": "BC", "manitoba": "MB", "new brunswick": "NB",
+    "newfoundland and labrador": "NL", "northwest territories": "NT", "nova scotia": "NS",
+    "nunavut": "NU", "ontario": "ON", "prince edward island": "PE", "quebec": "QC",
+    "saskatchewan": "SK", "yukon": "YT",
+}
+
+US_COUNTRY_NAMES = {"united states", "united states of america", "usa", "us"}
+CA_COUNTRY_NAMES = {"canada"}
+
+
+def _truncate(text: str, max_len: int) -> str:
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 3] + "..."
+
+
+def _format_location(exif: dict) -> tuple[str, str] | None:
+    """Returns (city_line, region_line), each independently truncated to
+    fit its own corner-overlay line, or None if Immich hasn't geocoded
+    this photo. region_line is the abbreviated state/province for US/CAN
+    locations (e.g. "CA", "ON"), else the full country name."""
+    city = exif.get("city")
+    if not city:
+        return None
+
+    state = exif.get("state")
+    country = exif.get("country")
+    country_key = (country or "").strip().lower()
+
+    if state and country_key in US_COUNTRY_NAMES:
+        region = US_STATE_ABBR.get(state.strip().lower(), state)
+    elif state and country_key in CA_COUNTRY_NAMES:
+        region = CA_PROVINCE_ABBR.get(state.strip().lower(), state)
+    elif country:
+        region = country
+    elif state:
+        region = state
+    else:
+        region = ""
+
+    return _truncate(city, LOCATION_LINE_MAX_LEN), _truncate(region, LOCATION_LINE_MAX_LEN)
+
+
+def _format_taken_at(exif: dict) -> str | None:
+    raw = exif.get("dateTimeOriginal")
+    if not raw:
+        return None
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).strftime("%m/%d/%y")
+    except ValueError:
+        return None
+
+
+@router.get("/frame/photo-info")
+def frame_photo_info(frame: Frame = Depends(require_device), db: Session = Depends(get_db)):
+    """Location/date-taken text for the manage-button overlay, plus the
+    asset id used to build the share-QR's target URL. Read-only, same
+    idempotent current-photo semantics as /frame/image -- doesn't advance
+    anything."""
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as locked:
+        photo_queue.get_current(locked, assets, in_quiet_hours=quiet_hours.in_quiet_hours(locked))
+        asset_id = locked.current_asset_id
+
+    if not asset_id:
+        raise HTTPException(404, "No current photo")
+
+    try:
+        asset = client.get_asset(asset_id)
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not reach Immich: {e}") from e
+
+    exif = asset.get("exifInfo") or {}
+    location = _format_location(exif)
+    return {
+        "asset_id": asset_id,
+        "location_line1": location[0] if location else None,
+        "location_line2": location[1] if location and location[1] else None,
+        "taken_at": _format_taken_at(exif),
+    }
+
+
+@router.get("/frame/share/{asset_id}")
+def frame_share(asset_id: str, frame: Frame = Depends(require_device)):
+    """Creates a 30-minute public Immich share link for asset_id and
+    redirects to it -- what the manage overlay's bottom-left QR code
+    points to. The link is created lazily, when this actually gets hit
+    (i.e. when someone scans it), not when the manage button was
+    pressed, so the 30-minute window starts when it's actually used.
+    Also scoped to the photo currently showing or queued on THIS frame --
+    not any arbitrary Immich asset id -- as a second layer even a leaked
+    token wouldn't bypass."""
+    require_configured(frame)
+
+    if asset_id != frame.current_asset_id and asset_id not in frame.queue:
+        raise HTTPException(404, "That photo isn't currently showing or queued on this frame")
+
+    client = immich_client_for(frame)
+    try:
+        share_url = client.create_share_link(asset_id, expires_in_s=1800)
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not create share link: {e}") from e
+
+    return RedirectResponse(share_url)
+
+
+@router.get("/frame/face-labels")
+def frame_face_labels(frame: Frame = Depends(require_device), db: Session = Depends(get_db)):
+    """Named-face positions for the manage button's escalated "level 2"
+    menu -- who's in the current photo, per Immich's own face
+    recognition (no detection/recognition happens here, see
+    app/face_labels.py). Response is a flattened, fixed-slot shape
+    (name_0/x_0/y_0, ...) rather than a JSON array, so the device's
+    hand-rolled parser can read it with the same flat-scalar helpers it
+    already has. Empty (count: 0) if no faces are named, or if anything
+    about fetching them fails -- this is a "nice to have" addition to
+    the overlay, not worth failing the whole menu over."""
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as locked:
+        photo_queue.get_current(locked, assets, in_quiet_hours=quiet_hours.in_quiet_hours(locked))
+        asset_id = locked.current_asset_id
+        smart_crop = locked.smart_crop_faces
+        orientation = locked.orientation
+
+    if not asset_id:
+        return {"count": 0}
+
+    try:
+        faces = client.get_asset_faces(asset_id)
+    except httpx.HTTPError as e:
+        logger.warning("Could not fetch faces for asset %s: %s", asset_id, e)
+        return {"count": 0}
+
+    if not any((face.get("person") or {}).get("name") for face in faces):
+        return {"count": 0}  # skip the extra preview download in the common no-named-faces case
+
+    try:
+        preview_bytes = client.download_asset_preview(asset_id)
+    except httpx.HTTPError as e:
+        logger.warning("Could not download asset %s for face-label mapping: %s", asset_id, e)
+        return {"count": 0}
+
+    labels = compute_face_labels(preview_bytes, faces, smart_crop, orientation)
+
+    result: dict[str, object] = {"count": len(labels)}
+    for i, label in enumerate(labels):
+        result[f"name_{i}"] = label["name"]
+        result[f"x_{i}"] = label["x"]
+        result[f"y_{i}"] = label["y"]
+    return result

server/app/routers/frame_pages.py

@@ -0,0 +1,49 @@
+"""The per-frame HTML pages: Photos (/frames/{id}), Configuration, and
+Stats tabs, all inside the sidebar app shell. Data loading happens
+client-side against /api/frames/{id}/... (routers/api_frames.py); these
+routes just authorize and render the scaffold."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+from sqlalchemy.orm import Session
+
+from ..auth import can_view_frame, current_user
+from ..db import get_db
+from ..models import Frame
+from ..quiet_hours import ALL_TIMEZONES
+from .common import shell_context
+
+router = APIRouter()
+templates = Jinja2Templates(directory="app/templates")
+
+
+def _frame_page(request: Request, db: Session, frame_id: int, template: str, tab: str, **extra):
+    user = current_user(request, db)
+    if user is None:
+        return RedirectResponse(f"/login?next=/frames/{frame_id}", status_code=303)
+    frame = db.get(Frame, frame_id)
+    if frame is None or not can_view_frame(db, user, frame):
+        raise HTTPException(404, "No such frame")
+    ctx = shell_context(request, db, user, active_frame=frame)
+    ctx.update({"frame": frame, "active_tab": tab, **extra})
+    return templates.TemplateResponse(template, ctx)
+
+
+@router.get("/frames/{frame_id}", response_class=HTMLResponse)
+def frame_photos_page(frame_id: int, request: Request, db: Session = Depends(get_db)):
+    return _frame_page(request, db, frame_id, "frame_photos.html", "photos")
+
+
+@router.get("/frames/{frame_id}/config", response_class=HTMLResponse)
+def frame_config_page(frame_id: int, request: Request, db: Session = Depends(get_db)):
+    return _frame_page(
+        request, db, frame_id, "frame_config.html", "config", timezones=ALL_TIMEZONES
+    )
+
+
+@router.get("/frames/{frame_id}/stats", response_class=HTMLResponse)
+def frame_stats_page(frame_id: int, request: Request, db: Session = Depends(get_db)):
+    return _frame_page(request, db, frame_id, "frame_stats.html", "stats")

server/app/routers/manage.py

@@ -0,0 +1,119 @@
+"""The limited no-login manage surface behind the on-frame "scan to
+manage" QR. The QR resolves to /m/<manage_token> (see main.index's
+device-credential redirect); the token grants exactly: view the current
+photo + upcoming queue, promote ("show next"), advance, back, and
+thumbnails. No settings, no removal, no other frames -- full control
+requires logging in."""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import HTMLResponse, Response
+from fastapi.templating import Jinja2Templates
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .. import photo_queue, quiet_hours
+from ..db import frame_locked, get_db
+from ..models import Frame
+from .common import immich_client_for, list_assets, require_configured
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+templates = Jinja2Templates(directory="app/templates")
+
+
+def require_manage(manage_token: str, db: Session = Depends(get_db)) -> Frame:
+    frame = db.scalars(select(Frame).where(Frame.manage_token == manage_token)).first()
+    if frame is None:
+        raise HTTPException(404, "Unknown manage link")
+    return frame
+
+
+@router.get("/m/{manage_token}", response_class=HTMLResponse)
+def manage_page(manage_token: str, request: Request, db: Session = Depends(get_db)):
+    frame = require_manage(manage_token, db)
+    return templates.TemplateResponse(
+        "manage.html",
+        {"request": request, "frame": frame, "manage_token": manage_token},
+    )
+
+
+@router.get("/api/m/{manage_token}/queue")
+def manage_queue(frame: Frame = Depends(require_manage), db: Session = Depends(get_db)):
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+
+    with frame_locked(db, frame.id) as cfg:
+        photo_queue.get_current(cfg, assets, in_quiet_hours=quiet_hours.in_quiet_hours(cfg))
+        photo_queue.sync_queue_length(cfg, assets)
+        current = cfg.current_asset_id
+        queue = list(cfg.queue)
+
+    def entry(asset_id: str) -> dict:
+        return {"id": asset_id, "thumbnail_url": f"/api/m/{frame.manage_token}/thumbnail/{asset_id}"}
+
+    return {
+        "frame_name": frame.name,
+        "current": entry(current) if current else None,
+        "upcoming": [entry(asset_id) for asset_id in queue],
+    }
+
+
+class ManagePromoteRequest(BaseModel):
+    asset_id: str
+
+
+@router.post("/api/m/{manage_token}/promote")
+def manage_promote(
+    body: ManagePromoteRequest,
+    frame: Frame = Depends(require_manage),
+    db: Session = Depends(get_db),
+):
+    with frame_locked(db, frame.id) as cfg:
+        if body.asset_id not in cfg.queue:
+            raise HTTPException(400, "That photo is no longer in the upcoming queue")
+        cfg.queue = [body.asset_id] + [a for a in cfg.queue if a != body.asset_id]
+    return {"status": "saved"}
+
+
+@router.post("/api/m/{manage_token}/advance")
+def manage_advance(frame: Frame = Depends(require_manage), db: Session = Depends(get_db)):
+    """Advances the server-side current photo; the panel itself updates
+    on the device's next wake (or its next-photo button)."""
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+    with frame_locked(db, frame.id) as cfg:
+        photo_queue.advance_forced(cfg, assets)
+    return {"status": "saved"}
+
+
+@router.post("/api/m/{manage_token}/back")
+def manage_back(frame: Frame = Depends(require_manage), db: Session = Depends(get_db)):
+    require_configured(frame)
+    client = immich_client_for(frame)
+    assets = list_assets(client, frame)
+    with frame_locked(db, frame.id) as cfg:
+        photo_queue.back_forced(cfg, assets)
+    return {"status": "saved"}
+
+
+@router.get("/api/m/{manage_token}/thumbnail/{asset_id}")
+def manage_thumbnail(asset_id: str, frame: Frame = Depends(require_manage)):
+    """Thumbnails scoped to what this frame is actually showing/queuing --
+    the manage token must not become a general Immich proxy."""
+    if asset_id != frame.current_asset_id and asset_id not in frame.queue:
+        raise HTTPException(404, "Not on this frame")
+    client = immich_client_for(frame)
+    try:
+        content, content_type = client.download_asset_thumbnail(asset_id)
+    except httpx.HTTPError as e:
+        raise HTTPException(502, f"Could not download thumbnail from Immich: {e}") from e
+    return Response(content=content, media_type=content_type)

server/app/routers/pages.py

@@ -0,0 +1,552 @@
+"""HTML page routes: first-run setup, login/logout, user settings, and
+the admin panel. The frame pages themselves stay in main.py (Phase A's
+single-frame index) until the Phase D restructure.
+
+All POSTs here are plain HTML forms, so CSRF rides a hidden form field
+(checked explicitly) rather than the X-CSRF-Token header the JSON API
+uses."""
+
+from __future__ import annotations
+
+import hmac
+import logging
+import time
+
+from fastapi import APIRouter, Depends, Form, HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from ..auth import (
+    SESSION_COOKIE,
+    SESSION_LIFETIME_S,
+    create_session,
+    current_session,
+    current_user,
+    destroy_session,
+    hash_password,
+    users_exist,
+    verify_password,
+)
+from ..db import get_db
+from ..models import Frame, PendingClaim, User, UserFrame
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+templates = Jinja2Templates(directory="app/templates")
+
+USERNAME_MAX_LEN = 64
+PASSWORD_MIN_LEN = 8
+PENDING_CLAIM_TTL_S = 24 * 3600
+
+
+def _set_session_cookie(response, cookie_value: str) -> None:
+    # No Secure flag: the server itself is plain HTTP by design (TLS is a
+    # reverse proxy's job, see README) and a LAN deployment without HTTPS
+    # must still be able to log in.
+    response.set_cookie(
+        SESSION_COOKIE,
+        cookie_value,
+        max_age=SESSION_LIFETIME_S,
+        httponly=True,
+        samesite="lax",
+    )
+
+
+def _check_form_csrf(request: Request, db: Session, csrf_token: str) -> None:
+    session = current_session(request, db)
+    if session is None or not hmac.compare_digest(csrf_token, session.csrf_token):
+        raise HTTPException(403, "Missing or invalid CSRF token")
+
+
+def _normalize_username(username: str) -> str:
+    return username.strip().lower()
+
+
+def _validate_credentials(username: str, password: str) -> str:
+    username = _normalize_username(username)
+    if not username or len(username) > USERNAME_MAX_LEN:
+        raise HTTPException(400, "Invalid username")
+    if len(password) < PASSWORD_MIN_LEN:
+        raise HTTPException(400, f"Password must be at least {PASSWORD_MIN_LEN} characters")
+    return username
+
+
+@router.get("/setup", response_class=HTMLResponse)
+def setup_page(request: Request, db: Session = Depends(get_db)):
+    if users_exist(db):
+        return RedirectResponse("/login", status_code=303)
+    return templates.TemplateResponse("setup.html", {"request": request, "error": None})
+
+
+@router.post("/setup")
+def setup_submit(
+    request: Request,
+    username: str = Form(...),
+    display_name: str = Form(""),
+    password: str = Form(...),
+    db: Session = Depends(get_db),
+):
+    """Creates admin #1 -- only ever available while no users exist, so it
+    needs no CSRF/session (there is nothing to ride). Links every
+    existing frame (i.e. the migrated frame #1) to the new admin, makes
+    them its owner + controller, and inherits the migrated Immich creds
+    onto their account (that's how env/config.json creds become per-user
+    state)."""
+    if users_exist(db):
+        raise HTTPException(403, "Setup has already been completed")
+    username = _validate_credentials(username, password)
+
+    admin = User(
+        username=username,
+        display_name=display_name.strip() or username,
+        password_hash=hash_password(password),
+        is_admin=True,
+        created_at=time.time(),
+    )
+    db.add(admin)
+    db.flush()
+
+    for frame in db.scalars(select(Frame)):
+        db.add(UserFrame(user_id=admin.id, frame_id=frame.id))
+        if frame.owner_user_id is None:
+            frame.owner_user_id = admin.id
+            frame.claimed_at = time.time()
+        if frame.controlled_by_user_id is None:
+            frame.controlled_by_user_id = admin.id
+        if not admin.immich_url and frame.immich_url and frame.immich_api_key:
+            admin.immich_url = frame.immich_url
+            admin.immich_api_key = frame.immich_api_key
+
+    db.commit()
+    logger.info("First-run setup: created admin '%s' and linked %s", username,
+                ", ".join(f"frame #{f.id}" for f in db.scalars(select(Frame))) or "no frames")
+
+    cookie_value, _ = create_session(db, admin)
+    response = RedirectResponse("/", status_code=303)
+    _set_session_cookie(response, cookie_value)
+    return response
+
+
+def _safe_next(next_url: str) -> str:
+    """Same-site relative paths only -- a login redirect target from a
+    query param must never become an open redirect."""
+    if next_url.startswith("/") and not next_url.startswith("//"):
+        return next_url
+    return "/"
+
+
+@router.get("/login", response_class=HTMLResponse)
+def login_page(request: Request, next: str = "", db: Session = Depends(get_db)):
+    if not users_exist(db):
+        return RedirectResponse("/setup", status_code=303)
+    if current_user(request, db) is not None:
+        return RedirectResponse(_safe_next(next), status_code=303)
+    return templates.TemplateResponse(
+        "login.html", {"request": request, "error": None, "next": next}
+    )
+
+
+@router.post("/login")
+def login_submit(
+    request: Request,
+    username: str = Form(...),
+    password: str = Form(...),
+    next: str = Form(""),
+    db: Session = Depends(get_db),
+):
+    user = db.scalars(
+        select(User).where(User.username == _normalize_username(username))
+    ).first()
+    if user is None or not user.password_hash or not verify_password(password, user.password_hash):
+        return templates.TemplateResponse(
+            "login.html",
+            {"request": request, "error": "Wrong username or password.", "next": next},
+            status_code=401,
+        )
+    cookie_value, _ = create_session(db, user)
+    response = RedirectResponse(_safe_next(next), status_code=303)
+    _set_session_cookie(response, cookie_value)
+    return response
+
+
+@router.post("/logout")
+def logout(request: Request, csrf_token: str = Form(""), db: Session = Depends(get_db)):
+    _check_form_csrf(request, db, csrf_token)
+    destroy_session(db, request)
+    response = RedirectResponse("/login", status_code=303)
+    response.delete_cookie(SESSION_COOKIE)
+    return response
+
+
+def _normalize_device_id(device_id: str) -> str:
+    device_id = device_id.strip().lower()
+    if len(device_id) != 12 or any(c not in "0123456789abcdef" for c in device_id):
+        raise HTTPException(400, "Invalid device id")
+    return device_id
+
+
+def _attempt_claim(db: Session, user: User, device_id: str) -> str:
+    """Claims the frame for `user` if it has registered, else records a
+    pending claim the frame's first check-in will attach (see
+    auth._register_frame). Returns "claimed" or "pending"."""
+    frame = db.scalars(select(Frame).where(Frame.device_id == device_id)).first()
+    now = time.time()
+    if frame is not None:
+        if frame.owner_user_id is not None:
+            raise HTTPException(409, "That frame is already claimed")
+        frame.owner_user_id = user.id
+        frame.claimed_at = now
+        if frame.controlled_by_user_id is None:
+            frame.controlled_by_user_id = user.id
+        if db.get(UserFrame, (user.id, frame.id)) is None:
+            db.add(UserFrame(user_id=user.id, frame_id=frame.id))
+        pending = db.get(PendingClaim, device_id)
+        if pending is not None:
+            db.delete(pending)
+        db.commit()
+        logger.info("User '%s' claimed frame #%d (%s)", user.username, frame.id, device_id)
+        return "claimed"
+
+    pending = db.get(PendingClaim, device_id)
+    if pending is None:
+        pending = PendingClaim(device_id=device_id, user_id=user.id, created_at=now,
+                               expires_at=now + PENDING_CLAIM_TTL_S)
+        db.add(pending)
+    else:
+        pending.user_id = user.id
+        pending.expires_at = now + PENDING_CLAIM_TTL_S
+    db.commit()
+    logger.info("User '%s' filed a pending claim for device %s", user.username, device_id)
+    return "pending"
+
+
+def _render_claim(request: Request, db: Session, device_id: str, error: str | None = None):
+    user = current_user(request, db)
+    session = current_session(request, db) if user else None
+    frame = db.scalars(select(Frame).where(Frame.device_id == device_id)).first()
+    if frame is None:
+        status = "unregistered"
+        pending = db.get(PendingClaim, device_id)
+        pending_yours = bool(pending and user and pending.user_id == user.id
+                             and pending.expires_at > time.time())
+    elif frame.owner_user_id is None:
+        status, pending_yours = "unclaimed", False
+    elif user is not None and (
+        frame.owner_user_id == user.id or db.get(UserFrame, (user.id, frame.id)) is not None
+    ):
+        status, pending_yours = "claimed_yours", False
+    else:
+        status, pending_yours = "claimed", False
+    return templates.TemplateResponse(
+        "claim.html",
+        {
+            "request": request,
+            "device_id": device_id,
+            "status": status,
+            "pending_yours": pending_yours,
+            "user": user,
+            "csrf_token": session.csrf_token if session else None,
+            "error": error,
+        },
+    )
+
+
+@router.get("/claim", response_class=HTMLResponse)
+def claim_page(request: Request, device_id: str = "", db: Session = Depends(get_db)):
+    """Where the captive portal's post-provisioning redirect lands. Also
+    the enrollment gate: a valid device id is what entitles a stranger to
+    create an account (signup form on this page); everyone else gets
+    enrolled by the admin."""
+    device_id = _normalize_device_id(device_id)
+    return _render_claim(request, db, device_id)
+
+
+@router.post("/claim")
+def claim_submit(
+    request: Request,
+    device_id: str = Form(...),
+    csrf_token: str = Form(""),
+    db: Session = Depends(get_db),
+):
+    device_id = _normalize_device_id(device_id)
+    user = current_user(request, db)
+    if user is None:
+        return RedirectResponse(f"/login?next=/claim%3Fdevice_id%3D{device_id}", status_code=303)
+    _check_form_csrf(request, db, csrf_token)
+    try:
+        _attempt_claim(db, user, device_id)
+    except HTTPException as e:
+        if e.status_code == 409:
+            return _render_claim(request, db, device_id, error=e.detail)
+        raise
+    return RedirectResponse(f"/claim?device_id={device_id}", status_code=303)
+
+
+@router.post("/claim/signup")
+def claim_signup(
+    request: Request,
+    device_id: str = Form(...),
+    username: str = Form(...),
+    password: str = Form(...),
+    db: Session = Depends(get_db),
+):
+    """Account creation, gated on a plausible frame claim: the device id
+    must belong to a frame that is unclaimed (or not yet registered --
+    the user beat the device here after provisioning). A fabricated id
+    can create an orphan account whose pending claim expires in 24h --
+    accepted at household scale, and visible in /admin."""
+    device_id = _normalize_device_id(device_id)
+    frame = db.scalars(select(Frame).where(Frame.device_id == device_id)).first()
+    if frame is not None and frame.owner_user_id is not None:
+        return _render_claim(request, db, device_id,
+                             error="That frame is already claimed -- log in instead.")
+    username = _validate_credentials(username, password)
+    if db.scalars(select(User).where(User.username == username)).first() is not None:
+        return _render_claim(request, db, device_id,
+                             error=f"Username '{username}' is taken -- log in instead?")
+
+    user = User(
+        username=username,
+        display_name=username,
+        password_hash=hash_password(password),
+        is_admin=False,
+        created_at=time.time(),
+    )
+    db.add(user)
+    db.commit()
+    logger.info("User '%s' signed up via claim gate for device %s", username, device_id)
+
+    _attempt_claim(db, user, device_id)
+    cookie_value, _ = create_session(db, user)
+    response = RedirectResponse(f"/claim?device_id={device_id}", status_code=303)
+    _set_session_cookie(response, cookie_value)
+    return response
+
+
+def _settings_context(request: Request, db: Session, user, saved: bool, error: str | None) -> dict:
+    from .common import shell_context
+
+    ctx = shell_context(request, db, user, active_nav="settings")
+    ctx.update({"saved": saved, "error": error})
+    return ctx
+
+
+@router.get("/settings", response_class=HTMLResponse)
+def settings_page(request: Request, db: Session = Depends(get_db)):
+    user = current_user(request, db)
+    if user is None:
+        return RedirectResponse("/login", status_code=303)
+    return templates.TemplateResponse(
+        "settings.html", _settings_context(request, db, user, saved=False, error=None)
+    )
+
+
+@router.post("/settings", response_class=HTMLResponse)
+def settings_submit(
+    request: Request,
+    csrf_token: str = Form(""),
+    display_name: str = Form(""),
+    immich_url: str = Form(""),
+    immich_api_key: str = Form(""),
+    current_password: str = Form(""),
+    new_password: str = Form(""),
+    db: Session = Depends(get_db),
+):
+    user = current_user(request, db)
+    if user is None:
+        return RedirectResponse("/login", status_code=303)
+    _check_form_csrf(request, db, csrf_token)
+
+    error = None
+    user.display_name = display_name.strip() or user.username
+    user.immich_url = immich_url.strip()
+    # Blank API key field = keep the existing one (it's never echoed back
+    # into the form -- a secret that round-trips through HTML is a secret
+    # in every browser's autofill store).
+    if immich_api_key.strip():
+        user.immich_api_key = immich_api_key.strip()
+
+    if new_password:
+        if not user.password_hash or not verify_password(current_password, user.password_hash):
+            error = "Current password is wrong -- password not changed."
+        elif len(new_password) < PASSWORD_MIN_LEN:
+            error = f"New password must be at least {PASSWORD_MIN_LEN} characters."
+        else:
+            user.password_hash = hash_password(new_password)
+
+    db.commit()
+    return templates.TemplateResponse(
+        "settings.html", _settings_context(request, db, user, saved=error is None, error=error)
+    )
+
+
+def _require_admin_page(request: Request, db: Session) -> User:
+    user = current_user(request, db)
+    if user is None or not user.is_admin:
+        raise HTTPException(403, "Admin only")
+    return user
+
+
+def _render_admin(request: Request, db: Session, admin: User, notice: str | None = None,
+                  error: str | None = None) -> HTMLResponse:
+    from .common import shell_context
+
+    users = list(db.scalars(select(User).order_by(User.id)))
+    frames = list(db.scalars(select(Frame).order_by(Frame.id)))
+    links = list(db.scalars(select(UserFrame)))
+    links_by_frame: dict[int, list[User]] = {}
+    users_by_id = {u.id: u for u in users}
+    for link in links:
+        links_by_frame.setdefault(link.frame_id, []).append(users_by_id[link.user_id])
+    ctx = shell_context(request, db, admin, active_nav="admin")
+    ctx.update({
+        "users": users,
+        "frames": frames,
+        "links_by_frame": links_by_frame,
+        "notice": notice,
+        "error": error,
+    })
+    return templates.TemplateResponse("admin.html", ctx)
+
+
+@router.get("/admin", response_class=HTMLResponse)
+def admin_page(request: Request, db: Session = Depends(get_db)):
+    user = current_user(request, db)
+    if user is None:
+        return RedirectResponse("/login", status_code=303)
+    if not user.is_admin:
+        raise HTTPException(403, "Admin only")
+    return _render_admin(request, db, user)
+
+
+@router.post("/admin/users", response_class=HTMLResponse)
+def admin_create_user(
+    request: Request,
+    csrf_token: str = Form(""),
+    username: str = Form(...),
+    password: str = Form(...),
+    is_admin: bool = Form(False),
+    db: Session = Depends(get_db),
+):
+    admin = _require_admin_page(request, db)
+    _check_form_csrf(request, db, csrf_token)
+    username = _validate_credentials(username, password)
+    if db.scalars(select(User).where(User.username == username)).first() is not None:
+        return _render_admin(request, db, admin, error=f"Username '{username}' already exists.")
+    db.add(User(
+        username=username,
+        display_name=username,
+        password_hash=hash_password(password),
+        is_admin=is_admin,
+        created_at=time.time(),
+    ))
+    db.commit()
+    return _render_admin(request, db, admin, notice=f"User '{username}' created.")
+
+
+@router.post("/admin/users/{user_id}/reset-password", response_class=HTMLResponse)
+def admin_reset_password(
+    user_id: int,
+    request: Request,
+    csrf_token: str = Form(""),
+    password: str = Form(...),
+    db: Session = Depends(get_db),
+):
+    admin = _require_admin_page(request, db)
+    _check_form_csrf(request, db, csrf_token)
+    target = db.get(User, user_id)
+    if target is None:
+        return _render_admin(request, db, admin, error="No such user.")
+    if len(password) < PASSWORD_MIN_LEN:
+        return _render_admin(request, db, admin,
+                             error=f"Password must be at least {PASSWORD_MIN_LEN} characters.")
+    target.password_hash = hash_password(password)
+    db.commit()
+    return _render_admin(request, db, admin, notice=f"Password reset for '{target.username}'.")
+
+
+@router.post("/admin/users/{user_id}/delete", response_class=HTMLResponse)
+def admin_delete_user(
+    user_id: int,
+    request: Request,
+    csrf_token: str = Form(""),
+    db: Session = Depends(get_db),
+):
+    admin = _require_admin_page(request, db)
+    _check_form_csrf(request, db, csrf_token)
+    if user_id == admin.id:
+        return _render_admin(request, db, admin, error="You can't delete your own account.")
+    target = db.get(User, user_id)
+    if target is None:
+        return _render_admin(request, db, admin, error="No such user.")
+    name = target.username
+    db.delete(target)  # sessions/links cascade; frames.owner goes NULL
+    db.commit()
+    return _render_admin(request, db, admin, notice=f"User '{name}' deleted.")
+
+
+@router.post("/admin/frames/{frame_id}/link-user", response_class=HTMLResponse)
+def admin_link_user(
+    frame_id: int,
+    request: Request,
+    csrf_token: str = Form(""),
+    username: str = Form(...),
+    db: Session = Depends(get_db),
+):
+    admin = _require_admin_page(request, db)
+    _check_form_csrf(request, db, csrf_token)
+    frame = db.get(Frame, frame_id)
+    target = db.scalars(select(User).where(User.username == _normalize_username(username))).first()
+    if frame is None or target is None:
+        return _render_admin(request, db, admin, error="No such frame or user.")
+    if db.get(UserFrame, (target.id, frame_id)) is not None:
+        return _render_admin(request, db, admin, error=f"'{target.username}' is already linked.")
+    db.add(UserFrame(user_id=target.id, frame_id=frame_id))
+    if frame.owner_user_id is None:
+        # Linking to an unclaimed frame claims it -- the admin flow for
+        # adopting a frame that self-registered without a pending claim.
+        frame.owner_user_id = target.id
+        frame.claimed_at = time.time()
+    db.commit()
+    return _render_admin(request, db, admin,
+                         notice=f"Linked '{target.username}' to frame #{frame_id}.")
+
+
+@router.post("/admin/frames/{frame_id}/end-legacy", response_class=HTMLResponse)
+def admin_end_legacy(
+    frame_id: int,
+    request: Request,
+    csrf_token: str = Form(""),
+    db: Session = Depends(get_db),
+):
+    """Closes the legacy-token migration window once the device is
+    confirmed on per-frame auth (device_token_ack + recent last_seen in
+    the frames table below)."""
+    admin = _require_admin_page(request, db)
+    _check_form_csrf(request, db, csrf_token)
+    frame = db.get(Frame, frame_id)
+    if frame is None:
+        return _render_admin(request, db, admin, error="No such frame.")
+    frame.legacy_token_enabled = False
+    db.commit()
+    return _render_admin(request, db, admin, notice=f"Legacy token disabled for frame #{frame_id}.")
+
+
+@router.post("/admin/frames/{frame_id}/delete", response_class=HTMLResponse)
+def admin_delete_frame(
+    frame_id: int,
+    request: Request,
+    csrf_token: str = Form(""),
+    db: Session = Depends(get_db),
+):
+    admin = _require_admin_page(request, db)
+    _check_form_csrf(request, db, csrf_token)
+    frame = db.get(Frame, frame_id)
+    if frame is None:
+        return _render_admin(request, db, admin, error="No such frame.")
+    db.delete(frame)  # links/battery log cascade
+    db.commit()
+    return _render_admin(request, db, admin, notice=f"Frame #{frame_id} deleted.")

server/app/static/battery_chart.js

@@ -0,0 +1,89 @@
+// Hand-drawn canvas battery-history chart. Ported intact from the
+// original single-page UI. Reads theme colors live so it redraws
+// correctly on theme changes (see the themechange listener in
+// frame_stats.js).
+
+let lastBatteryLog = null;
+
+function drawBatteryChart(log) {
+  lastBatteryLog = log;
+  const wrap = document.getElementById('battery-chart-wrap');
+  if (!log || log.length < 2) {
+    wrap.innerHTML = '<p class="sub">Not enough data yet.</p>';
+    return;
+  }
+  wrap.innerHTML = '';
+  const width = wrap.clientWidth || 440;
+  const height = 180;
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  canvas.style.display = 'block';
+  canvas.style.border = `1px solid ${themeColor('--border')}`;
+  canvas.style.borderRadius = '8px';
+  wrap.appendChild(canvas);
+  const ctx = canvas.getContext('2d');
+
+  const gridColor = themeColor('--border');
+  const mutedColor = themeColor('--text-muted');
+  const accentColor = themeColor('--accent');
+
+  const pad = { left: 28, right: 8, top: 10, bottom: 20 };
+  const plotW = width - pad.left - pad.right;
+  const plotH = height - pad.top - pad.bottom;
+
+  const times = log.map((p) => p[0]);
+  const minT = Math.min(...times);
+  const maxT = Math.max(...times);
+  const spanT = Math.max(1, maxT - minT);
+
+  const x = (t) => pad.left + ((t - minT) / spanT) * plotW;
+  const y = (pct) => pad.top + (1 - pct / 100) * plotH;
+
+  ctx.strokeStyle = gridColor;
+  ctx.fillStyle = mutedColor;
+  ctx.font = '10px system-ui, sans-serif';
+  ctx.lineWidth = 1;
+  ctx.textAlign = 'left';
+  [0, 25, 50, 75, 100].forEach((pct) => {
+    const yy = y(pct);
+    ctx.beginPath();
+    ctx.moveTo(pad.left, yy);
+    ctx.lineTo(width - pad.right, yy);
+    ctx.stroke();
+    ctx.fillText(String(pct), 2, yy + 3);
+  });
+
+  ctx.strokeStyle = accentColor;
+  ctx.lineWidth = 1.5;
+  ctx.beginPath();
+  log.forEach((p, i) => {
+    const px = x(p[0]);
+    const py = y(p[1]);
+    if (i === 0) ctx.moveTo(px, py);
+    else ctx.lineTo(px, py);
+  });
+  ctx.stroke();
+
+  const fmt = (t) => new Date(t * 1000).toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+  ctx.fillStyle = mutedColor;
+  ctx.textAlign = 'left';
+  ctx.fillText(fmt(minT), pad.left, height - 4);
+  ctx.textAlign = 'right';
+  ctx.fillText(fmt(maxT), width - pad.right, height - 4);
+}
+
+async function loadBatteryLog() {
+  const wrap = document.getElementById('battery-chart-wrap');
+  try {
+    const resp = await fetch(`${window.FRAME_API}/battery-log`);
+    if (!resp.ok) {
+      wrap.innerHTML = '<p class="sub">Could not load.</p>';
+      return;
+    }
+    const data = await resp.json();
+    drawBatteryChart(data.log);
+  } catch (e) {
+    wrap.innerHTML = '<p class="sub">Could not load.</p>';
+  }
+}

server/app/static/common.js

@@ -0,0 +1,97 @@
+// Shared plumbing for every page: CSRF-injecting fetch, theme toggle,
+// sidebar toggle (mobile), and small formatting helpers. No framework,
+// no build step -- plain scripts, load order handled by <script> tags.
+
+// Session-cookie auth needs CSRF proof on mutating requests. Wrapping
+// fetch once means no call site has to remember the header. The token
+// rides a <meta> tag emitted only for session-authed pages.
+(function () {
+  var meta = document.querySelector('meta[name="csrf-token"]');
+  if (!meta || !meta.content) return;
+  var CSRF = meta.content;
+  var origFetch = window.fetch;
+  window.fetch = function (input, init) {
+    init = init || {};
+    var method = (init.method || (input && input.method) || 'GET').toUpperCase();
+    var url = typeof input === 'string' ? input : (input && input.url) || '';
+    var sameOrigin = url.indexOf('://') === -1 || url.indexOf(location.origin) === 0;
+    if (sameOrigin && method !== 'GET' && method !== 'HEAD') {
+      init.headers = new Headers(init.headers || (input && input.headers) || {});
+      init.headers.set('X-CSRF-Token', CSRF);
+    }
+    return origFetch.call(this, input, init);
+  };
+})();
+
+// Theme toggle: explicit choice wins over the OS preference and is
+// remembered; with no explicit choice, CSS falls back to
+// prefers-color-scheme on its own. (The pre-paint snippet in the page
+// <head> applies the stored theme before first render.)
+(function () {
+  var btn = document.getElementById('theme-toggle');
+  if (!btn) return;
+
+  function currentTheme() {
+    var stored = null;
+    try { stored = localStorage.getItem('theme'); } catch (e) { /* ignore */ }
+    if (stored === 'light' || stored === 'dark') return stored;
+    return (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light';
+  }
+
+  btn.addEventListener('click', function () {
+    var theme = currentTheme() === 'dark' ? 'light' : 'dark';
+    document.documentElement.setAttribute('data-theme', theme);
+    try { localStorage.setItem('theme', theme); } catch (e) { /* ignore */ }
+    document.dispatchEvent(new CustomEvent('themechange', { detail: { theme: theme } }));
+  });
+})();
+
+// Mobile sidebar: hamburger opens, backdrop or navigation closes.
+(function () {
+  var shell = document.querySelector('.shell');
+  var toggle = document.getElementById('sidebar-toggle');
+  var backdrop = document.querySelector('.sidebar-backdrop');
+  if (!shell || !toggle) return;
+  toggle.addEventListener('click', function () { shell.classList.toggle('sidebar-open'); });
+  if (backdrop) {
+    backdrop.addEventListener('click', function () { shell.classList.remove('sidebar-open'); });
+  }
+})();
+
+function showStatus(ok, message) {
+  var el = document.getElementById('result');
+  if (!el) return;
+  el.innerHTML = '<div class="status ' + (ok ? 'ok' : 'err') + '"></div>';
+  el.firstChild.textContent = message;
+}
+
+// A 409 from a control-gated endpoint means someone else holds the
+// frame's control lock -- surface who, plus how to take over.
+async function apiError(resp) {
+  var text = await resp.text();
+  try {
+    var body = JSON.parse(text);
+    var detail = body.detail !== undefined ? body.detail : body;
+    if (detail && detail.error === 'not_controller') {
+      var holder = detail.holder || 'Someone else';
+      return holder + ' has control of this frame — use "Take control" to make changes.';
+    }
+    if (typeof detail === 'string') return detail;
+  } catch (e) { /* not JSON */ }
+  return text;
+}
+
+function formatDuration(seconds) {
+  var d = Math.floor(seconds / 86400);
+  var h = Math.floor((seconds % 86400) / 3600);
+  var m = Math.floor((seconds % 3600) / 60);
+  if (d > 0) return d + 'd ' + h + 'h';
+  if (h > 0) return h + 'h ' + m + 'm';
+  return m + 'm';
+}
+
+// Reads resolved colors from CSS custom properties rather than
+// hardcoding hex values, so canvas drawing matches the current theme.
+function themeColor(name) {
+  return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+}

server/app/static/frame_config.js

@@ -0,0 +1,201 @@
+// Configuration tab: frame settings + firmware card + take control.
+// window.FRAME_API is set by the template. Checkboxes are always sent
+// explicitly as "true"/"false" -- the server treats absent fields as
+// "leave unchanged", so a checkbox must never be simply omitted.
+
+async function saveConfig() {
+  const minutes = parseInt(document.getElementById('refresh_interval_minutes').value, 10) || 60;
+  const body = new URLSearchParams({
+    name: document.getElementById('frame_name').value || '',
+    order: document.getElementById('order').value,
+    orientation: document.getElementById('orientation').value,
+    refresh_interval_s: String(minutes * 60),
+    smart_crop_faces: String(document.getElementById('smart_crop_faces').checked),
+    quiet_hours_enabled: String(document.getElementById('quiet_hours_enabled').checked),
+    quiet_hours_start: document.getElementById('quiet_hours_start').value || '22:00',
+    quiet_hours_end: document.getElementById('quiet_hours_end').value || '07:00',
+    timezone: document.getElementById('timezone').value || 'UTC',
+  });
+  const resp = await fetch(`${window.FRAME_API}/config`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+  if (!resp.ok) {
+    throw new Error(await apiError(resp));
+  }
+}
+
+document.getElementById('config-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  try {
+    await saveConfig();
+    showStatus(true, 'Saved.');
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+});
+
+async function takeControl() {
+  try {
+    const resp = await fetch(`${window.FRAME_API}/take-control`, { method: 'POST' });
+    if (!resp.ok) throw new Error(await apiError(resp));
+    showStatus(true, 'You have control now.');
+    loadControl();
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+}
+
+async function loadControl() {
+  const banner = document.getElementById('control-banner');
+  try {
+    const resp = await fetch(`${window.FRAME_API}/queue`);
+    if (!resp.ok) return; // unconfigured frame: control still works via 409s
+    const data = await resp.json();
+    if (data.control && !data.control.you) {
+      banner.style.display = 'flex';
+      document.getElementById('control-holder').textContent = data.control.controller
+        ? `${data.control.controller} currently has control of this frame.`
+        : 'Nobody has control of this frame yet.';
+    } else {
+      banner.style.display = 'none';
+    }
+  } catch (e) { /* banner is best-effort */ }
+}
+
+document.getElementById('take-control').addEventListener('click', takeControl);
+
+// ---- Firmware card ----
+
+document.getElementById('firmware-upload').addEventListener('click', async () => {
+  const input = document.getElementById('firmware-file');
+  if (!input.files.length) {
+    showStatus(false, 'Pick a firmware .bin first.');
+    return;
+  }
+  const form = new FormData();
+  form.append('file', input.files[0]);
+  try {
+    const resp = await fetch(`${window.FRAME_API}/firmware`, { method: 'POST', body: form });
+    if (!resp.ok) {
+      throw new Error(await apiError(resp));
+    }
+    const result = await resp.json();
+    document.getElementById('firmware-available').textContent =
+      `Uploaded: v${result.version} -- the frame updates itself on its next wake if it's running something else.`;
+    showStatus(true, `Firmware v${result.version} uploaded (${result.size} bytes).`);
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+});
+
+function showRepoDisplayMode(url) {
+  document.getElementById('firmware-repo-text').textContent = url;
+  document.getElementById('firmware-repo-display').style.display = url ? 'block' : 'none';
+  document.getElementById('firmware-repo-edit').style.display = url ? 'none' : 'block';
+}
+
+document.getElementById('firmware-repo-edit-btn').addEventListener('click', () => {
+  document.getElementById('firmware-repo-display').style.display = 'none';
+  document.getElementById('firmware-repo-edit').style.display = 'block';
+  document.getElementById('firmware_update_repo_url').focus();
+});
+
+document.getElementById('firmware-settings-save').addEventListener('click', async () => {
+  try {
+    const body = new URLSearchParams({
+      firmware_update_repo_url: document.getElementById('firmware_update_repo_url').value || '',
+      firmware_auto_update: String(document.getElementById('firmware_auto_update').checked),
+    });
+    const resp = await fetch(`${window.FRAME_API}/config`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+    });
+    if (!resp.ok) throw new Error(await apiError(resp));
+    showStatus(true, 'Saved.');
+    showRepoDisplayMode(document.getElementById('firmware_update_repo_url').value.trim());
+    loadFirmwareCheck();
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+});
+
+async function loadFirmwareCheck(force) {
+  const statusEl = document.getElementById('firmware-gitea-status');
+  const btn = document.getElementById('firmware-update-btn');
+  const boardEl = document.getElementById('firmware-board');
+  try {
+    const resp = await fetch(`${window.FRAME_API}/firmware/check` + (force ? '?force=true' : ''));
+    if (!resp.ok) {
+      if (force) {
+        showStatus(false, await apiError(resp));
+      }
+      return;
+    }
+    const data = await resp.json();
+    if (data.board) {
+      boardEl.textContent = `Detected board: ${data.board}`;
+    }
+    if (!data.enabled) {
+      statusEl.style.display = 'none';
+      btn.style.display = 'none';
+      if (force) {
+        showStatus(false, 'No Gitea repo URL configured.');
+      }
+      return;
+    }
+    statusEl.style.display = 'block';
+    if (!data.board) {
+      statusEl.textContent = 'Waiting for the frame to check in before it can look up the right build.';
+      btn.style.display = 'none';
+    } else if (data.update_available) {
+      statusEl.textContent = `Update available: v${data.latest_version}.`;
+      btn.style.display = 'inline-block';
+    } else if (data.latest_version) {
+      statusEl.textContent = `Up to date (v${data.latest_version}).`;
+      btn.style.display = 'none';
+    } else {
+      statusEl.textContent = 'No releases found yet.';
+      btn.style.display = 'none';
+    }
+    if (force) {
+      showStatus(true, 'Checked.');
+    }
+  } catch (e) {
+    // A failed passive poll is silent; an explicit "Check now" click
+    // still surfaces the error.
+    if (force) {
+      showStatus(false, e.message);
+    }
+  }
+}
+
+document.getElementById('firmware-check-now').addEventListener('click', () => loadFirmwareCheck(true));
+
+document.getElementById('firmware-update-btn').addEventListener('click', async () => {
+  const btn = document.getElementById('firmware-update-btn');
+  btn.disabled = true;
+  try {
+    const resp = await fetch(`${window.FRAME_API}/firmware/apply-latest`, { method: 'POST' });
+    if (!resp.ok) {
+      throw new Error(await apiError(resp));
+    }
+    const result = await resp.json();
+    document.getElementById('firmware-available').textContent =
+      `Uploaded: v${result.version} -- the frame updates itself on its next wake if it's running something else.`;
+    showStatus(true, `Firmware v${result.version} staged from Gitea.`);
+    loadFirmwareCheck();
+  } catch (e) {
+    showStatus(false, e.message);
+  } finally {
+    btn.disabled = false;
+  }
+});
+
+loadControl();
+loadFirmwareCheck();
+// The server throttles actual Gitea API calls itself, so this poll is
+// cheap either way.
+setInterval(loadFirmwareCheck, 60000);

server/app/static/frame_photos.js

@@ -0,0 +1,126 @@
+// Photos tab: now-displaying, album picker, and the upcoming grid
+// (rendering/drag logic in queue.js). window.FRAME_API is set by the
+// template.
+
+function renderControlBanner(control) {
+  const banner = document.getElementById('control-banner');
+  if (!banner) return;
+  if (!control || control.you) {
+    banner.style.display = 'none';
+    return;
+  }
+  banner.style.display = 'flex';
+  document.getElementById('control-holder').textContent = control.controller
+    ? `${control.controller} currently has control of this frame.`
+    : 'Nobody has control of this frame yet.';
+}
+
+async function takeControl() {
+  try {
+    const resp = await fetch(`${window.FRAME_API}/take-control`, { method: 'POST' });
+    if (!resp.ok) throw new Error(await apiError(resp));
+    showStatus(true, 'You have control now.');
+    loadQueue();
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+}
+
+async function loadQueue() {
+  if (dragState) {
+    return; // don't yank the grid out from under an in-progress drag
+  }
+  const currentEl = document.getElementById('current-thumb');
+  try {
+    const resp = await fetch(`${window.FRAME_API}/queue`);
+    if (!resp.ok) {
+      currentEl.innerHTML =
+        '<p class="sub">Not available yet -- the owner needs to connect Immich (Settings) and pick an album.</p>';
+      renderUpcoming([]);
+      return;
+    }
+    const data = await resp.json();
+    currentEl.innerHTML = '';
+    if (data.current) {
+      const wrap = document.createElement('div');
+      wrap.className = 'thumb-wrap';
+
+      const img = document.createElement('img');
+      img.className = 'thumb';
+      img.src = data.current.thumbnail_url;
+      img.alt = '';
+      wrap.appendChild(img);
+
+      const removeBtn = document.createElement('button');
+      removeBtn.type = 'button';
+      removeBtn.className = 'remove-btn';
+      removeBtn.title = 'Remove from rotation';
+      removeBtn.textContent = '×';
+      removeBtn.addEventListener('click', () => removeAsset(data.current.id));
+      wrap.appendChild(removeBtn);
+
+      currentEl.appendChild(wrap);
+    } else {
+      currentEl.innerHTML = '<p class="sub">Nothing displayed yet.</p>';
+    }
+    renderControlBanner(data.control);
+    renderUpcoming(data.upcoming);
+  } catch (e) {
+    currentEl.innerHTML = '<p class="sub">Could not load.</p>';
+  }
+}
+
+async function savePhotoSettings() {
+  const body = new URLSearchParams({
+    album_id: document.getElementById('album_id').value || '',
+    queue_target_len: document.getElementById('queue_target_len').value,
+  });
+  const resp = await fetch(`${window.FRAME_API}/config`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+  if (!resp.ok) {
+    throw new Error(await apiError(resp));
+  }
+}
+
+document.getElementById('load-albums').addEventListener('click', async () => {
+  try {
+    const resp = await fetch(`${window.FRAME_API}/albums`);
+    if (!resp.ok) {
+      throw new Error(await apiError(resp));
+    }
+    const albums = await resp.json();
+
+    const select = document.getElementById('album_id');
+    select.innerHTML = '';
+    for (const a of albums) {
+      const opt = document.createElement('option');
+      opt.value = a.id;
+      opt.textContent = `${a.name} (${a.count})`;
+      select.appendChild(opt);
+    }
+    showStatus(true, `Loaded ${albums.length} album(s) -- pick one and click Save.`);
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+});
+
+document.getElementById('photos-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  try {
+    await savePhotoSettings();
+    showStatus(true, 'Saved.');
+    loadQueue();
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+});
+
+document.getElementById('take-control').addEventListener('click', takeControl);
+
+loadQueue();
+// Slow poll: picks up real changes (new photo displayed, queue edited
+// from elsewhere) without a manual refresh. Skipped mid-drag.
+setInterval(loadQueue, 10000);

server/app/static/frame_stats.js

@@ -0,0 +1,118 @@
+// Stats tab: device status, lifetime counters, battery history chart
+// (chart logic in battery_chart.js). window.FRAME_API set by template.
+
+let lastDevice = null;
+
+function renderDeviceStatus(device) {
+  const el = document.getElementById('device-status');
+  el.innerHTML = '';
+  if (!device || !device.last_seen) {
+    el.innerHTML = '<p class="sub">The frame hasn\'t checked in yet.</p>';
+    return;
+  }
+  const now = Date.now() / 1000;
+  const rows = [];
+  const ago = formatDuration(Math.max(0, now - device.last_seen));
+  rows.push(['Last seen', `${ago} ago`, device.overdue]);
+  if (device.firmware_version) {
+    let fw = `v${device.firmware_version}`;
+    if (device.firmware_available && device.firmware_available !== device.firmware_version) {
+      fw += ` (v${device.firmware_available} waiting)`;
+    }
+    rows.push(['Firmware', fw, false]);
+  }
+  if (device.battery) {
+    rows.push(['Battery', `${device.battery.percent}%`, false]);
+  }
+  if (device.on_battery_since) {
+    rows.push(['On battery for', formatDuration(now - device.on_battery_since), false]);
+  }
+  if (device.battery_estimate_s !== null && device.battery_estimate_s !== undefined) {
+    rows.push(['Est. remaining', `~${formatDuration(device.battery_estimate_s)}`, false]);
+  }
+  for (const [label, value, alert] of rows) {
+    const p = document.createElement('p');
+    p.className = 'sub';
+    if (alert) {
+      p.style.color = 'var(--danger-text)';
+      p.style.fontWeight = '600';
+    }
+    p.textContent = `${label}: ${value}`;
+    el.appendChild(p);
+  }
+}
+
+async function loadDevice() {
+  try {
+    const resp = await fetch(`${window.FRAME_API}/queue`);
+    if (!resp.ok) {
+      return;
+    }
+    const data = await resp.json();
+    lastDevice = data.device;
+    renderDeviceStatus(data.device);
+  } catch (e) { /* retried on the next poll */ }
+}
+
+function renderStats(stats) {
+  const el = document.getElementById('stats-box');
+  el.innerHTML = '';
+  const now = Date.now() / 1000;
+  const rows = [
+    ['Running since', stats.first_seen ? formatDuration(Math.max(0, now - stats.first_seen)) + ' ago' : 'never checked in'],
+    ['Wake cycles', stats.device_wakes],
+    ['Photos displayed', stats.photos_displayed],
+    ['Photos removed from rotation', stats.photos_removed],
+    ['Battery reports received', stats.battery_reports],
+    ['Battery recharge cycles', stats.recharge_cycles],
+    ['OTA updates applied', stats.ota_updates_applied],
+    ['Settings saved', stats.config_saves],
+  ];
+  for (const [label, value] of rows) {
+    const p = document.createElement('p');
+    p.className = 'sub';
+    p.textContent = `${label}: ${value}`;
+    el.appendChild(p);
+  }
+}
+
+async function loadStats() {
+  const el = document.getElementById('stats-box');
+  try {
+    const resp = await fetch(`${window.FRAME_API}/stats`);
+    if (!resp.ok) {
+      el.innerHTML = '<p class="sub">Could not load.</p>';
+      return;
+    }
+    renderStats(await resp.json());
+  } catch (e) {
+    el.innerHTML = '<p class="sub">Could not load.</p>';
+  }
+}
+
+loadDevice();
+loadStats();
+loadBatteryLog();
+
+// Redraw the canvas chart (and the "Last seen" alert color) with the
+// new theme's colors as soon as the toggle is used -- canvas pixels
+// don't repaint themselves the way CSS does.
+document.addEventListener('themechange', () => {
+  if (lastBatteryLog) {
+    drawBatteryChart(lastBatteryLog);
+  }
+  if (lastDevice) {
+    renderDeviceStatus(lastDevice);
+  }
+});
+
+// Fast tick: re-renders "Last seen"/"On battery for" from already-
+// fetched data every second so they count up smoothly without hitting
+// the server that often.
+setInterval(() => {
+  if (lastDevice) {
+    renderDeviceStatus(lastDevice);
+  }
+}, 1000);
+
+setInterval(loadDevice, 10000);

server/app/static/queue.js

@@ -0,0 +1,240 @@
+// The upcoming-photos grid: rendering plus drag-to-reorder. Ported
+// intact from the original single-page UI -- the Pointer Events state
+// machine below (hold-to-arm on touch so page scrolling still works) is
+// battle-tested; treat changes with suspicion.
+//
+// Expects window.FRAME_API = '/api/frames/<id>' set by the page, and a
+// loadQueue() global (frame_photos.js) to refetch authoritative state.
+
+let upcomingItems = [];
+
+// Pointer Events (not the native HTML5 Drag-and-Drop API) so the same
+// code drives mouse, touch, and pen -- native drag-and-drop is
+// mouse-only by spec and never fires at all on phones/tablets.
+//
+// On touch specifically, a card only "arms" for dragging after a
+// brief hold (DRAG_HOLD_MS) with the finger roughly stationary --
+// .photo-card's touch-action stays "pan-y" (native scroll allowed)
+// the whole time up to that point, so a normal touch-and-swipe to
+// scroll the page still works even though it starts on a card. Once
+// armed, touch-action switches to "none" for the rest of that touch
+// so drag tracking gets every pointermove reliably. Mouse skips the
+// hold entirely (no scroll-vs-drag ambiguity with a mouse).
+let dragState = null; // { pointerId, fromIndex, toIndex, moved, armed, holdTimer }
+const DRAG_START_THRESHOLD_PX = 6; // ignore tiny jitter once armed, before committing to a drag
+const DRAG_HOLD_MS = 250;
+const HOLD_CANCEL_THRESHOLD_PX = 10; // movement before the hold timer fires -> treat as a scroll, not a drag
+
+function vibrate(ms) {
+  // Chrome/Android only -- iOS Safari has no Vibration API. Wrapped so
+  // it's a harmless no-op everywhere else rather than needing a
+  // feature check at every call site.
+  try { navigator.vibrate?.(ms); } catch (e) { /* ignore */ }
+}
+
+function clearDragOverStyling() {
+  document.querySelectorAll('.photo-card.drag-over').forEach((el) => el.classList.remove('drag-over'));
+}
+
+function endDrag(card) {
+  if (dragState && dragState.holdTimer) {
+    clearTimeout(dragState.holdTimer);
+  }
+  card.style.touchAction = '';
+  card.style.transform = '';
+  card.classList.remove('dragging', 'drag-armed');
+  clearDragOverStyling();
+  if (dragState && dragState.moved && dragState.toIndex !== undefined && dragState.toIndex !== dragState.fromIndex) {
+    vibrate(15);
+    moveItem(dragState.fromIndex, dragState.toIndex);
+  }
+  dragState = null;
+}
+
+function renderUpcoming(items) {
+  upcomingItems = items;
+  const grid = document.getElementById('upcoming-grid');
+  grid.innerHTML = '';
+
+  items.forEach((item, i) => {
+    const card = document.createElement('div');
+    card.className = 'photo-card';
+    card.dataset.index = String(i);
+
+    const img = document.createElement('img');
+    img.src = item.thumbnail_url;
+    img.alt = '';
+    card.appendChild(img);
+
+    const badge = document.createElement('span');
+    badge.className = 'badge';
+    badge.textContent = String(i + 1);
+    card.appendChild(badge);
+
+    const removeBtn = document.createElement('button');
+    removeBtn.type = 'button';
+    removeBtn.className = 'remove-btn';
+    removeBtn.title = 'Remove from rotation';
+    removeBtn.textContent = '×';
+    removeBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      removeAsset(item.id);
+    });
+    card.appendChild(removeBtn);
+
+    const nextBtn = document.createElement('button');
+    nextBtn.type = 'button';
+    nextBtn.className = 'show-next';
+    nextBtn.textContent = 'Show next';
+    nextBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      showNext(i);
+    });
+    card.appendChild(nextBtn);
+
+    card.addEventListener('pointerdown', (e) => {
+      if (e.target.closest('.show-next') || e.target.closest('.remove-btn')) {
+        return; // let the button's own click handler run, don't start a drag
+      }
+      if (e.pointerType === 'mouse' && e.button !== 0) {
+        return; // left button only
+      }
+
+      dragState = {
+        pointerId: e.pointerId, fromIndex: i, toIndex: undefined, moved: false,
+        armed: e.pointerType !== 'touch', startX: e.clientX, startY: e.clientY, holdTimer: null,
+      };
+
+      if (e.pointerType === 'touch') {
+        dragState.holdTimer = setTimeout(() => {
+          if (dragState && dragState.pointerId === e.pointerId && !dragState.armed) {
+            dragState.armed = true;
+            card.classList.add('drag-armed');
+            card.style.touchAction = 'none';
+            vibrate(10);
+            try { card.setPointerCapture(e.pointerId); } catch (err) { /* pointer may have already left */ }
+          }
+        }, DRAG_HOLD_MS);
+      } else {
+        card.setPointerCapture(e.pointerId);
+      }
+    });
+
+    card.addEventListener('pointermove', (e) => {
+      if (!dragState || dragState.pointerId !== e.pointerId) {
+        return;
+      }
+
+      if (!dragState.armed) {
+        // Still deciding whether this is a hold-to-drag or a scroll --
+        // moving this much before the hold timer fires means scroll;
+        // bail out and let the browser's native pan-y handle it.
+        const dx0 = e.clientX - dragState.startX;
+        const dy0 = e.clientY - dragState.startY;
+        if (Math.hypot(dx0, dy0) > HOLD_CANCEL_THRESHOLD_PX) {
+          clearTimeout(dragState.holdTimer);
+          dragState = null;
+        }
+        return;
+      }
+
+      const dx = e.clientX - dragState.startX;
+      const dy = e.clientY - dragState.startY;
+
+      if (!dragState.moved) {
+        if (Math.hypot(dx, dy) < DRAG_START_THRESHOLD_PX) {
+          return;
+        }
+        dragState.moved = true;
+        card.classList.remove('drag-armed');
+        card.classList.add('dragging');
+      }
+
+      // Follows the finger 1:1 -- the actual "pick it up and carry it"
+      // feedback.
+      card.style.transform = `translate(${dx}px, ${dy}px) scale(1.06)`;
+
+      const overCard = document.elementFromPoint(e.clientX, e.clientY)?.closest('.photo-card');
+      clearDragOverStyling();
+      if (overCard && overCard !== card) {
+        overCard.classList.add('drag-over');
+        dragState.toIndex = Number(overCard.dataset.index);
+      } else {
+        dragState.toIndex = undefined;
+      }
+    });
+
+    card.addEventListener('pointerup', (e) => {
+      if (dragState && dragState.pointerId === e.pointerId) {
+        endDrag(card);
+      }
+    });
+    card.addEventListener('pointercancel', (e) => {
+      if (dragState && dragState.pointerId === e.pointerId) {
+        endDrag(card);
+      }
+    });
+
+    grid.appendChild(card);
+  });
+}
+
+function moveItem(fromIndex, toIndex) {
+  const items = upcomingItems.slice();
+  const [moved] = items.splice(fromIndex, 1);
+  items.splice(toIndex, 0, moved);
+  renderUpcoming(items);
+  persistOrder(items);
+}
+
+async function showNext(index) {
+  const assetId = upcomingItems[index].id;
+  try {
+    const resp = await fetch(`${window.FRAME_API}/queue/promote`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ asset_id: assetId }),
+    });
+    if (!resp.ok) {
+      throw new Error(await apiError(resp));
+    }
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+  loadQueue(); // always refetch the authoritative order rather than guessing locally
+}
+
+async function removeAsset(assetId) {
+  if (!confirm('Remove this photo from the rotation? It stays in Immich -- this frame just won\'t show it again.')) {
+    return;
+  }
+  try {
+    const resp = await fetch(`${window.FRAME_API}/queue/remove`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ asset_id: assetId }),
+    });
+    if (!resp.ok) {
+      throw new Error(await apiError(resp));
+    }
+  } catch (e) {
+    showStatus(false, e.message);
+  }
+  loadQueue();
+}
+
+async function persistOrder(items) {
+  try {
+    const resp = await fetch(`${window.FRAME_API}/queue/reorder`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ queue: items.map((item) => item.id) }),
+    });
+    if (!resp.ok) {
+      throw new Error(await apiError(resp));
+    }
+  } catch (e) {
+    showStatus(false, e.message);
+    loadQueue();
+  }
+}

server/app/static/theme.css

@@ -0,0 +1,470 @@
+:root {
+  --bg: #f5f6f8;
+  --surface: #ffffff;
+  --surface-alt: #f0f1f4;
+  --border: #e3e5e9;
+  --text: #16181d;
+  --text-muted: #666d7a;
+  --accent: #2563eb;
+  --accent-hover: #1d4ed8;
+  --focus-ring: rgba(37, 99, 235, 0.35);
+  --success-bg: #dcfce7;
+  --success-text: #166534;
+  --danger-bg: #fee2e2;
+  --danger-text: #991b1b;
+  --warn-bg: #fef9c3;
+  --warn-text: #854d0e;
+  --shadow: 0 1px 2px rgba(16, 24, 40, 0.04), 0 1px 3px rgba(16, 24, 40, 0.06);
+  --shadow-hover: 0 8px 20px rgba(16, 24, 40, 0.10);
+  --overlay: rgba(0, 0, 0, 0.55);
+  --overlay-hover: rgba(153, 27, 27, 0.85);
+  --color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --bg: #0d1016;
+    --surface: #161a22;
+    --surface-alt: #1d222b;
+    --border: #2a2f3a;
+    --text: #e8eaed;
+    --text-muted: #9aa2b1;
+    --accent: #4c8dff;
+    --accent-hover: #6ea1ff;
+    --focus-ring: rgba(76, 141, 255, 0.4);
+    --success-bg: rgba(34, 197, 94, 0.16);
+    --success-text: #4ade80;
+    --danger-bg: rgba(239, 68, 68, 0.16);
+    --danger-text: #f87171;
+    --warn-bg: rgba(234, 179, 8, 0.16);
+    --warn-text: #fbbf24;
+    --shadow: 0 1px 2px rgba(0, 0, 0, 0.35), 0 2px 10px rgba(0, 0, 0, 0.35);
+    --shadow-hover: 0 10px 24px rgba(0, 0, 0, 0.45);
+    --overlay: rgba(0, 0, 0, 0.55);
+    --overlay-hover: rgba(248, 113, 113, 0.35);
+    --color-scheme: dark;
+  }
+}
+:root[data-theme="dark"] {
+  --bg: #0d1016;
+  --surface: #161a22;
+  --surface-alt: #1d222b;
+  --border: #2a2f3a;
+  --text: #e8eaed;
+  --text-muted: #9aa2b1;
+  --accent: #4c8dff;
+  --accent-hover: #6ea1ff;
+  --focus-ring: rgba(76, 141, 255, 0.4);
+  --success-bg: rgba(34, 197, 94, 0.16);
+  --success-text: #4ade80;
+  --danger-bg: rgba(239, 68, 68, 0.16);
+  --danger-text: #f87171;
+  --warn-bg: rgba(234, 179, 8, 0.16);
+  --warn-text: #fbbf24;
+  --shadow: 0 1px 2px rgba(0, 0, 0, 0.35), 0 2px 10px rgba(0, 0, 0, 0.35);
+  --shadow-hover: 0 10px 24px rgba(0, 0, 0, 0.45);
+  --overlay: rgba(0, 0, 0, 0.55);
+  --overlay-hover: rgba(248, 113, 113, 0.35);
+  --color-scheme: dark;
+}
+
+* { box-sizing: border-box; }
+
+html {
+  color-scheme: var(--color-scheme);
+}
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  background: var(--bg);
+  color: var(--text);
+  -webkit-font-smoothing: antialiased;
+  transition: background-color .15s ease, color .15s ease;
+}
+
+.page {
+  max-width: 1080px;
+  margin: 0 auto;
+  padding: 28px 20px 72px;
+}
+.page.page-narrow {
+  max-width: 420px;
+  padding-top: 88px;
+}
+
+.topbar {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 24px;
+}
+.brand { display: flex; align-items: flex-start; gap: 12px; }
+.brand-mark {
+  font-size: 26px;
+  line-height: 1;
+  margin-top: 2px;
+}
+h1 { font-size: 21px; margin: 0; letter-spacing: -0.01em; font-weight: 700; }
+p.sub { color: var(--text-muted); font-size: 13.5px; margin: 5px 0 0; line-height: 1.5; }
+
+.icon-btn {
+  flex: none;
+  width: 38px;
+  height: 38px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  background: var(--surface);
+  color: var(--text);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 16px;
+  cursor: pointer;
+  box-shadow: var(--shadow);
+  transition: background-color .15s ease, border-color .15s ease, transform .1s ease;
+}
+.icon-btn:hover { background: var(--surface-alt); }
+.icon-btn:active { transform: scale(0.94); }
+
+.topbar-actions { display: flex; align-items: center; gap: 14px; }
+.topnav { display: flex; align-items: center; gap: 14px; font-size: 13.5px; }
+.topnav a { color: var(--text-muted); text-decoration: none; }
+.topnav a:hover { color: var(--text); }
+.inline-form { display: inline; margin: 0; }
+button.linklike {
+  background: none;
+  border: none;
+  padding: 0;
+  margin: 0;
+  color: var(--text-muted);
+  font-size: 13.5px;
+  font-weight: 400;
+  cursor: pointer;
+  box-shadow: none;
+}
+button.linklike:hover { color: var(--text); background: none; }
+
+.admin-table { width: 100%; border-collapse: collapse; font-size: 13.5px; }
+.admin-table th { text-align: left; color: var(--text-muted); font-weight: 600; padding: 6px 8px 6px 0; border-bottom: 1px solid var(--border); }
+.admin-table td { padding: 8px 8px 8px 0; border-bottom: 1px solid var(--border); vertical-align: top; }
+.admin-actions form { margin: 4px 0 0; }
+.admin-actions details summary { cursor: pointer; color: var(--text-muted); font-size: 13px; }
+.admin-actions input[type="password"] { margin-top: 6px; }
+.admin-frame { border-bottom: 1px solid var(--border); padding: 10px 0; }
+.admin-frame:last-child { border-bottom: none; }
+.admin-inline-form { display: flex; gap: 8px; align-items: center; margin-top: 6px; }
+.admin-inline-form input[type="text"] { margin-top: 0; flex: 1; }
+
+h2.card-title, summary.card-title {
+  font-size: 14.5px;
+  font-weight: 650;
+  margin: 0 0 14px;
+  letter-spacing: 0.01em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+summary.card-title { cursor: pointer; margin-bottom: 0; }
+details.card[open] summary.card-title { margin-bottom: 14px; }
+details.card .sub { margin-top: 8px; }
+
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  padding: 20px 22px 22px;
+  box-shadow: var(--shadow);
+}
+.card + .card { margin-top: 20px; }
+
+label { display: block; margin-top: 16px; font-size: 13px; font-weight: 600; color: var(--text); }
+label:first-child { margin-top: 0; }
+
+input, select {
+  width: 100%;
+  padding: 9px 10px;
+  box-sizing: border-box;
+  margin-top: 5px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  font-size: 14px;
+  background: var(--bg);
+  color: var(--text);
+  font-family: inherit;
+  transition: border-color .15s ease, box-shadow .15s ease;
+}
+input:focus, select:focus {
+  outline: none;
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px var(--focus-ring);
+}
+
+.checkbox-row { display: flex; align-items: center; gap: 8px; margin-top: 16px; }
+.checkbox-row input { width: auto; margin-top: 0; }
+.checkbox-row label { margin-top: 0; font-weight: normal; }
+
+button {
+  margin-top: 20px;
+  padding: 10px 16px;
+  border: none;
+  border-radius: 8px;
+  background: var(--accent);
+  color: white;
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 600;
+  font-family: inherit;
+  transition: background-color .15s ease, transform .1s ease;
+}
+button:hover { background: var(--accent-hover); }
+button:active { transform: translateY(1px); }
+button.btn-inline {
+  margin-top: 0;
+  padding: 3px 10px;
+  font-size: 12px;
+  vertical-align: middle;
+}
+button.secondary {
+  background: transparent;
+  color: var(--text);
+  border: 1px solid var(--border);
+  margin-right: 8px;
+}
+button.secondary:hover { background: var(--surface-alt); }
+
+.status { margin-top: 16px; padding: 10px 12px; border-radius: 8px; font-size: 14px; }
+.status.ok { background: var(--success-bg); color: var(--success-text); }
+.status.err { background: var(--danger-bg); color: var(--danger-text); }
+.info-box {
+  margin-bottom: 20px;
+  padding: 12px 14px;
+  border-radius: 10px;
+  font-size: 13px;
+  background: var(--surface-alt);
+  color: var(--text-muted);
+  border: 1px solid var(--border);
+}
+.info-box.warn { background: var(--warn-bg); color: var(--warn-text); border-color: transparent; }
+
+code {
+  background: var(--surface-alt);
+  color: var(--text);
+  padding: 2px 5px;
+  border-radius: 4px;
+  font-size: 0.92em;
+}
+.info-box code, .info-box.warn code { background: rgba(127, 127, 127, 0.18); color: inherit; }
+
+.thumb { width: 160px; max-width: 100%; border-radius: 8px; display: block; }
+
+.photo-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(110px, 1fr)); gap: 10px; margin-top: 8px; }
+.photo-card {
+  position: relative; cursor: grab; border-radius: 8px; overflow: hidden; aspect-ratio: 1;
+  background: var(--surface-alt); border: 1px solid var(--border);
+  box-shadow: var(--shadow);
+  transition: box-shadow .15s ease, transform .15s ease;
+  /* pan-y (not none): lets a normal touch-scroll of the page work
+     when you touch a card without meaning to drag it. Dragging on
+     touch instead requires a brief hold first (see the JS below),
+     which switches this to "none" for the rest of that touch --
+     only once we're sure it's a deliberate drag, not a scroll. */
+  touch-action: pan-y;
+  /* Without this, a press-and-drag gesture also triggers the
+     browser's native text/content selection (the blue highlight) --
+     distracting, and on some browsers it fights the pointer-based
+     drag tracking below closely enough to break it outright. */
+  user-select: none;
+  -webkit-user-select: none;
+}
+.photo-card:hover { box-shadow: var(--shadow-hover); transform: translateY(-1px); }
+.photo-card:active { cursor: grabbing; }
+.photo-card.drag-armed {
+  box-shadow: 0 0 0 3px var(--focus-ring) inset;
+  transform: scale(0.97);
+}
+/* No transform transition here -- the JS drives transform on every
+   pointermove to track the finger 1:1, and the .15s base transition
+   would otherwise make it visibly lag behind a fast swipe. */
+.photo-card.dragging {
+  z-index: 20;
+  box-shadow: 0 16px 32px rgba(0, 0, 0, 0.35);
+  transition: box-shadow .15s ease;
+  pointer-events: none; /* so elementFromPoint hits the card underneath, not this one */
+  cursor: grabbing;
+}
+.photo-card.drag-over { outline: 3px solid var(--accent); outline-offset: -3px; }
+.photo-card img { width: 100%; height: 100%; object-fit: cover; display: block; pointer-events: none; }
+.photo-card .badge { position: absolute; top: 6px; left: 6px; background: var(--overlay); color: white; font-size: 10px; padding: 2px 6px; border-radius: 4px; }
+.photo-card .remove-btn, .thumb-wrap .remove-btn {
+  position: absolute; top: 6px; right: 6px; width: 22px; height: 22px; margin: 0; padding: 0;
+  line-height: 20px; text-align: center; font-size: 13px; border-radius: 50%;
+  background: var(--overlay); color: white;
+}
+.photo-card .remove-btn:hover, .thumb-wrap .remove-btn:hover { background: var(--overlay-hover); }
+.photo-card .show-next {
+  position: absolute; bottom: 6px; left: 6px; right: 6px; margin: 0; padding: 5px 0;
+  font-size: 11px; text-align: center; background: rgba(37, 99, 235, 0.85); border-radius: 4px;
+}
+.thumb-wrap { position: relative; display: inline-block; }
+
+.layout {
+  display: grid;
+  grid-template-columns: minmax(0, 1.05fr) minmax(0, 0.95fr);
+  gap: 20px;
+  align-items: start;
+}
+.main-col, .side-col { display: flex; flex-direction: column; }
+@media (max-width: 860px) {
+  .layout { grid-template-columns: 1fr; }
+}
+/* ------------------------------------------------------------------ */
+/* App shell: left sidebar (frame list + account nav) + main content. */
+/* Used by app_base.html for all logged-in pages; the narrow auth/    */
+/* manage pages keep the simple centered .page layout above.          */
+/* ------------------------------------------------------------------ */
+
+.shell { display: flex; min-height: 100vh; }
+
+.sidebar {
+  width: 248px;
+  flex: none;
+  display: flex;
+  flex-direction: column;
+  background: var(--surface);
+  border-right: 1px solid var(--border);
+  padding: 20px 14px 16px;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow-y: auto;
+}
+.sidebar .brand { display: flex; align-items: center; gap: 10px; padding: 0 8px 18px; }
+.sidebar .brand h1 { font-size: 17px; }
+.sidebar-section {
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  padding: 14px 8px 6px;
+}
+.sidebar a.nav-item, .sidebar .nav-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 9px 10px;
+  border-radius: 8px;
+  color: var(--text);
+  text-decoration: none;
+  font-size: 14px;
+  transition: background-color .12s ease;
+}
+.sidebar a.nav-item:hover { background: var(--surface-alt); }
+.sidebar a.nav-item.active { background: var(--surface-alt); font-weight: 600; }
+.nav-item .frame-dot {
+  width: 8px; height: 8px; border-radius: 50%; flex: none;
+  background: var(--text-muted); opacity: 0.5;
+}
+.nav-item.online .frame-dot { background: #22c55e; opacity: 1; }
+.nav-item .nav-sub { margin-left: auto; font-size: 11.5px; color: var(--text-muted); }
+.sidebar-footer { margin-top: auto; padding-top: 14px; border-top: 1px solid var(--border); }
+.sidebar-footer .nav-item { color: var(--text-muted); font-size: 13.5px; }
+.sidebar-footer form { margin: 0; }
+.sidebar-footer button.linklike {
+  display: block; width: 100%; text-align: left; padding: 9px 10px; border-radius: 8px;
+}
+.sidebar-footer button.linklike:hover { background: var(--surface-alt); }
+
+.main {
+  flex: 1;
+  min-width: 0;
+  padding: 24px 28px 72px;
+  max-width: 1160px;
+}
+
+.page-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 18px;
+  flex-wrap: wrap;
+}
+.page-head h1 { font-size: 21px; margin: 0; letter-spacing: -0.01em; font-weight: 700; }
+.page-head .head-actions { display: flex; align-items: center; gap: 10px; }
+
+.tabs {
+  display: flex;
+  gap: 4px;
+  margin-bottom: 20px;
+  border-bottom: 1px solid var(--border);
+}
+.tabs a {
+  padding: 9px 14px;
+  font-size: 14px;
+  color: var(--text-muted);
+  text-decoration: none;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -1px;
+  transition: color .12s ease;
+}
+.tabs a:hover { color: var(--text); }
+.tabs a.active { color: var(--accent); border-bottom-color: var(--accent); font-weight: 600; }
+
+.control-banner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
+  margin-bottom: 18px;
+  padding: 10px 14px;
+  border-radius: 10px;
+  font-size: 13.5px;
+  background: var(--warn-bg);
+  color: var(--warn-text);
+}
+.control-banner button { margin: 0; }
+
+/* Mobile: sidebar off-canvas, hamburger in a slim top bar. */
+.mobile-bar { display: none; }
+.sidebar-backdrop { display: none; }
+@media (max-width: 860px) {
+  .mobile-bar {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    position: sticky;
+    top: 0;
+    z-index: 30;
+    background: var(--surface);
+    border-bottom: 1px solid var(--border);
+    padding: 10px 14px;
+  }
+  .mobile-bar .brand { display: flex; align-items: center; gap: 8px; }
+  .mobile-bar h1 { font-size: 16px; margin: 0; }
+  .mobile-bar .icon-btn { width: 34px; height: 34px; box-shadow: none; }
+  .mobile-bar .spacer { flex: 1; }
+
+  .shell { display: block; }
+  .sidebar {
+    position: fixed;
+    left: 0; top: 0; bottom: 0;
+    z-index: 50;
+    height: 100vh;
+    transform: translateX(-105%);
+    transition: transform .2s ease;
+    box-shadow: var(--shadow-hover);
+  }
+  .shell.sidebar-open .sidebar { transform: translateX(0); }
+  .sidebar-backdrop {
+    position: fixed; inset: 0; z-index: 40;
+    background: var(--overlay);
+    opacity: 0; pointer-events: none;
+    transition: opacity .2s ease;
+  }
+  .shell.sidebar-open .sidebar-backdrop { display: block; opacity: 1; pointer-events: auto; }
+  .sidebar-backdrop { display: block; }
+
+  .main { padding: 18px 14px 64px; }
+}

server/app/templates/_frame_tabs.html

@@ -0,0 +1,5 @@
+<nav class="tabs">
+  <a href="/frames/{{ frame.id }}" class="{% if active_tab == 'photos' %}active{% endif %}">Photos</a>
+  <a href="/frames/{{ frame.id }}/config" class="{% if active_tab == 'config' %}active{% endif %}">Configuration</a>
+  <a href="/frames/{{ frame.id }}/stats" class="{% if active_tab == 'stats' %}active{% endif %}">Stats</a>
+</nav>

server/app/templates/admin.html

@@ -0,0 +1,99 @@
+{% extends "app_base.html" %}
+
+{% block title %}Admin{% endblock %}
+{% block page_title %}Administration{% endblock %}
+
+{% block content %}
+  {% if notice %}<div class="status ok">{{ notice }}</div>{% endif %}
+  {% if error %}<div class="status err">{{ error }}</div>{% endif %}
+
+  <div class="layout">
+    <div class="main-col">
+      <section class="card">
+        <h2 class="card-title">Users</h2>
+        <table class="admin-table">
+          <thead><tr><th>Username</th><th>Display name</th><th>Role</th><th></th></tr></thead>
+          <tbody>
+            {% for u in users %}
+              <tr>
+                <td>{{ u.username }}</td>
+                <td>{{ u.display_name }}</td>
+                <td>{{ "admin" if u.is_admin else "user" }}</td>
+                <td class="admin-actions">
+                  <details>
+                    <summary>Reset password</summary>
+                    <form method="post" action="/admin/users/{{ u.id }}/reset-password">
+                      <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+                      <input type="password" name="password" minlength="8" placeholder="New password" required>
+                      <button type="submit" class="secondary btn-inline">Reset</button>
+                    </form>
+                  </details>
+                  {% if u.id != user.id %}
+                    <form method="post" action="/admin/users/{{ u.id }}/delete"
+                          onsubmit="return confirm('Delete user {{ u.username }}?');">
+                      <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+                      <button type="submit" class="secondary btn-inline">Delete</button>
+                    </form>
+                  {% endif %}
+                </td>
+              </tr>
+            {% endfor %}
+          </tbody>
+        </table>
+
+        <h2 class="card-title" style="margin-top: 24px;">Enroll a user</h2>
+        <form method="post" action="/admin/users">
+          <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+          <label>Username
+            <input type="text" name="username" maxlength="64" required>
+          </label>
+          <label>Password
+            <input type="password" name="password" minlength="8" required autocomplete="new-password">
+          </label>
+          <div class="checkbox-row">
+            <input type="checkbox" id="is_admin" name="is_admin" value="true">
+            <label for="is_admin">Administrator</label>
+          </div>
+          <button type="submit">Create user</button>
+        </form>
+      </section>
+    </div>
+
+    <div class="side-col">
+      <section class="card">
+        <h2 class="card-title">Frames</h2>
+        {% for f in frames %}
+          <div class="admin-frame">
+            <p class="sub">
+              <strong>#{{ f.id }} {{ f.name }}</strong><br>
+              device: <code>{{ f.device_id or "not yet reported" }}</code><br>
+              owner: {{ (f.owner.username if f.owner else none) or "UNCLAIMED" }}
+              &middot; linked: {{ links_by_frame.get(f.id, []) | map(attribute="username") | join(", ") or "nobody" }}<br>
+              firmware: {{ f.device_firmware_version or "?" }} ({{ f.device_board_variant or "board unknown" }})
+              &middot; token ack: {{ "yes" if f.device_token_ack else "no" }}
+              {% if f.legacy_token_enabled %}&middot; <strong>legacy token window OPEN</strong>{% endif %}
+            </p>
+            <form method="post" action="/admin/frames/{{ f.id }}/link-user" class="admin-inline-form">
+              <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+              <input type="text" name="username" placeholder="Link user by name" required>
+              <button type="submit" class="secondary btn-inline">Link</button>
+            </form>
+            {% if f.legacy_token_enabled %}
+              <form method="post" action="/admin/frames/{{ f.id }}/end-legacy" class="admin-inline-form"
+                    onsubmit="return confirm('Close the legacy-token window for frame #{{ f.id }}? Only do this once the device has acknowledged its own token.');">
+                <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+                <button type="submit" class="secondary btn-inline">Close legacy window</button>
+              </form>
+            {% endif %}
+            <form method="post" action="/admin/frames/{{ f.id }}/delete" class="admin-inline-form"
+                  onsubmit="return confirm('Delete frame #{{ f.id }} and all its history?');">
+              <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+              <button type="submit" class="secondary btn-inline">Delete</button>
+            </form>
+          </div>
+        {% endfor %}
+        {% if not frames %}<p class="sub">No frames yet.</p>{% endif %}
+      </section>
+    </div>
+  </div>
+{% endblock %}

server/app/templates/app_base.html

@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>{% block title %}ESPresso Frame{% endblock %}</title>
+  {% if csrf_token %}<meta name="csrf-token" content="{{ csrf_token }}">{% endif %}
+  <script>
+    // Applied before first paint so there's no flash of the wrong theme.
+    (function () {
+      try {
+        var stored = localStorage.getItem('theme');
+        if (stored === 'light' || stored === 'dark') {
+          document.documentElement.setAttribute('data-theme', stored);
+        }
+      } catch (e) { /* localStorage unavailable (private mode, etc.) */ }
+    })();
+  </script>
+  <link rel="stylesheet" href="/static/theme.css">
+  {% block extra_head %}{% endblock %}
+</head>
+<body>
+  <div class="shell">
+    <div class="sidebar-backdrop"></div>
+    <aside class="sidebar">
+      <div class="brand">
+        <span class="brand-mark" aria-hidden="true">☕</span>
+        <h1>ESPresso Frame</h1>
+      </div>
+
+      <div class="sidebar-section">Frames</div>
+      {% for f in sidebar_frames %}
+        <a class="nav-item {% if active_frame and active_frame.id == f.id %}active{% endif %} {% if f.recently_seen %}online{% endif %}"
+           href="/frames/{{ f.id }}">
+          <span class="frame-dot" aria-hidden="true"></span>
+          {{ f.name or ("Frame " ~ f.id) }}
+          {% if f.owner_user_id is none %}<span class="nav-sub">unclaimed</span>{% endif %}
+        </a>
+      {% endfor %}
+      {% if not sidebar_frames %}
+        <p class="sub" style="padding: 0 10px;">No frames yet.</p>
+      {% endif %}
+
+      <div class="sidebar-footer">
+        <a class="nav-item {% if active_nav == 'settings' %}active{% endif %}" href="/settings">Settings</a>
+        {% if user.is_admin %}
+          <a class="nav-item {% if active_nav == 'admin' %}active{% endif %}" href="/admin">Admin</a>
+        {% endif %}
+        <form method="post" action="/logout">
+          <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+          <button type="submit" class="linklike">Log out</button>
+        </form>
+      </div>
+    </aside>
+
+    <div class="main-wrap" style="flex: 1; min-width: 0;">
+      <div class="mobile-bar">
+        <button type="button" id="sidebar-toggle" class="icon-btn" title="Menu" aria-label="Open menu">☰</button>
+        <div class="brand"><span aria-hidden="true">☕</span><h1>ESPresso Frame</h1></div>
+        <div class="spacer"></div>
+      </div>
+
+      <main class="main">
+        <div class="page-head">
+          <h1>{% block page_title %}{% endblock %}</h1>
+          <div class="head-actions">
+            {% block head_actions %}{% endblock %}
+            <button type="button" id="theme-toggle" class="icon-btn" title="Toggle dark mode" aria-label="Toggle dark mode">🌓</button>
+          </div>
+        </div>
+        {% block tabs %}{% endblock %}
+        {% block content %}{% endblock %}
+      </main>
+    </div>
+  </div>
+
+  <script src="/static/common.js"></script>
+  {% block scripts %}{% endblock %}
+</body>
+</html>

server/app/templates/base.html

@@ -4,6 +4,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>{% block title %}ESPresso Frame{% endblock %}</title>
+  {% if csrf_token %}<meta name="csrf-token" content="{{ csrf_token }}">{% endif %}
   <script>
     // Applied before first paint so there's no flash of the wrong theme.
     (function () {
@@ -15,292 +16,7 @@
       } catch (e) { /* localStorage unavailable (private mode, etc.) */ }
     })();
   </script>
-  <style>
-    :root {
-      --bg: #f5f6f8;
-      --surface: #ffffff;
-      --surface-alt: #f0f1f4;
-      --border: #e3e5e9;
-      --text: #16181d;
-      --text-muted: #666d7a;
-      --accent: #2563eb;
-      --accent-hover: #1d4ed8;
-      --focus-ring: rgba(37, 99, 235, 0.35);
-      --success-bg: #dcfce7;
-      --success-text: #166534;
-      --danger-bg: #fee2e2;
-      --danger-text: #991b1b;
-      --warn-bg: #fef9c3;
-      --warn-text: #854d0e;
-      --shadow: 0 1px 2px rgba(16, 24, 40, 0.04), 0 1px 3px rgba(16, 24, 40, 0.06);
-      --shadow-hover: 0 8px 20px rgba(16, 24, 40, 0.10);
-      --overlay: rgba(0, 0, 0, 0.55);
-      --overlay-hover: rgba(153, 27, 27, 0.85);
-      --color-scheme: light;
-    }
-    @media (prefers-color-scheme: dark) {
-      :root:not([data-theme="light"]) {
-        --bg: #0d1016;
-        --surface: #161a22;
-        --surface-alt: #1d222b;
-        --border: #2a2f3a;
-        --text: #e8eaed;
-        --text-muted: #9aa2b1;
-        --accent: #4c8dff;
-        --accent-hover: #6ea1ff;
-        --focus-ring: rgba(76, 141, 255, 0.4);
-        --success-bg: rgba(34, 197, 94, 0.16);
-        --success-text: #4ade80;
-        --danger-bg: rgba(239, 68, 68, 0.16);
-        --danger-text: #f87171;
-        --warn-bg: rgba(234, 179, 8, 0.16);
-        --warn-text: #fbbf24;
-        --shadow: 0 1px 2px rgba(0, 0, 0, 0.35), 0 2px 10px rgba(0, 0, 0, 0.35);
-        --shadow-hover: 0 10px 24px rgba(0, 0, 0, 0.45);
-        --overlay: rgba(0, 0, 0, 0.55);
-        --overlay-hover: rgba(248, 113, 113, 0.35);
-        --color-scheme: dark;
-      }
-    }
-    :root[data-theme="dark"] {
-      --bg: #0d1016;
-      --surface: #161a22;
-      --surface-alt: #1d222b;
-      --border: #2a2f3a;
-      --text: #e8eaed;
-      --text-muted: #9aa2b1;
-      --accent: #4c8dff;
-      --accent-hover: #6ea1ff;
-      --focus-ring: rgba(76, 141, 255, 0.4);
-      --success-bg: rgba(34, 197, 94, 0.16);
-      --success-text: #4ade80;
-      --danger-bg: rgba(239, 68, 68, 0.16);
-      --danger-text: #f87171;
-      --warn-bg: rgba(234, 179, 8, 0.16);
-      --warn-text: #fbbf24;
-      --shadow: 0 1px 2px rgba(0, 0, 0, 0.35), 0 2px 10px rgba(0, 0, 0, 0.35);
-      --shadow-hover: 0 10px 24px rgba(0, 0, 0, 0.45);
-      --overlay: rgba(0, 0, 0, 0.55);
-      --overlay-hover: rgba(248, 113, 113, 0.35);
-      --color-scheme: dark;
-    }
-
-    * { box-sizing: border-box; }
-
-    html {
-      color-scheme: var(--color-scheme);
-    }
-
-    body {
-      margin: 0;
-      font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-      background: var(--bg);
-      color: var(--text);
-      -webkit-font-smoothing: antialiased;
-      transition: background-color .15s ease, color .15s ease;
-    }
-
-    .page {
-      max-width: 1080px;
-      margin: 0 auto;
-      padding: 28px 20px 72px;
-    }
-    .page.page-narrow {
-      max-width: 420px;
-      padding-top: 88px;
-    }
-
-    .topbar {
-      display: flex;
-      align-items: flex-start;
-      justify-content: space-between;
-      gap: 16px;
-      margin-bottom: 24px;
-    }
-    .brand { display: flex; align-items: flex-start; gap: 12px; }
-    .brand-mark {
-      font-size: 26px;
-      line-height: 1;
-      margin-top: 2px;
-    }
-    h1 { font-size: 21px; margin: 0; letter-spacing: -0.01em; font-weight: 700; }
-    p.sub { color: var(--text-muted); font-size: 13.5px; margin: 5px 0 0; line-height: 1.5; }
-
-    .icon-btn {
-      flex: none;
-      width: 38px;
-      height: 38px;
-      border-radius: 50%;
-      border: 1px solid var(--border);
-      background: var(--surface);
-      color: var(--text);
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      font-size: 16px;
-      cursor: pointer;
-      box-shadow: var(--shadow);
-      transition: background-color .15s ease, border-color .15s ease, transform .1s ease;
-    }
-    .icon-btn:hover { background: var(--surface-alt); }
-    .icon-btn:active { transform: scale(0.94); }
-
-    h2.card-title, summary.card-title {
-      font-size: 14.5px;
-      font-weight: 650;
-      margin: 0 0 14px;
-      letter-spacing: 0.01em;
-      text-transform: uppercase;
-      color: var(--text-muted);
-    }
-    summary.card-title { cursor: pointer; margin-bottom: 0; }
-    details.card[open] summary.card-title { margin-bottom: 14px; }
-    details.card .sub { margin-top: 8px; }
-
-    .card {
-      background: var(--surface);
-      border: 1px solid var(--border);
-      border-radius: 14px;
-      padding: 20px 22px 22px;
-      box-shadow: var(--shadow);
-    }
-    .card + .card { margin-top: 20px; }
-
-    label { display: block; margin-top: 16px; font-size: 13px; font-weight: 600; color: var(--text); }
-    label:first-child { margin-top: 0; }
-
-    input, select {
-      width: 100%;
-      padding: 9px 10px;
-      box-sizing: border-box;
-      margin-top: 5px;
-      border: 1px solid var(--border);
-      border-radius: 8px;
-      font-size: 14px;
-      background: var(--bg);
-      color: var(--text);
-      font-family: inherit;
-      transition: border-color .15s ease, box-shadow .15s ease;
-    }
-    input:focus, select:focus {
-      outline: none;
-      border-color: var(--accent);
-      box-shadow: 0 0 0 3px var(--focus-ring);
-    }
-
-    .checkbox-row { display: flex; align-items: center; gap: 8px; margin-top: 16px; }
-    .checkbox-row input { width: auto; margin-top: 0; }
-    .checkbox-row label { margin-top: 0; font-weight: normal; }
-
-    button {
-      margin-top: 20px;
-      padding: 10px 16px;
-      border: none;
-      border-radius: 8px;
-      background: var(--accent);
-      color: white;
-      cursor: pointer;
-      font-size: 14px;
-      font-weight: 600;
-      font-family: inherit;
-      transition: background-color .15s ease, transform .1s ease;
-    }
-    button:hover { background: var(--accent-hover); }
-    button:active { transform: translateY(1px); }
-    button.secondary {
-      background: transparent;
-      color: var(--text);
-      border: 1px solid var(--border);
-      margin-right: 8px;
-    }
-    button.secondary:hover { background: var(--surface-alt); }
-
-    .status { margin-top: 16px; padding: 10px 12px; border-radius: 8px; font-size: 14px; }
-    .status.ok { background: var(--success-bg); color: var(--success-text); }
-    .status.err { background: var(--danger-bg); color: var(--danger-text); }
-    .info-box {
-      margin-bottom: 20px;
-      padding: 12px 14px;
-      border-radius: 10px;
-      font-size: 13px;
-      background: var(--surface-alt);
-      color: var(--text-muted);
-      border: 1px solid var(--border);
-    }
-    .info-box.warn { background: var(--warn-bg); color: var(--warn-text); border-color: transparent; }
-
-    code {
-      background: var(--surface-alt);
-      color: var(--text);
-      padding: 2px 5px;
-      border-radius: 4px;
-      font-size: 0.92em;
-    }
-    .info-box code, .info-box.warn code { background: rgba(127, 127, 127, 0.18); color: inherit; }
-
-    .thumb { width: 160px; max-width: 100%; border-radius: 8px; display: block; }
-
-    .photo-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(110px, 1fr)); gap: 10px; margin-top: 8px; }
-    .photo-card {
-      position: relative; cursor: grab; border-radius: 8px; overflow: hidden; aspect-ratio: 1;
-      background: var(--surface-alt); border: 1px solid var(--border);
-      box-shadow: var(--shadow);
-      transition: box-shadow .15s ease, transform .15s ease;
-      /* pan-y (not none): lets a normal touch-scroll of the page work
-         when you touch a card without meaning to drag it. Dragging on
-         touch instead requires a brief hold first (see the JS below),
-         which switches this to "none" for the rest of that touch --
-         only once we're sure it's a deliberate drag, not a scroll. */
-      touch-action: pan-y;
-      /* Without this, a press-and-drag gesture also triggers the
-         browser's native text/content selection (the blue highlight) --
-         distracting, and on some browsers it fights the pointer-based
-         drag tracking below closely enough to break it outright. */
-      user-select: none;
-      -webkit-user-select: none;
-    }
-    .photo-card:hover { box-shadow: var(--shadow-hover); transform: translateY(-1px); }
-    .photo-card:active { cursor: grabbing; }
-    .photo-card.drag-armed {
-      box-shadow: 0 0 0 3px var(--focus-ring) inset;
-      transform: scale(0.97);
-    }
-    /* No transform transition here -- the JS drives transform on every
-       pointermove to track the finger 1:1, and the .15s base transition
-       would otherwise make it visibly lag behind a fast swipe. */
-    .photo-card.dragging {
-      z-index: 20;
-      box-shadow: 0 16px 32px rgba(0, 0, 0, 0.35);
-      transition: box-shadow .15s ease;
-      pointer-events: none; /* so elementFromPoint hits the card underneath, not this one */
-      cursor: grabbing;
-    }
-    .photo-card.drag-over { outline: 3px solid var(--accent); outline-offset: -3px; }
-    .photo-card img { width: 100%; height: 100%; object-fit: cover; display: block; pointer-events: none; }
-    .photo-card .badge { position: absolute; top: 6px; left: 6px; background: var(--overlay); color: white; font-size: 10px; padding: 2px 6px; border-radius: 4px; }
-    .photo-card .remove-btn, .thumb-wrap .remove-btn {
-      position: absolute; top: 6px; right: 6px; width: 22px; height: 22px; margin: 0; padding: 0;
-      line-height: 20px; text-align: center; font-size: 13px; border-radius: 50%;
-      background: var(--overlay); color: white;
-    }
-    .photo-card .remove-btn:hover, .thumb-wrap .remove-btn:hover { background: var(--overlay-hover); }
-    .photo-card .show-next {
-      position: absolute; bottom: 6px; left: 6px; right: 6px; margin: 0; padding: 5px 0;
-      font-size: 11px; text-align: center; background: rgba(37, 99, 235, 0.85); border-radius: 4px;
-    }
-    .thumb-wrap { position: relative; display: inline-block; }
-
-    .layout {
-      display: grid;
-      grid-template-columns: minmax(0, 1.05fr) minmax(0, 0.95fr);
-      gap: 20px;
-      align-items: start;
-    }
-    .main-col, .side-col { display: flex; flex-direction: column; }
-    @media (max-width: 860px) {
-      .layout { grid-template-columns: 1fr; }
-    }
-  </style>
+  <link rel="stylesheet" href="/static/theme.css">
   {% block extra_head %}{% endblock %}
 </head>
 <body>
@@ -319,32 +35,7 @@
     {% block content %}{% endblock %}
   </div>
 
-  <script>
-    // Shared theme toggle: explicit choice wins over the OS preference and
-    // is remembered; with no explicit choice, the CSS above falls back to
-    // prefers-color-scheme on its own.
-    (function () {
-      var btn = document.getElementById('theme-toggle');
-      if (!btn) return;
-
-      function currentTheme() {
-        var stored = null;
-        try { stored = localStorage.getItem('theme'); } catch (e) { /* ignore */ }
-        if (stored === 'light' || stored === 'dark') return stored;
-        return (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light';
-      }
-
-      function apply(theme) {
-        document.documentElement.setAttribute('data-theme', theme);
-        try { localStorage.setItem('theme', theme); } catch (e) { /* ignore */ }
-        document.dispatchEvent(new CustomEvent('themechange', { detail: { theme: theme } }));
-      }
-
-      btn.addEventListener('click', function () {
-        apply(currentTheme() === 'dark' ? 'light' : 'dark');
-      });
-    })();
-  </script>
+  <script src="/static/common.js"></script>
   {% block scripts %}{% endblock %}
 </body>
 </html>

server/app/templates/claim.html

@@ -0,0 +1,72 @@
+{% extends "base.html" %}
+
+{% block page_class %}page-narrow{% endblock %}
+
+{% block subtitle %}
+<p class="sub">Claim your frame</p>
+{% endblock %}
+
+{% block extra_head %}
+  {% if status == "unregistered" %}<meta http-equiv="refresh" content="6">{% endif %}
+{% endblock %}
+
+{% block content %}
+  {% if error %}<div class="status err">{{ error }}</div>{% endif %}
+
+  <section class="card">
+    <h2 class="card-title">Frame <code>{{ device_id }}</code></h2>
+
+    {% if status == "claimed_yours" %}
+      <div class="status ok">This frame is linked to your account.</div>
+      <p class="sub">It will show up in your frame list. If it was just
+        provisioned, give it a minute to connect and fetch its first image.</p>
+      <p><a href="/">Go to your frames</a></p>
+
+    {% elif status == "claimed" %}
+      <p class="sub">This frame already belongs to someone. If it's yours,
+        ask them (or an admin) to link your account to it.</p>
+
+    {% elif status == "unregistered" %}
+      {% if pending_yours %}
+        <div class="status ok">Claim recorded.</div>
+        <p class="sub">Waiting for the frame to connect for the first time --
+          it links to your account automatically the moment it checks in.
+          This page refreshes itself; it's safe to close, too.</p>
+      {% else %}
+        <p class="sub">The frame hasn't checked in yet -- it's probably still
+          restarting and joining your WiFi. This page refreshes itself.
+          {% if user %}You can claim it now anyway; it'll attach when it
+          arrives.{% endif %}</p>
+      {% endif %}
+    {% elif status == "unclaimed" %}
+      <p class="sub">This frame is connected and ready to be claimed.</p>
+    {% endif %}
+
+    {% if user and status in ("unclaimed", "unregistered") and not pending_yours %}
+      <form method="post" action="/claim">
+        <input type="hidden" name="device_id" value="{{ device_id }}">
+        <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+        <button type="submit">Claim this frame</button>
+      </form>
+    {% endif %}
+  </section>
+
+  {% if not user and status in ("unclaimed", "unregistered") %}
+    <section class="card">
+      <h2 class="card-title">Create your account</h2>
+      <p class="sub">A valid frame is your invitation -- set up an account to
+        claim it. Already have one?
+        <a href="/login?next=/claim%3Fdevice_id%3D{{ device_id }}">Log in instead</a>.</p>
+      <form method="post" action="/claim/signup">
+        <input type="hidden" name="device_id" value="{{ device_id }}">
+        <label>Username
+          <input type="text" name="username" maxlength="64" required autocomplete="username">
+        </label>
+        <label>Password
+          <input type="password" name="password" minlength="8" required autocomplete="new-password">
+        </label>
+        <button type="submit">Create account &amp; claim frame</button>
+      </form>
+    </section>
+  {% endif %}
+{% endblock %}

server/app/templates/frame_config.html

@@ -0,0 +1,111 @@
+{% extends "app_base.html" %}
+
+{% block title %}{{ frame.name or "Frame" }} · Configuration{% endblock %}
+{% block page_title %}{{ frame.name or "Frame " ~ frame.id }}{% endblock %}
+
+{% block tabs %}{% include "_frame_tabs.html" %}{% endblock %}
+
+{% block content %}
+  <div id="control-banner" class="control-banner" style="display: none;">
+    <span id="control-holder"></span>
+    <button type="button" id="take-control" class="btn-inline">Take control</button>
+  </div>
+
+  <div class="layout">
+    <div class="main-col">
+      <section class="card">
+        <h2 class="card-title">Display settings</h2>
+        <form id="config-form">
+          <label>Frame name
+            <input type="text" id="frame_name" maxlength="64" value="{{ frame.name }}">
+          </label>
+          <label>Order
+            <select id="order">
+              <option value="sequential" {% if frame.order == "sequential" %}selected{% endif %}>Sequential</option>
+              <option value="shuffle" {% if frame.order == "shuffle" %}selected{% endif %}>Shuffle</option>
+            </select>
+          </label>
+          <label>Orientation
+            <select id="orientation">
+              <option value="landscape" {% if frame.orientation == "landscape" %}selected{% endif %}>Landscape</option>
+              <option value="portrait" {% if frame.orientation == "portrait" %}selected{% endif %}>Portrait</option>
+              <option value="landscape_flipped" {% if frame.orientation == "landscape_flipped" %}selected{% endif %}>Landscape (flipped)</option>
+              <option value="portrait_flipped" {% if frame.orientation == "portrait_flipped" %}selected{% endif %}>Portrait (flipped)</option>
+            </select>
+          </label>
+          <label>Refresh interval (minutes)
+            <input type="number" id="refresh_interval_minutes" min="1" max="1440"
+                   value="{{ (frame.refresh_interval_s // 60) or 60 }}" required>
+          </label>
+          <div class="checkbox-row">
+            <input type="checkbox" id="smart_crop_faces" {% if frame.smart_crop_faces %}checked{% endif %}>
+            <label for="smart_crop_faces">Center faces in crop</label>
+          </div>
+          <div class="checkbox-row">
+            <input type="checkbox" id="quiet_hours_enabled" {% if frame.quiet_hours_enabled %}checked{% endif %}>
+            <label for="quiet_hours_enabled">Quiet hours (don't wake overnight)</label>
+          </div>
+          <label>Quiet hours start
+            <input type="time" id="quiet_hours_start" value="{{ frame.quiet_hours_start }}">
+          </label>
+          <label>Quiet hours end
+            <input type="time" id="quiet_hours_end" value="{{ frame.quiet_hours_end }}">
+          </label>
+          <label>Timezone
+            <select id="timezone">
+              {% for tz in timezones %}
+                <option value="{{ tz }}" {% if tz == frame.timezone %}selected{% endif %}>{{ tz }}</option>
+              {% endfor %}
+            </select>
+          </label>
+          <p class="sub" style="margin-top: 8px;">Quiet hours times are
+            interpreted in this timezone. The device may still wake once right
+            at the start of quiet hours -- it can't know ahead of time -- but
+            goes right back to sleep until they end.</p>
+          <button type="submit">Save</button>
+        </form>
+      </section>
+    </div>
+
+    <div class="side-col">
+      <section class="card">
+        <h2 class="card-title">Firmware update</h2>
+        <p class="sub" id="firmware-board">
+          {% if frame.device_board_variant %}Detected board: {{ frame.device_board_variant }}
+          {% else %}Board not detected yet -- the frame reports it on its next check-in.{% endif %}
+        </p>
+        <p class="sub" id="firmware-available">
+          {% if frame.firmware_available_version %}Uploaded: v{{ frame.firmware_available_version }} -- the frame
+          updates itself on its next wake if it's running something else.{% else %}No firmware uploaded yet.{% endif %}
+        </p>
+        <input type="file" id="firmware-file" accept=".bin">
+        <button type="button" class="secondary" id="firmware-upload">Upload firmware</button>
+
+        <div id="firmware-repo-display" style="margin-top: 16px; {% if not frame.firmware_update_repo_url %}display: none;{% endif %}">
+          <p class="sub">Gitea repo: <code id="firmware-repo-text">{{ frame.firmware_update_repo_url }}</code>
+            <button type="button" class="secondary btn-inline" id="firmware-repo-edit-btn">Edit</button>
+          </p>
+        </div>
+        <label id="firmware-repo-edit" style="{% if frame.firmware_update_repo_url %}display: none;{% endif %}">Gitea repo URL
+          <input type="text" id="firmware_update_repo_url" placeholder="https://git.example.com/owner/repo"
+                 value="{{ frame.firmware_update_repo_url }}">
+        </label>
+        <div class="checkbox-row">
+          <input type="checkbox" id="firmware_auto_update" {% if frame.firmware_auto_update %}checked{% endif %}>
+          <label for="firmware_auto_update">Automatically apply updates</label>
+        </div>
+        <button type="button" class="secondary" id="firmware-settings-save">Save</button>
+        <p class="sub" id="firmware-gitea-status" style="display: none; margin-top: 10px;"></p>
+        <button type="button" class="secondary" id="firmware-check-now">Check now</button>
+        <button type="button" id="firmware-update-btn" style="display: none;">Update frame</button>
+      </section>
+    </div>
+  </div>
+
+  <div id="result"></div>
+{% endblock %}
+
+{% block scripts %}
+  <script>window.FRAME_API = {{ ("/api/frames/" ~ frame.id) | tojson }};</script>
+  <script src="/static/frame_config.js"></script>
+{% endblock %}

server/app/templates/frame_photos.html

@@ -0,0 +1,60 @@
+{% extends "app_base.html" %}
+
+{% block title %}{{ frame.name or "Frame" }} · Photos{% endblock %}
+{% block page_title %}{{ frame.name or "Frame " ~ frame.id }}{% endblock %}
+
+{% block tabs %}{% include "_frame_tabs.html" %}{% endblock %}
+
+{% block content %}
+  <div id="control-banner" class="control-banner" style="display: none;">
+    <span id="control-holder"></span>
+    <button type="button" id="take-control" class="btn-inline">Take control</button>
+  </div>
+
+  <div class="layout">
+    <div class="main-col">
+      <section class="card">
+        <h2 class="card-title">Album</h2>
+        <form id="photos-form">
+          <label>Album
+            <select id="album_id">
+              {% if frame.album_id %}<option value="{{ frame.album_id }}" selected>(current selection -- Load Albums to change)</option>{% endif %}
+            </select>
+          </label>
+          <label>Upcoming photos to show
+            <select id="queue_target_len">
+              {% for n in [5, 10, 15, 20, 25, 30, 40, 50] %}
+                <option value="{{ n }}" {% if frame.queue_target_len == n %}selected{% endif %}>{{ n }}</option>
+              {% endfor %}
+            </select>
+          </label>
+          <button type="button" class="secondary" id="load-albums">Load Albums</button>
+          <button type="submit">Save</button>
+        </form>
+      </section>
+    </div>
+
+    <div class="side-col">
+      <section class="card">
+        <h2 class="card-title">Now displaying</h2>
+        <div id="current-thumb"><p class="sub">Loading...</p></div>
+      </section>
+    </div>
+  </div>
+
+  <section class="card" style="margin-top: 20px;">
+    <h2 class="card-title">Upcoming</h2>
+    <p class="sub">Drag a photo to reorder (on touch, hold briefly first so a
+      normal scroll still works), "Show next" to jump it to the front, or
+      the &times; to remove it from rotation entirely.</p>
+    <div id="upcoming-grid" class="photo-grid"></div>
+  </section>
+
+  <div id="result"></div>
+{% endblock %}
+
+{% block scripts %}
+  <script>window.FRAME_API = {{ ("/api/frames/" ~ frame.id) | tojson }};</script>
+  <script src="/static/queue.js"></script>
+  <script src="/static/frame_photos.js"></script>
+{% endblock %}

server/app/templates/frame_stats.html

@@ -0,0 +1,37 @@
+{% extends "app_base.html" %}
+
+{% block title %}{{ frame.name or "Frame" }} · Stats{% endblock %}
+{% block page_title %}{{ frame.name or "Frame " ~ frame.id }}{% endblock %}
+
+{% block tabs %}{% include "_frame_tabs.html" %}{% endblock %}
+
+{% block content %}
+  <div class="layout">
+    <div class="main-col">
+      <section class="card">
+        <h2 class="card-title">Battery history</h2>
+        <div id="battery-chart-wrap"><p class="sub">Loading...</p></div>
+      </section>
+
+      <section class="card">
+        <h2 class="card-title">Lifetime stats</h2>
+        <div id="stats-box"><p class="sub">Loading...</p></div>
+      </section>
+    </div>
+
+    <div class="side-col">
+      <section class="card">
+        <h2 class="card-title">Device</h2>
+        <div id="device-status"><p class="sub">Loading...</p></div>
+      </section>
+    </div>
+  </div>
+
+  <div id="result"></div>
+{% endblock %}
+
+{% block scripts %}
+  <script>window.FRAME_API = {{ ("/api/frames/" ~ frame.id) | tojson }};</script>
+  <script src="/static/battery_chart.js"></script>
+  <script src="/static/frame_stats.js"></script>
+{% endblock %}

server/app/templates/frames_empty.html

@@ -0,0 +1,20 @@
+{% extends "app_base.html" %}
+
+{% block title %}ESPresso Frame{% endblock %}
+{% block page_title %}Welcome{% endblock %}
+
+{% block content %}
+  <section class="card">
+    <h2 class="card-title">No frames yet</h2>
+    <p class="sub">Set up a frame and it'll appear in the sidebar:</p>
+    <p class="sub">1. Power the frame on -- it opens a WiFi network named
+      <code>ESPRESSO_XXXXXX</code> and shows join instructions on its panel.</p>
+    <p class="sub">2. Join that network and fill in your WiFi details plus this
+      server's address.</p>
+    <p class="sub">3. Your browser lands on this server's claim page and links
+      the frame to your account automatically.</p>
+    <p class="sub" style="margin-top: 12px;">Already provisioned? Ask whoever
+      claimed it (or an admin) to link your account, or scan the frame's
+      on-panel manage QR.</p>
+  </section>
+{% endblock %}

server/app/templates/index.html

@@ -1,783 +0,0 @@
-{% extends "base.html" %}
-
-{% block subtitle %}
-<p class="sub">Point your frame's "Tools Server" field at this server's <code>host:port</code>.</p>
-{% endblock %}
-
-{% block content %}
-  {% if cfg.immich_url %}
-    <div class="info-box">Immich: <code>{{ cfg.immich_url }}</code> (API key configured). Set via
-      <code>IMMICH_URL</code>/<code>IMMICH_API_KEY</code> in <code>docker-compose.yml</code> -- see
-      <code>docker-compose.yml.example</code>.</div>
-  {% else %}
-    <div class="info-box warn">Immich isn't configured yet. Set <code>IMMICH_URL</code> and
-      <code>IMMICH_API_KEY</code> in <code>docker-compose.yml</code> (copy
-      <code>docker-compose.yml.example</code>) and restart the server.</div>
-  {% endif %}
-
-  <div class="layout">
-    <div class="main-col">
-    <section class="card config-panel">
-      <h2 class="card-title">Settings</h2>
-      <form id="config-form">
-        <label>Album
-          <select id="album_id">
-            {% if cfg.album_id %}<option value="{{ cfg.album_id }}" selected>(current selection -- reload to rename)</option>{% endif %}
-          </select>
-        </label>
-        <label>Order
-          <select id="order">
-            <option value="sequential" {% if cfg.order == "sequential" %}selected{% endif %}>Sequential</option>
-            <option value="shuffle" {% if cfg.order == "shuffle" %}selected{% endif %}>Shuffle</option>
-          </select>
-        </label>
-        <label>Orientation
-          <select id="orientation">
-            <option value="landscape" {% if cfg.orientation == "landscape" %}selected{% endif %}>Landscape</option>
-            <option value="portrait" {% if cfg.orientation == "portrait" %}selected{% endif %}>Portrait</option>
-            <option value="landscape_flipped" {% if cfg.orientation == "landscape_flipped" %}selected{% endif %}>Landscape (flipped)</option>
-            <option value="portrait_flipped" {% if cfg.orientation == "portrait_flipped" %}selected{% endif %}>Portrait (flipped)</option>
-          </select>
-        </label>
-        <label>Refresh interval (minutes)
-          <input type="number" id="refresh_interval_minutes" min="1" max="1440"
-                 value="{{ (cfg.refresh_interval_s // 60) or 60 }}" required>
-        </label>
-        <div class="checkbox-row">
-          <input type="checkbox" id="smart_crop_faces" {% if cfg.smart_crop_faces %}checked{% endif %}>
-          <label for="smart_crop_faces">Center faces in crop</label>
-        </div>
-        <div class="checkbox-row">
-          <input type="checkbox" id="quiet_hours_enabled" {% if cfg.quiet_hours_enabled %}checked{% endif %}>
-          <label for="quiet_hours_enabled">Quiet hours (don't wake overnight)</label>
-        </div>
-        <label>Quiet hours start
-          <input type="time" id="quiet_hours_start" value="{{ cfg.quiet_hours_start }}">
-        </label>
-        <label>Quiet hours end
-          <input type="time" id="quiet_hours_end" value="{{ cfg.quiet_hours_end }}">
-        </label>
-        <label>Timezone
-          <select id="timezone">
-            {% for tz in timezones %}
-              <option value="{{ tz }}" {% if tz == cfg.timezone %}selected{% endif %}>{{ tz }}</option>
-            {% endfor %}
-          </select>
-        </label>
-        <p class="sub" style="margin-top: 8px;">Quiet hours times above are
-          interpreted in this timezone. The device may still wake once right
-          at the start of quiet hours -- it can't know ahead of time -- but
-          goes right back to sleep until they end.</p>
-        <label>Upcoming photos to show
-          <select id="queue_target_len">
-            {% for n in [5, 10, 15, 20, 25, 30, 40, 50] %}
-              <option value="{{ n }}" {% if cfg.queue_target_len == n %}selected{% endif %}>{{ n }}</option>
-            {% endfor %}
-          </select>
-        </label>
-        <label>Firmware Gitea repo URL
-          <input type="text" id="firmware_update_repo_url" placeholder="https://git.example.com/owner/repo"
-                 value="{{ cfg.firmware_update_repo_url }}">
-        </label>
-        <label>Frame's board
-          <select id="firmware_board_variant">
-            <option value="xiao" {% if cfg.firmware_board_variant == "xiao" %}selected{% endif %}>Seeed XIAO ESP32-C6</option>
-            <option value="devkit" {% if cfg.firmware_board_variant == "devkit" %}selected{% endif %}>ESP32-C6-DevKitC-1</option>
-          </select>
-        </label>
-        <div class="checkbox-row">
-          <input type="checkbox" id="firmware_auto_update" {% if cfg.firmware_auto_update %}checked{% endif %}>
-          <label for="firmware_auto_update">Automatically apply updates</label>
-        </div>
-        <p class="sub" style="margin-top: 8px;">When a Gitea repo URL is set, the
-          server periodically checks its releases for a newer build for the
-          board above. With auto-apply off, an "Update frame" button appears
-          below when one's found; with it on, the server stages the new
-          build itself -- the frame still only updates on its own next wake.</p>
-        <button type="button" class="secondary" id="load-albums">Load Albums</button>
-        <button type="submit">Save</button>
-      </form>
-      <div id="result"></div>
-    </section>
-
-    <details class="card">
-      <summary class="card-title">Stats</summary>
-      <div id="stats-box"><p class="sub">Loading...</p></div>
-    </details>
-    </div>
-
-    <div class="side-col">
-      <section class="card">
-        <h2 class="card-title">Now displaying</h2>
-        <div id="current-thumb"><p class="sub">Loading...</p></div>
-      </section>
-
-      <section class="card">
-        <h2 class="card-title">Device</h2>
-        <div id="device-status"><p class="sub">Loading...</p></div>
-      </section>
-
-      <section class="card">
-        <h2 class="card-title">Battery history</h2>
-        <div id="battery-chart-wrap"><p class="sub">Loading...</p></div>
-      </section>
-
-      <section class="card">
-        <h2 class="card-title">Firmware update</h2>
-        <p class="sub" id="firmware-available">
-          {% if cfg.firmware_available_version %}Uploaded: v{{ cfg.firmware_available_version }} -- the frame
-          updates itself on its next wake if it's running something else.{% else %}No firmware uploaded yet.{% endif %}
-        </p>
-        <input type="file" id="firmware-file" accept=".bin">
-        <button type="button" class="secondary" id="firmware-upload">Upload firmware</button>
-        <p class="sub" id="firmware-gitea-status" style="display: none; margin-top: 10px;"></p>
-        <button type="button" id="firmware-update-btn" style="display: none;">Update frame</button>
-      </section>
-    </div>
-  </div>
-
-  <section class="card" style="margin-top: 20px;">
-    <h2 class="card-title">Upcoming</h2>
-    <p class="sub">Drag a photo to reorder (on touch, hold briefly first so a
-      normal scroll still works), "Show next" to jump it to the front, or
-      the &times; to remove it from rotation entirely.</p>
-    <div id="upcoming-grid" class="photo-grid"></div>
-  </section>
-{% endblock %}
-
-{% block scripts %}
-  <script>
-    const resultEl = document.getElementById('result');
-
-    function showStatus(ok, message) {
-      resultEl.innerHTML = `<div class="status ${ok ? 'ok' : 'err'}">${message}</div>`;
-    }
-
-    async function saveConfig() {
-      const minutes = parseInt(document.getElementById('refresh_interval_minutes').value, 10) || 60;
-      const body = new URLSearchParams({
-        album_id: document.getElementById('album_id').value || '',
-        order: document.getElementById('order').value,
-        orientation: document.getElementById('orientation').value,
-        refresh_interval_s: String(minutes * 60),
-        smart_crop_faces: String(document.getElementById('smart_crop_faces').checked),
-        queue_target_len: document.getElementById('queue_target_len').value,
-        quiet_hours_enabled: String(document.getElementById('quiet_hours_enabled').checked),
-        quiet_hours_start: document.getElementById('quiet_hours_start').value || '22:00',
-        quiet_hours_end: document.getElementById('quiet_hours_end').value || '07:00',
-        timezone: document.getElementById('timezone').value || 'UTC',
-        firmware_update_repo_url: document.getElementById('firmware_update_repo_url').value || '',
-        firmware_board_variant: document.getElementById('firmware_board_variant').value,
-        firmware_auto_update: String(document.getElementById('firmware_auto_update').checked),
-      });
-      const resp = await fetch('/api/config', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body,
-      });
-      if (!resp.ok) {
-        throw new Error(await resp.text());
-      }
-    }
-
-    document.getElementById('load-albums').addEventListener('click', async () => {
-      try {
-        await saveConfig();
-
-        const resp = await fetch('/api/albums');
-        if (!resp.ok) {
-          throw new Error(await resp.text());
-        }
-        const albums = await resp.json();
-
-        const select = document.getElementById('album_id');
-        select.innerHTML = '';
-        for (const a of albums) {
-          const opt = document.createElement('option');
-          opt.value = a.id;
-          opt.textContent = `${a.name} (${a.count})`;
-          select.appendChild(opt);
-        }
-        showStatus(true, `Loaded ${albums.length} album(s) -- pick one and click Save.`);
-      } catch (e) {
-        showStatus(false, e.message);
-      }
-    });
-
-    document.getElementById('config-form').addEventListener('submit', async (e) => {
-      e.preventDefault();
-      try {
-        await saveConfig();
-        showStatus(true, 'Saved.');
-        loadQueue();
-      } catch (e) {
-        showStatus(false, e.message);
-      }
-    });
-
-    let upcomingItems = [];
-
-    // Pointer Events (not the native HTML5 Drag-and-Drop API) so the same
-    // code drives mouse, touch, and pen -- native drag-and-drop is
-    // mouse-only by spec and never fires at all on phones/tablets.
-    //
-    // On touch specifically, a card only "arms" for dragging after a
-    // brief hold (DRAG_HOLD_MS) with the finger roughly stationary --
-    // .photo-card's touch-action stays "pan-y" (native scroll allowed)
-    // the whole time up to that point, so a normal touch-and-swipe to
-    // scroll the page still works even though it starts on a card. Once
-    // armed, touch-action switches to "none" for the rest of that touch
-    // so drag tracking gets every pointermove reliably. Mouse skips the
-    // hold entirely (no scroll-vs-drag ambiguity with a mouse).
-    let dragState = null; // { pointerId, fromIndex, toIndex, moved, armed, holdTimer }
-    const DRAG_START_THRESHOLD_PX = 6; // ignore tiny jitter once armed, before committing to a drag
-    const DRAG_HOLD_MS = 250;
-    const HOLD_CANCEL_THRESHOLD_PX = 10; // movement before the hold timer fires -> treat as a scroll, not a drag
-
-    function vibrate(ms) {
-      // Chrome/Android only -- iOS Safari has no Vibration API. Wrapped so
-      // it's a harmless no-op everywhere else rather than needing a
-      // feature check at every call site.
-      try { navigator.vibrate?.(ms); } catch (e) { /* ignore */ }
-    }
-
-    function clearDragOverStyling() {
-      document.querySelectorAll('.photo-card.drag-over').forEach((el) => el.classList.remove('drag-over'));
-    }
-
-    function endDrag(card) {
-      if (dragState && dragState.holdTimer) {
-        clearTimeout(dragState.holdTimer);
-      }
-      card.style.touchAction = '';
-      card.style.transform = '';
-      card.classList.remove('dragging', 'drag-armed');
-      clearDragOverStyling();
-      if (dragState && dragState.moved && dragState.toIndex !== undefined && dragState.toIndex !== dragState.fromIndex) {
-        vibrate(15);
-        moveItem(dragState.fromIndex, dragState.toIndex);
-      }
-      dragState = null;
-    }
-
-    function renderUpcoming(items) {
-      upcomingItems = items;
-      const grid = document.getElementById('upcoming-grid');
-      grid.innerHTML = '';
-
-      items.forEach((item, i) => {
-        const card = document.createElement('div');
-        card.className = 'photo-card';
-        card.dataset.index = String(i);
-
-        const img = document.createElement('img');
-        img.src = item.thumbnail_url;
-        img.alt = '';
-        card.appendChild(img);
-
-        const badge = document.createElement('span');
-        badge.className = 'badge';
-        badge.textContent = String(i + 1);
-        card.appendChild(badge);
-
-        const removeBtn = document.createElement('button');
-        removeBtn.type = 'button';
-        removeBtn.className = 'remove-btn';
-        removeBtn.title = 'Remove from rotation';
-        removeBtn.textContent = '×';
-        removeBtn.addEventListener('click', (e) => {
-          e.stopPropagation();
-          removeAsset(item.id);
-        });
-        card.appendChild(removeBtn);
-
-        const nextBtn = document.createElement('button');
-        nextBtn.type = 'button';
-        nextBtn.className = 'show-next';
-        nextBtn.textContent = 'Show next';
-        nextBtn.addEventListener('click', (e) => {
-          e.stopPropagation();
-          showNext(i);
-        });
-        card.appendChild(nextBtn);
-
-        card.addEventListener('pointerdown', (e) => {
-          if (e.target.closest('.show-next') || e.target.closest('.remove-btn')) {
-            return; // let the button's own click handler run, don't start a drag
-          }
-          if (e.pointerType === 'mouse' && e.button !== 0) {
-            return; // left button only
-          }
-
-          dragState = {
-            pointerId: e.pointerId, fromIndex: i, toIndex: undefined, moved: false,
-            armed: e.pointerType !== 'touch', startX: e.clientX, startY: e.clientY, holdTimer: null,
-          };
-
-          if (e.pointerType === 'touch') {
-            dragState.holdTimer = setTimeout(() => {
-              if (dragState && dragState.pointerId === e.pointerId && !dragState.armed) {
-                dragState.armed = true;
-                card.classList.add('drag-armed');
-                card.style.touchAction = 'none';
-                vibrate(10);
-                try { card.setPointerCapture(e.pointerId); } catch (err) { /* pointer may have already left */ }
-              }
-            }, DRAG_HOLD_MS);
-          } else {
-            card.setPointerCapture(e.pointerId);
-          }
-        });
-
-        card.addEventListener('pointermove', (e) => {
-          if (!dragState || dragState.pointerId !== e.pointerId) {
-            return;
-          }
-
-          if (!dragState.armed) {
-            // Still deciding whether this is a hold-to-drag or a scroll --
-            // moving this much before the hold timer fires means scroll;
-            // bail out and let the browser's native pan-y handle it.
-            const dx0 = e.clientX - dragState.startX;
-            const dy0 = e.clientY - dragState.startY;
-            if (Math.hypot(dx0, dy0) > HOLD_CANCEL_THRESHOLD_PX) {
-              clearTimeout(dragState.holdTimer);
-              dragState = null;
-            }
-            return;
-          }
-
-          const dx = e.clientX - dragState.startX;
-          const dy = e.clientY - dragState.startY;
-
-          if (!dragState.moved) {
-            if (Math.hypot(dx, dy) < DRAG_START_THRESHOLD_PX) {
-              return;
-            }
-            dragState.moved = true;
-            card.classList.remove('drag-armed');
-            card.classList.add('dragging');
-          }
-
-          // Follows the finger 1:1 -- the actual "pick it up and carry it"
-          // feedback that was missing before (the card used to just fade
-          // in place while a static outline highlighted the drop target).
-          card.style.transform = `translate(${dx}px, ${dy}px) scale(1.06)`;
-
-          const overCard = document.elementFromPoint(e.clientX, e.clientY)?.closest('.photo-card');
-          clearDragOverStyling();
-          if (overCard && overCard !== card) {
-            overCard.classList.add('drag-over');
-            dragState.toIndex = Number(overCard.dataset.index);
-          } else {
-            dragState.toIndex = undefined;
-          }
-        });
-
-        card.addEventListener('pointerup', (e) => {
-          if (dragState && dragState.pointerId === e.pointerId) {
-            endDrag(card);
-          }
-        });
-        card.addEventListener('pointercancel', (e) => {
-          if (dragState && dragState.pointerId === e.pointerId) {
-            endDrag(card);
-          }
-        });
-
-        grid.appendChild(card);
-      });
-    }
-
-    function moveItem(fromIndex, toIndex) {
-      const items = upcomingItems.slice();
-      const [moved] = items.splice(fromIndex, 1);
-      items.splice(toIndex, 0, moved);
-      renderUpcoming(items);
-      persistOrder(items);
-    }
-
-    async function showNext(index) {
-      const assetId = upcomingItems[index].id;
-      try {
-        const resp = await fetch('/api/queue/promote', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ asset_id: assetId }),
-        });
-        if (!resp.ok) {
-          throw new Error(await resp.text());
-        }
-      } catch (e) {
-        showStatus(false, e.message);
-      }
-      loadQueue(); // always refetch the authoritative order rather than guessing locally
-    }
-
-    async function removeAsset(assetId) {
-      if (!confirm('Remove this photo from the rotation? It stays in Immich -- this frame just won\'t show it again.')) {
-        return;
-      }
-      try {
-        const resp = await fetch('/api/queue/remove', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ asset_id: assetId }),
-        });
-        if (!resp.ok) {
-          throw new Error(await resp.text());
-        }
-      } catch (e) {
-        showStatus(false, e.message);
-      }
-      loadQueue();
-    }
-
-    async function persistOrder(items) {
-      try {
-        const resp = await fetch('/api/queue/reorder', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ queue: items.map((item) => item.id) }),
-        });
-        if (!resp.ok) {
-          throw new Error(await resp.text());
-        }
-      } catch (e) {
-        showStatus(false, e.message);
-        loadQueue();
-      }
-    }
-
-    function formatDuration(seconds) {
-      const d = Math.floor(seconds / 86400);
-      const h = Math.floor((seconds % 86400) / 3600);
-      const m = Math.floor((seconds % 3600) / 60);
-      if (d > 0) return `${d}d ${h}h`;
-      if (h > 0) return `${h}h ${m}m`;
-      return `${m}m`;
-    }
-
-    function renderDeviceStatus(device) {
-      const el = document.getElementById('device-status');
-      el.innerHTML = '';
-      if (!device || !device.last_seen) {
-        el.innerHTML = '<p class="sub">The frame hasn\'t checked in yet.</p>';
-        return;
-      }
-      const now = Date.now() / 1000;
-      const rows = [];
-      const ago = formatDuration(Math.max(0, now - device.last_seen));
-      rows.push([`Last seen`, `${ago} ago`, device.overdue]);
-      if (device.firmware_version) {
-        let fw = `v${device.firmware_version}`;
-        if (device.firmware_available && device.firmware_available !== device.firmware_version) {
-          fw += ` (v${device.firmware_available} waiting)`;
-        }
-        rows.push(['Firmware', fw, false]);
-      }
-      if (device.battery) {
-        rows.push(['Battery', `${device.battery.percent}%`, false]);
-      }
-      if (device.on_battery_since) {
-        rows.push(['On battery for', formatDuration(now - device.on_battery_since), false]);
-      }
-      if (device.battery_estimate_s !== null && device.battery_estimate_s !== undefined) {
-        rows.push(['Est. remaining', `~${formatDuration(device.battery_estimate_s)}`, false]);
-      }
-      for (const [label, value, alert] of rows) {
-        const p = document.createElement('p');
-        p.className = 'sub';
-        if (alert) {
-          p.style.color = 'var(--danger-text)';
-          p.style.fontWeight = '600';
-        }
-        p.textContent = `${label}: ${value}`;
-        el.appendChild(p);
-      }
-    }
-
-    document.getElementById('firmware-upload').addEventListener('click', async () => {
-      const input = document.getElementById('firmware-file');
-      if (!input.files.length) {
-        showStatus(false, 'Pick a firmware .bin first.');
-        return;
-      }
-      const form = new FormData();
-      form.append('file', input.files[0]);
-      try {
-        const resp = await fetch('/api/firmware', { method: 'POST', body: form });
-        if (!resp.ok) {
-          throw new Error(await resp.text());
-        }
-        const result = await resp.json();
-        document.getElementById('firmware-available').textContent =
-          `Uploaded: v${result.version} -- the frame updates itself on its next wake if it's running something else.`;
-        showStatus(true, `Firmware v${result.version} uploaded (${result.size} bytes).`);
-      } catch (e) {
-        showStatus(false, e.message);
-      }
-    });
-
-    async function loadFirmwareCheck() {
-      const statusEl = document.getElementById('firmware-gitea-status');
-      const btn = document.getElementById('firmware-update-btn');
-      try {
-        const resp = await fetch('/api/firmware/check');
-        if (!resp.ok) {
-          return;
-        }
-        const data = await resp.json();
-        if (!data.enabled) {
-          statusEl.style.display = 'none';
-          btn.style.display = 'none';
-          return;
-        }
-        statusEl.style.display = 'block';
-        if (data.update_available) {
-          statusEl.textContent = `Update available: v${data.latest_version}.`;
-          btn.style.display = 'inline-block';
-        } else if (data.latest_version) {
-          statusEl.textContent = `Up to date (v${data.latest_version}).`;
-          btn.style.display = 'none';
-        } else {
-          statusEl.textContent = 'No releases found yet.';
-          btn.style.display = 'none';
-        }
-      } catch (e) {
-        // A failed check is silent -- the manual upload path still works
-        // regardless, and this just retries on the next poll.
-      }
-    }
-
-    document.getElementById('firmware-update-btn').addEventListener('click', async () => {
-      const btn = document.getElementById('firmware-update-btn');
-      btn.disabled = true;
-      try {
-        const resp = await fetch('/api/firmware/apply-latest', { method: 'POST' });
-        if (!resp.ok) {
-          throw new Error(await resp.text());
-        }
-        const result = await resp.json();
-        document.getElementById('firmware-available').textContent =
-          `Uploaded: v${result.version} -- the frame updates itself on its next wake if it's running something else.`;
-        showStatus(true, `Firmware v${result.version} staged from Gitea.`);
-        loadFirmwareCheck();
-      } catch (e) {
-        showStatus(false, e.message);
-      } finally {
-        btn.disabled = false;
-      }
-    });
-
-    let lastDevice = null;
-
-    async function loadQueue() {
-      if (dragState) {
-        return; // don't yank the grid out from under an in-progress drag
-      }
-      const currentEl = document.getElementById('current-thumb');
-      try {
-        const resp = await fetch('/api/queue');
-        if (!resp.ok) {
-          currentEl.innerHTML = '<p class="sub">Not available yet -- configure Immich and an album first.</p>';
-          renderUpcoming([]);
-          return;
-        }
-        const data = await resp.json();
-        currentEl.innerHTML = '';
-        if (data.current) {
-          const wrap = document.createElement('div');
-          wrap.className = 'thumb-wrap';
-
-          const img = document.createElement('img');
-          img.className = 'thumb';
-          img.src = data.current.thumbnail_url;
-          img.alt = '';
-          wrap.appendChild(img);
-
-          const removeBtn = document.createElement('button');
-          removeBtn.type = 'button';
-          removeBtn.className = 'remove-btn';
-          removeBtn.title = 'Remove from rotation';
-          removeBtn.textContent = '×';
-          removeBtn.addEventListener('click', () => removeAsset(data.current.id));
-          wrap.appendChild(removeBtn);
-
-          currentEl.appendChild(wrap);
-        } else {
-          currentEl.innerHTML = '<p class="sub">Nothing displayed yet.</p>';
-        }
-        lastDevice = data.device;
-        renderDeviceStatus(data.device);
-        renderUpcoming(data.upcoming);
-      } catch (e) {
-        currentEl.innerHTML = '<p class="sub">Could not load.</p>';
-      }
-    }
-
-    // Reads resolved colors from CSS custom properties rather than
-    // hardcoding hex values, so the chart matches the current theme
-    // (light/dark) without needing its own separate palette.
-    function themeColor(name) {
-      return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
-    }
-
-    let lastBatteryLog = null;
-
-    function drawBatteryChart(log) {
-      lastBatteryLog = log;
-      const wrap = document.getElementById('battery-chart-wrap');
-      if (!log || log.length < 2) {
-        wrap.innerHTML = '<p class="sub">Not enough data yet.</p>';
-        return;
-      }
-      wrap.innerHTML = '';
-      const width = wrap.clientWidth || 440;
-      const height = 180;
-      const canvas = document.createElement('canvas');
-      canvas.width = width;
-      canvas.height = height;
-      canvas.style.display = 'block';
-      canvas.style.border = `1px solid ${themeColor('--border')}`;
-      canvas.style.borderRadius = '8px';
-      wrap.appendChild(canvas);
-      const ctx = canvas.getContext('2d');
-
-      const gridColor = themeColor('--border');
-      const mutedColor = themeColor('--text-muted');
-      const accentColor = themeColor('--accent');
-
-      const pad = { left: 28, right: 8, top: 10, bottom: 20 };
-      const plotW = width - pad.left - pad.right;
-      const plotH = height - pad.top - pad.bottom;
-
-      const times = log.map((p) => p[0]);
-      const minT = Math.min(...times);
-      const maxT = Math.max(...times);
-      const spanT = Math.max(1, maxT - minT);
-
-      const x = (t) => pad.left + ((t - minT) / spanT) * plotW;
-      const y = (pct) => pad.top + (1 - pct / 100) * plotH;
-
-      ctx.strokeStyle = gridColor;
-      ctx.fillStyle = mutedColor;
-      ctx.font = '10px system-ui, sans-serif';
-      ctx.lineWidth = 1;
-      ctx.textAlign = 'left';
-      [0, 25, 50, 75, 100].forEach((pct) => {
-        const yy = y(pct);
-        ctx.beginPath();
-        ctx.moveTo(pad.left, yy);
-        ctx.lineTo(width - pad.right, yy);
-        ctx.stroke();
-        ctx.fillText(String(pct), 2, yy + 3);
-      });
-
-      ctx.strokeStyle = accentColor;
-      ctx.lineWidth = 1.5;
-      ctx.beginPath();
-      log.forEach((p, i) => {
-        const px = x(p[0]);
-        const py = y(p[1]);
-        if (i === 0) ctx.moveTo(px, py);
-        else ctx.lineTo(px, py);
-      });
-      ctx.stroke();
-
-      const fmt = (t) => new Date(t * 1000).toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
-      ctx.fillStyle = mutedColor;
-      ctx.textAlign = 'left';
-      ctx.fillText(fmt(minT), pad.left, height - 4);
-      ctx.textAlign = 'right';
-      ctx.fillText(fmt(maxT), width - pad.right, height - 4);
-    }
-
-    async function loadBatteryLog() {
-      const wrap = document.getElementById('battery-chart-wrap');
-      try {
-        const resp = await fetch('/api/battery-log');
-        if (!resp.ok) {
-          wrap.innerHTML = '<p class="sub">Could not load.</p>';
-          return;
-        }
-        const data = await resp.json();
-        drawBatteryChart(data.log);
-      } catch (e) {
-        wrap.innerHTML = '<p class="sub">Could not load.</p>';
-      }
-    }
-
-    function renderStats(stats) {
-      const el = document.getElementById('stats-box');
-      el.innerHTML = '';
-      const now = Date.now() / 1000;
-      const rows = [
-        ['Running since', stats.first_seen ? formatDuration(Math.max(0, now - stats.first_seen)) + ' ago' : 'never checked in'],
-        ['Wake cycles', stats.device_wakes],
-        ['Photos displayed', stats.photos_displayed],
-        ['Photos removed from rotation', stats.photos_removed],
-        ['Battery reports received', stats.battery_reports],
-        ['Battery recharge cycles', stats.recharge_cycles],
-        ['OTA updates applied', stats.ota_updates_applied],
-        ['Settings saved', stats.config_saves],
-      ];
-      for (const [label, value] of rows) {
-        const p = document.createElement('p');
-        p.className = 'sub';
-        p.textContent = `${label}: ${value}`;
-        el.appendChild(p);
-      }
-    }
-
-    async function loadStats() {
-      const el = document.getElementById('stats-box');
-      try {
-        const resp = await fetch('/api/stats');
-        if (!resp.ok) {
-          el.innerHTML = '<p class="sub">Could not load.</p>';
-          return;
-        }
-        renderStats(await resp.json());
-      } catch (e) {
-        el.innerHTML = '<p class="sub">Could not load.</p>';
-      }
-    }
-
-    loadQueue();
-    loadBatteryLog();
-    loadStats();
-    loadFirmwareCheck();
-
-    // Redraw the canvas chart (and the "Last seen" alert color) with the
-    // new theme's colors as soon as the toggle in the header is used --
-    // canvas pixels don't repaint themselves the way CSS does.
-    document.addEventListener('themechange', () => {
-      if (lastBatteryLog) {
-        drawBatteryChart(lastBatteryLog);
-      }
-      if (lastDevice) {
-        renderDeviceStatus(lastDevice);
-      }
-    });
-
-    // Fast tick: re-renders "Last seen"/"On battery for" etc. from the
-    // already-fetched device data every second, so they count up smoothly
-    // (1s ago, 5s ago, 1m ago...) without hitting the server that often.
-    setInterval(() => {
-      if (lastDevice) {
-        renderDeviceStatus(lastDevice);
-      }
-    }, 1000);
-
-    // Slow poll: picks up real changes (new photo displayed, queue edited
-    // from elsewhere, battery report, firmware version) without a manual
-    // refresh. Skipped mid-drag (see loadQueue above).
-    setInterval(loadQueue, 10000);
-
-    // Separate, slower poll for the Gitea release check -- cheap either
-    // way since the server itself throttles actual Gitea API calls to
-    // once per gitea_releases.UPDATE_CHECK_INTERVAL_S.
-    setInterval(loadFirmwareCheck, 60000);
-  </script>
-{% endblock %}

server/app/templates/login.html

@@ -0,0 +1,24 @@
+{% extends "base.html" %}
+
+{% block page_class %}page-narrow{% endblock %}
+
+{% block subtitle %}
+<p class="sub">Sign in</p>
+{% endblock %}
+
+{% block content %}
+  <section class="card">
+    <h2 class="card-title">Log in</h2>
+    {% if error %}<div class="status err">{{ error }}</div>{% endif %}
+    <form method="post" action="/login">
+      <input type="hidden" name="next" value="{{ next }}">
+      <label>Username
+        <input type="text" name="username" maxlength="64" required autofocus autocomplete="username">
+      </label>
+      <label>Password
+        <input type="password" name="password" required autocomplete="current-password">
+      </label>
+      <button type="submit">Log in</button>
+    </form>
+  </section>
+{% endblock %}

server/app/templates/manage.html

@@ -0,0 +1,116 @@
+{% extends "base.html" %}
+
+{% block subtitle %}
+<p class="sub">{{ frame.name or "Frame" }} &mdash; quick controls</p>
+{% endblock %}
+
+{% block content %}
+  <div class="layout">
+    <div class="main-col">
+      <section class="card">
+        <h2 class="card-title">Up next</h2>
+        <p class="sub">Tap "Show next" to move a photo to the front. The frame
+          picks it up on its next refresh. <a href="/login">Log in</a> for full
+          settings.</p>
+        <div id="upcoming-grid" class="photo-grid"></div>
+      </section>
+    </div>
+    <div class="side-col">
+      <section class="card">
+        <h2 class="card-title">Now displaying</h2>
+        <div id="current-thumb"><p class="sub">Loading...</p></div>
+        <div style="display: flex; gap: 8px;">
+          <button type="button" class="secondary" id="btn-back">&larr; Previous</button>
+          <button type="button" class="secondary" id="btn-advance">Next &rarr;</button>
+        </div>
+        <p class="sub" style="margin-top: 8px;">Changes what the frame shows on
+          its next wake.</p>
+      </section>
+    </div>
+  </div>
+  <div id="result"></div>
+{% endblock %}
+
+{% block scripts %}
+  <script>
+    const TOKEN = {{ manage_token | tojson }};
+    const resultEl = document.getElementById('result');
+
+    function showStatus(ok, message) {
+      resultEl.innerHTML = `<div class="status ${ok ? 'ok' : 'err'}">${message}</div>`;
+    }
+
+    async function post(path, body) {
+      const resp = await fetch(`/api/m/${TOKEN}/${path}`, {
+        method: 'POST',
+        headers: body ? { 'Content-Type': 'application/json' } : {},
+        body: body ? JSON.stringify(body) : undefined,
+      });
+      if (!resp.ok) {
+        throw new Error(await resp.text());
+      }
+    }
+
+    async function loadQueue() {
+      const currentEl = document.getElementById('current-thumb');
+      const grid = document.getElementById('upcoming-grid');
+      try {
+        const resp = await fetch(`/api/m/${TOKEN}/queue`);
+        if (!resp.ok) {
+          currentEl.innerHTML = '<p class="sub">This frame isn\'t set up yet.</p>';
+          return;
+        }
+        const data = await resp.json();
+        currentEl.innerHTML = '';
+        if (data.current) {
+          const img = document.createElement('img');
+          img.className = 'thumb';
+          img.src = data.current.thumbnail_url;
+          img.alt = '';
+          currentEl.appendChild(img);
+        } else {
+          currentEl.innerHTML = '<p class="sub">Nothing displayed yet.</p>';
+        }
+        grid.innerHTML = '';
+        for (const item of data.upcoming) {
+          const card = document.createElement('div');
+          card.className = 'photo-card';
+          const img = document.createElement('img');
+          img.src = item.thumbnail_url;
+          img.alt = '';
+          img.draggable = false;
+          card.appendChild(img);
+          const btn = document.createElement('button');
+          btn.type = 'button';
+          btn.className = 'show-next';
+          btn.textContent = 'Show next';
+          btn.addEventListener('click', async () => {
+            try {
+              await post('promote', { asset_id: item.id });
+              showStatus(true, 'Moved to the front.');
+              loadQueue();
+            } catch (e) {
+              showStatus(false, e.message);
+            }
+          });
+          card.appendChild(btn);
+          grid.appendChild(card);
+        }
+      } catch (e) {
+        currentEl.innerHTML = '<p class="sub">Could not load.</p>';
+      }
+    }
+
+    document.getElementById('btn-advance').addEventListener('click', async () => {
+      try { await post('advance'); showStatus(true, 'Advanced.'); loadQueue(); }
+      catch (e) { showStatus(false, e.message); }
+    });
+    document.getElementById('btn-back').addEventListener('click', async () => {
+      try { await post('back'); showStatus(true, 'Went back.'); loadQueue(); }
+      catch (e) { showStatus(false, e.message); }
+    });
+
+    loadQueue();
+    setInterval(loadQueue, 15000);
+  </script>
+{% endblock %}

server/app/templates/settings.html

@@ -0,0 +1,42 @@
+{% extends "app_base.html" %}
+
+{% block title %}Settings{% endblock %}
+{% block page_title %}Your account{% endblock %}
+
+{% block content %}
+  {% if saved %}<div class="status ok">Saved.</div>{% endif %}
+  {% if error %}<div class="status err">{{ error }}</div>{% endif %}
+
+  <section class="card">
+    <h2 class="card-title">Profile &amp; photo library</h2>
+    <form method="post" action="/settings">
+      <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+      <label>Display name
+        <input type="text" name="display_name" maxlength="64" value="{{ user.display_name }}">
+      </label>
+      <label>Immich URL
+        <input type="text" name="immich_url" placeholder="http://your-immich-host:2283"
+               value="{{ user.immich_url }}">
+      </label>
+      <label>Immich API key
+        <input type="password" name="immich_api_key" autocomplete="off"
+               placeholder="{% if user.immich_api_key %}(unchanged -- enter a new key to replace){% else %}your-immich-api-key{% endif %}">
+      </label>
+      <p class="sub" style="margin-top: 8px;">Frames you own pull photos from
+        this Immich library. The key needs read access to albums/assets/faces
+        plus <code>sharedLink.create</code> for the on-frame share QR.</p>
+
+      <h2 class="card-title" style="margin-top: 24px;">Change password</h2>
+      <label>Current password
+        <input type="password" name="current_password" autocomplete="current-password">
+      </label>
+      <label>New password
+        <input type="password" name="new_password" minlength="8" autocomplete="new-password">
+      </label>
+      <p class="sub" style="margin-top: 8px;">Leave both blank to keep your
+        current password.</p>
+
+      <button type="submit">Save</button>
+    </form>
+  </section>
+{% endblock %}

server/app/templates/setup.html

@@ -0,0 +1,30 @@
+{% extends "base.html" %}
+
+{% block page_class %}page-narrow{% endblock %}
+
+{% block subtitle %}
+<p class="sub">First-run setup</p>
+{% endblock %}
+
+{% block content %}
+  <section class="card">
+    <h2 class="card-title">Create the admin account</h2>
+    <p class="sub">This server has no users yet. The account you create here
+      is the administrator: it can enroll other users and manage every
+      frame. Any frame this server already knows about is linked to it
+      automatically.</p>
+    {% if error %}<div class="status err">{{ error }}</div>{% endif %}
+    <form method="post" action="/setup">
+      <label>Username
+        <input type="text" name="username" maxlength="64" required autofocus autocomplete="username">
+      </label>
+      <label>Display name (optional)
+        <input type="text" name="display_name" maxlength="64" autocomplete="name">
+      </label>
+      <label>Password
+        <input type="password" name="password" minlength="8" required autocomplete="new-password">
+      </label>
+      <button type="submit">Create admin account</button>
+    </form>
+  </section>
+{% endblock %}

server/requirements.txt

@@ -5,3 +5,5 @@ httpx==0.28.1
 pillow==12.3.0
 python-multipart==0.0.20
 jinja2==3.1.5
+sqlalchemy==2.0.51
+qrcode==8.2