183 lines
11 KiB
Markdown
183 lines
11 KiB
Markdown
# 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; outside those
|
|
paths only this note, the notify tests and the isolated probe changed.
|
|
|
|
## What is there
|
|
|
|
| File | Lines | Role |
|
|
| --- | --- | --- |
|
|
| `notify/notification_models.dart` | 169 | 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` | 122 | run+kind identity, the qualifying-key set, ledger with pruning, 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` | 250 | the `ChangeNotifier` capability |
|
|
| `ui/notification_permission_tile.dart` | 127 | the reusable native tile |
|
|
| `tool/notification_probe.dart` / `.mjs` | 291 / 314 | 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, dedupe per qualifying state
|
|
|
|
The identity is the attention surface's own `{runId}:{Kind}` key, which is also
|
|
the browser's `alertKey` and therefore the coalescing `tag`:
|
|
|
|
- The initial list seed raises no transition, so `publishTransitions` over the
|
|
attention controller's (empty) transition list posts nothing.
|
|
- `publishTransitions(transitions, qualifying:, dismissed:)` receives
|
|
`notificationQualifyingKeys(attention.rows)` — the `{runId}:{Kind}` keys of the
|
|
runs that are failed or waiting *right now*. A transition whose key is not in
|
|
that set is stale (the caller's accumulated list still holds it because the run
|
|
has moved on), so it neither posts nor re-records anything.
|
|
- At the end of the publish, every recorded identity outside the qualifying set
|
|
is forgotten ([`NotificationLedger.pruning`]). Publishing the frame that
|
|
*leaves* the state is what makes the next gate (or a later failure of a new
|
|
run id) a new announcement.
|
|
This is the browser's `forget`/`pruneNotified` model.
|
|
- A waiting run has no `finished_at`, so a timestamp marker cannot separate its
|
|
first decision gate from a later one. The run+kind identity plus pruning can:
|
|
`waiting -> running -> waiting` notifies once per gate even though both
|
|
entries carry identical timestamps. A retry that produces a new failed run id
|
|
is likewise a new identity; a failed run id never returns to running.
|
|
- A caller that misses the frame that leaves the state is still handled: the
|
|
attention detector creates one transition instance per genuine transition, so
|
|
an identity announced earlier in this session with a different instance is a
|
|
new occurrence and notifies. Republishing the same instance stays silent.
|
|
- The same transition can never notify twice across a republish, a reconnect
|
|
reseed, or a controller rebuilt over the same store while the run still
|
|
qualifies. The ledger records the identity before the platform is asked to
|
|
show it and persists it under `pipelines.next.notify.v1` through the injectable
|
|
`NotificationStore`. A value written by the previous timestamp-identity build
|
|
stops matching the qualifying set and is dropped on the next publish, so no
|
|
migration step is needed.
|
|
- The ledger is bounded by the runs currently qualifying, not by the history of
|
|
every event the install has ever seen.
|
|
- Writes are serialized through one queued future, so an older snapshot can
|
|
never land after a newer one, and a throwing read/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.
|
|
- `notified` returns an unmodifiable copy, so a caller cannot mutate the ledger
|
|
behind the controller's back.
|
|
|
|
## Wiring the manager still owes
|
|
|
|
```dart
|
|
final notify = NotificationController(store: const SharedPreferencesNotificationStore());
|
|
notify.onOpenRun = (runId) { /* open that run — navigation lives here, not in notify */ };
|
|
await notify.load();
|
|
// after *every* authoritative read and pushed frame the attention controller handles:
|
|
notify.publishTransitions(
|
|
attention.transitions,
|
|
qualifying: notificationQualifyingKeys(attention.rows),
|
|
dismissed: attention.dismissed,
|
|
);
|
|
```
|
|
|
|
Publishing on the frames that leave a state matters as much as publishing the
|
|
one that entered it: that is when the old identity is forgotten. `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` — **147 passed** (12 more than before
|
|
this change; the notify/tile files hold 55). New coverage in this change: the
|
|
`waiting -> running -> waiting` second gate with the real waiting shape (empty
|
|
`finished_at`) notifies again, with and without publishing the leaving frame;
|
|
a coalesced backlog of two gates notifies once; a stale transition from a run
|
|
that left is not re-posted; the identity is run+kind so two alerts of one run
|
|
share the browser tag; pruning drops identities outside the qualifying set;
|
|
old timestamped identities are dropped; `notificationQualifyingKeys` ignores
|
|
export waits, malformed ids and duplicates; `notified` is unmodifiable; ledger
|
|
writes are serialized in call order.
|
|
- `flutter test` (whole app) — **1058 passed**.
|
|
- `flutter analyze` — **No issues found** (whole project).
|
|
- `dart format --output=none --set-exit-if-changed` on every new lib/test file —
|
|
clean.
|
|
- `flutter build web` (the real `lib/main.dart`) — **succeeded**. This does *not*
|
|
compile the notify feature: nothing under `lib/` imports it yet, so the main
|
|
bundle contains none of its strings. It is a sanity check for the app only.
|
|
- `flutter build web -t tool/notification_probe.dart -o build/notification_probe_web`
|
|
— **succeeded**. This is the build that compiles the conditional-import web
|
|
bridge (`isSecureContext`, the alert copy and the real `Notification` seam are
|
|
in this bundle).
|
|
- 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 29 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; a second
|
|
decision gate posted exactly 2 in total, both tag `7:Decision`, with the
|
|
waiting frames carrying no `finished_at`; 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.
|
|
- 13 PNG captures regenerated in
|
|
`/Users/alan/.local/share/pipelines/data/artifacts/100/public/captures/notify/`
|
|
(`notification-transition-…`, `notification-denied-…`,
|
|
`notification-unsupported-…`, and
|
|
`notification-tile-{unsupported,insecure,default,granted,denied}-{material,cupertino}-dark-320-2x.png`).
|
|
|
|
One UI defect was found by the first captures and fixed in the previous visit:
|
|
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 instance rule is session-local. A controller rebuilt over the same store
|
|
can only distinguish a later gate if the frame that left the state was
|
|
published (which prunes the old identity), so the wiring above still publishes
|
|
every authoritative read and frame rather than only entering transitions.
|
|
- 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.
|
|
- The tile is not registered in Settings and background chat-question notices
|
|
(`web/src/app.js` `notifyChatQuestion`) are not part of this capability.
|
|
|
|
## Manager completion after the Code deadline
|
|
|
|
The run succeeded at Code, was rejected once at Review, and the retry hit the
|
|
30-minute deadline. The retained tree is complete: 147 attention tests pass and
|
|
analysis is clean. Merged directly. Shell wiring (permission tile in Settings and
|
|
transition delivery from the Runs attention controller) is the manager's next
|
|
step and is not claimed here.
|