---
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 is destructive, normal urgency is accented, and low urgency is subdued.
- 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

- Notification state remains additive and exposes active toast rows separately from history.
- 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.