Fix ee02 button-wakeup build: ext1 fallback for ESP32-S3

esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown() only exists on ESP32-C6 (SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP), so the ee02 (ESP32-S3) build failed with implicit-declaration errors in {back,next,combo}_button.c once the epd13in3e driver's #error stopped masking it. Each button file now branches on that capability macro: the C6 path (devkit/xiao) is untouched, and ESP32-S3 uses esp_sleep_enable_ext1_wakeup_io() instead. The earlier ext1 attempt was rejected on C6 hardware because its pull resistor didn't hold across RTC_PERIPH power-down -- tracing the same path in ESP-IDF source shows gpio_config()'s pull_up_en already delegates to rtc_gpio_pullup_en() for RTC-capable pins on every non-original-ESP32 target, so the pull-up should already survive the same power-down on S3. The _io() variant is additive, so the three button files don't need cross-file mask coordination. Also widens the button GPIO Kconfig range for IDF_TARGET_ESP32S3 (0-21, matching its RTC-IO set) instead of the C6-shaped 0-7. Verified: ee02, devkit, and xiao all build clean end-to-end locally (native ESP-IDF v6.0, no Docker in this sandbox). NOT verified: whether this actually avoids the spurious-instant-wakeup bug on real EE02 hardware -- that failure mode was only ever confirmed empirically, not root-caused in a way a compile can check. continue-on-error stays on in CI's ee02 build step until that's confirmed.
Port real epd13in3e driver from vendor code; fix wire-raster stride bug
2026-08-04 22:46:13 +00:00 · 2026-08-04 22:00:18 +00:00 · 2026-08-04 20:50:29 +00:00 · 2026-08-04 20:08:22 +00:00 · 2026-08-04 18:33:29 +00:00 · 2026-08-02 03:23:27 +00:00
247 changed files with 27045 additions and 1799 deletions
@@ -0,0 +1,132 @@
+---
+name: build-firmware
+description: Compile the espresso_frame firmware (firmware/) for all three board variants (ESP32-C6 devkit/xiao, ESP32-S3 ee02) 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 the devkit/xiao/ee02 board targets.
+---
+
+Compiles `firmware/` (ESP-IDF, targeting ESP32-C6 for devkit/xiao and
+ESP32-S3 for ee02) 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+esp32s3 toolchains + Python venv, via ESP-IDF's own
+  `./install.sh esp32c6,esp32s3` -- scoped to just this project's two
+  chip targets (see `firmware/README.md`'s board table: devkit/xiao are
+  esp32c6, ee02 is esp32s3), 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 ee02
+bash .claude/skills/build-firmware/build.sh both        # devkit + xiao
+bash .claude/skills/build-firmware/build.sh all         # devkit + xiao + ee02
+```
+
+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 for
+devkit/xiao, esp32s3 for ee02) 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 the 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),
+`firmware/build_xiao/espresso_frame.bin` (xiao), or
+`firmware/build_ee02/espresso_frame.bin` (ee02, once its driver actually
+compiles -- see the note above) -- all three paths are gitignored (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.
@@ -0,0 +1,81 @@
+#!/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 for
+# devkit/xiao, esp32s3 for ee02) 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).
+#
+# NOTE: ee02 builds will fail to compile -- deliberately -- until
+# firmware/components/epd13in3e's panel driver is ported from vendor
+# demo code (see that component's own top-of-file comment). The build
+# plumbing itself (target selection, partition table, sdkconfig
+# layering) is exercised regardless; only the final compile step fails.
+#
+# Usage:
+#   build.sh                        # build devkit (default)
+#   build.sh devkit
+#   build.sh xiao
+#   build.sh ee02
+#   build.sh both                   # build devkit + xiao (unchanged meaning)
+#   build.sh all                    # build devkit + xiao + ee02
+#   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 target
+  case "$board" in
+    devkit) sdkconfig="sdkconfig"; target="esp32c6" ;;
+    xiao) sdkconfig="sdkconfig.xiao_local"; target="esp32c6" ;;
+    ee02) sdkconfig="sdkconfig.ee02_local"; target="esp32s3" ;;
+    *) echo "Unknown board '$board' -- expected 'devkit', 'xiao', or 'ee02'" >&2; exit 1 ;;
+  esac
+
+  if [ ! -f "$sdkconfig" ]; then
+    echo "==> $board: no generated sdkconfig yet, setting target $target"
+    ./build_for_board.sh "$board" set-target "$target"
+  fi
+
+  local args=("$@")
+  if [ ${#args[@]} -eq 0 ]; then
+    args=(build)
+  fi
+  ./build_for_board.sh "$board" "${args[@]}"
+}
+
+board="${1:-devkit}"
+shift || true
+
+case "$board" in
+  both)
+    build_one devkit "$@"
+    build_one xiao "$@"
+    ;;
+  all)
+    build_one devkit "$@"
+    build_one xiao "$@"
+    build_one ee02 "$@"
+    ;;
+  *)
+    build_one "$board" "$@"
+    ;;
+esac
@@ -0,0 +1,59 @@
+#!/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+esp32s3 only --
+# this project's two chip targets (see firmware/README.md's board
+# table: devkit/xiao are esp32c6, ee02 is esp32s3). 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,esp32s3 (fast if already installed) ..."
+(cd "$IDF_DIR" && ./install.sh esp32c6,esp32s3)
+
+echo "setup complete -> $IDF_DIR/export.sh (build.sh sources this for you)"
@@ -0,0 +1,195 @@
+---
+name: make-widget
+description: Scaffold a new widget type for the espresso_frame server (the ~14-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, saved-layout config allowlist, 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.
+14. **`app/routers/api_layouts.py`** -- add a `"<type>": (...)` entry to
+    `LAYOUT_CONFIG_FIELDS` listing the config columns that are an
+    authored *setting* (as opposed to runtime/cache state like a fetch
+    cache or queue position, which a saved layout deliberately leaves
+    out -- see the dict's own comment). Skipping this doesn't error or
+    warn anywhere: the widget just silently saves/applies with an empty
+    `{}` config forever, resetting to defaults on every layout apply or
+    hold-to-cycle. This actually shipped missing for the weather widget
+    -- caught only because a user noticed layout-cycling kept resetting
+    its city/mode.
+
+## 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.
+- `test_saved_layouts.py` -- a `test_save_and_apply_round_trip_<type>_settings`
+  test: set every field the new `LAYOUT_CONFIG_FIELDS` entry lists,
+  save a layout, assert the `SavedLayoutWidget.config` snapshot has them
+  all, delete the frame's widgets, apply the layout back, assert the
+  new widget's config matches -- and that any runtime/cache field
+  (`checked_at`, a fetch cache, a queue) was *not* carried over. See
+  `test_save_and_apply_round_trip_weather_settings` for the pattern.
+
+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`).
@@ -0,0 +1,2 @@
+# Generated by setup.sh -- bakes in this host's /tmp paths, not portable.
+env.sh
@@ -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`.
@@ -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)
@@ -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"
@@ -0,0 +1,30 @@
+#!/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" \
+LOG_PATH="$SCRATCH/app.log" \
+.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)"
@@ -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
@@ -0,0 +1,76 @@
+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 every board variant still compiles (or, for ee02,
+# that everything up to its known/tracked #error still compiles --
+# see that step's own comment); 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"
+
+      # Expected to fail until firmware/components/epd13in3e's panel
+      # driver is ported from vendor demo code (deliberate #error, see
+      # that file's own top comment) -- continue-on-error so this known
+      # gap doesn't block every other firmware/** push. Still worth
+      # running: catches a regression in the surrounding scaffolding
+      # (Kconfig, main/CMakeLists.txt's component selection, sdkconfig
+      # layering) up to the point of that #error, same value a build
+      # check normally provides. Remove continue-on-error once
+      # epd13in3e's driver is real, so a build failure here goes back to
+      # being a genuine regression signal.
+      - name: Build (ee02 -- Seeed EE02, XIAO ESP32-S3 Plus + 13.3in panel)
+        continue-on-error: true
+        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 ee02 set-target esp32s3 &&
+            ./build_for_board.sh ee02 build
+          ')
+          docker cp "$PWD/." "$cid:/workspace"
+          docker start -a "$cid"
+          docker rm "$cid"
@@ -18,7 +18,7 @@ jobs:
    # actions) is a Node action that gets exec'd *inside* whatever container
    # the job specifies, so checkout fails immediately with "node: not
    # found" (hit this on the first real run). Checkout instead runs on the
-    # plain runner (which has Node), and only the two build steps below
+    # plain runner (which has Node), and only the three build steps below
    # spin up the ESP-IDF image themselves (docker create/cp/start, see the
    # comment on those steps for why not a plain `docker run -v`) -- the
    # runner already bind-mounts the host's docker socket, so docker-in-
@@ -33,11 +33,13 @@ jobs:
        id: version
        run: echo "version=$(tr -d '[:space:]' < firmware/version.txt)" >> "$GITHUB_OUTPUT"

-      # Two board variants, two partition tables/flash sizes (see
-      # firmware/README.md's "Building for the Seeed XIAO ESP32-C6"
-      # section) -- build_for_board.sh gives each its own build dir/
-      # generated sdkconfig so this never fights over shared state.
-      # set-target first since a fresh checkout has no cached sdkconfig
+      # Three board variants: devkit/xiao (ESP32-C6, different partition
+      # tables/flash sizes -- see firmware/README.md's "Building for the
+      # Seeed XIAO ESP32-C6" section) and ee02 (ESP32-S3 + 13.3" panel,
+      # a genuinely different chip target, not just a Kconfig variant).
+      # build_for_board.sh gives each its own build dir/generated
+      # sdkconfig so this never fights over shared state. set-target
+      # first since a fresh checkout has no cached sdkconfig
      # (firmware/sdkconfig* is gitignored, see firmware/.gitignore).
      # safe.directory guards against git's "dubious ownership" check,
      # since the container runs as root over content owned by a
@@ -64,8 +66,15 @@ jobs:
          ')
          docker cp "$PWD/." "$cid:/workspace"
          docker start -a "$cid"
-          docker cp "$cid:/workspace/firmware/build/espresso_frame.bin" /tmp/release-assets/firmware-devkit.bin
+          docker cp "$cid:/workspace/firmware/build/espresso_frame.bin" /tmp/release-assets/firmware-devkit_esp32c6.bin
          docker rm "$cid"
+          # Rename bridge: fielded devices flashed before this rename still
+          # report the bare "devkit" board name and look up "firmware-
+          # devkit.bin" for their OTA check -- publish a duplicate under
+          # the old name too so they can update at all. Safe to drop this
+          # duplicate in a later release once no fielded device reports
+          # the bare name anymore.
+          cp /tmp/release-assets/firmware-devkit_esp32c6.bin /tmp/release-assets/firmware-devkit.bin

      - name: Build (xiao -- Seeed XIAO ESP32-C6)
        run: |
@@ -77,7 +86,35 @@ jobs:
          ')
          docker cp "$PWD/." "$cid:/workspace"
          docker start -a "$cid"
-          docker cp "$cid:/workspace/firmware/build_xiao/espresso_frame.bin" /tmp/release-assets/firmware-xiao.bin
+          docker cp "$cid:/workspace/firmware/build_xiao/espresso_frame.bin" /tmp/release-assets/firmware-xiao_esp32c6.bin
+          docker rm "$cid"
+          # Same rename-bridge reasoning as the devkit step above.
+          cp /tmp/release-assets/firmware-xiao_esp32c6.bin /tmp/release-assets/firmware-xiao.bin
+
+      # NOTE: this build is expected to FAIL until
+      # firmware/components/epd13in3e's panel driver is ported from
+      # vendor demo code (see that component's own top-of-file comment
+      # -- a deliberate #error, not a bug here). `continue-on-error` so
+      # this known, tracked gap doesn't block publishing the devkit/xiao
+      # release (those boards work today and shouldn't wait on ee02) --
+      # this step's own status still shows failed/red individually in
+      # the run's step list, it just doesn't fail the overall job. Once
+      # epd13in3e's driver is real, a build failure here becomes a
+      # genuine regression again -- remove `continue-on-error` at that
+      # point so it goes back to failing the job like the other two
+      # builds do.
+      - name: Build (ee02 -- Seeed EE02, XIAO ESP32-S3 Plus + 13.3in panel)
+        continue-on-error: true
+        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 ee02 set-target esp32s3 &&
+            ./build_for_board.sh ee02 build
+          ')
+          docker cp "$PWD/." "$cid:/workspace"
+          docker start -a "$cid"
+          docker cp "$cid:/workspace/firmware/build_ee02/espresso_frame.bin" /tmp/release-assets/firmware-ee02.bin
          docker rm "$cid"

      # Plain stdlib urllib rather than `requests` -- not guaranteed to be
@@ -149,10 +186,25 @@ jobs:
          existing_assets = {a["name"]: a["id"] for a in release.get("assets", [])}

          assets = [
+              ("firmware-devkit_esp32c6.bin", "/tmp/release-assets/firmware-devkit_esp32c6.bin"),
+              ("firmware-xiao_esp32c6.bin", "/tmp/release-assets/firmware-xiao_esp32c6.bin"),
+              ("firmware-ee02.bin", "/tmp/release-assets/firmware-ee02.bin"),
+              # Rename-bridge duplicates for devices still on old firmware
+              # reporting the bare "devkit"/"xiao" board names -- see the
+              # build steps above. Safe to remove once no fielded device
+              # reports the bare name anymore.
              ("firmware-devkit.bin", "/tmp/release-assets/firmware-devkit.bin"),
              ("firmware-xiao.bin", "/tmp/release-assets/firmware-xiao.bin"),
          ]
          for name, path in assets:
+              if not os.path.exists(path):
+                  # Expected for firmware-ee02.bin while that build is
+                  # still allowed to fail (continue-on-error, see the
+                  # build step's own comment) -- publish whatever boards
+                  # did build rather than crashing the whole release over
+                  # a known, tracked gap.
+                  print(f"Skipping {name}: build did not produce {path}")
+                  continue
              if name in existing_assets:
                  del_status, _ = req("DELETE", f"/releases/{release_id}/assets/{existing_assets[name]}")
                  print(f"Removed existing asset {name} (status {del_status})")
@@ -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,41 @@ 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" bash -s <<'REMOTE'
+          set -e
+          cd ~/espresso-frame
+          docker compose down --remove-orphans
+          docker compose pull
+          # "down" returning doesn't guarantee the OS/docker-proxy has
+          # actually released port 8420 yet -- an immediate "up -d" right
+          # after (especially with "pull" a no-op because the image was
+          # already cached) can lose that race and fail with "port is
+          # already allocated", even though the exact same "up -d" run a
+          # few seconds later succeeds every time. Retry instead of
+          # guessing at a fixed sleep long enough to always cover it.
+          for i in $(seq 1 10); do
+            if docker compose up -d; then
+              exit 0
+            fi
+            echo "docker compose up -d failed (attempt $i/10) -- retrying in 3s"
+            sleep 3
+          done
+          echo "docker compose up -d did not succeed after 10 attempts"
+          exit 1
+          REMOTE
@@ -10,6 +10,9 @@ firmware/dependencies.lock
 firmware/build_xiao/
 firmware/sdkconfig.xiao_local
 firmware/sdkconfig.xiao_local.old
+firmware/build_ee02/
+firmware/sdkconfig.ee02_local
+firmware/sdkconfig.ee02_local.old

 # Python server
 server/__pycache__/
@@ -17,6 +20,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,4 +37,8 @@ server/docker-compose.yml
 .idea/
 *.swp
 .DS_Store
-.claude/
+.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/
@@ -0,0 +1,94 @@
+# 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).
+- [`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.
@@ -1,9 +1,12 @@
 # ESPresso Frame

-A DIY e-ink photo frame: an ESP32-C6 pulls photos from your
-[Immich](https://immich.app) library and displays them on a 7.3" full-color
+A DIY e-ink photo frame: an ESP32 board pulls photos from your
+[Immich](https://immich.app) library and displays them on a full-color
 e-paper panel, waking on a timer to refresh and spending the rest of its
-time in deep sleep.
+time in deep sleep. The original build is a 7.3" panel on an ESP32-C6;
+a larger 13.3" panel on Seeed's EE02 (ESP32-S3) is supported
+server-side, but its firmware driver isn't working yet -- see
+[`docs/hardware.md`](docs/hardware.md).

 - **No cables to a computer, no SD card shuffling.** Provisioning is a
  captive portal with a QR code drawn on the panel itself -- scan, join,
@@ -12,7 +15,9 @@ time in deep sleep.
  all the work (pulling from Immich, cropping, dithering, packing into
  the panel's exact pixel format) and hands the device a stream it can
  write straight to SPI. The ESP32-C6 has no PSRAM and not much SRAM to
-  spare -- keeping it a dumb display client is what makes that workable.
+  spare -- keeping it a dumb display client is what makes that workable
+  (the same design carries over to the ESP32-S3 board even though it
+  does have PSRAM, for consistency).
 - **Crops toward faces, not just the center**, using face bounding boxes
  Immich already computed for its own People feature -- no bundled face
  detector.
@@ -21,26 +26,32 @@ time in deep sleep.

 ## Hardware

- 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
+- ESP32-C6 dev board (8MB flash), or Seeed's XIAO ESP32-C6 (production
+  board) -- both drive the panel below.
+- [Waveshare 7.3" E Ink Spectra 6 (E6)](https://www.waveshare.com/7.3inch-e-paper-hat-e.htm) panel -- 800x480, 6-color, SPI.
+- Experimental, not yet working: [Waveshare 13.3" E Ink Spectra 6](https://www.waveshare.com/13.3inch-e-paper-hat-plus-e.htm)
+  (1600x1200) on [Seeed's EE02](https://www.seeedstudio.com/XIAO-ePaper-DIY-Kit-EE02-for-13-3-Spectratm-6-E-Ink.html)
+  (ESP32-S3) -- server-side support exists, but the firmware driver's
+  panel init sequence isn't ported from vendor code yet.

-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

 1. **[`server/`](server/)** -- run the FastAPI server first (Docker
   Compose, points at your Immich instance). See
   [`server/README.md`](server/README.md).
-2. **[`firmware/`](firmware/)** -- build and flash the ESP32-C6, then
+2. **[`firmware/`](firmware/)** -- build and flash the board, then
   scan the QR codes it draws on first boot to provision it. See
   [`firmware/README.md`](firmware/README.md).

 ## Repo layout

 ```
-firmware/   ESP-IDF project for the ESP32-C6
+firmware/   ESP-IDF project (ESP32-C6 devkit/xiao boards, ESP32-S3 ee02)
 server/     FastAPI server: Immich -> crop/dither/pack -> the frame
 docs/       Wiring and architecture notes
 ```
@@ -3,14 +3,15 @@
 Two independent pieces talk over HTTP or HTTPS (the server itself always
 speaks plain HTTP; HTTPS means a reverse proxy in front of it, see
 [`firmware/README.md`](../firmware/README.md#http-vs-https)) on the local
-network: the ESP32-C6 firmware, and a small FastAPI server that sits
-between it and Immich.
+network: the ESP32 firmware (ESP32-C6 for the devkit/xiao boards,
+ESP32-S3 for ee02 -- see [`docs/hardware.md`](hardware.md)), and a small
+FastAPI server that sits between it and Immich.

 ```mermaid
 sequenceDiagram
    participant Immich
    participant Server as ESPresso Frame Server
-    participant Frame as ESP32-C6 Frame
+    participant Frame as ESP32 Frame

    Note over Frame: First boot / never provisioned
    Frame->>Frame: Generate AP SSID/password, draw QR + config QR on panel
@@ -22,18 +23,18 @@ 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-->>Frame: 192,000 raw bytes, streamed
+    Server->>Server: Composite every widget's region onto one canvas,<br/>then enhance/overlay/quantize (dither)/pack 4bpp once
+    Server-->>Frame: packed 4bpp bytes, streamed<br/>(192,000 for the 7.3" panel; sized to whichever<br/>panel this frame's device reports, see Frame.panel_type)
    Frame->>Frame: Write to panel SPI buffer, compute CRC32
    alt CRC unchanged since last physical refresh
        Frame->>Frame: Skip refresh (nothing visually changed)
@@ -45,6 +46,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,
@@ -72,8 +84,9 @@ sequenceDiagram
     once).
   - Fetch the frame and write it into the panel's SPI buffer
     (`epd_write_frame()`), computing a CRC32 as it streams -- never
-     buffering the full ~192KB frame in RAM. The panel driver refuses to
-     write a short/wrong-size response into the buffer at all, so a
+     buffering the full packed frame in RAM (~192KB for the 7.3" panel;
+     proportionally more for the 13.3" panel). The panel driver refuses
+     to write a short/wrong-size response into the buffer at all, so a
     truncated fetch can't corrupt what's already there.
   - Compare the new CRC32 against the last one that was actually
     refreshed onto the panel (persisted in NVS). If it matches -- the
@@ -91,9 +104,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.
@@ -106,7 +119,9 @@ git history). Decoding a JPEG, then resizing/dithering/quantizing it to
 the panel's 6-color palette, would be expensive on-device in both memory
 and battery. Instead, the server does all of that with Pillow and hands
 the frame a pre-packed, ready-to-stream buffer -- the device never
-decodes an image at all.
+decodes an image at all. The ee02 board's ESP32-S3 does have PSRAM, but
+the same server-side design applies there too, for consistency and
+battery reasons rather than because the C6's memory limit forces it.

 ## Why face detection isn't run on-device (or even on the server)

@@ -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
@@ -152,3 +152,123 @@ photo. A full-color refresh on this panel takes 15-30+ seconds and draws
 more current than deep sleep by a wide margin -- expect battery life (if
 not running from USB power) to be dominated by refresh frequency, not
 sleep current.
+
+## Board identifiers
+
+Each board reports a name to the server (`X-Frame-Board`,
+`CONFIG_FRAME_BOARD_NAME`) that's chip-qualified rather than the plain
+`devkit`/`xiao` older firmware used -- `devkit_esp32c6`, `xiao_esp32c6`,
+`ee02` (see below). This changed once a second XIAO-based board (EE02,
+an ESP32-S3) existed and "xiao" alone stopped disambiguating hardware.
+The server keeps accepting the old bare names indefinitely, since
+already-flashed devices can't be retroactively renamed.
+
+## 13.3" Spectra 6 panel on Seeed's EE02 board (panel driver ported, `ee02` builds end-to-end; unverified on real hardware)
+
+A second panel size is supported server-side (the web UI shows a
+read-only "Panel: 13.3\" Spectra 6" once a frame's device reports
+itself as `ee02`), and **the panel driver itself is now real and
+compiles clean** -- `firmware/components/epd13in3e`'s init/LUT/refresh
+register sequence is a line-for-line port of Waveshare's own reference
+drivers for this exact panel+controller, confirmed identically across
+three independent vendor sources (Waveshare's RaspberryPi/c and ESP32
+drivers for this panel, plus Waveshare's own ESP-IDF example for their
+ESP32-S3-ePaper-13.3E6 driver board -- a different carrier than EE02,
+but the same panel/controller, hence the same command bytes). See that
+component's own top comment for details, and
+`server/app/image_pipeline.py`'s `PANEL_WIRE_TRANSPOSE` for a load-bearing
+correction that came with it: the panel's SPI wire raster is a *native
+1200x1600 (portrait)* raster, rotated 90 degrees from the panel's
+1600x1200 landscape mount/marketing size -- getting that backwards
+doesn't just rotate the image, it shreds it (1600x1200 and 1200x1600
+don't share a row stride).
+
+**A full `ee02` build now succeeds** (verified locally with a native,
+non-Docker ESP-IDF v6.0 install -- see
+`.claude/skills/build-firmware/SKILL.md`); `firmware/main/{back,next,combo}_button.c`
+used to call `esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown()`, an
+ESP32-C6-only deep-sleep GPIO-wakeup API (gated by
+`SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP`, which ESP32-S3's
+`soc_caps.h` doesn't define) with no ESP32-S3 fallback path. Each of the
+three button files now branches on that same capability macro: the
+ESP32-C6 path (devkit/xiao) is untouched, and a new ESP32-S3 path uses
+`esp_sleep_enable_ext1_wakeup_io()` (not the non-`_io()`
+`esp_sleep_enable_ext1_wakeup()`, which resets any previously-registered
+mask -- the `_io()` variant is additive, confirmed by reading
+`esp_hw_support/sleep_modes.c`, so the three button files can each keep
+registering their own GPIO independently, no combined-mask coordination
+needed) plus `esp_sleep_get_ext1_wakeup_status()` for the wake-cause
+check. The original C6 EXT1 attempt was rejected on hardware because
+its pull resistor didn't hold across the RTC_PERIPH power-down (see
+`firmware/main/next_button.c`'s `next_button_init()` comment) -- tracing
+the same code path for ESP32-S3 shows `gpio_config()`'s `pull_up_en`
+(already used by all three button files) delegates to
+`rtc_gpio_pullup_en()` for RTC-capable pins on every non-original-ESP32
+target (confirmed in `esp_driver_gpio/gpio.c`: `GPIO_RTCIO_ARE_INDEPENDENT`
+is 1 for both C6 and S3, meaning the digital and RTC pull registers are
+independent hardware and `gpio_config()` already sets the RTC one), so
+the pull-up should already survive the same power-down on ESP32-S3
+without any extra `rtc_gpio_*` calls. That reasoning is verified against
+IDF source, **not against real EE02 hardware** -- a clean compile
+confirms the code builds and links, not that it's actually
+spurious-wakeup-free on a real board. CI's
+`firmware-build-check.yml`/`firmware-release-build.yml`
+`continue-on-error` on this board's step is intentionally still in place
+until that hardware verification happens.
+
+Confirmed so far:
+
+- Panel: [Waveshare 13.3" e-Paper (E) Spectra 6](https://www.waveshare.com/13.3inch-e-paper-hat-plus-e.htm) --
+  1600x1200 mount size, 270.40x202.80mm, same 6-ink Spectra family as
+  the 7.3" panel (and, now vendor-confirmed, the identical 4-bit nibble
+  color codes). Full refresh ~19s. SPI wire raster is 1200x1600 (see
+  above).
+- Board: [Seeed's EE02](https://www.seeedstudio.com/XIAO-ePaper-DIY-Kit-EE02-for-13-3-Spectratm-6-E-Ink.html) --
+  a XIAO ESP32-S3 Plus (16MB flash, 8MB PSRAM) socketed into a dedicated
+  driver PCB, one reset + three user buttons, JST 2.0mm battery
+  connector with built-in charging IC.
+- Wiring (source: [github.com/rkaramandi/esphome-seeed-ee02](https://github.com/rkaramandi/esphome-seeed-ee02), a community integration, not Seeed's own schematic --
+  treat as a starting point, confirm before relying on it; Waveshare's
+  own ESP32-S3-ePaper-13.3E6 example uses different GPIO numbers, but
+  that's for Waveshare's own driver board, a different carrier than
+  EE02, so it doesn't apply here). Unlike epd7in3e's single chip-select,
+  this panel is driven as two halves sharing one CLK/MOSI/DC/RST/BUSY bus
+  with independent chip-selects -- now confirmed by the real driver code
+  too (master = left half, slave = right half of each row).
+
+  | Signal | GPIO | Kconfig option |
+  | --- | --- | --- |
+  | CLK | 7 | `EPD_PIN_CLK` |
+  | MOSI | 9 | `EPD_PIN_MOSI` |
+  | CS (master half) | 44 | `EPD_PIN_CS_MASTER` |
+  | CS (slave half) | 41 | `EPD_PIN_CS_SLAVE` |
+  | DC | 10 | `EPD_PIN_DC` |
+  | RST | 38 | `EPD_PIN_RST` |
+  | BUSY | 4 | `EPD_PIN_BUSY` |
+  | Panel power-enable | 43 | `EPD_PIN_POWER_EN` |
+
+  User buttons are reportedly at GPIO 2/3/5, but which physical button
+  maps to which logical role (next/back/menu) still isn't confirmed. The
+  firmware's button Kconfig options (`FRAME_NEXT_BUTTON_GPIO` etc.,
+  `firmware/main/Kconfig.projbuild`) now range to GPIO -1 to 21 under
+  `IDF_TARGET_ESP32S3` (the ESP32-S3's own ext1-wakeup-capable RTC-IO
+  range) instead of the ESP32-C6-shaped -1 to 7, so GPIO 2/3/5 fit
+  regardless -- but `firmware/sdkconfig.ee02` still deliberately doesn't
+  override the defaults inherited from the C6 boards (GPIO 2/0/1) until
+  the role mapping above is confirmed.
+
+  SPI clock is reportedly reliable only up to 2MHz on this
+  panel/board per the community ESPHome integration (vs. epd7in3e's 4MHz
+  default) -- see `firmware/sdkconfig.ee02`. Waveshare's own
+  ESP32-S3-ePaper-13.3E6 example defaults to 10MHz, but that's a
+  different carrier board, so it's a data point to try once real EE02
+  hardware exists, not a reason to bump the current conservative default
+  blind.
+
+Remaining unknowns before trusting this on real hardware: whether the
+ESP32-S3 button-wakeup path above actually avoids a spurious-instant-wakeup
+on a real board (not just compiles), the button-to-role mapping, the
+wiring table (community-sourced, not official), and
+`PANEL_WIRE_TRANSPOSE`'s rotation *direction* (`ROTATE_90` vs
+`ROTATE_270` -- a physical-assembly fact no vendor driver encodes, see
+that dict's own comment in `image_pipeline.py`).
@@ -0,0 +1,584 @@
+# 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 per-mode `Frame` columns
+it left behind (`album_id`, `calendar_*`, `whiteboard_*`, etc.) were
+dropped in migration 41, once every phase of the rollout had shipped
+(see "Known gaps" below for what's still open).
+
+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.
+  Also carries `font_scale` (one of `panel_style.FONT_SCALE_CHOICES` --
+  `1.0`/`1.25`/`1.5`, labeled Normal/Large/X-Large), a per-widget
+  legibility control: calendar and tasks widgets pack in the most body
+  text at the smallest default sizes, so their gear-icon dialogs get a
+  "Text size" card (`_widget_font_scale_fields.html`) the other types
+  don't. Same Widget-level-property-not-config-field reasoning as
+  border, and its own `POST .../widgets/{id}/font-scale` endpoint for
+  the same reason. `panel_style.scaled_size(value, font_scale)` is the
+  one shared multiply-and-round point every classic (`calendar_render.py`)
+  and modern (`html_render.py`/`calendar_html_render.py`) size calc
+  routes through immediately after its own tier lookup/floor, so row
+  heights and per-view row caps (already derived from the font size, not
+  a fixed constant) automatically re-fit around the bigger text instead
+  of overflowing their box.
+- 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. These tiers are pixel-size constants
+tuned against the 7.3" panel specifically; they aren't re-tuned or
+verified yet for the 13.3" panel's larger native resolution (see
+`docs/hardware.md`'s EE02 section) -- a widget's *grid footprint* (cell
+count) works the same on either panel, but its rendered legibility at
+that footprint's actual pixel size hasn't been checked on the bigger
+panel.
+
+### "Modern" render style (experimental)
+
+Every widget type except photos has a `render_style` column (`"classic"`
+default | `"modern"`) that swaps its hand-drawn PIL primitives for an
+HTML/CSS render: a Jinja2 template (`app/templates/widget_html/`) drawn
+through a persistent headless-Chromium browser (`app/html_render.py`,
+Playwright) instead of `ImageDraw` -- gradients, shadows, and soft icon
+shading PIL can't easily do. Calendar's own modern-style builders (all
+four view modes) live in `app/calendar_html_render.py` rather than
+`html_render.py` itself, mirroring `calendar_render.py`'s own separation
+from the simpler widget types.
+
+Every modern-style builder runs its own `ordered_dither` (Bayer/ordered,
+not Floyd-Steinberg) before returning, committing the widget to exact
+palette colors *before* compositing -- safe to mix with photo/other
+classic-rendered widgets on the same frame without a Floyd-Steinberg
+seam at the boundary, because ordered dithering has no cross-pixel error
+term the way Floyd-Steinberg's diffusion does (see `html_render.py`'s
+module docstring). No `Frame`-level dithering setting was needed to make
+this work.
+
+Not offered for the **photos** widget -- a real photograph isn't a
+synthesized dashboard card, and photos has a different concern instead:
+its own independent palette/dithering strength (`Frame.photo_palette_rgb`
+/ `photo_dither_strength`, a second "Photos configuration" card in
+Advanced Configuration, separate from the main `palette_rgb`/
+`dither_strength` every other widget uses). `widgets/photos.py`'s
+`render()` quantizes itself against these before returning, so a frame
+can tune the rest of its widgets' look (e.g. a calibrated palette for
+modern-style dashboard widgets) independently of what actually looks
+best for real photographs, with no `render_panel` changes needed --
+see that module's own docstring for the one small, accepted edge case
+(a border on a photos widget whose palette genuinely diverges from the
+frame's main one).
+
+Playwright/Chromium is a real, heavyweight runtime dependency imported
+lazily only when a widget actually uses modern style. Its browser binary
+is fetched by `start.sh` at container startup rather than baked into the
+image (see `server/Dockerfile`'s own comment) -- a single ~181MB
+`chrome-headless-shell` binary can't be split across Docker layers the
+way this project's pip/npm installs were, and confirmed-failed to push
+to the registry as a build-time layer; cached on the `/data` volume
+(`PLAYWRIGHT_BROWSERS_PATH`) so only the very first boot on a fresh
+volume actually downloads it. Still real-panel-unverified -- treat every
+"modern" style as experimental regardless of deploy status.
+
+Per-widget-type notes:
+
+- **weather**: `current`/`daily` modes only -- `hourly`/`multi_city`
+  always render classic regardless of this setting (see the Weather
+  widget section below).
+- **calendar**: all four view modes (agenda/today_tomorrow/week/month)
+  have a modern builder -- the only widget type with full modern-style
+  coverage from the start, rather than a partial rollout like weather's.
+  Month view's "falls back to agenda below a size threshold" behavior
+  (`_month_view_fits`) is honored identically in both styles.
+- **battery/text/tasks**: full coverage (both battery modes; text reuses
+  its own `_fit()` shrink-to-fit sizing logic, only the drawing differs).
+- **static image/whiteboard**: modern style is the *first* visual chrome
+  either widget type has ever had (classic draws the image with zero
+  frame/card at all) -- a rounded-corner, shadowed card
+  (`framed_image.html.jinja`, shared between the two) wrapping the
+  already-composed image. Left alone by the "bold minimal" pass below --
+  it never had the reskinned-classic problem the other widgets did.
+
+### "Bold minimal": a real redesign, not just a reskin
+
+The initial modern-style rollout (above) mostly translated each widget's
+*existing* classic layout into HTML/CSS -- same gradient header banner,
+same rounded-shadowed white card, prettier chrome around an unchanged
+composition. A second pass reworked weather (`current`/`daily`),
+calendar (all four views), tasks, and battery into an actual different
+visual language, picked from several divergent directions rendered
+through the real pipeline and reviewed with the maintainer (not chosen
+unilaterally -- see the "Reverted e-ink quantization attempt"-style
+caution about visual changes needing more than one look). Text and
+static/whiteboard were deliberately left as they were (see their notes
+just above) -- text already had zero chrome and its styling is
+user-authored content, not this system's to redesign; the framed-image
+card was already minimal.
+
+What changed, as a consistent language across every redesigned widget:
+
+- **No card.** No rounded-corner white box, no drop shadow, no outer
+  border -- content sits directly on the shared white canvas. `theme
+  ["radius"]`/`theme["shadow"]` are now unused by every redesigned
+  widget's builder (still resolved, for signature uniformity with
+  `resolve_theme`, but nothing reads them) -- a theme's radius/shadow
+  fields now only affect the *un*-redesigned modern widgets (static
+  image/whiteboard's `framed_image.html.jinja`).
+- **A slim accent rule instead of a gradient banner.** Every widget that
+  used to have a colored header bar with white text on it (weather's
+  `build_daily`, tasks, calendar's four views) now has a thin (~4-8px)
+  accent-colored rounded rule, with the header text as plain ink below
+  it instead of white text on top of it -- only that thin rule dithers
+  at the theme's richer `accent_amplitude` via `ordered_dither_regions`
+  now, not the header text sitting on it, which reads as a legibility
+  improvement, not just a visual one (see "Rich accent hues" below).
+- **A dominant hero value, not a centered icon+number of equal weight.**
+  Weather's `build_current` and battery's icon+percent used to be drawn
+  at roughly the same size, centered as a unit; both now put the numeric
+  value (temperature / battery percent) at a clearly dominant size, with
+  the icon small and secondary above it -- closer to a phone home-screen
+  widget than a dashboard tile.
+- **Padding/type sizes as a proportion of widget size, clamped to a
+  floor/ceiling, not a fixed pixel value.** So a 1-2 grid-cell widget
+  doesn't get comically large padding relative to its content, and a
+  near-full-panel widget doesn't get comically small padding either --
+  see `html_render._clamp` and every redesigned `build_*`'s own
+  `pad`/size calculations (`base = min(target_w, target_h)`, then a
+  fraction of `base` clamped to tuned floor/ceiling values).
+
+**A hairline color this palette can't actually render.** Auditing the
+month view's grid during this pass turned up a real, pre-existing bug
+carried forward unnoticed since the very first modern-style rollout:
+`.day-cell`/`.day-section`/`.col` divider borders used a pale gray
+(`#e2e6ec`) -- but `DEFAULT_PALETTE_RGB` has no gray in it at all (black/
+white/yellow/red/blue/green only), so a color that close to white always
+nearest-matches to pure white regardless of Bayer bias, at any amplitude
+-- confirmed by sampling actual rendered pixels, not just eyeballing a
+screenshot. The month grid's week-row dividers now use real solid black
+(`RULE`-equivalent, matching how the *classic* PIL renderer always drew
+them -- see `calendar_render.RULE`); the day-section/week-column dividers
+were simply dropped instead, since the accent rule + spacing at the
+start of the next section/column already read as a clear boundary
+without a line at all once you could actually render one.
+
+### Themes for modern-style widgets
+
+`Frame.theme` (String, default `"classic"`, one Advanced Configuration
+`<select>`) picks a curated visual preset for every modern-style widget
+on that frame -- font family, corner radius, drop shadow, and an accent
+hue for widgets with a header/accent region. Presets live in
+`app/theme_tokens.py`'s `THEMES` dict; `resolve_theme(theme_name,
+widget_kind, palette_rgb)` turns one into concrete, ready-to-render
+values (`accent_hex`/`accent_hex_dark`, resolved `font_regular`/
+`font_bold` file paths, `radius`, `shadow`, `accent_amplitude`). Inspired
+by [Tesserae](https://github.com/dmellok/tesserae)'s (AGPL-3.0) own
+three-layer CSS custom-property theme system -- this is an original
+reimplementation of that *architecture*, not a copy of its token file
+(see this repo's `CLAUDE.md` on copyleft dependencies).
+
+**What a theme actually changes, in practice**: the accent color (now a
+slim rule rather than a full header band -- see "Bold minimal" above) is
+still the most visible change on widgets that have one, but `font_family`
+applies to *every* text element in the widget, not just the header title
+-- day labels, temperatures, task rows, event times, day numbers all
+switch fonts too (e.g. "Moss" is serif, "Ochre" a slab serif), often
+more noticeable than the accent color on text-heavy widgets. `radius`/
+`shadow` only affect static image/whiteboard's card now (every other
+modern-style widget dropped its card in the "bold minimal" pass); text
+never used them (no card from the start) and weather/battery/tasks/
+calendar no longer have a card for them to apply to either.
+
+**A theme is purely stylistic, never functional color-coding.** Battery's
+charge-level red/yellow/green, calendar/tasks' per-owner event color
+chips, and text's user-authored inline run colors are status/identity
+signals, not style choices -- no theme may recolor them, and every
+`build_*`/`resolve_theme` call site that touches those stays on its own
+existing logic untouched. Text's own per-widget `font_family` setting
+(a user's explicit content-level choice, same carve-out reasoning) is
+similarly never overridden by a theme -- `build_text` accepts a
+`theme_name` param for signature uniformity with every other modern-
+style builder but deliberately ignores it.
+
+**Rich accent hues, not just the 6 exact panel inks.** A theme's
+`accent_hex` can be any arbitrary color (e.g. terracotta, moss, slate) --
+`html_render.ordered_dither_regions(rendered, palette_rgb,
+base_amplitude, accent_regions=[(rect, amplitude), ...])` dithers the
+whole widget at the existing safe default (`ordered_dither`'s tuned 48,
+unchanged, still icon/text-legible) and then *separately* re-dithers
+just the accent rectangle (a header bar's already-computed pixel rect)
+at a theme's higher `accent_amplitude` (~130) and pastes it back. Safe
+to do per-region for the same reason `ordered_dither` itself is safe
+per-widget: ordered (Bayer) dithering has no cross-pixel error term, so
+a region's result depends only on its own pixels. A single higher
+amplitude applied to the *whole* widget instead was tried and rejected --
+it washes out pale content (a weather icon's white cloud body nearly
+vanished in testing); confining the higher amplitude to just the accent
+rect avoids that while still letting the rect approximate a rich hue via
+denser stippling instead of flatly snapping to one nearest ink (what
+happens to a rich hue at the base amplitude).
+
+**"classic" is a deliberately no-visual-change default.** Its
+`accent_hex` is `None`, meaning "keep this widget kind's own pre-theme
+look exactly": weather's header was always a fixed blue gradient (now
+`theme_tokens._CLASSIC_WEATHER_GRADIENT`, byte-identical to the old
+module-level `ACCENT_START`/`ACCENT_END` constants this system
+replaced); tasks/calendar's header was always a flat single ink resolved
+through `panel_style.THEME` (still is, just via `resolve_theme` now).
+Widget kinds with no ink of their own (battery/text/static/whiteboard)
+fall back to black, though none of their templates currently have an
+accent-colored surface for it to visibly affect.
+
+Which widgets get the richer accent-region treatment: weather's
+`build_daily` (the slim rule, when `city_label` is set), tasks, and
+calendar's four view builders -- each computes its own small accent-rule
+pixel rect (a fixed-height band, not the old full header_h) and passes
+just that to `ordered_dither_regions`. Weather's `build_current` and
+battery have no accent surface at all (no header of any kind -- see
+"Bold minimal" above) and static/whiteboard's shared `build_framed_image`
+is unchanged from the original rollout; all three call plain
+`ordered_dither` with no accent region.
+
+## 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.
+
+**Render style** (`WeatherWidgetConfig.render_style`, `"classic"` default
+| `"modern"`, experimental) -- see "Modern render style" above; weather's
+own modern coverage is `current`/`daily` only, `hourly`/`multi_city`
+always render classic regardless of this setting.
+
+`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
+
+The original 8-phase rollout plan's last phase is done: migration 41
+dropped the legacy per-mode `Frame` columns (`mode`, `album_id`,
+`current_asset_id`, all `calendar_*`, all `whiteboard_*`, `queue`, etc.)
+-- see its own docstring in `app/migration.py` for the raw-SQL backfill
+safety net that ran first, and `server/README.md` no longer describes
+photos/calendar/whiteboard as per-frame "modes".
+
+Still open:
+
+- Whiteboard rendering is tagged **(alpha)** in the UI -- not fully
+  reliable yet, treat it as experimental if extending it.
@@ -1,6 +1,10 @@
 # ESPresso Frame Firmware

-ESP-IDF firmware for the ESP32-C6. On first boot it provisions itself over
+ESP-IDF firmware for the ESP32-C6 (devkit/xiao boards, 7.3" panel) or
+ESP32-S3 (ee02 board, 13.3" panel -- see
+[Building for Seeed's EE02](#building-for-seeeds-ee02-esp32-s3--133-panel-driver-ported-ee02-builds-end-to-end-unverified-on-real-hardware)
+below; it builds end-to-end now, but is still unverified on real EE02
+hardware). On first boot it provisions itself over
 a WiFi captive portal; after that it wakes on a timer, fetches an
 already-processed frame from the [server](../server/), streams it straight
 to the panel over SPI, and goes back to deep sleep.
@@ -48,6 +52,40 @@ never clobbers the other:
 (`./build_for_board.sh devkit ...` does the same for the dev board --
 equivalent to a plain `idf.py`, just consistent with the XIAO invocation.)

+### Building for Seeed's EE02 (ESP32-S3 + 13.3" panel, driver ported; `ee02` builds end-to-end, unverified on real hardware)
+
+EE02 is a different chip (ESP32-S3, not C6), so it needs `set-target
+esp32s3` instead of `esp32c6`, and its own partition table/flash-size
+Kconfig sized for its 16MB flash
+([`partitions_ee02.csv`](partitions_ee02.csv)):
+
+```
+./build_for_board.sh ee02 set-target esp32s3
+./build_for_board.sh ee02 build
+```
+
+**This now compiles and links clean end-to-end**, verified locally with
+a native, non-Docker ESP-IDF v6.0 install (see
+`.claude/skills/build-firmware/SKILL.md`).
+`firmware/components/epd13in3e`'s panel init/LUT/refresh register
+sequence is a real, vendor-confirmed port (see that component's own top
+comment and
+[`docs/hardware.md`](../docs/hardware.md#133-spectra-6-panel-on-seeeds-ee02-board-panel-driver-ported-ee02-builds-end-to-end-unverified-on-real-hardware)
+for the vendor sources and the load-bearing native-raster-orientation
+correction that came with it). `main/{back,next,combo}_button.c` used to
+call an ESP32-C6-only deep-sleep GPIO-wakeup API with no ESP32-S3
+fallback; each now branches on `SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP`
+to keep the ESP32-C6 path (devkit/xiao) untouched while using
+`esp_sleep_enable_ext1_wakeup_io()` on ESP32-S3 -- see `docs/hardware.md`'s
+same section for why the additive `_io()` variant needs no combined-mask
+coordination across the three button files, and why the pull-resistor
+concern that ruled out EXT1 wakeup on ESP32-C6 doesn't apply the same
+way here. That reasoning is confirmed against ESP-IDF source, **not
+against real EE02 hardware** -- CI's
+(`.gitea/workflows/firmware-build-check.yml`/`firmware-release-build.yml`)
+`continue-on-error` on this board's step is intentionally still in place
+until it is.
+
 ## Configuration (`idf.py menuconfig`)

 Under **ESPresso Frame Configuration**:
@@ -66,8 +104,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 +123,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
@@ -118,10 +185,9 @@ two-step setup screen:
   portal's config page (`http://192.168.4.1/` by default), for a
   one-scan shortcut once you've joined the AP.

-The config page asks for your home WiFi SSID/password, the "Tools
+The config page asks for your home WiFi SSID/password and 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 -- usually blank). Saving hands your browser
+Immich server; see below for the `https://` form). 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
@@ -183,19 +249,6 @@ certificate was actually issued for -- a bare LAN IP address
 (`https://192.168.1.50`) will fail the handshake even against a
 perfectly valid cert for a different name.

-## Access token
-
-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

 Wire a momentary push button between GPIO2 and GND (internal pull-up,
@@ -204,6 +257,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
@@ -223,7 +278,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)

@@ -262,9 +318,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.
@@ -283,8 +343,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
@@ -292,17 +353,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.

@@ -1,28 +1,42 @@
 #!/usr/bin/env bash
-# Builds/flashes for a specific board variant. This project targets two:
+# Builds/flashes for a specific board variant. This project targets three:
 #
 #   devkit  ESP32-C6-DevKitC-1 (8MB flash) -- the dev board. This is
 #           also the plain `idf.py` default (sdkconfig/build/), so this
 #           script's devkit mode is mostly for symmetry -- normal
-#           `idf.py build`/`flash` work fine too.
+#           `idf.py build`/`flash` work fine too. Reports itself as
+#           "devkit_esp32c6" (see main/Kconfig.projbuild).
 #   xiao    Seeed XIAO ESP32-C6 (4MB flash) -- the production board.
+#           Reports itself as "xiao_esp32c6".
+#   ee02    Seeed EE02 (XIAO ESP32-S3 Plus, 16MB flash) + 13.3" Spectra 6
+#           panel -- a genuinely different chip target (esp32s3, not
+#           esp32c6), unlike xiao's same-chip Kconfig-only variant.
+#           Reports itself as "ee02". NOTE: the epd13in3e driver this
+#           board links (firmware/components/epd13in3e) doesn't actually
+#           work yet -- its panel init/LUT/refresh register sequence is
+#           still unported from vendor demo code (see that component's
+#           own top-of-file comment); building for ee02 will fail to
+#           compile until that lands, by design (a deliberate #error, not
+#           a bug in this script).
 #
-# The two need different partition tables (the XIAO's 4MB doesn't fit
-# the dev board's two 2MB OTA app slots -- see partitions_xiao.csv,
-# 1.875MB slots instead) and a different flash-size Kconfig. Rather
-# than hand-editing the shared sdkconfig back and forth (fragile, easy
-# to leave it in the wrong state for whichever board you flash next),
-# each board gets its own build directory and its own generated
-# sdkconfig, seeded from sdkconfig.defaults (shared) with the board's
-# override file layered on top via ESP-IDF's own SDKCONFIG_DEFAULTS
-# mechanism. Switching boards is just switching which one you invoke --
-# neither ever touches the other's config or build output.
+# The three need different partition tables (each flash size needs its
+# own OTA app-slot sizing -- see partitions_xiao.csv/partitions_ee02.csv)
+# and different flash-size Kconfig. Rather than hand-editing the shared
+# sdkconfig back and forth (fragile, easy to leave it in the wrong state
+# for whichever board you flash next), each board gets its own build
+# directory and its own generated sdkconfig, seeded from
+# sdkconfig.defaults (shared) with the board's override file layered on
+# top via ESP-IDF's own SDKCONFIG_DEFAULTS mechanism. Switching boards is
+# just switching which one you invoke -- none ever touches another's
+# config or build output.
 #
 # Usage:
 #   ./build_for_board.sh xiao build
 #   ./build_for_board.sh xiao flash -p /dev/ttyUSB0
 #   ./build_for_board.sh xiao flash monitor -p /dev/ttyUSB0
 #   ./build_for_board.sh devkit build
+#   ./build_for_board.sh ee02 set-target esp32s3   # first build only, see below
+#   ./build_for_board.sh ee02 build
 #
 # Defaults to "build" if no idf.py subcommand is given.

@@ -32,7 +46,7 @@ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$script_dir"

 if [ $# -lt 1 ]; then
-    echo "Usage: $0 <devkit|xiao> [idf.py args...]" >&2
+    echo "Usage: $0 <devkit|xiao|ee02> [idf.py args...]" >&2
    exit 1
 fi
 board="$1"
@@ -49,8 +63,13 @@ case "$board" in
        sdkconfig_path="$script_dir/sdkconfig"
        defaults="$script_dir/sdkconfig.defaults"
        ;;
+    ee02)
+        build_dir="$script_dir/build_ee02"
+        sdkconfig_path="$script_dir/sdkconfig.ee02_local"
+        defaults="$script_dir/sdkconfig.defaults;$script_dir/sdkconfig.ee02"
+        ;;
    *)
-        echo "Unknown board '$board' -- expected 'devkit' or 'xiao'" >&2
+        echo "Unknown board '$board' -- expected 'devkit', 'xiao', or 'ee02'" >&2
        exit 1
        ;;
 esac
@@ -0,0 +1,13 @@
+# SRCS is conditional on which board's panel this build targets -- see
+# epd7in3e/CMakeLists.txt's identical comment (the two components mirror
+# each other: exactly one contributes actual object files/symbols to any
+# given build, the other is required but empty).
+if(CONFIG_FRAME_PANEL_EE02_13IN3)
+    set(srcs "epd13in3e.c")
+else()
+    set(srcs "")
+endif()
+
+idf_component_register(SRCS ${srcs}
+                       INCLUDE_DIRS "include"
+                       PRIV_REQUIRES esp_driver_spi esp_driver_gpio)
@@ -0,0 +1,65 @@
+menu "E-Paper Display (epd13in3e) Configuration"
+
+    config EPD_PIN_CLK
+        int "SPI CLK (SCLK) GPIO"
+        default 7
+        help
+            Defaults sourced from a community-verified ESPHome
+            integration for this exact board
+            (github.com/rkaramandi/esphome-seeed-ee02) -- NOT an
+            official Waveshare/Seeed reference driver (see
+            firmware/components/epd13in3e/epd13in3e.c's top comment,
+            which is about the still-unknown panel init/LUT/refresh
+            register sequence, a separate and larger unknown than this
+            pinout). Override if your own board wiring differs.
+
+    config EPD_PIN_MOSI
+        int "SPI MOSI (DIN) GPIO"
+        default 9
+
+    config EPD_PIN_CS_MASTER
+        int "SPI CS (master half) GPIO"
+        default 44
+        help
+            Unlike epd7in3e's single-CS interface, this panel is driven
+            as two halves over one shared CLK/MOSI/DC/RST/BUSY bus with
+            two independent chip-selects (master/slave) -- confirmed by
+            the same community ESPHome integration, not yet by this
+            component's own driver code (still unimplemented, see
+            epd13in3e.c).
+
+    config EPD_PIN_CS_SLAVE
+        int "SPI CS (slave half) GPIO"
+        default 41
+
+    config EPD_PIN_DC
+        int "Data/Command GPIO"
+        default 10
+
+    config EPD_PIN_RST
+        int "Reset GPIO"
+        default 38
+
+    config EPD_PIN_BUSY
+        int "Busy GPIO"
+        default 4
+
+    config EPD_PIN_POWER_EN
+        int "Panel power-enable GPIO"
+        default 43
+        help
+            No equivalent pin on epd7in3e's board -- the EE02 apparently
+            gates the panel's own power rail separately from the ESP32-S3
+            module's. Source: same community integration as the other
+            pins above.
+
+    config EPD_SPI_CLOCK_HZ
+        int "SPI clock speed (Hz)"
+        default 2000000
+        help
+            2MHz, not epd7in3e's 4MHz default -- the same community
+            integration notes higher rates were unreliable on this
+            panel/board combo. Revisit once wiring is confirmed on real
+            hardware.
+
+endmenu
@@ -0,0 +1,438 @@
+#include <string.h>
+
+#include "driver/gpio.h"
+#include "driver/spi_master.h"
+#include "esp_heap_caps.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_check.h"
+#include "esp_log.h"
+#include "esp_rom_crc.h"
+
+#include "epd13in3e.h"
+
+/* Command bytes/register values below are a line-for-line transcription of
+ * Waveshare's official reference drivers for this exact panel+controller --
+ * confirmed identical across three independent sources (RaspberryPi/c,
+ * ESP32, and the ESP32-S3-ePaper-13.3E6 ESP-IDF example; see this
+ * component's header for repo paths). Same "don't clean these up" rule as
+ * epd7in3e.c: this class of panel controller has no public datasheet, so
+ * the vendor driver is the source of truth for every byte.
+ *
+ * Unlike epd7in3e's single chip-select, this panel is driven as two
+ * independent controllers sharing one CLK/MOSI/DC/RST/BUSY bus but with
+ * separate chip-selects (EPD_PIN_CS_MASTER/EPD_PIN_CS_SLAVE) -- most init
+ * commands broadcast to both (CS_ALL), a handful of power/boost commands
+ * go only to the master (which owns the shared analog rails), and actual
+ * frame data is split per-row into a left half (master) and right half
+ * (slave), 300 bytes each out of each 600-byte row. That split is why
+ * epd_write_frame below buffers the whole frame in PSRAM before sending
+ * anything (every row needs slicing in half before either half can go out),
+ * unlike epd7in3e.c's straight single-CS passthrough streaming.
+ *
+ * Pin numbers themselves are NOT from this vendor code -- Waveshare's
+ * ESP32-S3-ePaper-13.3E6 example targets Waveshare's own driver board, a
+ * different carrier than Seeed's EE02 this project actually uses, so its
+ * GPIO numbers don't apply here. EE02's pins remain sourced from a
+ * community-verified ESPHome integration (see this component's Kconfig),
+ * not an official reference. */
+
+#define EPD_SPI_HOST SPI2_HOST
+#define EPD_SPI_CHUNK_SIZE 4096
+
+static const char *TAG = "epd13in3e";
+
+#define EPD_CHECK(expr) ESP_RETURN_ON_ERROR((expr), TAG, #expr)
+
+/* --- panel command opcodes --- */
+#define PSR             0x00
+#define PWR             0x01
+#define POF             0x02
+#define PON             0x04
+#define BTST_N          0x05
+#define BTST_P          0x06
+#define DTM             0x10 /* data transfer (frame data) */
+#define DRF             0x12 /* display refresh */
+#define CDI             0x50
+#define TCON            0x60
+#define TRES            0x61
+#define AN_TM           0x74
+#define AGID            0x86
+#define BUCK_BOOST_VDDN 0xB0
+#define TFT_VCOM_POWER  0xB1
+#define EN_BUF          0xB6
+#define BOOST_VDDP_EN   0xB7
+#define CCSET           0xE0
+#define PWS             0xE3
+#define CMD66           0xF0
+#define DEEP_SLEEP      0x07
+
+/* --- canned init parameter blobs (do NOT edit -- see top comment) --- */
+static const uint8_t PSR_V[]             = {0xDF, 0x69};
+static const uint8_t PWR_V[]             = {0x0F, 0x00, 0x28, 0x2C, 0x28, 0x38};
+static const uint8_t POF_V[]             = {0x00};
+static const uint8_t DRF_V[]             = {0x00};
+static const uint8_t CDI_V[]             = {0xF7};
+static const uint8_t TCON_V[]            = {0x03, 0x03};
+static const uint8_t TRES_V[]            = {0x04, 0xB0, 0x03, 0x20};
+static const uint8_t CMD66_V[]           = {0x49, 0x55, 0x13, 0x5D, 0x05, 0x10};
+static const uint8_t EN_BUF_V[]          = {0x07};
+static const uint8_t CCSET_V[]           = {0x01};
+static const uint8_t PWS_V[]             = {0x22};
+static const uint8_t AN_TM_V[]           = {0xC0, 0x1C, 0x1C, 0xCC, 0xCC, 0xCC, 0x15, 0x15, 0x55};
+static const uint8_t AGID_V[]            = {0x10};
+static const uint8_t BTST_P_V[]          = {0xE8, 0x28};
+static const uint8_t BOOST_VDDP_EN_V[]   = {0x01};
+static const uint8_t BTST_N_V[]          = {0xE8, 0x28};
+static const uint8_t BUCK_BOOST_VDDN_V[] = {0x01};
+static const uint8_t TFT_VCOM_POWER_V[]  = {0x02};
+
+static spi_device_handle_t s_spi;
+
+static void epd_delay_ms(uint32_t ms)
+{
+    vTaskDelay(pdMS_TO_TICKS(ms));
+}
+
+/* BUSY: LOW = busy, HIGH = idle -- same polarity/poll-interval reasoning
+ * as epd7in3e.c's identical comment (a tight 1ms-rounds-to-0-ticks poll
+ * starves the idle task badly enough to trip the watchdog). */
+static void epd_wait_busy(void)
+{
+    while (gpio_get_level((gpio_num_t)CONFIG_EPD_PIN_BUSY) == 0) {
+        epd_delay_ms(20);
+    }
+}
+
+static esp_err_t epd_spi_write(const uint8_t *data, size_t len)
+{
+    while (len > 0) {
+        size_t n = len > EPD_SPI_CHUNK_SIZE ? EPD_SPI_CHUNK_SIZE : len;
+        spi_transaction_t t = {
+            .length = n * 8,
+            .tx_buffer = data,
+        };
+        EPD_CHECK(spi_device_polling_transmit(s_spi, &t));
+        data += n;
+        len -= n;
+    }
+    return ESP_OK;
+}
+
+/* Unlike epd7in3e.c's send_command/send_data, these do NOT touch CS --
+ * this panel's two independent chip-selects (and the "broadcast to both"
+ * vs "master only" split the init sequence needs) mean CS bracketing has
+ * to be the caller's decision, not baked into the byte-send primitive. */
+static esp_err_t epd_send_command(uint8_t cmd)
+{
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_DC, 0);
+    return epd_spi_write(&cmd, 1);
+}
+
+static esp_err_t epd_send_data(const uint8_t *data, size_t len)
+{
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_DC, 1);
+    return epd_spi_write(data, len);
+}
+
+static esp_err_t epd_send_data_byte(uint8_t data)
+{
+    return epd_send_data(&data, 1);
+}
+
+static void epd_cs_both(int level)
+{
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_CS_MASTER, level);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_CS_SLAVE, level);
+}
+
+/* Sends `cmd` + its data blob to both controllers at once (most of the
+ * init sequence -- shared display-timing/power registers). */
+static esp_err_t epd_cmd_both(uint8_t cmd, const uint8_t *data, size_t len)
+{
+    epd_cs_both(0);
+    esp_err_t err = epd_send_command(cmd);
+    if (err == ESP_OK && data != NULL) {
+        err = epd_send_data(data, len);
+    }
+    epd_cs_both(1);
+    return err;
+}
+
+/* Sends `cmd` + its data blob to the master controller only -- the boost/
+ * VCOM power registers the master alone owns. */
+static esp_err_t epd_cmd_master(uint8_t cmd, const uint8_t *data, size_t len)
+{
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_CS_MASTER, 0);
+    esp_err_t err = epd_send_command(cmd);
+    if (err == ESP_OK && data != NULL) {
+        err = epd_send_data(data, len);
+    }
+    epd_cs_both(1);
+    return err;
+}
+
+/* 5-edge reset sequence (30ms each) -- per-vendor-source exact, more edges
+ * than epd7in3e.c's 3-edge/20ms reset. */
+static void epd_reset(void)
+{
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_RST, 1);
+    epd_delay_ms(30);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_RST, 0);
+    epd_delay_ms(30);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_RST, 1);
+    epd_delay_ms(30);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_RST, 0);
+    epd_delay_ms(30);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_RST, 1);
+    epd_delay_ms(30);
+}
+
+/* Power on, refresh, power off -- mirrors EPD_TurnOnDisplay()/
+ * EPD_13IN3E_TurnOnDisplay() in the reference drivers. */
+esp_err_t epd_turn_on_display(void)
+{
+    EPD_CHECK(epd_cmd_both(PON, NULL, 0));
+    epd_wait_busy();
+
+    epd_delay_ms(50);
+    EPD_CHECK(epd_cmd_both(DRF, DRF_V, sizeof(DRF_V)));
+    epd_wait_busy();
+
+    epd_delay_ms(50);
+    EPD_CHECK(epd_cmd_both(POF, POF_V, sizeof(POF_V)));
+    /* No busy-wait after POF -- matches every reference driver. */
+
+    return ESP_OK;
+}
+
+esp_err_t epd_init(void)
+{
+    gpio_config_t out_cfg = {
+        .pin_bit_mask = (1ULL << CONFIG_EPD_PIN_DC) | (1ULL << CONFIG_EPD_PIN_RST) |
+                        (1ULL << CONFIG_EPD_PIN_CS_MASTER) | (1ULL << CONFIG_EPD_PIN_CS_SLAVE) |
+                        (1ULL << CONFIG_EPD_PIN_POWER_EN),
+        .mode = GPIO_MODE_OUTPUT,
+    };
+    EPD_CHECK(gpio_config(&out_cfg));
+
+    gpio_config_t busy_cfg = {
+        .pin_bit_mask = (1ULL << CONFIG_EPD_PIN_BUSY),
+        .mode = GPIO_MODE_INPUT,
+    };
+    EPD_CHECK(gpio_config(&busy_cfg));
+
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_RST, 1);
+    epd_cs_both(1);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_POWER_EN, 0);
+
+    spi_bus_config_t bus_cfg = {
+        .mosi_io_num = CONFIG_EPD_PIN_MOSI,
+        .miso_io_num = -1,
+        .sclk_io_num = CONFIG_EPD_PIN_CLK,
+        .quadwp_io_num = -1,
+        .quadhd_io_num = -1,
+        .max_transfer_sz = EPD_SPI_CHUNK_SIZE,
+    };
+    EPD_CHECK(spi_bus_initialize(EPD_SPI_HOST, &bus_cfg, SPI_DMA_CH_AUTO));
+
+    spi_device_interface_config_t dev_cfg = {
+        .clock_speed_hz = CONFIG_EPD_SPI_CLOCK_HZ,
+        .mode = 0,
+        .spics_io_num = -1, /* both chip-selects are bit-banged by hand above */
+        .queue_size = 1,
+    };
+    EPD_CHECK(spi_bus_add_device(EPD_SPI_HOST, &dev_cfg, &s_spi));
+
+    /* Panel power-enable rail (no equivalent on epd7in3e's board -- EE02
+     * gates it separately from the ESP32-S3 module's own supply). */
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_POWER_EN, 1);
+    epd_delay_ms(10);
+
+    epd_reset();
+    epd_wait_busy();
+
+    /* Master-only: shared analog-timing register. */
+    EPD_CHECK(epd_cmd_master(AN_TM, AN_TM_V, sizeof(AN_TM_V)));
+
+    /* Broadcast: display-timing/power-sequencing registers both
+     * controllers need identically. */
+    EPD_CHECK(epd_cmd_both(CMD66, CMD66_V, sizeof(CMD66_V)));
+    EPD_CHECK(epd_cmd_both(PSR,   PSR_V,   sizeof(PSR_V)));
+    EPD_CHECK(epd_cmd_both(CDI,   CDI_V,   sizeof(CDI_V)));
+    EPD_CHECK(epd_cmd_both(TCON,  TCON_V,  sizeof(TCON_V)));
+    EPD_CHECK(epd_cmd_both(AGID,  AGID_V,  sizeof(AGID_V)));
+    EPD_CHECK(epd_cmd_both(PWS,   PWS_V,   sizeof(PWS_V)));
+    EPD_CHECK(epd_cmd_both(CCSET, CCSET_V, sizeof(CCSET_V)));
+    EPD_CHECK(epd_cmd_both(TRES,  TRES_V,  sizeof(TRES_V)));
+
+    /* Master-only: boost/VCOM power programming. */
+    EPD_CHECK(epd_cmd_master(PWR,             PWR_V,             sizeof(PWR_V)));
+    EPD_CHECK(epd_cmd_master(EN_BUF,          EN_BUF_V,          sizeof(EN_BUF_V)));
+    EPD_CHECK(epd_cmd_master(BTST_P,          BTST_P_V,          sizeof(BTST_P_V)));
+    EPD_CHECK(epd_cmd_master(BOOST_VDDP_EN,   BOOST_VDDP_EN_V,   sizeof(BOOST_VDDP_EN_V)));
+    EPD_CHECK(epd_cmd_master(BTST_N,          BTST_N_V,          sizeof(BTST_N_V)));
+    EPD_CHECK(epd_cmd_master(BUCK_BOOST_VDDN, BUCK_BOOST_VDDN_V, sizeof(BUCK_BOOST_VDDN_V)));
+    EPD_CHECK(epd_cmd_master(TFT_VCOM_POWER,  TFT_VCOM_POWER_V,  sizeof(TFT_VCOM_POWER_V)));
+
+    ESP_LOGI(TAG, "EPD initialized (CLK=%d MOSI=%d CS_M=%d CS_S=%d DC=%d RST=%d BUSY=%d PWR_EN=%d)",
+             CONFIG_EPD_PIN_CLK, CONFIG_EPD_PIN_MOSI, CONFIG_EPD_PIN_CS_MASTER,
+             CONFIG_EPD_PIN_CS_SLAVE, CONFIG_EPD_PIN_DC, CONFIG_EPD_PIN_RST,
+             CONFIG_EPD_PIN_BUSY, CONFIG_EPD_PIN_POWER_EN);
+
+    return ESP_OK;
+}
+
+esp_err_t epd_write_frame(epd_read_fn_t read_fn, void *ctx, uint32_t *out_crc32)
+{
+    ESP_RETURN_ON_FALSE(read_fn != NULL, ESP_ERR_INVALID_ARG, TAG, "read_fn required");
+
+    /* Every row has to be sliced into a left (master) and right (slave)
+     * half before either half can go out over SPI, so -- unlike
+     * epd7in3e.c's single-CS passthrough -- bytes can't be forwarded to
+     * the wire as they arrive. Buffer the whole ~938KB frame in PSRAM
+     * first (EE02's XIAO ESP32-S3 Plus has 8MB of it). */
+    uint8_t *frame = heap_caps_malloc(EPD_FRAME_BYTES, MALLOC_CAP_SPIRAM);
+    if (frame == NULL) {
+        ESP_LOGE(TAG, "OOM allocating %u-byte frame buffer", (unsigned)EPD_FRAME_BYTES);
+        return ESP_ERR_NO_MEM;
+    }
+
+    size_t total = 0;
+    uint32_t crc = 0;
+    size_t n;
+    while (total < EPD_FRAME_BYTES &&
+           (n = read_fn(frame + total, EPD_FRAME_BYTES - total, ctx)) > 0) {
+        crc = esp_rom_crc32_le(crc, frame + total, n);
+        total += n;
+    }
+
+    if (total != EPD_FRAME_BYTES) {
+        /* Same invariant as epd7in3e.c: never touch the panel on a
+         * short/wrong-size stream -- the visible screen is left exactly
+         * as it was. */
+        ESP_LOGE(TAG, "Stream supplied %u bytes, expected %u -- aborting refresh",
+                 (unsigned)total, (unsigned)EPD_FRAME_BYTES);
+        free(frame);
+        return ESP_ERR_INVALID_SIZE;
+    }
+
+    /* De-interleave into one half-buffer at a time and DMA it out as a
+     * single contiguous transfer (chunked internally by epd_spi_write) --
+     * far fewer, far larger SPI transactions than sending 1600 separate
+     * 300-byte rows per side. */
+    const size_t HALF_ROW = EPD_BYTES_PER_ROW / 2; /* 300 */
+    const size_t HALF_BUF = HALF_ROW * EPD_HEIGHT; /* 480000 */
+    uint8_t *half = heap_caps_malloc(HALF_BUF, MALLOC_CAP_SPIRAM);
+    if (half == NULL) {
+        ESP_LOGE(TAG, "OOM allocating %u-byte half-frame scratch buffer", (unsigned)HALF_BUF);
+        free(frame);
+        return ESP_ERR_NO_MEM;
+    }
+
+    for (size_t r = 0; r < EPD_HEIGHT; r++) {
+        memcpy(half + r * HALF_ROW, frame + r * EPD_BYTES_PER_ROW, HALF_ROW);
+    }
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_CS_MASTER, 0);
+    esp_err_t err = epd_send_command(DTM);
+    if (err == ESP_OK) {
+        err = epd_send_data(half, HALF_BUF);
+    }
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_CS_MASTER, 1);
+
+    if (err == ESP_OK) {
+        for (size_t r = 0; r < EPD_HEIGHT; r++) {
+            memcpy(half + r * HALF_ROW, frame + r * EPD_BYTES_PER_ROW + HALF_ROW, HALF_ROW);
+        }
+        gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_CS_SLAVE, 0);
+        err = epd_send_command(DTM);
+        if (err == ESP_OK) {
+            err = epd_send_data(half, HALF_BUF);
+        }
+        gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_CS_SLAVE, 1);
+    }
+
+    free(half);
+    free(frame);
+    EPD_CHECK(err);
+
+    if (out_crc32 != NULL) {
+        *out_crc32 = crc;
+    }
+
+    return ESP_OK;
+}
+
+esp_err_t epd_display_stream(epd_read_fn_t read_fn, void *ctx)
+{
+    esp_err_t err = epd_write_frame(read_fn, ctx, NULL);
+    if (err != ESP_OK) {
+        return err;
+    }
+    return epd_turn_on_display();
+}
+
+typedef struct {
+    const uint8_t *data;
+    size_t len;
+    size_t pos;
+} epd_buf_ctx_t;
+
+static size_t epd_buf_read(uint8_t *chunk, size_t chunk_size, void *ctx_)
+{
+    epd_buf_ctx_t *c = (epd_buf_ctx_t *)ctx_;
+    size_t remaining = c->len - c->pos;
+    size_t n = remaining < chunk_size ? remaining : chunk_size;
+    if (n == 0) {
+        return 0;
+    }
+    memcpy(chunk, c->data + c->pos, n);
+    c->pos += n;
+    return n;
+}
+
+esp_err_t epd_display_buffer(const uint8_t *frame, size_t len)
+{
+    epd_buf_ctx_t buf_ctx = { .data = frame, .len = len, .pos = 0 };
+    return epd_display_stream(epd_buf_read, &buf_ctx);
+}
+
+typedef struct {
+    uint8_t fill_byte;
+    size_t remaining;
+} epd_fill_ctx_t;
+
+static size_t epd_fill_read(uint8_t *chunk, size_t chunk_size, void *ctx_)
+{
+    epd_fill_ctx_t *c = (epd_fill_ctx_t *)ctx_;
+    size_t n = c->remaining < chunk_size ? c->remaining : chunk_size;
+    if (n == 0) {
+        return 0;
+    }
+    memset(chunk, c->fill_byte, n);
+    c->remaining -= n;
+    return n;
+}
+
+esp_err_t epd_clear(epd_color_t color)
+{
+    epd_fill_ctx_t fill_ctx = {
+        .fill_byte = (uint8_t)((color << 4) | color),
+        .remaining = EPD_FRAME_BYTES,
+    };
+    return epd_display_stream(epd_fill_read, &fill_ctx);
+}
+
+esp_err_t epd_sleep(void)
+{
+    epd_cs_both(0);
+    EPD_CHECK(epd_send_command(DEEP_SLEEP));
+    EPD_CHECK(epd_send_data_byte(0xA5)); /* magic deep-sleep arg per every reference driver */
+    epd_cs_both(1);
+
+    epd_delay_ms(100);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_POWER_EN, 0);
+    gpio_set_level((gpio_num_t)CONFIG_EPD_PIN_RST, 0);
+
+    return ESP_OK;
+}
@@ -0,0 +1,100 @@
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+#include "esp_err.h"
+
+/* Waveshare 13.3" e-Paper (E) Spectra 6 panel, driven by Seeed's EE02
+ * board (XIAO ESP32-S3 Plus). The panel is marketed/mounted as a
+ * 1600x1200 landscape rectangle (270.40x202.80mm), but its SPI
+ * controller addresses a native raster of 1200 columns x 1600 rows --
+ * i.e. the wire format is portrait, rotated 90 degrees from how the
+ * panel physically hangs. Confirmed identically across three independent
+ * vendor sources: Waveshare's RaspberryPi/c and ESP32 reference drivers
+ * for this exact panel (E-paper_Separate_Program/13.3inch_e-Paper_E in
+ * waveshare/e-Paper), and Waveshare's own ESP-IDF example for their
+ * ESP32-S3-ePaper-13.3E6 driver board (a *different* carrier board than
+ * Seeed's EE02, but the same panel+controller, hence the same command
+ * bytes/geometry -- only the GPIO numbers differ, and those come from
+ * EE02-specific sources, see this component's Kconfig). All three define
+ * EPD_WIDTH=1200/EPD_HEIGHT=1600 and split each row into two 600-byte
+ * (300px) halves sent to independent chip-selects: EPD_PIN_CS_MASTER
+ * gets the left half, EPD_PIN_CS_SLAVE the right -- see epd13in3e.c.
+ *
+ * Getting this backwards (assuming the wire raster matches the
+ * 1600x1200 mount/marketing size) doesn't just rotate the image -- 1600
+ * and 1200 don't share a row stride with 1200 and 1600 the other way
+ * (800 bytes/row x 1200 rows vs 600 bytes/row x 1600 rows), so a mismatch
+ * here slices real image rows at the wrong byte offsets and shreds the
+ * picture into a repeating diagonal garble, not a clean rotation.
+ * server/app/image_pipeline.py's PANEL_WIRE_TRANSPOSE handles the
+ * corresponding rotation server-side before packing bytes for this
+ * panel_type -- this header and that dict must agree on which axis is
+ * native. */
+#define EPD_WIDTH 1200
+#define EPD_HEIGHT 1600
+#define EPD_BYTES_PER_ROW ((EPD_WIDTH + 1) / 2)
+#define EPD_FRAME_BYTES (EPD_BYTES_PER_ROW * EPD_HEIGHT)
+
+/* Same 6-ink Spectra family as the 7.3" panel, and (now confirmed by the
+ * same three vendor sources as the geometry above) the same 4-bit nibble
+ * codes as epd7in3e.h's epd_color_t -- matches
+ * server/app/image_pipeline.py's PANEL_CODES unconditionally, no
+ * panel-specific table needed there. */
+typedef enum {
+    EPD_COLOR_BLACK = 0x0,
+    EPD_COLOR_WHITE = 0x1,
+    EPD_COLOR_YELLOW = 0x2,
+    EPD_COLOR_RED = 0x3,
+    EPD_COLOR_BLUE = 0x5,
+    EPD_COLOR_GREEN = 0x6,
+} epd_color_t;
+
+/** Configures SPI + GPIO and runs the panel's power-on register init sequence. */
+esp_err_t epd_init(void);
+
+/** Fills the whole panel with a single color and refreshes. */
+esp_err_t epd_clear(epd_color_t color);
+
+/**
+ * Called repeatedly by epd_display_stream() to fill up to chunk_size bytes
+ * into chunk. Must return the number of bytes written, or 0 once exhausted.
+ */
+typedef size_t (*epd_read_fn_t)(uint8_t *chunk, size_t chunk_size, void *ctx);
+
+/**
+ * Streams a full frame (EPD_FRAME_BYTES bytes, packed 2 pixels/byte) to the
+ * panel via read_fn and refreshes. Pulling from a caller-supplied source
+ * instead of a single buffer lets callers feed the panel directly from an
+ * HTTP response without holding the whole ~960KB frame in RAM.
+ */
+esp_err_t epd_display_stream(epd_read_fn_t read_fn, void *ctx);
+
+/**
+ * Like epd_display_stream(), but writes the frame into the panel's
+ * internal buffer over SPI WITHOUT triggering the physical refresh (the
+ * visible flash/flicker) -- call epd_turn_on_display() separately to make
+ * it visible. Returns ESP_ERR_INVALID_SIZE if read_fn didn't supply
+ * exactly EPD_FRAME_BYTES, same as epd_display_stream(); either way
+ * nothing is refreshed, so the visible screen is left untouched on
+ * error.
+ *
+ * If out_crc32 is non-NULL, it's set to a CRC32 of the bytes written --
+ * lets a caller compare against the last-displayed frame's CRC and skip
+ * the refresh entirely when nothing actually changed (e.g. redisplaying
+ * the same photo after a reboot).
+ */
+esp_err_t epd_write_frame(epd_read_fn_t read_fn, void *ctx, uint32_t *out_crc32);
+
+/**
+ * Triggers the panel's physical refresh cycle (power on, refresh, power
+ * off) -- the visible flash/flicker sequence. Call after epd_write_frame()
+ * to make the written buffer visible.
+ */
+esp_err_t epd_turn_on_display(void);
+
+/** Convenience wrapper around epd_display_stream() for an in-memory frame buffer. */
+esp_err_t epd_display_buffer(const uint8_t *frame, size_t len);
+
+/** Puts the panel into deep sleep to minimize power draw between refreshes. */
+esp_err_t epd_sleep(void);
@@ -1,3 +1,15 @@
-idf_component_register(SRCS "epd7in3e.c"
+# SRCS is conditional on which board's panel this build targets (see
+# main/CMakeLists.txt's comment on why REQUIRES/PRIV_REQUIRES itself
+# can't be) -- an ee02 build still always requires this component (so
+# its Kconfig menu/include dir exist), but contributes zero object
+# files/symbols to it, since epd13in3e.c provides the real epd_init()
+# etc. for that board instead.
+if(CONFIG_FRAME_PANEL_EE02_13IN3)
+    set(srcs "")
+else()
+    set(srcs "epd7in3e.c")
+endif()
+
+idf_component_register(SRCS ${srcs}
                       INCLUDE_DIRS "include"
                       PRIV_REQUIRES esp_driver_spi esp_driver_gpio)
@@ -1,3 +1,15 @@
+# Both EPD driver components are always REQUIRED (REQUIRES/PRIV_REQUIRES
+# can't itself depend on a Kconfig value -- ESP-IDF resolves the
+# component dependency graph in an early pass that runs BEFORE Kconfig
+# is generated, so a CONFIG_* check here would silently see an empty
+# value every time; confirmed the hard way, see git history if this
+# comment ever seems suspicious). Which one actually compiles anything
+# is decided inside each component's own CMakeLists.txt (conditional
+# SRCS, evaluated in the later, Kconfig-aware pass -- that's fine, it's
+# only REQUIRES itself that has the early-pass restriction), keyed off
+# the same CONFIG_FRAME_PANEL_EE02_13IN3 that main/epd_board.h uses to
+# pick which header every source file sees -- exactly one of the two
+# ever contributes actual object files/symbols to a given build.
 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
+                       PRIV_REQUIRES esp_event nvs_flash esp_wifi esp_netif esp_http_server esp_http_client mbedtls dns_server epd7in3e epd13in3e qrcode epaper_fonts esp_driver_gpio esp_adc esp_https_ota app_update esp_app_format
                       EMBED_FILES root.html)
@@ -2,18 +2,29 @@ menu "ESPresso Frame Configuration"

    config FRAME_BOARD_NAME
        string "Board variant name, reported to the server"
-        default "devkit"
+        default "devkit_esp32c6"
        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).
+            from a configured Gitea repo's releases, and (see
+            routers/device.py's BOARD_PANEL_MAP) which EPD panel it
+            drives -- no manual "which board/panel" picker in the web
+            UI. Must match one of the asset names
+            .gitea/workflows/firmware-release-build.yml publishes
+            (firmware-<name>.bin): "devkit_esp32c6" (this default, for
+            the plain ESP32-C6-DevKitC-1 build), "xiao_esp32c6" (set via
+            sdkconfig.xiao for the Seeed XIAO ESP32-C6 build), or "ee02"
+            (set via sdkconfig.ee02 for the Seeed EE02/XIAO ESP32-S3
+            Plus + 13.3" panel build) -- see build_for_board.sh.
+
+            Chip-qualified rather than plain "devkit"/"xiao": the EE02
+            board also sockets a XIAO module (an ESP32-S3 one), so
+            "xiao" alone stopped disambiguating hardware once EE02
+            existed. The server keeps accepting the old bare
+            "devkit"/"xiao" names indefinitely too, since already-
+            flashed devices report whatever name their current firmware
+            was built with and can't be retroactively renamed.

    config FRAME_XIAO_ANTENNA_INIT
        bool "Select onboard antenna on Seeed XIAO ESP32-C6 (RF switch init)"
@@ -33,6 +44,18 @@ menu "ESPresso Frame Configuration"
            by default in sdkconfig.xiao; leave off for the DevKitC-1
            dev board, which has no such switch.

+    config FRAME_PANEL_EE02_13IN3
+        bool "Build for the EE02 board + 13.3in Spectra 6 panel (ESP32-S3), not the 7.3in panel"
+        default n
+        help
+            Selects the epd13in3e driver component (13.3", 1600x1200)
+            instead of epd7in3e (7.3", 800x480) as main/epd_board.h's
+            target -- see firmware/components/epd13in3e. Firmware only
+            ever links one EPD driver at a time, same as the
+            devkit/xiao split links exactly one board's pin config.
+            Enabled by default in sdkconfig.ee02; leave off for the
+            ESP32-C6 boards (devkit/xiao), which drive the 7.3" panel.
+
    config ESP_AP_SSID
        string "Provisioning softAP SSID prefix"
        default "ESPRESSO"
@@ -119,6 +142,7 @@ menu "ESPresso Frame Configuration"
    config FRAME_NEXT_BUTTON_GPIO
        int "Next-photo button GPIO (-1 to disable)"
        default 2
+        range -1 21 if IDF_TARGET_ESP32S3
        range -1 7
        help
            Button wired between this GPIO and GND (active-low, internal
@@ -126,14 +150,17 @@ menu "ESPresso Frame Configuration"
            Pressing it wakes the device (if asleep), forces the server to
            advance to the next photo immediately (POST /frame/advance)
            regardless of the configured refresh interval, and displays
-            it. Must be GPIO 0-7 -- the only pins the ESP32-C6 can use as
-            a deep-sleep GPIO wakeup source, which is what lets a press
-            wake the device promptly instead of only being noticed during
-            its brief awake windows. Set to -1 to disable the feature.
+            it. Must be a deep-sleep-wakeup-capable GPIO: 0-7 on the
+            ESP32-C6, 0-21 on the ESP32-S3 (RTC-IO pins reachable by
+            esp_sleep_enable_ext1_wakeup_io()) -- required so a press
+            wakes the device promptly instead of only being noticed
+            during its brief awake windows. Set to -1 to disable the
+            feature.

    config FRAME_BACK_BUTTON_GPIO
        int "Back-photo button GPIO (-1 to disable)"
        default 0
+        range -1 21 if IDF_TARGET_ESP32S3
        range -1 7
        help
            Button wired between this GPIO and GND (active-low, internal
@@ -142,40 +169,40 @@ menu "ESPresso Frame Configuration"
            to return to the previously-current photo immediately
            (POST /frame/back), and displays it. Pressing next
            afterwards returns to where you were before pressing back.
-            Must be GPIO 0-7 for the same deep-sleep-wakeup reason as
+            Must be a deep-sleep-wakeup-capable GPIO, same range as
            FRAME_NEXT_BUTTON_GPIO above; defaults to a different pin
            than the other buttons. Set to -1 to disable the feature.

    config FRAME_COMBO_BUTTON_GPIO
        int "Menu/reset button GPIO (-1 to disable)"
        default 1
+        range -1 21 if IDF_TARGET_ESP32S3
        range -1 7
        help
            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-
-            wakeup reason as FRAME_NEXT_BUTTON_GPIO above; defaults to
+            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 a deep-sleep-wakeup-capable GPIO,
+            same range 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
            menu, both reset tiers, and factory-reset-via-button --
            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)"
@@ -185,8 +212,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)"
@@ -1,10 +1,15 @@
+#include <stdint.h>
+
 #include "driver/gpio.h"
 #include "esp_log.h"
 #include "esp_sleep.h"
+#include "soc/soc_caps.h"

 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"

+#include "wifi_provisioning.h"
+
 #include "back_button.h"

 static const char *TAG = "back_button";
@@ -14,6 +19,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)
 {
@@ -30,13 +36,20 @@ void back_button_init(void)
    };
    gpio_config(&io_conf);

+#if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
    /* See next_button.c for why this API (not ext1) -- it manages the
     * pull resistor across the sleep transition itself, so the pin
     * doesn't float and wake the device spuriously. */
    esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(1ULL << BACK_BUTTON_GPIO, ESP_GPIO_WAKEUP_GPIO_LOW);
+#else
+    /* See next_button.c for why ext1 is safe here on targets without the
+     * API above (e.g. ESP32-S3), and why _io() needs no cross-file mask
+     * coordination. */
+    ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(1ULL << BACK_BUTTON_GPIO, ESP_EXT1_WAKEUP_ANY_LOW));
+#endif
 }

-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 +57,53 @@ 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;
-    }
+#if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
+    bool caused_wake = esp_sleep_get_gpio_wakeup_status() & (1ULL << BACK_BUTTON_GPIO);
+#else
+    bool caused_wake = esp_sleep_get_ext1_wakeup_status() & (1ULL << BACK_BUTTON_GPIO);
+#endif

-    /* 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
@@ -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);
@@ -1,6 +1,7 @@
 #include "driver/gpio.h"
 #include "esp_log.h"
 #include "esp_sleep.h"
+#include "soc/soc_caps.h"

 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
@@ -31,10 +32,17 @@ void combo_button_init(void)
    };
    gpio_config(&io_conf);

+#if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
    /* See next_button.c for why this API (not ext1) -- it manages the
     * pull resistor across the sleep transition itself, so the pin
     * doesn't float and wake the device spuriously. */
    esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(1ULL << COMBO_BUTTON_GPIO, ESP_GPIO_WAKEUP_GPIO_LOW);
+#else
+    /* See next_button.c for why ext1 is safe here on targets without the
+     * API above (e.g. ESP32-S3), and why _io() needs no cross-file mask
+     * coordination. */
+    ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(1ULL << COMBO_BUTTON_GPIO, ESP_EXT1_WAKEUP_ANY_LOW));
+#endif
 }

 bool combo_button_check(void)
@@ -48,13 +56,17 @@ bool combo_button_check(void)
     * caused the wake even if it's since been released -- in which case
     * the poll loop below simply measures 0ms held, correctly resolving
     * to a quick press rather than "not pressed at all." */
+#if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
    bool caused_wake = esp_sleep_get_gpio_wakeup_status() & (1ULL << COMBO_BUTTON_GPIO);
+#else
+    bool caused_wake = esp_sleep_get_ext1_wakeup_status() & (1ULL << COMBO_BUTTON_GPIO);
+#endif
    if (!caused_wake && gpio_get_level(COMBO_BUTTON_GPIO) != 0) {
        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 +82,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)
@@ -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.
@@ -0,0 +1,17 @@
+#pragma once
+
+/* Which EPD driver component this binary is built against -- exactly one,
+ * selected at compile time by CONFIG_FRAME_PANEL_EE02_13IN3 (see
+ * main/Kconfig.projbuild and main/CMakeLists.txt's matching PRIV_REQUIRES
+ * selection). Every file that used to `#include "epd7in3e.h"` directly
+ * includes this instead, so a build for the other board picks up the
+ * right EPD_WIDTH/EPD_HEIGHT/EPD_FRAME_BYTES/epd_color_t/epd_init() etc.
+ * with no other source change -- both driver components expose the same
+ * function/macro names (see epd13in3e.h), just sized for their own
+ * panel. */
+
+#if CONFIG_FRAME_PANEL_EE02_13IN3
+#include "epd13in3e.h"
+#else
+#include "epd7in3e.h"
+#endif
@@ -3,10 +3,10 @@
 #include <stddef.h>
 #include <stdint.h>

-#include "epd7in3e.h"
+#include "epd_board.h"
 #include "fonts.h"

-/** Sets one pixel in a malloc'd EPD_FRAME_BYTES buffer (packed 2px/byte, per epd7in3e.h). */
+/** Sets one pixel in a malloc'd EPD_FRAME_BYTES buffer (packed 2px/byte, per epd_board.h). */
 void epd_draw_pixel(uint8_t *frame, int x, int y, epd_color_t color);

 /**
@@ -14,7 +14,7 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/event_groups.h"

-#include "epd7in3e.h"
+#include "epd_board.h"
 #include "status_screen.h"
 #include "combo_button.h"
 #include "ota_update.h"
@@ -95,18 +95,15 @@ static void save_wifi_cache(esp_netif_t *netif)
 }

 /* Builds a full URL from cfg->toolsserver + a path (no leading slash),
- * appending cfg->access_token as ?token= if one's set. toolsserver is
- * 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. 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. */
+ * appending cfg->device_token as &token= once one's been delivered.
+ * toolsserver is 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. 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=. 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;
@@ -123,9 +120,8 @@ static void build_url(char *out, size_t out_size, const frame_config_t *cfg, con
        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);
+    if (cfg->device_token[0] != '\0' && len < out_size) {
+        snprintf(out + len, out_size - len, "&token=%s", cfg->device_token);
    }
 }

@@ -276,6 +272,14 @@ 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
@@ -370,6 +374,7 @@ 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';
@@ -419,6 +424,10 @@ 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));

@@ -443,16 +452,17 @@ static size_t http_read_fn(uint8_t *chunk, size_t chunk_size, void *ctx_)
    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). 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
+/* 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. */
+ * (see the active EPD driver component, main/epd_board.h) 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";
@@ -460,6 +470,10 @@ static esp_err_t fetch_and_display(const frame_config_t *cfg, fetch_action_t act
        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];
@@ -673,10 +687,11 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
        image_ok = (fetch_err == ESP_OK);
        if (!image_ok) {
            /* epd_display_stream() never triggers a physical refresh on a
-             * failed/short/wrong-size stream (see epd7in3e.c), so the
-             * visible screen is guaranteed untouched here -- always safe
-             * to show what went wrong instead of leaving stale content
-             * with no indication anything failed. */
+             * failed/short/wrong-size stream (see the active EPD driver
+             * component, main/epd_board.h), so the visible screen is
+             * guaranteed untouched here -- always safe to show what went
+             * wrong instead of leaving stale content with no indication
+             * anything failed. */
            ESP_LOGW(TAG, "Fetch/display failed (%s), retrying sooner", esp_err_to_name(fetch_err));
            /* Covers the fast-connect cache's blind spot: WiFi can report
             * a successful connection (cached static IP "worked" at the
@@ -720,6 +735,11 @@ void frame_client_run(const frame_config_t *cfg, fetch_action_t action, bool sho
        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
@@ -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;

 /**
@@ -40,12 +40,21 @@ 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). */
@@ -1,10 +1,15 @@
+#include <stdint.h>
+
 #include "driver/gpio.h"
 #include "esp_log.h"
 #include "esp_sleep.h"
+#include "soc/soc_caps.h"

 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"

+#include "wifi_provisioning.h"
+
 #include "next_button.h"

 static const char *TAG = "next_button";
@@ -14,6 +19,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)
 {
@@ -31,16 +37,47 @@ void next_button_init(void)
    };
    gpio_config(&io_conf);

-    /* Not esp_sleep_enable_ext1_wakeup_io(): its internal pull resistors
-     * don't hold once the RTC_PERIPH domain powers down for deep sleep, so
-     * the pin floats and reads spuriously low, waking the device instantly
-     * on every sleep entry (confirmed on hardware). This GPIO-wakeup
-     * variant manages the pull resistor itself across the sleep
-     * transition. */
+#if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
+    /* Not esp_sleep_enable_ext1_wakeup_io() on its own: on a target
+     * without RTC-independent digital pull registers, ext1's internal
+     * pull resistors don't hold once the RTC_PERIPH domain powers down
+     * for deep sleep, so the pin floats and reads spuriously low, waking
+     * the device instantly on every sleep entry (confirmed on hardware,
+     * ESP32-C6). This GPIO-wakeup variant manages the pull resistor
+     * itself across the sleep transition, sidestepping the issue
+     * entirely -- but it only exists on chips with this capability
+     * (currently just ESP32-C6; see the #else below for other targets,
+     * e.g. ESP32-S3). */
    esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(1ULL << NEXT_BUTTON_GPIO, ESP_GPIO_WAKEUP_GPIO_LOW);
+#else
+    /* No HP-periph-powerdown wakeup API here (e.g. ESP32-S3) -- fall
+     * back to ext1, but NOT naively: on every non-original-ESP32 target
+     * (ESP32-S3 included), gpio_pullup_en() -- which the gpio_config()
+     * call above invokes via pull_up_en -- delegates to
+     * rtc_gpio_pullup_en() for RTC-capable pins (confirmed in
+     * esp_driver_gpio's gpio.c: GPIO_RTCIO_ARE_INDEPENDENT is 1 for
+     * every target except the original ESP32, meaning digital and RTC
+     * pull registers are independent hardware and gpio_config() already
+     * routes the pull-up through the RTC pad's own register for these
+     * pins, not just the digital one). That's exactly what was missing
+     * in the ext1 attempt that failed on hardware above -- so on this
+     * target the pull-up already survives the RTC_PERIPH power-down
+     * ext1 wakeup requires, without needing a separate rtc_gpio_*_en()
+     * call here. _io() (not the bare esp_sleep_enable_ext1_wakeup(),
+     * which resets any previously-configured mask) is additive across
+     * this file's, back_button.c's, and combo_button.c's independent
+     * init calls -- confirmed in esp_hw_support's sleep_modes.c -- so no
+     * shared-mask coordination between the three button files is
+     * needed. Still unconfirmed on real EE02 hardware: this avoids the
+     * *documented* failure mode of the earlier ext1 attempt, but that
+     * attempt was never root-caused beyond "confirmed spurious wakeup on
+     * hardware" -- treat this as untested until it's actually run on an
+     * EE02 board. */
+    ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(1ULL << NEXT_BUTTON_GPIO, ESP_EXT1_WAKEUP_ANY_LOW));
+#endif
 }

-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 +85,58 @@ 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;
-    }
+#if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
+    bool caused_wake = esp_sleep_get_gpio_wakeup_status() & (1ULL << NEXT_BUTTON_GPIO);
+#else
+    bool caused_wake = esp_sleep_get_ext1_wakeup_status() & (1ULL << NEXT_BUTTON_GPIO);
+#endif

-    /* 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
@@ -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);
@@ -36,9 +36,8 @@ static void build_ota_url(char *out, size_t out_size, const frame_config_t *cfg)
        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);
+    if (cfg->device_token[0] != '\0' && len < out_size) {
+        snprintf(out + len, out_size - len, "&token=%s", cfg->device_token);
    }
 }

@@ -4,7 +4,7 @@
 #include "esp_check.h"
 #include "esp_log.h"

-#include "epd7in3e.h"
+#include "epd_board.h"
 #include "epd_draw.h"
 #include "fonts.h"
 #include "qrcodegen.h"
@@ -97,11 +97,6 @@
                <input type="text" id="toolsserver" name="toolsserver" placeholder="e.g. 192.168.1.50:8080 or https://frame.example.com" maxlength="128" required>
            </div>

-            <div class="input-group">
-                <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>
@@ -3,7 +3,7 @@

 #include "esp_check.h"

-#include "epd7in3e.h"
+#include "epd_board.h"
 #include "epd_draw.h"
 #include "fonts.h"
 #include "wifi_provisioning.h"
@@ -19,7 +19,7 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"

-#include "epd7in3e.h"
+#include "epd_board.h"
 #include "qr_onboarding.h"
 #include "wifi_provisioning.h"
 #include "board_antenna.h"
@@ -73,20 +73,10 @@ esp_err_t frame_config_load(frame_config_t *out)
        return pass_err;
    }

-    /* Also optional -- most deployments won't set a server-side
-     * MANAGEMENT_TOKEN at all, in which case this stays empty and the
-     * manage-menu QR just links to the page with no ?token=. */
-    len = sizeof(out->access_token);
-    esp_err_t token_err = nvs_get_str(handle, "access_token", out->access_token, &len);
-    if (token_err != ESP_OK && token_err != ESP_ERR_NVS_NOT_FOUND) {
-        nvs_close(handle);
-        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);
+    esp_err_t 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;
@@ -131,9 +121,6 @@ esp_err_t frame_config_save(const frame_config_t *cfg)
    if (err == ESP_OK) {
        err = nvs_set_str(handle, "toolsserver", cfg->toolsserver);
    }
-    if (err == ESP_OK) {
-        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
@@ -191,7 +178,6 @@ void frame_config_clear(void)
    nvs_erase_key(handle, "sta_ssid");
    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);
@@ -234,6 +220,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
 * ---------------------------------------------------------------------- */
@@ -429,7 +438,6 @@ static esp_err_t save_config_post_handler(httpd_req_t *req)
    extract_form_value(body, "ssid", cfg.sta_ssid, sizeof(cfg.sta_ssid));
    extract_form_value(body, "password", cfg.sta_password, sizeof(cfg.sta_password));
    extract_form_value(body, "toolsserver", cfg.toolsserver, sizeof(cfg.toolsserver));
-    extract_form_value(body, "access_token", cfg.access_token, sizeof(cfg.access_token));

    if (strlen(cfg.sta_ssid) == 0 || strlen(cfg.toolsserver) == 0) {
        httpd_resp_send_err(req, HTTPD_400_BAD_REQUEST, "SSID and Tools Server are required");
@@ -443,8 +451,7 @@ static esp_err_t save_config_post_handler(httpd_req_t *req)
        return ESP_FAIL;
    }

-    ESP_LOGI(TAG, "Saved config: ssid='%s' toolsserver='%s' access_token=%s", cfg.sta_ssid, cfg.toolsserver,
-             strlen(cfg.access_token) ? "set" : "none");
+    ESP_LOGI(TAG, "Saved config: ssid='%s' toolsserver='%s'", cfg.sta_ssid, cfg.toolsserver);

    /* 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
@@ -17,11 +17,10 @@ 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; 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. */
+     * this device first introduces itself by id (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;

@@ -94,6 +93,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
@@ -0,0 +1,13 @@
+# Name,   Type, SubType, Offset,   Size,     Flags
+# Same OTA layout/offsets as partitions.csv (the 8MB dev-board table) --
+# the XIAO ESP32-S3 Plus's 16MB flash has plenty of room for the same
+# 2MB app slots (current firmware runs ~1.2MB, per partitions_xiao.csv's
+# own sizing note) without needing to trim anything the way the 4MB xiao
+# table did. Leaves ~12MB of the 16MB unused/unpartitioned for now --
+# revisit sizing once a real build's actual footprint and any EE02-
+# specific storage needs (if ever) are known.
+nvs,      data, nvs,     0x9000,   0x6000,
+phy_init, data, phy,     0xf000,   0x1000,
+ota_0,    app,  ota_0,   0x10000,  0x200000,
+otadata,  data, ota,     0x210000, 0x2000,
+ota_1,    app,  ota_1,   0x220000, 0x200000,
@@ -0,0 +1,50 @@
+# Board-specific overrides for Seeed's EE02 (XIAO ESP32-S3 Plus + 13.3"
+# Spectra 6 panel), layered on top of sdkconfig.defaults via
+# SDKCONFIG_DEFAULTS -- see build_for_board.sh, which is the supported
+# way to build with this file. Don't set this via a plain `idf.py
+# menuconfig` on the default build; that writes straight into the shared
+# sdkconfig, not this file.
+#
+# Unlike xiao (a same-chip Kconfig-only variant of the ESP32-C6 dev
+# board), EE02 is a genuinely different chip target (ESP32-S3) --
+# build_for_board.sh runs `set-target esp32s3` for this board before
+# building, same as it runs `set-target esp32c6` for devkit/xiao.
+CONFIG_FRAME_BOARD_NAME="ee02"
+
+# Selects the epd13in3e driver component (13.3", 1600x1200) instead of
+# epd7in3e -- see main/Kconfig.projbuild and main/CMakeLists.txt.
+CONFIG_FRAME_PANEL_EE02_13IN3=y
+
+# XIAO ESP32-S3 Plus: 16MB flash, 8MB PSRAM (vs. the plain XIAO ESP32-S3's
+# 8MB/8MB) -- see partitions_ee02.csv, sized generously against this,
+# not yet trimmed/tuned against a real build's actual footprint.
+CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_ee02.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions_ee02.csv"
+
+# EE02's e-paper interface pin defaults live in
+# firmware/components/epd13in3e/Kconfig instead of being overridden here
+# (mirrors how epd7in3e's Kconfig defaults are devkit-shaped and
+# sdkconfig.xiao only overrides the ones that actually differ) -- EE02's
+# pins are a different Kconfig menu entirely (EPD_PIN_CS_MASTER/CS_SLAVE/
+# POWER_EN don't exist on epd7in3e's board at all), not a same-menu
+# override, so there's nothing to set here beyond selecting the component
+# above.
+#
+# Deliberately NOT overriding FRAME_NEXT_BUTTON_GPIO/FRAME_BACK_BUTTON_
+# GPIO/FRAME_COMBO_BUTTON_GPIO/FRAME_BATTERY_ADC_GPIO here, even though
+# the same community source that gave the epd13in3e pinout also reports
+# EE02 has 3 user buttons at GPIO2/3/5: which physical button maps to
+# which logical role (next/back/combo) still isn't confirmed. The
+# button GPIOs' `range -1 7` constraint (main/Kconfig.projbuild) -- which
+# used to be hardcoded to the ESP32-C6's deep-sleep-wakeup-capable GPIO
+# set -- now widens to `range -1 21` under IDF_TARGET_ESP32S3 (the
+# ESP32-S3's own ext1-wakeup-capable RTC-IO range), so GPIO2/3/5 fit
+# either way and nothing here needs adjusting on that front. What's
+# still unconfirmed: (1) the button-to-role mapping above, and (2)
+# whether the S3 button-wakeup path itself (ext1 + RTC pull-up, see
+# main/next_button.c) actually avoids the spurious-instant-wakeup bug
+# that ruled out ext1 on the ESP32-C6 -- that needs real EE02 hardware,
+# not just a clean compile. FRAME_BATTERY_ADC_GPIO's `range -1 6` is a
+# separate, still-unwidened concern -- it's the ESP32-C6's ADC-capable
+# pin set, not a deep-sleep-wakeup range, and out of scope here.
@@ -8,7 +8,7 @@ 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"
+CONFIG_FRAME_BOARD_NAME="xiao_esp32c6"

 # 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.
@@ -1 +1 @@
-1.3.0
+1.4.2
@@ -0,0 +1,7 @@
+__pycache__/
+**/__pycache__/
+.venv/
+*.egg-info/
+data/
+render-service/node_modules/
+.git/
@@ -2,18 +2,118 @@ 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/*
+
+# EXPERIMENTAL. System libs a headless Chromium needs (app/html_render.py, the weather widget's
+# opt-in "modern" render style), trimmed from Playwright's own full
+# `install-deps chromium` list to just what a headless (no Xvfb),
+# Latin-text-plus-emoji use case needs: dropped xvfb (only needed for a
+# *headed* browser) and the CJK/Cyrillic/Thai locale font packages
+# (fonts-ipafont-gothic, fonts-wqy-zenhei, fonts-tlwg-loma-otf,
+# xfonts-cyrillic, xfonts-scalable, fonts-freefont-ttf, fonts-unifont) --
+# fonts-noto-color-emoji is the one that actually matters here (real
+# color emoji in the weather icons, vs. WeasyPrint/Pango's monochrome
+# fallback glyphs in this feature's original spike).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 libatspi2.0-0t64 \
+    libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libglib2.0-0t64 \
+    libnspr4 libnss3 libpango-1.0-0 libx11-6 libxcb1 libxcomposite1 \
+    libxdamage1 libxext6 libxfixes3 libxkbcommon0 libxrandr2 \
+    fonts-noto-color-emoji libfontconfig1 libfreetype6 fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

 COPY requirements.txt .
+# Split across several layers rather than one `pip install -r
+# requirements.txt` -- same Cloudflare single-blob/layer payload-size
+# limit as render-service's npm installs below. The single combined
+# layer was measured at ~113MB unpacked, over the limit on its own.
+# Isolating the largest packages gets every layer's unpacked size well
+# clear of 100MB (sqlalchemy ~15MB, pillow ~19MB, pypdfium2 ~8MB, the
+# remaining `-r requirements.txt` layer ~71MB). Each package version here
+# still comes from requirements.txt (`pip install -r` for everything that
+# doesn't need its own layer skips these, since pip sees them already
+# satisfied); the explicit versions below just control *when* each
+# installs -- same "single source of truth, just splitting *when* it
+# installs" tradeoff as the npm section's --no-save comment below.
+RUN pip install --no-cache-dir sqlalchemy==2.0.51
+RUN pip install --no-cache-dir pillow==12.3.0
+RUN pip install --no-cache-dir pypdfium2==5.12.1
+RUN pip install --no-cache-dir playwright==1.61.0
 RUN pip install --no-cache-dir -r requirements.txt

+# The headless Chromium binary itself is deliberately NOT installed
+# here at build time. `playwright install chromium-headless-shell`
+# unpacks to ~262MB, and its single `chrome-headless-shell` binary alone
+# (measured: 181MB) is one file -- unlike the pip/npm splits above
+# (independently-installable smaller packages moved into their own
+# layers), a single 181MB file can't be divided across multiple <100MB
+# Docker layers by any ordinary COPY/RUN restructuring; the whole file
+# lands in whichever layer's diff contains it, which confirmed-failed
+# to push to this project's registry (the same Cloudflare single-blob/
+# layer limit that forced the pip/npm splits elsewhere in this file --
+# see their comments). Fix: start.sh downloads it at container startup
+# instead, cached on the /data volume (PLAYWRIGHT_BROWSERS_PATH below)
+# so it survives restarts/redeploys and only ever downloads once per
+# volume, not once per image layer. Trade-off: first boot on a fresh
+# volume needs network access to Playwright's CDN -- true of Immich/
+# weather API access too, so not a new requirement for this server.
+ENV PLAYWRIGHT_BROWSERS_PATH=/data/.playwright-browsers
+
+# 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"]
@@ -37,26 +37,27 @@ algorithm itself -- it just streams the response straight to the panel.
   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).
+   configure. `MANAGEMENT_TOKEN` in `docker-compose.yml` is optional and
+   only matters pre-setup: if set, it's the credential that gates who
+   gets to be the one to run first-run setup on a freshly deployed
+   server, before any admin account exists.
 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 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.
+   builds every supported board and publishes them as release assets
+   (`firmware-devkit_esp32c6.bin`/`firmware-xiao_esp32c6.bin`/
+   `firmware-ee02.bin`, plus `firmware-devkit.bin`/`firmware-xiao.bin`
+   duplicates for devices still on pre-rename firmware) whenever
+   `firmware/version.txt` 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 same header also determines which EPD panel the frame renders for
+   (`Frame.panel_type`, see `docs/hardware.md`'s board identifiers
+   section) -- also never a manual setting. 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

@@ -91,19 +92,30 @@ algorithm itself -- it just streams the response straight to the panel.
  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.
+- **Server logs.** `/admin/logs` shows the tail of the process's own
+  log file (`LOG_PATH` env var, default `/data/server.log` -- the same
+  `/data` volume as the database and legacy config, so it survives
+  container restarts/redeploys; `LOG_LEVEL` env var, default `INFO`).
+  Rotates at ~2MB x 3 backups; the page only reads the current file,
+  "Download full log" streams it raw. There's no log shipping/
+  aggregation beyond this -- it's a single-container deployment, so
+  the file *is* the log.

 ## Endpoints

 Pages: `/` (routing hub), `/setup`, `/login`, `/claim`, `/settings`,
-`/admin`, `/frames/{id}` (Photos), `/frames/{id}/config`,
+`/admin`, `/admin/logs`, `/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 once `refresh_interval_s` has
+  the panel's raw 4-bit-per-pixel, 2-pixels-per-byte format
+  (`application/octet-stream`) -- 800x480/exactly 192,000 bytes for the
+  original 7.3" panel, 1600x1200/exactly 960,000 bytes for the 13.3"
+  panel (see `Frame.panel_type`/`image_pipeline.PANEL_SPECS`; a given
+  device's byte count is fixed by which firmware/panel it actually is).
+  **Side-effect-free** 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
@@ -121,11 +133,14 @@ Pages: `/` (routing hub), `/setup`, `/login`, `/claim`, `/settings`,
  this response may grow.
 - `GET /frame/photo-info` -- location/date overlay text for the manage
  menu (city + abbreviated US/CAN region or country, `MM/DD/YY`).
- `GET /frame/share/{asset_id}` -- creates a 30-minute public Immich
-  share link and 302s to it; scoped to the photo currently showing or
-  queued on *this* frame only.
- `GET /frame/face-labels` -- up to 4 named faces with 800x480
-  positions, flattened (`name_0`/`x_0`/`y_0`, ...) for the device's
+- `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 positions in the
+  frame's own panel space (800x480 for the 7.3" panel, 1600x1200 for the
+  13.3"), 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
@@ -200,19 +215,70 @@ Pages: `/` (routing hub), `/setup`, `/login`, `/claim`, `/settings`,
  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.
 - Auth in one breath: browsers use sessions (+CSRF), devices use
-  per-frame tokens (`?id=` + `?token=`), the manage QR uses its own
-  limited token, and `MANAGEMENT_TOKEN` survives only as the migration
-  credential for pre-multi-frame firmware. `/frame/share` stays scoped
-  to photos this frame is actually showing or has queued, not any
-  Immich asset ID someone might guess -- a second layer a leaked device
-  token alone wouldn't bypass.
- Calendar frame mode (`app/calendar_feed.py`) expands recurring events
+  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` is only ever the pre-setup claim gate (see
+  step 5 above).
+- The calendar widget (`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.
+- The whiteboard widget (`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).
@@ -252,3 +318,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.
@@ -1,14 +1,18 @@
-"""Authentication: password hashing, user sessions + CSRF, the legacy
-shared-token gate, and device resolution.
+"""Authentication: password hashing, user sessions + CSRF, the pre-setup
+claim 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).
+- MANAGEMENT_TOKEN (env-only, optional). Only meaningful before any user
+  account exists yet (fresh install, or freshly migrated, before
+  /setup has been run): if set, it gates who gets to be the one to run
+  /setup and claim the first admin account; once a user exists, sessions
+  are the only way in. Not a standing bearer credential -- the on-panel
+  manage QR now embeds a frame's own per-frame manage_token (/m/, see
+  routers/manage.py) rather than this shared one; CSRF doesn't apply to
+  it either way (it's an explicit per-request credential, not an ambient
+  cookie a cross-site request could ride).
 - Device credentials (?id= + ?token=, see require_device below).
 """

@@ -250,17 +254,16 @@ def require_frame_control(


 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."""
+    """The pre-setup claim-gate 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)."""
+    """Whether the request carries the current MANAGEMENT_TOKEN, via
+    query param or cookie. Only meaningful pre-setup (see require_browser
+    below) -- empty configured token => not valid (nothing to match)."""
    token = management_token()
    if not token:
        return False
@@ -270,12 +273,12 @@ def browser_token_valid(request: Request) -> bool:

 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."""
+    (CSRF-checked on mutations, returns the User). While NO users exist
+    yet (fresh install, or freshly migrated, before /setup has been run)
+    the API instead stays open if no MANAGEMENT_TOKEN is set, or opens
+    to whoever supplies it if one is -- there's nobody to log in as yet,
+    so this is purely the claim gate for who gets to run /setup. Once a
+    user exists, only a session gets in."""
    session = current_session(request, db)
    if session is not None:
        if request.method not in ("GET", "HEAD", "OPTIONS") and not _csrf_ok(request, session):
@@ -283,10 +286,9 @@ def require_browser(request: Request, db: Session = Depends(get_db)) -> User | N
        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
+    if not users_exist(db):
+        if not management_token() or browser_token_valid(request):
+            return None
    raise HTTPException(401, "Not logged in")


@@ -326,63 +328,29 @@ def _register_frame(db: Session, device_id: str) -> 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.
-    """
+    Firmware sends ?id=<12-hex-mac>&token=<per-frame device token>."""
    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")
+    if not device_id:
+        raise HTTPException(401, "Missing device id")
+
+    frame = db.scalars(select(Frame).where(Frame.device_id == device_id)).first()
+    if frame is None:
+        frame = _register_frame(db, device_id)
    else:
-        if not legacy_ok:
+        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)
+        elif not token_ok and frame.device_token_ack:
            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")
+        # else: 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.

    frame.last_seen = time.time()
    db.commit()
@@ -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
@@ -1,10 +1,11 @@
-"""Fetch, parse, and merge per-user ICS calendar feeds for calendar frame
-mode (see routers/device.py's RENDERERS["calendar"] and calendar_render.py).
+"""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 (owner_display_name, url)
-pairs, not ORM objects, so this module stays testable against fixture .ics
-text with no database or app involved.
+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
@@ -16,12 +17,15 @@ 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

@@ -83,27 +87,68 @@ def fetch_source_events(url: str, window_start: date, window_end: date) -> list[
    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[tuple[str, str]], window_start: date, window_end: date
+    sources: list[CalendarSource], window_start: date, window_end: date
 ) -> tuple[list[dict], str]:
-    """sources: [(owner_display_name, ics_url), ...]. Fetches each
-    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)."""
+    """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 owner_display_name, url in sources:
+    for source in sources:
        try:
-            events = fetch_source_events(url, window_start, window_end)
-        except CalendarFetchError:
+            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:
-            event["owner_display_name"] = owner_display_name
-            merged.append(event)
+            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 ""
@@ -0,0 +1,347 @@
+"""Calendar widget's "modern" render style -- all four view modes
+(agenda/today_tomorrow/week/month), mirroring calendar_render.py's own
+_build dispatch shape exactly so app/widgets/calendar.py and the
+calendar preview endpoint can call either module identically. Kept in
+its own module rather than joining app/html_render.py's other build_*
+functions, mirroring calendar_render.py's own separation from the
+simpler widgets (calendar is the one case where html_render.py growing
+a 5th unrelated builder starts to hurt readability).
+
+Reuses calendar_render's own private helpers (_events_on_day/_event_
+colors/_event_start/_fmt_time/_weather_for_day/_month_view_fits/
+_add_months) so a modern-style view's event list/colors/times/weather/
+month-grid math match the classic renderer's data exactly -- only the
+drawing differs, same relationship weather's build_current/build_daily
+have with weather_render.py."""
+
+from __future__ import annotations
+
+import calendar as calendar_module
+from datetime import date, datetime, timedelta
+from zoneinfo import ZoneInfo
+
+from PIL import Image
+
+from . import html_render, panel_style, theme_tokens
+from .calendar_render import (
+    MARGIN,
+    WEEKDAY_NAMES,
+    _add_months,
+    _event_colors,
+    _event_start,
+    _events_on_day,
+    _fmt_time,
+    _month_view_fits,
+    _weather_for_day,
+)
+
+
+def _weather_row(weather_cities, day, units) -> list[dict]:
+    entries = _weather_for_day(weather_cities, day)
+    return [
+        {"emoji": html_render.CATEGORY_EMOJI.get(e["category"], ""), "high": round(e["high"]), "low": round(e["low"])}
+        for e in entries
+    ]
+
+
+def _day_section_data(day: date, events: list[dict], tz: ZoneInfo, palette_rgb, weather_cities,
+                      weather_units: str, owners_seen: list[str], rows_avail_h: int, row_h: int) -> dict:
+    """One day's {header, weather_entries, rows, more_count} -- shared by
+    build_agenda/build_today_tomorrow/build_week's vertical layout, same
+    reuse relationship calendar_render._draw_agenda_day has with
+    _build_agenda/_build_today_tomorrow. `rows_avail_h` is the *rows*
+    area's own pixel budget only -- the caller has already reserved a
+    separate, uniform header_h (which is where weather actually renders,
+    see the day-header macro) for every section, so this function
+    doesn't need to account for weather space itself."""
+    header = day.strftime("%A, %B ") + str(day.day)
+    weather_entries = _weather_row(weather_cities, day, weather_units)
+    max_rows = max(0, rows_avail_h // row_h)
+
+    day_events = _events_on_day(events, day, tz)
+    rows = []
+    for event in day_events[:max_rows]:
+        colors = _event_colors(event, owners_seen, palette_rgb)
+        time_str = "All day" if event["all_day"] else _fmt_time(_event_start(event, tz))
+        rows.append({"colors": [html_render._rgb_to_hex(c) for c in colors], "time": time_str,
+                     "summary": event["summary"]})
+    return {"header": header, "weather_entries": weather_entries, "rows": rows,
+            "more_count": max(0, len(day_events) - max_rows)}
+
+
+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", theme_name: str | None = None,
+                 font_scale: float = 1.0) -> Image.Image:
+    """HTML/CSS-rendered analogue of calendar_render._build_agenda.
+
+    Bold-minimal: no card/border/shadow (theme["radius"]/theme["shadow"]
+    are unused, same carve-out as weather's build_current/build_daily --
+    see docs/widgets.md). The day header is plain ink text under a slim
+    accent-colored rule instead of white text on a full gradient band --
+    only that thin rule dithers at the theme's richer accent_amplitude
+    now, not the header text sitting on top of it, which is a legibility
+    improvement over the old design, not just a visual one."""
+    theme = theme_tokens.resolve_theme(theme_name, "calendar", palette_rgb)
+    day = datetime.now(tz).date() + timedelta(days=browse_offset)
+    title_size = panel_style.scaled_size(max(14, min(target_w, target_h) // 12), font_scale)
+    body_size = panel_style.scaled_size(max(11, min(target_w, target_h) // 20), font_scale)
+    weather_size = max(10, body_size - 2)
+    row_h = body_size + 14
+    unit_suffix = "F" if weather_units == "fahrenheit" else "C"
+    accent_h = round(html_render._clamp(min(target_w, target_h) * 0.025, 4, 8))
+
+    # Single day -- no cross-section alignment concern, so header_h can
+    # simply reflect whether THIS day actually has weather (unlike
+    # build_today_tomorrow/build_week's vertical layout, which must
+    # reserve the same header_h for every stacked section regardless).
+    has_weather = bool(_weather_row(weather_cities, day, weather_units))
+    header_h = accent_h + 10 + title_size + ((weather_size + 10) if has_weather else 0)
+
+    owners_seen: list[str] = []
+    data = _day_section_data(day, events, tz, palette_rgb, weather_cities, weather_units, owners_seen,
+                             target_h - header_h - MARGIN, row_h)
+
+    template = html_render._jinja_env.get_template("calendar_agenda.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, gutter=panel_style.GUTTER,
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+        header=data["header"], title_size=title_size, header_h=header_h, accent_h=accent_h,
+        accent_start=theme["accent_hex"], weather_entries=data["weather_entries"],
+        weather_size=weather_size, unit_suffix=unit_suffix, rows=data["rows"],
+        more_count=data["more_count"], row_h=row_h, body_size=body_size,
+    )
+    rendered = html_render.render_html_to_image(html, target_w, target_h)
+    gutter = panel_style.GUTTER
+    accent_rect = (gutter, gutter, target_w - gutter, gutter + accent_h)
+    return html_render.ordered_dither_regions(
+        rendered, palette_rgb, accent_regions=[(accent_rect, theme["accent_amplitude"])]
+    )
+
+
+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", theme_name: str | None = None,
+                         font_scale: float = 1.0) -> Image.Image:
+    """HTML/CSS-rendered analogue of calendar_render._build_today_tomorrow
+    -- two day-sections stacked (see _day_section_data). Bold-minimal, no
+    card (see build_agenda's docstring) -- each section's own slim accent
+    rule dithers richer via ordered_dither_regions, not its header text."""
+    theme = theme_tokens.resolve_theme(theme_name, "calendar", palette_rgb)
+    start_day = datetime.now(tz).date() + timedelta(days=browse_offset)
+    section_h = target_h // 2
+    title_size = panel_style.scaled_size(max(13, section_h // 8), font_scale)
+    body_size = panel_style.scaled_size(max(10, min(target_w, target_h) // 26), font_scale)
+    weather_size = max(9, body_size - 2)
+    row_h = body_size + 12
+    unit_suffix = "F" if weather_units == "fahrenheit" else "C"
+    accent_h = round(html_render._clamp(min(target_w, target_h) * 0.02, 3, 6))
+
+    day_dates = [start_day + timedelta(days=i) for i in range(2)]
+    # Uniform across both stacked sections regardless of which day(s)
+    # actually have weather -- see _day_section_data's own docstring for
+    # why a per-day header height misaligns where rows start.
+    any_weather = any(_weather_row(weather_cities, d, weather_units) for d in day_dates)
+    header_h = accent_h + 8 + title_size + ((weather_size + 8) if any_weather else 0)
+
+    owners_seen: list[str] = []
+    days = [
+        _day_section_data(d, events, tz, palette_rgb, weather_cities, weather_units, owners_seen,
+                          section_h - header_h, row_h)
+        for d in day_dates
+    ]
+
+    template = html_render._jinja_env.get_template("calendar_today_tomorrow.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, gutter=panel_style.GUTTER,
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+        days=days, title_size=title_size, header_h=header_h, accent_h=accent_h,
+        accent_start=theme["accent_hex"], weather_size=weather_size,
+        unit_suffix=unit_suffix, row_h=row_h, body_size=body_size,
+    )
+    rendered = html_render.render_html_to_image(html, target_w, target_h)
+    gutter = panel_style.GUTTER
+    accent_regions = [
+        ((gutter, gutter + i * section_h, target_w - gutter, gutter + i * section_h + accent_h),
+         theme["accent_amplitude"])
+        for i in range(len(days))
+    ]
+    return html_render.ordered_dither_regions(rendered, palette_rgb, accent_regions=accent_regions)
+
+
+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, theme_name: str | None = None, font_scale: float = 1.0) -> Image.Image:
+    """HTML/CSS-rendered analogue of calendar_render._build_week -- both
+    the vertical (stacked day-sections, reusing build_today_tomorrow's
+    template with an arbitrary day count) and horizontal (side-by-side
+    columns) layouts. Each header (per-section or per-column) dithers
+    richer via ordered_dither_regions."""
+    theme = theme_tokens.resolve_theme(theme_name, "calendar", palette_rgb)
+    gutter = panel_style.GUTTER
+    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)
+    unit_suffix = "F" if weather_units == "fahrenheit" else "C"
+    owners_seen: list[str] = []
+
+    if layout == "vertical":
+        section_h = target_h // days
+        title_size = panel_style.scaled_size(max(11, min(20, section_h // 6)), font_scale)
+        body_size = panel_style.scaled_size(max(9, min(target_w, target_h) // (18 + days)), font_scale)
+        weather_size = max(8, body_size - 2)
+        row_h = body_size + 10
+        accent_h = round(html_render._clamp(min(target_w, target_h) * 0.018, 3, 5))
+        day_dates = [week_first_day + timedelta(days=i) for i in range(days)]
+        # Uniform across all `days` stacked sections -- see
+        # _day_section_data's own docstring for why a per-day header
+        # height misaligns where rows start.
+        any_weather = any(_weather_row(weather_cities, d, weather_units) for d in day_dates)
+        header_h = accent_h + 6 + title_size + ((weather_size + 6) if any_weather else 0)
+        day_sections = [
+            _day_section_data(d, events, tz, palette_rgb, weather_cities, weather_units, owners_seen,
+                             section_h - header_h, row_h)
+            for d in day_dates
+        ]
+        template = html_render._jinja_env.get_template("calendar_today_tomorrow.html.jinja")
+        html = template.render(
+            w=target_w, h=target_h, gutter=gutter,
+            font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+            days=day_sections, title_size=title_size, header_h=header_h, accent_h=accent_h,
+            accent_start=theme["accent_hex"], weather_size=weather_size,
+            unit_suffix=unit_suffix, row_h=row_h, body_size=body_size,
+        )
+        rendered = html_render.render_html_to_image(html, target_w, target_h)
+        accent_regions = [
+            ((gutter, gutter + i * section_h, target_w - gutter, gutter + i * section_h + accent_h),
+             theme["accent_amplitude"])
+            for i in range(len(day_sections))
+        ]
+        return html_render.ordered_dither_regions(rendered, palette_rgb, accent_regions=accent_regions)
+
+    header_size = panel_style.scaled_size(max(10, min(16, (target_w // days) // 6)), font_scale)
+    chip_size = max(9, header_size - 3)
+    weather_size = max(8, chip_size - 1)
+    col_w = max(1, (target_w - panel_style.GUTTER * 2) // days)
+    row_h = chip_size + 8
+    accent_h = round(html_render._clamp(min(target_w, target_h) * 0.02, 3, 6))
+    # Reserve weather-line room in every column's header uniformly
+    # (whether or not THIS specific day has a cached forecast) -- a
+    # per-column height that depends on that day's own data would
+    # misalign where each column's event rows start across the week
+    # grid the moment any single day lacks a forecast entry.
+    header_h = header_size + 8 + (weather_size + 4 if weather_cities else 0)
+    max_rows = max(0, (target_h - panel_style.GUTTER * 2 - accent_h - 6 - header_h) // row_h)
+
+    cols = []
+    for i in range(days):
+        day = week_first_day + timedelta(days=i)
+        label = day.strftime("%a %-d") if day != today else f"★ {day.strftime('%a %-d')}"
+        weather_entries = _weather_row(weather_cities, day, weather_units)
+        day_events = _events_on_day(events, day, tz)
+        rows = []
+        for event in day_events[:max_rows]:
+            color = html_render._rgb_to_hex(_event_colors(event, owners_seen, palette_rgb)[0])
+            summary = event["summary"] if event["all_day"] else f"{_fmt_time(_event_start(event, tz))[:-3]} {event['summary']}"
+            rows.append({"color": color, "summary": summary})
+        cols.append({
+            "label": label, "weather": weather_entries[0] if weather_entries else None,
+            "rows": rows, "more_count": max(0, len(day_events) - max_rows),
+        })
+
+    template = html_render._jinja_env.get_template("calendar_week_horizontal.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, gutter=gutter,
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+        cols=cols, header_size=header_size, chip_size=chip_size,
+        header_h=header_h, accent_h=accent_h, weather_size=weather_size, unit_suffix=unit_suffix,
+        accent_start=theme["accent_hex"],
+    )
+    rendered = html_render.render_html_to_image(html, target_w, target_h)
+    accent_rect = (gutter, gutter, target_w - gutter, gutter + accent_h)
+    return html_render.ordered_dither_regions(rendered, palette_rgb, accent_regions=[(accent_rect, theme["accent_amplitude"])])
+
+
+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, theme_name: str | None = None,
+               font_scale: float = 1.0) -> Image.Image:
+    """HTML/CSS-rendered analogue of calendar_render._build_month --
+    density dots per day, not literal event text, same reasoning as the
+    classic renderer (real text at typical month-cell size is close to
+    unreadable on a 6-color dithered e-ink panel). The per-owner event
+    dots are identity-coding (like every other calendar view's chips) and
+    are never touched by a theme.
+
+    Bold-minimal: no card (see build_agenda's docstring); the old flat
+    accent-colored weekday-name band is now a slim accent rule above
+    plain bold weekday labels, matching every other calendar view's
+    header treatment -- only that rule dithers at the theme's richer
+    accent_amplitude via ordered_dither_regions. "Today" is still called
+    out with a small accent-filled pill around its day number (a
+    genuinely small accent surface, not a band, so it was left alone)."""
+    theme = theme_tokens.resolve_theme(theme_name, "calendar", palette_rgb)
+    gutter = panel_style.GUTTER
+    today = datetime.now(tz).date()
+    target_month = _add_months(date(today.year, today.month, 1), browse_offset)
+    weeks_dates = list(
+        calendar_module.Calendar(firstweekday=week_start).monthdatescalendar(target_month.year, target_month.month)
+    )
+    day_names = [n[:3] for n in (WEEKDAY_NAMES[week_start:] + WEEKDAY_NAMES[:week_start])]
+
+    header_size = panel_style.scaled_size(max(11, min(16, target_h // 30)), font_scale)
+    day_size = panel_style.scaled_size(max(10, min(15, target_w // 55)), font_scale)
+    dot_size = max(4, day_size // 2)
+    accent_h = round(html_render._clamp(min(target_w, target_h) * 0.02, 3, 6))
+
+    owners_seen: list[str] = []
+    weeks = []
+    for week in weeks_dates:
+        row = []
+        for day in week:
+            day_events = _events_on_day(events, day, tz)
+            dots = [html_render._rgb_to_hex(_event_colors(e, owners_seen, palette_rgb)[0]) for e in day_events[:4]]
+            row.append({
+                "day_num": day.day, "in_month": day.month == target_month.month,
+                "is_today": day == today, "dots": dots, "more_count": max(0, len(day_events) - 4),
+            })
+        weeks.append(row)
+
+    template = html_render._jinja_env.get_template("calendar_month.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, gutter=gutter,
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+        day_names=day_names, weeks=weeks, accent_h=accent_h,
+        header_size=header_size, day_size=day_size, dot_size=dot_size, accent_start=theme["accent_hex"],
+    )
+    rendered = html_render.render_html_to_image(html, target_w, target_h)
+    accent_rect = (gutter, gutter, target_w - gutter, gutter + accent_h)
+    return html_render.ordered_dither_regions(rendered, palette_rgb,
+                                              accent_regions=[(accent_rect, theme["accent_amplitude"])])
+
+
+def build(events: list[dict], view: str, 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", week_days: int = 7, week_layout: str = "horizontal",
+         week_start_offset: int = 0, theme_name: str | None = None, font_scale: float = 1.0) -> Image.Image:
+    """Dispatches to the right build_* -- mirrors calendar_render._build's
+    exact "month falls back to agenda when it doesn't fit" resolution, so
+    a narrow month-mode widget set to modern style still gets a sensible
+    modern view instead of erroring or silently reverting to classic."""
+    effective_view = view
+    if view == "month" and not _month_view_fits(target_w, target_h):
+        effective_view = "agenda"
+
+    if effective_view == "agenda":
+        return build_agenda(events, browse_offset, target_w, target_h, tz, palette_rgb, weather_cities,
+                            weather_units, theme_name, font_scale)
+    if effective_view == "today_tomorrow":
+        return build_today_tomorrow(events, browse_offset, target_w, target_h, tz, palette_rgb, weather_cities,
+                                    weather_units, theme_name, font_scale)
+    if effective_view == "week":
+        return 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, theme_name, font_scale)
+    return build_month(events, browse_offset, target_w, target_h, tz, week_start, palette_rgb, theme_name, font_scale)
@@ -1,50 +1,105 @@
-"""Renders calendar frame mode's three views (agenda/week/month) 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.
+"""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", "owner_display_name"}.
+(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/panel_style.draw_color_chip 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 . import panel_style
 from .image_pipeline import (
    DEFAULT_PALETTE_RGB,
+    EPD_HEIGHT,
+    EPD_WIDTH,
    _apply_manage_overlay,
    _quantize,
    _transpose_and_pack,
-    compose_into,
+    draw_text,
    logical_render_size,
 )
+from .weather import weather_category
+from .weather_render import draw_weather_row

-CALENDAR_VIEWS = ["agenda", "week", "month"]
-CALENDAR_VIEW_LABELS = {"agenda": "Agenda (today)", "week": "Week", "month": "Month"}
+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
+# MARGIN carries panel_style.CONTENT_MARGIN's value unchanged (not
+# re-tuned). BG/FG are this module's own plain black/white -- checkbox
+# outlines, month-view grid hairlines -- not a text-emphasis concern (no
+# MUTED gray here anymore -- see panel_style's module docstring for why:
+# a mid-gray fill has no close palette match and dithers into speckle
+# once the whole canvas is quantized. Secondary text now reads through
+# size/weight alone, always exact black).
+MARGIN = panel_style.CONTENT_MARGIN
 BG = (255, 255, 255)
 FG = (0, 0, 0)
-MUTED = (110, 110, 110)
-RULE = (200, 200, 200)
+# Structural dividers/grid lines (between stacked day sections, week
+# columns, month cells) stay a plain black rule -- gray dithers away to
+# near-invisible once quantized to the 6-color e-ink palette. Headers
+# no longer use this: see panel_style.draw_header_bar/theme_color.
+RULE = (0, 0, 0)

-# Cycled per distinct owner_display_name so a merged multi-person calendar
-# can 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.
+# 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 _owner_color(owner_display_name: str, owners_seen: list[str]) -> tuple[int, int, int]:
-    if owner_display_name not in owners_seen:
-        owners_seen.append(owner_display_name)
-    return OWNER_COLORS[owners_seen.index(owner_display_name) % len(OWNER_COLORS)]
+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
+    panel_style.draw_color_chip. 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 _event_start(event: dict, tz: ZoneInfo) -> datetime | date:
@@ -82,11 +137,184 @@ def _fmt_time(dt: datetime) -> str:
    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")
+
+
+# Neither Inter (panel_style.font_bold/font_regular, this module's own
+# body/title font -- see MARGIN/BG/FG comment above) nor PIL's bundled
+# default font has 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."""
+    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 = "..."
@@ -100,191 +328,559 @@ def _truncate_to_width(draw: ImageDraw.ImageDraw, text: str, font: ImageFont.Ima
    return text[:lo] + ellipsis if lo else ellipsis


-def _build_agenda(events: list[dict], browse_offset: int, orientation: str, tz: ZoneInfo,
-                  photo_inlay: Image.Image | None) -> Image.Image:
-    logical_w, logical_h = logical_render_size(orientation)
-    img = Image.new("RGB", (logical_w, logical_h), BG)
+# --- 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

-    text_x0 = MARGIN
-    text_w = logical_w - MARGIN * 2
-    if photo_inlay is not None:
-        # Long axis split: landscape splits left/right, portrait top/bottom.
-        if logical_w >= logical_h:
-            photo_w = logical_w // 2
-            photo = compose_into(photo_inlay, None, photo_w, logical_h, "crop_fill")
-            img.paste(photo, (0, 0))
-            text_x0 = photo_w + MARGIN
-            text_w = logical_w - photo_w - MARGIN * 2
-        else:
-            photo_h = logical_h // 2
-            photo = compose_into(photo_inlay, None, logical_w, photo_h, "crop_fill")
-            img.paste(photo, (0, 0))

-    draw = ImageDraw.Draw(img)
-    # Smaller title when the inlay halves the available width -- "Wednesday,
-    # July 22" at full size doesn't fit ~360px, and a *narrower* column is
-    # exactly when a smaller font (rather than truncating to "Wednesday...")
-    # keeps it actually informative.
-    title_font = ImageFont.load_default(size=34 if photo_inlay is None else 24)
-    body_font = ImageFont.load_default(size=22)
+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"

-    text_y0 = MARGIN if photo_inlay is None or logical_w >= logical_h else logical_h // 2 + MARGIN
-    day = datetime.now(tz).date() + timedelta(days=browse_offset)
+
+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 bar above it already does."""
+    x0, y0, w, h = region
+    header_h = title_font.size + 20
+    panel_style.draw_header_bar(draw, (x0, y0, w, header_h), header_h,
+                                panel_style.theme_color("calendar", palette_rgb))
+    text_x0 = x0 + MARGIN
+    text_w = w - MARGIN * 2
    header = day.strftime("%A, %B ") + str(day.day)
-    draw.text((text_x0, text_y0), _truncate_to_width(draw, header, title_font, text_w), fill=FG, font=title_font)
-    y = text_y0 + title_font.size + 12
-    draw.line([(text_x0, y), (text_x0 + text_w, y)], fill=RULE)
-    y += 12
+    draw_text(img, (text_x0, y0 + (header_h - title_font.size) // 2),
+             _truncate_to_width(draw, header, title_font, text_w), title_font, BG)
+    y = y0 + header_h + 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)
-    owners_seen: list[str] = []
    row_h = body_font.size + 14
-    max_rows = max(0, (logical_h - MARGIN - y) // row_h)
+    max_rows = max(0, (y0 + h - MARGIN - y) // row_h)

    if not day_events:
-        draw.text((text_x0, y), "Nothing scheduled", fill=MUTED, font=body_font)
+        draw_text(img, (text_x0, y), "Nothing scheduled", body_font)
    for i, event in enumerate(day_events):
        if i >= max_rows:
-            draw.text((text_x0, y), f"+{len(day_events) - max_rows} more", fill=MUTED, font=body_font)
+            draw_text(img, (text_x0, y), f"+{len(day_events) - max_rows} more", body_font)
            break
-        color = _owner_color(event["owner_display_name"], owners_seen)
-        draw.rectangle([text_x0, y + 3, text_x0 + 6, y + row_h - 8], fill=color)
+        colors = _event_colors(event, owners_seen, palette_rgb)
+        panel_style.draw_color_chip(draw, text_x0, y + 2, text_x0 + 10, y + row_h - 7, colors)
        time_str = "All day" if event["all_day"] else _fmt_time(_event_start(event, tz))
-        line = f"{time_str}  {event['summary']}"
-        draw.text((text_x0 + 16, y), _truncate_to_width(draw, line, body_font, text_w - 16), fill=FG, font=body_font)
+        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 chip
+    (reusing _event_colors/panel_style.draw_color_chip 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/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 checkbox in
+    this widget's own Green accent (see panel_style.THEME) -- that fill
+    is the "done" signal, no due-date prefix (irrelevant once done) and
+    no separate muted text treatment (see module-level MUTED removal
+    note above _event_colors)."""
+    x0, y0, w, h = region
+    header_h = title_font.size + 20
+    panel_style.draw_header_bar(draw, (x0, y0, w, header_h), header_h,
+                                panel_style.theme_color("tasks", palette_rgb))
+    text_x0 = x0 + MARGIN
+    text_w = w - MARGIN * 2
+    draw_text(img, (text_x0, y0 + (header_h - title_font.size) // 2),
+             _truncate_to_width(draw, title or "Tasks", title_font, text_w), title_font, BG)
+    y = y0 + header_h + 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)
+        return
+    owners_seen: list[str] = []
+    checkbox_fill = panel_style.theme_color("tasks", palette_rgb)
+    for i, task in enumerate(tasks):
+        if i >= max_rows:
+            draw_text(img, (text_x0, y), f"+{len(tasks) - max_rows} more", body_font)
+            break
+        done = task.get("completed_at") is not None
+        colors = _event_colors(task, owners_seen, palette_rgb)
+        panel_style.draw_color_chip(draw, text_x0, y + 2, text_x0 + 10, y + row_h - 7, colors)
+        box = body_font.size - 6
+        box_x = text_x0 + 18
+        box_y = y + (row_h - box) // 2 - 5
+        box_r = min(panel_style.CHIP_RADIUS, box // 2)
+        if done:
+            draw.rounded_rectangle([box_x, box_y, box_x + box, box_y + box], radius=box_r, fill=checkbox_fill)
+        else:
+            draw.rounded_rectangle([box_x, box_y, box_x + box, box_y + box], radius=box_r, 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)
+        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)
+        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", font_scale: float = 1.0) -> Image.Image:
+    img, draw, region = panel_style.card_canvas(target_w, target_h)
+
+    title_size, body_size, weather_size = (
+        panel_style.scaled_size(v, font_scale) for v in _AGENDA_FONTS[_size_tier(target_w, target_h)]
+    )
+    title_font = panel_style.font_bold(title_size)
+    body_font = panel_style.font_regular(body_size)
+    weather_font = panel_style.font_regular(weather_size)
+
+    day = datetime.now(tz).date() + timedelta(days=browse_offset)
+    owners_seen: list[str] = []
+    _draw_agenda_day(img, draw, day, events, tz, region, title_font, body_font, owners_seen,
+                     palette_rgb, weather_cities, weather_font, weather_units)
+
    return img


-def _build_week(events: list[dict], browse_offset: int, orientation: str, tz: ZoneInfo) -> Image.Image:
-    logical_w, logical_h = logical_render_size(orientation)
-    img = Image.new("RGB", (logical_w, logical_h), BG)
-    draw = ImageDraw.Draw(img)
+_TODAY_TOMORROW_FONTS = {"large": (26, 18, 16), "medium": (20, 15, 13), "small": (15, 12, 10)}

-    header_font = ImageFont.load_default(size=18)
-    chip_font = ImageFont.load_default(size=14)
+
+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", font_scale: float = 1.0) -> 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, draw, (cx0, cy0, cw, ch) = panel_style.card_canvas(target_w, target_h)
+
+    title_size, body_size, weather_size = (
+        panel_style.scaled_size(v, font_scale) for v in _TODAY_TOMORROW_FONTS[_size_tier(target_w, target_h)]
+    )
+    title_font = panel_style.font_bold(title_size)
+    body_font = panel_style.font_regular(body_size)
+    weather_font = panel_style.font_regular(weather_size)
+
+    start_day = datetime.now(tz).date() + timedelta(days=browse_offset)
+    section_h = ch // 2
+    owners_seen: list[str] = []
+    for i in range(2):
+        section_y0 = cy0 + i * section_h
+        if i > 0:
+            draw.line([(cx0 + MARGIN, section_y0), (cx0 + cw - MARGIN, section_y0)], fill=RULE)
+        _draw_agenda_day(img, draw, start_day + timedelta(days=i), events, tz,
+                         (cx0, section_y0, cw, 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, font_scale: float = 1.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, draw, (cx0, cy0, cw, ch) = panel_style.card_canvas(target_w, target_h)
+    tier = _size_tier(target_w, target_h)

    today = datetime.now(tz).date()
-    week_start = today - timedelta(days=today.weekday()) + timedelta(weeks=browse_offset)
-    col_w = (logical_w - MARGIN * 2) // 7
-    header_h = 44
+    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] = []

-    for col in range(7):
-        day = week_start + timedelta(days=col)
-        x0 = MARGIN + col * col_w
-        if col > 0:
-            draw.line([(x0, MARGIN), (x0, logical_h - MARGIN)], fill=RULE)
-        label = day.strftime("%a %-d") if day != today else f"* {day.strftime('%a %-d')}"
-        draw.text((x0 + 6, MARGIN), _truncate_to_width(draw, label, header_font, col_w - 10), fill=FG, font=header_font)
+    if layout == "vertical":
+        title_base, body_base, weather_base = _WEEK_VERTICAL_FONTS[tier]
+        title_font = panel_style.font_bold(panel_style.scaled_size(max(14, title_base - days), font_scale))
+        body_font = panel_style.font_regular(panel_style.scaled_size(max(11, body_base - days), font_scale))
+        weather_font = panel_style.font_regular(panel_style.scaled_size(max(9, weather_base - days), font_scale))
+        section_h = ch // days
+        for i in range(days):
+            section_y0 = cy0 + i * section_h
+            if i > 0:
+                draw.line([(cx0 + MARGIN, section_y0), (cx0 + cw - MARGIN, section_y0)], fill=RULE)
+            day = week_first_day + timedelta(days=i)
+            _draw_agenda_day(img, draw, day, events, tz, (cx0, section_y0, cw, section_h),
+                             title_font, body_font, owners_seen, palette_rgb,
+                             weather_cities, weather_font, weather_units)
+        return img

-        y = MARGIN + header_h
+    header_size, chip_size, weather_size = (
+        panel_style.scaled_size(v, font_scale) for v in _WEEK_HORIZONTAL_FONTS[tier]
+    )
+    header_font = panel_style.font_bold(header_size)
+    chip_font = panel_style.font_regular(chip_size)
+    weather_font = panel_style.font_regular(weather_size)
+    col_w = (cw - MARGIN * 2) // days
+    header_h = 44
+
+    for col in range(days):
+        day = week_first_day + timedelta(days=col)
+        x0 = cx0 + MARGIN + col * col_w
+        if col > 0:
+            draw.line([(x0, cy0 + MARGIN), (x0, cy0 + ch - MARGIN)], fill=RULE)
+        label = day.strftime("%a %-d") if day != today else f"* {day.strftime('%a %-d')}"
+        draw_text(img, (x0 + 6, cy0 + MARGIN), _truncate_to_width(draw, label, header_font, col_w - 10), header_font)
+
+        y = cy0 + 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, (logical_h - MARGIN - y) // row_h)
+        max_rows = max(0, (cy0 + ch - 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((x0 + 6, y), f"+{len(day_events) - max_rows}", fill=MUTED, font=chip_font)
+                draw_text(img, (x0 + 6, y), f"+{len(day_events) - max_rows}", chip_font)
                break
-            color = _owner_color(event["owner_display_name"], owners_seen)
-            draw.rectangle([x0 + 4, y + 2, x0 + 8, y + row_h - 6], fill=color)
-            text = event["summary"] if event["all_day"] else f"{_fmt_time(_event_start(event, tz))[:-3]} {event['summary']}"
-            draw.text((x0 + 14, y), _truncate_to_width(draw, text, chip_font, col_w - 18), fill=FG, font=chip_font)
+            colors = _event_colors(event, owners_seen, palette_rgb)
+            panel_style.draw_color_chip(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


-def _build_month(events: list[dict], browse_offset: int, orientation: str, tz: ZoneInfo) -> Image.Image:
+# 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, font_scale: float = 1.0) -> 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."""
-    logical_w, logical_h = logical_render_size(orientation)
-    img = Image.new("RGB", (logical_w, logical_h), BG)
-    draw = ImageDraw.Draw(img)
+    6-color dithered e-ink panel. Capped at 4 visible dots, "+N" beyond.
+    "Not in this month" day numbers used to be a muted gray -- now
+    de-emphasized by weight instead (Regular vs. Bold), same reasoning
+    as everywhere else this module dropped MUTED -- see module-level
+    comment above MARGIN/BG/FG."""
+    img, draw, (cx0, cy0, cw, ch) = panel_style.card_canvas(target_w, target_h)

-    header_font = ImageFont.load_default(size=16)
-    day_font = ImageFont.load_default(size=18)
+    header_size, day_size = (
+        panel_style.scaled_size(v, font_scale) for v in _MONTH_FONTS[_size_tier(target_w, target_h)]
+    )
+    header_font = panel_style.font_bold(header_size)
+    day_font_in_month = panel_style.font_bold(day_size)
+    day_font_out_of_month = panel_style.font_regular(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=0).monthdatescalendar(target_month.year, target_month.month))
+    weeks = list(calendar_module.Calendar(firstweekday=week_start).monthdatescalendar(target_month.year, target_month.month))

-    col_w = (logical_w - MARGIN * 2) // 7
+    col_w = (cw - MARGIN * 2) // 7
    header_h = 28
-    grid_top = MARGIN + header_h
-    row_h = (logical_h - MARGIN - grid_top) // len(weeks)
+    grid_top = cy0 + MARGIN + header_h
+    row_h = (cy0 + ch - MARGIN - grid_top) // len(weeks)
+    today_accent = panel_style.theme_color("calendar", palette_rgb)
+    today_badge_r = min(panel_style.CHIP_RADIUS, 9)

-    for col, name in enumerate(["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]):
-        draw.text((MARGIN + col * col_w + 6, MARGIN), name, fill=MUTED, font=header_font)
+    day_names = WEEKDAY_NAMES[week_start:] + WEEKDAY_NAMES[:week_start]
+    for col, name in enumerate(day_names):
+        draw_text(img, (cx0 + MARGIN + col * col_w + 6, cy0 + MARGIN), name[:3], header_font)

    owners_seen: list[str] = []
-    dot_r = 4
+    dot_r = 6
    for row, week in enumerate(weeks):
        for col, day in enumerate(week):
-            x0 = MARGIN + col * col_w
+            x0 = cx0 + 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
-            color = FG if in_month else MUTED
            if day == today:
-                draw.rectangle([x0 + 2, y0 + 2, x0 + 24, y0 + 20], outline=FG)
-            draw.text((x0 + 6, y0 + 4), str(day.day), fill=color, font=day_font)
+                # A filled accent badge (this widget's own theme color,
+                # see panel_style.THEME) instead of the old bare outline
+                # -- an actual "today" indicator, not just an outline
+                # easy to miss at ~24px. Sized around the actual digit
+                # bbox (not a fixed pixel box) so a bold 2-digit day
+                # number ("30") fits as comfortably as a single digit
+                # ("3") at every size tier.
+                day_str = str(day.day)
+                text_x, text_y = x0 + 6, y0 + 4
+                dbbox = draw.textbbox((text_x, text_y), day_str, font=day_font_in_month)
+                pad = 3
+                badge_rect = [dbbox[0] - pad, dbbox[1] - pad, dbbox[2] + pad, dbbox[3] + pad]
+                badge_r = min(today_badge_r, (badge_rect[3] - badge_rect[1]) // 2)
+                draw.rounded_rectangle(badge_rect, radius=badge_r, fill=today_accent)
+                draw_text(img, (text_x, text_y), day_str, day_font_in_month, BG)
+            else:
+                day_font = day_font_in_month if in_month else day_font_out_of_month
+                draw_text(img, (x0 + 6, y0 + 4), str(day.day), day_font)

            day_events = _events_on_day(events, day, tz)
            dot_x = x0 + 8
-            dot_y = y0 + row_h - 14
+            dot_y = y0 + row_h - dot_r * 2 - 6
            for i, event in enumerate(day_events[:4]):
-                color = _owner_color(event["owner_display_name"], owners_seen)
-                draw.ellipse([dot_x, dot_y, dot_x + dot_r * 2, dot_y + dot_r * 2], fill=color)
-                dot_x += dot_r * 2 + 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((dot_x, dot_y - 4), f"+{len(day_events) - 4}", fill=MUTED, font=header_font)
+                draw_text(img, (dot_x, dot_y - 2), f"+{len(day_events) - 4}", header_font)

    return img


-_BUILDERS = {"agenda": _build_agenda, "week": _build_week, "month": _build_month}
+_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, orientation: str, timezone: str,
-          photo_inlay: Image.Image | None, fetch_summary: str) -> Image.Image:
+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, font_scale: float = 1.0) -> Image.Image:
    tz = ZoneInfo(timezone) if timezone else ZoneInfo("UTC")
-    builder = _BUILDERS.get(view, _build_agenda)
-    if builder is _build_agenda:
-        img = _build_agenda(events, browse_offset, orientation, tz, photo_inlay)
+    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, font_scale)
+    elif effective_view == "today_tomorrow":
+        img = _build_today_tomorrow(events, browse_offset, target_w, target_h, tz, palette_rgb,
+                                    weather_cities, weather_units, font_scale)
+    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, font_scale)
+    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, font_scale)
    else:
-        img = builder(events, browse_offset, orientation, tz)
+        img = _build_agenda(events, browse_offset, target_w, target_h, tz, palette_rgb,
+                            weather_cities, weather_units, font_scale)

    if fetch_summary:
-        draw = ImageDraw.Draw(img)
-        font = ImageFont.load_default(size=14)
-        logical_w, logical_h = img.size
-        draw.text((MARGIN, logical_h - MARGIN - font.size), fetch_summary, fill=MUTED, font=font)
+        # Drawn as a final overlay onto the already-composited img (not
+        # inside any one _build_* branch above), so it offsets by
+        # panel_style.GUTTER itself to land inside the same visible
+        # margin every builder's own content already respects.
+        font = panel_style.font_regular(14 if _size_tier(target_w, target_h) != "small" else 11)
+        draw_text(img, (panel_style.GUTTER + MARGIN, target_h - panel_style.GUTTER - MARGIN - font.size),
+                 fetch_summary, font)

    return img


 def render_calendar(events: list[dict], view: str, browse_offset: int, orientation: str,
-                    palette_rgb: list | None, timezone: str, photo_inlay: Image.Image | None = None,
-                    fetch_summary: str = "", manage: dict | None = None) -> bytes:
-    """Renders one of CALENDAR_VIEWS to the panel's packed format. Always
-    returns exactly EPD_WIDTH*EPD_HEIGHT/2 bytes, same invariant every
-    other renderer honors."""
-    img = _build(events, view, browse_offset, orientation, timezone, photo_inlay, fetch_summary)
+                    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, panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> bytes:
+    """Renders one of CALENDAR_VIEWS full-panel to the panel's packed
+    format. Returns exactly panel_w*panel_h/2 bytes (see
+    image_pipeline.panel_size), 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, panel_w, panel_h)
+    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, photo_inlay: Image.Image | None = None,
-                                fetch_summary: str = "", manage: dict | None = None) -> bytes:
+                                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, font_scale: float = 1.0,
+                                panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> 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."""
-    img = _build(events, view, browse_offset, orientation, timezone, photo_inlay, fetch_summary)
+    target_w, target_h = logical_render_size(orientation, panel_w, panel_h)
+    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, font_scale)
+    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", font_scale: float = 1.0) -> 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, draw, region = panel_style.card_canvas(target_w, target_h)
+    title_size, body_size = (
+        panel_style.scaled_size(v, font_scale) for v in _TASKS_FONTS[_size_tier(target_w, target_h)]
+    )
+    title_font = panel_style.font_bold(title_size)
+    body_font = panel_style.font_regular(body_size)
+    _draw_tasks(img, draw, region, 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",
+                 panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> bytes:
+    """Renders the tasks widget full-panel to the panel's packed format.
+    Returns exactly panel_w*panel_h/2 bytes, same invariant every other
+    renderer honors."""
+    target_w, target_h = logical_render_size(orientation, panel_w, panel_h)
+    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", font_scale: float = 1.0,
+                             panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> 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, panel_w, panel_h)
+    img = _build_tasks(tasks, target_w, target_h, palette_rgb, title, font_scale=font_scale)
    img = _apply_manage_overlay(img, manage)
    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
    buf = io.BytesIO()
@@ -16,7 +16,7 @@ from typing import Iterator
 from sqlalchemy import create_engine, event
 from sqlalchemy.orm import Session, sessionmaker

-from .models import Frame
+from .models import WIDGET_CONFIG_MODELS, Frame, Widget

 DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:////data/espresso.db")

@@ -86,3 +86,33 @@ def frame_locked(db: Session, frame_id: int) -> Iterator[Frame]:
        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
@@ -15,7 +15,7 @@ import io

 from PIL import Image, ImageOps

-from .image_pipeline import _has_bounding_box, _placement_transform, logical_render_size
+from .image_pipeline import EPD_HEIGHT, EPD_WIDTH, _has_bounding_box, _placement_transform, logical_render_size

 # Not a memory constraint anymore (the overlay renders server-side now,
 # not malloc'd per-label on the device) -- purely a legibility cap. A
@@ -25,7 +25,8 @@ MAX_LABELED_FACES = 6


 def compute_face_labels(preview_bytes: bytes, faces: list[dict], display_mode: str,
-                        orientation: str = "landscape") -> list[dict]:
+                        orientation: str = "landscape", region: tuple[int, int, int, int] | None = None,
+                        panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> 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
@@ -38,6 +39,15 @@ def compute_face_labels(preview_bytes: bytes, faces: list[dict], display_mode: s
    match the settings that were active then -- otherwise the placement
    computed here won't match what's actually on screen.

+    `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).
@@ -46,11 +56,16 @@ def compute_face_labels(preview_bytes: bytes, faces: list[dict], display_mode: s
    if not named:
        return []

-    logical_w, logical_h = logical_render_size(orientation)
+    if region is None:
+        logical_w, logical_h = logical_render_size(orientation, panel_w, panel_h)
+        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"))

    scale_x, scale_y, offset_x, offset_y = _placement_transform(
-        fitted.width, fitted.height, logical_w, logical_h, display_mode, faces
+        fitted.width, fitted.height, target_w, target_h, display_mode, faces
    )

    labels = []
@@ -65,12 +80,16 @@ def compute_face_labels(preview_bytes: bytes, faces: list[dict], display_mode: s
        center_x = (face["boundingBoxX1"] + face["boundingBoxX2"]) / 2 * img_scale_x
        bottom_y = face["boundingBoxY2"] * img_scale_y

-        frame_x = center_x * scale_x + offset_x
-        frame_y = bottom_y * scale_y + offset_y
+        # 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

-        labels.append({"name": face["person"]["name"], "x": int(frame_x), "y": int(frame_y)})
+        labels.append({"name": face["person"]["name"],
+                       "x": int(region_x + region_x0), "y": int(region_y + region_y0)})

    return labels
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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",
+}
@@ -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)
@@ -0,0 +1,667 @@
+"""Experimental "modern" render style, offered as an opt-in alternative
+to several widget types' hand-drawn PIL primitives: Jinja2 + a
+persistent headless Chromium browser (Playwright) -- see docs/widgets.md
+for the design rationale (gradients/shadows/soft shading that PIL can't
+easily do, at the cost of a real browser-process dependency). Everything
+in this module is shared infrastructure (the persistent browser, ordered
+dithering) plus one `build_*` function per widget type that has a
+modern-style builder -- battery/text/tasks/static image/whiteboard live
+here directly (mirroring how those widget types are themselves "inlined"
+in their own widget.py rather than getting a dedicated render module);
+calendar's (all four view modes, see calendar_html_render.py) is the one
+exception, kept separate the same reason calendar_render.py itself is
+its own 800+ line file rather than joining battery/text/tasks inline.
+Not offered for the photos widget -- a real photograph isn't a
+synthesized dashboard card, and photos has its own separate palette/
+dithering concern instead (see widgets/photos.py).
+
+Two things this module owns that nothing else in the codebase needed
+before:
+
+1. A **persistent** background browser process. Widget rendering already
+   happens concurrently across a fresh `ThreadPoolExecutor` per frame
+   request (routers/device.py's _render_widgets) -- Playwright's sync
+   API is thread-affine (an object must be used from the thread that
+   created it), so a single browser object can't be handed across those
+   ad-hoc worker threads, and relaunching a full Chromium process on
+   every widget render would be real, avoidable latency. Fix: one
+   background thread runs its own persistent asyncio event loop hosting
+   one long-lived `Browser`, lazily started on first use (see start()) --
+   not eagerly at server startup, so a deployment that never enables the
+   weather widget's "modern" style never launches Chromium at all and
+   never needs Playwright's browser binaries installed. main.py's
+   lifespan only wires up the *shutdown* half (stop()), so a clean
+   server restart doesn't leave an orphaned Chromium process behind if
+   this was ever actually used. render_html_to_image() is a plain sync
+   function any worker thread can call, bridging in via
+   `asyncio.run_coroutine_threadsafe` (the standard safe cross-thread
+   entry point into a *running* loop on another thread).
+
+2. **Per-region ordered (Bayer) dithering against the palette**, done
+   here rather than in the shared image_pipeline.py pipeline.
+   render_panel's whole-canvas single Floyd-Steinberg pass exists
+   because Floyd-Steinberg's error diffusion can't be split across
+   independently-quantized regions without a visible seam at the
+   boundary -- but that reasoning doesn't apply to ordered dithering,
+   which has no cross-pixel error term (each pixel's dither decision
+   only depends on its own position + color). So this module dithers its
+   own rendered widget to *already-exact* palette colors before
+   returning it; the later shared Floyd-Steinberg pass sees zero
+   quantization error there and leaves it untouched -- the same
+   "pre-commit to exact palette colors" trick image_pipeline.draw_text
+   and the hand-drawn weather icons already rely on, just reached a
+   different way. Floyd-Steinberg keeps working exactly as before for
+   photos and every other (classic-rendered) widget region.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import threading
+from datetime import date
+from pathlib import Path
+
+import numpy as np
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+from PIL import Image
+
+from . import panel_style, theme_tokens
+from .image_pipeline import DEFAULT_PALETTE_RGB, hex_to_rgb
+
+_TEMPLATE_DIR = Path(__file__).resolve().parent / "templates" / "widget_html"
+_FONT_DIR = Path(__file__).resolve().parent / "fonts"
+
+_jinja_env = Environment(
+    loader=FileSystemLoader(str(_TEMPLATE_DIR)),
+    autoescape=select_autoescape(["html", "jinja"]),
+)
+
+CATEGORY_EMOJI = {
+    "clear": "☀️",
+    "partly_cloudy": "⛅",
+    "cloudy": "☁️",
+    "fog": "\U0001f32b️",
+    "rain": "\U0001f327️",
+    "snow": "❄️",
+    "thunderstorm": "⛈️",
+}
+
+# Spelled-out condition word for the "bold minimal" current-mode layout --
+# classic's build_current never needed one (icon + temp only), but the
+# redesigned modern layout has room for a secondary line under the temp.
+CATEGORY_LABEL = {
+    "clear": "Clear",
+    "partly_cloudy": "Partly cloudy",
+    "cloudy": "Cloudy",
+    "fog": "Fog",
+    "rain": "Rain",
+    "snow": "Snow",
+    "thunderstorm": "Thunderstorm",
+}
+
+
+def _rgb_to_hex(rgb: tuple[int, int, int]) -> str:
+    return "#%02x%02x%02x" % tuple(rgb)
+
+
+def _darken_hex(rgb: tuple[int, int, int], factor: float = 0.75) -> str:
+    """A darker shade of `rgb` for a CSS gradient's second stop -- purely
+    decorative (ordered_dither commits everything to exact palette colors
+    regardless of which literal hex a gradient starts from)."""
+    return _rgb_to_hex(tuple(max(0, round(c * factor)) for c in rgb))
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    """Keeps a size/spacing value proportional to widget dimensions
+    (`value` is always some fraction of target_w/target_h) while still
+    guaranteeing a floor (stays legible on a 1-2 grid-cell widget) and a
+    ceiling (stops padding/type from just growing forever on a
+    near-full-panel widget -- see build_current's docstring)."""
+    return max(lo, min(hi, value))
+
+
+# --- Persistent background browser -------------------------------------
+
+_loop: asyncio.AbstractEventLoop | None = None
+_loop_thread: threading.Thread | None = None
+_browser = None
+_playwright_cm = None
+_start_lock = threading.Lock()
+
+
+async def _launch_browser() -> None:
+    global _browser, _playwright_cm
+    from playwright.async_api import async_playwright
+
+    _playwright_cm = async_playwright()
+    playwright = await _playwright_cm.__aenter__()
+    _browser = await playwright.chromium.launch()
+
+
+async def _close_browser() -> None:
+    global _browser, _playwright_cm
+    if _browser is not None:
+        await _browser.close()
+        _browser = None
+    if _playwright_cm is not None:
+        await _playwright_cm.__aexit__(None, None, None)
+        _playwright_cm = None
+
+
+def start() -> None:
+    """Launches the background event loop + persistent Chromium browser,
+    if not already running. Called lazily by render_html_to_image on
+    first use (not from main.py's lifespan -- see module docstring for
+    why this must stay opt-in) -- exposed directly too, for tests that
+    want to control startup explicitly. Idempotent -- a second call
+    while already started is a no-op."""
+    global _loop, _loop_thread
+    if _loop is not None:
+        return
+    ready = threading.Event()
+
+    def _run() -> None:
+        global _loop
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        _loop = loop
+        ready.set()
+        loop.run_forever()
+
+    _loop_thread = threading.Thread(target=_run, daemon=True, name="html-render-loop")
+    _loop_thread.start()
+    ready.wait()
+    asyncio.run_coroutine_threadsafe(_launch_browser(), _loop).result()
+
+
+def stop() -> None:
+    """Closes the browser and stops the background loop -- called from
+    main.py's lifespan shutdown so a server restart never leaves an
+    orphaned Chromium process behind. No-op if start() was never called
+    (the common case: most deployments never enable "modern" style)."""
+    global _loop, _loop_thread
+    if _loop is None:
+        return
+    asyncio.run_coroutine_threadsafe(_close_browser(), _loop).result()
+    _loop.call_soon_threadsafe(_loop.stop)
+    _loop_thread.join(timeout=5)
+    _loop = None
+    _loop_thread = None
+
+
+async def _screenshot(html: str, target_w: int, target_h: int) -> bytes:
+    page = await _browser.new_page(viewport={"width": target_w, "height": target_h}, device_scale_factor=1)
+    try:
+        await page.set_content(html, wait_until="networkidle")
+        return await page.screenshot()
+    finally:
+        await page.close()
+
+
+def render_html_to_image(html: str, target_w: int, target_h: int) -> Image.Image:
+    """Renders `html` (already sized to target_w x target_h via its own
+    <style>) through the persistent headless Chromium browser and
+    returns an RGB image of exactly that size. Safe to call from any
+    thread -- bridges into the dedicated background asyncio loop via
+    run_coroutine_threadsafe. Lazily calls start() on first use (see its
+    docstring) -- the first "modern" style render on a freshly-started
+    server pays Chromium's launch latency; every render after that reuses
+    the same persistent browser."""
+    if _loop is None:
+        with _start_lock:
+            if _loop is None:
+                start()
+    future = asyncio.run_coroutine_threadsafe(_screenshot(html, target_w, target_h), _loop)
+    png_bytes = future.result()
+    return Image.open(io.BytesIO(png_bytes)).convert("RGB")
+
+
+# --- Ordered (Bayer 8x8) dithering against an arbitrary palette ---------
+
+_BAYER8 = (
+    np.array(
+        [
+            [0, 32, 8, 40, 2, 34, 10, 42],
+            [48, 16, 56, 24, 50, 18, 58, 26],
+            [12, 44, 4, 36, 14, 46, 6, 38],
+            [60, 28, 52, 20, 62, 30, 54, 22],
+            [3, 35, 11, 43, 1, 33, 9, 41],
+            [51, 19, 59, 27, 49, 17, 57, 25],
+            [15, 47, 7, 39, 13, 45, 5, 37],
+            [63, 31, 55, 23, 61, 29, 53, 21],
+        ],
+        dtype=np.float32,
+    )
+    / 64.0
+    - 0.5
+)
+
+
+def ordered_dither(img: Image.Image, palette_rgb: list | None, amplitude: float = 48.0) -> Image.Image:
+    """Bayer-ordered dither of `img` against `palette_rgb` (falls back to
+    DEFAULT_PALETTE_RGB) -- every output pixel is one of the palette's
+    exact colors, spatially patterned rather than error-diffused, so it's
+    safe to run per-region before compositing (see module docstring for
+    why that's not true of Floyd-Steinberg). `amplitude` is the Bayer
+    bias's full swing in 0-255 RGB units before nearest-palette-color
+    matching -- 48 was the value this render style was tuned against in
+    the exploratory spike behind this feature; not exposed as a per-frame
+    setting (unlike dither_strength) since there's only one consumer of
+    it today."""
+    palette = np.array(palette_rgb or DEFAULT_PALETTE_RGB, dtype=np.float32)
+    arr = np.asarray(img.convert("RGB"), dtype=np.float32)
+    h, w, _ = arr.shape
+    tile = np.tile(_BAYER8, (h // 8 + 1, w // 8 + 1))[:h, :w]
+    biased = np.clip(arr + tile[:, :, None] * amplitude, 0, 255)
+    diffs = biased[:, :, None, :] - palette[None, None, :, :]
+    dists = np.einsum("hwkc,hwkc->hwk", diffs, diffs)
+    idx = np.argmin(dists, axis=2)
+    return Image.fromarray(palette[idx].astype(np.uint8), "RGB")
+
+
+def ordered_dither_regions(rendered: Image.Image, palette_rgb: list | None, base_amplitude: float = 48.0,
+                           accent_regions: list[tuple[tuple[int, int, int, int], float]] = ()) -> Image.Image:
+    """Like `ordered_dither`, but lets specific rectangles (e.g. a themed
+    header bar) dither at a higher amplitude than the rest of the widget.
+    A single higher amplitude applied to a whole widget washes out pale
+    content (a weather icon's white cloud body nearly disappeared in
+    testing); dithering the base image at the safe default and only
+    re-dithering an accent rect on top -- pasted back over the base --
+    lets a header carry a rich, arbitrary accent hue (via denser
+    stippling) without touching icon/text legibility elsewhere. Safe to
+    do per-region for the same reason `ordered_dither` is safe per-widget
+    (see its docstring): no cross-pixel error-diffusion term, so each
+    region's result depends only on its own pixels."""
+    base = ordered_dither(rendered, palette_rgb, amplitude=base_amplitude)
+    for (x0, y0, x1, y1), amplitude in accent_regions:
+        crop = rendered.crop((x0, y0, x1, y1))
+        base.paste(ordered_dither(crop, palette_rgb, amplitude=amplitude), (x0, y0))
+    return base
+
+
+# --- Weather "modern" style ----------------------------------------------
+
+def _day_label(day_date: date) -> str:
+    delta = (day_date - date.today()).days
+    if delta == 0:
+        return "Today"
+    if delta == 1:
+        return "Tomorrow"
+    return day_date.strftime("%a")
+
+
+def _short_city(city_label: str) -> str:
+    """geocode_city (see docs/widgets.md's Weather widget section) hands
+    back a full "City, Region, Country" string -- fine for classic's
+    build_current (just drawn as one line, however wide) but wrong for
+    the bold-minimal layout's small top-row label, where a 1-2 grid-
+    cell widget has no room for the whole thing. Every phone-homescreen
+    weather widget this style is drawing from shows just the city, so
+    that's what this keeps -- CSS `text-overflow: ellipsis` is still in
+    the template as a safety net for a custom single-segment label
+    that's itself too long, not as the primary truncation strategy."""
+    return city_label.split(",")[0].strip()
+
+
+def build_current(entry: dict | None, target_w: int, target_h: int, palette_rgb: list | None = None,
+                  units: str = "fahrenheit", city_label: str = "", theme_name: str | None = None) -> Image.Image:
+    """HTML/CSS-rendered analogue of weather_render.build_current --
+    same call signature, so app/widgets/weather.py can dispatch to
+    either interchangeably. Returns an already-palette-exact RGB image
+    (see ordered_dither).
+
+    "Bold minimal" layout: the temperature itself is the graphic --
+    city label + icon in a top row, the temp (dominant) and spelled-out
+    condition anchored to the bottom, no card/border/shadow at all. This
+    is a deliberate departure from every other modern-style widget's
+    card-on-white-canvas chrome (see docs/widgets.md) -- there's nothing
+    for a "card" to visually separate from here, so `theme["radius"]`/
+    `theme["shadow"]` have no effect on this template; still theme-aware
+    for font_family only, same as before. No header/accent region either
+    (see ordered_dither_regions' docstring) -- a themed accent has
+    nothing to attach to in a chrome-free layout.
+
+    Every size below is a fraction of `base` (the widget's shorter side),
+    clamped to a floor/ceiling rather than fixed -- so a 1-grid-cell
+    widget doesn't get comically oversized padding relative to its
+    content, and a near-full-panel widget doesn't get comically large
+    padding relative to *its* content either. Floors/ceilings are tuned
+    by eye against real widget sizes, not derived from anything."""
+    img = Image.new("RGB", (target_w, target_h), (255, 255, 255))
+    if not entry:
+        return img
+
+    theme = theme_tokens.resolve_theme(theme_name, "weather", palette_rgb)
+    unit_suffix = "F" if units == "fahrenheit" else "C"
+    base = min(target_w, target_h)
+    pad = _clamp(base * 0.09, 10, 26)
+    icon_size = _clamp(base * 0.20, 22, 60)
+    temp_size = _clamp(base * 0.46, 30, 150)
+    deg_size = _clamp(temp_size * 0.28, 12, 40)
+    cond_size = _clamp(base * 0.075, 11, 20)
+    city_size = _clamp(base * 0.06, 10, 15)
+    template = _jinja_env.get_template("weather_current.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, pad=round(pad),
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+        emoji=CATEGORY_EMOJI.get(entry["category"], ""),
+        condition=CATEGORY_LABEL.get(entry["category"], ""),
+        temp=round(entry["temp"]), unit_suffix=unit_suffix, city_label=_short_city(city_label),
+        icon_size=round(icon_size), temp_size=round(temp_size), deg_size=round(deg_size),
+        cond_size=round(cond_size), city_size=round(city_size),
+    )
+    rendered = render_html_to_image(html, target_w, target_h)
+    return ordered_dither(rendered, palette_rgb)
+
+
+def build_daily(daily: dict[str, dict], target_w: int, target_h: int, palette_rgb: list | None = None,
+               units: str = "fahrenheit", city_label: str = "", theme_name: str | None = None) -> Image.Image:
+    """HTML/CSS-rendered analogue of weather_render.build_daily -- same
+    call signature. Returns an already-palette-exact RGB image (see
+    ordered_dither).
+
+    "Bold minimal" layout, matching build_current: no card/border/
+    shadow, a row of day columns each carrying its own high (dominant)
+    / low (muted) temp the same way build_current makes the current
+    temp dominant. The old full-width gradient banner is gone --
+    city_label, when set, is a slim accent-colored rule (not a block)
+    with the city name understated beneath it, so there's still
+    somewhere for a theme's accent hue to show up (dithered richer via
+    ordered_dither_regions, same mechanism as before) without dragging
+    back the "card with a colored header" chrome this redesign is
+    moving away from. `theme["radius"]`/`theme["shadow"]` are unused
+    here for the same reason as build_current -- no card for them to
+    apply to."""
+    img = Image.new("RGB", (target_w, target_h), (255, 255, 255))
+    days = list(daily.items())
+    if not days:
+        return img
+
+    theme = theme_tokens.resolve_theme(theme_name, "weather", palette_rgb)
+    unit_suffix = "F" if units == "fahrenheit" else "C"
+    base = min(target_w, target_h)
+    pad = round(_clamp(base * 0.08, 10, 22))
+    col_w = max(1, (target_w - pad * 2) // len(days))
+    col_gap = round(_clamp(col_w * 0.12, 4, 16))
+    icon_size = round(_clamp(col_w * 0.30, 16, 32))
+    day_label_size = round(_clamp(col_w * 0.15, 10, 14))
+    high_size = round(_clamp(col_w * 0.32, 16, 32))
+    low_size = round(max(9, high_size * 0.55))
+    city_size = round(_clamp(base * 0.055, 10, 14))
+    accent_h = round(_clamp(base * 0.025, 4, 8))
+    day_entries = [
+        {
+            "label": _day_label(date.fromisoformat(day_str)),
+            "emoji": CATEGORY_EMOJI.get(d["category"], ""),
+            "high": round(d["high"]),
+            "low": round(d["low"]),
+        }
+        for day_str, d in days
+    ]
+    template = _jinja_env.get_template("weather_daily.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, pad=pad, col_gap=col_gap,
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+        city_label=_short_city(city_label), city_size=city_size, accent_h=accent_h,
+        accent_start=theme["accent_hex"], accent_end=theme["accent_hex_dark"],
+        days=day_entries, icon_size=icon_size, day_label_size=day_label_size,
+        high_size=high_size, low_size=low_size, unit_suffix=unit_suffix,
+    )
+    rendered = render_html_to_image(html, target_w, target_h)
+    if not city_label:
+        return ordered_dither(rendered, palette_rgb)
+    accent_rect = (pad, pad, target_w - pad, pad + accent_h)
+    return ordered_dither_regions(rendered, palette_rgb, accent_regions=[(accent_rect, theme["accent_amplitude"])])
+
+
+SUPPORTED_MODES = ("current", "daily")
+
+
+def build(mode: str, data, target_w: int, target_h: int, palette_rgb: list | None = None,
+         units: str = "fahrenheit", city_label: str = "", theme_name: str | None = None) -> Image.Image:
+    """Dispatches to build_current/build_daily -- mirrors weather_render.
+    build()'s signature (minus interval_hours, which no modern-style mode
+    uses) so app/widgets/weather.py and the weather preview endpoint can
+    call either module identically. Only call this for mode in
+    SUPPORTED_MODES -- callers are expected to have already fallen back to
+    weather_render.build() for hourly/multi_city (see weather.py)."""
+    if mode == "current":
+        return build_current(data, target_w, target_h, palette_rgb, units, city_label, theme_name)
+    return build_daily(data, target_w, target_h, palette_rgb, units, city_label, theme_name)
+
+
+def render_weather_preview_png(mode: str, data, orientation: str, palette_rgb: list | None,
+                               units: str = "fahrenheit", city_label: str = "",
+                               theme_name: str | None = None, panel_w: int | None = None,
+                               panel_h: int | None = None) -> bytes:
+    """Modern-style analogue of weather_render.render_weather_preview_png
+    -- same browser-viewable-PNG convention every other widget's preview
+    endpoint uses. build()'s output is already palette-exact (see
+    ordered_dither), so the final _quantize pass here is a no-op on it,
+    same reasoning as the module docstring's compositing story."""
+    from .image_pipeline import EPD_HEIGHT, EPD_WIDTH, _quantize, _png_bytes, logical_render_size
+
+    target_w, target_h = logical_render_size(orientation, panel_w or EPD_WIDTH, panel_h or EPD_HEIGHT)
+    img = build(mode, data, target_w, target_h, palette_rgb, units, city_label, theme_name)
+    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
+    return _png_bytes(quantized)
+
+
+# --- Battery "modern" style ------------------------------------------------
+
+def _battery_sizes(target_w: int, target_h: int, num_lines: int, scale: float) -> dict:
+    base = min(target_w, target_h)
+    icon_h = max(14, int(base * 0.15 * scale))
+    pct_size = max(20, int(base * 0.42 * scale))
+    line_size = max(9, int(base * 0.085 * scale))
+    gap = max(4, int(base * 0.035 * scale))
+    total = icon_h + gap + pct_size + num_lines * (line_size + gap)
+    return {"icon_h": icon_h, "pct_size": pct_size, "line_size": line_size, "gap": gap, "total": total}
+
+
+def build_battery(percent: int, lines: list[str], target_w: int, target_h: int,
+                  palette_rgb: list | None = None, theme_name: str | None = None) -> Image.Image:
+    """HTML/CSS-rendered analogue of widgets/battery.py's classic PIL
+    drawing -- same icon+percent+caption-lines shape, `lines` already
+    resolved by the caller (widgets/battery.py's _lines_for(), shared
+    with the classic path so the estimate/age formatting only lives in
+    one place). Returns an already-palette-exact RGB image (see
+    ordered_dither). Theme-aware for font only -- the charge-level
+    fill_color below is a functional status signal (not a style choice)
+    and is never touched by a theme, and there's no header/accent region
+    to dither richer via ordered_dither_regions.
+
+    Bold-minimal: no card (theme["radius"] unused, same carve-out as
+    weather's build_current -- see docs/widgets.md); the percent is the
+    hero value anchored toward the bottom, same treatment build_current
+    gives the temperature, with the icon small and secondary above it
+    instead of both competing at the same size like the old centered
+    layout did.
+
+    Shrinks icon/text sizes together (in 0.05 steps down to 0.3x) until
+    the whole stack actually fits the available height -- the classic
+    PIL path solves the same "icon + percent + 0-2 lines in a fixed box"
+    problem by truncating lines that don't fit; scaling down instead
+    keeps every resolved line visible, which reads better for a widget
+    that only ever has at most 2 short caption lines to begin with."""
+    pad = round(_clamp(min(target_w, target_h) * 0.09, 10, 26))
+    avail_h = target_h - pad * 2
+    num_lines = len(lines)
+    scale = 1.0
+    sizes = _battery_sizes(target_w, target_h, num_lines, scale)
+    while sizes["total"] > avail_h and scale > 0.3:
+        scale -= 0.05
+        sizes = _battery_sizes(target_w, target_h, num_lines, scale)
+    # Extreme case (a 1x1-grid-cell-sized widget in "detailed" mode):
+    # scale bottomed out and it still doesn't fit -- drop the least
+    # important line rather than render overlapping text, same
+    # graceful-degradation idiom the classic PIL path's own
+    # `if y + small_font_size > ...: break` truncation already uses.
+    while sizes["total"] > avail_h and lines:
+        lines = lines[:-1]
+        num_lines = len(lines)
+        sizes = _battery_sizes(target_w, target_h, num_lines, scale)
+
+    theme = theme_tokens.resolve_theme(theme_name, "battery", palette_rgb)
+    fill_color = panel_style.battery_fill_color(percent, palette_rgb)
+    icon_h = sizes["icon_h"]
+    icon_w = int(icon_h * 1.8)
+    stroke = max(2, icon_h // 12)
+    nub_w = max(3, icon_w // 10)
+    template = _jinja_env.get_template("battery.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, pad=pad,
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"], percent=percent, lines=lines,
+        icon_w=icon_w, icon_h=icon_h, icon_radius=icon_h // 6, stroke=stroke,
+        fill_pct=max(0, min(100, percent)), fill_radius=max(0, icon_h // 6 - stroke),
+        fill_color=_rgb_to_hex(fill_color), fill_color_dark=_darken_hex(fill_color),
+        nub_w=nub_w, nub_h=icon_h // 2, nub_radius=max(1, nub_w // 3),
+        pct_size=sizes["pct_size"], line_size=sizes["line_size"], line_gap=sizes["gap"],
+    )
+    rendered = render_html_to_image(html, target_w, target_h)
+    return ordered_dither(rendered, palette_rgb)
+
+
+# --- Text "modern" style ---------------------------------------------------
+
+def build_text(cfg, target_w: int, target_h: int, palette_rgb: list | None = None,
+              theme_name: str | None = None) -> Image.Image:
+    """HTML/CSS-rendered analogue of widgets/text.py's classic PIL
+    drawing. Reuses widgets/text.py's own `_fit()` for the one piece of
+    logic CSS has no native equivalent for (shrink-to-fit sizing) --
+    `_fit` measures against the exact same vendored font files via PIL,
+    so the resolved size is a real fit decision, not a guess -- but lets
+    the browser do its own text wrapping/line-breaking at that size
+    (paragraphs/runs passed through directly as HTML) rather than
+    replicating `_fit`'s own word-wrapped line list; the two wrapping
+    algorithms can disagree on exact break points, an acceptable
+    approximation since this style only needs to look good and fit
+    reasonably, not be pixel-identical to classic. Returns an already-
+    palette-exact RGB image (see ordered_dither).
+
+    theme_name is accepted (every modern-style build_* function takes
+    one, threaded uniformly from frame.theme) but deliberately unused --
+    the text widget's own font_family is a per-widget, user-authored
+    choice (see widgets/text.py's module docstring), same carve-out
+    reasoning as run-level colors; a frame theme overriding it would
+    silently undo an explicit user choice. text.html.jinja also has no
+    card chrome (no radius/shadow) for a theme to touch."""
+    from PIL import ImageDraw
+
+    from . import widgets  # local import: heavy-ish, and only "modern" text needs it
+
+    text_widget = widgets.text
+    bg_rgb = (hex_to_rgb(cfg.background_color) if cfg.background_color else None) or (255, 255, 255)
+    family = cfg.font_family if cfg.font_family in text_widget.FONT_FAMILIES else text_widget.DEFAULT_FONT_FAMILY
+    paragraphs = cfg.content or []
+    margin = text_widget.MARGIN
+    max_width = max(10, target_w - 2 * margin)
+    max_height = max(10, target_h - 2 * margin)
+
+    measure_img = Image.new("RGB", (1, 1))
+    draw = ImageDraw.Draw(measure_img)
+    size, _lines = text_widget._fit(draw, paragraphs, family, cfg.font_size, max_width, max_height)
+
+    files = text_widget._FONT_FILES.get(family) or text_widget._FONT_FILES[text_widget.DEFAULT_FONT_FAMILY]
+    align = cfg.align if cfg.align in ("left", "center", "right") else "left"
+    template = _jinja_env.get_template("text.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, margin=margin, bg_color=_rgb_to_hex(bg_rgb),
+        size=size, line_height=text_widget.LINE_HEIGHT_FACTOR, align=align,
+        font_regular=str(_FONT_DIR / files[(False, False)]), font_bold=str(_FONT_DIR / files[(True, False)]),
+        font_italic=str(_FONT_DIR / files[(False, True)]), font_bold_italic=str(_FONT_DIR / files[(True, True)]),
+        paragraphs=paragraphs,
+    )
+    rendered = render_html_to_image(html, target_w, target_h)
+    return ordered_dither(rendered, palette_rgb)
+
+
+# --- Tasks "modern" style ---------------------------------------------------
+
+def build_tasks(tasks: list[dict], target_w: int, target_h: int, palette_rgb: list | None = None,
+                title: str = "Tasks", theme_name: str | None = None, font_scale: float = 1.0) -> Image.Image:
+    """HTML/CSS-rendered analogue of calendar_render._build_tasks --
+    same header+checklist shape. Reuses calendar_render's own
+    _event_colors/_fmt_task_due (the exact color-dedup/due-date-format
+    logic the classic renderer uses) so a task's color chip/due string
+    matches classic style exactly; only the drawing differs -- and a
+    theme's accent never touches those per-owner chip colors (identity-
+    coding, not style) or the done-checkbox fill (a completion state
+    signal, not a style choice -- it happens to reuse the accent color,
+    but that's incidental, same as before this redesign).
+
+    Bold-minimal: no card (theme["shadow"]/["radius"] unused, same
+    carve-out as calendar's redesigned views -- see docs/widgets.md).
+    The old gradient header banner is now a slim accent rule + plain
+    bold title, matching every calendar view's day-header language --
+    only the rule dithers at the theme's richer accent_amplitude, not
+    the title text sitting on it. Returns an already-palette-exact RGB
+    image (see ordered_dither)."""
+    from .calendar_render import _event_colors, _fmt_task_due
+
+    theme = theme_tokens.resolve_theme(theme_name, "tasks", palette_rgb)
+    base = min(target_w, target_h)
+    accent_h = round(_clamp(base * 0.025, 3, 6))
+    title_size = panel_style.scaled_size(max(14, base // 12), font_scale)
+    body_size = panel_style.scaled_size(max(11, base // 20), font_scale)
+    row_h = body_size + 14
+    box_size = max(10, body_size - 4)
+    header_h = accent_h + 6 + title_size
+    avail_h = target_h - panel_style.GUTTER * 2 - header_h - 8
+    max_rows = max(0, avail_h // row_h)
+
+    owners_seen: list[str] = []
+    rows = []
+    for task in tasks[:max_rows]:
+        colors = _event_colors(task, owners_seen, palette_rgb)
+        done = task.get("completed_at") is not None
+        due = None if done else (_fmt_task_due(task.get("due")) or None)
+        rows.append({
+            "colors": [_rgb_to_hex(c) for c in colors],
+            "done": done,
+            "due": due,
+            "summary": task["summary"],
+        })
+    more_count = max(0, len(tasks) - max_rows)
+
+    template = _jinja_env.get_template("tasks.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, gutter=panel_style.GUTTER,
+        font_regular=theme["font_regular"], font_bold=theme["font_bold"],
+        title=title, header_h=header_h, accent_h=accent_h, title_size=title_size,
+        accent_start=theme["accent_hex"],
+        rows=rows, more_count=more_count, row_h=row_h, box_size=box_size, body_size=body_size,
+    )
+    rendered = render_html_to_image(html, target_w, target_h)
+    gutter = panel_style.GUTTER
+    accent_rect = (gutter, gutter, target_w - gutter, gutter + accent_h)
+    return ordered_dither_regions(rendered, palette_rgb, accent_regions=[(accent_rect, theme["accent_amplitude"])])
+
+
+# --- Static image / whiteboard "modern" style (shared) ---------------------
+
+def build_framed_image(composed: Image.Image, target_w: int, target_h: int,
+                       palette_rgb: list | None = None, theme_name: str | None = None,
+                       widget_kind: str = "static") -> Image.Image:
+    """Wraps an already-composed image (static_image.py/whiteboard.py's
+    own compose_into() output, exactly target_w x target_h, already
+    cropped/fit per that widget's own display_mode) in a rounded-corner,
+    shadowed card -- the first visual chrome either widget type has ever
+    had (both currently draw with zero chrome of their own). Theme-aware
+    for radius/shadow only -- no text/header content to accent or font.
+    Returns an already-palette-exact RGB image (see ordered_dither)."""
+    import base64
+
+    theme = theme_tokens.resolve_theme(theme_name, widget_kind, palette_rgb)
+    buf = io.BytesIO()
+    composed.convert("RGB").save(buf, format="PNG")
+    image_b64 = base64.b64encode(buf.getvalue()).decode("ascii")
+
+    template = _jinja_env.get_template("framed_image.html.jinja")
+    html = template.render(
+        w=target_w, h=target_h, gutter=panel_style.GUTTER, radius=theme["radius"], shadow=theme["shadow"],
+        image_b64=image_b64,
+    )
+    rendered = render_html_to_image(html, target_w, target_h)
+    return ordered_dither(rendered, palette_rgb)
@@ -3,12 +3,200 @@
 from __future__ import annotations

 import io
+import math

-from PIL import Image, ImageEnhance, ImageOps
+from PIL import Image, ImageDraw, ImageEnhance, ImageFont, ImageOps

 EPD_WIDTH = 800
 EPD_HEIGHT = 480

+# Registry of every supported panel's native pixel size, keyed by
+# Frame.panel_type. New entries get added here as a new EPD driver
+# component is supported firmware-side (see firmware/components/) --
+# geometry lives in exactly one place rather than as new module-level
+# globals per panel.
+DEFAULT_PANEL_TYPE = "epd7in3e"
+PANEL_SPECS: dict[str, tuple[int, int]] = {
+    "epd7in3e": (EPD_WIDTH, EPD_HEIGHT),
+    # Waveshare's 13.3" e-Paper (E) Spectra 6 panel (270.40x202.80mm,
+    # 1600x1200px, 4:3) driven by Seeed's EE02 board. This is the panel's
+    # MOUNT/marketing size, not its SPI wire raster -- the controller
+    # itself addresses a native 1200x1600 (portrait) raster, rotated 90
+    # degrees from how the panel physically hangs. Both facts are now
+    # vendor-confirmed (see firmware/components/epd13in3e's own docstring)
+    # -- PANEL_SPECS stays in mount/logical terms like the 7.3" panel's
+    # entry (everything upstream of packing -- composition, the widget
+    # grid, face-label placement -- reasons in this space); the wire-raster
+    # rotation is applied only at pack time, see PANEL_WIRE_TRANSPOSE.
+    "epd13in3e": (1600, 1200),
+}
+
+# Panels whose SPI wire raster is rotated 90 degrees from PANEL_SPECS's
+# mount/logical size (see that dict's own comment on epd13in3e). None =
+# wire raster already matches the logical size, no extra rotation (true
+# for the 7.3" panel). Applied in _transpose_and_pack AFTER the
+# user-selected ORIENTATION_TRANSPOSE -- these are two independent
+# rotations for two independent reasons (how the frame is hung vs. a fixed
+# fact about this panel's controller wiring) and must not be conflated.
+#
+# Getting this wrong doesn't just rotate the output image: 1600x1200 and
+# 1200x1600 don't share a row stride (800 bytes/row x 1200 rows vs 600
+# bytes/row x 1600 rows), so packing at the wrong one slices real image
+# rows at the wrong byte offsets and shreds the picture into a repeating
+# diagonal garble on the real panel, not a clean rotation -- see
+# test_transpose_and_pack_epd13in3e_uses_true_wire_raster_stride in
+# tests/test_render_size_invariants.py, which catches exactly that
+# regression without needing real hardware.
+#
+# Direction (ROTATE_90 vs ROTATE_270) is a physical-assembly fact this
+# code can't derive from vendor driver bytes -- it depends on which edge
+# of the panel ends up "up" in this project's frame housing. Picked
+# ROTATE_90 as a documented placeholder; confirm/flip against real
+# hardware once the EE02 firmware target is actually flashed and
+# displaying (a wrong direction shows a rotated/mirrored image, not
+# corruption, so it's safe to ship pending that check).
+PANEL_WIRE_TRANSPOSE: dict[str, "Image.Transpose | None"] = {
+    "epd7in3e": None,
+    "epd13in3e": Image.Transpose.ROTATE_90,
+}
+
+# Human-readable label per PANEL_SPECS key, for the frame settings page's
+# read-only "Panel" line (see routers/device.py's BOARD_PANEL_MAP for how
+# a frame's panel_type actually gets set -- this is display-only).
+PANEL_LABELS: dict[str, str] = {
+    "epd7in3e": '7.3" Spectra 6',
+    "epd13in3e": '13.3" Spectra 6',
+}
+
+
+def panel_size(panel_type: str) -> tuple[int, int]:
+    """(width, height) native pixel size for a Frame.panel_type key.
+    Unknown/blank panel_type (e.g. a frame created before this field
+    existed) falls back to the original 7.3" panel this project shipped
+    with, never raises."""
+    return PANEL_SPECS.get(panel_type, PANEL_SPECS[DEFAULT_PANEL_TYPE])
+
+# 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],
+                       radius: int = 0) -> 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. `radius` is opt-in and only
+    honored by "solid"/"fancy" (rounded_rectangle instead of rectangle) --
+    "dashed"/"dotted" trace each of the 4 edges as independent straight
+    segments (see _dashed_edge/_dotted_edge) and ignore it, a documented
+    limitation rather than a bug. Defaults to 0 (unchanged sharp-corner
+    behavior) and no call site passes non-zero today -- this ships the
+    capability for a future per-widget "rounded border" setting without
+    changing default behavior anywhere (see tests/test_widget_border.py's
+    exact-corner-pixel assertions)."""
+    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)
+    r = max(0, min(radius, (w - 1) // 2, (h - 1) // 2))
+
+    if style == "fancy":
+        line_t = max(1, t // 3)
+        gap = max(2, t - 2 * line_t)
+        if r:
+            draw.rounded_rectangle([0, 0, w - 1, h - 1], radius=r, outline=color, width=line_t)
+        else:
+            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:
+            inner_r = max(0, min(r - inset, (w - 1 - 2 * inset) // 2, (h - 1 - 2 * inset) // 2)) if r else 0
+            if inner_r:
+                draw.rounded_rectangle([inset, inset, w - 1 - inset, h - 1 - inset], radius=inner_r,
+                                       outline=color, width=line_t)
+            else:
+                draw.rectangle([inset, inset, w - 1 - inset, h - 1 - inset], outline=color, width=line_t)
+        return
+
+    if style == "solid":
+        if r:
+            draw.rounded_rectangle([0, 0, w - 1, h - 1], radius=r, outline=color, width=t)
+        else:
+            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
@@ -24,21 +212,24 @@ ORIENTATION_TRANSPOSE = {
 }


-def logical_render_size(orientation: str) -> tuple[int, int]:
+def logical_render_size(orientation: str, panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> tuple[int, int]:
    """(width, height) the photo is composed/cropped at for this
-    orientation, before rotating into native panel space."""
+    orientation, before rotating into native panel space. Defaults to the
+    7.3" panel's native size; callers with a Frame in scope should pass
+    *panel_size(frame.panel_type) instead."""
    if orientation in ("portrait", "portrait_flipped"):
-        return EPD_HEIGHT, EPD_WIDTH
-    return EPD_WIDTH, EPD_HEIGHT
+        return panel_h, panel_w
+    return panel_w, panel_h


-def logical_to_native(x: float, y: float, orientation: str) -> tuple[int, int]:
+def logical_to_native(x: float, y: float, orientation: str,
+                      panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> tuple[int, int]:
    """Maps a point in logical (pre-rotation) frame space to native
-    800x480 panel space, applying the same rotation ORIENTATION_TRANSPOSE
-    applies to the pixels -- anything positioned in logical coordinates
-    (e.g. face labels) needs this to stay attached to the rotated
-    content. PIL's ROTATE_90 is counterclockwise; ROTATE_270 clockwise."""
-    logical_w, logical_h = logical_render_size(orientation)
+    panel space, applying the same rotation ORIENTATION_TRANSPOSE applies
+    to the pixels -- anything positioned in logical coordinates (e.g.
+    face labels) needs this to stay attached to the rotated content.
+    PIL's ROTATE_90 is counterclockwise; ROTATE_270 clockwise."""
+    logical_w, logical_h = logical_render_size(orientation, panel_w, panel_h)
    if orientation == "landscape_flipped":
        return int(logical_w - 1 - x), int(logical_h - 1 - y)
    if orientation == "portrait":  # ROTATE_90 (CCW)
@@ -65,12 +256,52 @@ DEFAULT_PALETTE_RGB = [

 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 DEFAULT_PALETTE_RGB/PALETTE_LABELS -- fixed by the
-# hardware protocol, never user-configurable. 0x4 is intentionally unused
-# upstream.
+# A community-measured alternative starting point for the same 6 slots,
+# ported (data only, not code) from paperlesspaper/epdoptimize's
+# src/dither/data/default-palettes.json "spectra6" entry (Apache
+# License 2.0, https://github.com/paperlesspaper/epdoptimize) -- offered
+# as a one-click "Load calibrated preset" in the Advanced configuration
+# UI, not a new default: unlike DEFAULT_PALETTE_RGB above, these are an
+# actual panel's measured appearance rather than idealized primaries
+# (real Spectra 6 white/black are notably duller than pure #fff/#000),
+# but measured from a different unit than any given frame's actual
+# panel -- panel_style.py's own docstring already notes units vary
+# enough to be worth calibrating per frame, and this hasn't been
+# verified against this project's own hardware.
+CALIBRATED_SPECTRA6_RGB = [
+    (0x1F, 0x22, 0x26),  # BLACK
+    (0xB9, 0xC7, 0xC9),  # WHITE
+    (0xC1, 0xBB, 0x1E),  # YELLOW
+    (0x62, 0x20, 0x1E),  # RED
+    (0x23, 0x3F, 0x8E),  # BLUE
+    (0x35, 0x56, 0x3A),  # GREEN
+]
+
+# The 7.3" panel's actual 4-bit color codes (see
+# firmware/components/epd7in3e), in the same order as DEFAULT_PALETTE_RGB/
+# PALETTE_LABELS -- fixed by the hardware protocol, never user-
+# configurable. 0x4 is intentionally unused upstream. Used unconditionally
+# for every panel_type today -- confirmed (not just assumed) that the
+# 13.3" panel's controller uses the identical codes, from the same vendor
+# driver sources as PANEL_SPECS["epd13in3e"]'s own comment, so no
+# panel-specific table is needed here.
 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 palette_to_hex(palette_rgb: list) -> list[str]:
    """[(0,0,0), ...] -> ["#000000", ...], for pre-filling the Advanced
@@ -78,6 +309,21 @@ def palette_to_hex(palette_rgb: list) -> list[str]:
    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
@@ -197,6 +443,13 @@ DISPLAY_MODE_LABELS = {
 DEFAULT_DISPLAY_MODE = "crop_faces"
 LETTERBOX_BG = (255, 255, 255)

+# 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"
+

 def _placement_transform(
    img_width: int, img_height: int, target_w: int, target_h: int,
@@ -248,11 +501,13 @@ def compose_into(source: Image.Image, faces: list[dict] | None, target_w: int, t
    return ImageOps.fit(fitted, (target_w, target_h), method=Image.LANCZOS)  # crop_fill, or crop_faces w/ no faces


-def _compose(source: Image.Image, faces: list[dict] | None, orientation: str, display_mode: str) -> Image.Image:
+def _compose(source: Image.Image, faces: list[dict] | None, orientation: str, display_mode: str,
+            panel_w: int = EPD_WIDTH, panel_h: int = EPD_HEIGHT) -> 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)
+    image at logical_render_size(orientation, panel_w, panel_h), before
+    enhancement or quantization. See render_frame for what each
+    display_mode does."""
+    return compose_into(source, faces, *logical_render_size(orientation, panel_w, panel_h), display_mode)


 def _enhance(img: Image.Image, color_boost: float, contrast_boost: float) -> Image.Image:
@@ -282,19 +537,34 @@ def _quantize(img: Image.Image, palette_rgb: list | None, dither_strength: float
    return blended.quantize(palette=palette_image, dither=Image.Dither.FLOYDSTEINBERG)


-def _transpose_and_pack(quantized: Image.Image, orientation: str) -> bytes:
+def _transpose_and_pack(quantized: Image.Image, orientation: str,
+                        panel_type: str = DEFAULT_PANEL_TYPE) -> 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."""
+    and packs it 2 pixels/byte the way the panel's EPD driver expects
+    (see firmware/components/epd7in3e). Returns exactly width*height/2
+    bytes for whatever native size `quantized` actually is post-rotation
+    -- the canvas was already built at the calling frame's own panel size
+    (see panel_size()), so this derives dimensions from the image itself
+    rather than a fixed global.
+
+    Two independent rotations happen here, in order: ORIENTATION_TRANSPOSE
+    (how the frame is physically hung -- a per-frame user choice), then
+    PANEL_WIRE_TRANSPOSE (a fixed fact about this panel_type's SPI wire
+    raster vs. its mount size -- see that dict's own comment). Most panels
+    need only the first; epd13in3e needs both."""
    transpose = ORIENTATION_TRANSPOSE.get(orientation)
    if transpose is not None:
        quantized = quantized.transpose(transpose)
+    wire_transpose = PANEL_WIRE_TRANSPOSE.get(panel_type)
+    if wire_transpose is not None:
+        quantized = quantized.transpose(wire_transpose)
    pixels = quantized.load()
+    w, h = quantized.size

-    out = bytearray(EPD_WIDTH * EPD_HEIGHT // 2)
+    out = bytearray(w * h // 2)
    i = 0
-    for y in range(EPD_HEIGHT):
-        for x in range(0, EPD_WIDTH, 2):
+    for y in range(h):
+        for x in range(0, w, 2):
            left = PANEL_CODES[pixels[x, y]]
            right = PANEL_CODES[pixels[x + 1, y]]
            out[i] = (left << 4) | right
@@ -321,11 +591,11 @@ 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:
+                 manage: dict | None = None, panel_type: str = DEFAULT_PANEL_TYPE) -> 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.
+    pixels/byte the way the target panel_type's EPD driver expects.
+    Returns exactly width*height/2 bytes for that panel (see panel_size).

    `display_mode` (see DISPLAY_MODES) picks how the photo's aspect ratio
    is reconciled with the panel's: crop_fill (center-crop to fill,
@@ -351,34 +621,114 @@ def render_frame(source: Image.Image, faces: list[dict] | None = None,
    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.
+
+    `panel_type` (see Frame.panel_type/panel_size) picks which panel's
+    native resolution to render for -- None/unrecognized falls back to
+    the original 7.3" panel.
    """
-    fitted = _enhance(_compose(source, faces, orientation, display_mode), color_boost, contrast_boost)
+    panel_w, panel_h = panel_size(panel_type)
+    fitted = _enhance(_compose(source, faces, orientation, display_mode, panel_w, panel_h),
+                      color_boost, contrast_boost)
    fitted = _apply_manage_overlay(fitted, manage)
    quantized = _quantize(fitted, palette_rgb, dither_strength)
-    return _transpose_and_pack(quantized, orientation)
+    return _transpose_and_pack(quantized, orientation, panel_type)
+
+
+def _png_bytes(img: Image.Image) -> bytes:
+    buf = io.BytesIO()
+    img.convert("RGB").save(buf, format="PNG")
+    return buf.getvalue()
+
+
+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,
+                 capture_snapshot: bool = False,
+                 panel_type: str = DEFAULT_PANEL_TYPE) -> bytes | tuple[bytes, 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.
+
+    capture_snapshot=True (only meaningful alongside as_png=False) returns
+    (packed_bytes, png_bytes) instead of just packed_bytes -- both derived
+    from the same already-quantized canvas, so a device-facing render can
+    also persist a browser-viewable copy (see routers/device.py's
+    _record_last_displayed) without re-running composition/quantization a
+    second time.
+
+    `panel_type` (see Frame.panel_type/panel_size) picks the target
+    panel's native resolution -- callers must have computed `regions`'
+    rects against this same panel's logical_render_size (see
+    routers/device.py's _render_widgets, which always derives both from
+    the same frame.panel_type)."""
+    logical_w, logical_h = logical_render_size(orientation, *panel_size(panel_type))
+    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:
+        return _png_bytes(quantized)
+    packed = _transpose_and_pack(quantized, orientation, panel_type)
+    if capture_snapshot:
+        return packed, _png_bytes(quantized)
+    return packed


 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:
+                       manage: dict | None = None, panel_type: str = DEFAULT_PANEL_TYPE) -> 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)
+    panel_w, panel_h = panel_size(panel_type)
+    fitted = _enhance(_compose(source, faces, orientation, display_mode, panel_w, panel_h),
+                      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()
+    return _png_bytes(quantized)


 def render_placeholder(lines: list[str], qr_url: str | None = None,
                       orientation: str = "landscape", palette_rgb: list | None = None,
-                       manage: dict | None = None) -> bytes:
+                       manage: dict | None = None, as_png: bool = False,
+                       capture_snapshot: bool = False,
+                       panel_type: str = DEFAULT_PANEL_TYPE) -> bytes | tuple[bytes, 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
@@ -386,15 +736,16 @@ def render_placeholder(lines: list[str], qr_url: str | None = None,

    `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."""
-    from PIL import ImageDraw, ImageFont
-
-    logical_w, logical_h = logical_render_size(orientation)
+    yet. `capture_snapshot`, same as render_panel's -- (packed, png)
+    instead of just packed. `panel_type`, same as render_frame's."""
+    margin = 24
+    logical_w, logical_h = logical_render_size(orientation, *panel_size(panel_type))
    img = Image.new("RGB", (logical_w, logical_h), (255, 255, 255))
-    draw = ImageDraw.Draw(img)
+    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:
@@ -409,19 +760,39 @@ def render_placeholder(lines: list[str], qr_url: str | None = None,
        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
-        bbox = draw.textbbox((0, 0), line, font=font)
-        line_heights.append((line, font, bbox[2] - bbox[0], bbox[3] - bbox[1]))
+        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(((logical_w - w) // 2, y), line, fill=(0, 0, 0), font=font)
+        draw_text(img, ((logical_w - w) // 2, y), line, font)
        y += h + gap

    if qr_img:
@@ -429,4 +800,9 @@ def render_placeholder(lines: list[str], qr_url: str | None = None,

    img = _apply_manage_overlay(img, manage)
    quantized = _quantize(img, palette_rgb, dither_strength=1.0)
-    return _transpose_and_pack(quantized, orientation)
+    if as_png:
+        return _png_bytes(quantized)
+    packed = _transpose_and_pack(quantized, orientation, panel_type)
+    if capture_snapshot:
+        return packed, _png_bytes(quantized)
+    return packed
@@ -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")
--- a/Show More
+++ b/Show More
@@ -1 +1 @@
 .3.0
 .4.2