Example pictures in the Plugin Library (M5 part 3b-2)

[txoof-bot]

Part of #238 (M5 part 3b-2: example pictures in the Plugin Library).

What changed

Each plugin in the Plugin Library now shows an example picture, drawn with its sample data and default settings, at your screen's size. The plugin's name and its picture open the Add page (the separate Add link is gone, txoof 2026-10-10).

• Best gray (txoof 2026-10-10): pictures are drawn in 256 shades of gray, also for black-and-white and 4-gray screens, so they are easy to see on a phone. Color screens keep their colors. The page says a black-and-white or gray screen shows fewer shades.

• Drawn ahead, saved (txoof's choice A, 2026-10-10): pictures are drawn in the background and saved in library-pictures/ in the state folder, so the page opens at once. Drawing starts a minute after PaperPi starts (the first screen update goes first), or at once when the Library page is opened or the config is reloaded. One picture at a time, each in its own plugin process, 10 s limit (as the preview's sample).

• Fingerprint in the file name: <type>-<16 hex>.png, made from the name, size and time of last change of every file in the plugin's folder, the screen's width/height/type, and the PaperPi and epdlib versions. A new or changed plugin or another screen gets a new name, so it is drawn again; pictures that match nothing are deleted. File contents are not read: moon_phase has 19 MB of images, too slow to read at every page open on a Pi 3 (all 9 fingerprints take about 75 ms on this Pi 4).

• While missing: the page shows "Drawing the example picture…" and asks again every 3 s (htmx) until it is there.

• Failures: a plugin that is too slow is tried up to 3 times; any other failure shows why and is not tried again until the fingerprint changes or PaperPi restarts, so an open Library page can't keep the Pi busy. A folder that can't be written says so.

• Reload: as in the scheduler, a change of the screen's type, model, size or mode applies at the next start, so the pictures keep the start values (rotation and color apply at once).

• New route GET /library/pictures/<file> (login needed, strict name check, no links, private, max-age=86400) and GET /library/<type>/picture (the htmx part).

• New limit LIBRARY_PICTURES_WAIT = 60. server.start gets state_dir and display from paperpi run.

Measured on this Pi 4: all 9 pictures for a 1200×825 gray16 screen in 11 s, about 270 KB in all.

Known limits (also in the design note): changes to PaperPi's shared code outside a plugin's folder count only through the version number; the web interface loads each plugin's code once, so the Library list (and a plugin that was broken at the start) changes only after a restart. Two PaperPi processes sharing one state folder would delete each other's pictures (not a supported setup).

Preview on the settings page (txoof asked whether it matches the configured screen): it already used the screen size and type from [display] (tested since 3b-1). One gap is fixed here: after a change of size, mode or type that waits for a restart, previews now draw for the screen as it runs, like the Library pictures and the scheduler (PluginEditor.display, set by WebServer.use_display).

Area

web (src/paperpi/web/), core (cli.py, limits.py), docs (README.md, docs/decisions/web-interface.md).

Tests

• New tests/test_web_pictures.py (29 tests, fake plugin process): drawn once, changed plugin / other screen drawn again, only old pictures and .part files deleted, failures shown and not retried, slow plugin tried 3 times, any error shown while the others are still drawn, unwritable folder, wait at start, stop, reload keeps size, name check and links, Library page, htmx part, picture route. test_cli.py checks the new start arguments.
• uv run pytest -n auto: 1475 passed (picture tests 5 times in a row with -n 4: no flaky runs)
• uv run ruff check . passes
• Hardware tests: not needed (no display or driver code changed)
• End to end: paperpi run with a virtual screen; pictures appeared within the first page checks; a screen change applied only after restart, old pictures were deleted.

Images

No browser on the Pi for a screenshot. A demo runs on the Pi for a look: http://192.168.1.224:8091/library (virtual 800×480 black-and-white screen, login off, scratch config).

Review

• Review agents' comments answered: four reviews (quality, tests, security, docs) ran before opening; all their findings are fixed in the second commit, except the shared-state-folder case and the shared-code fingerprint gap (listed above as known limits).

Only txoof approves and merges this PR.

🤖 Generated with Claude Code