id: NL-SPEC-C49F734E
type: spec
title: Notification surfaces and lifecycle
Notification surfaces and lifecycle
Outcome
Notifications form one coherent system across a bar widget, persistent popup history, and transient toasts.
Behavior
The widget exposes unread or active state without rendering a card.
The popup renders full cards grouped by application.
Toasts render compact cards on the primary screen when notifications arrive.
Reusing a protocol ID updates its history row and visible toast without duplication or reordering.
Transient notifications may appear as toasts but never enter history.
Invoking an action closes a non-resident notification; resident notifications remain.
Dismissing a toast preserves history; closing a card removes that notification.
clear all removes history and visible toasts.
dnd immediately removes and suppresses low and normal toasts.
Critical toasts bypass dnd and remain until dismissed.
SUPER+ESC dismisses every visible toast, including critical toasts, without deleting history.
Positive expiry uses the supplied duration, unspecified expiry uses five seconds, and zero is sticky.
Rendering
Full cards show the resolved application icon, application name, relative time, summary, wrapped body, optional image, and server actions.
Compact cards show the resolved icon, summary, urgency, and applicable progress or lifetime state.
Named icons use theme lookup; image paths and URLs render as images.
Critical urgency takes the error tint, unread notifications the accent, read normal ones stay neutral, and low urgency is subdued (owner decision 2026-11-14).
Full cards expose close, explicit copy, optional progress, and inline reply only when advertised.
User-facing labels are lowercase.
Drag-to-dismiss, debug metadata, cryptic count pills, and unused telemetry are absent.
Contracts and safety
Functional notification state exposes active toast rows separately from history; unused interface descriptors are not part of its contract.
Copying body text requires explicit user action.
Native notification references are released when neither history nor a toast needs them.
Destructive history clearing is button-only and has no implicit keyboard route.
Real notifications verify icons, wrapping, images, actions, replacement, expiry, critical persistence, and dnd.
Screenshots confirm full and compact layouts and lowercase labels.
Popup history scrolls, the shortcut dismisses toasts end to end, and runtime logs contain no QML errors.
---
id: NL-SPEC-C49F734E
type: spec
title: Notification surfaces and lifecycle
---
# Notification surfaces and lifecycle
## Outcome
Notifications form one coherent system across a bar widget, persistent popup history, and transient toasts.
## Behavior
- The widget exposes unread or active state without rendering a card.
- The popup renders full cards grouped by application.
- Toasts render compact cards on the primary screen when notifications arrive.
- Reusing a protocol ID updates its history row and visible toast without duplication or reordering.
- Transient notifications may appear as toasts but never enter history.
- Invoking an action closes a non-resident notification; resident notifications remain.
- Dismissing a toast preserves history; closing a card removes that notification.
- `clear all` removes history and visible toasts.
- `dnd` immediately removes and suppresses low and normal toasts.
- Critical toasts bypass `dnd` and remain until dismissed.
- `SUPER+ESC` dismisses every visible toast, including critical toasts, without deleting history.
- Positive expiry uses the supplied duration, unspecified expiry uses five seconds, and zero is sticky.
## Rendering
- Full cards show the resolved application icon, application name, relative time, summary, wrapped body, optional image, and server actions.
- Compact cards show the resolved icon, summary, urgency, and applicable progress or lifetime state.
- Named icons use theme lookup; image paths and URLs render as images.
- Critical urgency takes the error tint, unread notifications the accent, read normal ones stay neutral, and low urgency is subdued (owner decision 2026-11-14).
- Full cards expose close, explicit copy, optional progress, and inline reply only when advertised.
- User-facing labels are lowercase.
- Drag-to-dismiss, debug metadata, cryptic count pills, and unused telemetry are absent.
## Contracts and safety
- Functional notification state exposes active toast rows separately from history; unused interface descriptors are not part of its contract.
- Copying body text requires explicit user action.
- Native notification references are released when neither history nor a toast needs them.
- Destructive history clearing is button-only and has no implicit keyboard route.
## Acceptance
- Isolated checks cover replacement, read preservation, `dnd`, critical bypass, sticky timeout, transient exclusion, and toast dismissal.
- Real notifications verify icons, wrapping, images, actions, replacement, expiry, critical persistence, and `dnd`.
- Screenshots confirm full and compact layouts and lowercase labels.
- Popup history scrolls, the shortcut dismisses toasts end to end, and runtime logs contain no QML errors.