fuzzyworld-tools / commit
Plan: report replays on the issue pages (Q104)
PLAN.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/PLAN.md b/PLAN.md index 44459b3..0d6c2f8 100644 --- a/PLAN.md +++ b/PLAN.md @@ -4,7 +4,7 @@ Where fuzzyworld-tools goes from here: from "a static mirror of my repos" to a s code host built on one rule: **DreamHost only serves files; other machines do the work.** This is a planning document. Nothing in it is promised; the order is the current priority. -Last updated 2026-10-28. +Last updated 2026-11-03. **Who it is for.** First, me: I build the site I want and need (no GitLab, no WordPress, as few machines as possible). Second, anyone who wants to get going with the fewest resources. Anything that only makes sense for my setup is @@ -320,6 +320,46 @@ because it runs on a machine in my home (part of Pull requests). A private repo's issues are always private, whatever this says. - Import the GitLab issues and notes in `~/code/gitlab-export/*/issues.json`. +### Report replays (Q104; planned 2026-11-03, nothing built here yet) + +Idea from the Explodorama bug mails: a report can carry a **machine-readable payload** (for the game: the run +record, a few KB of JSON: seed, rules version and actions), and the issue page can then show *what the reporter +saw* as a looping animation. The game side (the replay page, its limits, how old rules are loaded) is in +`~/code/explodorama/PLAN.md` §20. This repo's part: + +- **Intake stays email.** DreamHost only serves files, so no upload endpoint (no abuse surface, no server code). + The existing mailbox cron reads `Run record: {…}` (or whatever line an app agrees on) out of a report. + The mail's quoted-printable text is decoded first (the game's `tools/report-replay.mjs` already does it in + Node; port the same rule to Python, and keep a test with a real report). +- **Store it beside the issue.** For a repo whose issue mode allows publishing, the cron writes the payload as + a static file next to the issue page (`…/issues/<n>/record.json`), under the same visibility rule as the + report itself: `public` as it arrives, `reviewed` only after I mark it public, `private` never. The payload + is validated first (size ≤ 64 KB, parses as JSON, expected keys); anything else stays only in my mailbox. + Reporter emails are still never shown; the device string stays out of the page by default. +- **Link a viewer, don't build one.** An app announces its viewer in `package.json`, for example + `"fuzzyworld": { "replay": "replay.html?report={record}" }`; with it, an issue page that has a payload shows + "Watch what happened", a link (or an iframe on the same origin) to that page of the app, with `{record}` set + to the stored file. Without the key, nothing changes. This keeps the core free of any game knowledge (🔌 + plugin-shaped: an app opts in). +- **CSP.** The viewer is the app's own script on the app's own origin, so the site-wide `script-src 'self'` + policy (Q99) holds; the record is data, never inserted as HTML. The issue page itself needs no script. +- **Old rules.** A viewer may need the sim of the report's own rules version. An app can publish those as + static files at deploy time (Explodorama: `/explodorama/sim/<simVersion>.js`); fuzzyworld-tools only has to + let `fw deploy` carry such extra files (a per-app list of globs in `package.json`) and keep old ones. The + runner (TrueNAS) can build them on a tag; DreamHost has no Node. +- **Admin panel (Q102).** On the laptop, the inbox lists reports with a Replay link per report (the same viewer, + served locally with the dev page's `&rules=` mode, which can use any commit from git), and the buttons that + mark a report public, close it, or turn it into a regression fixture in the app's repo (`test/fixtures/`). + The panel is a thin local web page over `fw` commands; it holds no state of its own. + +**Order:** (1) the game's production replay page and limits (its PLAN §20.2 steps 1-2), by hand, with a stored +record; (2) the cron extracting and publishing `record.json` and the `replay` key; (3) per-rules-version sim +files in `fw deploy`; (4) the panel. Each step is useful alone. + +**Open:** whether the viewer opens in the same page (iframe) or its own; a `reviewed` report's payload being +published at the same moment as its text; how long old `sim/` files are kept; compact records in the game's +`mailto:` link (game PLAN §20.2 step 4) before or after step 2. + ## Pull requests - Contributions arrive at `contrib-68uq+<repo>@fuzzyworld.net` as a branch URL or patches (already live).