Files
pipelines/app/notes/A2-notify.md
T
alan 7718604268 feat(app): add the notification capability behind a platform seam
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.
2026-10-22 01:23:24 +01:00

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 publishTransitions over the attention controller's (empty) transition list posts nothing.
  • The dedupe identity is {runId}:{Kind}@{marker} where the marker is the run's trimmed finished_at else created_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.v1 through the injectable NotificationStore. publishTransitions is 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) and label · pipeline, matching web/src/notify.js and RunAlerts.kt verbatim. Nothing is invented, and no stage field 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 real lib/main.dart) — succeeded.
  • Real-browser probe (tool/notification_probe.dart + .mjs, isolated loopback server, Browser.grantPermissions / Browser.setPermission, window.Notification replaced with a recording spy before load): all 25 checks passed — seed posted 0; one transition posted exactly 1 with title A run failed, body Nightly audit · nightly and tag 1: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 to public/captures/notify/): notification-transition-…, notification-denied-…, notification-unsupported-… and notification-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's Notifications row 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 pruneNotified is 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 unsupported and no device or OS notification behaviour was exercised. No pubspec change.