An abstract NotificationBridge with a dart:js_interop web implementation and an honest unsupported stub; a NotificationController that reports only the platform's permission word, asks only from an explicit gesture, never re-prompts a denied answer, and notifies once per run+kind+finished marker under its own persisted ledger key. One reusable native NotificationPermissionTile for Settings, an isolated browser probe, and focused tests. No shell/settings wiring.
7.8 KiB
A2 — notification capability behind a platform seam
The notification capability exists as reusable Dart under
lib/features/attention/notify/, plus one reusable Settings tile at
lib/features/attention/ui/notification_permission_tile.dart. Nothing was wired
into the shell, Settings, the application or the Runs screen, and no tracked
file outside those paths changed (git status shows only new files).
What is there
| File | Lines | Role |
|---|---|---|
notify/notification_models.dart |
170 | permission state, environment, copy, permission view, alert title/body, NotificationMessage |
notify/notification_bridge.dart |
30 | the abstract NotificationBridge + the conditional-import factory |
notify/notification_bridge_web.dart |
95 | the real Notification API via dart:js_interop (no package:web) |
notify/notification_bridge_stub.dart |
27 | non-web stub that reports unsupported honestly |
notify/notification_ledger.dart |
91 | identity (run+kind+marker), ledger, total JSON codec, pipelines.next.notify.v1 |
notify/notification_store.dart |
83 | injectable store seam; total shared_preferences impl + memory impl |
notify/notification_controller.dart |
194 | the ChangeNotifier capability |
ui/notification_permission_tile.dart |
127 | the reusable native tile |
tool/notification_probe.dart / .mjs |
265 / 295 | isolated real-browser probe |
Platform seam
NotificationBridge answers the platform's own facts
(environment() → supported, secureContext, raw permission),
requestPermission() (only ever called from an explicit gesture) and
show(message, onTap:). The web bridge declares @JS('Notification') with
external factory, external static permission, external static requestPermission and an onclick setter, and reaches the global only after a
globalContext support check, so an unsupported browser is never touched. The
stub returns supported: false and show() == false.
NotificationController.permission is one of unsupported,
needsSecureContext, notRequested (the API's own default — default is a
Dart reserved word, and each state exposes wireName = unsupported |
insecure | default | granted | denied), granted, denied. It is
derived only from notificationStateOf(environment); granted is never assumed
from an unrecognised word. requestPermission() asks only while the state is
still notRequested, issues the platform request before any await so it stays
inside the gesture, persists asked without awaiting, and follows the platform's
answer. A denied state is never re-prompted.
Notify only on live transitions
- The initial list seed raises no transition, so
publishTransitionsover the attention controller's (empty) transition list posts nothing. - The dedupe identity is
{runId}:{Kind}@{marker}where the marker is the run's trimmedfinished_atelsecreated_at— the same recency the surface orders by. A retried run that fails again carries a new marker and notifies once more; the same transition can never notify twice, including across a reconnect. - The ledger records an identity before the platform is asked to show it and
persists it under
pipelines.next.notify.v1through the injectableNotificationStore.publishTransitionsis therefore idempotent, so the manager may pass the whole accumulated transition list. A store that throws on read or write is swallowed; the in-memory ledger still applies for the session. - A dismissed identity is recorded but never shown (the transition detector already suppresses it; the publish guard covers a caller that passes it).
- Content is the entry's own words: the kind headline (
A run failed/A run needs your decision) andlabel · pipeline, matchingweb/src/notify.jsandRunAlerts.ktverbatim. Nothing is invented, and nostagefield is added because neither reference client's alert body carries one. - A batch posts in order, bounded to
maxNotificationsPerBatch(5); the rest are posted on the next call because the ones already posted are recorded.
Wiring the manager still owes
final notify = NotificationController(store: const SharedPreferencesNotificationStore());
notify.onOpenRun = (runId) { /* open that run — navigation lives here, not in notify */ };
await notify.load();
// after each authoritative read / pushed frame the attention controller handles:
notify.publishTransitions(attention.transitions, dismissed: attention.dismissed);
load() once, and publishTransitions on every frame/seed, is enough; it is
idempotent. refreshPermission() re-reads the platform facts after a focus
change. The tile is embedded by the Settings screen with the live state/asked
and an onRequest that calls notify.requestPermission().
Tests and evidence
flutter test test/features/attention— 135 passed (the 43 new notify/tile tests plus the existing attention suite; the new coverage is: seed never notifies; one live transition once with its own words and identity; duplicate frame and republished list silent; reconnect reseed and a rebuilt controller silent; a genuinely new failure notifies again; dismissed excluded (detector and publish guard); unsupported/needs-secure/denied/granted permission paths and "denied is never re-prompted"; a prompt that grants nothing; the bounded batch; the tap seam; an unavailable store and a throwing platform post; the non-web stub; the tile copy per state, the asked wording, the Enable gesture and both hosts at 320 logical px / 2x in dark with the action present).flutter analyze— No issues found (whole project).flutter build web(the reallib/main.dart) — succeeded.- Real-browser probe (
tool/notification_probe.dart+.mjs, isolated loopback server,Browser.grantPermissions/Browser.setPermission,window.Notificationreplaced with a recording spy before load): all 25 checks passed — seed posted 0; one transition posted exactly 1 with titleA run failed, bodyNightly audit · nightlyand tag1:Failed@…; a dismissed transition posted 0; a reconnect replay posted 1 in total; denied and unsupported pages posted 0 and read their honest copy; all five tile states read correctly on Material and Cupertino at 320 logical px / 2x. Captures (copied topublic/captures/notify/):notification-transition-…,notification-denied-…,notification-unsupported-…andnotification-tile-{unsupported,insecure,default,granted,denied}-{material,cupertino}-dark-320-2x.png(13 PNGs).
One defect was found by the capture and fixed: putting the Enable action in a
ListTile trailing slot squeezed the section title to one glyph per line at
320 px / 2x, so the action now sits on its own row below the copy (as the
browser's settings section does), and the widget test guards it.
Deliberate limits
PARITY.md'sNotificationsrow is still Missing: this slice is a capability plus a reusable tile, not a delivered Settings section or shell wiring. The row should move when the manager embeds the tile and wires the controller, with authenticated smoke evidence.- The browser's in-session
pruneNotifiedis deliberately not reproduced: a prune would let an already-announced transition that is still in the caller's list post a second time. A run that leaves and re-enters the same qualifying state with an unchanged marker is therefore the same identity and does not notify twice — which is what the run+kind+marker rule requires. - A browser whose
Notification.requestPermission()uses the legacy callback-only form (no returned promise) falls back to the honest default wording, as the web client also does. - Mobile (Android/iOS) is unverified: the stub reports
unsupportedand no device or OS notification behaviour was exercised. Nopubspecchange.