Swap combo button tiers: quick press resets, ~3s hold shows menu

Quick reset is now the fast/default action; summoning the management
menu takes a deliberate hold. Factory reset at ~15s is unchanged.
Renamed FRAME_COMBO_SOFT_RESET_HOLD_MS -> FRAME_COMBO_MENU_HOLD_MS to
match its new meaning. Bumps firmware to 1.4.1.

.claude/skills/build-firmware/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: build-firmware
+description: Compile the espresso_frame ESP32-C6 firmware (firmware/) for both board variants without Docker -- a native, non-container ESP-IDF v6.0 install. Use when asked to build the firmware, verify a firmware/main/*.c change actually compiles, or check both the devkit and xiao board targets.
+---
+
+Compiles `firmware/` (ESP-IDF, targeting ESP32-C6) locally, without
+Docker -- CI's `firmware-build-check.yml`/`firmware-release-build.yml`
+build inside the `espressif/idf:release-v6.0` container image, but
+**this sandbox cannot run containers at all**: `docker.io` installs and
+`dockerd` starts fine even as root, but the sandbox strips
+`cap_sys_admin` (and blocks the bare `unshare` syscall) from the
+capability set regardless of uid, which container image-layer
+extraction and namespace setup both require. Confirmed by hand:
+`docker run hello-world` fails to extract even the tiny hello-world
+layer ("failed to extract layer... operation not permitted" with the
+overlayfs snapshotter; "unshare: operation not permitted" even with
+the vfs storage driver instead). This is a hard restriction of the
+sandbox itself, not a permissions/setup problem -- don't spend time
+re-trying `--privileged`-equivalent flags or alternate storage drivers,
+none of it routes around a missing `cap_sys_admin`.
+
+The workaround: skip containers entirely and install ESP-IDF the same
+way a developer would set it up on their own machine (`git clone` +
+ESP-IDF's own `install.sh`) -- that path needs nothing this sandbox
+disallows, just normal file/process operations.
+
+## Setup (once per fresh container)
+
+```bash
+bash .claude/skills/build-firmware/setup.sh
+```
+
+Installs (via real `apt-get` -- this container actually has root and a
+working package manager, unlike run-server's Chromium bootstrap which
+had neither):
+- OS build deps: `python3`/`venv`/`pip`, `cmake`, `ninja-build`,
+  `flex`/`bison`/`gperf`, `build-essential`, `libusb-1.0-0`.
+- ESP-IDF itself: a shallow, single-branch, recursive-submodule clone
+  of `release/v6.0` (~700MB) into `~/.espressif-idf/esp-idf` -- matches
+  the IDF version CI's Docker image pins. Only clones once; re-running
+  `setup.sh` never touches an existing checkout.
+- The esp32c6 toolchain + Python venv, via ESP-IDF's own
+  `./install.sh esp32c6` -- scoped to just this project's one target
+  (see `firmware/README.md`'s board table), not every chip ESP-IDF
+  supports, to keep the download/disk footprint down. `install.sh` is
+  already idempotent on its own, so `setup.sh` always calls it rather
+  than duplicating that check -- a re-run costs a few seconds once
+  everything's cached.
+
+Takes a few minutes on a cold run (mostly `install.sh`'s own pip/tool
+downloads), well under a minute on a re-run. Needs real root (`apt-get
+install`) -- if this container ever runs as non-root, this setup
+doesn't apply as-is (would need the same non-root apt-download +
+`dpkg-deb -x` extraction dance `run-server`'s `setup.sh` uses for
+Chromium).
+
+Disk: budget ~4GB free before starting (esp-idf checkout + toolchain +
+Python env land around 3.4GB in `~/.espressif`, plus the ~700MB
+checkout itself). Confirmed working with as little as ~7GB free.
+
+## Build
+
+```bash
+bash .claude/skills/build-firmware/build.sh            # devkit (default)
+bash .claude/skills/build-firmware/build.sh xiao
+bash .claude/skills/build-firmware/build.sh both        # both variants
+```
+
+Each board gets its own build directory and generated sdkconfig (see
+`firmware/build_for_board.sh`'s own comment) -- building one never
+disturbs the other. `build.sh` auto-runs `set-target esp32c6` the very
+first time a board is built (no generated sdkconfig yet); later builds
+skip straight to `idf.py build`. Extra arguments pass straight through
+to `idf.py`, e.g.:
+
+```bash
+bash .claude/skills/build-firmware/build.sh xiao flash -p /dev/ttyUSB0
+```
+
+`flash`/`monitor` need an actual attached device and serial port --
+this sandbox has neither, so those only work when this skill runs
+somewhere hardware is actually plugged in (a real dev machine, or a
+differently-configured environment with device passthrough).
+
+A clean build of one board takes ~30s once the target's already been
+configured (~1,000 build steps total split across both boards, most of
+it ESP-IDF's own components -- this project's own `firmware/main/*.c`
+and `firmware/components/*` sources are a small fraction of that and
+compile in a few seconds). Output lands at
+`firmware/build/espresso_frame.bin` (devkit) or
+`firmware/build_xiao/espresso_frame.bin` (xiao) -- both paths are
+gitignored (`firmware/.gitignore`... actually the repo root
+`.gitignore`'s "ESP-IDF firmware build output" section), so nothing
+here needs cleaning up before a commit.
+
+## Verified
+
+Both board variants (`devkit` set-target esp32c6 + build, `xiao`
+set-target esp32c6 + build) built successfully end-to-end using this
+exact setup.sh/build.sh pair, producing real
+`espresso_frame.bin` images with normal free-space margins (41%/36%
+of their respective app partitions) and no errors -- only one
+pre-existing, unrelated warning (`battery.c`'s unused `TAG` when that
+file's logging is compiled out). This is a real compile check, not
+just a syntax read -- if a future change breaks the build, this skill
+will actually catch it.
+
+## Troubleshooting
+
+- **`docker: ... unshare: operation not permitted` / `failed to
+  extract layer ... operation not permitted`**: expected in this
+  sandbox, see the top of this file. Don't debug it further -- use this
+  skill's native install instead.
+- **`ESP-IDF not found at ... -- run setup.sh first`**: `build.sh`'s
+  own check for a missing `$IDF_DIR/export.sh` -- run `setup.sh` (see
+  above) before the first build.
+- **`idf.py: command not found` if you try to run it directly**: same
+  gotcha `firmware/build_for_board.sh` already documents -- `idf.py` is
+  normally a shell *function* from ESP-IDF's `export.sh`, not on PATH
+  as a real executable, so it isn't inherited into a script's own
+  subshell even after sourcing `export.sh` in your interactive shell
+  first. Use `build.sh` (or `build_for_board.sh`, which calls
+  `python "$IDF_PATH/tools/idf.py"` directly) instead of typing
+  `idf.py` in a fresh script/subshell.
+- **Disk pressure during `install.sh`**: this environment runs close to
+  full (single-digit GB free is normal, not a sign of a leak) --
+  `df -h /` before running `setup.sh` if a build mysteriously fails
+  partway with a "no space left on device"-shaped error.

.claude/skills/build-firmware/build.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Builds (or flashes/monitors, if a serial port is actually attached)
+# the espresso_frame firmware for one board variant, via the project's
+# own firmware/build_for_board.sh -- this script just sources the
+# ESP-IDF environment first and auto-runs `set-target esp32c6` on a
+# board's very first build (a fresh clone has no generated sdkconfig
+# yet, same reasoning as CI's own build steps -- see firmware/README.md's
+# "Building for the Seeed XIAO ESP32-C6" section).
+#
+# Usage:
+#   build.sh                        # build devkit (default)
+#   build.sh devkit
+#   build.sh xiao
+#   build.sh both                   # build both board variants
+#   build.sh xiao flash -p /dev/ttyUSB0   # only meaningful with real hardware attached
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+firmware_dir="$(git -C "$script_dir" rev-parse --show-toplevel)/firmware"
+
+IDF_DIR="$HOME/.espressif-idf/esp-idf"
+if [ ! -f "$IDF_DIR/export.sh" ]; then
+  echo "ESP-IDF not found at $IDF_DIR -- run setup.sh first" >&2
+  exit 1
+fi
+# export.sh is chatty and assumes an interactive shell prompt in spots;
+# redirect its own stdout, not ours, so build.sh's actual output (and a
+# real failure's stderr) stays visible.
+source "$IDF_DIR/export.sh" > /dev/null
+
+cd "$firmware_dir"
+
+build_one() {
+  local board="$1"
+  shift
+  local sdkconfig
+  case "$board" in
+    devkit) sdkconfig="sdkconfig" ;;
+    xiao) sdkconfig="sdkconfig.xiao_local" ;;
+    *) echo "Unknown board '$board' -- expected 'devkit' or 'xiao'" >&2; exit 1 ;;
+  esac
+
+  if [ ! -f "$sdkconfig" ]; then
+    echo "==> $board: no generated sdkconfig yet, setting target esp32c6"
+    ./build_for_board.sh "$board" set-target esp32c6
+  fi
+
+  local args=("$@")
+  if [ ${#args[@]} -eq 0 ]; then
+    args=(build)
+  fi
+  ./build_for_board.sh "$board" "${args[@]}"
+}
+
+board="${1:-devkit}"
+shift || true
+
+if [ "$board" = "both" ]; then
+  build_one devkit "$@"
+  build_one xiao "$@"
+else
+  build_one "$board" "$@"
+fi

.claude/skills/build-firmware/setup.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# One-time (idempotent) environment bootstrap for compiling the
+# espresso_frame firmware (firmware/) without Docker -- see this
+# skill's SKILL.md for why not Docker, even though that's what CI uses.
+# Re-run any time; every step is safe/fast to repeat once already done.
+set -euo pipefail
+
+IDF_ROOT="$HOME/.espressif-idf"
+IDF_DIR="$IDF_ROOT/esp-idf"
+# Matches the espressif/idf:release-v6.0 image CI's
+# firmware-build-check.yml/firmware-release-build.yml use -- keep this
+# in sync with those workflow files if the project's pinned IDF version
+# ever changes.
+IDF_BRANCH="release/v6.0"
+
+# 1. OS packages ESP-IDF's own install.sh needs (python3 + venv/pip,
+# cmake, ninja, a C toolchain for the odd host-side code generator, git
+# for the clone below, flex/bison/gperf for mbedtls/etc.'s generated
+# parsers, libusb for esptool's USB/JTAG bits even though this skill
+# doesn't flash real hardware). Installed via apt with real root --
+# unlike run-server's Chromium bootstrap, this container actually has
+# root and a working apt, so no non-root extraction dance is needed
+# here.
+PKGS="git python3 python3-venv python3-pip cmake ninja-build ccache libusb-1.0-0 wget flex bison gperf build-essential"
+missing=()
+for pkg in $PKGS; do
+  dpkg -s "$pkg" >/dev/null 2>&1 || missing+=("$pkg")
+done
+if [ ${#missing[@]} -gt 0 ]; then
+  echo "installing OS packages: ${missing[*]}"
+  apt-get update
+  DEBIAN_FRONTEND=noninteractive apt-get install -y "${missing[@]}"
+fi
+
+# 2. ESP-IDF checkout -- shallow, single branch, recursive submodules
+# also shallow (~700MB total, vs. several GB for a full clone). Only
+# clones once; re-running this script never re-clones or resets it, so
+# any local changes you made for debugging survive a re-run.
+if [ ! -d "$IDF_DIR/.git" ]; then
+  echo "cloning esp-idf $IDF_BRANCH into $IDF_DIR ..."
+  mkdir -p "$IDF_ROOT"
+  git clone --branch "$IDF_BRANCH" --depth 1 --shallow-submodules --recursive \
+    https://github.com/espressif/esp-idf.git "$IDF_DIR"
+else
+  echo "esp-idf already cloned at $IDF_DIR"
+fi
+
+# 3. Toolchain + Python virtualenv, scoped to esp32c6 only -- this
+# project's one target (see firmware/README.md's board table). Scoping
+# avoids downloading toolchains for every chip ESP-IDF supports, which
+# matters given this container's disk headroom. install.sh is already
+# idempotent on its own (checks what's present and skips it), so this
+# always calls it rather than trying to duplicate that check here --
+# a re-run only costs a few seconds once everything's cached.
+echo "running esp-idf install.sh esp32c6 (fast if already installed) ..."
+(cd "$IDF_DIR" && ./install.sh esp32c6)
+
+echo "setup complete -> $IDF_DIR/export.sh (build.sh sources this for you)"

.claude/skills/make-widget/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: make-widget
+description: Scaffold a new widget type for the espresso_frame server (the ~13-file checklist a widget type touches -- config table, grid footprint, render module, registry, migration, config-save + endpoints, dialog template + JS, script tag, WIDGET_LABELS, docs, tests). Use when asked to add a new widget type to a frame's panel (e.g. "add a text widget", "add an RSS widget", "add a weather-only widget").
+---
+
+Adding a widget type is a very consistent, repeated pattern in this
+codebase (`photos`/`calendar`/`whiteboard`/`tasks`/`static`) -- see
+`docs/widgets.md` for the system's actual data model/rendering/dialog
+architecture (read that first if you haven't). This skill is the
+checklist of every file that pattern touches, so nothing gets silently
+dropped (the static-image widget shipped without a `docs/widgets.md`
+update; this skill exists so that doesn't keep happening).
+
+**For a complete worked example touching every item below**, `git show
+35e80c6 --stat` (the static-image widget's commit) in this repo.
+
+All paths below are relative to `server/`.
+
+## Before writing any code: shape decisions
+
+Answer these first -- they determine which existing widget type is the
+closest template to copy from:
+
+- **Live upstream to poll, or self-contained/user-authored?** Calendar/
+  whiteboard/tasks fetch from somewhere external on a throttle
+  (`checked_at` + `get_or_refresh_*` in `routers/common.py`). Photos'
+  queue and the static image widget don't -- their content is set once
+  via the dialog (an upload, a pick) and just sits there until changed.
+  A text widget is almost certainly this second shape.
+- **Single source, or multi-source merge?** Calendar/tasks merge
+  several *people's* data (`FrameCalendar`/`FrameTaskList`, owner-adds/
+  anyone-mutes). Only reach for that shape if the new type genuinely
+  needs to combine several linked users' own data -- most new widget
+  types are single-owner/single-config and don't need it.
+- **Any button actions**, or is `ACTIONS = {}` correct (nothing to
+  advance/back/force)? Tasks and static image are both `{}`.
+- **Minimum sane grid footprint** -- how small can this widget be
+  before its content is illegible/pointless?
+
+Pick your template accordingly:
+
+| New widget shape | Copy from |
+|---|---|
+| Self-contained, user-authored/uploaded, no fetch, no actions | `app/widgets/static_image.py` |
+| Single external source, throttled fetch, one "check_now" action | `app/widgets/whiteboard.py` |
+| Multi-source merge, owner-adds/anyone-mutes permissions | `app/widgets/tasks.py` (simpler) or `calendar.py` (also has size-tier rendering) |
+| Stateful queue/rotation with advance/back | `app/widgets/photos.py` |
+
+## The checklist
+
+1. **`app/models.py`** -- new `<Type>WidgetConfig` table, `widget_id`
+   `Mapped[int]` primary key `ForeignKey("widgets.id", ondelete="CASCADE")`,
+   plus whatever fields the type needs. Add it to the `WIDGET_CONFIG_MODELS`
+   dict at the bottom of the file.
+2. **`app/grid.py`** -- add an entry to `MIN_FOOTPRINT`.
+3. **`app/widgets/<type>.py`** -- new module exposing:
+   - `render(db, frame, widget, target_w, target_h, is_normal_wake=True) -> Image.Image`
+     -- RGB, exactly `target_w x target_h`, **never raises** for a
+     foreseeable failure (missing config, fetch error) -- fall back to
+     `._shared.placeholder_image(target_w, target_h, [lines])` instead.
+   - `ACTIONS: dict[str, Callable[[Session, Frame, Widget], None]]`
+   - `ACTION_LABELS: dict[str, str]`
+4. **`app/widgets/__init__.py`** -- import the new module, add it to
+   `WIDGET_TYPES`.
+5. **`app/migration.py`** -- new `_migration_N`. A brand-new table with
+   no legacy data to carry forward is just
+   `Base.metadata.create_all(bind=conn)` (see `_migration_20`) -- it
+   only creates the one new table, existing ones are untouched. Register
+   `(N, _migration_N)` as the new last entry in `MIGRATIONS`.
+6. **`app/routers/api_widgets.py`**:
+   - Add any new `Form(...)` fields to `api_widget_config_save`'s
+     signature, and a new `elif widget.widget_type == "<type>":` branch
+     inside its body. Reuse an existing field name (e.g. `display_mode`)
+     where the semantics genuinely match -- fields are namespaced by
+     which widget type actually reads them, not by name collision, so
+     this is safe (see the comment above `display_mode` in that
+     function).
+   - Add type-specific endpoints as needed (upload/source-select/etc.).
+     Use `require_widget_control` for widget-wide settings a dialog Save
+     button changes; use `require_widget_view` (not control) for the
+     owner-adds/anyone-mutes multi-source pattern, matching
+     `api_widget_calendar_select`/`api_widget_task_list_select`.
+   - Add a `GET .../preview/<type>` endpoint mirroring the others --
+     `render_preview_png` (the full palette/dither pipeline) for
+     image-like content, or a dedicated `render_<type>_preview_png` in a
+     rendering module for text/graphics content (see
+     `calendar_render.render_tasks_preview_png`).
+7. **`app/routers/frame_pages.py`** -- import the new config model, add
+   an `if widget.widget_type == "<type>":` branch in `widget_dialog()`
+   returning `templates.TemplateResponse("_widget_dialog_<type>.html", {...})`.
+8. **`app/templates/_widget_dialog_<type>.html`** -- the dialog
+   fragment: settings card(s) + `<img class="preview-img"
+   id="<type>-preview">` + a refresh button, using the existing
+   `.card`/`.card-title`/`.sub`/`.checkbox-row` classes from
+   `theme.css` rather than inventing new ones.
+9. **`app/static/widget_dialog_<type>.js`** -- an `init<Type>Dialog()`/
+   `close<Type>Dialog()` pair (not a page-load script -- see any
+   existing `widget_dialog_*.js`'s header comment for the contract).
+   `window.fetch` already CSRF-injects (see `common.js`), so POSTs don't
+   need a manual header. **Never build user-supplied text into the DOM
+   via `innerHTML` string interpolation** -- use `textContent`/
+   `createElement` (a filename, a task summary, anything another linked
+   user's account could have set is a stored-XSS vector otherwise).
+10. **`app/templates/frame_layout.html`** -- add
+    `<script src="/static/widget_dialog_<type>.js"></script>` next to
+    the other widget dialog scripts.
+11. **`app/static/frame_layout.js`** -- add the type to both
+    `DIALOG_INIT` and `DIALOG_CLOSE`.
+12. **`app/static/common.js`** -- add a `WIDGET_LABELS` entry (the
+    human label shown in the add-widget button, the widget box, and the
+    button-assignment picker in `frame_config.js`).
+13. **`docs/widgets.md`** -- update every place that enumerates widget
+    types: the intro sentence, the `widget_type` column-value list, the
+    `MIN_FOOTPRINT` prose line, the `app/widgets/` module list. This is
+    the project's own "start here" doc per `CLAUDE.md` -- don't ship a
+    widget without it staying accurate.
+
+## Tests (`server/tests/`)
+
+- `test_widgets_<type>.py` -- unit-level `render()` tests, no HTTP:
+  correct size/mode with no config, with config, at
+  `grid.MIN_FOOTPRINT`'s smallest box, `ACTIONS == {}` if passive.
+  Mirror `test_widgets_static.py` (self-contained) or
+  `test_widgets_tasks.py` (fetch-backed, monkeypatches the fetch call).
+- `test_widget_config_and_queue_endpoints.py` -- add a
+  `_add_<type>_widget` helper plus an HTTP-level
+  `test_config_save_updates_a_<type>_widget` test, and tests for any new
+  endpoints (upload/select/preview: 400 before configured, 200 after,
+  400 for the wrong widget type via `_require_widget_type`).
+- `test_migrations.py` -- add the new table to
+  `test_expected_columns_exist_on_current_schema`'s spot-check
+  (`inspector.get_table_names()` or `inspector.get_columns(...)`).
+- Owner-adds/anyone-mutes multi-source table? Add cases to
+  `test_permission_boundaries.py` following its existing
+  calendar-select/task-list-select pattern (owner can add, non-owner
+  can mute but not add, 404 for an unrelated widget id, 400 for the
+  wrong widget type).
+- Any pure-logic helper module (decoding, parsing -- like
+  `app/image_upload.py`) gets its own `test_<module>.py`: no HTTP, no
+  DB, just the function.
+
+Run the full suite before calling it done:
+
+```bash
+cd server && .venv/bin/pytest -q
+```
+
+Comfortably under 30s for the whole suite (~200+ tests) -- there's no
+reason to skip this or run a subset.
+
+## Browser verification (required, not optional)
+
+Per `CLAUDE.md`, reading the JS is not enough -- this project has
+shipped UI bugs (mobile viewport CSS collapse, a dialog's status message
+landing behind its own backdrop, a JSON/form body mismatch) that only
+showed up live. Use the `run-server` skill:
+
+- Clear existing widgets and add one of the new type
+  (`POST /api/frames/1/widgets`), resize it (`PATCH`), open its dialog
+  (`click .widget-box-settings`), exercise its actual settings/upload
+  flow through the real UI controls (not just a raw `fetch` in `eval` --
+  that only proves the endpoint works, not that the button is wired to
+  it), and check `console-errors` for anything beyond the expected
+  favicon 404.
+- Check the full composited panel preview
+  (`#frame-preview-thumb` on `/frames/{id}/config`) actually shows the
+  new widget's content -- not just its own dialog's `preview/<type>`
+  image, which only proves the render function works in isolation.
+- Screenshot **both** desktop (`viewport 1280 900`) and mobile
+  (the driver's default) widths -- the layout genuinely forks at the
+  860px breakpoint in `theme.css`.
+
+## Commit
+
+One commit for the whole widget (models + migration + render + router +
+UI + tests + docs) -- this project's convention is one feature per
+commit, not split by layer. No `Co-Authored-By: Claude` trailer (see
+root `CLAUDE.md`).

.claude/skills/run-server/.gitignore

@@ -0,0 +1,2 @@
+# Generated by setup.sh -- bakes in this host's /tmp paths, not portable.
+env.sh

.claude/skills/run-server/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: run-server
+description: Build, run, and drive the espresso_frame FastAPI server (server/) -- start it against a scratch DB, browser-test its UI, run its pytest suite. Use when asked to start the server, take a screenshot of a frame page, click through the web UI, or verify a server/UI change actually works.
+---
+
+The espresso_frame server is a FastAPI app (`app.main:app`) with a
+server-rendered Jinja UI. For agent/automated use it's driven by a
+Playwright REPL at `.claude/skills/run-server/driver.py`, run under
+tmux -- `chromium-cli` isn't available in this container, so this
+driver replaces it (same command vocabulary: nav/wait-for/click/fill/
+screenshot/eval/console-errors).
+
+This container ships with **no Python, Node, Docker, or browser, and
+no sudo**. `setup.sh` bootstraps everything non-root; it's the bulk of
+what makes this skill non-obvious. Run it once per fresh container.
+
+Commands below (`setup.sh`, `start-server.sh`, `stop-server.sh`,
+`env.sh`, `driver.py`) are invoked from the **repo root** via their
+`.claude/skills/run-server/` path -- the scripts `cd` into `server/`
+themselves. Anything under `.venv/` (the venv itself, `pytest`,
+`uvicorn`) lives inside `server/`, so those commands need `server/`
+prefixed or `cd server` first.
+
+## Prerequisites
+
+None to install manually -- `setup.sh` does it all without root, using
+only `curl`/`apt-get download`/`dpkg-deb -x` (never `apt-get install`,
+which needs root). It downloads ~450MB total (Python, Chromium, tmux,
+shared libs) on first run.
+
+```bash
+bash .claude/skills/run-server/setup.sh
+```
+
+Re-running is safe and fast -- every step checks whether it already
+happened (venv exists? chromium downloaded? libs extracted? tmux
+present?) before doing any work.
+
+This creates:
+- `.venv/` -- Python 3.12 + `requirements.txt` + `playwright`, via `uv`
+  (a static Rust binary that fetches its own Python -- no compiler
+  needed, install via `curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- `~/.cache/ms-playwright/` -- Chromium (full `chrome` + headless-shell)
+- `/tmp/run-server-chromium-deps/` -- Chromium's + tmux's shared libs
+  and fonts, extracted (not installed) from `.deb` files
+- `.claude/skills/run-server/env.sh` -- the `PATH`/`LD_LIBRARY_PATH`/
+  `FONTCONFIG_PATH`/`RUN_SERVER_CHROME_BIN` exports the driver needs
+  (gitignored -- host-specific `/tmp` paths, regenerated by setup.sh)
+
+## Run (agent path)
+
+**1. Start the server** against a scratch DB (never the real
+deployment's data -- see `CLAUDE.md`):
+
+```bash
+bash .claude/skills/run-server/start-server.sh
+# -> server PID <pid> up on http://127.0.0.1:8420 (log: /tmp/run-server-scratch/server.log)
+```
+
+Optional args: `start-server.sh [scratch-dir] [port]` (defaults
+`/tmp/run-server-scratch` / `8420`).
+
+**2. Drive it**, wrapped in tmux so you can send one command at a time
+and read the response before sending the next. `tmux` itself was
+extracted the same non-root way as Chromium's libs (see Prerequisites)
+and needs `LD_LIBRARY_PATH` set in *this* shell too, not just inside
+the pane -- source `env.sh` before the first `tmux` call:
+
+```bash
+source .claude/skills/run-server/env.sh
+tmux new-session -d -s runserver -x 200 -y 50
+tmux send-keys -t runserver \
+  'source .claude/skills/run-server/env.sh && server/.venv/bin/python .claude/skills/run-server/driver.py' Enter
+timeout 20 bash -c 'until tmux capture-pane -t runserver -p | grep -q "driver>"; do sleep 0.3; done'
+
+# Every fresh scratch DB starts with no users -- bootstrap-admin
+# completes first-run /setup and logs in (see Commands table):
+tmux send-keys -t runserver 'bootstrap-admin' Enter
+timeout 15 bash -c 'until tmux capture-pane -t runserver -p | grep -q "bootstrapped admin"; do sleep 0.3; done'
+
+tmux send-keys -t runserver 'nav /frames/1/config' Enter
+tmux send-keys -t runserver 'wait-for #frame-preview-thumb' Enter
+tmux send-keys -t runserver 'screenshot before' Enter
+tmux capture-pane -t runserver -p
+```
+
+Poll for a specific marker between `send-keys` and `capture-pane`
+(`driver>`, `bootstrapped admin`, `screenshot:`, ...) rather than a
+fixed `sleep` -- it's faster and fails loudly instead of capturing a
+half-rendered screen. Give each poll its own `timeout` (~15-20s); don't
+chain many polling loops inside one shell invocation -- see Gotchas.
+
+Screenshots land in `/tmp/run-server-shots/` (override:
+`SCREENSHOT_DIR`). **Actually look at them** -- a blank or error-page
+screenshot is a failure to launch, not success.
+
+**Test every UI change at both a desktop and a mobile viewport.** The
+driver defaults to a desktop size (1280x900); switch with `viewport`.
+The app's mobile breakpoint is 860px (`theme.css`) -- below that the
+sidebar goes off-canvas behind a hamburger (`.mobile-bar`). A page that
+looks right at 1280px can still overflow, overlap the mobile bar, or
+mis-center a `<dialog>` at phone widths -- screenshot both:
+
+```bash
+tmux send-keys -t runserver 'viewport 1280 900' Enter   # desktop (also the default)
+tmux send-keys -t runserver 'screenshot desktop-x' Enter
+tmux send-keys -t runserver 'viewport 390 844' Enter     # iPhone-ish mobile width
+tmux send-keys -t runserver 'screenshot mobile-x' Enter
+```
+
+### Driver commands
+
+| command | what it does |
+|---|---|
+| `nav <path-or-url>` | navigate (relative paths resolve against `http://127.0.0.1:8420`, override with `RUN_SERVER_BASE_URL`) |
+| `wait-for <selector>` | wait up to 10s for a selector (plain CSS -- see Gotchas for attribute selectors) |
+| `click <selector>` | click an element |
+| `fill <selector> <value>` | fill an input |
+| `press <key>` | keyboard press (e.g. `Enter`) |
+| `screenshot [name]` | → `/tmp/run-server-shots/<name>.png` |
+| `eval <js>` | evaluate JS in the page, prints JSON |
+| `console-errors` | prints all captured console/page errors as a JSON array |
+| `viewport [w] [h]` | resize the viewport, default `390 844` -- use `1280 900` for desktop (see Gotchas re: real touch input) |
+| `is-open <dialog-selector>` | prints `true`/`false` for a `<dialog>` element's `.open` -- use this instead of `wait-for sel[open]` |
+| `bootstrap-admin [user] [pass]` | completes first-run `/setup` (defaults `admin`/`testpassword123`); links frame #1 and logs in |
+| `quit` | closes the browser, exits the driver |
+
+**3. Stop the server** when done:
+
+```bash
+bash .claude/skills/run-server/stop-server.sh
+tmux kill-session -t runserver
+```
+
+## Run (human path)
+
+```bash
+cd server
+DATABASE_URL="sqlite:////tmp/dev.db" CONFIG_PATH="/tmp/dev-config.json" \
+  .venv/bin/uvicorn app.main:app --reload --port 8420
+```
+
+Open `http://localhost:8420` in a real browser. `start.sh` (the Docker
+entrypoint) is not this -- it also launches the Node whiteboard
+render-service sidecar, which needs Node (not installed here) and
+isn't needed for most UI testing.
+
+## Test
+
+```bash
+cd server && .venv/bin/pytest
+```
+
+Uses its own tempfile SQLite per run (`tests/conftest.py`) -- no setup
+needed beyond the venv.
+
+---
+
+## Gotchas
+
+- **`viewport` only resizes the window -- it does not emulate touch
+  input.** `click` still dispatches a mouse click, not a tap; there's
+  no touch-delay, no `:hover`-stickiness-after-tap, no `hasTouch`
+  context. It catches real bugs (layout overflow, off-canvas sidebar,
+  a `<dialog>` mis-centering at phone widths) but won't catch anything
+  that's specifically a touch-vs-mouse event difference. Good enough
+  for CSS/layout verification; not a substitute for testing on an
+  actual phone if a change touches touch-specific interaction.
+
+- **`chrome-headless-shell` (Playwright's default headless target)
+  crashes on basic calls in this container**, e.g. `page.set_content()`
+  returns `TargetClosedError`, even after every `ldd`-reported missing
+  library is resolved. The full `chrome` binary (`chromium-*/chrome-linux64/chrome`)
+  + `--no-sandbox` is stable; `driver.py` and `setup.sh` both use it,
+  not the headless-shell default.
+
+- **Missing fonts silently break `fill()`, not just rendering.** Before
+  `fontconfig`/`libfontconfig1` were extracted and `fonts.conf` pointed
+  at the extracted font dir, `page.fill()` ran with no error but left
+  inputs empty (`input_value()` returned `""`), and all text rendered
+  invisible in screenshots. It looks like a scripting bug, not a
+  missing-lib problem -- if `fill` silently no-ops, suspect fonts
+  before suspecting the selector or a race.
+
+- **No `apt-get install` / `playwright install-deps` (no root) and no
+  `apt-get update` into the real `/var/lib/apt/lists` (root-owned).**
+  Worked around by redirecting apt's state dirs to a scratch,
+  user-writable path (`-o Dir::State::Lists=... -o Dir::Cache=...`),
+  which makes plain `update` and `install --download-only --print-uris`
+  work as a non-root user; then `dpkg-deb -x <deb> <root>` (extract,
+  not install) needs no root either. `setup.sh` does this for
+  Chromium's deps *and* for `tmux` itself, which also isn't
+  preinstalled.
+
+- **`wait-for` with an attribute selector like `#frame-preview-dialog[open]`
+  is unreliable through `tmux send-keys`** -- shell/tmux escaping of
+  `[`/`]` easily mangles it (seen: a real 10s Playwright timeout from a
+  garbled selector, not a fast failure). Use the app-specific `is-open
+  <selector>` command instead of `wait-for sel[open]` to check a
+  `<dialog>`'s open state.
+
+- **Don't chain many `tmux send-keys` + polling-`timeout` loops inside
+  one shell invocation.** Each poll can legitimately take up to its own
+  timeout (e.g. 15s) if a selector is wrong; five or six chained in one
+  command can add up past this tool's own command timeout even though
+  each individual step is fine. Send one or two commands per shell
+  call and check the pane before continuing.
+
+- **A crashed `chrome-headless-shell` process can leave a large core
+  dump file** (`server/core`, ~170MB, from the crash described above)
+  if core dumps are enabled. It's not part of the app -- delete it, and
+  use full `chrome` (as `driver.py` does) to avoid triggering it again.
+
+## Troubleshooting
+
+- **`error while loading shared libraries: libglib-2.0.so.0` (or similar)
+  when launching Chromium directly**: `LD_LIBRARY_PATH` isn't set --
+  source `.claude/skills/run-server/env.sh` first, or run through
+  `driver.py`, which reads `RUN_SERVER_CHROME_BIN` from it.
+- **`fc-list` prints nothing after extracting fonts**: `fonts.conf`'s
+  `<dir>` entries still point at the real (unpopulated) `/usr/share/fonts`.
+  `setup.sh` patches this with `sed`; if you extracted packages by hand,
+  do the same.
+- **`E: Could not open lock file ... Permission denied` from `apt-get`**:
+  you're missing the `-o Dir::State::Lists=... -o Dir::Cache=...`
+  overrides -- plain `apt-get update`/`install` always needs root here.
+- **`tmux: command not found`**: not preinstalled and no sudo; run
+  `setup.sh`, which fetches it the same non-root way as Chromium's libs.
+- **`tmux: error while loading shared libraries: libutempter.so.0`**:
+  you sourced `env.sh` inside the driver's tmux pane but not in the
+  shell that *invokes* `tmux` itself -- `tmux` was extracted from the
+  same non-root `.deb` set as Chromium and needs `LD_LIBRARY_PATH` too.
+  `source .claude/skills/run-server/env.sh` before the first `tmux`
+  command, not just inside `send-keys`.

.claude/skills/run-server/driver.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""REPL driver for the espresso_frame server's web UI.
+
+Playwright-based since chromium-cli isn't available in this container.
+Reads one command per line from stdin, prints a result line -- built
+for tmux send-keys/capture-pane use by an agent. Vocabulary mirrors
+chromium-cli where it overlaps (nav/wait-for/click/fill/screenshot/
+eval/console-errors).
+
+Requires setup.sh to have run first (Python venv + Playwright Chromium
++ the non-root shared-lib/font extraction). Run via:
+
+    .claude/skills/run-server/env.sh sourced, then
+    server/.venv/bin/python .claude/skills/run-server/driver.py
+
+See SKILL.md for the full agent-path invocation (tmux wrapping etc).
+"""
+import glob
+import json
+import os
+import sys
+
+from playwright.sync_api import sync_playwright
+
+SHOT_DIR = os.environ.get("SCREENSHOT_DIR", "/tmp/run-server-shots")
+os.makedirs(SHOT_DIR, exist_ok=True)
+BASE = os.environ.get("RUN_SERVER_BASE_URL", "http://127.0.0.1:8420")
+
+
+def find_chrome() -> str:
+    override = os.environ.get("RUN_SERVER_CHROME_BIN")
+    if override and os.path.exists(override):
+        return override
+    matches = glob.glob(os.path.expanduser("~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome"))
+    if not matches:
+        sys.exit("chrome binary not found -- run setup.sh first")
+    return matches[0]
+
+
+pw = sync_playwright().start()
+# The FULL `chrome` binary, not chrome-headless-shell (Playwright's
+# default headless target): chrome-headless-shell crashed on basic
+# calls like set_content() in this container even once every
+# ldd-reported missing lib was resolved. Full chrome + --no-sandbox is
+# stable here.
+browser = pw.chromium.launch(executable_path=find_chrome(), args=["--no-sandbox"])
+page = browser.new_page(viewport={"width": 1280, "height": 900})
+console_errors: list[str] = []
+page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+page.on("pageerror", lambda exc: console_errors.append(str(exc)))
+# Playwright auto-DISMISSES native confirm()/alert() dialogs by default
+# (returns false) -- several destructive actions in this app (remove
+# widget, clear all widgets) gate on `confirm()`, so without this a
+# `click` on one of those buttons would silently no-op. Auto-accept
+# instead, since a driver testing a "yes, do the destructive thing"
+# flow needs the confirm to actually go through.
+page.on("dialog", lambda dialog: dialog.accept())
+
+
+def cmd_nav(arg):
+    url = arg if arg.startswith("http") else BASE + arg
+    page.goto(url)
+    print("nav ->", page.url)
+
+
+def cmd_wait_for(arg):
+    page.wait_for_selector(arg, timeout=10000)
+    print("found:", arg)
+
+
+def cmd_click(arg):
+    page.click(arg)
+    print("clicked:", arg)
+
+
+def cmd_fill(arg):
+    sel, _, value = arg.partition(" ")
+    page.fill(sel, value)
+    print("filled:", sel, "=", value)
+
+
+def cmd_press(arg):
+    page.keyboard.press(arg)
+    print("pressed:", arg)
+
+
+def cmd_screenshot(arg):
+    name = arg or f"ss-{len(os.listdir(SHOT_DIR))}"
+    path = os.path.join(SHOT_DIR, name + ".png")
+    page.screenshot(path=path)
+    print("screenshot:", path)
+
+
+def cmd_eval(arg):
+    try:
+        print(json.dumps(page.evaluate(arg)))
+    except Exception as e:
+        print("ERROR:", e)
+
+
+def cmd_console_errors(_arg):
+    print(json.dumps(console_errors))
+
+
+def cmd_viewport(arg):
+    """Resize the viewport. No args -> 390x844 (iPhone-ish mobile
+    width); the page itself starts at 1280x900 (desktop) on launch, so
+    `viewport 1280 900` gets back to that. The app's mobile breakpoint
+    is 860px (see theme.css) -- anything under that exercises the
+    off-canvas sidebar/mobile-bar layout."""
+    parts = arg.split()
+    width = int(parts[0]) if len(parts) > 0 else 390
+    height = int(parts[1]) if len(parts) > 1 else 844
+    page.set_viewport_size({"width": width, "height": height})
+    print("viewport:", width, "x", height)
+
+
+def cmd_is_open(arg):
+    """App-specific: print whether a <dialog> element is open (true/false)."""
+    print(json.dumps(page.eval_on_selector(arg, "el => el.open")))
+
+
+def cmd_bootstrap_admin(arg):
+    """App-specific: complete first-run /setup (username/password args,
+    default admin/testpassword123). Every scratch DB starts with no
+    users, and /setup is the only way in -- it also auto-links the
+    pre-existing frame #1 (created by migrations) to the new admin, so
+    /frames/1/... is reachable right after this."""
+    parts = arg.split()
+    username = parts[0] if len(parts) > 0 else "admin"
+    password = parts[1] if len(parts) > 1 else "testpassword123"
+    page.goto(BASE + "/setup")
+    page.fill("input[name=username]", username)
+    page.fill("input[name=password]", password)
+    page.click("button[type=submit]")
+    page.wait_for_load_state("networkidle")
+    print("bootstrapped admin, now at:", page.url)
+
+
+def cmd_quit(_arg):
+    browser.close()
+    pw.stop()
+    sys.exit(0)
+
+
+COMMANDS = {
+    "nav": cmd_nav,
+    "wait-for": cmd_wait_for,
+    "click": cmd_click,
+    "fill": cmd_fill,
+    "press": cmd_press,
+    "screenshot": cmd_screenshot,
+    "eval": cmd_eval,
+    "console-errors": cmd_console_errors,
+    "viewport": cmd_viewport,
+    "is-open": cmd_is_open,
+    "bootstrap-admin": cmd_bootstrap_admin,
+    "quit": cmd_quit,
+}
+
+print("run-server driver -- commands:", ", ".join(COMMANDS), flush=True)
+print("driver>", end=" ", flush=True)
+for line in sys.stdin:
+    line = line.strip()
+    if not line:
+        print("driver>", end=" ", flush=True)
+        continue
+    cmd, _, rest = line.partition(" ")
+    fn = COMMANDS.get(cmd)
+    if fn is None:
+        print("unknown command:", cmd, "-- try one of:", ", ".join(COMMANDS))
+    else:
+        try:
+            fn(rest)
+        except Exception as e:
+            print("ERROR:", e)
+    print("driver>", end=" ", flush=True)

.claude/skills/run-server/setup.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# One-time (idempotent) environment bootstrap for running the
+# espresso_frame FastAPI server and browser-driving its UI, in a
+# container that ships with NO Python/Node/Docker/browser and NO sudo.
+# Re-run any time; every step checks whether it already happened.
+set -euo pipefail
+cd "$(git -C "$(dirname "${BASH_SOURCE[0]}")" rev-parse --show-toplevel)/server"
+
+UV_BIN="$HOME/.local/bin/uv"
+DEPS_ROOT="/tmp/run-server-chromium-deps"
+APT_WORK="/tmp/apt-work-run-server"
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="$SKILL_DIR/env.sh"
+
+# 1. uv: a static Rust binary that can fetch its own Python build with
+# no C compiler needed (this container has none).
+if [ ! -x "$UV_BIN" ]; then
+  echo "installing uv..."
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+fi
+
+# 2. Python 3.12 + venv + server deps
+if [ ! -x .venv/bin/uvicorn ]; then
+  echo "creating venv + installing server deps..."
+  "$UV_BIN" python install 3.12
+  "$UV_BIN" venv --python 3.12 .venv
+  "$UV_BIN" pip install -r requirements.txt
+fi
+
+# 3. Playwright (Python) + its Chromium download (~280MB: full chrome +
+# chrome-headless-shell + ffmpeg)
+if ! .venv/bin/python -c "import playwright" 2>/dev/null; then
+  echo "installing playwright..."
+  "$UV_BIN" pip install playwright
+fi
+if ! ls "$HOME"/.cache/ms-playwright/chromium-*/chrome-linux64/chrome >/dev/null 2>&1; then
+  echo "downloading chromium..."
+  .venv/bin/playwright install chromium
+fi
+
+# 4. Chromium's shared libs + fonts. `playwright install-deps` and
+# `apt-get install` both need root; neither is available. Instead:
+# download the .deb files directly (apt-get download works read-only
+# without root once given a user-writable state dir) and extract
+# (not install) them with dpkg-deb -x, which needs no root either.
+if [ ! -f "$DEPS_ROOT/usr/lib/x86_64-linux-gnu/libglib-2.0.so.0" ]; then
+  echo "fetching chromium's shared libs + fonts (non-root)..."
+  mkdir -p "$APT_WORK/lists" "$APT_WORK/cache/archives/partial" "$APT_WORK/debs" "$DEPS_ROOT"
+
+  apt-get -o Dir::State::Lists="$APT_WORK/lists" -o Dir::Cache="$APT_WORK/cache" \
+    -o Dir::Etc::SourceParts=/dev/null update
+
+  PKGS="libglib2.0-0t64 libnspr4 libnss3 libatk1.0-0t64 libatk-bridge2.0-0t64
+        libdbus-1-3 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1
+        libxkbcommon0 libasound2t64 libatspi2.0-0t64 libcups2t64 libcairo2
+        libpango-1.0-0 libpangocairo-1.0-0 libx11-6 libxcb1 libxext6
+        fonts-liberation fontconfig libfontconfig1"
+  # ^ first row: what chrome-headless-shell's ldd reported missing.
+  # second row: what the FULL chrome binary additionally needed (we use
+  # full chrome, not headless-shell -- see Gotchas in SKILL.md).
+
+  apt-get -o Dir::State::Lists="$APT_WORK/lists" -o Dir::Cache="$APT_WORK/cache" \
+    -o Dir::Etc::SourceParts=/dev/null install --download-only --reinstall -y \
+    --print-uris $PKGS | grep -oP "^'[^']+'" | tr -d "'" > "$APT_WORK/urls.txt"
+
+  (cd "$APT_WORK/debs" && xargs -n1 -P8 curl -sS -O --max-time 30) < "$APT_WORK/urls.txt"
+  for f in "$APT_WORK"/debs/*.deb; do dpkg-deb -x "$f" "$DEPS_ROOT"; done
+
+  # fonts.conf as shipped points at the real /usr/share/fonts, which is
+  # root-owned and has nothing extracted into it. Point it at our
+  # extracted copy instead, and give it a writable cache dir.
+  mkdir -p /tmp/run-server-fontcache
+  sed -i "s#<dir>/usr/share/fonts</dir>#<dir>$DEPS_ROOT/usr/share/fonts</dir>#" \
+    "$DEPS_ROOT/etc/fonts/fonts.conf"
+  sed -i "s#<cachedir>.*</cachedir>#<cachedir>/tmp/run-server-fontcache</cachedir>#" \
+    "$DEPS_ROOT/etc/fonts/fonts.conf"
+
+  PATH="$DEPS_ROOT/usr/bin:$PATH" \
+    LD_LIBRARY_PATH="$DEPS_ROOT/usr/lib/x86_64-linux-gnu:$DEPS_ROOT/lib/x86_64-linux-gnu" \
+    FONTCONFIG_PATH="$DEPS_ROOT/etc/fonts" \
+    "$DEPS_ROOT/usr/bin/fc-cache" -f
+fi
+
+# 5. tmux -- also missing, also no apt/sudo. Same non-root download +
+# dpkg-deb -x trick, into the same extracted root (so its `usr/bin` is
+# already on PATH via env.sh).
+if [ ! -f "$DEPS_ROOT/usr/bin/tmux" ]; then
+  echo "fetching tmux (non-root)..."
+  mkdir -p "$APT_WORK/lists" "$APT_WORK/cache/archives/partial" "$APT_WORK/debs" "$DEPS_ROOT"
+  apt-get -o Dir::State::Lists="$APT_WORK/lists" -o Dir::Cache="$APT_WORK/cache" \
+    -o Dir::Etc::SourceParts=/dev/null install --download-only --reinstall -y \
+    --print-uris tmux | grep -oP "^'[^']+'" | tr -d "'" > "$APT_WORK/tmux_urls.txt"
+  (cd "$APT_WORK/debs" && xargs -n1 -P3 curl -sS -O --max-time 30) < "$APT_WORK/tmux_urls.txt"
+  for f in $(sed -E 's#.*/##' "$APT_WORK/tmux_urls.txt"); do dpkg-deb -x "$APT_WORK/debs/$f" "$DEPS_ROOT"; done
+fi
+
+CHROME_BIN="$(ls "$HOME"/.cache/ms-playwright/chromium-*/chrome-linux64/chrome | head -1)"
+
+cat > "$ENV_FILE" <<EOF
+# Generated by setup.sh. Source this before running driver.py (it
+# needs LD_LIBRARY_PATH/FONTCONFIG_PATH set before the Chromium
+# subprocess launches -- driver.py does not source it for you).
+# start-server.sh does NOT need this file -- uvicorn has no such deps.
+export PATH="\$HOME/.local/bin:$DEPS_ROOT/usr/bin:\$PATH"
+export LD_LIBRARY_PATH="$DEPS_ROOT/usr/lib/x86_64-linux-gnu:$DEPS_ROOT/lib/x86_64-linux-gnu"
+export FONTCONFIG_PATH="$DEPS_ROOT/etc/fonts"
+export RUN_SERVER_CHROME_BIN="$CHROME_BIN"
+EOF
+
+echo "setup complete -> $ENV_FILE"

.claude/skills/run-server/start-server.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Background-launch the server against a scratch DB/config -- never the
+# real deployment's data (see CLAUDE.md). Waits for readiness, prints
+# the PID and log path. Usage: ./start-server.sh [scratch-dir] [port]
+set -euo pipefail
+cd "$(git -C "$(dirname "${BASH_SOURCE[0]}")" rev-parse --show-toplevel)/server"
+
+SCRATCH="${1:-/tmp/run-server-scratch}"
+PORT="${2:-8420}"
+mkdir -p "$SCRATCH"
+
+DATABASE_URL="sqlite:///$SCRATCH/test.db" \
+CONFIG_PATH="$SCRATCH/config.json" \
+.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port "$PORT" \
+  > "$SCRATCH/server.log" 2>&1 &
+PID=$!
+echo "$PID" > "$SCRATCH/server.pid"
+
+for _ in $(seq 1 30); do
+  curl -sf -o /dev/null "http://127.0.0.1:$PORT/" && break
+  sleep 0.5
+done
+
+if ! curl -sf -o /dev/null "http://127.0.0.1:$PORT/"; then
+  echo "server did not become ready -- check $SCRATCH/server.log" >&2
+  exit 1
+fi
+
+echo "server PID $PID up on http://127.0.0.1:$PORT (log: $SCRATCH/server.log, db: $SCRATCH/test.db)"

.claude/skills/run-server/stop-server.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Usage: ./stop-server.sh [scratch-dir]
+SCRATCH="${1:-/tmp/run-server-scratch}"
+if [ -f "$SCRATCH/server.pid" ]; then
+  kill "$(cat "$SCRATCH/server.pid")" 2>/dev/null || true
+  rm -f "$SCRATCH/server.pid"
+  echo "stopped"
+else
+  echo "no $SCRATCH/server.pid -- nothing to stop"
+fi

.gitea/workflows/firmware-build-check.yml

@@ -0,0 +1,51 @@
+name: Firmware build check
+
+# Fires on every push touching firmware source, unlike
+# firmware-release-build.yml (which only builds+publishes when
+# firmware/version.txt itself is bumped -- the "cut a release" signal).
+# This just verifies both board variants still compile; nothing else in
+# CI catches a firmware/** push that breaks the build until someone
+# happens to bump the version next.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "firmware/**"
+      - ".gitea/workflows/firmware-build-check.yml"
+
+jobs:
+  build-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Same docker create/cp/start pattern as firmware-release-build.yml
+      # (see that file's own comment for why -- the runner's job
+      # workspace lives in a named Docker volume, not a real host path,
+      # so a nested `docker run -v "$PWD:..."` bind-mounts nothing
+      # useful). No release/artifact step here -- this only needs to
+      # prove `idf.py build` still succeeds for each board.
+      - name: Build (devkit -- ESP32-C6-DevKitC-1)
+        run: |
+          cid=$(docker create -w /workspace/firmware espressif/idf:release-v6.0 bash -c '
+            git config --global --add safe.directory /workspace &&
+            . "$IDF_PATH/export.sh" &&
+            ./build_for_board.sh devkit set-target esp32c6 &&
+            ./build_for_board.sh devkit build
+          ')
+          docker cp "$PWD/." "$cid:/workspace"
+          docker start -a "$cid"
+          docker rm "$cid"
+
+      - name: Build (xiao -- Seeed XIAO ESP32-C6)
+        run: |
+          cid=$(docker create -w /workspace/firmware espressif/idf:release-v6.0 bash -c '
+            git config --global --add safe.directory /workspace &&
+            . "$IDF_PATH/export.sh" &&
+            ./build_for_board.sh xiao set-target esp32c6 &&
+            ./build_for_board.sh xiao build
+          ')
+          docker cp "$PWD/." "$cid:/workspace"
+          docker start -a "$cid"
+          docker rm "$cid"

.gitea/workflows/server-docker-build.yml

@@ -8,7 +8,27 @@ on:
       - ".gitea/workflows/server-docker-build.yml"
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        working-directory: server
+        run: pip install -r requirements-dev.txt
+
+      - name: Run tests
+        working-directory: server
+        run: pytest
+
   build-and-push:
+    needs: test
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -32,3 +52,21 @@ jobs:
           tags: |
             git.thumeit.com/tfaour/espresso-frame-server:latest
             git.thumeit.com/tfaour/espresso-frame-server:${{ gitea.sha }}
+
+  deploy:
+    needs: build-and-push
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy over SSH
+        env:
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
+          DEPLOY_PORT: ${{ secrets.DEPLOY_PORT || '22' }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "$DEPLOY_SSH_KEY" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+          ssh-keyscan -p "$DEPLOY_PORT" "$DEPLOY_HOST" >> ~/.ssh/known_hosts 2>/dev/null
+          ssh -i ~/.ssh/deploy_key -p "$DEPLOY_PORT" -o StrictHostKeyChecking=yes \
+            espressoframe_deployer@"$DEPLOY_HOST" \
+            'cd ~/espresso-frame && docker compose pull && docker compose up -d'

.gitignore

@@ -17,6 +17,13 @@ server/**/__pycache__/
 server/.venv/
 server/*.egg-info/
 server/data/
+server/.pytest_cache/
+# render-service/ (whiteboard mode's Node sidecar) -- installed fresh
+# inside the Docker image, never committed. No package-lock.json exists
+# yet either (no Node/npm available in this project's dev environment to
+# generate one -- see render-service/README.md); if one's added later, do
+# NOT ignore it, lockfiles belong in git.
+server/render-service/node_modules/
 # Real deploy config, copied from docker-compose.yml.example -- holds the
 # Immich API key, must never be committed.
 server/docker-compose.yml
@@ -27,3 +34,8 @@ server/docker-compose.yml
 .idea/
 *.swp
 .DS_Store
+.claude/*
+# ...except Claude Code skills (e.g. agent-run instructions for this
+# app) -- those are project tooling worth sharing, not personal/local
+# state like settings.local.json or worktrees/.
+!.claude/skills/

CLAUDE.md

@@ -0,0 +1,95 @@
+# espresso_frame
+
+A DIY e-ink photo frame: an ESP32-C6 (`firmware/`, ESP-IDF) driving a
+Waveshare 7.3" E Ink Spectra 6 panel (800x480, 6-color, SPI), paired with a
+self-hosted FastAPI server (`server/`) that pulls from Immich, does all
+image processing (crop/dither/quantize/pack), and serves a placeable
+photos/calendar/whiteboard/weather widget system to the device.
+
+CURRENT TODO
+-sharing layouts with linked users
+-a "coming up this week" widget
+-on reset dismiss the menu.
+
+Start here, don't re-derive from scratch:
+- [`docs/architecture.md`](docs/architecture.md) -- how firmware and
+  server talk (sequence diagram, boot flow).
+- [`docs/widgets.md`](docs/widgets.md) -- the server-side widget system
+  (data model, grid placement, compositor, button-action dispatch). Notes
+  a known gap at the bottom (legacy `Frame` columns not yet dropped).
+- [`docs/hardware.md`](docs/hardware.md) -- wiring.
+- [`server/README.md`](server/README.md), [`firmware/README.md`](firmware/README.md)
+  -- per-component setup, config, and a lot of accumulated gotchas
+  (Immich API shape, TLS trust-anchor details, button GPIO wakeup
+  quirks, etc.) -- check these before assuming something is a new bug.
+
+## Conventions specific to this repo
+
+- **No `Co-Authored-By: Claude` trailers in commits.** Attribution lives
+  in the root [`README.md`](README.md) instead (see its last line) --
+  the maintainer's explicit preference, not the default.
+- **Copyleft dependencies need an explicit flag, not a silent decision.**
+  Before adding anything LGPL/GPL/AGPL (or unclear), verify the actual
+  license via `pip show`/package metadata -- including transitive deps,
+  not just the top-level package -- and present the finding and tradeoff
+  in plain text rather than picking an approach unilaterally (hand-rolling
+  an alternative, swapping packages, silently accepting it). This project
+  has knowingly accepted AGPL-3.0-or-later exposure once already
+  (`icalendar-searcher`, a transitive dep of `caldav`) as a deliberate,
+  explicit call -- not a precedent for skipping the check next time.
+- **Scope new auth/access-control broadly, not just to the literal
+  endpoint named.** When a request changes the trust model (e.g. adding
+  public-internet exposure), apply the new gate to every endpoint serving
+  real data or performing a real action, and call out anything you're
+  tempted to exclude and why. This repo shipped a token gate once that
+  covered `/api/*` but left `/frame/image` -- the actual photo bytes --
+  open; caught immediately in production.
+- **Commit and push once a task is verified working, without waiting to
+  be asked separately.** Once tests pass (and, for UI changes, the
+  browser check has been done), stage the relevant files, write a normal
+  commit message, and push to the current branch -- the maintainer's
+  standing authorization for the commit/push step itself. This doesn't
+  relax anything else: still run `git status`/review the diff before
+  staging, still never force-push/amend a pushed commit/skip hooks, and
+  still surface anything that looks like it needs a real decision (e.g.
+  a change that would trigger `main`'s deploy workflow, see below)
+  instead of pushing through it silently.
+
+## Working in this repo
+
+- **Server tests**: `cd server && pytest` (SQLite, fixtures wipe/reseed
+  between tests -- see `tests/conftest.py`). Migration changes need a
+  matching test in `tests/test_migrations.py`; anything touching
+  `require_frame_view`/`require_frame_control` boundaries needs a
+  same-shape permission test (see `tests/test_permission_boundaries.py`
+  and `tests/test_button_actions.py` for the pattern: owner, linked user,
+  unrelated user, logged out).
+- **UI changes**: verify in a real browser (Playwright), not just by
+  reading the JS -- this project has hit multiple bugs that only showed up
+  live (mobile viewport CSS collapse, a dialog's status message landing
+  behind its own backdrop, a JSON/form-urlencoded body mismatch). Spin up
+  `uvicorn app.main:app` against a scratch `DATABASE_URL`/`CONFIG_PATH`
+  sqlite file, don't touch the real deployment's data. `.claude/skills/run-server/`
+  (`/run-server`) has a driver for exactly this.
+- **New/changed UI must work at both desktop and mobile widths --
+  screenshot both, don't assume one implies the other.** The layout
+  genuinely forks at the 860px breakpoint (`theme.css`): the sidebar
+  goes off-canvas behind a hamburger below it. A dialog, header
+  control, or new widget that looks right at a wide viewport can
+  overflow, overlap the mobile bar, or mis-center at phone widths.
+  `run-server`'s driver has a `viewport` command for exactly this
+  (defaults to a phone size; switch to `1280 900` for desktop).
+- **Deploy**: Gitea Actions at `git.thumeit.com/tfaour/espresso_frame`
+  (`.gitea/workflows/server-docker-build.yml`: `test` -> `build-and-push`
+  -> `deploy` on any push to `main` touching `server/**`; `deploy` SSHes
+  into the host as `espressoframe_deployer` and runs `docker compose pull
+  && docker compose up -d`). A separate workflow
+  (`firmware-release-build.yml`) builds+publishes firmware binaries as
+  Gitea release assets when `firmware/version.txt` changes. Poll CI status
+  with `curl https://git.thumeit.com/api/v1/repos/tfaour/espresso_frame/actions/tasks`
+  rather than asking the user to check.
+- **Device-facing paths are frozen.** `/frame/image`, `/frame/advance`,
+  `/frame/back`, `/frame/config`, `/frame/battery`, `/frame/firmware` and
+  their exact JSON key names (`refresh_interval_s`, `firmware_version`,
+  etc.) are baked into deployed firmware -- never rename or restructure
+  these without a firmware-side migration story to match.

README.md

@@ -24,9 +24,10 @@ time in deep sleep.
 - ESP32-C6 dev board (8MB flash)
 - [Waveshare 7.3" E Ink Spectra 6 (E6)](https://www.waveshare.com/7.3inch-e-paper-hat-e.htm) panel -- 800x480, 6-color, SPI
 
-See [`docs/hardware.md`](docs/hardware.md) for wiring and
+See [`docs/hardware.md`](docs/hardware.md) for wiring,
 [`docs/architecture.md`](docs/architecture.md) for how the two halves talk
-to each other.
+to each other, and [`docs/widgets.md`](docs/widgets.md) for the server's
+placeable photos/calendar/whiteboard widget system.
 
 ## Getting started
 

docs/architecture.md

@@ -22,17 +22,17 @@ sequenceDiagram
     Frame->>Frame: Connect to home WiFi
     alt next-photo button pressed
         Frame->>Server: POST /frame/advance
-        Server->>Server: Force-advance to next queued photo, reset interval clock
+        Server->>Server: Run every action assigned to NEXT, in order<br/>(may span several widgets -- see docs/widgets.md)
     else back-photo button pressed
         Frame->>Server: POST /frame/back
-        Server->>Server: Return to previously-current photo (bounded history),<br/>reset interval clock
+        Server->>Server: Run every action assigned to BACK, in order
     else normal wake
         Frame->>Server: GET /frame/image
-        Server->>Server: Advance only if refresh_interval_s has elapsed<br/>since the current photo was set -- otherwise a no-op
+        Server->>Server: Render every widget on the panel into its own region<br/>(each independently idempotent -- a photo widget only<br/>actually advances once its own refresh_interval_s has elapsed)
     end
-    Server->>Immich: List album assets / download preview / faces
+    Server->>Immich: List album assets / download preview / faces<br/>(once per photo widget on the panel)
     Immich-->>Server: JPEG + face bounding boxes
-    Server->>Server: Crop (face-aware) + quantize (dither) + pack 4bpp
+    Server->>Server: Composite every widget's region onto one canvas,<br/>then enhance/overlay/quantize (dither)/pack 4bpp once
     Server-->>Frame: 192,000 raw bytes, streamed
     Frame->>Frame: Write to panel SPI buffer, compute CRC32
     alt CRC unchanged since last physical refresh
@@ -45,6 +45,17 @@ sequenceDiagram
     Frame->>Frame: Deep sleep (server-configured interval, or a short<br/>retry interval on any failure)
 ```
 
+The device-facing endpoints above (`/frame/image`, `/frame/advance`,
+`/frame/back`, `/frame/config`) are frozen -- baked into deployed firmware
+-- and unchanged by any of this. What *does* change server-side: a frame's
+panel isn't a single fixed "mode" anymore, it holds an arbitrary
+arrangement of independently placed/sized widgets (photos/calendar/
+whiteboard, including several of the same type), each rendered into its
+own region and composited together, with NEXT/BACK each mapped to their
+own ordered list of per-widget actions rather than one fixed meaning. See
+[`docs/widgets.md`](widgets.md) for the widget system's data model,
+placement grid, and button-action dispatch.
+
 ## Firmware boot flow
 
 1. **No stored config** (first boot, or NVS erased): bring up the display,
@@ -91,9 +102,9 @@ sequenceDiagram
    - Deep sleep for the server-configured interval on success, or a
      shorter retry interval on any failure.
 
-   The menu/reset button's soft-reset and factory-reset tiers (held ~3s
-   or ~15s) are handled earlier, before any of this, and never return --
-   see [`firmware/README.md`](../firmware/README.md#managing-the-queue-soft-resetting-and-factory-resetting).
+   The menu/reset button's soft-reset (quick press) and factory-reset
+   (held ~15s) tiers are handled earlier, before any of this, and never
+   return -- see [`firmware/README.md`](../firmware/README.md#managing-the-queue-soft-resetting-and-factory-resetting).
 
 See [`docs/hardware.md`](hardware.md) for wiring and
 [`server/README.md`](../server/README.md) for the server side.

docs/hardware.md

@@ -40,10 +40,10 @@ pressed):
   photo; see
   [`firmware/README.md`](../firmware/README.md#going-back-to-the-previous-photo).
 - **Menu / reset (GPIO1)**: one button, three actions by hold duration --
-  a quick press overlays a "scan to manage" QR code on the current photo
-  for 30 seconds; holding ~3s then releasing soft-resets the device
-  (config kept); holding ~15s factory-resets it (clears WiFi/server
-  config, reprovisions); see
+  a quick press soft-resets the device (config kept); holding ~3s then
+  releasing overlays a "scan to manage" QR code on the current photo for
+  30 seconds; holding ~15s factory-resets it (clears WiFi/server config,
+  reprovisions); see
   [`firmware/README.md`](../firmware/README.md#managing-the-queue-soft-resetting-and-factory-resetting).
 
 All three pins were picked because they're within GPIO 0-7 -- the only

docs/widgets.md

@@ -0,0 +1,359 @@
+# Widget system
+
+A frame's panel isn't one fixed "mode" anymore -- it holds N independently
+placed/sized widgets (photos/calendar/whiteboard/tasks/static image/text/
+weather/battery), like arranging icons on an Android home screen. A frame
+can hold several widgets of the same type (e.g. two photo widgets pointed
+at different Immich albums side by side).
+This replaced an earlier design where `Frame.mode` picked exactly one
+full-panel renderer; that column (and the other now-dead per-mode `Frame`
+columns it left behind -- `album_id`, `calendar_*`, `whiteboard_*`, etc.)
+is still physically present but unused, pending a final cleanup migration
+(see "Known gaps" below).
+
+The device-facing contract is unchanged by any of this: `GET /frame/image`,
+`POST /frame/advance`, `POST /frame/back` are the same frozen paths
+firmware has always called (see `docs/architecture.md`) -- what changed is
+entirely server-side, in how those endpoints decide what to render and what
+a button press does.
+
+## Data model
+
+- `Widget` (`server/app/models.py`): `id`, `frame_id`, `widget_type`
+  (`"photos"` | `"calendar"` | `"whiteboard"` | `"tasks"` | `"static"` |
+  `"text"` | `"weather"` | `"battery"`), `x`/`y`/`w`/`h`
+  (grid cells), `sort_order`. Widgets never overlap (enforced server-side in
+  `routers/api_widgets.py`, re-validated regardless of what the client
+  already checked) -- that's what keeps compositing simple: no z-order,
+  no blending, just N independent regions pasted onto one shared canvas.
+  Also carries an optional per-widget border (`border_style` -- `"none"`
+  | `"solid"` | `"dashed"` | `"dotted"` | `"fancy"`, `border_thickness`,
+  `border_color_index`, an index into the frame's palette so a border
+  always renders as one of the panel's exact 6 ink colors) directly on
+  `Widget` itself rather than a per-type config table, since every
+  widget type can have one regardless of `widget_type`. Drawn by
+  `image_pipeline.draw_widget_border` onto each widget's own region in
+  `routers/device.py`'s `_render_widgets`, before that region is pasted
+  onto the shared canvas -- one central integration point instead of
+  every `app/widgets/*.py` module needing to know about it. Set via the
+  gear-icon dialog's shared "Border" card (`_widget_border_fields.html`,
+  included by every `_widget_dialog_*.html` template) and
+  `POST .../widgets/{id}/border`, its own endpoint (not folded into
+  `api_widget_config_save`) since that endpoint's per-type dispatch is
+  keyed on a config row via `widget_locked`, and border fields live on
+  `Widget` itself, not any per-type config table.
+- Per-type 1:1 extension tables -- `PhotoWidgetConfig`,
+  `CalendarWidgetConfig`, `WhiteboardWidgetConfig`, `TaskWidgetConfig`,
+  `StaticWidgetConfig`, `TextWidgetConfig`, `WeatherWidgetConfig`,
+  `BatteryWidgetConfig`, each keyed by `widget_id` with
+  `ondelete="CASCADE"` -- rather than one wide table with every type's
+  mostly-irrelevant columns. `TextWidgetConfig.content` is parsed rich
+  text (paragraphs of styled runs), never raw HTML -- see
+  `server/app/text_content.py`'s module docstring for why that parse
+  step is the widget's actual stored-XSS sanitization boundary.
+  `PhotoWidgetConfig`
+  mirrors `app/photo_queue.py`'s attribute names exactly, so that module's
+  advance/back/queue logic ports across widget instances unchanged.
+  `PhotoWidgetConfig.locked` (migration 27) freezes `current_asset_id`
+  against both the timer-elapsed auto-advance
+  (`photo_queue.get_current`) and the advance/back button actions
+  (`app/widgets/photos.py`'s `ACTIONS`) until unlocked -- toggled via a
+  "Lock this photo" button in the widget's own dialog
+  (`POST .../widgets/{id}/lock`), shown as a lock badge on the widget's
+  box on the Layout tab canvas.
+  `TaskWidgetConfig` used to be a handful of `tasks_*` columns bolted onto
+  `CalendarWidgetConfig` (a week-view-only, single-list task list); split
+  into its own widget type (migration 17) so a task list can be placed
+  and sized independent of any calendar's view/footprint, then (migration
+  18) given the same multi-source shape a calendar widget already has.
+  `WeatherWidgetConfig` similarly lifts `CalendarWidgetConfig`'s embedded
+  weather strip (still present and unchanged, `weather_*` columns) out
+  into its own placeable widget type (migration 24) -- see "Weather
+  widget" below. `BatteryWidgetConfig` (migration 25) is the odd one out
+  -- its actual content (`Frame.battery_percent`/`battery_as_of`) isn't
+  in this table at all, already existing frame-level state set by
+  `routers/device.py`'s `frame_battery` regardless of whether a battery
+  widget is even placed; the config row only holds a display-mode
+  setting (`"compact"` | `"detailed"`).
+- `FrameCalendar`/`FrameTaskList` are keyed by `widget_id` (not
+  `frame_id`) since a frame can now have more than one independent
+  calendar/tasks widget, each with its own included set. Identical
+  shape and permission model (owner-added, anyone-linked-can-mute, see
+  "Per-widget config UI" below) -- `FrameTaskList` just has no `"ics"`
+  calendar_key variant, since a plain ICS subscription has no VTODO
+  (task) collection.
+- `FrameButtonAction` (`id`, `frame_id`, `button` [`"next"`|`"back"`],
+  `widget_id`, `action`, `sort_order`) -- see "Button actions" below.
+
+## Placement: a grid, not freeform pixels
+
+`app/grid.py` is pure grid math, no I/O. The grid is `GRID_LONG=8` x
+`GRID_SHORT=5` cells, defined relative to the panel's long/short axis
+(not "landscape" specifically) so it stays valid across
+`image_pipeline.logical_render_size(orientation)`'s genuine width/height
+swap for portrait -- landscape orientations are 8 cols x 5 rows, portrait
+are 5 cols x 8 rows, same cell size either way. **Changing a frame's
+orientation invalidates its existing layout** (an 8x5 arrangement isn't
+valid on a 5x8 grid) -- the server resets to one full-panel widget on an
+orientation change rather than trying to remap coordinates.
+
+Each widget type has a minimum grid footprint (`grid.MIN_FOOTPRINT`):
+photos 1x1, calendar 3x2 (a crammed calendar is illegible regardless of
+size-tier scaling), whiteboard 2x2, tasks 2x2, static image 1x1, text 2x1,
+weather 2x2 (its hourly/daily strips need the room; current/multi_city
+modes would tolerate smaller, but every mode shares one footprint value),
+battery 1x1 (just an icon + a percent, legible even at a single cell,
+like photos/static -- though see `MIN_FOOTPRINT`'s own comment in
+`grid.py` on a mobile-width gear-icon click-target gap at that size,
+already pre-existing for photos/static too). Enforced both client-side
+(UX, in the Layout tab's drag/resize canvas -- `static/frame_layout.js`)
+and server-side (`routers/api_widgets.py`) -- the client is never trusted
+alone.
+
+## Rendering: one shared compositor
+
+`app/widgets/` is the render/action registry -- one module per
+`widget_type` (`photos.py`, `calendar.py`, `whiteboard.py`, `tasks.py`,
+`static_image.py`, `text.py`, `weather.py`, `battery.py`), each exposing:
+
+- `render(db, frame, widget, target_w, target_h, is_normal_wake) -> Image`:
+  an unquantized RGB image exactly `target_w x target_h`, the widget's
+  content composed into its own region. Never raises for a foreseeable
+  failure (an Immich hiccup, an unconfigured widget) -- falls back to a
+  small placeholder within its own region instead, so one widget having a
+  bad moment doesn't blank the whole panel.
+- `ACTIONS: dict[str, Callable]` -- named button actions this type
+  supports (`"advance"`/`"back"` for photos and calendar, `"check_now"`
+  for whiteboard and weather -- both throttled external fetches with a
+  forced-refetch action). Empty for tasks, static image, text, and
+  battery -- nothing to advance/back/force for a passive checklist, a
+  fixed uploaded image, a fixed block of authored text, or a number the
+  device itself pushes on every wake.
+- `ACTION_LABELS: dict[str, str]` -- human labels for the button-
+  assignment UI.
+
+`routers/device.py`'s `_render_widgets` loads every `Widget` row for the
+frame, maps each one's grid rect to pixels (`grid.cell_to_pixels`), calls
+its module's `render()`, and hands the whole list of `(rect, image)`
+regions to `image_pipeline.render_panel` -- which pastes every region onto
+one shared canvas, then runs enhance/manage-overlay/quantize/dither/pack
+**once** over the composited result. Quantizing the whole canvas together
+(not each region separately before pasting) is what keeps the 6-color
+e-ink dithering pattern consistent across a widget boundary instead of a
+visible seam at the edge.
+
+Calendar widgets pick from discrete size tiers (`calendar_render.py`'s
+`_SIZE_TIERS`) for font size/margins/row heights based on their actual
+grid footprint, rather than continuously scaling constants tuned for a
+full ~800x480 canvas -- falls back to agenda view if a widget is too small
+for month view to stay legible.
+
+## Button actions
+
+Each physical button (NEXT/BACK) runs the `(widget, action)` binding of
+every widget on the frame that has one -- **at most one binding per
+widget per button** (a widget can't be bound to two different actions on
+the same button). On a press, `routers/device.py`'s `_run_button_actions`
+runs every widget's assigned action for that button (each in its own
+`widget_locked` span -- never nested, since the underlying per-frame lock
+isn't reentrant), catching and logging any single action's failure
+without blocking the rest, then re-renders and returns the whole composed
+panel once at the end regardless of which actions succeeded. Which
+widget's action runs first never matters -- each only touches its own
+state, and the shared re-render happens once, after all of them finish.
+
+The UI for this lives in each widget's own gear-icon config dialog (the
+"Button actions" card, `templates/_widget_button_fields.html` +
+`static/widget_dialog_button_actions.js`, `POST
+/api/frames/{id}/widgets/{widget_id}/button-actions`) -- not a frame-level
+tab, since assigning a widget's next/back behavior is naturally part of
+configuring that widget. The card only renders for widget types with a
+non-empty `ACTIONS` (photos, calendar, whiteboard, weather); tasks/
+static/text/battery have nothing to bind so the card is omitted for
+them. An empty selection ("(none)") clears that button's binding for the
+widget.
+
+A newly-created widget (including the one auto-migrated from a frame's
+old `mode` on upgrade) gets a sensible default binding reproducing its
+old button behavior -- see `widgets.default_button_actions` (called from
+both `migration.py`'s backfill and `api_widgets.py`'s
+`api_widget_create`), so a widget is never left with nothing bound until
+someone deliberately reassigns it.
+
+### Hold-for-global-action
+
+Holding NEXT or BACK past a configurable duration (`Frame.hold_duration_ms`,
+minimum 3000ms, set on the Configuration tab) triggers a **global**
+action instead of the per-widget one -- not scoped to any widget, e.g.
+cycling through the user's saved layouts. See `app/global_actions.py`'s
+`GLOBAL_ACTIONS`/`GLOBAL_ACTION_LABELS` registry and
+`routers/device.py`'s `/frame/global-next`/`/frame/global-back` (the
+device calls these instead of `/frame/advance`/`/frame/back` once it
+detects a long press -- see `firmware/main/next_button.c`/`back_button.c`).
+`Frame.next_hold_action`/`back_hold_action` pick which registry entry (if
+any) each button's hold triggers; unset is a silent no-op, same
+convention as an unbound short-press button.
+
+## Per-widget config UI
+
+Each widget has a gear-icon button on the Layout canvas that opens a
+`<dialog>` with that widget's own settings (album, calendar/task-list
+inclusion, whiteboard source, etc.) -- not a per-frame tab, since a
+frame can now have several widgets of the same type with independent
+settings. The
+dialog HTML is injected server-rendered (`routers/frame_pages.py`'s
+`widget_dialog`, dispatching on `widget.widget_type`); its JS is a
+top-level, always-loaded file (`static/widget_dialog_*.js`) exposing
+`init<Type>Dialog()`/`close<Type>Dialog()`, since dynamically-injected
+HTML can't carry executable `<script>` tags. While a dialog is open,
+`window.FRAME_API` is repointed at that widget's own API base
+(`/api/frames/{id}/widgets/{widget_id}`) and restored on close;
+`window.FRAME_BASE_API` stays pointed at the frame-level base throughout
+for the always-present header/status-bar JS.
+
+## Saved layouts
+
+A user can snapshot a frame's whole widget arrangement -- every widget's
+type/placement/settings, calendar/task sources, and button-action
+bindings -- under a name (`SavedLayout` + `SavedLayoutWidget` +
+`SavedLayoutSource` + `SavedLayoutButtonAction`, `server/app/models.py`),
+then switch back to it later, or apply it to a *different* frame. Saved
+layouts are owned by the **user**, not any one frame -- the same set
+shows up (with a per-frame `compatible` flag) on every frame that user
+controls whose grid matches (`grid.grid_dims(orientation)`'s cols/rows,
+landscape-class 8x5 vs. portrait-class 5x8), not just the frame it was
+captured from.
+
+Saving only captures an authored *setting*, never runtime/cache state --
+a photo widget's current queue position, a calendar's fetch cache, a
+whiteboard's rendered-image cache, etc. are deliberately left out (see
+`routers/api_layouts.py`'s `LAYOUT_CONFIG_FIELDS` allowlist per
+`widget_type`), so applying a layout feels like a fresh widget of that
+type with its settings pre-filled, not a resurrection of stale state
+from whenever it was saved. A static-image widget's uploaded bytes are
+the one exception carried through verbatim (`SavedLayoutWidget.image`).
+Saving again under a name the user already has overwrites that layout's
+snapshot in place rather than erroring or creating a duplicate --
+`SavedLayout`'s own docstring.
+
+Applying a layout to a frame (`api_layout_apply`, `require_frame_control`)
+deletes every widget currently on that frame and recreates the saved
+arrangement from scratch, remapping calendar/task sources and button
+bindings onto the newly-created widget ids -- same "act unconditionally
+on the server, confirm on the client" posture as the Layout tab's own
+"Clear all". A source whose owning user account no longer exists is
+silently dropped rather than left dangling (config is JSON, not
+FK-checked, so nothing else would catch that).
+
+The web UI lives in the Layout tab's "Saved layouts" card
+(`static/saved_layouts.js`, `GET`/`POST /api/frames/{id}/layouts`,
+`PATCH`/`DELETE /api/layouts/{id}`, `POST
+/api/frames/{id}/layouts/{id}/apply`) -- name + Save, then a list of
+saved layouts each with Apply/rename/delete, incompatible ones shown
+greyed-out with a "different orientation" badge rather than hidden.
+
+## Weather widget
+
+A standalone widget type (`models.WeatherWidgetConfig`, `app/widgets/
+weather.py`) -- distinct from, and unrelated in code to,
+`CalendarWidgetConfig`'s own embedded weather strip (still present,
+still Open-Meteo-only, still working exactly as before). Four display
+modes (`WeatherWidgetConfig.mode`, switchable in the widget's dialog like
+`calendar_view`):
+
+- `current` -- one city's current temp + a condition icon.
+- `hourly` -- one city, a row of ticks across the day at a configurable
+  interval (`hourly_interval_hours`: 3/4/6/12).
+- `daily` -- one city, a multi-day strip (`daily_days`, 1-14).
+- `multi_city` -- several cities' current-day high/low/icon side by
+  side -- the calendar widget's embedded strip, as a standalone
+  widget's whole content instead of a strip above an agenda day.
+
+`current`/`hourly`/`daily` share one configured location
+(`city_label`/`city_latitude`/`city_longitude`, set via `POST .../
+weather-location`, geocoded through `weather.geocode_city`); `multi_city`
+has its own list (`cities`, add/remove via `POST .../weather-widget-
+cities/add`|`remove` -- named to avoid colliding with the calendar
+widget's own, differently-scoped `weather-cities/add`|`remove` routes,
+which share the same `{widget_id}`-parameterized path shape).
+
+**Providers** (`app/weather/`, a dispatch registry over pluggable
+implementations mirroring `app/widgets/` itself): `WeatherWidgetConfig.
+provider` selects which of `app/weather.PROVIDERS` actually fetches --
+`"open_meteo"` (worldwide, no API key), `"nws"` (api.weather.gov, US
+only, no API key, approximates "current" with the first hourly forecast
+period rather than a real station observation), or `"ec"` (Environment
+Canada, api.weather.gc.ca's MSC GeoMet OGC API, Canada only, no API key).
+Every provider function returns already-normalized `{"category": ...}`
+entries (one of `clear`/`partly_cloudy`/`cloudy`/`fog`/`rain`/`snow`/
+`thunderstorm`) so `app/weather_render.py`'s drawing code never needs to
+know which provider supplied an entry. `geocode_city` (name -> lat/lon)
+always goes through Open-Meteo's free geocoder regardless of which
+provider is chosen to fetch with the result.
+
+EC's `citypageweather-realtime` collection is only queryable by bounding
+box (OGC API - Features), not a direct by-coordinate endpoint -- unlike
+Open-Meteo/NWS's simple lat/lon REST, `app/weather/ec.py`'s
+`_nearest_site` widens the box progressively and picks the closest site
+by straight-line distance, rejecting anything beyond 300 km (calibrated
+against a real bug caught in development: an unconditional "nearest
+site, however far" matched a Miami, FL query to a site in Ontario,
+1824 km away, once the box widened enough to cover the whole country).
+
+`app/weather_render.py` holds every weather-related drawing primitive:
+`draw_weather_icon`/`draw_weather_row` (extracted out of
+`calendar_render.py`, which still imports `draw_weather_row` for its own
+embedded strip, unchanged) plus this widget's own `build_current`/
+`build_hourly`/`build_daily`/`build_multi_city`, dispatched by `build()`
+-- the weather analogue of `calendar_render.py`'s own `_build_tasks`/
+`render_tasks_preview_png` relationship. Icons are hand-drawn (no custom
+font/icon asset), styled after Environment Canada's own icon set
+(pointed sun rays, a puffy cloud, teardrop rain, dendrite snowflakes, a
+zigzag bolt) but filled with the panel's *exact* ink RGB values rather
+than an arbitrary bitmap's anti-aliased colors -- a flat fill that's
+already a palette color quantizes with zero dithering error to diffuse,
+where a fetched/vendored icon's colors (almost never an exact match)
+dither into a visible speckle at these small on-panel sizes (confirmed
+by actually running one through the real quantize pass during
+development). Used for every provider's rendering, not just when EC is
+selected as the provider.
+
+## Battery widget
+
+The simplest widget type (`models.BatteryWidgetConfig`, `app/widgets/
+battery.py`): shows this frame's own last-reported battery level. Unlike
+every other widget type, there's no live upstream to poll and nothing to
+cache -- the content is `Frame.battery_percent`/`battery_as_of`, set by
+`routers/device.py`'s `frame_battery` on every device wake-on-battery
+report, which already existed for the Device panel's own history chart
+regardless of whether a battery widget is placed anywhere. The widget's
+own config is just a display mode: `"compact"` (icon + percent) or
+`"detailed"` (default, adds `routers/common.py`'s existing
+`battery_estimate_s` time-remaining estimate and the last report's age).
+`render()` falls back to a "No reports yet" placeholder for a frame that
+has never reported (never run on battery, or not yet claimed by a
+device) rather than showing a stale or fabricated number. The battery
+icon fill color (red/yellow/green by percent) uses the same exact-panel-
+ink-RGB approach as the weather icons above and `manage_overlay.py`'s own
+battery glyph on the "scan to manage" overlay -- a separate, unrelated
+piece of code with its own fixed small size, not shared with this
+widget, but drawing from the same thresholds/colors so a battery glyph
+reads the same wherever one shows up on a panel.
+
+## Known gaps (Phase 6, not yet done)
+
+The original 8-phase rollout plan's last phase is still open:
+
+- Legacy per-mode `Frame` columns (`mode`, `album_id`,
+  `current_asset_id`, all `calendar_*`, all `whiteboard_*`, etc.) are
+  still physically present in the schema but no longer read or written
+  anywhere -- they need a dedicated final migration to drop them. Left in
+  place deliberately through the widget-system rollout (a much larger
+  blast radius cutover than this project's usual same-migration-drop
+  convention) but there's no reason to keep carrying them now that every
+  phase has shipped.
+- `server/README.md` still describes photos/calendar/whiteboard as
+  per-frame "modes" in several places rather than widgets -- needs a pass
+  once the column drop above is safely deployed.
+- Whiteboard rendering is tagged **(alpha)** in the UI -- not fully
+  reliable yet, treat it as experimental if extending it.

firmware/README.md

@@ -66,8 +66,9 @@ Under **ESPresso Frame Configuration**:
 | `FRAME_NEXT_BUTTON_GPIO` | 2 | Next-photo button GPIO (-1 to disable). Must be 0-7 (ESP32-C6's deep-sleep-wakeup-capable pins) |
 | `FRAME_BACK_BUTTON_GPIO` | 0 | Back-photo button GPIO (-1 to disable). Must be 0-7 |
 | `FRAME_COMBO_BUTTON_GPIO` | 1 | Menu/reset button GPIO (-1 to disable). Must be 0-7 |
-| `FRAME_COMBO_SOFT_RESET_HOLD_MS` | 3000 | How long the combo button must be held (then released) to soft-reset |
+| `FRAME_COMBO_MENU_HOLD_MS` | 3000 | How long the combo button must be held (then released) to show the management menu |
 | `FRAME_COMBO_FACTORY_RESET_HOLD_MS` | 15000 | How long the combo button must be held to factory-reset |
+| `FRAME_HOLD_ACTION_MS` | 3000 | **Fallback only** -- how long NEXT/BACK must be held to trigger a global action instead of a short press; see below |
 | `FRAME_BATTERY_ADC_GPIO` | -1 (disabled) | Battery voltage-divider ADC GPIO; see the Battery section below |
 | `FRAME_VBUS_SENSE_GPIO` | -1 (disabled) | USB-power sense GPIO for hiding the battery indicator on mains |
 
@@ -84,6 +85,34 @@ reflashing. The Kconfig value only applies before the device has ever
 successfully reached a configured server, or if the response doesn't
 include a valid interval.
 
+### Holding NEXT/BACK for a global action
+
+Past `FRAME_HOLD_ACTION_MS`, holding NEXT or BACK stops meaning "advance/
+back this widget" and instead triggers whatever frame-wide action (if
+any) is configured for that button's hold on the server's Configuration
+tab -- e.g. cycling through saved layouts (see
+`server/app/global_actions.py`). Fires immediately at the threshold,
+without waiting for release -- same convention as the combo button's
+factory-reset tier below.
+
+Same "fallback only" caveat as `FRAME_SLEEP_INTERVAL_S` above, but with
+one more wrinkle: the server's actual `hold_duration_ms` (set on the
+Configuration tab, `GET /frame/config`'s response) can't be used for
+*this* wake's button decision -- that decision happens in `main.c`
+before WiFi even connects, but `/frame/config` isn't fetched until near
+the end of the wake cycle (after the image fetch, deliberately -- see
+`frame_client_run`'s own comment on why). So the device always acts on
+whatever value the *previous* wake fetched (persisted in NVS via
+`frame_config_set_hold_duration_ms`), falling back to
+`FRAME_HOLD_ACTION_MS` only before it's ever successfully fetched one.
+In practice this means changing the duration on the Configuration tab
+takes effect starting with the wake *after* the next one, not
+immediately.
+
+Holding a button through the poll loop keeps the device awake and
+connected longer than a normal short-press wake -- the same tradeoff
+already accepted for the combo button's menu/reset holds below.
+
 ### WiFi fast-connect
 
 After a successful home-WiFi connection, the device caches the AP's
@@ -121,8 +150,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 +214,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
 
@@ -197,6 +233,8 @@ device (if asleep) and tells the server to advance to the next photo
 right away, regardless of the configured refresh interval -- no long hold
 needed, since advancing is easily reversible by pressing again. See
 `FRAME_NEXT_BUTTON_GPIO` above to change the pin or disable the feature.
+Holding it past `FRAME_HOLD_ACTION_MS` instead means something else
+entirely -- see "Holding NEXT/BACK for a global action" above.
 
 Normal wakes and reboots never advance the photo on their own -- the
 server decides when to advance based on its own clock (see
@@ -216,7 +254,8 @@ disable the feature.
 
 If there's nothing to go back to yet (freshly provisioned, or you've
 already gone back as far as there is history), it's a no-op -- the
-current photo stays exactly as it was, no flash on the panel.
+current photo stays exactly as it was, no flash on the panel. Same
+long-hold caveat as the next-photo button above.
 
 ## Battery (XIAO ESP32-C6)
 
@@ -255,9 +294,13 @@ One more button, wired between GPIO1 and GND (same wiring style as the
 other buttons), covers three actions -- disambiguated purely by how
 long it's held:
 
-**A quick press** wakes the device and overlays several corners of
-whatever photo is currently showing, leaving the middle of the photo
-visible and unchanged:
+**A quick press** soft-resets the device -- `esp_restart()`, keeping the
+stored WiFi/server config. Useful for recovering a hung device without
+losing setup.
+
+**Holding it ~3 seconds, then releasing** wakes the device (if asleep)
+and overlays several corners of whatever photo is currently showing,
+leaving the middle of the photo visible and unchanged:
 
 - **Top-right**: a QR code -- "SCAN TO MANAGE" -- linking to the
   server's config page.
@@ -276,8 +319,9 @@ for faces Immich hasn't been told a name for; no face detection happens
 on the device or the server, this is entirely Immich's own People
 feature). A third press exits immediately rather than waiting out the
 30-second timer. Holding the button during this stage doesn't trigger
-either reset tier below -- the hold-duration read only ever happens
-once, right when the device first wakes, before any menu is shown.
+the factory-reset tier below -- the hold-duration read only ever
+happens once, right when the device first wakes, before any menu is
+shown.
 
 The device stays awake for the whole menu interaction (up to three
 physical refreshes: the base overlay, the escalated one, and
@@ -285,17 +329,13 @@ reverting), so this costs meaningfully more power than a normal wake --
 expected for a deliberate, occasional action, same tradeoff as the
 other buttons.
 
-**Holding it ~3 seconds, then releasing** soft-resets the device --
-`esp_restart()`, keeping the stored WiFi/server config. Useful for
-recovering a hung device without losing setup.
-
 **Holding it ~15 seconds** (whether or not you're still holding it --
 this fires immediately, it doesn't wait for release) clears the stored
 WiFi/server config and restarts into provisioning. From either power-on
 or while the device is deep-asleep, since this GPIO is armed as a
 wakeup source.
 
-See `FRAME_COMBO_BUTTON_GPIO`, `FRAME_COMBO_SOFT_RESET_HOLD_MS`, and
+See `FRAME_COMBO_BUTTON_GPIO`, `FRAME_COMBO_MENU_HOLD_MS`, and
 `FRAME_COMBO_FACTORY_RESET_HOLD_MS` above to change the pin or hold
 durations, or disable all three actions.
 

firmware/main/CMakeLists.txt

@@ -1,3 +1,3 @@
-idf_component_register(SRCS main.c wifi_provisioning.c frame_client.c qr_onboarding.c status_screen.c epd_draw.c next_button.c back_button.c combo_button.c manage_qr_overlay.c battery.c ota_update.c board_antenna.c
+idf_component_register(SRCS main.c wifi_provisioning.c frame_client.c qr_onboarding.c status_screen.c epd_draw.c next_button.c back_button.c combo_button.c battery.c ota_update.c board_antenna.c
                        PRIV_REQUIRES esp_event nvs_flash esp_wifi esp_netif esp_http_server esp_http_client mbedtls dns_server epd7in3e qrcode epaper_fonts esp_driver_gpio esp_adc esp_https_ota app_update esp_app_format
                        EMBED_FILES root.html)

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
@@ -139,13 +154,12 @@ menu "ESPresso Frame Configuration"
             Button wired between this GPIO and GND (active-low, internal
             pull-up enabled in firmware -- no external resistor needed).
             One pin, three actions depending on how long it's held:
-            a quick press shows the management menu (same as before);
-            holding it FRAME_COMBO_SOFT_RESET_HOLD_MS then releasing
-            soft-resets the device (reboots, keeps the stored WiFi/
-            server config); holding it all the way to
-            FRAME_COMBO_FACTORY_RESET_HOLD_MS clears the stored config
-            and restarts into provisioning, regardless of whether it's
-            released yet. Must be GPIO 0-7 for the same deep-sleep-
+            a quick press soft-resets the device (reboots, keeps the
+            stored WiFi/server config); holding it FRAME_COMBO_MENU_HOLD_MS
+            then releasing shows the management menu; holding it all the
+            way to FRAME_COMBO_FACTORY_RESET_HOLD_MS clears the stored
+            config and restarts into provisioning, regardless of whether
+            it's released yet. Must be GPIO 0-7 for the same deep-sleep-
             wakeup reason as FRAME_NEXT_BUTTON_GPIO above; defaults to
             a different pin than the other buttons. Set to -1 to
             disable the feature entirely (also disables the management
@@ -153,14 +167,14 @@ menu "ESPresso Frame Configuration"
             reconfiguring then only works by erasing NVS over USB, see
             firmware/README.md).
 
-    config FRAME_COMBO_SOFT_RESET_HOLD_MS
-        int "Soft-reset hold duration (ms)"
+    config FRAME_COMBO_MENU_HOLD_MS
+        int "Management-menu hold duration (ms)"
         default 3000
         depends on FRAME_COMBO_BUTTON_GPIO >= 0
         help
             How long the menu/reset button must be held before releasing
-            it triggers a soft reset (reboot, config kept). Long enough
-            to be clearly distinct from a quick menu-opening press.
+            it shows the management menu instead of soft-resetting. Long
+            enough to be clearly distinct from a quick reset tap.
 
     config FRAME_COMBO_FACTORY_RESET_HOLD_MS
         int "Factory-reset hold duration (ms)"
@@ -170,8 +184,25 @@ menu "ESPresso Frame Configuration"
             How long the menu/reset button must be held continuously
             before the device clears its stored config and reboots into
             provisioning, regardless of release. Comfortably longer than
-            FRAME_COMBO_SOFT_RESET_HOLD_MS so the two tiers can't be
-            confused for each other.
+            FRAME_COMBO_MENU_HOLD_MS so the two tiers can't be confused
+            for each other.
+
+    config FRAME_HOLD_ACTION_MS
+        int "Next/back hold-for-global-action duration (ms)"
+        default 3000
+        range 3000 10000
+        help
+            How long the NEXT or BACK button must be held before it
+            triggers a frame-wide action (see server/app/global_actions.py
+            -- e.g. cycling saved layouts) instead of that button's normal
+            short-press behavior. Only a first-boot/never-connected
+            fallback: once the device has fetched GET /frame/config at
+            least once, the server's own Frame.hold_duration_ms (set on
+            the Configuration tab) overrides this on every later boot --
+            see wifi_provisioning.h's frame_config_get_hold_duration_ms.
+            Floor matches the server's own minimum, so a long-held button
+            never means something different depending on which value
+            happened to apply.
 
     config FRAME_BATTERY_ADC_GPIO
         int "Battery voltage-divider ADC GPIO (-1 to disable)"

firmware/main/back_button.c

@@ -1,3 +1,5 @@
+#include <stdint.h>
+
 #include "driver/gpio.h"
 #include "esp_log.h"
 #include "esp_sleep.h"
@@ -5,6 +7,8 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 
+#include "wifi_provisioning.h"
+
 #include "back_button.h"
 
 static const char *TAG = "back_button";
@@ -14,6 +18,7 @@ static const char *TAG = "back_button";
 #define BACK_BUTTON_GPIO ((gpio_num_t)CONFIG_FRAME_BACK_BUTTON_GPIO)
 #define BACK_BUTTON_DEBOUNCE_MS 20
 #define BACK_BUTTON_DEBOUNCE_CHECKS 3
+#define BACK_BUTTON_POLL_MS 100
 
 void back_button_init(void)
 {
@@ -36,7 +41,7 @@ void back_button_init(void)
     esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(1ULL << BACK_BUTTON_GPIO, ESP_GPIO_WAKEUP_GPIO_LOW);
 }
 
-bool back_button_check(void)
+back_button_result_t back_button_check(void)
 {
     /* A quick tap can easily release before this runs (~0.4-0.5s into
      * boot, confirmed on hardware -- a live gpio_get_level() check here
@@ -44,32 +49,49 @@ bool back_button_check(void)
      * status register is latched at the moment of waking and isn't
      * cleared until the next sleep entry, so it reliably reflects a tap
      * regardless of how quickly it was released. */
-    if (esp_sleep_get_gpio_wakeup_status() & (1ULL << BACK_BUTTON_GPIO)) {
-        ESP_LOGI(TAG, "Back-photo button caused this wake, going back");
-        return true;
-    }
+    bool caused_wake = esp_sleep_get_gpio_wakeup_status() & (1ULL << BACK_BUTTON_GPIO);
 
-    /* Not a GPIO-wakeup-from-this-pin boot (normal timer wake, or a fresh
-     * power-on/reflash) -- fall back to a live, debounced level check so
-     * holding the button down while powering on also works. */
-    if (gpio_get_level(BACK_BUTTON_GPIO) != 0) {
-        return false;
-    }
-
-    for (int i = 0; i < BACK_BUTTON_DEBOUNCE_CHECKS; i++) {
-        vTaskDelay(pdMS_TO_TICKS(BACK_BUTTON_DEBOUNCE_MS));
+    if (!caused_wake) {
+        /* Not a GPIO-wakeup-from-this-pin boot (normal timer wake, or a
+         * fresh power-on/reflash) -- fall back to a live, debounced level
+         * check so holding the button down while powering on also
+         * works. */
         if (gpio_get_level(BACK_BUTTON_GPIO) != 0) {
-            return false; /* noise, not a real press */
+            return BACK_BUTTON_NOT_PRESSED;
+        }
+        for (int i = 0; i < BACK_BUTTON_DEBOUNCE_CHECKS; i++) {
+            vTaskDelay(pdMS_TO_TICKS(BACK_BUTTON_DEBOUNCE_MS));
+            if (gpio_get_level(BACK_BUTTON_GPIO) != 0) {
+                return BACK_BUTTON_NOT_PRESSED; /* noise, not a real press */
+            }
         }
     }
 
-    ESP_LOGI(TAG, "Back-photo button held during power-on, going back");
-    return true;
+    /* Confirmed pressed -- measure how long, same reasoning/pattern as
+     * next_button_check(). */
+    uint32_t hold_threshold_ms;
+    if (frame_config_get_hold_duration_ms(&hold_threshold_ms) != ESP_OK) {
+        hold_threshold_ms = CONFIG_FRAME_HOLD_ACTION_MS;
+    }
+
+    uint32_t elapsed_ms = 0;
+    while (gpio_get_level(BACK_BUTTON_GPIO) == 0) {
+        if (elapsed_ms >= hold_threshold_ms) {
+            ESP_LOGI(TAG, "Back button held past %ums, triggering global hold action",
+                     (unsigned)hold_threshold_ms);
+            return BACK_BUTTON_HOLD;
+        }
+        vTaskDelay(pdMS_TO_TICKS(BACK_BUTTON_POLL_MS));
+        elapsed_ms += BACK_BUTTON_POLL_MS;
+    }
+
+    ESP_LOGI(TAG, "Back-photo button short press (%ums), going back", (unsigned)elapsed_ms);
+    return BACK_BUTTON_SHORT_PRESS;
 }
 
 #else
 
 void back_button_init(void) {}
-bool back_button_check(void) { return false; }
+back_button_result_t back_button_check(void) { return BACK_BUTTON_NOT_PRESSED; }
 
 #endif

firmware/main/back_button.h

@@ -12,9 +12,23 @@
  */
 void back_button_init(void);
 
+typedef enum {
+    BACK_BUTTON_NOT_PRESSED,
+    /** A short press -- same immediate-response reasoning as the
+     * next-photo button. */
+    BACK_BUTTON_SHORT_PRESS,
+    /** Held past the configured hold duration (see
+     * wifi_provisioning.h's frame_config_get_hold_duration_ms) --
+     * triggers a frame-wide action instead (see
+     * server/app/global_actions.py, frame_client.h's FETCH_GLOBAL_BACK).
+     * Fires immediately at the threshold, without waiting for release. */
+    BACK_BUTTON_HOLD,
+} back_button_result_t;
+
 /**
- * Returns whether the back-photo button is currently held, debounced with
- * a couple of short re-checks to reject noise. Same immediate-response
- * reasoning as the next-photo button -- no long hold-to-confirm gate.
+ * Checks the back-photo button and, if it's pressed at all, blocks
+ * polling its level until either it's released (BACK_BUTTON_SHORT_PRESS)
+ * or the hold duration elapses (BACK_BUTTON_HOLD) -- same pattern as
+ * next_button_check(). Evaluated once per wake.
  */
-bool back_button_check(void);
+back_button_result_t back_button_check(void);

firmware/main/battery.c

@@ -1,3 +1,5 @@
+#include <stdlib.h>
+
 #include "driver/gpio.h"
 #include "esp_adc/adc_cali_scheme.h"
 #include "esp_adc/adc_oneshot.h"
@@ -11,7 +13,13 @@ static const char *TAG = "battery";
 #if CONFIG_FRAME_BATTERY_ADC_GPIO >= 0
 
 #define BATTERY_ADC_GPIO CONFIG_FRAME_BATTERY_ADC_GPIO
-#define BATTERY_SAMPLES 8
+#define BATTERY_SAMPLES 16
+/* Trimmed mean: the extreme BATTERY_TRIM samples on each end (regulator/
+ * RF transients, not the true resting voltage) are dropped before
+ * averaging the rest -- a plain average lets even one or two of those
+ * skew the result enough to read as a real percent change downstream
+ * (see the recharge-jump handling in routers/device.py). */
+#define BATTERY_TRIM 3
 /* The external divider halves the battery voltage (2x200k, per the
  * Seeed-documented XIAO wiring) so a full 4.2V cell reads ~2.1V at the
  * pin, inside the 12dB-attenuation ADC range. */
@@ -34,6 +42,11 @@ static const struct {
     { 3300, 5 },   { 3000, 0 },
 };
 
+static int int_cmp(const void *a, const void *b)
+{
+    return *(const int *)a - *(const int *)b;
+}
+
 static int mv_to_percent(int mv)
 {
     int n = sizeof(LIPO_CURVE) / sizeof(LIPO_CURVE[0]);
@@ -139,19 +152,17 @@ int battery_read_percent(void)
         ESP_LOGW(TAG, "ADC calibration unavailable, using nominal scaling");
     }
 
-    int mv_sum = 0;
+    int mv_samples[BATTERY_SAMPLES];
     int samples = 0;
     for (int i = 0; i < BATTERY_SAMPLES; i++) {
         int value;
         if (calibrated) {
             if (adc_oneshot_get_calibrated_result(adc, cali, channel, &value) == ESP_OK) {
-                mv_sum += value;
-                samples++;
+                mv_samples[samples++] = value;
             }
         } else {
             if (adc_oneshot_read(adc, channel, &value) == ESP_OK) {
-                mv_sum += value * 3300 / 4095; /* nominal 12-bit full scale at 12dB */
-                samples++;
+                mv_samples[samples++] = value * 3300 / 4095; /* nominal 12-bit full scale at 12dB */
             }
         }
     }
@@ -167,7 +178,19 @@ int battery_read_percent(void)
         return -1;
     }
 
-    int battery_mv = (mv_sum / samples) * BATTERY_DIVIDER_RATIO;
+    /* Only trim if there's enough left afterward to still be a
+     * meaningful average -- falls back to a plain average of whatever
+     * came in on a wake where most reads failed. */
+    qsort(mv_samples, samples, sizeof(int), int_cmp);
+    int trim = (samples > 2 * BATTERY_TRIM) ? BATTERY_TRIM : 0;
+    int mv_sum = 0;
+    int kept = 0;
+    for (int i = trim; i < samples - trim; i++) {
+        mv_sum += mv_samples[i];
+        kept++;
+    }
+
+    int battery_mv = (mv_sum / kept) * BATTERY_DIVIDER_RATIO;
     if (battery_mv < BATTERY_MV_MIN || battery_mv > BATTERY_MV_MAX) {
         ESP_LOGI(TAG, "Reading %dmV outside plausible battery range, ignoring", battery_mv);
         return -1;

firmware/main/combo_button.c

@@ -53,8 +53,8 @@ bool combo_button_check(void)
         return false; /* not pressed, and didn't cause this wake either */
     }
 
-    ESP_LOGI(TAG, "Combo button held -- quick press for menu, %dms for soft reset, %dms for factory reset",
-             CONFIG_FRAME_COMBO_SOFT_RESET_HOLD_MS, CONFIG_FRAME_COMBO_FACTORY_RESET_HOLD_MS);
+    ESP_LOGI(TAG, "Combo button held -- quick press for soft reset, %dms for menu, %dms for factory reset",
+             CONFIG_FRAME_COMBO_MENU_HOLD_MS, CONFIG_FRAME_COMBO_FACTORY_RESET_HOLD_MS);
 
     int elapsed_ms = 0;
     while (gpio_get_level(COMBO_BUTTON_GPIO) == 0) {
@@ -70,13 +70,13 @@ bool combo_button_check(void)
         }
     }
 
-    if (elapsed_ms >= CONFIG_FRAME_COMBO_SOFT_RESET_HOLD_MS) {
-        ESP_LOGW(TAG, "Held %dms and released, soft-restarting (config kept)", elapsed_ms);
-        esp_restart();
+    if (elapsed_ms >= CONFIG_FRAME_COMBO_MENU_HOLD_MS) {
+        ESP_LOGI(TAG, "Held %dms and released, showing management menu", elapsed_ms);
+        return true;
     }
 
-    ESP_LOGI(TAG, "Quick press (%dms), showing management menu", elapsed_ms);
-    return true;
+    ESP_LOGW(TAG, "Quick press (%dms), soft-restarting (config kept)", elapsed_ms);
+    esp_restart();
 }
 
 bool combo_button_is_pressed(void)

firmware/main/combo_button.h

@@ -16,11 +16,11 @@ void combo_button_init(void);
  * Checks the combined menu/reset button and acts on how long it was
  * held, evaluated once per wake:
  *   - Not pressed: returns false immediately.
- *   - Released before CONFIG_FRAME_COMBO_SOFT_RESET_HOLD_MS (a quick
- *     press): returns true -- caller should show the management menu.
- *   - Released between the soft-reset and factory-reset thresholds: a
- *     soft reset (esp_restart(), stored WiFi/server config kept) --
+ *   - Released before CONFIG_FRAME_COMBO_MENU_HOLD_MS (a quick press):
+ *     a soft reset (esp_restart(), stored WiFi/server config kept) --
  *     never returns.
+ *   - Released between the menu and factory-reset thresholds: returns
+ *     true -- caller should show the management menu.
  *   - Held through CONFIG_FRAME_COMBO_FACTORY_RESET_HOLD_MS: a factory
  *     reset (frame_config_clear() + esp_restart(), fires immediately
  *     without waiting for release) -- never returns.

firmware/main/frame_client.c

@@ -16,10 +16,10 @@
 
 #include "epd7in3e.h"
 #include "status_screen.h"
-#include "manage_qr_overlay.h"
 #include "combo_button.h"
 #include "ota_update.h"
 #include "board_antenna.h"
+#include "battery.h"
 
 #include "frame_client.h"
 
@@ -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);
     }
 }
 
@@ -265,7 +276,20 @@ esp_err_t frame_wifi_connect_sta(const frame_config_t *cfg)
 typedef struct {
     bool reachable;
     uint32_t refresh_interval_s; /* CONFIG_FRAME_SLEEP_INTERVAL_S if absent/unparseable */
+    /* How long NEXT/BACK must be held to trigger a global action instead
+     * of a short press (see next_button.h/back_button.h) --
+     * CONFIG_FRAME_HOLD_ACTION_MS if absent/unparseable (older server) or
+     * unreachable. Persisted via frame_config_set_hold_duration_ms() for
+     * the *next* boot's button-hold decision -- this fetch happens too
+     * late in the cycle for its own boot's decision, see that function's
+     * own doc comment. */
+    uint32_t hold_duration_ms;
     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,16 +366,22 @@ 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 = {
         .reachable = false,
         .refresh_interval_s = CONFIG_FRAME_SLEEP_INTERVAL_S,
+        .hold_duration_ms = CONFIG_FRAME_HOLD_ACTION_MS,
     };
     result.firmware_version[0] = '\0';
+    result.device_token[0] = '\0';
 
     char url[256];
     build_url(url, sizeof(url), cfg, "frame/config");
@@ -364,6 +394,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 +406,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 &&
@@ -394,251 +428,66 @@ static frame_server_config_t fetch_frame_config(const frame_config_t *cfg)
         ESP_LOGW(TAG, "'%s' response missing refresh_interval_s, using fallback %ds", url,
                  (int)result.refresh_interval_s);
     }
+    uint32_t hold_ms;
+    if (json_extract_uint(body, "hold_duration_ms", &hold_ms)) {
+        result.hold_duration_ms = hold_ms;
+    }
     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;
 }
 
-/* GETs the server's /frame/photo-info for the manage-button overlay:
- * location/taken_at text (left empty if the server didn't have them --
- * e.g. no GPS EXIF to geocode, or no capture date) and a share_url built
- * from the returned asset_id, same construction pattern as
- * run_fetch_cycle()'s management_url. Any failure (unreachable, no
- * current photo, etc.) just leaves all outputs empty -- the caller
- * treats that as "skip these optional overlay regions", not a hard
- * error, since the base "scan to manage" QR should still show. */
-static void fetch_photo_info(const frame_config_t *cfg, char *location_line1, size_t location_line1_size,
-                              char *location_line2, size_t location_line2_size, char *taken_at, size_t taken_at_size,
-                              char *share_url, size_t share_url_size)
-{
-    location_line1[0] = '\0';
-    location_line2[0] = '\0';
-    taken_at[0] = '\0';
-    share_url[0] = '\0';
-
-    char url[256];
-    build_url(url, sizeof(url), cfg, "frame/photo-info");
-
-    /* CONFIG_FRAME_FETCH_TIMEOUT_MS, not the shorter SERVER_CHECK one:
-     * unlike fetch_frame_config() (always called after the image fetch
-     * has already warmed the connection, see frame_client_run()), this
-     * is the *first* network call of the wake cycle whenever the manage
-     * menu is opened -- same cold-connection latency spike that made
-     * the short timeout unreliable for /frame/config before, now worse
-     * with a real TLS handshake on top. Confirmed on hardware: this
-     * timed out under CONFIG_FRAME_SERVER_CHECK_TIMEOUT_MS while the
-     * rest of the cycle (a fresh connection, but not the *first* one)
-     * succeeded fine. */
-    esp_http_client_config_t config = {
-        .url = url,
-        .method = HTTP_METHOD_GET,
-        .timeout_ms = CONFIG_FRAME_FETCH_TIMEOUT_MS,
-        .crt_bundle_attach = esp_crt_bundle_attach,
-    };
-    esp_http_client_handle_t client = esp_http_client_init(&config);
-
-    esp_err_t err = esp_http_client_open(client, 0);
-    if (err != ESP_OK) {
-        ESP_LOGW(TAG, "'%s' not reachable: %s", url, esp_err_to_name(err));
-        esp_http_client_cleanup(client);
-        return;
-    }
-
-    int status = esp_http_client_fetch_headers(client) >= 0 ? esp_http_client_get_status_code(client) : -1;
-    if (status != 200) {
-        ESP_LOGW(TAG, "'%s' returned HTTP %d", url, status);
-        esp_http_client_close(client);
-        esp_http_client_cleanup(client);
-        return;
-    }
-
-    char body[384];
-    int total = 0;
-    int n;
-    while (total < (int)sizeof(body) - 1 &&
-           (n = esp_http_client_read(client, body + total, sizeof(body) - 1 - total)) > 0) {
-        total += n;
-    }
-    body[total] = '\0';
-
-    esp_http_client_close(client);
-    esp_http_client_cleanup(client);
-
-    json_extract_string(body, "location_line1", location_line1, location_line1_size);
-    json_extract_string(body, "location_line2", location_line2, location_line2_size);
-    json_extract_string(body, "taken_at", taken_at, taken_at_size);
-
-    char asset_id[48];
-    if (json_extract_string(body, "asset_id", asset_id, sizeof(asset_id))) {
-        char path[80];
-        snprintf(path, sizeof(path), "frame/share/%s", asset_id);
-        build_url(share_url, share_url_size, cfg, path);
-    }
-}
-
-/* GETs the server's /frame/face-labels for the manage-button's escalated
- * "level 2" menu -- named-face positions, if Immich has any for the
- * current photo. Response is a flattened, fixed-slot shape ("count",
- * then name_0/x_0/y_0, name_1/x_1/y_1, ...) rather than a real JSON
- * array, read with the same flat-scalar helpers as everywhere else in
- * this file instead of needing an actual array parser. Any failure
- * (unreachable, malformed response, etc.) just returns 0 -- named faces
- * are a "nice to have" addition to the menu, not worth failing it over. */
-static int fetch_face_labels(const frame_config_t *cfg, manage_face_label_t *out, int max_labels)
-{
-    char url[256];
-    build_url(url, sizeof(url), cfg, "frame/face-labels");
-
-    /* Same reasoning as fetch_photo_info() -- this is a manage-menu
-     * request too, not a warmed-connection reachability check. */
-    esp_http_client_config_t config = {
-        .url = url,
-        .method = HTTP_METHOD_GET,
-        .timeout_ms = CONFIG_FRAME_FETCH_TIMEOUT_MS,
-        .crt_bundle_attach = esp_crt_bundle_attach,
-    };
-    esp_http_client_handle_t client = esp_http_client_init(&config);
-
-    esp_err_t err = esp_http_client_open(client, 0);
-    if (err != ESP_OK) {
-        ESP_LOGW(TAG, "'%s' not reachable: %s", url, esp_err_to_name(err));
-        esp_http_client_cleanup(client);
-        return 0;
-    }
-
-    int status = esp_http_client_fetch_headers(client) >= 0 ? esp_http_client_get_status_code(client) : -1;
-    if (status != 200) {
-        ESP_LOGW(TAG, "'%s' returned HTTP %d", url, status);
-        esp_http_client_close(client);
-        esp_http_client_cleanup(client);
-        return 0;
-    }
-
-    char body[768];
-    int total = 0;
-    int n;
-    while (total < (int)sizeof(body) - 1 &&
-           (n = esp_http_client_read(client, body + total, sizeof(body) - 1 - total)) > 0) {
-        total += n;
-    }
-    body[total] = '\0';
-
-    esp_http_client_close(client);
-    esp_http_client_cleanup(client);
-
-    uint32_t count = 0;
-    json_extract_uint(body, "count", &count);
-    if ((int)count > max_labels) {
-        count = (uint32_t)max_labels;
-    }
-
-    int found = 0;
-    for (uint32_t i = 0; i < count; i++) {
-        char key[16];
-        snprintf(key, sizeof(key), "name_%u", (unsigned)i);
-        if (!json_extract_string(body, key, out[found].name, sizeof(out[found].name))) {
-            continue;
-        }
-        snprintf(key, sizeof(key), "x_%u", (unsigned)i);
-        uint32_t x;
-        if (!json_extract_uint(body, key, &x)) {
-            continue;
-        }
-        snprintf(key, sizeof(key), "y_%u", (unsigned)i);
-        uint32_t y;
-        if (!json_extract_uint(body, key, &y)) {
-            continue;
-        }
-        out[found].x = (int)x;
-        out[found].y = (int)y;
-        found++;
-    }
-    return found;
-}
-
 typedef struct {
     esp_http_client_handle_t client;
-    size_t stream_pos;                 /* running absolute offset into the frame, for overlay splicing */
-    const manage_overlay_set_t *overlay; /* NULL = no overlay this fetch */
 } http_read_ctx_t;
 
-/* Splices one overlay region's pixels over the real photo bytes in chunk
- * wherever chunk's absolute byte range [chunk_start, chunk_start+chunk_len)
- * within the full frame intersects that region's rectangle. Rows/chunks
- * outside the region's footprint are left completely untouched.
- * region->x0 is always even (see manage_qr_overlay.h), so byte_x0 below
- * is exact. */
-static void splice_overlay_region(uint8_t *chunk, size_t chunk_len, size_t chunk_start,
-                                   const manage_overlay_region_t *region)
-{
-    int byte_x0 = region->x0 / 2;
-    int byte_w = region->w / 2;
-    size_t chunk_end = chunk_start + chunk_len;
-
-    for (int row = region->y0; row < region->y0 + region->h; row++) {
-        size_t row_start = (size_t)row * EPD_BYTES_PER_ROW + (size_t)byte_x0;
-        size_t row_end = row_start + (size_t)byte_w;
-
-        size_t lo = row_start > chunk_start ? row_start : chunk_start;
-        size_t hi = row_end < chunk_end ? row_end : chunk_end;
-        if (lo >= hi) {
-            continue;
-        }
-
-        size_t region_row_offset = (size_t)(row - region->y0) * (size_t)byte_w + (lo - row_start);
-        memcpy(chunk + (lo - chunk_start), region->buf + region_row_offset, hi - lo);
-    }
-}
-
-static void splice_overlay(uint8_t *chunk, size_t chunk_len, size_t chunk_start, const manage_overlay_set_t *overlay)
-{
-    for (int i = 0; i < overlay->count; i++) {
-        splice_overlay_region(chunk, chunk_len, chunk_start, &overlay->regions[i]);
-    }
-}
-
 /* Pulls the next chunk straight out of the in-progress HTTP response --
  * epd_write_frame() calls this to feed the panel without ever holding
- * the full ~192KB frame in RAM. Splices in ctx->overlay's regions (if
- * set) as chunks pass through, so the panel driver never needs to know
- * an overlay exists at all. */
+ * the full ~192KB frame in RAM. Just a plain relay: the manage overlay
+ * (scan-to-manage QR, battery, location/date, share-QR, named face
+ * labels) is composited server-side now (see server/app/manage_overlay.py),
+ * baked into the same image bytes as any other render -- this function,
+ * like the rest of this file, has no idea an overlay exists. */
 static size_t http_read_fn(uint8_t *chunk, size_t chunk_size, void *ctx_)
 {
     http_read_ctx_t *ctx = (http_read_ctx_t *)ctx_;
     int n = esp_http_client_read(ctx->client, (char *)chunk, (int)chunk_size);
-    if (n <= 0) {
-        return 0;
-    }
-
-    if (ctx->overlay != NULL) {
-        splice_overlay(chunk, (size_t)n, ctx->stream_pos, ctx->overlay);
-    }
-    ctx->stream_pos += (size_t)n;
-
-    return (size_t)n;
+    return n > 0 ? (size_t)n : 0;
 }
 
-/* GETs /frame/image (FETCH_NORMAL), or POSTs /frame/advance or
- * /frame/back to force a move in either direction (FETCH_ADVANCE /
- * FETCH_BACK -- the next-photo / back-photo buttons), and streams the
- * response directly into the panel, splicing in overlay's pixels (if
- * non-NULL) as it streams. Returning non-ESP_OK means the panel was
- * never actually refreshed -- epd_display_stream() (see epd7in3e.c)
- * refuses to trigger a physical refresh on a short/wrong-size stream,
- * so a failure here always leaves the visible screen exactly as it
- * was. */
-static esp_err_t fetch_and_display(const frame_config_t *cfg, fetch_action_t action,
-                                    const manage_overlay_set_t *overlay)
+/* GETs /frame/image (FETCH_NORMAL), or POSTs /frame/advance, /frame/back,
+ * /frame/global-next, or /frame/global-back to force a move/action
+ * (FETCH_ADVANCE / FETCH_BACK -- a short press; FETCH_GLOBAL_NEXT /
+ * FETCH_GLOBAL_BACK -- a held press, see next_button.h/back_button.h).
+ * manage=true (the manage button) appends &manage=1, telling the server
+ * to bake its overlay into this same response instead of returning the
+ * bare content -- see server/app/routers/device.py. Returning non-ESP_OK
+ * means the panel was never actually refreshed -- epd_display_stream()
+ * (see epd7in3e.c) refuses to trigger a physical refresh on a short/
+ * wrong-size stream, so a failure here always leaves the visible screen
+ * exactly as it was. */
+static esp_err_t fetch_and_display(const frame_config_t *cfg, fetch_action_t action, bool manage)
 {
     const char *path = "frame/image";
     if (action == FETCH_ADVANCE) {
         path = "frame/advance";
     } else if (action == FETCH_BACK) {
         path = "frame/back";
+    } else if (action == FETCH_GLOBAL_NEXT) {
+        path = "frame/global-next";
+    } else if (action == FETCH_GLOBAL_BACK) {
+        path = "frame/global-back";
     }
 
     char url[256];
     build_url(url, sizeof(url), cfg, path);
+    if (manage) {
+        size_t len = strlen(url);
+        if (len + strlen("&manage=1") < sizeof(url)) {
+            strcpy(url + len, "&manage=1");
+        }
+    }
 
     esp_http_client_config_t config = {
         .url = url,
@@ -665,7 +514,7 @@ static esp_err_t fetch_and_display(const frame_config_t *cfg, fetch_action_t act
     }
     ESP_LOGI(TAG, "Fetching frame (%d bytes) from '%s'", content_length, url);
 
-    http_read_ctx_t ctx = { .client = client, .overlay = overlay };
+    http_read_ctx_t ctx = { .client = client };
     uint32_t crc = 0;
     err = epd_write_frame(http_read_fn, &ctx, &crc);
 
@@ -693,8 +542,7 @@ static esp_err_t fetch_and_display(const frame_config_t *cfg, fetch_action_t act
     return err;
 }
 
-#define MANAGE_MENU_MAX_LEVEL 2
-#define MANAGE_MENU_LEVEL_TIMEOUT_MS 30000
+#define MANAGE_MENU_TIMEOUT_MS 30000
 #define MANAGE_MENU_POLL_MS 150
 #define MANAGE_MENU_DEBOUNCE_MS 30
 
@@ -726,110 +574,42 @@ static bool wait_for_button_press(uint32_t timeout_ms)
     return false;
 }
 
-/* Builds and shows one level of the manage menu: level 1 is the base
- * overlay (management QR + location/date/share-QR wherever the server
- * had that data); level 2 adds named-face labels on top. action only
- * applies at level 1 -- escalating to level 2 redisplays the same
- * photo, so it never re-advances/-backs. */
-static esp_err_t show_menu_level(const frame_config_t *cfg, fetch_action_t action, int level,
-                                  int battery_percent)
+/* Runs the manage-button view: fetches once with manage=1 (the server
+ * bakes its whole overlay -- scan-to-manage QR, battery, location/date/
+ * share-QR, every named face label, no more RAM-driven cap on how many --
+ * into the response), shows it, then waits up to 30s for either another
+ * press or the timeout before reverting to a plain fetch. Device stays
+ * awake throughout (doesn't sleep the panel or the chip). Returns
+ * non-ESP_OK only if the manage fetch itself failed; a revert failure
+ * after that is logged but doesn't count as an overall failure --
+ * something was already shown successfully, which was the point of the
+ * button. */
+static esp_err_t run_management_menu(const frame_config_t *cfg, fetch_action_t action)
 {
-    char management_url[256];
-    build_url(management_url, sizeof(management_url), cfg, "");
-
-    char location_line1[32];
-    char location_line2[32];
-    char taken_at[32];
-    /* Wider than the other URL buffers in this file: unlike a fixed path,
-     * this one stacks toolsserver (up to 128) + "/frame/share/" + an
-     * asset_id (up to 47) + "?token=" + an access_token (up to 64) --
-     * worst case ~266 bytes, which a 256-byte buffer could silently
-     * truncate the token off of (build_url()'s bounds check avoids an
-     * overflow, but a truncated/dropped token still means the resulting
-     * request just 401s with no obvious cause). */
-    char share_url[320];
-    fetch_photo_info(cfg, location_line1, sizeof(location_line1), location_line2,
-                      sizeof(location_line2), taken_at, sizeof(taken_at), share_url, sizeof(share_url));
-
-    manage_face_label_t face_labels[MANAGE_FACE_LABELS_MAX];
-    int face_label_count = 0;
-    if (level >= 2) {
-        face_label_count = fetch_face_labels(cfg, face_labels, MANAGE_FACE_LABELS_MAX);
-    }
-
-    manage_overlay_content_t content = {
-        .management_url = management_url,
-        .location_line1 = location_line1[0] != '\0' ? location_line1 : NULL,
-        .location_line2 = location_line2[0] != '\0' ? location_line2 : NULL,
-        .taken_at = taken_at[0] != '\0' ? taken_at : NULL,
-        .share_url = share_url[0] != '\0' ? share_url : NULL,
-        .face_labels = face_labels,
-        .face_label_count = face_label_count,
-        .battery_percent = battery_percent,
-    };
-
-    manage_overlay_set_t overlay;
-    esp_err_t err = manage_overlay_render(&content, &overlay);
+    esp_err_t err = fetch_and_display(cfg, action, true);
     if (err != ESP_OK) {
-        manage_overlay_free(&overlay);
-        return err;
+        ESP_LOGW(TAG, "Could not fetch manage view (%s), showing photo normally", esp_err_to_name(err));
+        return fetch_and_display(cfg, action, false);
     }
 
-    err = fetch_and_display(cfg, action, &overlay);
-    manage_overlay_free(&overlay);
-    return err;
-}
+    ESP_LOGI(TAG, "Showing manage view, waiting up to 30s");
+    wait_for_button_press(MANAGE_MENU_TIMEOUT_MS);
 
-/* Runs the manage-button menu: level 1 (the base overlay) shows first;
- * from there, each further press within 30s escalates one level (up to
- * MANAGE_MENU_MAX_LEVEL, which adds named-face labels), and a press once
- * already at the max level exits immediately instead of escalating
- * further. A 30s timeout at any level also exits. Device stays awake
- * throughout (doesn't sleep the panel or the chip). Returns non-ESP_OK
- * only if the very first (level 1) render/fetch failed; failures after
- * that (escalating, or the final revert) are logged but don't count as
- * an overall failure -- something was already shown successfully, which
- * was the point of the button. */
-static esp_err_t run_management_menu(const frame_config_t *cfg, fetch_action_t action, int battery_percent)
-{
-    int level = 1;
-    esp_err_t err = show_menu_level(cfg, action, level, battery_percent);
-    if (err != ESP_OK) {
-        ESP_LOGW(TAG, "Could not render management overlay (%s), showing photo normally", esp_err_to_name(err));
-        return fetch_and_display(cfg, action, NULL);
-    }
-
-    for (;;) {
-        ESP_LOGI(TAG, "Showing management menu level %d, waiting up to 30s", level);
-        bool pressed = wait_for_button_press(MANAGE_MENU_LEVEL_TIMEOUT_MS);
-        if (!pressed || level >= MANAGE_MENU_MAX_LEVEL) {
-            break; /* timeout at any level, or a press while already maxed out -- exit */
-        }
-        level++;
-        esp_err_t level_err = show_menu_level(cfg, FETCH_NORMAL, level, battery_percent);
-        if (level_err != ESP_OK) {
-            ESP_LOGW(TAG, "Could not render menu level %d (%s), reverting", level, esp_err_to_name(level_err));
-            break;
-        }
-    }
-
-    esp_err_t revert_err = fetch_and_display(cfg, FETCH_NORMAL, NULL);
+    esp_err_t revert_err = fetch_and_display(cfg, FETCH_NORMAL, false);
     if (revert_err != ESP_OK) {
-        ESP_LOGW(TAG, "Failed to revert management overlay (%s)", esp_err_to_name(revert_err));
+        ESP_LOGW(TAG, "Failed to revert manage view (%s)", esp_err_to_name(revert_err));
     }
     return ESP_OK;
 }
 
 /* Runs the appropriate fetch for this cycle: a plain fetch, or -- if
- * show_management_qr -- the escalating manage menu (see
- * run_management_menu()). */
-static esp_err_t run_fetch_cycle(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr,
-                                  int battery_percent)
+ * show_management_qr -- the manage view (see run_management_menu()). */
+static esp_err_t run_fetch_cycle(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr)
 {
     if (!show_management_qr) {
-        return fetch_and_display(cfg, action, NULL);
+        return fetch_and_display(cfg, action, false);
     }
-    return run_management_menu(cfg, action, battery_percent);
+    return run_management_menu(cfg, action);
 }
 
 /* Reports the battery percent to the server (POST /frame/battery).
@@ -873,8 +653,7 @@ static void report_battery(const frame_config_t *cfg, int percent)
     esp_http_client_cleanup(client);
 }
 
-void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr,
-                       int battery_percent)
+void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr)
 {
     esp_err_t epd_err = epd_init();
     bool have_display = (epd_err == ESP_OK);
@@ -908,7 +687,7 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
      * worth it to stop false-failing on the common case. */
     bool image_ok = true;
     if (have_display) {
-        esp_err_t fetch_err = run_fetch_cycle(cfg, action, show_management_qr, battery_percent);
+        esp_err_t fetch_err = run_fetch_cycle(cfg, action, show_management_qr);
         image_ok = (fetch_err == ESP_OK);
         if (!image_ok) {
             /* epd_display_stream() never triggers a physical refresh on a
@@ -943,9 +722,41 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
          * normal boot, not just the one right after an update). */
         esp_ota_mark_app_valid_cancel_rollback();
 
+        /* Read now, not at boot: the photo (and, if shown, the manage
+         * overlay -- entirely server-composited now, using the server's
+         * own last-known battery value, not a local reading, see
+         * server/app/manage_overlay.py) is already on the panel, so
+         * there's no display deadline to beat.
+         * Reading here instead of right after waking sidesteps taking the
+         * ADC sample while the rail's still settling from whatever the
+         * boot/reset just did, with no need to guess a settle delay --
+         * the fetch/display work already done this cycle is the delay.
+         * Still safe re: the battery/button pin sharing (battery.h) --
+         * every button check main.c does happens well before this, at
+         * the very start of boot. */
+        int battery_percent = battery_read_percent();
         report_battery(cfg, battery_percent);
         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;
+        if (server_cfg.reachable) {
+            /* For next boot's button-hold decision, not this one -- see
+             * frame_config_get_hold_duration_ms()'s own doc comment. */
+            frame_config_set_hold_duration_ms(server_cfg.hold_duration_ms);
+        }
+
+        /* 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

firmware/main/frame_client.h

@@ -9,14 +9,19 @@
  * Which photo-fetch behavior this wake cycle should use -- normally the
  * idempotent GET /frame/image (the server decides on its own whether to
  * advance, based on its configured refresh interval, so a plain
- * wake/reboot never skips a photo just by asking), or POST
- * /frame/advance / POST /frame/back to force a move in either direction
- * (the next-photo / back-photo buttons).
+ * wake/reboot never skips a photo just by asking), POST /frame/advance /
+ * POST /frame/back to force a move in either direction (a short press of
+ * the next-photo / back-photo buttons), or POST /frame/global-next /
+ * POST /frame/global-back to run whatever frame-wide action (if any) is
+ * configured for a held press (see next_button.h/back_button.h's
+ * *_HOLD result and app/global_actions.py server-side).
  */
 typedef enum {
     FETCH_NORMAL,
     FETCH_ADVANCE,
     FETCH_BACK,
+    FETCH_GLOBAL_NEXT,
+    FETCH_GLOBAL_BACK,
 } fetch_action_t;
 
 /**
@@ -33,14 +38,17 @@ esp_err_t frame_wifi_connect_sta(const frame_config_t *cfg);
  * deep-sleep until the next refresh.
  *
  * If show_management_qr is true (the manage button was held), the
- * displayed photo gets a small "scan to manage" QR overlay in the
- * top-right corner linking to the server's config page, held for 30
- * seconds (the device stays awake), then reverted back to the plain
- * photo before proceeding to the normal sleep-interval logic.
+ * request for that cycle carries &manage=1, and the server bakes its
+ * whole manage overlay (scan-to-manage QR, battery, location/date,
+ * share-QR, named face labels) directly into the image it returns --
+ * see server/app/manage_overlay.py; this device is otherwise unaware
+ * any of that exists, it just displays whatever comes back. Held for 30
+ * seconds (the device stays awake), then reverted back to a plain fetch
+ * before proceeding to the normal sleep-interval logic.
  *
- * battery_percent (0-100, or -1 for "no reading" -- see
- * battery_read_percent()) is shown on the management menu overlay and
- * reported to the server after a successful fetch; -1 skips both.
+ * Reads the battery (see battery_read_percent()) itself, once, after the
+ * photo is already on the panel, and reports it to the server on a
+ * successful fetch; a -1 reading ("no reading" -- on mains, disabled, or
+ * implausible) skips the report.
  */
-void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr,
-                       int battery_percent);
+void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool show_management_qr);

firmware/main/main.c

@@ -10,7 +10,6 @@
 #include "next_button.h"
 #include "back_button.h"
 #include "combo_button.h"
-#include "battery.h"
 
 static const char *TAG = "main";
 
@@ -41,29 +40,32 @@ void app_main(void)
     back_button_init();
     combo_button_init();
 
-    bool next_pressed = next_button_check();
-    bool back_pressed = back_button_check();
+    next_button_result_t next_result = next_button_check();
+    back_button_result_t back_result = back_button_check();
     /* Next takes priority over back if somehow both read pressed at once
      * (e.g. both held through a power-on) -- an arbitrary but
-     * deterministic tie-break, not expected to matter in practice. */
-    fetch_action_t action = next_pressed ? FETCH_ADVANCE : back_pressed ? FETCH_BACK : FETCH_NORMAL;
+     * deterministic tie-break, not expected to matter in practice. Same
+     * priority applies whether the winning button resolved to a short
+     * press or a hold. */
+    fetch_action_t action;
+    if (next_result != NEXT_BUTTON_NOT_PRESSED) {
+        action = (next_result == NEXT_BUTTON_HOLD) ? FETCH_GLOBAL_NEXT : FETCH_ADVANCE;
+    } else if (back_result != BACK_BUTTON_NOT_PRESSED) {
+        action = (back_result == BACK_BUTTON_HOLD) ? FETCH_GLOBAL_BACK : FETCH_BACK;
+    } else {
+        action = FETCH_NORMAL;
+    }
     /* Soft-resets or clears config + restarts internally for a medium/
      * long hold and never returns in those cases -- only returns here
      * for "not pressed" (false) or "quick press" (true, show the menu). */
     bool show_management_qr = combo_button_check();
 
-    /* Must come after the button checks: the battery pin is (by design,
-     * on the XIAO board) shared with a button, and the ADC read briefly
-     * takes the pin over -- see battery.h. -1 = no reading (disabled,
-     * on mains, or implausible). */
-    int battery_percent = battery_read_percent();
-
     frame_config_t cfg;
     esp_err_t cfg_err = frame_config_load(&cfg);
     if (cfg_err == ESP_OK) {
         ESP_LOGI(TAG, "Found stored config for '%s', connecting to home WiFi", cfg.sta_ssid);
         if (frame_wifi_connect_sta(&cfg) == ESP_OK) {
-            frame_client_run(&cfg, action, show_management_qr, battery_percent);
+            frame_client_run(&cfg, action, show_management_qr);
             return; /* frame_client_run currently never returns */
         }
         ESP_LOGW(TAG, "Could not connect to stored WiFi after %d attempts, falling back to provisioning",

firmware/main/manage_qr_overlay.c

@@ -1,356 +0,0 @@
-#include <stdlib.h>
-#include <string.h>
-
-#include "esp_check.h"
-
-#include "epd7in3e.h"
-#include "epd_draw.h"
-#include "fonts.h"
-#include "qrcodegen.h"
-
-#include "manage_qr_overlay.h"
-
-static const char *TAG = "manage_qr_overlay";
-
-#define QR_MAX_VERSION 10
-#define QR_BUFFER_LEN qrcodegen_BUFFER_LEN_FOR_VERSION(QR_MAX_VERSION)
-/* Smaller than qr_onboarding.c's QR_MODULE_PX (8) -- these are compact
- * corner popups, not a full-screen setup step. */
-#define QR_MODULE_PX 4
-#define PADDING 16
-#define QR_TEXT_GAP 8
-#define LINE_GAP 4
-/* Distance from the panel's edges to each overlay box. Combined with
- * EPD_WIDTH/EPD_HEIGHT and each region's forced-even width below, this
- * guarantees x0 is always even -- required so a region's columns land on
- * frame byte boundaries (2px/byte) when spliced into the fetch stream. */
-#define PANEL_MARGIN 20
-
-typedef enum {
-    CORNER_TOP_LEFT,
-    CORNER_TOP_RIGHT,
-    CORNER_BOTTOM_LEFT,
-    CORNER_BOTTOM_RIGHT,
-} overlay_corner_t;
-
-static void position_region(manage_overlay_region_t *region, overlay_corner_t corner)
-{
-    switch (corner) {
-    case CORNER_TOP_LEFT:
-        region->x0 = PANEL_MARGIN;
-        region->y0 = PANEL_MARGIN;
-        break;
-    case CORNER_TOP_RIGHT:
-        region->x0 = EPD_WIDTH - PANEL_MARGIN - region->w;
-        region->y0 = PANEL_MARGIN;
-        break;
-    case CORNER_BOTTOM_LEFT:
-        region->x0 = PANEL_MARGIN;
-        region->y0 = EPD_HEIGHT - PANEL_MARGIN - region->h;
-        break;
-    case CORNER_BOTTOM_RIGHT:
-        region->x0 = EPD_WIDTH - PANEL_MARGIN - region->w;
-        region->y0 = EPD_HEIGHT - PANEL_MARGIN - region->h;
-        break;
-    }
-}
-
-static void draw_qr(uint8_t *buf, int stride, int width, int height, const uint8_t *qrcode, int origin_x,
-                     int origin_y)
-{
-    int size = qrcodegen_getSize(qrcode);
-    for (int y = 0; y < size; y++) {
-        for (int x = 0; x < size; x++) {
-            epd_color_t color = qrcodegen_getModule(qrcode, x, y) ? EPD_COLOR_BLACK : EPD_COLOR_WHITE;
-            for (int dy = 0; dy < QR_MODULE_PX; dy++) {
-                for (int dx = 0; dx < QR_MODULE_PX; dx++) {
-                    epd_draw_pixel_ex(buf, stride, width, height, origin_x + x * QR_MODULE_PX + dx,
-                                       origin_y + y * QR_MODULE_PX + dy, color);
-                }
-            }
-        }
-    }
-}
-
-/* White-padded box with a QR code encoding payload, plus zero, one, or
- * two centered caption lines beneath it (either may be NULL). Used for
- * both the top-right "scan to manage" box (two lines) and the
- * bottom-left share-link box (no lines). */
-static esp_err_t render_qr_region(const char *payload, const char *line1, const char *line2, overlay_corner_t corner,
-                                   manage_overlay_region_t *out)
-{
-    uint8_t temp_buffer[QR_BUFFER_LEN];
-    uint8_t qrcode[QR_BUFFER_LEN];
-    bool ok = qrcodegen_encodeText(payload, temp_buffer, qrcode, qrcodegen_Ecc_MEDIUM, qrcodegen_VERSION_MIN,
-                                    QR_MAX_VERSION, qrcodegen_Mask_AUTO, true);
-    ESP_RETURN_ON_FALSE(ok, ESP_FAIL, TAG, "QR encoding failed for '%s' (too long for max version)", payload);
-
-    int qr_size = qrcodegen_getSize(qrcode);
-    int qr_px = qr_size * QR_MODULE_PX;
-
-    /* Font24 (32x41px uppercase glyphs) is the only font vendored into
-     * this project -- see components/epaper_fonts. "SCAN TO MANAGE" on
-     * one line would be 448px wide, too wide for a compact corner box,
-     * so it's passed in pre-wrapped across two lines instead. */
-    int text_w = 0;
-    int text_h = 0;
-    if (line1 != NULL) {
-        int w1 = (int)strlen(line1) * Font24.Width;
-        int w2 = line2 != NULL ? (int)strlen(line2) * Font24.Width : 0;
-        text_w = w1 > w2 ? w1 : w2;
-        text_h = QR_TEXT_GAP + Font24.Height + (line2 != NULL ? LINE_GAP + Font24.Height : 0);
-    }
-
-    int content_w = qr_px > text_w ? qr_px : text_w;
-    int content_h = qr_px + text_h;
-
-    int w = content_w + PADDING * 2;
-    int h = content_h + PADDING * 2;
-    w += w % 2; /* keep byte-aligned (2px/byte) */
-
-    int stride = w / 2;
-    uint8_t *buf = malloc((size_t)stride * h);
-    ESP_RETURN_ON_FALSE(buf != NULL, ESP_ERR_NO_MEM, TAG, "Failed to allocate overlay region");
-    memset(buf, (EPD_COLOR_WHITE << 4) | EPD_COLOR_WHITE, (size_t)stride * h);
-
-    int center_x = w / 2;
-    int y = PADDING;
-    draw_qr(buf, stride, w, h, qrcode, center_x - qr_px / 2, y);
-    y += qr_px;
-    if (line1 != NULL) {
-        y += QR_TEXT_GAP;
-        epd_draw_text_centered_ex(buf, stride, w, h, &Font24, line1, center_x, y);
-        y += Font24.Height;
-    }
-    if (line2 != NULL) {
-        y += LINE_GAP;
-        epd_draw_text_centered_ex(buf, stride, w, h, &Font24, line2, center_x, y);
-    }
-
-    out->buf = buf;
-    out->w = w;
-    out->h = h;
-    position_region(out, corner);
-    return ESP_OK;
-}
-
-/* White-padded box with one or two centered lines of text (line2 may be
- * NULL) -- used for the top-left location (city + state/country, two
- * lines rather than cramming both onto one to keep the box from
- * threatening to overlap the top-right QR box) and the bottom-right
- * date-taken label (one line). */
-static esp_err_t render_text_region(const char *line1, const char *line2, overlay_corner_t corner,
-                                     manage_overlay_region_t *out)
-{
-    int w1 = (int)strlen(line1) * Font24.Width;
-    int w2 = line2 != NULL ? (int)strlen(line2) * Font24.Width : 0;
-    int text_w = w1 > w2 ? w1 : w2;
-    int text_h = Font24.Height + (line2 != NULL ? LINE_GAP + Font24.Height : 0);
-
-    int w = text_w + PADDING * 2;
-    int h = text_h + PADDING * 2;
-    w += w % 2;
-
-    int stride = w / 2;
-    uint8_t *buf = malloc((size_t)stride * h);
-    ESP_RETURN_ON_FALSE(buf != NULL, ESP_ERR_NO_MEM, TAG, "Failed to allocate overlay region");
-    memset(buf, (EPD_COLOR_WHITE << 4) | EPD_COLOR_WHITE, (size_t)stride * h);
-
-    int center_x = w / 2;
-    int y = PADDING;
-    epd_draw_text_centered_ex(buf, stride, w, h, &Font24, line1, center_x, y);
-    if (line2 != NULL) {
-        y += Font24.Height + LINE_GAP;
-        epd_draw_text_centered_ex(buf, stride, w, h, &Font24, line2, center_x, y);
-    }
-
-    out->buf = buf;
-    out->w = w;
-    out->h = h;
-    position_region(out, corner);
-    return ESP_OK;
-}
-
-/* Deliberately tighter than PADDING (used for the fixed QR/text corner
- * boxes) -- these labels sit right next to a face rather than needing
- * generous QR-scanning margin, and there can be several of them
- * simultaneously (see MANAGE_FACE_LABELS_MAX's memory-budget note in
- * the header). */
-#define FACE_LABEL_PADDING 8
-#define FACE_LABEL_GAP 4 /* distance from the face's anchor point to the label box */
-
-/* White-padded single-line name label positioned near an arbitrary
- * (anchor_x, anchor_y) face position, rather than a fixed corner --
- * unlike the four corner regions (always in-bounds by construction),
- * this needs real clamping since a face can be anywhere, including near
- * an edge. Centered horizontally on the face, placed just below it by
- * default, flipped above if there's no room below. */
-static esp_err_t render_face_label_region(const char *name, int anchor_x, int anchor_y, manage_overlay_region_t *out)
-{
-    int text_w = (int)strlen(name) * Font24.Width;
-    int w = text_w + FACE_LABEL_PADDING * 2;
-    int h = Font24.Height + FACE_LABEL_PADDING * 2;
-    w += w % 2;
-
-    int stride = w / 2;
-    uint8_t *buf = malloc((size_t)stride * h);
-    ESP_RETURN_ON_FALSE(buf != NULL, ESP_ERR_NO_MEM, TAG, "Failed to allocate overlay region");
-    memset(buf, (EPD_COLOR_WHITE << 4) | EPD_COLOR_WHITE, (size_t)stride * h);
-    epd_draw_text_centered_ex(buf, stride, w, h, &Font24, name, w / 2, FACE_LABEL_PADDING);
-
-    int x0 = anchor_x - w / 2;
-    int y0 = anchor_y + FACE_LABEL_GAP;
-    if (y0 + h > EPD_HEIGHT) {
-        y0 = anchor_y - FACE_LABEL_GAP - h; /* no room below -- place above the face instead */
-    }
-    if (x0 < 0) {
-        x0 = 0;
-    } else if (x0 + w > EPD_WIDTH) {
-        x0 = EPD_WIDTH - w;
-    }
-    if (y0 < 0) {
-        y0 = 0;
-    } else if (y0 + h > EPD_HEIGHT) {
-        y0 = EPD_HEIGHT - h;
-    }
-    x0 -= x0 % 2; /* keep byte-aligned (2px/byte) */
-
-    out->buf = buf;
-    out->w = w;
-    out->h = h;
-    out->x0 = x0;
-    out->y0 = y0;
-    return ESP_OK;
-}
-
-/* Battery glyph dimensions -- a static outline (body rectangle + small
- * terminal nub on the right), deliberately NOT a fill-level graphic. */
-#define BATTERY_ICON_W 44
-#define BATTERY_ICON_H 24
-#define BATTERY_ICON_STROKE 2
-#define BATTERY_NUB_W 6
-#define BATTERY_NUB_H 12
-#define BATTERY_ICON_TEXT_GAP 8
-#define BATTERY_REGION_GAP 8 /* vertical gap below the manage QR box */
-
-static void draw_battery_icon(uint8_t *buf, int stride, int width, int height, int x0, int y0)
-{
-    for (int y = 0; y < BATTERY_ICON_H; y++) {
-        for (int x = 0; x < BATTERY_ICON_W; x++) {
-            bool edge = x < BATTERY_ICON_STROKE || x >= BATTERY_ICON_W - BATTERY_ICON_STROKE ||
-                        y < BATTERY_ICON_STROKE || y >= BATTERY_ICON_H - BATTERY_ICON_STROKE;
-            if (edge) {
-                epd_draw_pixel_ex(buf, stride, width, height, x0 + x, y0 + y, EPD_COLOR_BLACK);
-            }
-        }
-    }
-    int nub_y = y0 + (BATTERY_ICON_H - BATTERY_NUB_H) / 2;
-    for (int y = 0; y < BATTERY_NUB_H; y++) {
-        for (int x = 0; x < BATTERY_NUB_W; x++) {
-            epd_draw_pixel_ex(buf, stride, width, height, x0 + BATTERY_ICON_W + x, nub_y + y, EPD_COLOR_BLACK);
-        }
-    }
-}
-
-/* White-padded box with the battery glyph and "NN%" beside it, placed
- * directly below an already-positioned anchor region (the top-right
- * manage QR box), right-aligned to the anchor's right edge. */
-static esp_err_t render_battery_region(int percent, const manage_overlay_region_t *anchor,
-                                        manage_overlay_region_t *out)
-{
-    char text[8];
-    snprintf(text, sizeof(text), "%d%%", percent);
-
-    int icon_total_w = BATTERY_ICON_W + BATTERY_NUB_W;
-    int text_w = (int)strlen(text) * Font24.Width;
-    int content_w = icon_total_w + BATTERY_ICON_TEXT_GAP + text_w;
-    int content_h = Font24.Height > BATTERY_ICON_H ? Font24.Height : BATTERY_ICON_H;
-
-    int w = content_w + PADDING * 2;
-    int h = content_h + PADDING * 2;
-    w += w % 2;
-
-    int stride = w / 2;
-    uint8_t *buf = malloc((size_t)stride * h);
-    ESP_RETURN_ON_FALSE(buf != NULL, ESP_ERR_NO_MEM, TAG, "Failed to allocate overlay region");
-    memset(buf, (EPD_COLOR_WHITE << 4) | EPD_COLOR_WHITE, (size_t)stride * h);
-
-    draw_battery_icon(buf, stride, w, h, PADDING, PADDING + (content_h - BATTERY_ICON_H) / 2);
-    epd_draw_text_ex(buf, stride, w, h, &Font24, text, PADDING + icon_total_w + BATTERY_ICON_TEXT_GAP,
-                      PADDING + (content_h - Font24.Height) / 2);
-
-    out->buf = buf;
-    out->w = w;
-    out->h = h;
-    out->x0 = anchor->x0 + anchor->w - w;
-    out->x0 -= out->x0 % 2; /* keep byte-aligned (2px/byte) */
-    out->y0 = anchor->y0 + anchor->h + BATTERY_REGION_GAP;
-    return ESP_OK;
-}
-
-esp_err_t manage_overlay_render(const manage_overlay_content_t *content, manage_overlay_set_t *out)
-{
-    out->count = 0;
-
-    esp_err_t err = render_qr_region(content->management_url, "SCAN TO", "MANAGE", CORNER_TOP_RIGHT,
-                                      &out->regions[out->count]);
-    if (err != ESP_OK) {
-        return err;
-    }
-    out->count++;
-
-    if (content->battery_percent >= 0 && content->battery_percent <= 100) {
-        /* Anchored below the manage QR box just rendered (regions[0]). */
-        if (render_battery_region(content->battery_percent, &out->regions[0], &out->regions[out->count]) ==
-            ESP_OK) {
-            out->count++;
-        }
-    }
-
-    if (content->location_line1 != NULL && content->location_line1[0] != '\0') {
-        const char *line2 =
-            (content->location_line2 != NULL && content->location_line2[0] != '\0') ? content->location_line2 : NULL;
-        if (render_text_region(content->location_line1, line2, CORNER_TOP_LEFT, &out->regions[out->count]) ==
-            ESP_OK) {
-            out->count++;
-        }
-    }
-
-    if (content->taken_at != NULL && content->taken_at[0] != '\0') {
-        if (render_text_region(content->taken_at, NULL, CORNER_BOTTOM_RIGHT, &out->regions[out->count]) == ESP_OK) {
-            out->count++;
-        }
-    }
-
-    if (content->share_url != NULL && content->share_url[0] != '\0') {
-        if (render_qr_region(content->share_url, "SCAN TO", "DOWNLOAD", CORNER_BOTTOM_LEFT,
-                              &out->regions[out->count]) == ESP_OK) {
-            out->count++;
-        }
-    }
-
-    int face_count = content->face_label_count;
-    if (face_count > MANAGE_FACE_LABELS_MAX) {
-        face_count = MANAGE_FACE_LABELS_MAX;
-    }
-    for (int i = 0; content->face_labels != NULL && i < face_count; i++) {
-        const manage_face_label_t *label = &content->face_labels[i];
-        if (label->name[0] == '\0') {
-            continue;
-        }
-        if (render_face_label_region(label->name, label->x, label->y, &out->regions[out->count]) == ESP_OK) {
-            out->count++;
-        }
-    }
-
-    return ESP_OK;
-}
-
-void manage_overlay_free(manage_overlay_set_t *overlay)
-{
-    for (int i = 0; i < overlay->count; i++) {
-        free(overlay->regions[i].buf);
-        overlay->regions[i].buf = NULL;
-    }
-    overlay->count = 0;
-}

firmware/main/manage_qr_overlay.h

@@ -1,61 +0,0 @@
-#pragma once
-
-#include <stdint.h>
-
-#include "esp_err.h"
-
-/* 5 fixed regions (manage QR, battery indicator, location, date, share
- * QR) plus up to MANAGE_FACE_LABELS_MAX arbitrary-position named-face
- * labels (see manage_face_label_t below). MANAGE_FACE_LABELS_MAX is
- * capped small deliberately, not arbitrarily -- each label is its own
- * malloc'd buffer, and the fixed regions alone already use a meaningful
- * chunk of the ESP32-C6's limited RAM; this keeps worst-case overlay
- * memory well clear of what the WiFi/HTTP stack needs alongside it. */
-#define MANAGE_FACE_LABELS_MAX 4
-#define MANAGE_OVERLAY_MAX_REGIONS (5 + MANAGE_FACE_LABELS_MAX)
-
-typedef struct {
-    uint8_t *buf; /* malloc'd (w/2)*h bytes, packed 2px/byte; owned by the region */
-    int x0, y0;   /* top-left corner, panel pixel coordinates (x0 is always even) */
-    int w, h;     /* pixel dimensions (w is always even) */
-} manage_overlay_region_t;
-
-typedef struct {
-    manage_overlay_region_t regions[MANAGE_OVERLAY_MAX_REGIONS];
-    int count;
-} manage_overlay_set_t;
-
-typedef struct {
-    char name[16];
-    int x, y; /* anchor point (bottom-center of the face), panel pixel coordinates */
-} manage_face_label_t;
-
-typedef struct {
-    const char *management_url;  /* top-right QR + "SCAN TO"/"MANAGE" caption -- always shown */
-    const char *location_line1;  /* top-left text, line 1 (city); NULL/empty skips this region */
-    const char *location_line2;  /* top-left text, line 2 (state/country); NULL/empty is fine if line1 is set */
-    const char *taken_at;        /* bottom-right text; NULL/empty skips this region */
-    const char *share_url;       /* bottom-left QR + "SCAN TO"/"DOWNLOAD" caption; NULL/empty skips this region */
-    const manage_face_label_t *face_labels; /* named-face labels ("level 2" menu); NULL/empty count skips these */
-    int face_label_count;                   /* clamped to MANAGE_FACE_LABELS_MAX internally */
-    int battery_percent;                    /* 0-100 shows an icon + percent below the manage QR; -1 skips it */
-} manage_overlay_content_t;
-
-/**
- * Renders the manage-button overlay: always a "scan to manage" QR in the
- * top-right corner, plus whichever of location_line1/taken_at/share_url
- * are non-NULL/non-empty in their own corners (top-left, bottom-right,
- * bottom-left respectively), plus one region per entry in face_labels
- * (positioned near that face rather than a fixed corner -- see
- * render_face_label_region() in the .c file for the clamping logic).
- * Each region is its own separately malloc'd small buffer (not a full
- * EPD_FRAME_BYTES frame). A failure rendering the top-right region fails
- * the whole call; a failure rendering any other region just skips that
- * region and keeps going. Caller must call manage_overlay_free() on out
- * regardless of the return value (out->count reflects however many
- * regions were actually populated).
- */
-esp_err_t manage_overlay_render(const manage_overlay_content_t *content, manage_overlay_set_t *out);
-
-/** Frees every populated region's buffer in overlay. */
-void manage_overlay_free(manage_overlay_set_t *overlay);

firmware/main/next_button.c

@@ -1,3 +1,5 @@
+#include <stdint.h>
+
 #include "driver/gpio.h"
 #include "esp_log.h"
 #include "esp_sleep.h"
@@ -5,6 +7,8 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 
+#include "wifi_provisioning.h"
+
 #include "next_button.h"
 
 static const char *TAG = "next_button";
@@ -14,6 +18,7 @@ static const char *TAG = "next_button";
 #define NEXT_BUTTON_GPIO ((gpio_num_t)CONFIG_FRAME_NEXT_BUTTON_GPIO)
 #define NEXT_BUTTON_DEBOUNCE_MS 20
 #define NEXT_BUTTON_DEBOUNCE_CHECKS 3
+#define NEXT_BUTTON_POLL_MS 100
 
 void next_button_init(void)
 {
@@ -40,7 +45,7 @@ void next_button_init(void)
     esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(1ULL << NEXT_BUTTON_GPIO, ESP_GPIO_WAKEUP_GPIO_LOW);
 }
 
-bool next_button_check(void)
+next_button_result_t next_button_check(void)
 {
     /* A quick tap can easily release before this runs (~0.4-0.5s into
      * boot, confirmed on hardware -- a live gpio_get_level() check here
@@ -48,32 +53,54 @@ bool next_button_check(void)
      * status register is latched at the moment of waking and isn't
      * cleared until the next sleep entry, so it reliably reflects a tap
      * regardless of how quickly it was released. */
-    if (esp_sleep_get_gpio_wakeup_status() & (1ULL << NEXT_BUTTON_GPIO)) {
-        ESP_LOGI(TAG, "Next-photo button caused this wake, forcing advance");
-        return true;
-    }
+    bool caused_wake = esp_sleep_get_gpio_wakeup_status() & (1ULL << NEXT_BUTTON_GPIO);
 
-    /* Not a GPIO-wakeup-from-this-pin boot (normal timer wake, or a fresh
-     * power-on/reflash) -- fall back to a live, debounced level check so
-     * holding the button down while powering on also works. */
-    if (gpio_get_level(NEXT_BUTTON_GPIO) != 0) {
-        return false;
-    }
-
-    for (int i = 0; i < NEXT_BUTTON_DEBOUNCE_CHECKS; i++) {
-        vTaskDelay(pdMS_TO_TICKS(NEXT_BUTTON_DEBOUNCE_MS));
+    if (!caused_wake) {
+        /* Not a GPIO-wakeup-from-this-pin boot (normal timer wake, or a
+         * fresh power-on/reflash) -- fall back to a live, debounced level
+         * check so holding the button down while powering on also
+         * works. */
         if (gpio_get_level(NEXT_BUTTON_GPIO) != 0) {
-            return false; /* noise, not a real press */
+            return NEXT_BUTTON_NOT_PRESSED;
+        }
+        for (int i = 0; i < NEXT_BUTTON_DEBOUNCE_CHECKS; i++) {
+            vTaskDelay(pdMS_TO_TICKS(NEXT_BUTTON_DEBOUNCE_MS));
+            if (gpio_get_level(NEXT_BUTTON_GPIO) != 0) {
+                return NEXT_BUTTON_NOT_PRESSED; /* noise, not a real press */
+            }
         }
     }
 
-    ESP_LOGI(TAG, "Next-photo button held during power-on, forcing advance");
-    return true;
+    /* Confirmed pressed (either the wake cause, or debounced during
+     * power-on) -- measure how long, same polling pattern as
+     * combo_button.c's own hold-tier detection. Reads the last hold
+     * duration the server reported (persisted from a previous cycle,
+     * see frame_config_get_hold_duration_ms's own doc comment), falling
+     * back to the Kconfig default before the device has ever fetched
+     * one. */
+    uint32_t hold_threshold_ms;
+    if (frame_config_get_hold_duration_ms(&hold_threshold_ms) != ESP_OK) {
+        hold_threshold_ms = CONFIG_FRAME_HOLD_ACTION_MS;
+    }
+
+    uint32_t elapsed_ms = 0;
+    while (gpio_get_level(NEXT_BUTTON_GPIO) == 0) {
+        if (elapsed_ms >= hold_threshold_ms) {
+            ESP_LOGI(TAG, "Next button held past %ums, triggering global hold action",
+                     (unsigned)hold_threshold_ms);
+            return NEXT_BUTTON_HOLD;
+        }
+        vTaskDelay(pdMS_TO_TICKS(NEXT_BUTTON_POLL_MS));
+        elapsed_ms += NEXT_BUTTON_POLL_MS;
+    }
+
+    ESP_LOGI(TAG, "Next-photo button short press (%ums), forcing advance", (unsigned)elapsed_ms);
+    return NEXT_BUTTON_SHORT_PRESS;
 }
 
 #else
 
 void next_button_init(void) {}
-bool next_button_check(void) { return false; }
+next_button_result_t next_button_check(void) { return NEXT_BUTTON_NOT_PRESSED; }
 
 #endif

firmware/main/next_button.h

@@ -12,10 +12,27 @@
  */
 void next_button_init(void);
 
+typedef enum {
+    NEXT_BUTTON_NOT_PRESSED,
+    /** A short press -- advancing a photo is low-stakes and should feel
+     * immediate, so this fires the moment the button releases (or right
+     * away for a wake-triggered press, once it's confirmed not a hold). */
+    NEXT_BUTTON_SHORT_PRESS,
+    /** Held past the configured hold duration (see
+     * wifi_provisioning.h's frame_config_get_hold_duration_ms) --
+     * triggers a frame-wide action instead (see
+     * server/app/global_actions.py, frame_client.h's FETCH_GLOBAL_NEXT).
+     * Fires immediately at the threshold, without waiting for release --
+     * same convention as combo_button.c's factory-reset tier. */
+    NEXT_BUTTON_HOLD,
+} next_button_result_t;
+
 /**
- * Returns whether the next-photo button is currently held, debounced with
- * a couple of short re-checks to reject noise. No long hold-to-confirm
- * gate -- advancing a photo is low-stakes and should feel immediate, so
- * this returns right away either way.
+ * Checks the next-photo button and, if it's pressed at all (either what
+ * caused this wake, per the latched wakeup-status register, or held
+ * through a debounced power-on check), blocks polling its level until
+ * either it's released (NEXT_BUTTON_SHORT_PRESS) or the hold duration
+ * elapses (NEXT_BUTTON_HOLD, returned immediately, not waiting for
+ * release). Evaluated once per wake.
  */
-bool next_button_check(void);
+next_button_result_t next_button_check(void);

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);
@@ -200,6 +234,29 @@ void frame_config_invalidate_last_display_crc32(void)
     nvs_close(handle);
 }
 
+esp_err_t frame_config_get_hold_duration_ms(uint32_t *out)
+{
+    nvs_handle_t handle;
+    esp_err_t err = nvs_open(NVS_NAMESPACE, NVS_READONLY, &handle);
+    if (err != ESP_OK) {
+        return err;
+    }
+    err = nvs_get_u32(handle, "hold_ms", out);
+    nvs_close(handle);
+    return err;
+}
+
+void frame_config_set_hold_duration_ms(uint32_t ms)
+{
+    nvs_handle_t handle;
+    if (nvs_open(NVS_NAMESPACE, NVS_READWRITE, &handle) != ESP_OK) {
+        return;
+    }
+    nvs_set_u32(handle, "hold_ms", ms);
+    nvs_commit(handle);
+    nvs_close(handle);
+}
+
 /* ------------------------------------------------------------------------
  * WiFi fast-connect cache
  * ---------------------------------------------------------------------- */
@@ -412,15 +469,63 @@ 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. This page is entirely self-contained (no external
+     * resources) so it renders fully from what we send now, before the
+     * softAP goes away -- a phone mid-load of a remote asset would just
+     * time out once the AP drops. The visible countdown ticks down for
+     * PROVISIONING_COUNTDOWN_S seconds and then redirects; the AP is kept
+     * alive for one second longer than that (see the vTaskDelay below) so
+     * the countdown always finishes, and the phone has that whole window
+     * to rejoin its normal WiFi and let the redirect land on the real
+     * server. "Redirect now" covers a phone that's already reconnected.
+     * 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);
+
+#define PROVISIONING_COUNTDOWN_S 10
+
+    char resp[1536];
+    snprintf(resp, sizeof(resp),
+             "<!doctype html><html><head>"
+             "<meta http-equiv=\"refresh\" content=\"%d;url=%s\">"
+             "<style>body{font-family:sans-serif;text-align:center;padding:2em}"
+             "#now{display:inline-block;margin-top:1em;padding:.6em 1.2em;"
+             "background:#2563eb;color:#fff;text-decoration:none;border-radius:8px}</style></head>"
+             "<body><h3>Saved &mdash; the frame is restarting</h3>"
+             "<p>Reconnect to your normal WiFi if it doesn't happen automatically.</p>"
+             "<p>Redirecting you in <span id=\"n\">%d</span> seconds&hellip;</p>"
+             "<p><a id=\"now\" href=\"%s\">Redirect now</a></p>"
+             "<script>"
+             "var n=%d,e=document.getElementById('n');"
+             "var t=setInterval(function(){"
+             "n--;if(e)e.textContent=n;"
+             "if(n<=0){clearInterval(t);location.href='%s';}"
+             "},1000);"
+             "</script>"
+             "</body></html>",
+             PROVISIONING_COUNTDOWN_S, claim_url, PROVISIONING_COUNTDOWN_S, claim_url,
+             PROVISIONING_COUNTDOWN_S, claim_url);
     httpd_resp_set_type(req, "text/html");
     httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
 
-    /* Let the response flush to the client before rebooting into STA mode. */
-    vTaskDelay(pdMS_TO_TICKS(1000));
+    /* Keep the softAP up for the full visible countdown (plus a 1s margin
+     * for the response to flush and the JS timer to fire) before tearing
+     * it down -- see the comment above for why. */
+    vTaskDelay(pdMS_TO_TICKS((PROVISIONING_COUNTDOWN_S + 1) * 1000));
     esp_restart();
 
+#undef PROVISIONING_COUNTDOWN_S
+
     return ESP_OK;
 }
 

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.
@@ -70,6 +94,27 @@ void frame_config_set_last_display_crc32(uint32_t crc32);
  */
 void frame_config_invalidate_last_display_crc32(void);
 
+/**
+ * Returns the hold_duration_ms the server most recently reported via GET
+ * /frame/config (see frame_client.c's fetch_frame_config/frame_client_run)
+ * -- how long NEXT/BACK must be held before next_button_check()/
+ * back_button_check() treat it as a hold-for-global-action instead of a
+ * short press. Returns ESP_ERR_NVS_NOT_FOUND if the device has never
+ * fetched one yet (fresh install/factory reset); caller should fall back
+ * to CONFIG_FRAME_HOLD_ACTION_MS in that case.
+ *
+ * Deliberately a *previous* cycle's value: this cycle's own button
+ * decision happens in main.c before WiFi even connects, but
+ * /frame/config isn't fetched until near the end of frame_client_run
+ * (after the image fetch, for connection-warmth/timeout reasons -- see
+ * its own comment) -- so there's no same-cycle fresh value to use yet.
+ */
+esp_err_t frame_config_get_hold_duration_ms(uint32_t *out);
+
+/** Persists the hold duration reported by the server, for the *next*
+ * boot's button-hold decision to use. */
+void frame_config_set_hold_duration_ms(uint32_t ms);
+
 /**
  * Returns this device's provisioning AP identity: a fixed SSID (from
  * Kconfig) and a password that's generated once on first use and persisted

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.4.1

server/.dockerignore

@@ -0,0 +1,7 @@
+__pycache__/
+**/__pycache__/
+.venv/
+*.egg-info/
+data/
+render-service/node_modules/
+.git/

server/Dockerfile

@@ -2,18 +2,66 @@ FROM python:3.12-slim
 
 WORKDIR /app
 
-# tzdata: python:3.12-slim doesn't include it by default, so the zoneinfo
-# database backing the web UI's "Timezone" setting (used by "Quiet hours")
-# would have no named zones to resolve without this -- ZoneInfo() would
-# raise for anything other than "UTC".
-RUN apt-get update && apt-get install -y --no-install-recommends tzdata \
+# tzdata/fonts/Node.js all from Debian's own repo in one layer -- no
+# external curl/gnupg dance needed (see below for why that changed).
+# tzdata: python:3.12-slim doesn't include it by default, so the
+# zoneinfo database backing the web UI's "Timezone" setting (used by
+# "Quiet hours") would have no named zones to resolve without this --
+# ZoneInfo() would raise for anything other than "UTC".
+# fontconfig/fonts-dejavu-core: whiteboard mode's render-service/ (own
+# README there) needs something to render whiteboard text with.
+#
+# Node.js: whiteboard frame mode's render-service/ runs as a second
+# process in this same container rather than a separate compose service
+# -- it's a lightweight, stateless, localhost-only sidecar with nothing
+# worth independently scaling or restarting. Used to be installed via
+# NodeSource's setup script (Debian's own nodejs package was too old for
+# jsdom's minimum back when this base image tracked Debian bookworm) --
+# switched to Debian's own `nodejs`/`npm` packages after NodeSource's
+# deb.nodesource.com started intermittently 403ing on both its setup_*.x
+# scripts *and* its GPG key (a live NodeSource-side S3/CDN issue,
+# confirmed 2026-07-27 by hitting deb.nodesource.com directly -- some
+# setup_NN.x paths 403, others 200, no consistent pattern, so no
+# NodeSource-hosted install path could be trusted not to silently break
+# again). This base image now tracks Debian trixie, whose own `nodejs`
+# package is 20.19.2 -- inside jsdom 29's stated engines range
+# (`^20.19.0 || ^22.13.0 || >=24.0.0`) and well above express/resvg-js's
+# much lower floors -- so there's no longer a version gap to route
+# around NodeSource for. One less external dependency, and no more
+# curl-piped-into-bash (that pattern is also what let the NodeSource
+# failure go undetected here in the first place: `curl -f ... | bash -`
+# on a 403 hands bash an empty, "successful" script instead of failing
+# the RUN outright).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    tzdata fontconfig fonts-dejavu-core nodejs npm \
     && rm -rf /var/lib/apt/lists/*
 
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
+# render-service/'s dependencies installed as several separate layers
+# rather than one `npm install` covering all of them -- a from-scratch
+# push of this image once hit Cloudflare's payload-size limit on a
+# single blob/layer upload (the registry sits behind it), and splitting
+# a big layer into several smaller ones is the direct fix for exactly
+# that failure mode, independent of anything about the registry itself.
+# --no-save: package.json already fully declares these (with the exact
+# same version pins used here) as the single source of truth for what
+# this service depends on -- these calls are just about *when* each one
+# gets installed for layer-size reasons, not re-deciding what's needed.
+COPY render-service/package.json ./render-service/package.json
+WORKDIR /app/render-service
+RUN npm install --omit=dev --no-save express@^5.2.1 && npm cache clean --force
+RUN npm install --omit=dev --no-save jsdom@^29.1.1 && npm cache clean --force
+RUN npm install --omit=dev --no-save @excalidraw/[email protected] && npm cache clean --force
+RUN npm install --omit=dev --no-save @resvg/[email protected] && npm cache clean --force
+WORKDIR /app
+
+COPY render-service/server.js ./render-service/server.js
 COPY app ./app
+COPY start.sh .
+RUN chmod +x start.sh
 
 EXPOSE 8420
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8420"]
+CMD ["./start.sh"]

server/README.md

@@ -8,214 +8,191 @@ 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).
+- **Email (optional).** An admin sets an SMTP server once (`/admin` --
+  server, port, username/password, from address, STARTTLS on/off; a
+  "send test email to myself" button, delivered to the admin's own
+  email); each user sets their own email in Settings. Once both are in
+  place: **"Forgot password?"** on the login page emails a one-hour
+  reset link (a generic "check your email" response either way, so the
+  endpoint can't be used to enumerate accounts), and a frame's
+  Configuration tab can set a **battery-alert threshold** -- an email to
+  the frame's owner the first time a report drops to or below it, not
+  again until a recharge is detected and it crosses again. No SMTP
+  configured, or no email on the relevant account, and both features
+  silently no-op rather than erroring.
 
 ## 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/{manage_token}` -- creates a 30-minute public Immich
+  share link covering every photo widget's currently-showing photo on
+  *this* frame and 302s to it. Authenticated by the frame's own
+  `manage_token` (see the manage QR below), not device credentials -- a
+  phone scanning the QR has no way to supply `?id=`/`?token=`.
+- `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. Also where
+  the battery-alert threshold (below) is checked and, at most once per
+  discharge cycle, emailed to the owner.
+- `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`, `display_mode` (`crop_fill`/`crop_faces`/
+  `stretch_fill`/`letterbox`, see `image_pipeline.DISPLAY_MODES`),
+  `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`,
+  `battery_alert_threshold_pct` -- percent, or `-1`/blank to disable --,
+  `palette` -- exactly 6 `#rrggbb` values in black/white/yellow/red/
+  blue/green order --, `palette_reset` -- `true` clears back to the
+  default palette --, `color_boost`/`contrast_boost` -- PIL
+  `ImageEnhance` factors, 0-2, 1 = unchanged --, `dither_strength` --
+  0-1, blends toward a flat/undithered quantization before running
+  Floyd-Steinberg, so 0 = no dithering texture and 1 = full strength).
+- `GET  .../preview/original`, `GET .../preview/rendered` -- the
+  before/after comparison on the Configuration tab: the current
+  photo's Immich preview untouched (JPEG), and that same photo run
+  through this frame's actual saved rendering pipeline (PNG, upright
+  logical orientation, not packed device bytes) -- reflects saved
+  settings, not unsaved slider positions.
+- `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,19 +201,79 @@ 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.
-- 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
-  rendered test image against the real panel.
+- Auth in one breath: browsers use sessions (+CSRF), devices use
+  per-frame tokens (`?id=` + `?token=`), the manage QR and the
+  scan-to-download QR both use the frame's own `manage_token` (device
+  tokens don't work for either -- neither is ever called by firmware,
+  both are opened by a phone that has no way to supply `?id=`/`?token=`),
+  and `MANAGEMENT_TOKEN` survives only as the migration credential for
+  pre-multi-frame firmware.
+- Calendar frame mode (`app/calendar_feed.py`) expands recurring events
+  (RRULE/EXDATE/DST) via [`recurring-ical-events`](https://pypi.org/project/recurring-ical-events/),
+  which is LGPL-3.0-or-later -- the only non-permissively-licensed
+  dependency here. It's used as an ordinary `pip install` runtime import,
+  never vendored or modified, so this project's own code stays under its
+  own license; LGPL's copyleft terms apply to that library itself, not
+  to code that merely links against it dynamically.
+- CalDAV account support (`app/caldav_client.py`, alongside the plain ICS
+  subscription) wraps the `caldav` PyPI package. `caldav` itself is
+  dual-licensed GPL-3.0-or-later/Apache-2.0, but it hard-depends on
+  `icalendar-searcher`, which is **AGPL-3.0-or-later** -- the strongest
+  copyleft in this project's dependency tree, and the one whose
+  network-use clause is written specifically for server applications
+  like this one (not just "don't vendor/modify it," which was enough
+  reasoning for the LGPL dependency above). Taking this on was an
+  explicit, informed call by the project owner, not a default -- anyone
+  redistributing this project (vs. just self-hosting it) should
+  re-evaluate that tradeoff for their own situation before doing so.
+- Whiteboard frame mode (`app/webdav_client.py`, `app/whiteboard.py`)
+  fetches a Nextcloud Whiteboard (or any WebDAV server's) `.whiteboard`
+  file -- which turns out to be Excalidraw scene JSON (elements/appState/
+  files), not an image -- and renders it via `render-service/`, a small
+  Node.js sidecar using Excalidraw's own real export code
+  (`@excalidraw/utils`'s `exportToSvg`) plus `@resvg/resvg-js` (a native
+  Rust SVG rasterizer, no headless browser) to turn that into a PNG. That
+  sidecar runs as a **second process inside this same container**
+  (`Dockerfile` installs Node, `start.sh` launches it in the background
+  before `exec`-ing uvicorn), reachable only at `127.0.0.1:3001` from the
+  Python process -- not a second docker-compose service, since it's
+  lightweight, stateless, and has nothing worth independently scaling or
+  restarting. License check (after getting burned once already in this
+  same file, on the CalDAV dependency below, into checking transitive
+  deps and not just top-level ones): Excalidraw, `@excalidraw/utils`,
+  every one of its own runtime dependencies, `@resvg/resvg-js`
+  (MPL-2.0 -- weak/file-level copyleft, doesn't extend to code that just
+  calls into it), `jsdom`, and `express` are all MIT/Apache-2.0/Zlib/
+  MPL-2.0 -- no repeat of the AGPL surprise. **Not runtime-tested against
+  a real `npm install`/`docker build`** -- this project's dev environment
+  has no Node.js/npm, only network access to the npm registry API (used
+  to verify the above and pick real, current dependency versions). See
+  `render-service/README.md` for exactly what is and isn't verified.
+- Calendar event titles can contain emoji, which `ImageFont.load_default()`
+  (used for every other bit of text this project renders) has no glyphs
+  for -- PIL/FreeType substitute a visible ".notdef" tofu box rather than
+  skipping the codepoint. `app/calendar_render.py` draws emoji runs with
+  a vendored font instead (Google's Noto Emoji, OFL-1.1 -- license text
+  at `app/fonts/OFL.txt`), the one deliberate exception to this project's
+  usual "no new font/icon assets" default elsewhere in calendar_render.py
+  -- there's no way to hand-draw arbitrary emoji with primitives the way
+  the weather icons are. Full color (`app/fonts/NotoColorEmoji.ttf`,
+  embedded CBDT bitmap glyphs) is tried first and confirmed to hold up
+  fine through the panel's own Floyd-Steinberg dithering; a deployment
+  whose Pillow/FreeType wasn't built with embedded color bitmap support
+  falls back to a monochrome outline font (`app/fonts/NotoEmoji.ttf`)
+  instead of crashing or rendering nothing. Color glyphs are only stored
+  at one embedded bitmap size (109px), so they're rasterized once at
+  that size and scaled down to the target row height rather than drawn
+  directly like normal vector text.
+- The 6-color palette RGB values in `app/image_pipeline.py`
+  (`DEFAULT_PALETTE_RGB`) are approximations, not measured values
+  (Waveshare doesn't publish exact color primaries for this panel).
+  Each frame's Configuration tab has an **Advanced configuration**
+  section (collapsed by default) with a color picker per ink color --
+  tune them once you can compare a rendered photo against the real
+  panel, and "Reset to defaults" to go back. Different panel units can
+  vary enough to be worth calibrating per frame.
 
 ## Deploying a pre-built image
 
@@ -268,3 +305,19 @@ CONFIG_PATH=./data/config.json uvicorn app.main:app --reload --host 0.0.0.0 --po
 `--host 0.0.0.0` matters here: without it, uvicorn defaults to
 `127.0.0.1` (localhost-only), which the ESP32 can't reach over the LAN.
 The Docker image already binds `0.0.0.0` by default.
+
+## Running tests
+
+```
+pip install -r requirements-dev.txt
+pytest
+```
+
+Runs against a fresh temp SQLite database (`tests/conftest.py` sets
+`DATABASE_URL` before anything imports `app.db`), with every table wiped
+and reseeded (frame #1 + server settings, same as a real fresh install)
+between tests -- no Docker, Node, or a real Immich/CalDAV/WebDAV server
+needed; a few tests spin up small local HTTP servers as fixtures to
+stand in for those. Also runs as its own job in
+`.gitea/workflows/server-docker-build.yml`, gating the image build/push
+-- a failing test suite blocks the push, not just decorates it.

server/app/auth.py

@@ -0,0 +1,389 @@
+"""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, PasswordResetToken, PendingClaim, ServerSettings, 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
+PASSWORD_RESET_TOKEN_LIFETIME_S = 3600
+
+# 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 get_server_settings(db: Session) -> ServerSettings:
+    """The SMTP config singleton -- migration.py guarantees row id=1
+    exists (created at startup if missing), so this is never None."""
+    settings = db.get(ServerSettings, 1)
+    assert settings is not None
+    return settings
+
+
+def create_password_reset_token(db: Session, user: User) -> str:
+    token = secrets.token_urlsafe(32)
+    now = time.time()
+    # Opportunistic prune, same pattern as sessions/pending claims.
+    for stale in db.scalars(select(PasswordResetToken).where(PasswordResetToken.expires_at < now)):
+        db.delete(stale)
+    db.add(PasswordResetToken(
+        token=token, user_id=user.id, created_at=now,
+        expires_at=now + PASSWORD_RESET_TOKEN_LIFETIME_S,
+    ))
+    db.commit()
+    return token
+
+
+def consume_password_reset_token(db: Session, token: str) -> User | None:
+    """Looks up the token and, if valid, deletes it (single-use) and
+    returns the user it was issued for. None for an unknown/expired
+    token -- callers show a generic error either way."""
+    row = db.get(PasswordResetToken, token)
+    if row is None or row.expires_at < time.time():
+        return None
+    user = db.get(User, row.user_id)
+    db.delete(row)
+    db.commit()
+    return user
+
+
+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/caldav_client.py

@@ -0,0 +1,225 @@
+"""CalDAV account support: discovering which calendars an account exposes,
+and fetching one calendar's events or tasks -- the second way (alongside
+calendar_feed.py's single-file ICS subscription) a user can link a
+calendar for calendar frame mode (Nextcloud, Fastmail, iCloud, Radicale,
+Baikal, ...). Task lists (VTODO collections) are CalDAV-only -- a plain
+ICS subscription doesn't meaningfully have one -- see fetch_tasks.
+
+Thin wrapper around the `caldav` PyPI package (RFC 4791 client). NOTE ON
+LICENSING: `caldav` itself is dual-licensed GPL-3.0-or-later / Apache-2.0,
+but it hard-depends on `icalendar-searcher`, which is AGPL-3.0-or-later --
+the strongest copyleft license in this project's dependency tree, and the
+one whose network-use clause is specifically written for server
+applications like this one. This was an explicit, informed call by the
+project owner to accept that exposure rather than hand-roll a CalDAV
+client -- see the server README's Notes section. Anyone redistributing
+this project (as opposed to just self-hosting it) should reread that
+tradeoff for their own situation.
+
+Pure functions -- no ORM, no FastAPI Depends -- same testability
+philosophy as calendar_feed.py. Event parsing/expansion reuses
+icalendar + recurring_ical_events directly (rather than trusting each
+CalDAV server's own possibly-inconsistent RRULE expansion) so a CalDAV
+calendar and an ICS subscription behave identically once fetched.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import date, datetime
+
+import caldav
+import icalendar
+import recurring_ical_events
+
+logger = logging.getLogger(__name__)
+
+HTTP_TIMEOUT_S = 15
+
+
+class CalDavError(Exception):
+    """Discovery or fetch failed -- network, auth, or an unexpected
+    server response. Raised loudly; callers (Settings' discover
+    endpoint, calendar_feed.merge_events) decide what to do. Wraps
+    whatever the caldav package/its transport raised, since that
+    exception hierarchy isn't something call sites should need to know
+    about directly."""
+
+
+def discover_calendars(base_url: str, username: str, password: str) -> list[dict]:
+    """[{"href": absolute_calendar_url, "display_name": str}, ...] for
+    every calendar in this account. base_url is the server's CalDAV
+    entry point (e.g. "https://cloud.example.com/remote.php/dav/" for
+    Nextcloud) -- the caller supplies it directly, same idiom as the
+    plain ICS subscription URL."""
+    try:
+        client = caldav.DAVClient(url=base_url, username=username, password=password, timeout=HTTP_TIMEOUT_S)
+        calendars = client.principal().calendars()
+    except Exception as e:
+        raise CalDavError(str(e)) from e
+
+    result = []
+    for cal in calendars:
+        try:
+            display_name = cal.get_display_name() or cal.name
+        except Exception:
+            display_name = None
+        result.append({"href": str(cal.url), "display_name": display_name or str(cal.url)})
+    return result
+
+
+def fetch_calendar_events(calendar_url: str, username: str, password: str,
+                           window_start: date, window_end: date) -> list[dict]:
+    """One CalDAV calendar's events in [window_start, window_end] -- same
+    event dict shape as calendar_feed.fetch_source_events (no
+    "owner_display_name"; the caller adds that).
+
+    Deliberately does NOT use the calendar-query REPORT's server-side
+    time-range filter (caldav.Calendar.date_search) -- RFC 4791 leaves
+    that corner case underspecified and real servers disagree on it
+    (the caldav package's own docs warn "servers often behave
+    differently when presented with a search request"; confirmed here
+    too, once against a real server, as a calendar whose events just
+    silently never came back despite discovery/auth both working
+    fine). Instead this fetches every event in the calendar unfiltered
+    (get_events() is a plain "list VEVENTs" REPORT with no time-range
+    element -- the much more universally-supported case) and does 100%
+    of the date-window filtering/recurrence-expansion client-side via
+    icalendar + recurring_ical_events, exactly like calendar_feed.py
+    already does for plain ICS feeds. Heavier per-fetch (the whole
+    calendar, not just the window) but far more reliable."""
+    try:
+        client = caldav.DAVClient(url=calendar_url, username=username, password=password, timeout=HTTP_TIMEOUT_S)
+        calendar = caldav.Calendar(client=client, url=calendar_url)
+        objects = calendar.get_events()
+    except Exception as e:
+        raise CalDavError(str(e)) from e
+
+    events: list[dict] = []
+    for obj in objects:
+        try:
+            ical = icalendar.Calendar.from_ical(obj.data)
+            occurrences = recurring_ical_events.of(ical).between(window_start, window_end)
+        except Exception as e:  # one malformed resource shouldn't blank the whole calendar
+            logger.warning("Could not parse a CalDAV event from %s: %s", calendar_url, e)
+            continue
+        for occ in occurrences:
+            dtstart = occ.get("DTSTART")
+            dtend = occ.get("DTEND")
+            if dtstart is None:
+                continue
+            start_dt = dtstart.dt
+            end_dt = dtend.dt if dtend is not None else start_dt
+            all_day = not isinstance(start_dt, datetime)
+            events.append({
+                "summary": str(occ.get("SUMMARY") or "(untitled)"),
+                "start": start_dt.isoformat(),
+                "end": end_dt.isoformat(),
+                "all_day": all_day,
+            })
+    return events
+
+
+def fetch_tasks(calendar_url: str, username: str, password: str,
+                completed_since: datetime | None = None) -> list[dict]:
+    """Outstanding VTODOs from one CalDAV task list, plus -- when
+    completed_since is given -- ones completed at or after that cutoff
+    (see routers/common.py's get_or_refresh_tasks_for_widget, which
+    passes "now - 24h" when TaskWidgetConfig.show_completed is on;
+    None, the default, means completed tasks are dropped entirely, the
+    original behavior). {"summary", "due" (ISO date/datetime string or
+    None), "completed_at" (ISO datetime string, or None for an
+    outstanding task)}, ... . Outstanding tasks sort first (by due date,
+    no-due-date last), any included completed ones after (most recently
+    completed first).
+
+    Fetches every task including completed ones and filters/sorts
+    client-side rather than trusting get_todos()'s own
+    include_completed/sort_keys server-side filtering, same reasoning as
+    fetch_calendar_events not trusting the time-range REPORT filter --
+    a simpler filter than a time range, but not worth re-litigating
+    which server-side filters are reliable one at a time."""
+    try:
+        client = caldav.DAVClient(url=calendar_url, username=username, password=password, timeout=HTTP_TIMEOUT_S)
+        calendar = caldav.Calendar(client=client, url=calendar_url)
+        objects = calendar.get_todos(include_completed=True)
+    except Exception as e:
+        raise CalDavError(str(e)) from e
+
+    outstanding: list[dict] = []
+    completed: list[dict] = []
+    for obj in objects:
+        try:
+            ical = icalendar.Calendar.from_ical(obj.data)
+        except Exception as e:  # one malformed resource shouldn't blank the whole list
+            logger.warning("Could not parse a CalDAV task from %s: %s", calendar_url, e)
+            continue
+        for component in ical.walk("VTODO"):
+            status = str(component.get("STATUS") or "NEEDS-ACTION").upper()
+            summary = str(component.get("SUMMARY") or "(untitled)")
+            if status == "COMPLETED":
+                completed_prop = component.get("COMPLETED")
+                completed_dt = completed_prop.dt if completed_prop is not None else None
+                if completed_since is None or completed_dt is None or completed_dt < completed_since:
+                    continue
+                completed.append({"summary": summary, "due": None, "completed_at": completed_dt.isoformat()})
+            else:
+                due = component.get("DUE")
+                outstanding.append({
+                    "summary": summary,
+                    "due": due.dt.isoformat() if due is not None else None,
+                    "completed_at": None,
+                })
+    outstanding.sort(key=lambda t: (t["due"] is None, t["due"] or ""))
+    completed.sort(key=lambda t: t["completed_at"], reverse=True)
+    return outstanding + completed
+
+
+@dataclass
+class TaskSource:
+    """One task list to merge in -- CalDAV only, no ICS variant (a plain
+    ICS subscription has no VTODO collection to speak of).
+    owner_display_name tags every task pulled from this source so a
+    merged checklist can show whose task is whose; color_index (2-5,
+    into image_pipeline.DEFAULT_PALETTE_RGB) is this list's manually
+    pinned color, or None for calendar_render.py's auto-cycle-by-owner-
+    name fallback -- see models.FrameTaskList."""
+
+    owner_display_name: str
+    url: str
+    username: str
+    password: str
+    color_index: int | None = None
+
+
+def merge_tasks(sources: list[TaskSource], completed_since: datetime | None = None) -> tuple[list[dict], str]:
+    """Fetches each source independently -- one broken list never blanks
+    another's tasks. Returns (merged_tasks, fetch_summary); fetch_summary
+    is "" when every source succeeded, else "N of M task lists
+    unavailable" (same no-naming-names posture as calendar_feed.
+    merge_events). No cross-list duplicate collapsing (unlike
+    merge_events) -- a task synced to two lists at once is rare enough,
+    and lower-stakes than a duplicated calendar event, not to be worth
+    the same de-dup machinery."""
+    merged: list[dict] = []
+    failures = 0
+    for source in sources:
+        try:
+            tasks = fetch_tasks(source.url, source.username, source.password, completed_since=completed_since)
+        except CalDavError:
+            failures += 1
+            continue
+        for task in tasks:
+            merged.append({
+                **task,
+                "owner_display_name": source.owner_display_name,
+                "color_index": source.color_index,
+            })
+
+    outstanding = [t for t in merged if t["completed_at"] is None]
+    completed = [t for t in merged if t["completed_at"] is not None]
+    outstanding.sort(key=lambda t: (t["due"] is None, t["due"] or ""))
+    completed.sort(key=lambda t: t["completed_at"], reverse=True)
+    summary = f"{failures} of {len(sources)} task lists unavailable" if failures else ""
+    return outstanding + completed, summary

server/app/calendar_feed.py

@@ -0,0 +1,155 @@
+"""Fetch, parse, and merge per-user calendar feeds -- ICS subscriptions
+and (via caldav_client.py) CalDAV collections -- for calendar frame mode
+(see routers/device.py's RENDERERS["calendar"] and calendar_render.py).
+
+Pure functions -- no ORM, no FastAPI Depends. Callers (routers/common.py's
+get_or_refresh_calendar_events) supply plain CalendarSource values, not
+ORM objects, so this module stays testable against fixture .ics text with
+no database or app involved.
+
+Recurring events (RRULE/EXDATE/RDATE, DST-aware) are expanded via
+recurring-ical-events rather than hand-rolled -- that's genuinely fiddly
+to get right (see its own docs), not worth reinventing. It's LGPL-3.0 (an
+ordinary runtime pip dependency, never vendored/modified -- see the
+server README's Notes section for why that doesn't put this project's own
+code under LGPL terms).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+
+import httpx
+import icalendar
+import recurring_ical_events
+
+from . import caldav_client
+
+HTTP_TIMEOUT_S = 15.0
+FETCH_MAX_BYTES = 10 * 1024 * 1024  # sanity cap -- a real feed is KB, not MB
+
+CHECK_INTERVAL_S = 20 * 60  # don't refetch/reparse any feed more often than this
+
+# How far back/forward each merge-fetch expands recurring events. Households
+# look back far less than they plan ahead, hence the asymmetry. Browsing
+# outside this window (calendar_browse_offset) just yields an empty view,
+# not an error -- self-heals on the next normal wake regardless.
+EXPAND_WINDOW_PAST_DAYS = 30
+EXPAND_WINDOW_FUTURE_DAYS = 200
+
+
+class CalendarFetchError(Exception):
+    """One feed was unreachable, not valid ICS, or too large. Raised by
+    fetch_source_events(); merge_events() is what catches this per-source
+    so one broken feed can't blank out another's events."""
+
+
+def fetch_source_events(url: str, window_start: date, window_end: date) -> list[dict]:
+    """One feed: download, parse, expand recurrences within
+    [window_start, window_end]. Raises CalendarFetchError on any problem
+    -- network, malformed ICS, or an oversized response."""
+    try:
+        with httpx.stream("GET", url, timeout=HTTP_TIMEOUT_S, follow_redirects=True) as resp:
+            resp.raise_for_status()
+            chunks = []
+            total = 0
+            for chunk in resp.iter_bytes():
+                total += len(chunk)
+                if total > FETCH_MAX_BYTES:
+                    raise CalendarFetchError(f"Feed exceeds {FETCH_MAX_BYTES} bytes")
+                chunks.append(chunk)
+            body = b"".join(chunks)
+    except httpx.HTTPError as e:
+        raise CalendarFetchError(str(e)) from e
+
+    try:
+        cal = icalendar.Calendar.from_ical(body)
+        occurrences = recurring_ical_events.of(cal).between(window_start, window_end)
+    except Exception as e:  # icalendar/recurring_ical_events raise a mix of ValueError-family exceptions
+        raise CalendarFetchError(f"Could not parse ICS feed: {e}") from e
+
+    events = []
+    for occ in occurrences:
+        dtstart = occ.get("DTSTART")
+        dtend = occ.get("DTEND")
+        if dtstart is None:
+            continue
+        start_dt = dtstart.dt
+        end_dt = dtend.dt if dtend is not None else start_dt
+        all_day = not isinstance(start_dt, datetime)  # date, not datetime -- VALUE=DATE
+        events.append({
+            "summary": str(occ.get("SUMMARY") or "(untitled)"),
+            "start": start_dt.isoformat(),
+            "end": end_dt.isoformat(),
+            "all_day": all_day,
+        })
+    return events
+
+
+@dataclass(frozen=True)
+class CalendarSource:
+    """One calendar to merge in: either a plain ICS subscription (kind
+    "ics", url is the feed itself) or one CalDAV collection (kind
+    "caldav", url is the calendar's own URL, username/password its
+    account credentials) -- see caldav_client.py. owner_display_name
+    tags every event pulled from this source so a merged agenda can show
+    whose event is whose. color_index (2-5, into
+    image_pipeline.DEFAULT_PALETTE_RGB) is this calendar's manually
+    pinned color, or None to fall back on calendar_render.py's old
+    auto-cycle-by-owner-name behavior -- see models.FrameCalendar."""
+
+    owner_display_name: str
+    kind: str
+    url: str
+    username: str = ""
+    password: str = ""
+    color_index: int | None = None
+
+
+def merge_events(
+    sources: list[CalendarSource], window_start: date, window_end: date
+) -> tuple[list[dict], str]:
+    """Fetches each source independently -- one broken feed never blanks
+    another's events. Returns (merged_time_sorted_events, fetch_summary);
+    fetch_summary is "" when every source succeeded, else "N of M
+    calendars unavailable" (never *which* source -- naming whose feed is
+    down to everyone who looks at a shared household display is a bigger
+    overshare than the outage itself).
+
+    Events sharing the exact same (summary, start, end, all_day) across
+    different calendars -- e.g. a shared family event synced onto more
+    than one person's calendar -- collapse into one entry rather than
+    showing as duplicate rows. Every merged event carries a "sources"
+    list ([{"owner_display_name", "color_index"}, ...], length 1 for an
+    ordinary non-duplicated event) that calendar_render.py draws a
+    color indicator per entry of, so a collapsed event still visibly
+    shows every calendar it came from."""
+    merged: list[dict] = []
+    by_key: dict[tuple, dict] = {}
+    failures = 0
+    for source in sources:
+        try:
+            if source.kind == "caldav":
+                events = caldav_client.fetch_calendar_events(
+                    source.url, source.username, source.password, window_start, window_end
+                )
+            else:
+                events = fetch_source_events(source.url, window_start, window_end)
+        except (CalendarFetchError, caldav_client.CalDavError):
+            failures += 1
+            continue
+        for event in events:
+            source_entry = {"owner_display_name": source.owner_display_name, "color_index": source.color_index}
+            key = (event["summary"], event["start"], event["end"], event["all_day"])
+            existing = by_key.get(key)
+            if existing is None:
+                event["sources"] = [source_entry]
+                by_key[key] = event
+                merged.append(event)
+            else:
+                existing["sources"].append(source_entry)
+
+    merged.sort(key=lambda e: e["start"])
+    summary = f"{failures} of {len(sources)} calendars unavailable" if failures else ""
+    return merged, summary

server/app/calendar_render.py

@@ -0,0 +1,850 @@
+"""Renders calendar frame mode's three views (agenda/week/month), and the
+separate standalone tasks widget (see models.TaskWidgetConfig -- a task
+list used to be a calendar-widget-only week-view slot, split out into
+its own widget type so it isn't tied to a calendar's view/footprint),
+into the panel's packed format, following image_pipeline.
+render_placeholder's own precedent: build an RGB canvas with
+ImageDraw/ImageFont, then the same _quantize/_transpose_and_pack every
+other renderer ends on.
+
+Event dicts here are calendar_feed.py's shape: {"summary", "start", "end"
+(ISO 8601 strings), "all_day", "sources": [{"owner_display_name",
+"color_index"}, ...]} -- more than one entry in "sources" means
+merge_events collapsed several calendars' identical (same title/time)
+events into one, see _event_colors/_draw_color_bar below.
+"""
+
+from __future__ import annotations
+
+import calendar as calendar_module
+import io
+import re
+from datetime import date, datetime, timedelta
+from functools import lru_cache
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from PIL import Image, ImageDraw, ImageFont
+
+from .image_pipeline import (
+    DEFAULT_PALETTE_RGB,
+    _apply_manage_overlay,
+    _quantize,
+    _transpose_and_pack,
+    draw_text,
+    logical_render_size,
+)
+from .weather import weather_category
+from .weather_render import draw_weather_row
+
+CALENDAR_VIEWS = ["agenda", "today_tomorrow", "week", "month"]
+CALENDAR_VIEW_LABELS = {"agenda": "Agenda (today)", "today_tomorrow": "Agenda (today & tomorrow)",
+                        "week": "Week", "month": "Month"}
+WEEKDAY_NAMES = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
+
+MARGIN = 20
+BG = (255, 255, 255)
+FG = (0, 0, 0)
+MUTED = (110, 110, 110)
+# Was a light gray, but that dithers away to near-invisible once quantized
+# to the 6-color e-ink palette -- black reads as an actual line on-panel.
+RULE = (0, 0, 0)
+
+# Fallback for any event whose calendar has no manually pinned color
+# (event["color_index"] is None): cycled per distinct owner_display_name
+# so a merged multi-person calendar can still visually tell whose event
+# is whose -- the panel's own non-black/white ink colors, skipping
+# black/white (index 0/1 in DEFAULT_PALETTE_RGB) since those are already
+# the page's text/background.
+OWNER_COLORS = DEFAULT_PALETTE_RGB[2:]
+
+
+def _event_colors(event: dict, owners_seen: list[str], palette_rgb: list | None) -> list[tuple[int, int, int]]:
+    """One color per contributing calendar (event["sources"] -- see
+    calendar_feed.merge_events, which collapses events sharing the exact
+    same title/time across different calendars into one entry with
+    several sources, e.g. a shared family event synced onto more than
+    one person's calendar). Usually just one color; more than one is
+    what tells the "same event, more than one calendar" case apart from
+    an ordinary single-calendar event at render time -- see
+    _draw_color_bar. Each source's own manually pinned color
+    (FrameCalendar.color_index -- see routers/api_widgets.py's
+    api_widget_calendar_color) resolves against whichever palette this frame
+    actually renders with, so a pinned "Blue" stays this frame's actual
+    blue; a source with no color pinned falls back to the old
+    auto-cycle-by-owner-name behavior. owners_seen is shared across every
+    event/source in a render so that cycle stays consistent view-wide."""
+    sources = event.get("sources") or [
+        {"owner_display_name": event.get("owner_display_name"), "color_index": event.get("color_index")}
+    ]
+    colors = []
+    for source in sources:
+        color_index = source.get("color_index")
+        if color_index is not None:
+            palette = palette_rgb or DEFAULT_PALETTE_RGB
+            colors.append(tuple(palette[color_index]))
+            continue
+        owner_display_name = source.get("owner_display_name")
+        if owner_display_name not in owners_seen:
+            owners_seen.append(owner_display_name)
+        colors.append(OWNER_COLORS[owners_seen.index(owner_display_name) % len(OWNER_COLORS)])
+    return colors
+
+
+def _draw_color_bar(draw: ImageDraw.ImageDraw, x0: int, y0: int, x1: int, y1: int,
+                    colors: list[tuple[int, int, int]], radius: int) -> None:
+    """One rounded bar for a single-source event, or that same overall
+    footprint split into equal-width side-by-side segments -- one per
+    contributing calendar -- for a deduplicated shared event (see
+    _event_colors/calendar_feed.merge_events). Splitting rather than
+    e.g. concentric rings keeps every color equally "thick and bold" at
+    a glance, the same design goal a single pinned color already has."""
+    if len(colors) == 1:
+        draw.rounded_rectangle([x0, y0, x1, y1], radius=radius, fill=colors[0])
+        return
+    seg_w = (x1 - x0) / len(colors)
+    for i, color in enumerate(colors):
+        seg_x0 = round(x0 + i * seg_w)
+        seg_x1 = round(x0 + (i + 1) * seg_w) - (2 if i < len(colors) - 1 else 0)
+        draw.rectangle([seg_x0, y0, seg_x1, y1], fill=color)
+
+
+def _event_start(event: dict, tz: ZoneInfo) -> datetime | date:
+    """Parses event["start"] and, for timed events, converts to `tz` --
+    calendar_feed.py stores whatever timezone each source event carried
+    (often UTC), but display/bucketing needs to happen in the frame's own
+    timezone."""
+    dt = datetime.fromisoformat(event["start"])
+    if event["all_day"]:
+        return dt if isinstance(dt, date) and not isinstance(dt, datetime) else dt.date()
+    return dt.astimezone(tz)
+
+
+def _events_on_day(events: list[dict], day: date, tz: ZoneInfo) -> list[dict]:
+    on_day = [e for e in events if _local_date(e, tz) == day]
+    on_day.sort(key=lambda e: (not e["all_day"], e["start"]))
+    return on_day
+
+
+def _local_date(event: dict, tz: ZoneInfo) -> date:
+    start = _event_start(event, tz)
+    return start if isinstance(start, date) and not isinstance(start, datetime) else start.date()
+
+
+def _add_months(d: date, months: int) -> date:
+    total = d.month - 1 + months
+    year = d.year + total // 12
+    month = total % 12 + 1
+    day = min(d.day, calendar_module.monthrange(year, month)[1])
+    return date(year, month, day)
+
+
+def _fmt_time(dt: datetime) -> str:
+    text = dt.strftime("%I:%M %p").lstrip("0")
+    return text if text else "12:00 AM"
+
+
+def _fmt_task_due(due: str | None) -> str:
+    """"2026-07-25" or "2026-07-25T14:00:00+00:00" -> "Jul 25" -- tasks
+    only need a compact reminder of when they're due, not the precision
+    an event's own start/end time gets."""
+    if not due:
+        return ""
+    try:
+        dt = datetime.fromisoformat(due)
+    except ValueError:
+        return ""
+    d = dt.date() if isinstance(dt, datetime) else dt
+    return d.strftime("%b %-d")
+
+
+# ImageFont.load_default() (used for everything else in this module --
+# see the module docstring) has no emoji glyphs, and PIL/FreeType don't
+# skip an unsupported codepoint, they substitute a ".notdef" tofu box (a
+# visible filled rectangle) -- reads as a rendering glitch, not "emoji
+# not supported". So event titles get drawn with two fonts: the normal
+# text font for everything else, and one of these for actual emoji runs
+# (see _split_emoji_runs/_draw_mixed_line) -- both Noto Emoji, OFL-1.1,
+# vendored at app/fonts/ (license alongside at app/fonts/OFL.txt).
+#
+# Color (NotoColorEmoji.ttf) is tried first: full-color CBDT bitmap
+# glyphs, which the panel's own Floyd-Steinberg dithering turns into a
+# recognizable (if slightly speckled) color rendering rather than a flat
+# monochrome shape -- confirmed by actually rendering a test agenda row
+# through the real quantizer, not just theorizing about it. Its one
+# real quirk: CBDT stores glyphs at a single embedded bitmap size
+# (_COLOR_EMOJI_NATIVE_SIZE), so every glyph is rasterized once at that
+# size and scaled down to the target row height, unlike normal vector
+# text which draws directly at whatever size is asked for.
+#
+# NotoEmoji.ttf (monochrome, vector) is the fallback for a deployment
+# whose Pillow/FreeType wasn't built with embedded color bitmap support
+# -- confirmed working locally, but that's a build-time detail this
+# project doesn't control everywhere it might run, so a rendering
+# failure falls back instead of showing nothing/crashing.
+_COLOR_EMOJI_FONT_PATH = Path(__file__).parent / "fonts" / "NotoColorEmoji.ttf"
+_MONO_EMOJI_FONT_PATH = Path(__file__).parent / "fonts" / "NotoEmoji.ttf"
+_COLOR_EMOJI_NATIVE_SIZE = 109
+
+
+@lru_cache(maxsize=1)
+def _color_emoji_font() -> ImageFont.FreeTypeFont | None:
+    try:
+        return ImageFont.truetype(str(_COLOR_EMOJI_FONT_PATH), _COLOR_EMOJI_NATIVE_SIZE)
+    except Exception:
+        return None
+
+
+@lru_cache(maxsize=None)
+def _mono_emoji_font(size: int) -> ImageFont.FreeTypeFont:
+    return ImageFont.truetype(str(_MONO_EMOJI_FONT_PATH), size)
+
+
+@lru_cache(maxsize=512)
+def _emoji_glyph(run_text: str, target_h: int) -> Image.Image:
+    """One emoji run (consecutive emoji collapse into a single run, see
+    _split_emoji_runs) as an RGBA image target_h tall, ready to
+    alpha-composite onto the canvas. Tries color first, falls back to
+    monochrome (rendered directly at target_h, since that font is
+    vector) if the color font failed to load or this Pillow/FreeType
+    build can't decode its embedded bitmaps. Cached -- the same emoji
+    recurs across a household's events, and rasterizing+scaling isn't
+    free."""
+    color_font = _color_emoji_font()
+    if color_font is not None:
+        try:
+            probe = ImageDraw.Draw(Image.new("RGBA", (1, 1)))
+            raw_w = max(1, round(probe.textlength(run_text, font=color_font)))
+            tmp = Image.new("RGBA", (raw_w, _COLOR_EMOJI_NATIVE_SIZE), (255, 255, 255, 0))
+            ImageDraw.Draw(tmp).text((0, 0), run_text, font=color_font, embedded_color=True)
+            scale = target_h / _COLOR_EMOJI_NATIVE_SIZE
+            return tmp.resize((max(1, round(raw_w * scale)), target_h), Image.LANCZOS)
+        except Exception:
+            pass  # this deployment's Pillow can't render embedded color bitmaps -- fall back
+
+    mono_font = _mono_emoji_font(target_h)
+    bbox = mono_font.getbbox(run_text)
+    w, h = max(1, bbox[2] - bbox[0]), max(1, bbox[3] - bbox[1])
+    mask = Image.new("L", (w, h), 0)
+    ImageDraw.Draw(mask).text((-bbox[0], -bbox[1]), run_text, fill=255, font=mono_font)
+    glyph = Image.new("RGBA", (w, h), (255, 255, 255, 0))
+    glyph.paste((0, 0, 0, 255), (0, 0), mask)
+    return glyph
+
+
+# Matches runs of actual emoji base characters (the standard Unicode
+# emoji blocks -- stable ranges even as new individual emoji get added
+# within them, so this doesn't need updating as emoji sets grow).
+_EMOJI_PATTERN = re.compile(
+    "["
+    "\U0001F1E6-\U0001F1FF"  # regional indicator symbols (flag emoji)
+    "\U0001F300-\U0001F5FF"  # misc symbols & pictographs
+    "\U0001F600-\U0001F64F"  # emoticons
+    "\U0001F680-\U0001F6FF"  # transport & map symbols
+    "\U0001F900-\U0001F9FF"  # supplemental symbols & pictographs
+    "\U0001FA70-\U0001FAFF"  # symbols & pictographs extended-A
+    "\U00002600-\U000026FF"  # misc symbols (☀☂☕ etc.)
+    "\U00002700-\U000027BF"  # dingbats (✂✈✉ etc.)
+    "]+"
+)
+_EMOJI_SPLIT_PATTERN = re.compile(f"({_EMOJI_PATTERN.pattern})")
+# Codepoints with no meaningful standalone glyph once color/ligature
+# context is dropped: skin-tone modifiers (this is monochrome -- no
+# color to modify), the variation selector that just requests emoji
+# presentation, and the zero-width joiner used to fuse multiple emoji
+# into one combined glyph. That fusion (e.g. the "family" emoji from
+# four base emoji + 3 ZWJs) needs OpenType ligature substitution
+# (raqm/harfbuzz), which Pillow only does with a specific, non-default
+# build -- not something to depend on. Stripping the ZWJ instead means a
+# ZWJ sequence just draws as its individual base glyphs side by side
+# (four separate people instead of one family glyph) -- a real fallback,
+# not a crash or tofu.
+_EMOJI_MODIFIER_PATTERN = re.compile("[\U0001F3FB-\U0001F3FF\U0000FE0F\U0000200D]")
+
+
+def _split_emoji_runs(text: str) -> list[tuple[str, bool]]:
+    """text -> [(run, is_emoji), ...], modifier/joiner codepoints
+    dropped first (see _EMOJI_MODIFIER_PATTERN). Consecutive emoji
+    collapse into one run (_EMOJI_PATTERN's own "+"), consecutive
+    plain-text characters into the other."""
+    cleaned = _EMOJI_MODIFIER_PATTERN.sub("", text)
+    parts = [p for p in _EMOJI_SPLIT_PATTERN.split(cleaned) if p]
+    return [(p, bool(_EMOJI_PATTERN.fullmatch(p))) for p in parts]
+
+
+def _draw_mixed_line(img: Image.Image, draw: ImageDraw.ImageDraw, xy: tuple[int, int], text: str,
+                     text_font: ImageFont.ImageFont, max_width: int, fill: tuple[int, int, int] = FG) -> None:
+    """Draws `text` left-to-right, switching between text_font (normal
+    characters) and an emoji glyph image (actual emoji runs, per
+    _split_emoji_runs/_emoji_glyph) so emoji visibly render instead of a
+    tofu box. Truncates with "..." once max_width is exceeded -- unlike
+    _truncate_to_width this can't binary-search a single font's metrics
+    across mixed fonts/images, so it works run-by-run instead (and can't
+    partially truncate an emoji run the way it can a text run -- one
+    that doesn't fit just isn't drawn). Fine for the short single-line
+    strings this draws (event/task titles), not meant as a general
+    rich-text layout engine. `fill` only affects text runs -- emoji
+    glyphs are already their own color."""
+    x, y = xy
+    cursor = x
+    # A little taller than text_font's own size so glyphs don't look
+    # cramped next to it; the -2 paste offset below roughly centers that
+    # against the surrounding text's row -- tuned by eye against a real
+    # rendered agenda row, not derived from font metrics.
+    emoji_h = text_font.size + 6
+    for run_text, is_emoji in _split_emoji_runs(text):
+        remaining = max_width - (cursor - x)
+        if remaining <= 0:
+            break
+        if is_emoji:
+            glyph = _emoji_glyph(run_text, emoji_h)
+            if glyph.width <= remaining:
+                img.paste(glyph, (round(cursor), y - 2), glyph)
+                cursor += glyph.width
+            else:
+                break
+        else:
+            run_w = draw.textlength(run_text, font=text_font)
+            if run_w <= remaining:
+                draw_text(img, (round(cursor), y), run_text, text_font, fill)
+                cursor += run_w
+            else:
+                draw_text(img, (round(cursor), y), _truncate_to_width(draw, run_text, text_font, remaining),
+                         text_font, fill)
+                break
+
+
+def _truncate_to_width(draw: ImageDraw.ImageDraw, text: str, font: ImageFont.ImageFont, max_width: int) -> str:
+    """Pixel-width-aware truncation (unlike device.py's char-count
+    _truncate, tuned for a fixed firmware font at a fixed size) -- this
+    module draws at several different sizes, so truncation has to
+    measure the actual font/size in play. Still uses `draw.textlength`
+    for measurement (identical metrics to draw_text's own bbox), just
+    doesn't paint anything."""
+    if draw.textlength(text, font=font) <= max_width:
+        return text
+    ellipsis = "..."
+    lo, hi = 0, len(text)
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        if draw.textlength(text[:mid] + ellipsis, font=font) <= max_width:
+            lo = mid
+        else:
+            hi = mid - 1
+    return text[:lo] + ellipsis if lo else ellipsis
+
+
+# --- Size tiers ---------------------------------------------------------
+#
+# A calendar widget can now be placed at any grid footprint (see
+# app/grid.py), not just the full panel -- these three discrete tiers
+# (chosen by nearest-fit against the target box's pixel area) drive font
+# sizes/margins instead of continuously scaling a layout that was tuned
+# by eye for the full ~800x480 panel, which would risk ugly proportions
+# at odd in-between sizes. Area-based (not width/height-based) so the
+# same footprint tiers the same regardless of landscape/portrait target
+# box shape.
+_TIER_LARGE_AREA = 280_000   # near/at a full 800x480 panel (384,000px^2)
+_TIER_MEDIUM_AREA = 120_000  # roughly a half-panel split
+
+
+def _size_tier(target_w: int, target_h: int) -> str:
+    area = target_w * target_h
+    if area >= _TIER_LARGE_AREA:
+        return "large"
+    if area >= _TIER_MEDIUM_AREA:
+        return "medium"
+    return "small"
+
+
+def _month_view_fits(target_w: int, target_h: int) -> bool:
+    """Month view needs real width to keep 7 columns' day numbers and
+    density dots legible -- below the "small" size tier that stops being
+    true, so _build falls back to agenda view instead of drawing an
+    unreadable grid."""
+    return _size_tier(target_w, target_h) != "small"
+
+
+# --- Weather strip, agenda/today & tomorrow/week views only (never
+# month -- see _BUILDERS/_build) --------------------------------------
+
+def _weather_for_day(weather_cities: list[dict] | None, day: date) -> list[dict]:
+    """[{"label", "code", "high", "low", "category"}, ...] for every
+    configured city that has a cached forecast for this specific date --
+    weather_cities is routers/common.py's get_or_refresh_weather() cache
+    shape, [{"label", "days": {"YYYY-MM-DD": {"code","high","low"}}}]."""
+    if not weather_cities:
+        return []
+    key = day.isoformat()
+    entries = []
+    for city in weather_cities:
+        d = (city.get("days") or {}).get(key)
+        if d is None:
+            continue
+        # Just the city name on-panel ("Portland", not the full
+        # disambiguated "Portland, Oregon, United States") -- that fuller
+        # form matters for telling apart geocoder candidates when adding
+        # a city (see weather.geocode_city), not for a compact display row.
+        entries.append({"label": city["label"].split(",")[0].strip(), "high": d["high"], "low": d["low"],
+                        "category": weather_category(d["code"])})
+    return entries
+
+
+def _draw_agenda_day(img: Image.Image, draw: ImageDraw.ImageDraw, day: date, events: list[dict], tz: ZoneInfo,
+                     region: tuple[int, int, int, int], title_font: ImageFont.ImageFont,
+                     body_font: ImageFont.ImageFont, owners_seen: list[str], palette_rgb: list | None = None,
+                     weather_cities: list[dict] | None = None, weather_font: ImageFont.ImageFont | None = None,
+                     weather_units: str = "fahrenheit") -> None:
+    """Draws one day's header + weather strip (if any) + event rows
+    within `region` (x0, y0, w, h) -- factored out of _build_agenda so
+    the today-and-tomorrow view (_build_today_tomorrow) can stack two of
+    these vertically without duplicating the row-layout/truncation
+    logic. Weather is drawn above the event list -- eating into the same
+    row budget the event count is truncated against, exactly like the
+    header/rule above it already does."""
+    x0, y0, w, h = region
+    text_x0, text_y0 = x0 + MARGIN, y0 + MARGIN
+    text_w = w - MARGIN * 2
+    header = day.strftime("%A, %B ") + str(day.day)
+    draw_text(img, (text_x0, text_y0), _truncate_to_width(draw, header, title_font, text_w), title_font)
+    y = text_y0 + title_font.size + 12
+    draw.line([(text_x0, y), (text_x0 + text_w, y)], fill=RULE)
+    y += 12
+
+    weather_entries = _weather_for_day(weather_cities, day)
+    if weather_entries:
+        y += draw_weather_row(img, draw, text_x0, y, text_w, weather_entries,
+                              icon_r=title_font.size // 2, font=weather_font or body_font, units=weather_units,
+                              palette_rgb=palette_rgb)
+
+    day_events = _events_on_day(events, day, tz)
+    row_h = body_font.size + 14
+    max_rows = max(0, (y0 + h - MARGIN - y) // row_h)
+
+    if not day_events:
+        draw_text(img, (text_x0, y), "Nothing scheduled", body_font, MUTED)
+    for i, event in enumerate(day_events):
+        if i >= max_rows:
+            draw_text(img, (text_x0, y), f"+{len(day_events) - max_rows} more", body_font, MUTED)
+            break
+        colors = _event_colors(event, owners_seen, palette_rgb)
+        _draw_color_bar(draw, text_x0, y + 2, text_x0 + 10, y + row_h - 7, colors, radius=3)
+        time_str = "All day" if event["all_day"] else _fmt_time(_event_start(event, tz))
+        prefix = f"{time_str}  "
+        draw_text(img, (text_x0 + 18, y), prefix, body_font)
+        prefix_w = draw.textlength(prefix, font=body_font)
+        _draw_mixed_line(img, draw, (text_x0 + 18 + prefix_w, y), event["summary"],
+                         body_font, text_w - 18 - prefix_w)
+        y += row_h
+
+
+def _draw_tasks(img: Image.Image, draw: ImageDraw.ImageDraw, region: tuple[int, int, int, int],
+                tasks: list[dict], title_font: ImageFont.ImageFont, body_font: ImageFont.ImageFont,
+                palette_rgb: list | None = None, title: str = "Tasks") -> None:
+    """A simple checklist filling `region` (x0, y0, w, h) -- a header
+    (`title`, truncated to fit -- TaskWidgetConfig.name or the "Tasks"
+    default; the only widget type with its own on-panel title, since
+    it's the only one where "which list is this" isn't obvious from its
+    content the way a calendar/photo/whiteboard's is), then a color bar
+    (reusing _event_colors/_draw_color_bar as-is: a task dict's
+    top-level owner_display_name/color_index is exactly _event_colors'
+    single-source fallback shape, since caldav_client.merge_tasks
+    doesn't cross-list-dedup tasks into a "sources" list the way
+    merge_events dedups events) + checkbox glyph + due date (if any) +
+    summary per task, same header/rule/row-cap/truncation shape as
+    _draw_agenda_day's event list so the standalone tasks widget (see
+    _build_tasks) reads as the same consistent design as everything
+    else on-panel, not a bolted-together look. Reuses _draw_mixed_line
+    so a task summary with emoji in it renders the same way an event
+    title's does.
+
+    Outstanding tasks get an empty checkbox; completed ones (only ever
+    present when TaskWidgetConfig.show_completed is on -- see
+    caldav_client.fetch_tasks' completed_since) get a filled one and
+    muted text, no due-date prefix (irrelevant once done)."""
+    x0, y0, w, h = region
+    text_x0, text_y0 = x0 + MARGIN, y0 + MARGIN
+    text_w = w - MARGIN * 2
+    draw_text(img, (text_x0, text_y0), _truncate_to_width(draw, title or "Tasks", title_font, text_w), title_font)
+    y = text_y0 + title_font.size + 12
+    draw.line([(text_x0, y), (text_x0 + text_w, y)], fill=RULE)
+    y += 12
+
+    row_h = body_font.size + 14
+    max_rows = max(0, (y0 + h - MARGIN - y) // row_h)
+
+    if not tasks:
+        draw_text(img, (text_x0, y), "Nothing outstanding", body_font, MUTED)
+        return
+    owners_seen: list[str] = []
+    for i, task in enumerate(tasks):
+        if i >= max_rows:
+            draw_text(img, (text_x0, y), f"+{len(tasks) - max_rows} more", body_font, MUTED)
+            break
+        done = task.get("completed_at") is not None
+        colors = _event_colors(task, owners_seen, palette_rgb)
+        _draw_color_bar(draw, text_x0, y + 2, text_x0 + 10, y + row_h - 7, colors, radius=3)
+        box = body_font.size - 6
+        box_x = text_x0 + 18
+        box_y = y + (row_h - box) // 2 - 5
+        if done:
+            draw.rectangle([box_x, box_y, box_x + box, box_y + box], fill=FG)
+        else:
+            draw.rectangle([box_x, box_y, box_x + box, box_y + box], outline=FG, width=2)
+        text_x = box_x + box + 10
+        due_str = None if done else _fmt_task_due(task.get("due"))
+        prefix = f"{due_str}  " if due_str else ""
+        if prefix:
+            draw_text(img, (text_x, y), prefix, body_font, MUTED)
+        prefix_w = draw.textlength(prefix, font=body_font) if prefix else 0
+        _draw_mixed_line(img, draw, (round(text_x + prefix_w), y), task["summary"],
+                         body_font, text_w - (text_x - text_x0) - prefix_w, fill=MUTED if done else FG)
+        y += row_h
+
+
+# Per-tier (title, body, weather) font sizes -- "Wednesday, July 22" at
+# full size doesn't fit a narrow column, and a narrower box is exactly
+# when a smaller font (rather than truncating to "Wednesday...") keeps
+# the header actually informative.
+_AGENDA_FONTS = {"large": (34, 22, 20), "medium": (24, 22, 16), "small": (18, 16, 13)}
+
+
+def _build_agenda(events: list[dict], browse_offset: int, target_w: int, target_h: int, tz: ZoneInfo,
+                  palette_rgb: list | None = None, weather_cities: list[dict] | None = None,
+                  weather_units: str = "fahrenheit") -> Image.Image:
+    img = Image.new("RGB", (target_w, target_h), BG)
+    draw = ImageDraw.Draw(img)
+
+    title_size, body_size, weather_size = _AGENDA_FONTS[_size_tier(target_w, target_h)]
+    title_font = ImageFont.load_default(size=title_size)
+    body_font = ImageFont.load_default(size=body_size)
+    weather_font = ImageFont.load_default(size=weather_size)
+
+    day = datetime.now(tz).date() + timedelta(days=browse_offset)
+    owners_seen: list[str] = []
+    _draw_agenda_day(img, draw, day, events, tz, (0, 0, target_w, target_h), title_font, body_font, owners_seen,
+                     palette_rgb, weather_cities, weather_font, weather_units)
+
+    return img
+
+
+_TODAY_TOMORROW_FONTS = {"large": (26, 18, 16), "medium": (20, 15, 13), "small": (15, 12, 10)}
+
+
+def _build_today_tomorrow(events: list[dict], browse_offset: int, target_w: int, target_h: int, tz: ZoneInfo,
+                          palette_rgb: list | None = None, weather_cities: list[dict] | None = None,
+                          weather_units: str = "fahrenheit") -> Image.Image:
+    """Two _draw_agenda_day sections stacked vertically (below each other
+    rather than side-by-side -- narrower than tall doesn't leave enough
+    width per day for the event-row text at smaller sizes). browse_offset
+    shifts the whole two-day window together, same "days" unit
+    _build_agenda already uses, so NEXT/BACK behaves identically across
+    both views."""
+    img = Image.new("RGB", (target_w, target_h), BG)
+    draw = ImageDraw.Draw(img)
+
+    title_size, body_size, weather_size = _TODAY_TOMORROW_FONTS[_size_tier(target_w, target_h)]
+    title_font = ImageFont.load_default(size=title_size)
+    body_font = ImageFont.load_default(size=body_size)
+    weather_font = ImageFont.load_default(size=weather_size)
+
+    start_day = datetime.now(tz).date() + timedelta(days=browse_offset)
+    section_h = target_h // 2
+    owners_seen: list[str] = []
+    for i in range(2):
+        section_y0 = i * section_h
+        if i > 0:
+            draw.line([(MARGIN, section_y0), (target_w - MARGIN, section_y0)], fill=RULE)
+        _draw_agenda_day(img, draw, start_day + timedelta(days=i), events, tz,
+                         (0, section_y0, target_w, section_h), title_font, body_font, owners_seen,
+                         palette_rgb, weather_cities, weather_font, weather_units)
+
+    return img
+
+
+# Vertical layout's base (title, body, weather) sizes, before the
+# per-day-count reduction below -- same three tiers as every other view.
+_WEEK_VERTICAL_FONTS = {"large": (26, 18, 16), "medium": (20, 15, 13), "small": (16, 12, 10)}
+# Horizontal layout's (header, chip, weather) sizes.
+_WEEK_HORIZONTAL_FONTS = {"large": (18, 14, 12), "medium": (14, 12, 10), "small": (11, 10, 8)}
+
+
+def _build_week(events: list[dict], browse_offset: int, target_w: int, target_h: int, tz: ZoneInfo,
+                week_start: int, palette_rgb: list | None = None,
+                weather_cities: list[dict] | None = None, weather_units: str = "fahrenheit",
+                days: int = 7, layout: str = "horizontal",
+                start_offset: int = 0) -> Image.Image:
+    """`days` (2-10, see routers/api_widgets.py's clamp) side-by-side
+    columns (layout="horizontal", the original fixed-at-7 behavior
+    generalized) or stacked bands (layout="vertical", reusing
+    _draw_agenda_day the same way _build_today_tomorrow does, just for
+    an arbitrary day count instead of a hardcoded 2).
+
+    At the default 7 days, the view anchors to week_start (a fixed
+    weekday, "start on the most recent Monday") exactly like before --
+    otherwise "start of the week" doesn't mean much for an arbitrary day
+    count, so it instead starts `start_offset` days from today (0 =
+    today, see routers/api_widgets.py's api_widget_config_save)."""
+    img = Image.new("RGB", (target_w, target_h), BG)
+    draw = ImageDraw.Draw(img)
+    tier = _size_tier(target_w, target_h)
+
+    today = datetime.now(tz).date()
+    if days == 7:
+        days_since_start = (today.weekday() - week_start) % 7
+        week_first_day = today - timedelta(days=days_since_start) + timedelta(days=days * browse_offset)
+    else:
+        week_first_day = today + timedelta(days=start_offset) + timedelta(days=days * browse_offset)
+    owners_seen: list[str] = []
+
+    if layout == "vertical":
+        title_base, body_base, weather_base = _WEEK_VERTICAL_FONTS[tier]
+        title_font = ImageFont.load_default(size=max(14, title_base - days))
+        body_font = ImageFont.load_default(size=max(11, body_base - days))
+        weather_font = ImageFont.load_default(size=max(9, weather_base - days))
+        section_h = target_h // days
+        for i in range(days):
+            section_y0 = i * section_h
+            if i > 0:
+                draw.line([(MARGIN, section_y0), (target_w - MARGIN, section_y0)], fill=RULE)
+            day = week_first_day + timedelta(days=i)
+            _draw_agenda_day(img, draw, day, events, tz, (0, section_y0, target_w, section_h),
+                             title_font, body_font, owners_seen, palette_rgb,
+                             weather_cities, weather_font, weather_units)
+        return img
+
+    header_size, chip_size, weather_size = _WEEK_HORIZONTAL_FONTS[tier]
+    header_font = ImageFont.load_default(size=header_size)
+    chip_font = ImageFont.load_default(size=chip_size)
+    weather_font = ImageFont.load_default(size=weather_size)
+    col_w = (target_w - MARGIN * 2) // days
+    header_h = 44
+
+    for col in range(days):
+        day = week_first_day + timedelta(days=col)
+        x0 = MARGIN + col * col_w
+        if col > 0:
+            draw.line([(x0, MARGIN), (x0, target_h - MARGIN)], fill=RULE)
+        label = day.strftime("%a %-d") if day != today else f"* {day.strftime('%a %-d')}"
+        draw_text(img, (x0 + 6, MARGIN), _truncate_to_width(draw, label, header_font, col_w - 10), header_font)
+
+        y = MARGIN + header_h
+        # Columns are narrow, so only what actually fits gets drawn (see
+        # weather_render.draw_weather_row) -- typically one city, no label
+        # (the column itself makes which day it's for obvious; a city name
+        # wouldn't fit anyway). Never more than that -- this is already
+        # the tight view.
+        weather_entries = _weather_for_day(weather_cities, day)
+        if weather_entries:
+            y += draw_weather_row(img, draw, x0 + 4, y, col_w - 8, weather_entries,
+                                  icon_r=8, font=weather_font, units=weather_units, show_labels=False,
+                                  palette_rgb=palette_rgb)
+        row_h = chip_font.size + 10
+        max_rows = max(0, (target_h - MARGIN - y) // row_h)
+        day_events = _events_on_day(events, day, tz)
+        for i, event in enumerate(day_events):
+            if i >= max_rows:
+                draw_text(img, (x0 + 6, y), f"+{len(day_events) - max_rows}", chip_font, MUTED)
+                break
+            colors = _event_colors(event, owners_seen, palette_rgb)
+            _draw_color_bar(draw, x0 + 4, y + 1, x0 + 11, y + row_h - 5, colors, radius=2)
+            if event["all_day"]:
+                _draw_mixed_line(img, draw, (x0 + 16, y), event["summary"], chip_font, col_w - 20)
+            else:
+                prefix = f"{_fmt_time(_event_start(event, tz))[:-3]} "
+                draw_text(img, (x0 + 16, y), prefix, chip_font)
+                prefix_w = draw.textlength(prefix, font=chip_font)
+                _draw_mixed_line(img, draw, (x0 + 16 + prefix_w, y), event["summary"],
+                                 chip_font, col_w - 20 - prefix_w)
+            y += row_h
+
+    return img
+
+
+# Only "large"/"medium" in practice -- _build falls back to agenda view
+# below the "small" tier (see _month_view_fits) -- but keyed defensively
+# by tier rather than a bare bool so a future tier addition can't
+# silently fall through to a KeyError here.
+_MONTH_FONTS = {"large": (16, 18), "medium": (12, 13), "small": (12, 13)}
+
+
+def _build_month(events: list[dict], browse_offset: int, target_w: int, target_h: int, tz: ZoneInfo,
+                 week_start: int, palette_rgb: list | None = None) -> Image.Image:
+    """Density dots per day, not literal event text -- real text at
+    typical month-cell size (~100x70px) is close to unreadable on a
+    6-color dithered e-ink panel. Capped at 4 visible dots, "+N" beyond."""
+    img = Image.new("RGB", (target_w, target_h), BG)
+    draw = ImageDraw.Draw(img)
+
+    header_size, day_size = _MONTH_FONTS[_size_tier(target_w, target_h)]
+    header_font = ImageFont.load_default(size=header_size)
+    day_font = ImageFont.load_default(size=day_size)
+
+    today = datetime.now(tz).date()
+    target_month = _add_months(date(today.year, today.month, 1), browse_offset)
+    weeks = list(calendar_module.Calendar(firstweekday=week_start).monthdatescalendar(target_month.year, target_month.month))
+
+    col_w = (target_w - MARGIN * 2) // 7
+    header_h = 28
+    grid_top = MARGIN + header_h
+    row_h = (target_h - MARGIN - grid_top) // len(weeks)
+
+    day_names = WEEKDAY_NAMES[week_start:] + WEEKDAY_NAMES[:week_start]
+    for col, name in enumerate(day_names):
+        draw_text(img, (MARGIN + col * col_w + 6, MARGIN), name[:3], header_font, MUTED)
+
+    owners_seen: list[str] = []
+    dot_r = 6
+    for row, week in enumerate(weeks):
+        for col, day in enumerate(week):
+            x0 = MARGIN + col * col_w
+            y0 = grid_top + row * row_h
+            draw.rectangle([x0, y0, x0 + col_w, y0 + row_h], outline=RULE)
+            in_month = day.month == target_month.month
+            text_color = FG if in_month else MUTED
+            if day == today:
+                draw.rectangle([x0 + 2, y0 + 2, x0 + 24, y0 + 20], outline=FG)
+            draw_text(img, (x0 + 6, y0 + 4), str(day.day), day_font, text_color)
+
+            day_events = _events_on_day(events, day, tz)
+            dot_x = x0 + 8
+            dot_y = y0 + row_h - dot_r * 2 - 6
+            for i, event in enumerate(day_events[:4]):
+                # First contributing calendar's color only, even for a
+                # deduplicated shared event -- month view is density
+                # dots, not a place to also show which calendars a
+                # shared event came from (see _event_colors).
+                event_color = _event_colors(event, owners_seen, palette_rgb)[0]
+                draw.ellipse([dot_x, dot_y, dot_x + dot_r * 2, dot_y + dot_r * 2], fill=event_color)
+                dot_x += dot_r * 2 + 5
+            if len(day_events) > 4:
+                draw_text(img, (dot_x, dot_y - 2), f"+{len(day_events) - 4}", header_font, MUTED)
+
+    return img
+
+
+_BUILDERS = {"agenda": _build_agenda, "today_tomorrow": _build_today_tomorrow, "week": _build_week,
+            "month": _build_month}
+
+
+def _build(events: list[dict], view: str, browse_offset: int, target_w: int, target_h: int, timezone: str,
+          fetch_summary: str, week_start: int, palette_rgb: list | None = None,
+          weather_cities: list[dict] | None = None, weather_units: str = "fahrenheit",
+          week_days: int = 7, week_layout: str = "horizontal",
+          week_start_offset: int = 0) -> Image.Image:
+    tz = ZoneInfo(timezone) if timezone else ZoneInfo("UTC")
+    effective_view = view
+    if view == "month" and not _month_view_fits(target_w, target_h):
+        effective_view = "agenda"
+
+    if effective_view == "agenda":
+        img = _build_agenda(events, browse_offset, target_w, target_h, tz, palette_rgb,
+                            weather_cities, weather_units)
+    elif effective_view == "today_tomorrow":
+        img = _build_today_tomorrow(events, browse_offset, target_w, target_h, tz, palette_rgb,
+                                    weather_cities, weather_units)
+    elif effective_view == "week":
+        img = _build_week(events, browse_offset, target_w, target_h, tz, week_start, palette_rgb,
+                          weather_cities, weather_units, week_days, week_layout, week_start_offset)
+    elif effective_view == "month":
+        # Never given weather -- no room for it at typical month-cell
+        # size, same reasoning that already keeps this view to density
+        # dots instead of literal event text (see _build_month's own
+        # docstring). Colors are still passed through, though -- that's
+        # a different concern (legibility of individual events) than
+        # needing a whole extra strip of content.
+        img = _build_month(events, browse_offset, target_w, target_h, tz, week_start, palette_rgb)
+    else:
+        img = _build_agenda(events, browse_offset, target_w, target_h, tz, palette_rgb,
+                            weather_cities, weather_units)
+
+    if fetch_summary:
+        font = ImageFont.load_default(size=14 if _size_tier(target_w, target_h) != "small" else 11)
+        draw_text(img, (MARGIN, target_h - MARGIN - font.size), fetch_summary, font, MUTED)
+
+    return img
+
+
+def render_calendar(events: list[dict], view: str, browse_offset: int, orientation: str,
+                    palette_rgb: list | None, timezone: str,
+                    fetch_summary: str = "", manage: dict | None = None, week_start: int = 0,
+                    weather_cities: list[dict] | None = None, weather_units: str = "fahrenheit",
+                    week_days: int = 7, week_layout: str = "horizontal",
+                    week_start_offset: int = 0) -> bytes:
+    """Renders one of CALENDAR_VIEWS full-panel to the panel's packed
+    format. Always returns exactly EPD_WIDTH*EPD_HEIGHT/2 bytes, same
+    invariant every other renderer honors. weather_cities is
+    routers/common.py's get_or_refresh_weather() cache, or None/[] to
+    omit the weather strip entirely (also always omitted for view ==
+    "month")."""
+    target_w, target_h = logical_render_size(orientation)
+    img = _build(events, view, browse_offset, target_w, target_h, timezone, fetch_summary, week_start,
+                palette_rgb, weather_cities, weather_units, week_days, week_layout, week_start_offset)
+    img = _apply_manage_overlay(img, manage)
+    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
+    return _transpose_and_pack(quantized, orientation)
+
+
+def render_calendar_preview_png(events: list[dict], view: str, browse_offset: int, orientation: str,
+                                palette_rgb: list | None, timezone: str,
+                                fetch_summary: str = "", manage: dict | None = None, week_start: int = 0,
+                                weather_cities: list[dict] | None = None, weather_units: str = "fahrenheit",
+                                week_days: int = 7, week_layout: str = "horizontal",
+                                week_start_offset: int = 0) -> bytes:
+    """Same pipeline as render_calendar, but a normal browser-viewable
+    PNG in logical (upright) orientation -- mirrors
+    image_pipeline.render_preview_png's relationship to render_frame."""
+    target_w, target_h = logical_render_size(orientation)
+    img = _build(events, view, browse_offset, target_w, target_h, timezone, fetch_summary, week_start,
+                palette_rgb, weather_cities, weather_units, week_days, week_layout, week_start_offset)
+    img = _apply_manage_overlay(img, manage)
+    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
+    buf = io.BytesIO()
+    quantized.convert("RGB").save(buf, format="PNG")
+    return buf.getvalue()
+
+
+# --- Standalone tasks widget (split out of the old calendar-widget-only
+# week-view task list -- see models.TaskWidgetConfig) -----------------
+
+_TASKS_FONTS = {"large": (24, 18), "medium": (20, 16), "small": (16, 13)}
+
+
+def _build_tasks(tasks: list[dict], target_w: int, target_h: int, palette_rgb: list | None = None,
+                 title: str = "Tasks") -> Image.Image:
+    """A tasks widget's entire region is the checklist -- unlike the old
+    week-view slot, there's no day columns/header to share space with,
+    so this is just _draw_tasks over the whole box."""
+    img = Image.new("RGB", (target_w, target_h), BG)
+    draw = ImageDraw.Draw(img)
+    title_size, body_size = _TASKS_FONTS[_size_tier(target_w, target_h)]
+    title_font = ImageFont.load_default(size=title_size)
+    body_font = ImageFont.load_default(size=body_size)
+    _draw_tasks(img, draw, (0, 0, target_w, target_h), tasks, title_font, body_font, palette_rgb, title)
+    return img
+
+
+def render_tasks(tasks: list[dict], orientation: str, palette_rgb: list | None,
+                 manage: dict | None = None, title: str = "Tasks") -> bytes:
+    """Renders the tasks widget full-panel to the panel's packed format.
+    Always returns exactly EPD_WIDTH*EPD_HEIGHT/2 bytes, same invariant
+    every other renderer honors."""
+    target_w, target_h = logical_render_size(orientation)
+    img = _build_tasks(tasks, target_w, target_h, palette_rgb, title)
+    img = _apply_manage_overlay(img, manage)
+    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
+    return _transpose_and_pack(quantized, orientation)
+
+
+def render_tasks_preview_png(tasks: list[dict], orientation: str, palette_rgb: list | None,
+                             manage: dict | None = None, title: str = "Tasks") -> bytes:
+    """Same pipeline as render_tasks, but a normal browser-viewable PNG
+    in logical (upright) orientation -- mirrors render_calendar_preview_
+    png's relationship to render_calendar."""
+    target_w, target_h = logical_render_size(orientation)
+    img = _build_tasks(tasks, target_w, target_h, palette_rgb, title)
+    img = _apply_manage_overlay(img, manage)
+    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
+    buf = io.BytesIO()
+    quantized.convert("RGB").save(buf, format="PNG")
+    return buf.getvalue()

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,118 @@
+"""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 WIDGET_CONFIG_MODELS, Frame, Widget
+
+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()
+
+
+@contextmanager
+def widget_locked(db: Session, frame_id: int, widget_id: int) -> Iterator[tuple[Frame, Widget, object]]:
+    """Same lock/refresh/commit dance as frame_locked, additionally
+    resolving and refreshing the widget's own per-type config row
+    (PhotoWidgetConfig/CalendarWidgetConfig/WhiteboardWidgetConfig/
+    TaskWidgetConfig, see models.WIDGET_CONFIG_MODELS). Deliberately
+    still locks at *frame* granularity -- the exact same per-frame
+    threading.Lock frame_locked
+    uses, not a separate per-widget lock -- simplest, avoids a new class
+    of multi-lock deadlock bugs, and this project's actual concurrency
+    needs are tiny (a handful of users per household frame).
+
+    threading.Lock is not reentrant: a caller executing several widget
+    actions in one pass (e.g. a button press assigned multiple
+    (widget, action) pairs, see routers/device.py) MUST call this once
+    per action, sequentially, never nested inside an outer
+    frame_locked/widget_locked span for the same frame -- nesting would
+    deadlock instantly, not just misbehave."""
+    with frame_locked(db, frame_id) as frame:
+        widget = db.get(Widget, widget_id)
+        if widget is None or widget.frame_id != frame_id:
+            raise LookupError(f"Widget {widget_id} does not belong to frame {frame_id}")
+        config_model = WIDGET_CONFIG_MODELS[widget.widget_type]
+        config = db.get(config_model, widget_id)
+        if config is None:
+            raise LookupError(f"Widget {widget_id} has no {widget.widget_type} config row")
+        db.refresh(config)
+        yield frame, widget, config

server/app/face_labels.py

@@ -1,6 +1,6 @@
 """Maps named faces (from Immich's own face recognition/People feature)
-onto their position in the final rendered 800x480 frame, for the
-manage-button overlay's escalated "who's in this photo" menu level.
+onto their position in the final rendered frame, for the manage-button
+overlay's named-face labels (see manage_overlay.py, which draws them).
 
 No face detection or recognition happens here or anywhere else in this
 project -- Immich's GET /api/faces?id={assetId} already returns each
@@ -15,71 +15,80 @@ import io
 
 from PIL import Image, ImageOps
 
-from .image_pipeline import (
-    _face_aware_crop_box,
-    _plain_center_crop_box,
-    logical_render_size,
-    logical_to_native,
-)
+from .image_pipeline import _has_bounding_box, _placement_transform, logical_render_size
 
-# Small caps, not arbitrary: each label is its own malloc'd overlay
-# buffer on the device (see firmware/main/manage_qr_overlay.c), and the
-# four existing fixed corner regions already use a meaningful chunk of
-# the ESP32-C6's limited RAM. Capping at 4 short names keeps the total
-# overlay memory budget well clear of the WiFi/HTTP stack's own needs.
-MAX_LABELED_FACES = 4
-NAME_MAX_LEN = 10
+# Not a memory constraint anymore (the overlay renders server-side now,
+# not malloc'd per-label on the device) -- purely a legibility cap. A
+# photo with a dozen named people would just be visual clutter regardless
+# of what's rendering it.
+MAX_LABELED_FACES = 6
 
 
-def compute_face_labels(preview_bytes: bytes, faces: list[dict], smart_crop_faces: bool,
-                        orientation: str = "landscape") -> list[dict]:
-    """Returns up to MAX_LABELED_FACES [{"name", "x", "y"}], x/y in native
-    800x480 panel pixel space at each named face's bottom-center point.
+def compute_face_labels(preview_bytes: bytes, faces: list[dict], display_mode: str,
+                        orientation: str = "landscape", region: tuple[int, int, int, int] | None = None) -> list[dict]:
+    """Returns up to MAX_LABELED_FACES [{"name", "x", "y"}], x/y in
+    logical (pre-rotation) frame space at each named face's bottom-center
+    point -- manage_overlay.compose() draws these directly onto the
+    logical-space image before it's rotated into native panel space, so
+    no rotation happens here (contrast with the old firmware-side
+    version, which drew post-rotation and needed logical_to_native).
     Faces without an Immich-identified person name are skipped entirely.
     preview_bytes must be the same preview image render_frame() used for
-    the currently-displayed frame, and smart_crop_faces/orientation must
-    match the settings that were active then -- otherwise the crop box and
-    rotation computed here won't match what's actually on screen.
+    the currently-displayed frame, and display_mode/orientation must
+    match the settings that were active then -- otherwise the placement
+    computed here won't match what's actually on screen.
 
-    The crop math runs in logical (pre-rotation) space, matching
-    render_frame()'s composition step; each anchor is then rotated into
-    native panel coordinates via logical_to_native(), since the firmware
-    draws labels in native space.
+    `region` is (x0, y0, w, h): where in the logical canvas the photo
+    actually landed, if not the whole thing -- e.g. a photo widget placed
+    in one corner of the panel rather than full-screen (see
+    routers/common.py's build_manage_content, which passes each photo
+    widget's own placement rect) -- without this a label would be placed
+    as if the photo filled the entire canvas, landing well off where the
+    widget actually is. None (the default) means the photo fills the
+    whole logical canvas.
+
+    The placement math matches render_frame()'s own composition step
+    exactly (see image_pipeline._placement_transform, shared so the two
+    can't drift apart).
     """
     named = [face for face in faces if (face.get("person") or {}).get("name")]
     if not named:
         return []
 
-    logical_w, logical_h = logical_render_size(orientation)
+    if region is None:
+        logical_w, logical_h = logical_render_size(orientation)
+        region_x0, region_y0, target_w, target_h = 0, 0, logical_w, logical_h
+    else:
+        region_x0, region_y0, target_w, target_h = region
+
     fitted = ImageOps.exif_transpose(Image.open(io.BytesIO(preview_bytes)).convert("RGB"))
 
-    if smart_crop_faces and faces:
-        left, top, right, bottom = _face_aware_crop_box(fitted.width, fitted.height, logical_w, logical_h, faces)
-        crop_w, crop_h = right - left, bottom - top
-    else:
-        left, top, crop_w, crop_h = _plain_center_crop_box(fitted.width, fitted.height, logical_w, logical_h)
+    scale_x, scale_y, offset_x, offset_y = _placement_transform(
+        fitted.width, fitted.height, target_w, target_h, display_mode, faces
+    )
 
     labels = []
     for face in named[:MAX_LABELED_FACES]:
+        if not _has_bounding_box(face):
+            continue
         face_w = face.get("imageWidth") or fitted.width
         face_h = face.get("imageHeight") or fitted.height
-        scale_x = fitted.width / face_w
-        scale_y = fitted.height / face_h
+        img_scale_x = fitted.width / face_w
+        img_scale_y = fitted.height / face_h
 
-        center_x = (face["boundingBoxX1"] + face["boundingBoxX2"]) / 2 * scale_x
-        bottom_y = face["boundingBoxY2"] * scale_y
+        center_x = (face["boundingBoxX1"] + face["boundingBoxX2"]) / 2 * img_scale_x
+        bottom_y = face["boundingBoxY2"] * img_scale_y
 
-        frame_x = (center_x - left) * (logical_w / crop_w)
-        frame_y = (bottom_y - top) * (logical_h / crop_h)
+        # Relative to the region's own origin first (matches
+        # _placement_transform's target_w/target_h space), then shifted
+        # into full-canvas coordinates.
+        region_x = center_x * scale_x + offset_x
+        region_y = bottom_y * scale_y + offset_y
 
-        if not (0 <= frame_x <= logical_w and 0 <= frame_y <= logical_h):
-            continue  # this face got cropped out of the final frame entirely
+        if not (0 <= region_x <= target_w and 0 <= region_y <= target_h):
+            continue  # this face got cropped out of the region entirely
 
-        name = face["person"]["name"]
-        if len(name) > NAME_MAX_LEN:
-            name = name[: NAME_MAX_LEN - 3] + "..."
-
-        native_x, native_y = logical_to_native(frame_x, frame_y, orientation)
-        labels.append({"name": name, "x": native_x, "y": native_y})
+        labels.append({"name": face["person"]["name"],
+                       "x": int(region_x + region_x0), "y": int(region_y + region_y0)})
 
     return labels

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/fonts/OFL-Arvo.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2010-2013, Anton Koovit ([email protected]), with Reserved Font Name 'Arvo'
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

server/app/fonts/OFL-CrimsonText.txt

@@ -0,0 +1,93 @@
+Copyright 2010 The Crimson Text Project Authors (https://github.com/googlefonts/Crimson)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

server/app/fonts/OFL-IBMPlex.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

server/app/fonts/OFL-Inter.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

server/app/fonts/OFL-SourceSans.txt

@@ -0,0 +1,93 @@
+Copyright 2010-2020 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

server/app/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2013 Google LLC
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

server/app/global_actions.py

@@ -0,0 +1,115 @@
+"""Frame-wide actions triggered by holding NEXT/BACK past
+Frame.hold_duration_ms, instead of the per-widget action a short press
+runs (see models.FrameButtonAction, app/widgets/*.py's ACTIONS). Not
+scoped to any one widget -- e.g. cycling through the owner's saved
+layouts -- so this is its own registry rather than living in a widget
+module.
+
+Each function's signature is (db, frame) -> None, the frame-level
+analogue of a widget ACTIONS entry's (db, frame, widget) -> None, and
+each is responsible for its own locking/commit internally (frame_locked/
+widget_locked), same convention as app/widgets/*.py. routers/device.py's
+/frame/global-next and /frame/global-back look up which (if any) of
+these Frame.next_hold_action/back_hold_action points to and call it,
+same "unset/unknown -> silent no-op" posture as an unbound short-press
+button."""
+
+from __future__ import annotations
+
+import logging
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from . import grid
+from .db import frame_locked
+from .models import Frame, PhotoWidgetConfig, SavedLayout, Widget
+from .routers.api_layouts import apply_layout_to_frame
+from .widgets import WIDGET_TYPES
+
+logger = logging.getLogger(__name__)
+
+
+def cycle_layout(db: Session, frame: Frame) -> None:
+    """Applies the owner's next saved layout compatible with this
+    frame's current grid size, in a stable order (by id), wrapping back
+    to the first past the last one. A silent no-op if the frame is
+    unclaimed or its owner has no compatible saved layouts -- same
+    posture as every other action here when there's nothing to do."""
+    if frame.owner_user_id is None:
+        return
+    cols, rows = grid.grid_dims(frame.orientation)
+    candidates = db.scalars(
+        select(SavedLayout)
+        .where(SavedLayout.user_id == frame.owner_user_id, SavedLayout.cols == cols, SavedLayout.rows == rows)
+        .order_by(SavedLayout.id)
+    ).all()
+    if not candidates:
+        return
+
+    next_layout = candidates[0]
+    if frame.last_cycled_layout_id is not None:
+        for i, layout in enumerate(candidates):
+            if layout.id == frame.last_cycled_layout_id:
+                next_layout = candidates[(i + 1) % len(candidates)]
+                break
+
+    apply_layout_to_frame(db, frame, next_layout)
+    with frame_locked(db, frame.id) as locked:
+        locked.last_cycled_layout_id = next_layout.id
+
+
+def refresh_all_widgets(db: Session, frame: Frame) -> None:
+    """Runs every widget's own check_now (calendar/weather/whiteboard),
+    regardless of which button it's normally bound to -- a manual "sync
+    everything now" global action. One widget's failure doesn't block
+    the rest, same posture as routers/device.py's _run_button_actions."""
+    widgets = db.scalars(select(Widget).where(Widget.frame_id == frame.id)).all()
+    for widget in widgets:
+        module = WIDGET_TYPES.get(widget.widget_type)
+        check_now = module.ACTIONS.get("check_now") if module else None
+        if check_now is None:
+            continue
+        try:
+            check_now(db, frame, widget)
+        except Exception:
+            logger.exception(
+                "refresh_all_widgets failed for widget %d (frame %d)", widget.id, frame.id
+            )
+
+
+def toggle_all_photo_locks(db: Session, frame: Frame) -> None:
+    """Flips PhotoWidgetConfig.locked for every photo widget on the frame
+    at once. Target state is the opposite of "everything's already
+    locked" -- one hold freezes every photo widget unless they're all
+    already frozen, in which case it unfreezes all of them. A no-op if
+    the frame has no photo widgets."""
+    widget_ids = [
+        w.id for w in db.scalars(
+            select(Widget).where(Widget.frame_id == frame.id, Widget.widget_type == "photos")
+        )
+    ]
+    if not widget_ids:
+        return
+    configs = db.scalars(
+        select(PhotoWidgetConfig).where(PhotoWidgetConfig.widget_id.in_(widget_ids))
+    ).all()
+    if not configs:
+        return
+    target = not all(c.locked for c in configs)
+    with frame_locked(db, frame.id):
+        for config in configs:
+            config.locked = target
+
+
+GLOBAL_ACTIONS = {
+    "cycle_layout": cycle_layout,
+    "refresh_all_widgets": refresh_all_widgets,
+    "toggle_all_photo_locks": toggle_all_photo_locks,
+}
+
+GLOBAL_ACTION_LABELS = {
+    "cycle_layout": "Cycle saved layouts",
+    "refresh_all_widgets": "Refresh all widgets now",
+    "toggle_all_photo_locks": "Freeze/unfreeze all photo widgets",
+}

server/app/grid.py

@@ -0,0 +1,113 @@
+"""Snap-to-grid placement math for widgets (see models.Widget) -- pure,
+no I/O, no ORM.
+
+The grid is defined relative to the panel's long/short axis, not
+landscape/portrait specifically, so it stays valid across
+image_pipeline.logical_render_size(orientation)'s genuine width/height
+swap for portrait (not just a rotation applied at the very end) --
+landscape orientations are GRID_LONG columns x GRID_SHORT rows, portrait
+orientations are GRID_SHORT columns x GRID_LONG rows, same cell size
+either way. Changing a frame's orientation therefore invalidates any
+existing widget layout (an 8x5 arrangement isn't valid on a 5x8 grid) --
+callers are expected to reset to one full-panel widget on an orientation
+change, not try to remap coordinates.
+"""
+
+from __future__ import annotations
+
+GRID_LONG = 8
+GRID_SHORT = 5
+
+# Per-widget-type minimum grid footprint (cols, rows) -- enforced both in
+# the placement UI and server-side (routers/api_widgets.py). A calendar
+# widget crammed into 1x1 would be illegible regardless of size-tier
+# scaling (see calendar_render.py); whiteboard needs enough room to be
+# worth looking at; photos can go as small as a single cell; tasks needs
+# enough width for a due-date prefix plus a couple words of summary
+# without truncating on every row; weather needs enough room for its
+# hourly/daily strips to stay legible (its current/multi_city modes
+# would tolerate smaller, but every mode shares one footprint value).
+# battery is just an icon + a percent (+ two optional small lines in
+# "detailed" mode) -- legible even at a single cell, like photos/static.
+# NOTE: a 1x1 widget-box on a narrow mobile canvas can clip its own
+# gear/remove buttons behind theme.css's overflow: hidden (their fixed
+# pixel offsets overflow the box's clipped width) -- a pre-existing
+# layout gap that already affects photos/static at 1x1 too, not fixed
+# here; see the finding called out where this was discovered.
+MIN_FOOTPRINT: dict[str, tuple[int, int]] = {
+    "photos": (1, 1),
+    "calendar": (3, 2),
+    "whiteboard": (2, 2),
+    "tasks": (2, 2),
+    "static": (1, 1),
+    "text": (2, 1),
+    "weather": (2, 2),
+    "battery": (1, 1),
+}
+
+Rect = tuple[int, int, int, int]  # (x, y, w, h)
+
+
+def grid_dims(orientation: str) -> tuple[int, int]:
+    """(cols, rows) for this orientation."""
+    if orientation in ("portrait", "portrait_flipped"):
+        return GRID_SHORT, GRID_LONG
+    return GRID_LONG, GRID_SHORT
+
+
+def full_panel_rect(orientation: str) -> Rect:
+    """The single full-panel widget rect for this orientation -- what a
+    frame gets reset to whenever its layout can't carry over (initial
+    migration backfill, an orientation change)."""
+    cols, rows = grid_dims(orientation)
+    return (0, 0, cols, rows)
+
+
+def in_bounds(orientation: str, rect: Rect) -> bool:
+    cols, rows = grid_dims(orientation)
+    x, y, w, h = rect
+    return x >= 0 and y >= 0 and w > 0 and h > 0 and x + w <= cols and y + h <= rows
+
+
+def meets_minimum(widget_type: str, rect: Rect) -> bool:
+    min_w, min_h = MIN_FOOTPRINT.get(widget_type, (1, 1))
+    _, _, w, h = rect
+    return w >= min_w and h >= min_h
+
+
+def overlaps(a: Rect, b: Rect) -> bool:
+    ax, ay, aw, ah = a
+    bx, by, bw, bh = b
+    return ax < bx + bw and bx < ax + aw and ay < by + bh and by < ay + ah
+
+
+def find_open_rect(orientation: str, existing: list[Rect], w: int, h: int) -> Rect | None:
+    """First w x h rect that's in-bounds and doesn't overlap any of
+    `existing`, scanning row-major (top-left first) -- used when creating
+    a widget without an explicit placement (see routers/api_widgets.py),
+    so adding one from a type picker doesn't require the caller to find
+    empty space itself first. None if no such rect fits anywhere."""
+    cols, rows = grid_dims(orientation)
+    for y in range(rows - h + 1):
+        for x in range(cols - w + 1):
+            candidate = (x, y, w, h)
+            if not any(overlaps(candidate, other) for other in existing):
+                return candidate
+    return None
+
+
+def cell_to_pixels(orientation: str, panel_w: int, panel_h: int, rect: Rect) -> tuple[int, int, int, int]:
+    """Grid rect -> pixel rect in logical (pre-rotation) canvas space --
+    against image_pipeline.logical_render_size(orientation)'s own
+    (panel_w, panel_h), the same space every renderer already composes
+    in before the final orientation transpose."""
+    cols, rows = grid_dims(orientation)
+    cell_w = panel_w / cols
+    cell_h = panel_h / rows
+    x, y, w, h = rect
+    px, py = round(x * cell_w), round(y * cell_h)
+    # Snap the far edge to the next cell boundary rather than compounding
+    # per-cell rounding error across w/h -- keeps adjacent widgets'
+    # shared edge pixel-exact instead of leaving a stray gap/overlap.
+    px2, py2 = round((x + w) * cell_w), round((y + h) * cell_h)
+    return (px, py, px2 - px, py2 - py)

server/app/image_pipeline.py

@@ -2,11 +2,114 @@
 
 from __future__ import annotations
 
-from PIL import Image, ImageOps
+import io
+import math
+
+from PIL import Image, ImageDraw, ImageEnhance, ImageFont, ImageOps
 
 EPD_WIDTH = 800
 EPD_HEIGHT = 480
 
+# PIL's TrueType rendering antialiases by default (graduated gray edge
+# pixels). Those survive straight into _quantize's Floyd-Steinberg
+# dithering, which -- confirmed visually -- turns them into scattered
+# colored speckles along every glyph edge once forced onto the panel's 6
+# colors, since a mid-gray input has no close palette match and the
+# diffused error bounces between whichever colors are nearest. Drawing
+# through a thresholded bilevel mask instead keeps every edge pure
+# black/white, which _quantize then reproduces exactly (both are already
+# palette colors, nothing to dither). Shared by every module that draws
+# text before quantization (this file's render_placeholder,
+# calendar_render.py, manage_overlay.py).
+_TEXT_MASK_THRESHOLD = 110
+
+
+def draw_text(img: Image.Image, xy: tuple[int, int], text: str, font: ImageFont.ImageFont,
+              fill: tuple[int, int, int] = (0, 0, 0)) -> None:
+    bbox = font.getbbox(text)
+    w, h = max(1, bbox[2] - bbox[0]), max(1, bbox[3] - bbox[1])
+    mask = Image.new("L", (w, h), 0)
+    ImageDraw.Draw(mask).text((-bbox[0], -bbox[1]), text, fill=255, font=font)
+    mask = mask.point(lambda p: 255 if p > _TEXT_MASK_THRESHOLD else 0)
+    img.paste(fill, (xy[0] + bbox[0], xy[1] + bbox[1]), mask)
+
+
+def _dashed_edge(draw: ImageDraw.ImageDraw, x0: float, y0: float, x1: float, y1: float,
+                 width: int, color: tuple[int, int, int], dash: float, gap: float) -> None:
+    length = math.hypot(x1 - x0, y1 - y0)
+    if length <= 0:
+        return
+    ux, uy = (x1 - x0) / length, (y1 - y0) / length
+    pos = 0.0
+    while pos < length:
+        end = min(pos + dash, length)
+        draw.line([(x0 + ux * pos, y0 + uy * pos), (x0 + ux * end, y0 + uy * end)], fill=color, width=width)
+        pos += dash + gap
+
+
+def _dotted_edge(draw: ImageDraw.ImageDraw, x0: float, y0: float, x1: float, y1: float,
+                 width: int, color: tuple[int, int, int], spacing: float) -> None:
+    length = math.hypot(x1 - x0, y1 - y0)
+    if length <= 0:
+        return
+    ux, uy = (x1 - x0) / length, (y1 - y0) / length
+    r = max(1, width / 2)
+    pos = 0.0
+    while pos <= length:
+        cx, cy = x0 + ux * pos, y0 + uy * pos
+        draw.ellipse([cx - r, cy - r, cx + r, cy + r], fill=color)
+        pos += spacing
+
+
+def draw_widget_border(img: Image.Image, style: str, thickness: int, color: tuple[int, int, int]) -> None:
+    """Draws a border inset within img's own bounds, mutating it in
+    place -- called once per widget's own region (routers/device.py's
+    _render_widgets, and each widget type's own dialog preview) before
+    that region's image is pasted onto the shared canvas, so a border
+    never straddles the boundary between two adjacent widgets. `color`
+    should already be an exact palette RGB (see resolve_border_color) so
+    the stroke quantizes with zero dithering error, same reasoning as
+    the weather/battery icons' exact-panel-ink-RGB fills.
+
+    "solid"/"dashed"/"dotted" are a single thickness-px stroke traced
+    just inside the image's edge; "fancy" is two thinner concentric
+    strokes with a gap between them, picture-frame-mat style. "none" (or
+    a non-positive thickness) draws nothing."""
+    if style == "none" or thickness <= 0:
+        return
+    w, h = img.size
+    t = max(1, min(int(thickness), min(w, h) // 2))
+    draw = ImageDraw.Draw(img)
+
+    if style == "fancy":
+        line_t = max(1, t // 3)
+        gap = max(2, t - 2 * line_t)
+        draw.rectangle([0, 0, w - 1, h - 1], outline=color, width=line_t)
+        inset = line_t + gap
+        if w - 2 * inset > 1 and h - 2 * inset > 1:
+            draw.rectangle([inset, inset, w - 1 - inset, h - 1 - inset], outline=color, width=line_t)
+        return
+
+    if style == "solid":
+        draw.rectangle([0, 0, w - 1, h - 1], outline=color, width=t)
+        return
+
+    # dashed/dotted trace the same centered-on-the-edge path solid/
+    # fancy's rectangle outline draws, so all four styles sit at the
+    # same inset regardless of which is chosen.
+    half = t / 2
+    x0, y0, x1, y1 = half, half, w - 1 - half, h - 1 - half
+    edges = [(x0, y0, x1, y0), (x1, y0, x1, y1), (x1, y1, x0, y1), (x0, y1, x0, y0)]
+    if style == "dashed":
+        dash, gap = t * 3, t * 2
+        for ex0, ey0, ex1, ey1 in edges:
+            _dashed_edge(draw, ex0, ey0, ex1, ey1, t, color, dash, gap)
+    elif style == "dotted":
+        spacing = max(t * 2, t + 4)
+        for ex0, ey0, ex1, ey1 in edges:
+            _dotted_edge(draw, ex0, ey0, ex1, ey1, t, color, spacing)
+
+
 # How each orientation maps the logically-composed image onto the native
 # 800x480 panel. "portrait"/"portrait_flipped" compose at 480x800 (so the
 # crop ratio matches how the frame actually hangs) and rotate into native
@@ -45,39 +148,86 @@ def logical_to_native(x: float, y: float, orientation: str) -> tuple[int, int]:
         return int(logical_h - 1 - y), int(x)
     return int(x), int(y)
 
-# Approximate sRGB for each of the panel's 6 ink colors. These are
-# reasonable placeholders, not measured values -- Waveshare doesn't publish
-# exact color primaries for this panel. Tune them once you can compare a
-# rendered test image against the real panel.
-PALETTE_RGB = [
-    # (0, 0, 0),  # BLACK
-    # (255, 255, 255),  # WHITE
-    # (255, 219, 0),  # YELLOW
-    # (207, 0, 15),  # RED
-    # (0, 39, 133),  # BLUE
-    # (0, 133, 55),  # GREEN
-    (0, 0, 0),
-    (255, 255, 255),
-    (255, 243, 56),
-    (191, 0, 0),
-    (100, 64, 255),
-    (67, 138, 28)
+# Approximate sRGB for each of the panel's 6 ink colors -- reasonable
+# placeholders, not measured values (Waveshare doesn't publish exact
+# color primaries for this panel). This is the fallback for any frame
+# that hasn't tuned its own (Frame.palette_rgb, set from a frame's
+# Configuration tab -- "Advanced configuration" -- once you can compare
+# a rendered test image against the real panel; different panel units
+# can vary enough to be worth calibrating per frame).
+DEFAULT_PALETTE_RGB = [
+    (0, 0, 0),  # BLACK
+    (255, 255, 255),  # WHITE
+    (255, 219, 0),  # YELLOW
+    (207, 0, 15),  # RED
+    (0, 39, 133),  # BLUE
+    (0, 133, 55),  # GREEN
 ]
 
+PALETTE_LABELS = ["Black", "White", "Yellow", "Red", "Blue", "Green"]
+
 # The panel's actual 4-bit color codes (see firmware/components/epd7in3e),
-# in the same order as PALETTE_RGB. 0x4 is intentionally unused upstream.
+# in the same order as DEFAULT_PALETTE_RGB/PALETTE_LABELS -- fixed by the
+# hardware protocol, never user-configurable. 0x4 is intentionally unused
+# upstream.
 PANEL_CODES = [0x0, 0x1, 0x2, 0x3, 0x5, 0x6]
 
+# Per-widget optional border (models.Widget.border_style, see
+# draw_widget_border below). "none" is the default/no-op; the rest are
+# thickness-px strokes inset within the widget's own region.
+BORDER_STYLES = ["none", "solid", "dashed", "dotted", "fancy"]
+BORDER_STYLE_LABELS = {
+    "none": "None",
+    "solid": "Solid",
+    "dashed": "Dashed",
+    "dotted": "Dotted",
+    "fancy": "Fancy (double line)",
+}
+MIN_BORDER_THICKNESS = 1
+MAX_BORDER_THICKNESS = 8
+DEFAULT_BORDER_THICKNESS = 3
 
-def _build_palette_image() -> Image.Image:
+
+def palette_to_hex(palette_rgb: list) -> list[str]:
+    """[(0,0,0), ...] -> ["#000000", ...], for pre-filling the Advanced
+    configuration color pickers."""
+    return ["#%02x%02x%02x" % tuple(c) for c in palette_rgb]
+
+
+def resolve_border_color(color_index: int, palette_rgb: list | None) -> tuple[int, int, int]:
+    """Widget.border_color_index -> an actual RGB tuple, against this
+    frame's tuned palette if it has one (falls back to
+    DEFAULT_PALETTE_RGB) -- so a border always renders as one of the
+    panel's real 6 ink colors and never needs to be dithered, same
+    reasoning as the weather/battery icons' exact-panel-ink-RGB fills
+    (see docs/widgets.md). Out-of-range indexes (a stale value from a
+    frame that used to have more colors, though that never happens
+    today) fall back to Black rather than raising."""
+    palette = palette_rgb or DEFAULT_PALETTE_RGB
+    if 0 <= color_index < len(palette):
+        return tuple(palette[color_index])
+    return tuple(palette[0])
+
+
+def hex_to_rgb(hex_str: str) -> tuple[int, int, int] | None:
+    """"#1a2b3c" -> (26, 43, 60), or None for anything that isn't exactly
+    a 6-hex-digit color (what <input type="color"> always sends, but a
+    direct API call might not)."""
+    hex_str = hex_str.strip().lstrip("#")
+    if len(hex_str) != 6:
+        return None
+    try:
+        return (int(hex_str[0:2], 16), int(hex_str[2:4], 16), int(hex_str[4:6], 16))
+    except ValueError:
+        return None
+
+
+def _build_palette_image(palette_rgb: list) -> Image.Image:
     pal_img = Image.new("P", (1, 1))
-    pal_img.putpalette([channel for rgb in PALETTE_RGB for channel in rgb])
+    pal_img.putpalette([channel for rgb in palette_rgb for channel in rgb])
     return pal_img
 
 
-_PALETTE_IMAGE = _build_palette_image()
-
-
 def _plain_center_crop_box(
     img_width: int, img_height: int, target_width: int, target_height: int
 ) -> tuple[float, float, int, int]:
@@ -99,6 +249,16 @@ def _plain_center_crop_box(
     return left, top, crop_w, crop_h
 
 
+def _has_bounding_box(face: dict) -> bool:
+    """Immich has occasionally been observed to return a face entry with
+    a still-pending or otherwise incomplete bounding box (a null field)
+    -- treat it as undetected rather than crash on arithmetic with None."""
+    return all(
+        face.get(k) is not None
+        for k in ("boundingBoxX1", "boundingBoxX2", "boundingBoxY1", "boundingBoxY2")
+    )
+
+
 def _face_aware_crop_box(
     img_width: int, img_height: int, target_width: int, target_height: int, faces: list[dict]
 ) -> tuple[int, int, int, int]:
@@ -119,6 +279,8 @@ def _face_aware_crop_box(
     min_x = min_y = float("inf")
     max_x = max_y = float("-inf")
     for face in faces:
+        if not _has_bounding_box(face):
+            continue
         face_w = face.get("imageWidth") or img_width
         face_h = face.get("imageHeight") or img_height
         scale_x = img_width / face_w
@@ -152,29 +314,116 @@ def _face_aware_crop_box(
     return (int(left), int(top), int(left) + crop_w, int(top) + crop_h)
 
 
-def render_frame(source: Image.Image, faces: list[dict] | None = None,
-                 orientation: str = "landscape") -> bytes:
-    """Fits `source` to the panel's resolution, quantizes it to the 6-color
-    palette with Floyd-Steinberg dithering, and packs 2 pixels/byte the way
-    epd7in3e.c expects. Always returns exactly EPD_WIDTH*EPD_HEIGHT/2 bytes.
+# Display modes: how a photo's aspect ratio gets reconciled with the
+# panel's. "crop_faces" falls back to "crop_fill" behavior when no faces
+# were detected/passed. DEFAULT_DISPLAY_MODE matches this project's old
+# always-on smart_crop_faces=True default.
+DISPLAY_MODES = ["crop_fill", "crop_faces", "stretch_fill", "letterbox"]
+DISPLAY_MODE_LABELS = {
+    "crop_fill": "Crop to fill",
+    "crop_faces": "Crop to faces",
+    "stretch_fill": "Stretch to fill",
+    "letterbox": "Shrink to fit",
+}
+DEFAULT_DISPLAY_MODE = "crop_faces"
+LETTERBOX_BG = (255, 255, 255)
 
-    If `faces` (from ImmichClient.get_asset_faces) is non-empty, crops
-    toward keeping them on screen instead of a plain center-crop.
+# Static-image widget only offers a subset of DISPLAY_MODES -- no face
+# detection for an uploaded image, so "crop_faces" (which silently falls
+# back to crop_fill anyway, see compose_into) would just be a confusing
+# duplicate entry in that dialog's dropdown.
+STATIC_DISPLAY_MODES = ["crop_fill", "stretch_fill", "letterbox"]
+DEFAULT_STATIC_DISPLAY_MODE = "crop_fill"
 
-    `orientation` (see ORIENTATION_TRANSPOSE) composes the photo for how
-    the frame physically hangs, then rotates into native panel space --
-    the output byte layout is identical either way.
-    """
-    logical_w, logical_h = logical_render_size(orientation)
+
+def _placement_transform(
+    img_width: int, img_height: int, target_w: int, target_h: int,
+    display_mode: str, faces: list[dict] | None = None,
+) -> tuple[float, float, float, float]:
+    """Returns (scale_x, scale_y, offset_x, offset_y) mapping a point in
+    source-image pixel space to a point in target logical space, for the
+    given display_mode. Shared by render_frame (which also does the
+    actual pixel crop/resize/pad) and face_labels.py (label position
+    math) -- they must stay in exact agreement or overlay labels drift
+    off the people they're meant to point at."""
+    if display_mode == "stretch_fill":
+        return target_w / img_width, target_h / img_height, 0.0, 0.0
+    if display_mode == "letterbox":
+        scale = min(target_w / img_width, target_h / img_height)
+        return scale, scale, (target_w - img_width * scale) / 2, (target_h - img_height * scale) / 2
+    if display_mode == "crop_faces" and faces:
+        left, top, right, bottom = _face_aware_crop_box(img_width, img_height, target_w, target_h, faces)
+        crop_w, crop_h = right - left, bottom - top
+    else:
+        left, top, crop_w, crop_h = _plain_center_crop_box(img_width, img_height, target_w, target_h)
+    scale_x, scale_y = target_w / crop_w, target_h / crop_h
+    return scale_x, scale_y, -left * scale_x, -top * scale_y
+
+
+def compose_into(source: Image.Image, faces: list[dict] | None, target_w: int, target_h: int,
+                 display_mode: str) -> Image.Image:
+    """Crop/resize/letterbox `source` per display_mode into an arbitrary
+    target_w x target_h box -- returns an RGB image, before enhancement or
+    quantization. See render_frame for what each display_mode does.
+    _compose() is the common case of this (target = the full panel, at
+    logical_render_size(orientation)); this more general form also backs
+    calendar_render.py's agenda photo-inlay, which composes into just a
+    sub-region of the panel instead of the whole thing."""
     fitted = ImageOps.exif_transpose(source.convert("RGB"))
 
-    if faces:
-        box = _face_aware_crop_box(fitted.width, fitted.height, logical_w, logical_h, faces)
-        fitted = fitted.crop(box).resize((logical_w, logical_h), Image.LANCZOS)
-    else:
-        fitted = ImageOps.fit(fitted, (logical_w, logical_h), method=Image.LANCZOS)
+    if display_mode == "stretch_fill":
+        return fitted.resize((target_w, target_h), Image.LANCZOS)
+    if display_mode == "letterbox":
+        scale = min(target_w / fitted.width, target_h / fitted.height)
+        new_w, new_h = max(1, round(fitted.width * scale)), max(1, round(fitted.height * scale))
+        resized = fitted.resize((new_w, new_h), Image.LANCZOS)
+        canvas = Image.new("RGB", (target_w, target_h), LETTERBOX_BG)
+        canvas.paste(resized, ((target_w - new_w) // 2, (target_h - new_h) // 2))
+        return canvas
+    if display_mode == "crop_faces" and faces:
+        box = _face_aware_crop_box(fitted.width, fitted.height, target_w, target_h, faces)
+        return fitted.crop(box).resize((target_w, target_h), Image.LANCZOS)
+    return ImageOps.fit(fitted, (target_w, target_h), method=Image.LANCZOS)  # crop_fill, or crop_faces w/ no faces
 
-    quantized = fitted.quantize(palette=_PALETTE_IMAGE, dither=Image.Dither.FLOYDSTEINBERG)
+
+def _compose(source: Image.Image, faces: list[dict] | None, orientation: str, display_mode: str) -> Image.Image:
+    """Crop/resize/letterbox `source` per display_mode -- returns an RGB
+    image at logical_render_size(orientation), before enhancement or
+    quantization. See render_frame for what each display_mode does."""
+    return compose_into(source, faces, *logical_render_size(orientation), display_mode)
+
+
+def _enhance(img: Image.Image, color_boost: float, contrast_boost: float) -> Image.Image:
+    if color_boost != 1.0:
+        img = ImageEnhance.Color(img).enhance(color_boost)
+    if contrast_boost != 1.0:
+        img = ImageEnhance.Contrast(img).enhance(contrast_boost)
+    return img
+
+
+def _quantize(img: Image.Image, palette_rgb: list | None, dither_strength: float) -> Image.Image:
+    """RGB -> palette-quantized P-mode image, same size/orientation as
+    `img` (no rotation here). dither_strength blends `img` toward its own
+    flat (undithered) quantization before running Floyd-Steinberg on the
+    blend: at 0 there's zero quantization error left to diffuse (so the
+    result IS the flat quantization, no dithering texture at all); at 1
+    it's `img` unchanged (full-strength dithering, this project's
+    original always-on behavior); values between give a smooth continuum
+    of dithering intensity rather than an on/off toggle."""
+    palette_image = _build_palette_image(palette_rgb or DEFAULT_PALETTE_RGB)
+    if dither_strength >= 1.0:
+        return img.quantize(palette=palette_image, dither=Image.Dither.FLOYDSTEINBERG)
+    if dither_strength <= 0.0:
+        return img.quantize(palette=palette_image, dither=Image.Dither.NONE)
+    flat = img.quantize(palette=palette_image, dither=Image.Dither.NONE).convert("RGB")
+    blended = Image.blend(flat, img, dither_strength)
+    return blended.quantize(palette=palette_image, dither=Image.Dither.FLOYDSTEINBERG)
+
+
+def _transpose_and_pack(quantized: Image.Image, orientation: str) -> bytes:
+    """Rotates a logical-space quantized image into native panel space
+    and packs it 2 pixels/byte the way epd7in3e.c expects. Always
+    returns exactly EPD_WIDTH*EPD_HEIGHT/2 bytes."""
     transpose = ORIENTATION_TRANSPOSE.get(orientation)
     if transpose is not None:
         quantized = quantized.transpose(transpose)
@@ -190,3 +439,206 @@ def render_frame(source: Image.Image, faces: list[dict] | None = None,
             i += 1
 
     return bytes(out)
+
+
+def _apply_manage_overlay(img: Image.Image, manage: dict | None) -> Image.Image:
+    """Composites the manage-button overlay (scan-to-manage QR, battery,
+    location/date/share-QR, named face labels) onto an already-composed,
+    already-enhanced image, if requested -- see manage_overlay.compose().
+    Local import: manage_overlay is an optional, occasionally-used
+    concern (only /frame/*?manage=1 requests need it), same reasoning
+    render_placeholder already applies to its own `import qrcode`."""
+    if manage is None:
+        return img
+    from . import manage_overlay
+
+    return manage_overlay.compose(img, **manage)
+
+
+def render_frame(source: Image.Image, faces: list[dict] | None = None,
+                 orientation: str = "landscape", palette_rgb: list | None = None,
+                 display_mode: str = DEFAULT_DISPLAY_MODE, color_boost: float = 1.0,
+                 contrast_boost: float = 1.0, dither_strength: float = 1.0,
+                 manage: dict | None = None) -> bytes:
+    """Fits `source` to the panel's resolution, applies color/contrast
+    enhancement, quantizes it to the 6-color palette, and packs 2
+    pixels/byte the way epd7in3e.c expects. Always returns exactly
+    EPD_WIDTH*EPD_HEIGHT/2 bytes.
+
+    `display_mode` (see DISPLAY_MODES) picks how the photo's aspect ratio
+    is reconciled with the panel's: crop_fill (center-crop to fill,
+    excess trimmed), crop_faces (as crop_fill, but shifts the crop to
+    keep `faces` on screen -- falls back to crop_fill if none), stretch_fill
+    (fills exactly, aspect ratio not preserved), letterbox (whole photo
+    visible, letterboxed with LETTERBOX_BG where it doesn't fill).
+
+    `color_boost`/`contrast_boost` are PIL ImageEnhance factors (1.0 =
+    unchanged, matching PIL's own convention); `dither_strength` is
+    0.0-1.0 (see _quantize).
+
+    `orientation` (see ORIENTATION_TRANSPOSE) composes the photo for how
+    the frame physically hangs, then rotates into native panel space --
+    the output byte layout is identical either way.
+
+    `palette_rgb` overrides DEFAULT_PALETTE_RGB (a frame's tuned colors,
+    see Frame.palette_rgb) -- None uses the default.
+
+    `manage` is a dict of manage_overlay.compose()'s kwargs (management_url,
+    battery_percent, location_lines, taken_at, share_url, face_labels), or
+    None to skip it -- see routers/device.py's build_manage_content(),
+    which callers pass this straight through from. Applied after
+    enhancement, before quantization, so the overlay's pure black/white
+    graphics aren't affected by color/contrast boost.
+    """
+    fitted = _enhance(_compose(source, faces, orientation, display_mode), color_boost, contrast_boost)
+    fitted = _apply_manage_overlay(fitted, manage)
+    quantized = _quantize(fitted, palette_rgb, dither_strength)
+    return _transpose_and_pack(quantized, orientation)
+
+
+def render_panel(regions: list[tuple[tuple[int, int, int, int], Image.Image]], orientation: str = "landscape",
+                 palette_rgb: list | None = None, color_boost: float = 1.0, contrast_boost: float = 1.0,
+                 dither_strength: float = 1.0, manage: dict | None = None, as_png: bool = False) -> bytes:
+    """The widget system's compositor -- generalizes render_frame's tail
+    (paste, enhance once, overlay once, quantize once, pack once) from
+    "compose one photo" to "paste N already-rendered regions, then run
+    the same single shared pipeline over the result." Not a
+    restructuring: the calendar mode's old photo-inlay feature already
+    pasted a second, independently-composed image onto the canvas before
+    `_enhance`/`_quantize` ran exactly once over the whole thing -- this
+    just generalizes that from a fixed 1-2 region split to an arbitrary
+    list.
+
+    Each region is (rect, image): rect is (x, y, w, h) in *logical*
+    (pre-rotation) canvas space -- the same space logical_render_size(
+    orientation) describes, and what app/grid.py's cell_to_pixels()
+    produces -- and image is an already-composed RGB image exactly w x h
+    in size (e.g. from compose_into() for a photo/whiteboard widget, or
+    calendar_render's own builder for a calendar widget). Regions are
+    expected not to overlap (see models.Widget's docstring on why) --
+    this function doesn't enforce that itself, callers/the placement API
+    do, since by the time rendering happens it's too late to do anything
+    but paste in whatever order they're given (later entries would just
+    paint over earlier ones).
+
+    Quantizing/dithering the *whole* composited canvas once, rather than
+    each region separately before pasting, is what keeps a 6-color
+    e-ink panel's dithering pattern consistent across a widget boundary
+    instead of showing a visible seam where two independently-dithered
+    regions meet.
+
+    as_png=True returns a normal browser-viewable PNG in logical (upright)
+    orientation instead of packed native-panel bytes, same convention as
+    render_preview_png -- used for the web UI's live "how it's displaying"
+    thumbnail."""
+    logical_w, logical_h = logical_render_size(orientation)
+    canvas = Image.new("RGB", (logical_w, logical_h), LETTERBOX_BG)
+    for (x, y, w, h), region_img in regions:
+        canvas.paste(region_img.convert("RGB"), (x, y))
+
+    fitted = _enhance(canvas, color_boost, contrast_boost)
+    fitted = _apply_manage_overlay(fitted, manage)
+    quantized = _quantize(fitted, palette_rgb, dither_strength)
+    if as_png:
+        buf = io.BytesIO()
+        quantized.convert("RGB").save(buf, format="PNG")
+        return buf.getvalue()
+    return _transpose_and_pack(quantized, orientation)
+
+
+def render_preview_png(source: Image.Image, faces: list[dict] | None = None,
+                       orientation: str = "landscape", palette_rgb: list | None = None,
+                       display_mode: str = DEFAULT_DISPLAY_MODE, color_boost: float = 1.0,
+                       contrast_boost: float = 1.0, dither_strength: float = 1.0,
+                       manage: dict | None = None) -> bytes:
+    """Identical composition/enhancement/quantization pipeline as
+    render_frame, but returned as a normal browser-viewable PNG in
+    logical (upright, as-the-frame-actually-hangs) orientation rather
+    than packed native-panel bytes and rotation -- what the web UI's
+    "how it will look on the frame" preview shows."""
+    fitted = _enhance(_compose(source, faces, orientation, display_mode), color_boost, contrast_boost)
+    fitted = _apply_manage_overlay(fitted, manage)
+    quantized = _quantize(fitted, palette_rgb, dither_strength)
+    buf = io.BytesIO()
+    quantized.convert("RGB").save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def render_placeholder(lines: list[str], qr_url: str | None = None,
+                       orientation: str = "landscape", palette_rgb: list | None = None,
+                       manage: dict | None = None, as_png: bool = False) -> 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.
+
+    `manage`, same as render_frame's -- lets the manage button still work
+    (at minimum, the scan-to-manage QR) on a frame that isn't configured
+    yet."""
+    margin = 24
+    logical_w, logical_h = logical_render_size(orientation)
+    img = Image.new("RGB", (logical_w, logical_h), (255, 255, 255))
+    draw = ImageDraw.Draw(img)  # measurement only (textbbox/textlength) -- painting goes through draw_text
+
+    title_font = ImageFont.load_default(size=34)
+    body_font = ImageFont.load_default(size=24)
+    max_text_w = logical_w - margin * 2
+
+    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)
+
+    # Word-wrap each input line to the panel's actual width (portrait is
+    # much narrower than landscape -- a line written assuming ~800px
+    # would otherwise run straight off the edge) before laying anything
+    # out, so wrapped sub-lines count toward the vertical centering below.
+    def wrap(text: str, font) -> list[str]:
+        words = text.split()
+        if not words:
+            return [text]
+        out, current = [], words[0]
+        for word in words[1:]:
+            candidate = f"{current} {word}"
+            if draw.textlength(candidate, font=font) <= max_text_w:
+                current = candidate
+            else:
+                out.append(current)
+                current = word
+        out.append(current)
+        return out
+
+    # 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
+        for sub_line in wrap(line, font):
+            bbox = draw.textbbox((0, 0), sub_line, font=font)
+            line_heights.append((sub_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(img, ((logical_w - w) // 2, y), line, font)
+        y += h + gap
+
+    if qr_img:
+        img.paste(qr_img, ((logical_w - qr_img.width) // 2, y + 14))
+
+    img = _apply_manage_overlay(img, manage)
+    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
+    if as_png:
+        buf = io.BytesIO()
+        quantized.convert("RGB").save(buf, format="PNG")
+        return buf.getvalue()
+    return _transpose_and_pack(quantized, orientation)

server/app/image_upload.py

@@ -0,0 +1,54 @@
+"""Decodes an arbitrary uploaded file (PNG/JPEG/GIF/BMP/WEBP/TIFF/PDF/...)
+into a plain RGB PIL image, for the static-image widget (see routers/
+api_widgets.py's api_widget_static_upload, app/widgets/static_image.py).
+The result is stored (as PNG bytes) rather than the original upload, so
+render() never needs to re-run PDF/GIF decoding on every panel refresh --
+this module only runs once, at upload time.
+
+PDF decoding uses pypdfium2 (Google's PDFium bindings -- BSD-3-Clause/
+Apache-2.0, no copyleft exposure) rather than a GPL/AGPL alternative
+like PyMuPDF, per CLAUDE.md's copyleft-dependency convention (a check
+that only applies to copyleft/unclear licenses -- this one's plainly
+permissive, so no explicit flag was needed here)."""
+
+from __future__ import annotations
+
+import io
+
+import pypdfium2 as pdfium
+from fastapi import HTTPException
+from PIL import Image, UnidentifiedImageError
+
+MAX_UPLOAD_BYTES = 25 * 1024 * 1024  # generous for a single image/PDF page; stops an accidental huge upload
+# ~144 DPI off a PDF's 72-DPI native unit -- comfortably above the panel's
+# own 800x480, without ballooning render time/memory on a poster-sized page.
+PDF_RENDER_SCALE = 2.0
+
+
+def decode_upload(data: bytes) -> Image.Image:
+    """Raises HTTPException(400) for anything that isn't a recognizable
+    image or PDF. Detects PDF by magic bytes, not the client-supplied
+    filename/content-type (neither is trustworthy). A PDF renders only
+    its first page -- there's no "which page" concept for a single-image
+    widget."""
+    if len(data) > MAX_UPLOAD_BYTES:
+        raise HTTPException(400, f"File is too large (max {MAX_UPLOAD_BYTES // (1024 * 1024)}MB)")
+    if data.startswith(b"%PDF-"):
+        return _decode_pdf(data)
+    try:
+        img = Image.open(io.BytesIO(data))
+        img.load()
+    except UnidentifiedImageError:
+        raise HTTPException(400, "Not a recognizable image or PDF file") from None
+    return img.convert("RGB")
+
+
+def _decode_pdf(data: bytes) -> Image.Image:
+    try:
+        pdf = pdfium.PdfDocument(data)
+        if len(pdf) == 0:
+            raise HTTPException(400, "PDF has no pages")
+        bitmap = pdf[0].render(scale=PDF_RENDER_SCALE)
+    except pdfium.PdfiumError as e:
+        raise HTTPException(400, f"Could not read PDF: {e}") from e
+    return bitmap.to_pil().convert("RGB")

server/app/immich_client.py

@@ -80,10 +80,10 @@ class ImmichClient:
         resp.raise_for_status()
         return resp.json()
 
-    def create_share_link(self, asset_id: str, expires_in_s: int) -> str:
-        """Creates a public, view-only Immich share link for a single
-        asset, expiring expires_in_s seconds from now, and returns its
-        public URL. Used by the manage-button overlay's share QR --
+    def create_share_link(self, asset_ids: list[str], expires_in_s: int) -> str:
+        """Creates a public, view-only Immich share link covering one or
+        more assets, expiring expires_in_s seconds from now, and returns
+        its public URL. Used by the manage-button overlay's share QR --
         created lazily (only when someone actually scans it), not when
         the button's pressed, so the expiry clock starts when it's
         actually used."""
@@ -93,7 +93,7 @@ class ImmichClient:
             headers=self._headers,
             json={
                 "type": "INDIVIDUAL",
-                "assetIds": [asset_id],
+                "assetIds": list(asset_ids),
                 "expiresAt": expires_at,
                 "allowUpload": False,
                 "allowDownload": True,

server/app/mail.py

@@ -0,0 +1,68 @@
+"""SMTP email sending -- password resets and battery-threshold alerts.
+
+Config lives in the server_settings singleton row (admin-configured via
+/admin, see routers/pages.py), not env vars -- it's operator
+infrastructure a household admin sets up once through the UI, same
+spirit as the rest of this project's "no separate config file" stance
+post-redesign. Uses stdlib smtplib; no new dependency.
+
+send_email() never raises -- a broken mail server shouldn't 500 a
+password-reset request or a battery report; callers get a bool and log
+a warning on failure."""
+
+from __future__ import annotations
+
+import email.utils
+import logging
+import smtplib
+import ssl
+from email.mime.text import MIMEText
+
+from .models import ServerSettings
+
+logger = logging.getLogger(__name__)
+
+SMTP_TIMEOUT_S = 10
+
+
+def send_email(settings: ServerSettings, to_address: str, subject: str, body: str) -> bool:
+    if not settings.smtp_host or not to_address:
+        return False
+
+    msg = MIMEText(body)
+    msg["Subject"] = subject
+    msg["From"] = settings.smtp_from_address or settings.smtp_username or "noreply@localhost"
+    msg["To"] = to_address
+    # email.mime doesn't set either of these on its own -- and a missing
+    # Message-ID in particular is enough for a strict content filter
+    # (e.g. Amavis's header-sanity check) to quarantine an otherwise
+    # cleanly SPF/DKIM/DMARC-passing message outright. Domain in the
+    # generated id matches the From address so it's traceable back here.
+    msg["Date"] = email.utils.formatdate(localtime=True)
+    msg["Message-ID"] = email.utils.make_msgid(domain=msg["From"].rsplit("@", 1)[-1])
+
+    try:
+        # "ssl" (implicit TLS, port 465 typically) needs a TLS socket from
+        # the very first byte -- SMTP_SSL, not SMTP+starttls(). Connecting
+        # a plaintext SMTP() to a TLS-only port fails outright (garbled
+        # banner/timeout), it doesn't degrade gracefully, so this has to
+        # be a real branch rather than "starttls() or not".
+        if settings.smtp_encryption == "ssl":
+            with smtplib.SMTP_SSL(
+                settings.smtp_host, settings.smtp_port,
+                timeout=SMTP_TIMEOUT_S, context=ssl.create_default_context(),
+            ) as smtp:
+                if settings.smtp_username:
+                    smtp.login(settings.smtp_username, settings.smtp_password)
+                smtp.send_message(msg)
+        else:
+            with smtplib.SMTP(settings.smtp_host, settings.smtp_port, timeout=SMTP_TIMEOUT_S) as smtp:
+                if settings.smtp_encryption == "starttls":
+                    smtp.starttls(context=ssl.create_default_context())
+                if settings.smtp_username:
+                    smtp.login(settings.smtp_username, settings.smtp_password)
+                smtp.send_message(msg)
+        return True
+    except (OSError, smtplib.SMTPException, ssl.SSLError) as e:
+        logger.warning("Failed to send email to %s: %s", to_address, e)
+        return False

server/app/main.py

@@ -1,199 +1,58 @@
-"""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}/...
+  api_widgets.py  widget CRUD + grid placement, /api/frames/{id}/widgets
+  api_layouts.py  named, user-owned saved layouts, /api/layouts,
+                  /api/frames/{id}/layouts
+  frame_pages.py  the per-frame Photos/Configuration/Layout/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, api_layouts, api_widgets, 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(api_widgets.router)
+app.include_router(api_layouts.router)
+app.include_router(frame_pages.router)
+app.include_router(pages.router)
+app.include_router(manage.router)
 
 
 @app.get("/health")
@@ -201,695 +60,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/manage_overlay.py

@@ -0,0 +1,240 @@
+"""Composites the manage-button overlay -- "scan to manage" QR, battery,
+location/date-taken, share-QR, named face labels -- server-side, onto an
+already-composed image (any mode: a photo, or a calendar view), before
+quantization. Replaces what used to be firmware/main/manage_qr_overlay.c
+generating and positioning all of this on-device.
+
+Corner/spacing constants below are plain Python now, not a protocol
+contract with firmware -- adjustable here without touching anything else.
+Uses the same toolkit image_pipeline.render_placeholder already does
+(PIL ImageDraw/ImageFont, the qrcode library), just doing more with it.
+"""
+
+from __future__ import annotations
+
+from PIL import Image, ImageDraw, ImageFont
+
+from .image_pipeline import DEFAULT_PALETTE_RGB, draw_text
+
+PADDING = 16
+QR_TEXT_GAP = 8
+LINE_GAP = 4
+PANEL_MARGIN = 20
+QR_TARGET_PX = 180
+
+TITLE_FONT_SIZE = 22
+BODY_FONT_SIZE = 20
+
+BATTERY_ICON_W = 40
+BATTERY_ICON_H = 22
+BATTERY_ICON_STROKE = 2
+BATTERY_NUB_W = 5
+BATTERY_NUB_H = 10
+BATTERY_ICON_TEXT_GAP = 8
+BATTERY_REGION_GAP = 8  # vertical gap below the manage QR box
+
+FACE_LABEL_PADDING = 8
+FACE_LABEL_GAP = 4  # distance from the face's anchor point to the label box
+
+
+def _font(size: int) -> ImageFont.ImageFont:
+    return ImageFont.load_default(size=size)
+
+
+def _qr_image(url: str, target_px: int = QR_TARGET_PX) -> Image.Image:
+    import qrcode
+
+    qr = qrcode.QRCode(border=1, box_size=1)
+    qr.add_data(url)
+    qr.make(fit=True)
+    raw = qr.make_image().get_image().convert("RGB")
+    scale = max(1, target_px // raw.width)
+    return raw.resize((raw.width * scale, raw.height * scale), Image.NEAREST)
+
+
+def _text_box(draw: ImageDraw.ImageDraw, lines: list[str], font: ImageFont.ImageFont) -> tuple[int, int]:
+    """(width, height) of `lines` stacked with LINE_GAP between them, at
+    `font` -- the box _draw_text_box below will need."""
+    w = 0
+    h = 0
+    for i, line in enumerate(lines):
+        bbox = draw.textbbox((0, 0), line, font=font)
+        w = max(w, bbox[2] - bbox[0])
+        h += (bbox[3] - bbox[1]) + (LINE_GAP if i else 0)
+    return w, h
+
+
+def _draw_centered_lines(img: Image.Image, draw: ImageDraw.ImageDraw, lines: list[str], font: ImageFont.ImageFont,
+                         center_x: int, top: int) -> None:
+    y = top
+    for line in lines:
+        bbox = draw.textbbox((0, 0), line, font=font)
+        w = bbox[2] - bbox[0]
+        draw_text(img, (center_x - w // 2, y), line, font)
+        y += (bbox[3] - bbox[1]) + LINE_GAP
+
+
+def _draw_qr_box(img: Image.Image, draw: ImageDraw.ImageDraw, url: str, caption: list[str],
+                 corner: str) -> tuple[int, int, int, int]:
+    """White-padded box with a QR code and centered caption lines below
+    it, placed in one of the panel's four corners. Returns (x0, y0, w, h)
+    -- callers that need to anchor something else relative to this box
+    (the battery, below the manage QR) use it instead of recomputing the
+    same geometry a second time."""
+    qr_img = _qr_image(url)
+    text_w, text_h = _text_box(draw, caption, _font(TITLE_FONT_SIZE)) if caption else (0, 0)
+    content_w = max(qr_img.width, text_w)
+    content_h = qr_img.height + (QR_TEXT_GAP + text_h if caption else 0)
+
+    w = content_w + PADDING * 2
+    h = content_h + PADDING * 2
+    x0, y0 = _corner_origin(img.size, (w, h), corner)
+
+    draw.rectangle([x0, y0, x0 + w, y0 + h], fill=(255, 255, 255), outline=(0, 0, 0))
+    center_x = x0 + w // 2
+    img.paste(qr_img, (center_x - qr_img.width // 2, y0 + PADDING))
+    if caption:
+        _draw_centered_lines(img, draw, caption, _font(TITLE_FONT_SIZE), center_x, y0 + PADDING + qr_img.height + QR_TEXT_GAP)
+    return x0, y0, w, h
+
+
+def _draw_text_box(img: Image.Image, draw: ImageDraw.ImageDraw, lines: list[str], corner: str) -> None:
+    """White-padded box with centered text lines, placed in one of the
+    panel's four corners."""
+    font = _font(BODY_FONT_SIZE)
+    text_w, text_h = _text_box(draw, lines, font)
+    w = text_w + PADDING * 2
+    h = text_h + PADDING * 2
+    x0, y0 = _corner_origin(img.size, (w, h), corner)
+
+    draw.rectangle([x0, y0, x0 + w, y0 + h], fill=(255, 255, 255), outline=(0, 0, 0))
+    _draw_centered_lines(img, draw, lines, font, x0 + w // 2, y0 + PADDING)
+
+
+def _corner_origin(img_size: tuple[int, int], box_size: tuple[int, int], corner: str) -> tuple[int, int]:
+    img_w, img_h = img_size
+    box_w, box_h = box_size
+    if corner == "top-left":
+        return PANEL_MARGIN, PANEL_MARGIN
+    if corner == "top-right":
+        return img_w - PANEL_MARGIN - box_w, PANEL_MARGIN
+    if corner == "bottom-left":
+        return PANEL_MARGIN, img_h - PANEL_MARGIN - box_h
+    return img_w - PANEL_MARGIN - box_w, img_h - PANEL_MARGIN - box_h  # bottom-right
+
+
+# DEFAULT_PALETTE_RGB order is [BLACK, WHITE, YELLOW, RED, BLUE, GREEN]
+# (see image_pipeline.PANEL_CODES) -- picked by level so the fill itself
+# carries the "how worried should I be" signal, not just the number next
+# to it. Thresholds match the low-battery-alert spirit elsewhere in this
+# project (not tied to a frame's own configured alert threshold, since
+# this glyph has to make sense with no configuration at all).
+_BATTERY_LOW = DEFAULT_PALETTE_RGB[3]  # red
+_BATTERY_MEDIUM = DEFAULT_PALETTE_RGB[2]  # yellow
+_BATTERY_HIGH = DEFAULT_PALETTE_RGB[5]  # green
+
+
+def _battery_fill_color(percent: int) -> tuple[int, int, int]:
+    if percent <= 15:
+        return _BATTERY_LOW
+    if percent <= 40:
+        return _BATTERY_MEDIUM
+    return _BATTERY_HIGH
+
+
+def _draw_battery(img: Image.Image, draw: ImageDraw.ImageDraw, percent: int, anchor_x0: int, anchor_y0: int,
+                  anchor_w: int, anchor_h: int) -> None:
+    """Battery glyph (now actually filled to `percent`, not just a static
+    outline -- easy now that this renders server-side instead of being a
+    fixed bitmap firmware drew) + "NN%" text, right-aligned under the
+    given anchor box (the manage QR box) -- a sensible default position,
+    not a constraint anything else has to route around; move this call
+    site's arguments to place it anywhere else instead."""
+    font = _font(BODY_FONT_SIZE)
+    text = f"{percent}%"
+    icon_total_w = BATTERY_ICON_W + BATTERY_NUB_W
+    text_w = draw.textlength(text, font=font)
+    content_w = icon_total_w + BATTERY_ICON_TEXT_GAP + text_w
+    content_h = max(font.size, BATTERY_ICON_H)
+
+    w = int(content_w + PADDING * 2)
+    h = int(content_h + PADDING * 2)
+    x0 = anchor_x0 + anchor_w - w
+    y0 = anchor_y0 + anchor_h + BATTERY_REGION_GAP
+
+    draw.rectangle([x0, y0, x0 + w, y0 + h], fill=(255, 255, 255), outline=(0, 0, 0))
+
+    icon_x = x0 + PADDING
+    icon_y = y0 + PADDING + (content_h - BATTERY_ICON_H) // 2
+    inner_x0, inner_y0 = icon_x + BATTERY_ICON_STROKE, icon_y + BATTERY_ICON_STROKE
+    inner_x1, inner_y1 = icon_x + BATTERY_ICON_W - BATTERY_ICON_STROKE, icon_y + BATTERY_ICON_H - BATTERY_ICON_STROKE
+    fill_x1 = inner_x0 + round((inner_x1 - inner_x0) * (percent / 100))
+    if fill_x1 > inner_x0:
+        draw.rectangle([inner_x0, inner_y0, fill_x1, inner_y1], fill=_battery_fill_color(percent))
+    draw.rectangle([icon_x, icon_y, icon_x + BATTERY_ICON_W, icon_y + BATTERY_ICON_H], outline=(0, 0, 0),
+                   width=BATTERY_ICON_STROKE)
+    nub_y = icon_y + (BATTERY_ICON_H - BATTERY_NUB_H) // 2
+    draw.rectangle([icon_x + BATTERY_ICON_W, nub_y, icon_x + BATTERY_ICON_W + BATTERY_NUB_W, nub_y + BATTERY_NUB_H],
+                   fill=(0, 0, 0))
+    draw_text(img, (icon_x + icon_total_w + BATTERY_ICON_TEXT_GAP, y0 + PADDING + (content_h - font.size) // 2),
+             text, font)
+
+
+def _draw_face_label(img: Image.Image, draw: ImageDraw.ImageDraw, name: str, anchor_x: int, anchor_y: int) -> None:
+    """White-padded name label centered under an arbitrary (anchor_x,
+    anchor_y) point, flipped above if there's no room below, clamped to
+    stay fully on-panel -- unlike the four corner boxes (always in-bounds
+    by construction), a face can be anywhere, including near an edge."""
+    font = _font(BODY_FONT_SIZE)
+    text_w = draw.textlength(name, font=font)
+    bbox = draw.textbbox((0, 0), name, font=font)
+    text_h = bbox[3] - bbox[1]
+
+    w = int(text_w + FACE_LABEL_PADDING * 2)
+    h = int(text_h + FACE_LABEL_PADDING * 2)
+    img_w, img_h = img.size
+
+    x0 = anchor_x - w // 2
+    y0 = anchor_y + FACE_LABEL_GAP
+    if y0 + h > img_h:
+        y0 = anchor_y - FACE_LABEL_GAP - h  # no room below -- place above instead
+    x0 = max(0, min(x0, img_w - w))
+    y0 = max(0, min(y0, img_h - h))
+
+    draw.rectangle([x0, y0, x0 + w, y0 + h], fill=(255, 255, 255), outline=(0, 0, 0))
+    draw_text(img, (x0 + FACE_LABEL_PADDING, y0 + FACE_LABEL_PADDING - bbox[1]), name, font)
+
+
+def compose(image: Image.Image, management_url: str, battery_percent: int | None = None,
+           location_lines: tuple[str, str] | None = None, taken_at: str | None = None,
+           share_url: str | None = None, face_labels: list[dict] | None = None) -> Image.Image:
+    """Draws the manage overlay onto a copy of `image` (RGB, any mode's
+    already-composed/enhanced logical-space canvas) and returns it.
+    management_url's "scan to manage" box always shows; everything else
+    is optional and simply omitted when not given -- battery_percent
+    None or out of 0-100 skips the battery box, location_lines/taken_at/
+    share_url empty/None skip their own box, face_labels empty skips
+    those."""
+    img = image.copy()
+    draw = ImageDraw.Draw(img)
+
+    qr_x0, qr_y0, qr_w, qr_h = _draw_qr_box(img, draw, management_url, ["SCAN TO", "MANAGE"], "top-right")
+
+    if battery_percent is not None and 0 <= battery_percent <= 100:
+        _draw_battery(img, draw, battery_percent, qr_x0, qr_y0, qr_w, qr_h)
+
+    if location_lines and location_lines[0]:
+        lines = [line for line in location_lines if line]
+        _draw_text_box(img, draw, lines, "top-left")
+
+    if taken_at:
+        _draw_text_box(img, draw, [taken_at], "bottom-right")
+
+    if share_url:
+        _draw_qr_box(img, draw, share_url, ["SCAN TO", "DOWNLOAD"], "bottom-left")
+
+    for label in face_labels or []:
+        if label.get("name"):
+            _draw_face_label(img, draw, label["name"], label["x"], label["y"])
+
+    return img

server/app/models.py

@@ -0,0 +1,903 @@
+"""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, LargeBinary, 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="")
+    # Password-reset emails and battery-threshold alerts (frames.owner's
+    # email -- see routers/device.py's frame_battery) go here; blank = no
+    # email configured, both features silently no-op for this user.
+    email: Mapped[str] = mapped_column(String, default="")
+    # Personal ICS subscription URL (no OAuth) for calendar frame mode --
+    # see calendar_feed.py. Setting this alone shows up nowhere: a linked
+    # frame only pulls this user's events in once they've also added it
+    # on that frame's own Calendar tab (FrameCalendar below).
+    calendar_ics_url: Mapped[str] = mapped_column(String, default="")
+    # A CalDAV account (Nextcloud, Fastmail, iCloud, ...) alongside the
+    # plain ICS subscription above -- see caldav_client.py. calendar_url
+    # is the server's CalDAV entry point the user pasted in, not any one
+    # calendar's own URL; the individual calendars it exposes are
+    # discovered and cached below.
+    calendar_caldav_url: Mapped[str] = mapped_column(String, default="")
+    calendar_caldav_username: Mapped[str] = mapped_column(String, default="")
+    calendar_caldav_password: Mapped[str] = mapped_column(String, default="")
+    # [{"href", "display_name"}, ...] from the last successful
+    # caldav_client.discover_calendars() call, refreshed by Settings'
+    # "Discover calendars" button -- NULL until discovery has ever
+    # succeeded. This is what a frame's Calendar tab offers the user to
+    # add, without hitting the CalDAV server on every page load.
+    calendar_caldav_calendars: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    calendar_caldav_checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    # WebDAV credentials for whiteboard frame mode (see webdav_client.py,
+    # whiteboard.py) -- generic WebDAV, not Nextcloud-specific, but
+    # webdav_reuse_caldav_creds is a convenience for the common case
+    # where it IS the same Nextcloud account as calendar_caldav_*: skip
+    # re-entering the same username/password, since Nextcloud's CalDAV
+    # and general-file-WebDAV both sit under the one account. Doesn't
+    # try to be clever and derive the reuse automatically -- an explicit
+    # opt-in, same as everywhere else in this project defaults features
+    # off rather than silently inferring them.
+    webdav_username: Mapped[str] = mapped_column(String, default="")
+    webdav_password: Mapped[str] = mapped_column(String, default="")
+    webdav_reuse_caldav_creds: Mapped[bool] = mapped_column(Boolean, default=False)
+    # Optional starting folder for the whiteboard dialog's file-picker
+    # (see routers/api_widgets.py's api_widget_whiteboard_browse) --
+    # purely a convenience for browsing to a file rather than typing its
+    # full URL.
+    # Never used for fetching/rendering itself, which always uses the
+    # frame's own saved whiteboard_url regardless of whether this is set.
+    webdav_base_url: 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 -- "photos", "calendar", or "whiteboard"
+    # (see routers/device.py RENDERERS/ADVANCE_RENDERERS/BACK_RENDERERS
+    # and routers/common.py FRAME_MODES).
+    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")
+    # How a photo's aspect ratio is reconciled with the panel's -- see
+    # image_pipeline.DISPLAY_MODES.
+    display_mode: Mapped[str] = mapped_column(String, default="crop_faces")
+    orientation: Mapped[str] = mapped_column(String, default="landscape")
+    queue_target_len: Mapped[int] = mapped_column(Integer, default=20)
+    # Advanced configuration: [[r,g,b], ...] x6 (black/white/yellow/red/
+    # blue/green, matching image_pipeline.PANEL_CODES order) overriding
+    # DEFAULT_PALETTE_RGB for this frame's actual panel. NULL = use the
+    # default -- most frames never touch this.
+    palette_rgb: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    # Advanced configuration: PIL ImageEnhance factors, 1.0 = unchanged
+    # (see image_pipeline.render_frame).
+    color_boost: Mapped[float] = mapped_column(Float, default=1.0)
+    contrast_boost: Mapped[float] = mapped_column(Float, default=1.0)
+    # 0.0-1.0, see image_pipeline._quantize -- 1.0 matches this project's
+    # original always-on full-strength Floyd-Steinberg dithering.
+    dither_strength: Mapped[float] = mapped_column(Float, default=1.0)
+
+    # -- calendar mode (see calendar_feed.py, calendar_render.py,
+    # routers/device.py's RENDERERS["calendar"]) --
+    calendar_view: Mapped[str] = mapped_column(String, default="agenda")  # "agenda" | "week" | "month"
+    # 0=Monday..6=Sunday (matches date.weekday()/calendar.Calendar) --
+    # which day week/month views start their grid on.
+    calendar_week_start: Mapped[int] = mapped_column(Integer, default=0)
+    # Agenda view only; reuses this frame's existing photos-mode album/
+    # queue, not a separate photo setup.
+    calendar_photo_inlay: Mapped[bool] = mapped_column(Boolean, default=False)
+    # How many periods (unit depends on calendar_view: days/weeks/months)
+    # NEXT/BACK have browsed from "today". Reset to 0 by the next normal
+    # (non-button) /frame/image request, and whenever calendar_view
+    # itself changes -- a stale offset means something different in a
+    # different view's units.
+    calendar_browse_offset: Mapped[int] = mapped_column(Integer, default=0)
+    # Throttled merge-fetch cache (see routers/common.py's
+    # get_or_refresh_calendar_events) -- same shape as the
+    # firmware_update_checked_at/firmware_gitea_latest_version pattern
+    # below. One shared cache for every included user's merged events,
+    # not per-user.
+    calendar_checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    calendar_cached_events: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    # "" when the last merge-fetch fully succeeded, else e.g. "1 of 2
+    # calendars unavailable" -- never names which user's feed failed, a
+    # shared household display shouldn't call out a specific person's
+    # outage to everyone who looks at it.
+    calendar_fetch_summary: Mapped[str] = mapped_column(String, default="")
+
+    # Optional weather strip, agenda/today & tomorrow/week views only --
+    # never month, there's no room (see calendar_render.py's _BUILDERS).
+    # Off by default.
+    calendar_weather_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
+    calendar_weather_units: Mapped[str] = mapped_column(String, default="fahrenheit")  # "fahrenheit" | "celsius"
+    # [{"label", "latitude", "longitude"}, ...] -- each geocoded once via
+    # weather.geocode_city() when added from the Calendar tab.
+    calendar_weather_cities: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    # Throttled per-city forecast cache (see routers/common.py's
+    # get_or_refresh_weather) -- same shape idiom as
+    # calendar_checked_at/calendar_cached_events above.
+    # [{"label", "days": {"YYYY-MM-DD": {"code","high","low"}}}, ...]
+    calendar_weather_checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    calendar_weather_cached: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+
+    # Week view: how many days to show (2-10, default 7 -- the original
+    # fixed behavior) and whether they're laid out as side-by-side
+    # columns or stacked bands (see calendar_render.py's _build_week).
+    calendar_week_days: Mapped[int] = mapped_column(Integer, default=7)
+    calendar_week_layout: Mapped[str] = mapped_column(String, default="horizontal")  # "horizontal" | "vertical"
+    # Only used when calendar_week_days != 7 -- calendar_week_start's
+    # fixed-weekday anchor ("start on the most recent Monday") stops
+    # making sense once the view isn't a literal calendar week, so a
+    # non-7-day view instead starts this many days from today (0 =
+    # starts today, negative = starts in the past, positive = starts in
+    # the future). Ignored (calendar_week_start governs instead) at the
+    # default 7 days, so this has no effect until someone actually
+    # changes the day count.
+    calendar_week_start_offset: Mapped[int] = mapped_column(Integer, default=0)
+
+    # Optional task list, week view only -- takes the space of one day
+    # slot rather than adding an extra one (see calendar_render.py's
+    # _draw_tasks). CalDAV only (a task list is a VTODO collection, not
+    # something a plain ICS subscription meaningfully has); source is
+    # one specific linked user's own CalDAV calendar, same
+    # owner-controls-their-own-data permission split as FrameCalendar.
+    # calendar_tasks_user_id
+    # SET NULL on the user's deletion clears the source rather than
+    # leaving a dangling reference (checked_at isn't reset by that, but
+    # the next refresh attempt finds no source and just returns []).
+    calendar_tasks_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
+    calendar_tasks_user_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    calendar_tasks_calendar_key: Mapped[str | None] = mapped_column(String, nullable=True)
+    calendar_tasks_checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    # [{"summary", "due" (ISO date/datetime string or None)}, ...],
+    # already filtered to outstanding (not-completed) tasks and sorted
+    # by due date -- see caldav_client.fetch_tasks.
+    calendar_tasks_cached: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+
+    # -- whiteboard mode (see webdav_client.py, whiteboard.py,
+    # routers/device.py's RENDERERS["whiteboard"]) -- a frame-wide
+    # setting like calendar mode's own frame_calendars source, not
+    # personal data, but still owner-gated the same way: only
+    # whiteboard_user_id may point the frame at their own account, since
+    # it's their credentials being used to fetch it. --
+    whiteboard_user_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    # The specific .whiteboard file's WebDAV URL -- pasted directly, same
+    # idiom as calendar_ics_url, not discovered/browsed (unlike CalDAV's
+    # account-has-several-calendars case, a WebDAV account doesn't need
+    # a picker step here since the user already knows which one file).
+    whiteboard_url: Mapped[str] = mapped_column(String, default="")
+    whiteboard_checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    # Cached rendered PNG bytes (see whiteboard.fetch_and_render) --
+    # BLOB rather than the JSON columns the rest of this cache-pattern
+    # family uses, since this is binary image data, not JSON-shaped.
+    whiteboard_cached_image: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+
+    # -- 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="")
+
+    # Battery-low email alert (see routers/device.py's frame_battery).
+    # -1 = disabled. Sent to the owner's email once per discharge cycle
+    # (battery_alert_sent resets alongside battery_history whenever a
+    # recharge is detected, same trigger as stats_recharge_cycles).
+    battery_alert_threshold_pct: Mapped[int] = mapped_column(Integer, default=-1)
+    battery_alert_sent: Mapped[bool] = mapped_column(Boolean, default=False)
+
+    # -- 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="")
+
+    # -- hold-for-global-action (see app/global_actions.py) -- holding
+    # NEXT/BACK past hold_duration_ms triggers a global action instead of
+    # the per-widget one that a short press runs (models.FrameButtonAction).
+    # Not scoped to any widget, e.g. cycling saved layouts -- hence its
+    # own pair of frame-level columns rather than living in that table.
+    hold_duration_ms: Mapped[int] = mapped_column(Integer, default=3000)
+    next_hold_action: Mapped[str | None] = mapped_column(String, nullable=True, default=None)
+    back_hold_action: Mapped[str | None] = mapped_column(String, nullable=True, default=None)
+    # Where "cycle saved layouts" resumes from -- the last SavedLayout id
+    # it applied, so repeated holds advance through the list instead of
+    # re-applying the same one every time. Deliberately not a real FK:
+    # this is just a resume cursor, not a relationship needing cascade/
+    # referential integrity -- if that layout's since been deleted or
+    # renamed away, global_actions.cycle_layout just doesn't find it and
+    # starts over from the first one, same as an unset value.
+    last_cycled_layout_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # -- 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 FrameCalendar(Base):
+    """One calendar included on one frame -- calendar_key is "ics" (the
+    owner's single calendar_ics_url) or "caldav:<href>" (one of the
+    owner's CalDAV collections; href matches an entry in
+    User.calendar_caldav_calendars). Replaces the old single
+    UserFrame.calendar_included boolean now that a CalDAV account can
+    expose more than one calendar.
+
+    A row only ever gets created by its own owner (adding a calendar to
+    a frame is each person's own data-sharing choice, not something a
+    frame's controller decides on their behalf) -- but once it exists,
+    ANY user linked to the frame may flip included back to False, muting
+    a calendar they'd rather not see on a shared display even though
+    they don't own it. Only the owner may flip it back to True. See
+    routers/api_widgets.py's api_widget_calendar_select.
+
+    Keyed by widget_id, not frame_id -- a frame can hold more than one
+    independent calendar widget (see Widget), each with its own included-
+    calendars set; "included on this frame" stopped being unambiguous
+    the moment that became possible (see migration.py's
+    _ensure_frame_calendars_rekeyed, which re-keyed this table)."""
+
+    __tablename__ = "frame_calendars"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"))
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    calendar_key: Mapped[str] = mapped_column(String)
+    # Snapshot label for display -- so the list still reads sensibly even
+    # if the owner's CalDAV account later stops offering this calendar.
+    calendar_label: Mapped[str] = mapped_column(String, default="")
+    included: Mapped[bool] = mapped_column(Boolean, default=True)
+    # Index into image_pipeline.DEFAULT_PALETTE_RGB/PALETTE_LABELS (2-5:
+    # Yellow/Red/Blue/Green -- 0/1 are reserved, already the page's
+    # text/background) pinning this calendar's events to a specific
+    # panel color rather than calendar_render.py's old owner-name
+    # auto-cycle. NULL keeps the auto-cycle behavior. Only the calendar's
+    # owner may set this -- see routers/api_widgets.py's api_widget_calendar_color.
+    color_index: Mapped[int | None] = mapped_column(Integer, nullable=True, default=None)
+
+    __table_args__ = (
+        Index("ix_frame_calendars_unique", "widget_id", "user_id", "calendar_key", unique=True),
+    )
+
+
+class FrameTaskList(Base):
+    """One CalDAV task list included on one tasks widget -- calendar_key
+    is "caldav:<href>" (an entry in User.calendar_caldav_calendars; no
+    "ics" variant, unlike FrameCalendar -- a plain ICS subscription has
+    no VTODO collection). Same owner-controls-their-own-data shape as
+    FrameCalendar in every other respect: a row is only ever created by
+    its own owner, but any user linked to the frame may flip included
+    back to False, and only the owner may flip it back to True or set
+    color_index. See routers/api_widgets.py's api_widget_task_list_select/
+    api_widget_task_list_color."""
+
+    __tablename__ = "frame_task_lists"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"))
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    calendar_key: Mapped[str] = mapped_column(String)
+    calendar_label: Mapped[str] = mapped_column(String, default="")
+    included: Mapped[bool] = mapped_column(Boolean, default=True)
+    color_index: Mapped[int | None] = mapped_column(Integer, nullable=True, default=None)
+
+    __table_args__ = (
+        Index("ix_frame_task_lists_unique", "widget_id", "user_id", "calendar_key", unique=True),
+    )
+
+
+class Widget(Base):
+    """One placed/sized content item on a frame's panel -- the unit the
+    widget system replaces the old single Frame.mode with (see
+    app/grid.py for the grid this x/y/w/h is measured in, and app/widgets/
+    for the widget_type -> render/action dispatch registry). Widgets never
+    overlap (enforced server-side in routers/api_widgets.py), which is
+    what keeps compositing simple: no z-order, no blending, just N
+    independent regions pasted onto one shared canvas before a single
+    shared dither/quantize pass (see image_pipeline.render_panel).
+
+    widget_type selects which of the three per-type extension tables below
+    (PhotoWidgetConfig/CalendarWidgetConfig/WhiteboardWidgetConfig) holds
+    this widget's actual settings/state -- a 1:1 relational split rather
+    than one wide table with every type's columns, matching how
+    FrameCalendar/BatteryLog are already their own tables in this
+    codebase rather than crammed onto Frame."""
+
+    __tablename__ = "widgets"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    frame_id: Mapped[int] = mapped_column(ForeignKey("frames.id", ondelete="CASCADE"))
+    widget_type: Mapped[str] = mapped_column(String)  # "photos" | "calendar" | "whiteboard" | "tasks" | "static" | "text" | "weather" | "battery"
+    x: Mapped[int] = mapped_column(Integer)
+    y: Mapped[int] = mapped_column(Integer)
+    w: Mapped[int] = mapped_column(Integer)
+    h: Mapped[int] = mapped_column(Integer)
+    # Display/tie-break ordering only (e.g. listing widgets in a UI) --
+    # NOT a z-order, since widgets never overlap. Named sort_order, not
+    # order, to sidestep the SQL-keyword dance Frame.order needed
+    # (mapped to a differently-named column) -- nothing outside this
+    # table needs to match a specific attribute name here.
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+    # Optional decorative border, drawn once around this widget's own
+    # region (routers/device.py's _render_widgets) regardless of
+    # widget_type -- a Widget-level property, not a per-type config
+    # column, since every widget type can have one. See
+    # image_pipeline.BORDER_STYLES/draw_widget_border. "none" (the
+    # default) draws nothing, so existing widgets don't suddenly grow a
+    # border. border_color_index indexes into the frame's palette_rgb
+    # (0-5, Black/White/Yellow/Red/Blue/Green) rather than storing an
+    # arbitrary hex -- an exact palette color quantizes with zero
+    # dithering error, same reasoning as the weather/battery icons'
+    # exact-panel-ink-RGB fills (see docs/widgets.md).
+    border_style: Mapped[str] = mapped_column(String, default="none")
+    border_thickness: Mapped[int] = mapped_column(Integer, default=3)
+    border_color_index: Mapped[int] = mapped_column(Integer, default=0)
+
+    __table_args__ = (Index("ix_widgets_frame", "frame_id"),)
+
+
+class PhotoWidgetConfig(Base):
+    """One photo widget's settings + queue state. Attribute names match
+    Frame's old photo-queue columns exactly (down to `order`'s same
+    photo_order column-name dodge) -- app/photo_queue.py's 5 functions
+    are duck-typed against these exact names (never isinstance-checked
+    against Frame), so they port unchanged onto this table."""
+
+    __tablename__ = "photo_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    album_id: Mapped[str] = mapped_column(String, default="")
+    order: Mapped[str] = mapped_column("photo_order", String, default="sequential")
+    display_mode: Mapped[str] = mapped_column(String, default="crop_faces")
+    queue_target_len: Mapped[int] = mapped_column(Integer, default=20)
+    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)
+    locked: Mapped[bool] = mapped_column(Boolean, default=False)
+
+
+class CalendarWidgetConfig(Base):
+    """One calendar widget's settings + cached-fetch state -- the same
+    fields that used to live as calendar_* columns directly on Frame,
+    minus calendar_photo_inlay (dropped: arbitrary widget placement
+    subsumes what a fixed 50/50 inlay split did, so it's not a special
+    case anymore, just place a photo widget alongside) and minus
+    tasks_* (also dropped: split out into its own standalone widget
+    type, see TaskWidgetConfig, so a task list isn't tied to a
+    calendar's week view/footprint anymore). "Included calendars" is
+    its own table (FrameCalendar), widget_id-keyed so each calendar
+    widget on a frame has its own independent set."""
+
+    __tablename__ = "calendar_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    view: Mapped[str] = mapped_column(String, default="agenda")
+    week_start: Mapped[int] = mapped_column(Integer, default=0)
+    browse_offset: Mapped[int] = mapped_column(Integer, default=0)
+    checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    cached_events: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    fetch_summary: Mapped[str] = mapped_column(String, default="")
+    weather_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
+    weather_units: Mapped[str] = mapped_column(String, default="fahrenheit")
+    weather_cities: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    weather_checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    weather_cached: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    week_days: Mapped[int] = mapped_column(Integer, default=7)
+    week_layout: Mapped[str] = mapped_column(String, default="horizontal")
+    week_start_offset: Mapped[int] = mapped_column(Integer, default=0)
+
+
+class TaskWidgetConfig(Base):
+    """One tasks widget's settings + cached-fetch state -- split out of
+    CalendarWidgetConfig (which used to carry these as tasks_* columns,
+    a week-view-only task list bolted onto a calendar widget) so a task
+    list can be placed and sized on its own, independent of any
+    calendar's view/footprint. No separate "enabled" flag -- unlike the
+    old bolted-on version, the widget's mere presence on the grid is the
+    on/off switch, same as every other widget type.
+
+    Which task lists feed this widget lives in FrameTaskList, not here
+    -- a widget can merge more than one person's list, mirroring
+    CalendarWidgetConfig/FrameCalendar exactly (this used to be a single
+    user_id/calendar_key pair here, one list only; migration 18 carried
+    each widget's existing single source forward as its first
+    FrameTaskList row when splitting this out)."""
+
+    __tablename__ = "task_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    # Shown on-panel in place of the default "Tasks" header (see
+    # calendar_render._draw_tasks) -- "" keeps the default. The only
+    # widget type with its own on-panel title at all, since it's the
+    # only one where "which list is this" isn't already obvious from
+    # its content the way a calendar/photo/whiteboard's is.
+    name: Mapped[str] = mapped_column(String, default="")
+    checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    # [{"summary", "due", "completed_at" (ISO date/datetime strings or
+    # None), "owner_display_name", "color_index"}, ...] -- the merged
+    # multi-list result, same general shape as CalendarWidgetConfig.
+    # cached_events. See caldav_client.merge_tasks.
+    cached: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    # Also include tasks completed in the last 24h (drawn checked-box +
+    # muted, see calendar_render._draw_tasks) rather than just
+    # outstanding ones -- off by default, same "opt into more" posture
+    # as calendar_weather_enabled.
+    show_completed: Mapped[bool] = mapped_column(Boolean, default=False)
+
+
+class WhiteboardWidgetConfig(Base):
+    """One whiteboard widget's source + rendered-PNG cache -- the same
+    fields that used to live as whiteboard_* columns directly on Frame."""
+
+    __tablename__ = "whiteboard_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    url: Mapped[str] = mapped_column(String, default="")
+    checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    cached_image: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+
+
+class WeatherWidgetConfig(Base):
+    """One weather widget's settings + cached-fetch state. Four display
+    modes (see app/widgets/weather.py): "current" (one city, current
+    temp + icon), "hourly" (one city, a row of ticks across the day),
+    "daily" (one city, a multi-day strip), "multi_city" (several cities'
+    current-day high/low/icon side by side -- the calendar widget's
+    embedded weather strip, lifted out into its own widget type).
+    `provider` selects which of app/weather/'s PROVIDERS actually fetches
+    ("open_meteo" | "nws" -- see that package's own module docstring).
+    `cached`'s shape depends on `mode`: {"temp","category"} for current,
+    a list of {"time","temp","category"} for hourly, a
+    {"YYYY-MM-DD": {...}} dict for daily, or a list of
+    {"label","high","low","category"} for multi_city."""
+
+    __tablename__ = "weather_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    mode: Mapped[str] = mapped_column(String, default="current")  # current | hourly | daily | multi_city
+    provider: Mapped[str] = mapped_column(String, default="open_meteo")  # open_meteo | nws
+    units: Mapped[str] = mapped_column(String, default="fahrenheit")  # fahrenheit | celsius
+    # Single-location modes only (current/hourly/daily) -- geocoded once
+    # via weather.geocode_city() when set, same idiom as
+    # CalendarWidgetConfig.weather_cities' per-entry shape.
+    city_label: Mapped[str | None] = mapped_column(String, nullable=True)
+    city_latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    city_longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    hourly_interval_hours: Mapped[int] = mapped_column(Integer, default=4)
+    daily_days: Mapped[int] = mapped_column(Integer, default=5)
+    # multi_city mode only -- [{"label", "latitude", "longitude"}, ...],
+    # same shape as CalendarWidgetConfig.weather_cities.
+    cities: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    checked_at: Mapped[float] = mapped_column(Float, default=0.0)
+    cached: Mapped[dict | list | None] = mapped_column(JSON, nullable=True, default=None)
+
+
+class TextWidgetConfig(Base):
+    """One text widget's authored content + display settings -- another
+    no-live-upstream type like StaticWidgetConfig, just parsed rich text
+    instead of an uploaded image. content is never raw HTML: the
+    dialog's contenteditable innerHTML is parsed server-side (see
+    app/text_content.py, the sanitization boundary) into this plain
+    run structure at save time, so render() (app/widgets/text.py) never
+    re-parses/sanitizes HTML on every panel refresh, and the dialog never
+    re-injects stored HTML via innerHTML when reopened.
+
+    [[{"text","bold","italic","underline","color","bg"}, ...], ...] --
+    outer list is paragraphs (line breaks), inner list is styled runs
+    within that paragraph. color/bg are "#rrggbb" or null (falls back to
+    black text / no highlight). NULL (not just []) means never
+    configured, matching StaticWidgetConfig.image's None-vs-empty
+    convention for "not configured yet"."""
+
+    __tablename__ = "text_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    content: Mapped[list | None] = mapped_column(JSON, nullable=True, default=None)
+    # Base point size for the whole block -- render() shrinks this down
+    # (never up) to fit the widget's actual box; per-run font size isn't
+    # supported, only the bold/italic/underline/color/bg style flags are
+    # per-run (see app/text_content.py) -- keeps the wrap/shrink-to-fit
+    # layout in app/widgets/text.py to one size per render pass.
+    font_size: Mapped[int] = mapped_column(Integer, default=28)
+    # A key into app/widgets/text.py's FONT_FAMILIES, also whole-widget
+    # not per-run (see font_size above for why).
+    font_family: Mapped[str] = mapped_column(String, default="sans")
+    align: Mapped[str] = mapped_column(String, default="left")  # "left" | "center" | "right"
+    background_color: Mapped[str] = mapped_column(String, default="#ffffff")
+
+
+class StaticWidgetConfig(Base):
+    """One static-image widget's uploaded content + display settings --
+    unlike every other widget type, this one has no live upstream to
+    poll (Immich/CalDAV/WebDAV): the "source" is whatever the user last
+    uploaded (see routers/api_widgets.py's api_widget_static_upload,
+    app/image_upload.py), decoded once at upload time into plain RGB PNG
+    bytes so app/widgets/static_image.py's render() never re-runs
+    PDF/GIF decoding on every panel refresh."""
+
+    __tablename__ = "static_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    image: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    original_filename: Mapped[str] = mapped_column(String, default="")
+    uploaded_at: Mapped[float] = mapped_column(Float, default=0.0)
+    # Same DISPLAY_MODES vocabulary as PhotoWidgetConfig.display_mode,
+    # minus crop_faces -- no face detection for an uploaded image (see
+    # image_pipeline.STATIC_DISPLAY_MODES).
+    display_mode: Mapped[str] = mapped_column(String, default="crop_fill")
+
+
+class BatteryWidgetConfig(Base):
+    """One battery widget's display settings -- another no-live-upstream
+    type like StaticWidgetConfig/TextWidgetConfig, just showing existing
+    frame-level state (Frame.battery_percent/battery_as_of, already set
+    by routers/device.py's frame_battery on every device report) instead
+    of anything the widget itself fetches or the user authors. `mode`
+    "compact" is icon + percent only; "detailed" (default) adds the
+    routers.common.battery_estimate_s time-remaining estimate and the
+    last report's age."""
+
+    __tablename__ = "battery_widget_configs"
+
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"), primary_key=True)
+    mode: Mapped[str] = mapped_column(String, default="detailed")  # compact | detailed
+
+
+# widget_type -> its per-type extension table, keyed by widget_id. Used
+# by db.widget_locked() to resolve the right config row without importing
+# app/widgets/'s heavier render/action registry just for this lookup.
+WIDGET_CONFIG_MODELS: dict[str, type] = {
+    "photos": PhotoWidgetConfig,
+    "calendar": CalendarWidgetConfig,
+    "whiteboard": WhiteboardWidgetConfig,
+    "tasks": TaskWidgetConfig,
+    "static": StaticWidgetConfig,
+    "battery": BatteryWidgetConfig,
+    "text": TextWidgetConfig,
+    "weather": WeatherWidgetConfig,
+}
+
+
+class FrameButtonAction(Base):
+    """One (widget, action) binding for one of a frame's two physical
+    buttons -- e.g. {button: "next", widget_id: <photo widget>, action:
+    "advance"}. At most one binding per (widget, button) -- edited from
+    that widget's own config dialog (routers/api_widgets.py's
+    api_widget_config_save), prefilled with a sane default at widget
+    creation (app/widgets/default_button_actions). On a press, every
+    widget's row for that (frame, button) runs -- see routers/device.py's
+    frame_advance/frame_back. sort_order is unused (which widget's action
+    runs first never matters: each only touches its own state, and one
+    shared re-render happens after all of them finish) but kept around so
+    dispatch has a stable, deterministic query order."""
+
+    __tablename__ = "frame_button_actions"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    frame_id: Mapped[int] = mapped_column(ForeignKey("frames.id", ondelete="CASCADE"))
+    button: Mapped[str] = mapped_column(String)  # "next" | "back"
+    widget_id: Mapped[int] = mapped_column(ForeignKey("widgets.id", ondelete="CASCADE"))
+    action: Mapped[str] = mapped_column(String)  # e.g. "advance", "back", "check_now" -- see app/widgets/
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+
+    __table_args__ = (
+        Index("ix_frame_button_actions_frame_button", "frame_id", "button", "sort_order"),
+        Index("ix_frame_button_actions_widget_button", "widget_id", "button", unique=True),
+    )
+
+
+class SavedLayout(Base):
+    """A named snapshot of one frame's widget arrangement (types,
+    placement, per-widget settings, button assignments) -- owned by a
+    *user*, not a frame, so it can be applied to any frame that user
+    controls whose grid matches (see docs/widgets.md's "Saved layouts").
+    cols/rows is the grid.grid_dims(orientation) the snapshot was taken
+    at -- an 8x5 (landscape-class) layout isn't meaningful on a 5x8
+    (portrait-class) frame, same reasoning as grid.py's own orientation-
+    change note.
+
+    Saving again with a name that already exists for this user
+    overwrites that layout's snapshot in place (see routers/
+    api_layouts.py's api_layout_save) rather than erroring or quietly
+    creating a second layout with the same name -- the "named save slot"
+    behavior people expect."""
+
+    __tablename__ = "saved_layouts"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    name: Mapped[str] = mapped_column(String)
+    cols: Mapped[int] = mapped_column(Integer)
+    rows: Mapped[int] = mapped_column(Integer)
+    created_at: Mapped[float] = mapped_column(Float, default=time.time)
+    updated_at: Mapped[float] = mapped_column(Float, default=time.time)
+
+    __table_args__ = (
+        Index("ix_saved_layouts_user_name", "user_id", "name", unique=True),
+    )
+
+
+class SavedLayoutWidget(Base):
+    """One captured widget's type/placement/settings within a
+    SavedLayout -- the snapshot analogue of Widget plus its per-type
+    config row, minus anything that's runtime/cache state rather than an
+    authored setting (a photo widget's current queue position, a
+    calendar's fetch cache, a whiteboard's rendered-image cache, etc.)
+    -- see api_layouts.LAYOUT_CONFIG_FIELDS for the exact per-type field
+    allowlist. `config` holds every JSON-safe captured setting; `image`
+    is only ever populated for a static-image widget's uploaded bytes
+    (its own BLOB column rather than folding base64 into the JSON, same
+    reasoning as StaticWidgetConfig.image itself)."""
+
+    __tablename__ = "saved_layout_widgets"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    saved_layout_id: Mapped[int] = mapped_column(ForeignKey("saved_layouts.id", ondelete="CASCADE"))
+    widget_type: Mapped[str] = mapped_column(String)
+    x: Mapped[int] = mapped_column(Integer)
+    y: Mapped[int] = mapped_column(Integer)
+    w: Mapped[int] = mapped_column(Integer)
+    h: Mapped[int] = mapped_column(Integer)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+    config: Mapped[dict] = mapped_column(JSON, default=dict)
+    image: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+
+    __table_args__ = (Index("ix_saved_layout_widgets_layout", "saved_layout_id"),)
+
+
+class SavedLayoutSource(Base):
+    """One included calendar/task-list source captured on a calendar or
+    tasks SavedLayoutWidget -- the snapshot analogue of FrameCalendar/
+    FrameTaskList. `kind` ("calendar" | "task") distinguishes which,
+    since both shapes are otherwise identical and sharing one table
+    avoids a near-duplicate SavedLayoutTaskSource table."""
+
+    __tablename__ = "saved_layout_sources"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    saved_layout_widget_id: Mapped[int] = mapped_column(
+        ForeignKey("saved_layout_widgets.id", ondelete="CASCADE")
+    )
+    kind: Mapped[str] = mapped_column(String)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    calendar_key: Mapped[str] = mapped_column(String)
+    calendar_label: Mapped[str] = mapped_column(String, default="")
+    included: Mapped[bool] = mapped_column(Boolean, default=True)
+    color_index: Mapped[int | None] = mapped_column(Integer, nullable=True, default=None)
+
+    __table_args__ = (Index("ix_saved_layout_sources_widget", "saved_layout_widget_id"),)
+
+
+class SavedLayoutButtonAction(Base):
+    """One (button, action) binding captured for one SavedLayoutWidget --
+    the snapshot analogue of FrameButtonAction. References the captured
+    widget directly rather than a frame_id/widget_id pair (neither
+    exists until the layout is applied) so applying can remap it onto
+    whichever new Widget row that captured widget becomes -- see
+    routers/api_layouts.py's api_layout_apply."""
+
+    __tablename__ = "saved_layout_button_actions"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    saved_layout_widget_id: Mapped[int] = mapped_column(
+        ForeignKey("saved_layout_widgets.id", ondelete="CASCADE")
+    )
+    button: Mapped[str] = mapped_column(String)
+    action: Mapped[str] = mapped_column(String)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+
+    __table_args__ = (Index("ix_saved_layout_button_actions_widget", "saved_layout_widget_id"),)
+
+
+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 ServerSettings(Base):
+    """Singleton row (id always 1) holding operator-level SMTP config, set
+    from /admin -- not env vars, since this is infrastructure a household
+    admin configures once through the UI rather than at container
+    deploy time. Used for password-reset emails and battery-threshold
+    alerts (see app/mail.py). smtp_host empty = email sending disabled;
+    every send site checks that and no-ops rather than erroring."""
+
+    __tablename__ = "server_settings"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    smtp_host: Mapped[str] = mapped_column(String, default="")
+    smtp_port: Mapped[int] = mapped_column(Integer, default=587)
+    smtp_username: Mapped[str] = mapped_column(String, default="")
+    smtp_password: Mapped[str] = mapped_column(String, default="")
+    smtp_from_address: Mapped[str] = mapped_column(String, default="")
+    # "none" (plaintext, port 25 typically), "starttls" (upgrades a
+    # plaintext connection, port 587 typically), or "ssl" (TLS from the
+    # first byte -- a different handshake entirely, not just starttls()
+    # skipped; port 465 typically). See app/mail.py.
+    smtp_encryption: Mapped[str] = mapped_column(String, default="starttls")
+
+
+class PasswordResetToken(Base):
+    """A single-use, time-limited "forgot password" link. token is the
+    URL-safe secret itself (not hashed, like PendingClaim/manage_token --
+    it's a short-lived bearer credential emailed once, not a long-lived
+    session secret)."""
+
+    __tablename__ = "password_reset_tokens"
+
+    token: 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,11 +85,21 @@ 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], frame: Frame) -> 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
-    interval has elapsed -- always mutates cfg."""
+    interval has elapsed -- always mutates cfg.
+
+    `frame` is a separate reference to the owning Frame, for fields that
+    stay frame-level rather than moving onto a photo widget's own config
+    (currently just stats_photos_displayed) -- once a photo widget's
+    queue state lives on its own PhotoWidgetConfig row rather than
+    directly on Frame (see models.py), `cfg` and `frame` stop being the
+    same object; every existing caller today still passes the same Frame
+    for both, which is also why this stays a required (not optional)
+    param -- no implicit "guess which Frame owns this" fallback to get
+    wrong later."""
     if cfg.current_asset_id:
         # Recorded regardless of *why* this advance happened (a manual
         # next-press or the timer just elapsing) -- back should be able
@@ -105,7 +115,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
+    frame.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 +123,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], frame: Frame) -> 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
@@ -122,7 +132,7 @@ def back_forced(cfg: FrameConfig, assets: list[dict]) -> bool:
     since). Returns whether it actually moved -- False (history empty or
     entirely stale) is a no-op, callers should still just display
     whatever's current rather than treating it as an error. Used by the
-    back-photo button (POST /frame/back)."""
+    back-photo button (POST /frame/back). See advance_forced() on `frame`."""
     valid_ids = {a["id"] for a in assets}
     while cfg.history:
         previous_id = cfg.history.pop()
@@ -132,12 +142,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
+        frame.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, frame: Frame) -> 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
@@ -146,10 +156,10 @@ def remove_from_rotation(cfg: FrameConfig, assets: list[dict], asset_id: str) ->
     *not* through advance_forced(), since that would record the removed
     photo in history, and going back to a photo you just explicitly
     removed doesn't make sense. Returns whether the current photo
-    changed as a result."""
+    changed as a result. See advance_forced() on `frame`."""
     if asset_id not in cfg.excluded_asset_ids:
         cfg.excluded_asset_ids.append(asset_id)
-        cfg.stats.photos_removed += 1
+        frame.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 +177,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
+    frame.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 +190,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], frame: Frame, 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
@@ -190,6 +200,10 @@ def get_current(cfg: FrameConfig, assets: list[dict], in_quiet_hours: bool = Fal
     ahead, while a wake that lands after the interval has elapsed still
     advances exactly once, even after a long time offline.
 
+    refresh_interval_s is read off `frame`, not `cfg` -- it's a device
+    wake-cadence setting shared by the whole panel, not something that
+    becomes per-widget (see advance_forced() on the cfg/frame split).
+
     in_quiet_hours suppresses *only* the elapsed-time trigger -- an
     unset/invalid current photo still gets picked regardless, since
     showing nothing is worse than showing something even at 3am. This
@@ -197,12 +211,19 @@ def get_current(cfg: FrameConfig, assets: list[dict], in_quiet_hours: bool = Fal
     /api/queue), so without this an open browser tab polling overnight
     would silently advance the current photo on raw elapsed time alone,
     even though the device itself is correctly asleep through the
-    window (see main.py's _effective_refresh_interval_s)."""
+    window (see main.py's _effective_refresh_interval_s).
+
+    cfg.locked suppresses the elapsed-time trigger the same way
+    in_quiet_hours does -- a locked widget still needs an initial pick
+    if it somehow has none (an unconfigured widget just locked, or a
+    changed album), but once it has a current photo the whole point of
+    locking is that it stops moving on its own until explicitly
+    unlocked."""
     valid_ids = {a["id"] for a in assets}
     needs_pick = not cfg.current_asset_id or cfg.current_asset_id not in valid_ids
-    time_elapsed = (time.time() - cfg.current_asset_set_at) >= cfg.refresh_interval_s
-    stale = needs_pick or (time_elapsed and not in_quiet_hours)
+    time_elapsed = (time.time() - cfg.current_asset_set_at) >= frame.refresh_interval_s
+    stale = needs_pick or (time_elapsed and not in_quiet_hours and not cfg.locked)
     if not stale:
         return False
-    advance_forced(cfg, assets)
+    advance_forced(cfg, assets, frame)
     return True

server/app/quiet_hours.py

@@ -0,0 +1,137 @@
+"""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 date, 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 local_date(cfg) -> date:
+    """`date.today()` in cfg.timezone (falls back to UTC for an
+    unrecognized zone, same as _zoneinfo) -- what calendar mode's "today"
+    anchor and browse-offset both key off of, so every part of that
+    feature agrees on what day it is for a given frame."""
+    return datetime.now(_zoneinfo(cfg.timezone)).date()
+
+
+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 quiet_span_s(cfg) -> int:
+    """Seconds per day quiet hours keeps the device asleep -- 0 when
+    disabled. Used by common.py's battery-remaining estimate to turn a
+    per-wake battery cost into a wall-clock duration: quiet hours cuts
+    how many wakes happen per day without changing what any one wake
+    costs, so it belongs in the wakes-per-day math, not the per-wake
+    rate itself."""
+    if not cfg.quiet_hours_enabled:
+        return 0
+    return _quiet_hours_span_s(cfg.quiet_hours_start, cfg.quiet_hours_end)
+
+
+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,401 @@
+"""The web UI's JSON API for frame-wide settings: /api/frames/{id}/...
+Per-widget settings (album, calendar view/inclusion, whiteboard source,
+etc.) live in api_widgets.py instead, under /api/frames/{id}/widgets/
+{widget_id}/... -- split out once a frame could hold more than one
+widget of the same type.
+
+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: only provided fields 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 sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .. import gitea_releases, grid, quiet_hours
+from ..auth import require_frame_control, require_frame_view, require_user_api
+from ..db import frame_locked, get_db
+from ..global_actions import GLOBAL_ACTIONS
+from ..image_pipeline import PALETTE_LABELS, hex_to_rgb
+from ..firmware import firmware_path, parse_app_version
+from ..models import BatteryLog, Frame, Widget
+from .common import OVERDUE_FACTOR, battery_estimate_s, immich_client_for, immich_creds, valid_http_url
+from .device import render_frame_preview_png
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+MIN_REFRESH_INTERVAL_S = 60
+MAX_REFRESH_INTERVAL_S = 86400
+
+ORIENTATIONS = ("landscape", "portrait", "landscape_flipped", "portrait_flipped")
+
+# See app/global_actions.py -- how long NEXT/BACK must be held before the
+# device treats it as a hold instead of a short press.
+MIN_HOLD_DURATION_MS = 3000
+MAX_HOLD_DURATION_MS = 10000
+
+
+def _reset_widget_layout_for_new_orientation(db: Session, frame_id: int, new_orientation: str) -> None:
+    """A widget's x/y/w/h are grid cells relative to the OLD orientation's
+    cols x rows (see grid.grid_dims) -- landscape and portrait use a
+    transposed grid (8x5 vs 5x8), so an existing placement is often
+    literally out of bounds on the new grid, not just visually wrong.
+    There's no sensible coordinate remap between two differently-shaped
+    grids, so instead: keep whichever widget was first by placement
+    order, resized to fill the new full panel, and delete the rest --
+    cascading to their own config rows and any FrameButtonAction
+    bindings via ondelete="CASCADE" (see models.py). The frontend is
+    expected to confirm this with the user before submitting an
+    orientation change (see frame_config.js) -- this always executes
+    unconditionally once called, same posture as every other
+    confirm-on-the-client / act-unconditionally-on-the-server action in
+    this codebase."""
+    widgets = db.scalars(
+        select(Widget).where(Widget.frame_id == frame_id).order_by(Widget.sort_order)
+    ).all()
+    if not widgets:
+        return
+    keep, *rest = widgets
+    for widget in rest:
+        db.delete(widget)
+    keep.x, keep.y, keep.w, keep.h = grid.full_panel_rect(new_orientation)
+
+
+@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),
+    refresh_interval_s: 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),
+    battery_alert_threshold_pct: int | None = Form(None),
+    palette: list[str] | None = Form(None),
+    palette_reset: bool | None = Form(None),
+    color_boost: float | None = Form(None),
+    contrast_boost: float | None = Form(None),
+    dither_strength: float | None = Form(None),
+    hold_duration_ms: int | None = Form(None),
+    next_hold_action: str | None = Form(None),
+    back_hold_action: str | None = Form(None),
+    frame: Frame = Depends(require_frame_control),
+    db: Session = Depends(get_db),
+):
+    """Partial update of frame-wide settings only -- per-widget settings
+    (album, calendar view/inclusion, whiteboard source, etc.) live on
+    routers/api_widgets.py's /widgets/{widget_id}/... endpoints instead,
+    since a frame can hold more than one widget of the same type and
+    "the frame's calendar settings" stopped being unambiguous the moment
+    that became possible. `mode` and `calendar_photo_inlay` are no
+    longer accepted here either: mode no longer governs anything (a
+    frame's widgets do), and photo inlay has no widget-system equivalent
+    (place an independent photo widget alongside instead). All three are
+    harmless no-ops if an old cached page still POSTs them -- FastAPI
+    silently ignores form fields with no matching parameter.
+
+    An actual orientation *change* resets the frame's widget layout (see
+    _reset_widget_layout_for_new_orientation) -- widget placement is
+    grid-cell-relative to the panel's long/short axis, which swaps on a
+    landscape<->portrait change, so an old placement is usually not just
+    visually wrong but literally out of bounds on the new grid.
+
+    hold_duration_ms/next_hold_action/back_hold_action configure hold-
+    for-global-action (see app/global_actions.py) -- a frame-wide
+    setting, not per-widget, hence living here rather than on
+    api_widgets.py's per-widget button-actions endpoint. An unrecognized
+    action value clears the binding rather than erroring, same posture
+    as this endpoint's other enum-ish fields (orientation, timezone)."""
+    with frame_locked(db, frame.id) as cfg:
+        if name is not None:
+            cfg.name = name.strip()[:64] or cfg.name
+        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 orientation is not None:
+            new_orientation = orientation if orientation in ORIENTATIONS else "landscape"
+            if new_orientation != cfg.orientation:
+                _reset_widget_layout_for_new_orientation(db, cfg.id, new_orientation)
+            cfg.orientation = new_orientation
+        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:
+            stripped = firmware_update_repo_url.strip()
+            if stripped and not valid_http_url(stripped):
+                raise HTTPException(400, "Firmware repo URL must be a plain http:// or https:// URL")
+            cfg.firmware_update_repo_url = stripped
+        if firmware_auto_update is not None:
+            cfg.firmware_auto_update = firmware_auto_update
+        if battery_alert_threshold_pct is not None:
+            cfg.battery_alert_threshold_pct = max(-1, min(100, battery_alert_threshold_pct))
+            # A changed threshold should be able to fire again immediately,
+            # not stay suppressed by a flag set under the old value.
+            cfg.battery_alert_sent = False
+        if palette_reset:
+            cfg.palette_rgb = None
+        elif palette is not None:
+            if len(palette) != len(PALETTE_LABELS):
+                raise HTTPException(400, f"Expected {len(PALETTE_LABELS)} palette colors, got {len(palette)}")
+            parsed = [hex_to_rgb(h) for h in palette]
+            if any(rgb is None for rgb in parsed):
+                raise HTTPException(400, "Palette colors must be #rrggbb hex values")
+            cfg.palette_rgb = [list(rgb) for rgb in parsed]
+        if color_boost is not None:
+            cfg.color_boost = max(0.0, min(2.0, color_boost))
+        if contrast_boost is not None:
+            cfg.contrast_boost = max(0.0, min(2.0, contrast_boost))
+        if dither_strength is not None:
+            cfg.dither_strength = max(0.0, min(1.0, dither_strength))
+        if hold_duration_ms is not None:
+            cfg.hold_duration_ms = max(MIN_HOLD_DURATION_MS, min(MAX_HOLD_DURATION_MS, hold_duration_ms))
+        if next_hold_action is not None:
+            cfg.next_hold_action = next_hold_action if next_hold_action in GLOBAL_ACTIONS else None
+        if back_hold_action is not None:
+            cfg.back_hold_action = back_hold_action if back_hold_action in GLOBAL_ACTIONS else None
+        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}/status")
+def api_status(
+    request: Request, frame: Frame = Depends(require_frame_view), db: Session = Depends(get_db)
+):
+    """Device liveness + control-lock info -- frame-level facts (battery,
+    last-seen, firmware, who has control), not tied to any particular
+    widget. Powers static/device_status_bar.js, shown on every per-frame
+    page regardless of which widgets that frame has. Used to piggyback on
+    the photo queue endpoint (back when a frame had at most one widget,
+    always photos-shaped); split out once that stopped being true, so the
+    status bar isn't blank on a frame with no photo widget."""
+    user = require_user_api(request, db)
+    now = time.time()
+    overdue_gap = quiet_hours.max_expected_gap_s(frame) * OVERDUE_FACTOR
+    return {
+        "control": {
+            "controller": (frame.controlled_by.display_name or frame.controlled_by.username) if frame.controlled_by else None,
+            "you": frame.controlled_by_user_id == user.id,
+        },
+        "device": {
+            "last_seen": frame.last_seen or None,
+            "overdue": bool(frame.last_seen and now - frame.last_seen > overdue_gap),
+            "firmware_version": frame.device_firmware_version or None,
+            "firmware_available": frame.firmware_available_version or None,
+            "battery": (
+                {"percent": frame.battery_percent, "as_of": frame.battery_as_of}
+                if frame.battery_percent >= 0 else None
+            ),
+            "battery_estimate_s": battery_estimate_s(frame, db),
+        },
+    }
+
+
+@router.get("/api/frames/{frame_id}/preview")
+def api_frame_preview(
+    request: Request, frame: Frame = Depends(require_frame_view), db: Session = Depends(get_db)
+):
+    """A small PNG of exactly what the frame is currently displaying --
+    the same widget compositor /frame/image uses (see routers/device.py's
+    render_frame_preview_png), just handed back upright and unpacked for
+    the dashboard header's live thumbnail instead of the device's packed
+    native format. Not cached: cheap enough for an on-demand header image,
+    and each widget's own render is already idempotent between a device's
+    real wakes (see photo_queue.get_current, calendar widget's browse
+    reset), so an extra read here doesn't skip or duplicate anything."""
+    png = render_frame_preview_png(db, frame, request)
+    return Response(content=png, media_type="image/png")
+
+
+@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]}
+
+
+
+@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.post("/api/frames/{frame_id}/firmware/check")
+def api_firmware_check(
+    force: bool = False, frame: Frame = Depends(require_frame_control), 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.
+
+    require_frame_control (not view), and POST (not GET): this can
+    silently stage new firmware as a side effect (the auto-apply path
+    below) exactly like /firmware/apply-latest, so it needs the same
+    guard that route has -- a linked viewer without control shouldn't be
+    able to trigger that, and as a GET it would've been exempt from the
+    CSRF check require_user_api only applies to non-GET/HEAD/OPTIONS."""
+    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}