Preview button on the plugin settings page (M5 part 3b-1)

[txoof-bot]

Part of #238 (M5 part 3b-1).

What changed

A Preview button on each plugin's settings page. It draws the plugin with the settings in the form, before you save them, at your screen's size and for your screen's type. The real screen is not touched and nothing is saved.

• Preview applies the form to a copy of the config file text, the same way Save does, so it draws exactly what Save would write.
• The drawing runs in its own process with a time limit, as normal updates do (runner.run_update). Each preview gets a new, empty storage folder that is deleted afterwards.
• Real data first, for at most 45 s (or the plugin's own time limit, if shorter; agreed 2026-10-09, Q2 = B). When the real data fails, takes too long, has nothing to show, or a required setting is still empty, the preview draws the sample data (at most 10 s) and says why.
• One preview at a time. A second click meanwhile gets "Another preview is being drawn. Wait a moment, then try again."
• The picture is sent inside the page (a data: address), so it is never saved as a file. The pages' security header now allows such pictures: img-src 'self' data:.
• When PaperPi stops, no new preview drawing starts. An unexpected error shows a short message, with the details in the log. If the log-in has expired, the log-in page opens normally instead of inside the preview area.
• No "send to display" button here (Q1 = B): a "Show on screen now" button comes with the home page in part 4.
• Docs: README, docs/decisions/web-interface.md (update for 3b-1), docs/writing-plugins.md (sample data is also used by previews).
• CLAUDE.md: new rule "every PR is based on main, no stacked PRs" (the leftover from part 3a).

New files: src/paperpi/web/preview.py, src/paperpi/web/templates/preview.html, tests/test_web_preview.py. New limits: PREVIEW_LIVE (45 s) and PREVIEW_SAMPLE (10 s) in limits.py.

Choices I made without asking

• A preview uses a new, empty storage folder, not the plugin's own one, so it can't change saved files such as downloaded data.
• The waiting text says "This can take about a minute" (45 s of real data + 10 s of sample + starting processes).
• Every answer of the preview address is a 200, because htmx only shows 200 answers. Errors are shown as text in the preview area.

For later (noted in the design note)

• Security review: an empty secret field keeps the saved secret, also in a preview. A future plugin with both a secret and a web address the user can change (for example the Dutch public transport plugin) must not send the saved secret to a changed address, and its network errors should only say "could not reach the server". No current plugin has such an address.
• Error texts from plugins show Python error names (e.g. "URLError: ..."). This is older behaviour from runner.py; the preview is the first page that shows it.

Area

web (src/paperpi/web/), core (limits.py, one line in cli.py), docs, CLAUDE.md, README.md.

Tests

• 29 new tests in tests/test_web_preview.py: real data at the screen's size and type (also a rotated gray4 screen), the 45 s cap, unsaved form values used and nothing saved, sample fallback with its reason (timeout, error, nothing to show, missing setting), sample failing too, form errors, a block changed meanwhile, two blocks with the same ID, problems of other blocks not listed, a saved secret kept and never shown, one preview at a time, the lock freed after an error, unexpected errors, stopping, expired log-in with htmx, the security header, and one real end-to-end preview of basic_clock (about 1 s).
• uv run pytest passes: 1445 passed (with -n auto)
• uv run ruff check . passes
• Hardware tests: not needed (no display or driver code changed)

Images

No browser on the Pi, so no screenshot of the page. The preview of basic_clock was checked by eye: the real current time at 1200 x 825 pixels. To try it: open a plugin's Settings, change a value, press Preview.

Review

• Review agents' comments answered: 4 reviews (code quality, tests, security, docs) ran before the first push; all their findings are fixed in the second commit or listed above under "For later". Nothing was posted as comments.

Only txoof approves and merges this PR.

🤖 Generated with Claude Code