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

53
CONTEXT.md Normal file
View File

@@ -0,0 +1,53 @@
# Buzz domain language
Shared terminology for Buzz product behavior. This glossary currently covers mobile [push suppression](#push-suppression); it is not a complete model of Buzz.
## Notifications
### Mobile push notification
A notification directed to a user's mobile installation through the platform's push service.
### Push suppression
Withholding an otherwise eligible [mobile push notification](#mobile-push-notification) based on [desktop activity](#desktop-activity) and a working connection to the relevant community. It does not depend on whether desktop alerts can be shown.
_Avoid_: Read receipt, mark as read, mute
### Desktop activity
User interaction with the computer running Buzz, including interaction with another application. It is the interaction itself, not a state that lasts afterward, and does not imply that a particular Buzz message was displayed or read.
_Avoid_: Message visibility, read activity
### In-app activity
User interaction inside Buzz. Recent in-app activity remains evidence of [desktop activity](#desktop-activity) after Buzz loses focus; current window focus is a separate condition.
### Desktop inactivity
The state reached when the duration specified in the spec has elapsed since the last observed [desktop activity](#desktop-activity).
### Additional notification delay
A waiting period after [desktop inactivity](#desktop-inactivity) begins before [mobile push notifications](#mobile-push-notification) resume. This is distinct from the inactivity threshold itself.
### Suppressed message
A message whose otherwise eligible [mobile push notification](#mobile-push-notification) was withheld. The term refers to its notification, not withholding the message itself, and says nothing about whether the message has been read.
### Suppression activity signal
Information communicated for deciding whether [desktop activity](#desktop-activity) warrants [push suppression](#push-suppression). It is distinct from [visible presence](#visible-presence) and is not a read receipt.
### Visible presence
The availability status shown to other members, such as online, away, or offline. A chosen visible presence status does not necessarily reflect actual [desktop activity](#desktop-activity).
### Suppression renewal
A [suppression activity signal](#suppression-activity-signal) that extends how long [push suppression](#push-suppression) applies based on activity on one desktop.
### Inactivity cutoff
The time of the last observed [desktop activity](#desktop-activity) plus the duration specified in the spec, when [desktop inactivity](#desktop-inactivity) begins. New desktop activity moves this cutoff forward.