docs: specify desktop-driven mobile push suppression (#7809)

## Summary

Define when desktop activity suppresses otherwise eligible mobile
message notifications: a ten-minute inactivity window, short-lived
relay-owned suppression, and per-installation push preferences. Include
a shared glossary and renewal timing diagram. The gateway remains
unaware of suppression.

This is a design draft ready for review, not an implementation-ready
protocol. Wire format, synchronization, and several failure-handling
details remain explicitly open. Please also review the tension between
the agreed relay-confirmed preference changes and VISION_MOBILE.md's
requirement that stopping notifications must not depend on a relay
response.

### Related issue

Related: #3234 covers per-channel notification settings and push
filtering; this spec focuses on desktop-activity suppression. No
duplicate spec PR found.

### Testing

Documentation-only change. Local Markdown links and anchors resolve;
whitespace validation and commit hooks passed. The full local CI gate
could not complete: dependency compilation exhausted local disk space
(OS error 28). GitHub checks currently report no failures.

---------

Signed-off-by: Tom Brow <tomb@block.xyz>
Co-authored-by: Diem Nguyen <ngthuydiem@users.noreply.github.com>
This commit is contained in:
Tom Brow
2026-09-29 09:54:08 -07:00
committed by GitHub
parent efe04288ea
commit 45c288c179
3 changed files with 242 additions and 1 deletions

View File

@@ -10,7 +10,7 @@ When writing a spec or implementing significant changes or tests, check them for
- **Offline first.** Show cached content immediately; support reading, composing, and queuing actions regardless of connectivity. Sync in the background without disrupting use. Make unavailable content and prolonged sync problems clear.
- **Responsive UI.** The user interface does not hang or stutter, regardless of the scale of a community or number of communities joined. Expensive or slow operations happen in parallel with UI feedback and animation. Actions are reflected in UI instantly and optimistically.
- **Don't lose user-generated data.** Drafts and pending actions survive restarts, app updates, and cache rebuilds. Important pending actions (e.g. undelivered sent messages) are clearly identified visually and offer affordances for retrying or recovering the uncommitted data.
- **Don't trust relays.** Their behavior is outside our and users' control. Critical user intents (leaving a community, stopping notifications from a relay, etc.) should never be blocked on a response from a relay. The behavior or performance of one relay that the client is connected to should not degrade the experience of using other relays or non-relay-dependent functionality in the app, including by adding latency.
- **Don't trust relays.** Their behavior is outside our and users' control. Critical actions that the client can enforce, such as leaving a community locally, must not wait for a relay response. Changing a relay-controlled push preference requires relay cooperation: saving a local choice or retrying indefinitely does not guarantee that remote notifications stop. For this setting, show a bounded pending state, then make rejection, unavailability, or missing confirmation clear without claiming success. Warn that notifications may continue and let the user pursue separate recourse; do not queue the failed change for automatic retry. Recourse against a relay that ignores notification preferences is separate from the [mobile push suppression spec](docs/mobile-push-suppression.md). The behavior or performance of one relay that the client is connected to should not degrade the experience of using other relays or non-relay-dependent functionality in the app, including by adding latency.
- **Accessibility.** The app supports platform accessibility features, including screen readers, text scaling, and reduced motion.
## Relationship to other clients