diff --git a/docs/plans/2026-10-19_seen-click-intent.md b/docs/plans/2026-10-19_seen-click-intent.md new file mode 100644 index 000000000..225ac823b --- /dev/null +++ b/docs/plans/2026-10-19_seen-click-intent.md @@ -0,0 +1,30 @@ +# Brief: a Seen click that waited out a Board read can undo another viewer's mark + +Gitea #1671. Filed by Sage on Mos's ruling mos-0861 A1, from Darkwing's non-blocking note on row 172 (#1670, comment 29207). +Low priority. It goes after row 66. Nobody starts it until it is briefed and claimed. Line numbers are at +origin/refactor b5d4d0f22. + +## The problem + +Row 172 made a Seen click that lands during a Board read wait for the read +(`packages/webui/src/public/app.js:407-419`). After the wait the handler looks the row up again from the fresh +data (`:414`) and posts `seen: !r.seen` (`:416`). The click means what its label said when the person clicked it: +"Seen" marks the row seen, "Unsee" returns it to waiting. The post instead toggles whatever the fresh row says. + +So if another viewer marks the row seen while the read is in flight, the fresh row is already seen, and this +click posts `seen: false`. A click meant as "mark seen" returns the row to waiting, and the announcement says +"returned to waiting". The reverse case works the same way with "Unsee". + +## What a fix needs to settle + +- The intent comes from the button as clicked: its label or a `data-` value captured before the wait, not the + fresh row. +- If the fresh row already holds that intent, the click posts nothing, or posts the same value (what the route + does with a repeat decides which), and says so. +- A test in `packages/webui/tests/board-held.test.mjs` holds the read with `window.__hold`, changes the row's seen + state in the held answer, clicks Seen and checks the post and the announcement. + +## Out of scope + +Changing the `/api/seen` route itself (`packages/control-board/src/serve.mjs:257`, which the webui forwards to). The row 172 wait and the single-click guard stay as +they are.