Push notifications: suppress when user is actively using the app (tab visible / online)

[serge-ivo]

Bug

Push notifications are being sent even when the user is actively looking at the app. If the user has the app open and visible (tab is in the foreground, app is online), push notifications should be suppressed entirely — they are redundant and disruptive.

Expected behavior

• Push notifications should only be delivered when the user is not looking at the app — i.e., the tab/window is hidden, the app is in the background, or the client has gone offline.
• If the user is online and the app tab is visible (document.visibilityState === 'visible'), do not send or display a push notification.

Steps to reproduce

1. Open the app and keep it in the foreground.
2. Trigger any action that generates a push notification (e.g., agent reply, alert).
3. Observe that the push notification fires even though the user is actively viewing the app.

Fix

• On the client side: before registering or displaying a push notification, check document.visibilityState and the online status. If the page is visible and online, suppress the notification.
• On the service worker / backend side: consider passing a presence/visibility signal so the server can skip sending the push payload when the client is known to be active.
• Gate the push delivery on: document.visibilityState !== 'visible' || !navigator.onLine.

[serge-ivo]

This appears to be already implemented — worth verifying before anyone picks it up.

store/sw.js:16-19 does exactly what this ticket asks:

self.clients.matchAll({ type: "window", includeUncontrolled: true }).then((clients) => {
    // Skip notification if the user has a visible console tab
    const onSite = clients.some((c) => c.visibilityState === "visible" && c.url.includes("/console"));
    if (onSite) return;

The /console URL filter covers the whole app, not just one page: the SPA is mounted at base: "/console/" (store/console/vite.config.ts:7) with a matching router basename, so every console route contains it.

The !navigator.onLine half of the proposed gate is moot — if the client is offline the push isn't being displayed anyway.

Two things that would make this real again rather than closeable:

1. Which surface did you see it on? The SW only governs the web app. If the notification appeared on the iOS/Android build, that is a genuinely uncovered path and this ticket should be re-scoped to say so.
2. The server-side half is genuinely not done. notifyUser (routes/push.ts:195) always calls sendPushToUser; the suppression is display-side only. That costs bandwidth and battery, not user disruption — a smaller, different ticket than the one filed.

Suggest closing as already-fixed unless (1) applies.

[serge-ivo]

Verified your comment at HEAD: the premise is already implemented for the web app, and I shipped the half that genuinely was not — 5c38591 (CI green, host deployed, live at https://proagentstore.online/sw.js).

What was already true. store/sw.js skips showNotification whenever a /console client reports visibilityState === "visible", and that URL test does cover every route (SPA base /console/ + matching router basename). The !navigator.onLine half stays moot — an offline client is not displaying a push either way.

What was missing. The suppressed push was dropped. The thing you would have been told about then reached you only via the bell badge, on its next 30s poll. So "suppressed because you are looking" was true of the notification but not of the information.

The SW now forwards the payload to the visible tabs instead of discarding it, and Layout refreshes the badge on receipt. Push covers "not looking", the badge covers "looking", neither fires twice. It is also what let the badge poll halt in a hidden tab in #272 without opening a gap — hidden is exactly when the push does fire. Wire format + guard are pure and tested in store/console/src/lib/pushMessages.ts (message on a page is a shared channel, so it recognises its own envelope exactly rather than approximately).

Left for you — the two things I will not guess at

1. Which surface showed it. Still unanswered, and I could not settle it from the code, so I did not re-scope the ticket. What the code does say: ios/ and android/ are thin WebView shells (MainActivity.kt, no push code, no notification path a service worker governs), and per the pags-native-app-store-submission note they are debug builds that were never submitted — so if what you saw was on a phone, it was the installed PWA (SW logic applies, and this fix applies) and not a native build. If it was the web app or the PWA, this is closeable as-is. If it really was a native build, that is an uncovered path and the ticket should be re-scoped to say so.

2. The server still sends every push unconditionally. notifyUser → sendPushToUser (workers/api/src/routes/push.ts:204) — suppression remains display-side, which costs bandwidth and battery rather than attention, exactly as you called it. Doing it properly needs a presence signal the server can read (a heartbeat from the visible tab, or last-seen on the session), which is a server-side change and a different, smaller ticket. I stayed client-side deliberately: another agent owns workers/api/** this batch.

Leaving this open on question 1 rather than closing it on an assumption.

[serge-ivo]

Closing this: the display side is the whole fix, and the server side should not be built

The suppression shipped in 5c38591 and is complete end to end: store/sw.js skips
showNotification() when a /console client reports visibilityState === "visible", and forwards
the suppressed payload to those tabs (pags:push-suppressed) so the bell badge updates immediately
rather than on its next poll — Layout.tsx:70 consumes it. Suppressing a notification is only
honest if the app surfaces it, and it does.

What was left open was the ticket's second bullet: "consider passing a presence/visibility signal so
the server can skip sending the push payload" — making notifyUser → sendPushToUser conditional.
I looked at building it and it should not be built, for three reasons in descending order.

1. It would be a regression, not an improvement. Presence would be per-USER; push delivery is
per-DEVICE. sendPushToUser fans out to every subscription the account has. "This user has a visible
tab somewhere" is not the question that decides whether a given device should buzz — and answering
the wrong question kills the phone notification because a laptop tab happens to be open. That is
strictly worse than today. The service worker does not have this problem: each device decides for
itself, at delivery time, from ground truth about that device. There is no server-side signal that
can match that, because the fact being tested lives on the client and is per-endpoint.

2. Keeping it fresh means reintroducing the polling that was just removed. A presence row is
only useful if it is current, which means a periodic write from every visible tab, forever. The
commit that shipped the display half (5c38591, with a50b5ce) exists specifically to stop tabs
spending on fixed-interval work — seven pollers moved to active/idle/hidden cadences. A presence
heartbeat is that cost re-added as a D1 write, on the one path we deliberately just quieted.

3. Any heartbeat is wrong inside its own TTL window, and wrong in the dangerous direction. A user
who tabbed away seconds ago still reads as present, so the notification is suppressed and never
arrives anywhere — a lost notification, which is much worse than a redundant one. The client-side
check has no such window.

Set against that, the benefit is one avoided Web Push HTTP request. The banner is already not shown;
nothing user-visible changes. That is not worth a presence store, a heartbeat, and a per-device
correctness regression.

The open question about which surface showed the notification (PWA or a native shell) is settled:
ios/ and android/ are WebView shells with no push code and were never submitted, so any sighting
on a phone was the PWA — which is exactly what sw.js governs.

Closing as done by the display-side fix. If a case later appears where suppression must be
per-device and server-side (e.g. push costs money, or a device must be excluded before send), the
right shape is to key presence on the push subscription endpoint the tab owns, not on the user —
but nothing today needs it.

[serge-ivo]

Referenced from #360. The gate shipped here is correct and #360 is not a re-open — verified at HEAD that store/sw.js:25 still suppresses on a visible /console client and forwards the payload.

What #360 covers is what a per-device visibility gate structurally cannot: sendPushToUser (routes/push.ts:145) fans out to every subscription row for the user, and each device's SW decides independently. So the laptop you are looking at goes quiet and the phone in your pocket does not. The closing comment here identified the per-USER vs per-DEVICE tension as the reason not to build a server-side presence gate — correctly — and #360 takes the consequence from there: a per-type mute and actor suppression, rather than presence.