Web interface (M5)

The issue splits the work into five substantial parts and points to src/paperpi/web/, cli.py, config.py, scheduler.py, pyproject.toml, and uv.lock. Start by reading docs/decisions/web-interface.md, config-format.md, and live-config-reload.md, then choose one unclaimed part and trace its relevant entry points. Done means implementing that part as a separate PR, including its listed behavior and any required dependency or documentation updates.

The web interface for PaperPi v2 (milestone M5). Design: docs/decisions/web-interface.md, config-format.md, live-config-reload.md.

Decided with txoof (2026-10-07)

• The web server runs inside paperpi run in its own thread. Preview drawings run in a separate process with a time limit, like normal screen updates.
• The password is stored as a scrypt hash (built into Python) in the config file.
• New packages: fastapi, uvicorn (plain), jinja2, python-multipart.
• Log-in can be switched off with a setting in the config file. Then anyone on the home network can use the web interface without a password.
• Forgotten password: clear steps in the docs and on the log-in page, and a command:
  1. Run paperpi reset-password on the Pi (or in the Docker container). It removes the saved password (deleting the line by hand does the same).
  2. Restart or reload PaperPi.
  3. Open the web interface; the first visitor sets a new password.

Parts (one PR each, about 300–600 lines)

• 1. Web server and log-in (split in two, 2026-10-07):
  • 1a. [web] settings, password hash storage, paperpi reset-password: #239
  • 1b. Server inside paperpi run, first visitor sets the password, cookie for 1 year, Log out, login = false, base page, htmx shipped: #240 (stacked on #239)
• 2. Plugins (split in two, agreed with txoof 2026-10-07):
  • 2a. Required plugin settings (paperpi.plugin.setting(required=True), the standard place for a setting's options; met.no plugins need a real email): #241
  • 2b. Active Plugins page (only the plugins you added: on/off, move up/down buttons, remove with "Are you sure?"; "Needs settings" and Switch on greyed out) and Plugin Library page (every plugin with its description; add one with a name). Saving keeps comments, keeps unapplied hand edits and applies at once. Split in two (agreed with txoof 2026-10-07):
    • 2b-1. Editing plugin blocks in the config file as text: #244
    • 2b-2. The two pages: #245
• 3a. Plugin settings form built from each plugin's settings description (opened from Active Plugins), errors next to fields. Split in three (agreed with txoof 2026-10-08), stacked:
  • 3a-0. Fixed plugin id + friendly name (renaming without losing the storage folder): #251 (merged)
  • 3a-1. Writing settings into a plugin block; form fields from the settings description and checked values back, with an error per field; pytest-xdist: #256 (together with 3a-2)
  • 3a-2. The settings page (layout: own settings, then display time / refresh / layout / level, the rest folded under "More settings"; folded "Technical information" with the id), the place where setting helpers plug in, opened right after adding from the Library: #256
• 3b. Preview button (separate process, sample data when the source can't be reached), and example pictures in the Plugin Library. Split in two (2026-10-09), each based on main:
  • 3b-1. Preview button on the settings page (real data for at most 45 s, then the sample data, saying why; one preview at a time; no "send to display" here, a "Show on screen now" button comes in part 4): #258
  • 3b-2. Example pictures in the Plugin Library (drawn ahead, saved in the state folder, redrawn when the plugin or screen changes): #265
• 3c. Setting helpers (design: docs/decisions/setting-helpers.md, agreed with txoof 2026-10-10). Lookup service: Open-Meteo (gives altitude too). Two PRs, each based on main:
  • 3c-1. The general structure: helpers return choices as dictionaries of kinds (fill, show, link, note), search box, pick list and Use on the settings page: #268
  • 3c-2. location with Open-Meteo for met_no and moon_phase, altitude for met_no (the work of #176): #271
  • Later: command line paperpi helper met_no.location "...": #269
• 4. Home page (current screen image, updates by itself; "Show on screen now" button for a saved plugin, agreed 2026-10-09), warnings page, "config file changed outside the web interface. Apply changes?".
  • txoof, 2026-10-10: the image of what is on the screen now goes at the top of the home page (the main screen of the web interface), before anything else.
  • Designed with txoof on 2026-10-11 using clickable mockups: the home page shows the screen picture at the top (shrinks to a slim bar while scrolling) and replaces the Active Plugins page (plugin cards with their last picture, list or grid, drag to reorder, Show now, Skip to next, Refresh); a menu on every page (covers #262); light/dark button.
  • The Warnings page gets a Full log tab: the log lines since PaperPi started (kept in memory), with filter, search, new lines while the page is open, and Download log as a text file (txoof, 2026-10-11).
  • Hand edits: a bar on every page links to a Review changes page (old → new per plugin, Apply changes, Undo hand edits). Command line paperpi reload: #272.
  • PRs, each based on main, one after another:
    • 4-1. New look, menu on every page (closes #262), light/dark button, design decisions in web-interface.md: #274
    • 4-2. Scheduler controls (Show now as an extra turn, Skip, Refresh, Dismiss) and a summary of its state, no web pages yet: #276
    • 4-3. The new Home page (screen picture at the top, plugin cards, drag to reorder); replaces Active Plugins: #280
    • 4-4. Warnings page and log (small log file + memory, Full log tab, download)
      • 4-4a. Log keeping (memory + small file, plugin process lines) and the Full log tab: #281
      • 4-4b. Warnings tab (Needs attention now, recent warnings and errors, count in the menu): #286
    • 4-5a. Review changes page: bar + changes + Apply changes (#290)
    • 4-5b. Undo hand edits (confirm, keeps paperpi.toml.undone) (#291)
    • Plugin Library refresh
      • A. Plugin titles, labels (Requires setup / Requires internet / Uses home network), "Added:", search, README page per plugin: #292
      • B. Layout titles (also on the settings page), a picture for every layout, Look closer, the Add window; titles instead of types on Home, Settings and Remove
• 5. Application and screen settings.
  • txoof, 2026-10-10: a way to change the display type and the other system settings in the web interface, not only in the config file: [display] (type, model, width/height, mode, rotation, color, vcom, max_refresh, clean_every, on_exit, fallback_clock, splash_time) and [web] (port, address, login, password). To decide when starting: which settings apply at once and which need a restart (docs/decisions/live-config-reload.md), and how a wrong screen type or port is undone when the page can't be reached any more.

Area

web (src/paperpi/web/), core (cli.py, config.py, scheduler.py hooks), ci (pyproject.toml, uv.lock), docs.