@quazardous/qdadm 2.26.1 → 2.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.26.1",
+  "version": "2.28.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/components/show/ShowPage.vue

@@ -36,7 +36,8 @@
  * - #footer: Custom footer (replaces ShowActions if provided)
  * - #error: Custom error display
  * - #loading: Custom display for the first load. A reload of a record already
- *   on screen keeps it there, marked busy (#2435).
+ *   on screen keeps it there, marked busy (#2435); the notification badge shows
+ *   the activity (#2677).
  */
 import { computed, type PropType } from 'vue'
 import PageHeader from '../layout/PageHeader.vue'
@@ -227,7 +228,6 @@ type ShowFieldValue = string | number | boolean | Date | Record<string, unknown>
 
     <!-- Content -->
     <template v-else>
-      <div v-if="loading" class="show-refreshing" role="progressbar" aria-label="Refreshing" />
       <!-- Single content body; Card wrapper is conditional (#1193) -->
       <CardShell :card="cardWrapper">
         <!-- Grid layout with optional media zone -->
@@ -310,28 +310,7 @@ type ShowFieldValue = string | number | boolean | Date | Record<string, unknown>
   padding: 3rem;
 }
 
-/* A record being refreshed stays on screen: a thin bar says so (#2435). */
-.show-refreshing {
-  height: 3px;
-  margin-bottom: -1rem; /* inside the page gap: the content does not move */
-  background: linear-gradient(90deg, transparent, var(--p-primary-color, #3b82f6), transparent);
-  background-size: 40% 100%;
-  background-repeat: no-repeat;
-  animation: show-refreshing 1.1s ease-in-out infinite;
-}
-
-@keyframes show-refreshing {
-  from { background-position: -40% 0; }
-  to { background-position: 140% 0; }
-}
 
-@media (prefers-reduced-motion: reduce) {
-  .show-refreshing {
-    animation: none;
-    background: var(--p-primary-color, #3b82f6);
-    opacity: 0.4;
-  }
-}
 
 .show-error-message {
   margin: 1rem 0;

package/src/composables/useEntityItemFormPage.ts

@@ -37,6 +37,7 @@ import {
 } from './useEntityItemPage'
 import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
 import { registerPageState } from './usePageState'
+import { useNotifications } from '../notifications/NotificationStore'
 import { deepClone } from '../utils/transformers'
 import { getSiblingRoutes } from '../module/moduleRegistry'
 import {
@@ -130,6 +131,8 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
   const route = useRoute()
   const confirm = useConfirm() as ConfirmService
   const debug = inject<boolean>('qdadmDebug', false)
+  // Loads show as activity on the notification badge (#2677); a no-op without notifications.
+  const notifications = useNotifications()
 
   // Use useEntityItemPage for common infrastructure
   const itemPage = useEntityItemPage({
@@ -273,7 +276,14 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
     }
   }
 
+  // Only the latest load may write (#2666): moving quickly between records, a
+  // slow answer for the previous one would otherwise land in this record's form.
+  let loadSeq = 0
+
   async function load(): Promise<void> {
+    const seq = ++loadSeq
+    const isLatest = (): boolean => seq === loadSeq
+
     if (!isEdit.value) {
       data.value = deepClone(initialData) as T
       takeSnapshot()
@@ -284,7 +294,8 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
     try {
       // The item itself, never a cached list row: a list row may be a summary,
       // and whatever this form shows empty it saves back empty (#2484).
-      const responseData = await manager.get(entityId.value!, undefined, { listCache: false })
+      const responseData = await notifications.track(manager.get(entityId.value!, undefined, { listCache: false }))
+      if (!isLatest()) return
       const transformed = transformLoad(responseData)
       if (debug) reportMissingFields(transformed as Record<string, unknown>)
       data.value = transformed as T
@@ -298,6 +309,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
         await onLoadSuccess(transformed as T)
       }
     } catch (error) {
+      if (!isLatest()) return
       const axiosError = error as AxiosError
       toast.add({
         severity: 'error',
@@ -306,7 +318,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
         life: 5000,
       })
     } finally {
-      loading.value = false
+      if (isLatest()) loading.value = false
     }
   }
 

package/src/composables/useEntityItemPage.ts

@@ -15,6 +15,7 @@
 import { ref, computed, onMounted, provide, type Ref, type ComputedRef } from 'vue'
 import { useRoute } from 'vue-router'
 import { useStackHydrator, type StackHydratorReturn } from '../chain/useStackHydrator'
+import { useNotifications } from '../notifications/NotificationStore'
 import type { EntityManagerCrud } from '../entity/EntityManager.interface'
 import type { OrchestratorLike } from '../entity/EntityManager.interface'
 import { useOrchestrator } from '../orchestrator/useOrchestrator.js'
@@ -161,6 +162,8 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
 
   // Stack hydrator for setting entity data on navigation context
   const hydrator = useStackHydrator()
+  // Loads show as activity on the notification badge (#2677); a no-op without notifications.
+  const notifications = useNotifications()
 
   // ============ STATE ============
 
@@ -315,7 +318,15 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
    * @param id - Optional ID override (defaults to route param)
    * @returns Loaded entity data or null on error
    */
+  let loadSeq = 0
+
   async function load(id: string | number | null = entityId.value): Promise<T | null> {
+    // Only the latest call may write (#2666). Live reloads and id changes can
+    // overlap; an older answer landing last would put a past state on screen.
+    // A superseded call resolves to null and touches nothing.
+    const seq = ++loadSeq
+    const isLatest = (): boolean => seq === loadSeq
+
     if (!id) {
       error.value = 'No entity ID provided'
       return null
@@ -325,7 +336,8 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
     error.value = null
 
     try {
-      const responseData = await manager.get(id)
+      const responseData = await notifications.track(manager.get(id))
+      if (!isLatest()) return null
 
       if (!responseData) {
         error.value = `${manager.label || entity} not found`
@@ -344,6 +356,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
 
       return transformed
     } catch (err) {
+      if (!isLatest()) return null
       console.error(`[useEntityItemPage] Failed to load ${entity}:`, err)
       const axiosError = err as { response?: { data?: { detail?: string } }; message?: string }
       error.value =
@@ -357,7 +370,7 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
 
       return null
     } finally {
-      loading.value = false
+      if (isLatest()) loading.value = false
     }
   }
 

package/src/composables/useEntityItemShowPage.ts

@@ -35,7 +35,8 @@
  */
 import { ref, computed, onUnmounted, type Ref, type ComputedRef } from 'vue'
 import { registerPageState } from './usePageState'
-import { useRouter, type Router } from 'vue-router'
+import { useRouter, useRoute, type Router } from 'vue-router'
+import { useNotifications } from '../notifications/NotificationStore'
 import { useConfirm } from 'primevue/useconfirm'
 import { requireDeleteConfirmation } from './confirmDelete'
 import {
@@ -325,8 +326,20 @@ export function useEntityItemShowPage<T = Record<string, unknown>>(
   // Reload when THIS record changed outside the session (#1888 lot D).
   // Scoped by id: an event about another record must not reload every open
   // detail page. An event carrying no id concerns the whole entity and applies.
+  const notifications = useNotifications()
+  const route = useRoute()
   useLiveEntity(entity, manager, async () => {
-    await base.reload()
+    const record = await base.reload()
+    // A change made elsewhere to the record on screen leaves a line in the
+    // history (#2677): short-lived, linked back to it, never a pop-up.
+    if (!record) return
+    const name = entityLabel.value ? `"${entityLabel.value}"` : `#${entityId.value}`
+    notifications.addNotification({
+      severity: 'info',
+      summary: `${manager.label ?? entity} ${name} updated elsewhere`,
+      keep: 'short',
+      ...(route?.name ? { to: { name: String(route.name), params: { ...route.params } } } : {}),
+    })
   }, { id: () => entityId.value })
   // Cast orchestrator to include toast methods
   const orchestrator = baseOrchestrator as Orchestrator

package/src/composables/useListPage.ts

@@ -38,6 +38,7 @@ import {
 import { useConfirm } from 'primevue/useconfirm'
 import { requireDeleteConfirmation } from './confirmDelete'
 import { registerPageState, activeFilters } from './usePageState'
+import { useNotifications } from '../notifications/NotificationStore'
 import { useHooks } from './useHooks.js'
 import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } from './useEntityItemPage.js'
 import { useActiveStack } from '../chain/useActiveStack.js'
@@ -142,6 +143,8 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
 
   const router = useRouter()
   const route = useRoute()
+  // Loads show as activity on the notification badge (#2677); a no-op without notifications.
+  const notifications = useNotifications()
   const confirm = useConfirm() as ConfirmService
 
   // Mobile detection (viewport width < 768px)
@@ -841,9 +844,12 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
         params = onBeforeLoad(params) || params
       }
 
-      const response = manager.query
-        ? await manager.query(params, { routingContext: entityContext.value })
-        : await manager.list(params, entityContext.value)
+      // The request shows as activity on the notification badge (#2677).
+      const response = await notifications.track(
+        manager.query
+          ? manager.query(params, { routingContext: entityContext.value })
+          : manager.list(params, entityContext.value)
+      )
 
       fromCache.value = response.fromCache || false
 

package/src/composables/useLiveEntity.ts

@@ -15,8 +15,11 @@
  * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
  */
 
-import { inject, onUnmounted } from 'vue'
+import { inject, onUnmounted, watch } from 'vue'
 import type { SignalBus } from '../kernel/SignalBus'
+import { useApiClient } from '../api/apiClient'
+import type { HttpClient } from '../entity/storage/ApiStorage'
+import { SSE_SUBSCRIPTIONS_KEY, type SseSubscriptions } from '../kernel/sseSubscriptions'
 
 export interface UseLiveEntityOptions {
   /**
@@ -37,7 +40,8 @@ interface LivePolicy {
  *
  * @param entityName - entity to watch
  * @param manager - its manager, read for the `live` policy (may be null)
- * @param reload - what to run; coalesced, never called concurrently by us
+ * @param reload - what to run; coalesced, and never called while a previous
+ *   call's promise is still pending — changes arriving meanwhile cause one more call
  * @returns unsubscribe function (also called automatically on unmount)
  */
 export function useLiveEntity(
@@ -60,10 +64,44 @@ export function useLiveEntity(
   let timer: ReturnType<typeof setTimeout> | null = null
   let disposed = false
 
+  // Never two reloads at once (#2666), as this composable promises: an event
+  // arriving while one is in flight marks it dirty, and exactly one more runs
+  // when it settles — no overlapping requests, and the last state lands.
+  let inFlight = false
+  let dirty = false
+
+  const settle = (): void => {
+    inFlight = false
+    if (dirty && !disposed) {
+      dirty = false
+      run()
+    }
+  }
+
+  // Only a reload that returns a promise is in flight: a synchronous one is done
+  // when it returns. A failure — thrown or rejected — must not stop the next one;
+  // the page reports its own load errors.
+  const run = (): void => {
+    let result: void | Promise<void>
+    try {
+      result = reload()
+    } catch {
+      return
+    }
+    if (result && typeof (result as Promise<void>).then === 'function') {
+      inFlight = true
+      ;(result as Promise<void>).then(settle, settle)
+    }
+  }
+
   const fire = (): void => {
     timer = null
     if (disposed) return
-    void reload()
+    if (inFlight) {
+      dirty = true
+      return
+    }
+    run()
   }
 
   const off = signals.on('entity:data-invalidate', (event: { name: string; data: unknown }) => {
@@ -100,6 +138,15 @@ export function useLiveEntity(
     timer = setTimeout(fire, coalesceMs)
   })
 
+  // Per-record subscription (#2664): a detail page asks the backend to send
+  // this record's changes to this tab, for as long as it shows the record.
+  const subscriptions = inject<SseSubscriptions | null>(SSE_SUBSCRIPTIONS_KEY, null)
+  const apiClient = subscriptions && options.id ? useApiClient() : null
+  const stopSubscription =
+    subscriptions && apiClient && options.id
+      ? followRecord(subscriptions, apiClient, entityName, options.id, inject<boolean>('qdadmDebug', false))
+      : () => {}
+
   const stop = (): void => {
     disposed = true
     if (timer) {
@@ -107,9 +154,84 @@ export function useLiveEntity(
       timer = null
     }
     off()
+    stopSubscription()
   }
 
   onUnmounted(stop)
 
   return stop
 }
+
+/**
+ * Keep a subscription to the record `id()` points at: POST when it is shown,
+ * renew at half of `expires_in`, DELETE when it changes or the page leaves.
+ *
+ * Never throws into the page — without a subscription the page still works, it
+ * just does not hear about changes. Failures are said in debug mode only.
+ */
+function followRecord(
+  subscriptions: SseSubscriptions,
+  api: HttpClient,
+  entity: string,
+  id: () => string | number | null | undefined,
+  debug: boolean
+): () => void {
+  let current: string | null = null
+  let renewTimer: ReturnType<typeof setTimeout> | null = null
+  let stopped = false
+
+  const body = (recordId: string) => ({ session: subscriptions.session, entity, id: recordId })
+
+  const report = (what: string, recordId: string, error: unknown): void => {
+    if (!debug) return
+    const status = (error as { response?: { status?: number } })?.response?.status
+    const reason = status ?? (error as { message?: string })?.message ?? String(error)
+    console.warn(`[qdadm] live subscription ${what} failed for ${entity} #${recordId} (${reason}) — the page will not update on its own`)
+  }
+
+  const clearRenewal = (): void => {
+    if (renewTimer) clearTimeout(renewTimer)
+    renewTimer = null
+  }
+
+  const subscribe = async (recordId: string, retryAfterMs: number | null = null): Promise<void> => {
+    try {
+      const { data } = await api.post<{ expires_in?: number }>(subscriptions.url, body(recordId))
+      if (stopped || current !== recordId) return
+      const seconds = Number(data?.expires_in)
+      if (seconds > 0) renewTimer = setTimeout(() => void subscribe(recordId, (seconds * 1000) / 2), (seconds * 1000) / 2)
+    } catch (error) {
+      report('subscribe', recordId, error)
+      // A renewal that fails is tried again at the same pace: the subscription is about to lapse.
+      if (!stopped && current === recordId && retryAfterMs) {
+        renewTimer = setTimeout(() => void subscribe(recordId, retryAfterMs), retryAfterMs)
+      }
+    }
+  }
+
+  const unsubscribe = (recordId: string): void => {
+    api
+      .request({ method: 'DELETE', url: subscriptions.url, data: body(recordId) })
+      .catch((error: unknown) => report('unsubscribe', recordId, error))
+  }
+
+  const follow = (raw: string | number | null | undefined): void => {
+    const next = raw == null || raw === '' ? null : String(raw)
+    if (next === current) return
+    clearRenewal()
+    if (current) unsubscribe(current)
+    current = next
+    if (next) void subscribe(next)
+  }
+
+  const stopWatch = watch(id, follow, { immediate: true })
+
+  return () => {
+    if (stopped) return
+    stopped = true
+    stopWatch()
+    clearRenewal()
+    if (current) unsubscribe(current)
+    current = null
+  }
+}

package/src/kernel/Kernel.registries.ts

@@ -16,6 +16,7 @@ import { Orchestrator } from '../orchestrator/Orchestrator'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { Kernel } from './Kernel'
 import type { SSEConfig } from './Kernel.types'
+import { sseTabSession, withQueryParam } from './sseSubscriptions'
 // #1196 Phase B — this-typing against the real Kernel shape (was Self = any)
 type Self = Kernel
 
@@ -447,6 +448,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
         'getToken',
         'connectOnSignal',
         'disconnectOnSignal',
+        'subscriptions',
       ]),
       {
         getToken:
@@ -454,6 +456,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
           'and query strings reach access logs',
         entities: 'no entity cache will be invalidated from the stream',
         tokenParam: 'the token will be sent under the default name "token"',
+        subscriptions: 'detail pages will not subscribe to their record, and the stream carries no tab session',
       }
     )
   }
@@ -466,6 +469,16 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     this._validateSseConfig(sse)
 
+    // Per-record subscriptions (#2664): the tab id is minted here and put in
+    // the stream URL, so the one the pages subscribe with is the same.
+    let url = sse.url
+    this.sseSubscriptions = null
+    if (sse.subscriptions?.url) {
+      const session = sseTabSession()
+      this.sseSubscriptions = { url: sse.subscriptions.url, session }
+      url = withQueryParam(url, sse.subscriptions.sessionParam ?? 'session', session)
+    }
+
     // An explicit sse.getToken wins — including an explicit null, which means
     // "send no token" and must not fall back to the auth adapter.
     const getToken =
@@ -477,7 +490,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     this.sseBridge = createSSEBridge({
       signals: this.signals!,
-      url: sse.url,
+      url,
       reconnectDelay: sse.reconnectDelay ?? 5000,
       signalPrefix: sse.signalPrefix ?? 'sse',
       autoConnect: sse.autoConnect ?? false,

package/src/kernel/Kernel.ts

@@ -80,6 +80,7 @@ import { isDebugBarKilled } from './debugBarKillSwitch'
 import { applyApiMethods } from './Kernel.api'
 import { applyI18nMethods } from './Kernel.i18n'
 import type { I18n } from '../i18n/I18n'
+import type { SseSubscriptions } from './sseSubscriptions'
 
 export class Kernel {
   options: KernelOptions
@@ -101,6 +102,8 @@ export class Kernel {
   deferred!: DeferredRegistry
   eventRouter: EventRouter | null = null
   sseBridge: SSEBridge | null = null
+  /** Where detail pages subscribe to their record, and as which tab (#2664). Null without `sse.subscriptions`. */
+  sseSubscriptions: SseSubscriptions | null = null
   /** Routes external entity changes to cache invalidation (#1888). */
   liveEntityRouter: LiveEntityRouter | null = null
   layoutComponents: InternalLayoutComponents | null = null

package/src/kernel/Kernel.types.ts

@@ -135,6 +135,23 @@ export interface SSEConfig {
    * See docs/adr/0009-live-entities.md.
    */
   entities?: string[] | true | '*'
+  /**
+   * Per-record subscriptions (#2664): a detail page tells the backend which
+   * record it shows, so the stream carries that record's changes to this tab.
+   *
+   * `url` receives `POST {session, entity, id}` when a detail page shows a
+   * record, answering `{expires_in}` (seconds); qdadm renews at half of it, and
+   * sends `DELETE` with the same body when the page leaves the record. Calls go
+   * through the kernel's `apiClient`, with the app's own auth.
+   *
+   * `session` is a per-tab id qdadm mints and also appends to the stream URL as
+   * `sessionParam` (default `'session'`): the stream and the subscriptions name
+   * the same tab. Do not put your own session parameter in `url`.
+   *
+   * The entity must be declared in `entities`, or its frames are dropped before
+   * any page sees them. Absent: no subscription, no session parameter.
+   */
+  subscriptions?: { url: string; sessionParam?: string }
   /**
    * Token appended to the SSE URL as a query parameter.
    *
@@ -182,6 +199,10 @@ export interface DebugBarConfig {
 export interface NotificationsConfig {
   enabled?: boolean
   maxNotifications?: number
+  /** Keep level per severity (#2677). Default: success and info `short`, warn and error `long`. */
+  keep?: Partial<Record<'success' | 'info' | 'warn' | 'error', 'none' | 'short' | 'long'>>
+  /** How long a `short` entry stays in the list, in ms. Default 5 minutes. */
+  shortKeepMs?: number
 }
 
 /**

package/src/kernel/Kernel.vue.ts

@@ -334,6 +334,8 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
 
     if (this.sseBridge) {
       app.provide('qdadmSSEBridge', this.sseBridge)
+      // Detail pages subscribe to their record through this (#2664); null without sse.subscriptions.
+      app.provide('qdadmSSESubscriptions', this.sseSubscriptions)
     }
 
     app.provide('qdadmHooks', this.hookRegistry)
@@ -357,6 +359,8 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
     if (this.options.notifications?.enabled) {
       this.notificationStore = createNotificationStore({
         maxNotifications: this.options.notifications.maxNotifications,
+        keep: this.options.notifications.keep,
+        shortKeepMs: this.options.notifications.shortKeepMs,
       })
       app.provide(NOTIFICATION_KEY, this.notificationStore)
     }

package/src/kernel/sseSubscriptions.ts

@@ -0,0 +1,54 @@
+/**
+ * Per-record SSE subscriptions (#2664) — the tab's identity, shared by the
+ * stream and the subscription calls.
+ *
+ * A detail page tells the backend which record it shows, so the stream carries
+ * that record's changes to this tab only. The backend has to know which stream
+ * a subscription belongs to, and the only thing both sides can name is the
+ * tab: qdadm mints one id per browser tab, appends it to the stream URL, and
+ * sends the same id with every subscription. One owner, so the two cannot
+ * disagree.
+ */
+
+/** What the kernel hands to `useLiveEntity`: where to subscribe, and as which tab. */
+export interface SseSubscriptions {
+  url: string
+  session: string
+}
+
+/** Injection key under which the kernel provides `SseSubscriptions` (or null). */
+export const SSE_SUBSCRIPTIONS_KEY = 'qdadmSSESubscriptions'
+
+const TAB_SESSION_KEY = 'qdadm:sse-session'
+
+function mintId(): string {
+  // randomUUID only exists in secure contexts; a plain-http deployment still needs an id.
+  const c = typeof crypto !== 'undefined' ? crypto : null
+  if (c && typeof c.randomUUID === 'function') return c.randomUUID()
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`
+}
+
+/**
+ * This tab's id: kept in sessionStorage, so a reload is the same tab and a new
+ * tab is a new one. Storage that throws (blocked site data) still yields an id,
+ * valid for this page load.
+ */
+export function sseTabSession(): string {
+  try {
+    const existing = window.sessionStorage.getItem(TAB_SESSION_KEY)
+    if (existing) return existing
+    const id = mintId()
+    window.sessionStorage.setItem(TAB_SESSION_KEY, id)
+    return id
+  } catch {
+    return mintId()
+  }
+}
+
+/** `url` with `name=value` added to its query string, before any fragment. */
+export function withQueryParam(url: string, name: string, value: string): string {
+  const [base, fragment] = url.split('#', 2)
+  const param = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+  const joined = `${base}${base!.includes('?') ? '&' : '?'}${param}`
+  return fragment === undefined ? joined : `${joined}#${fragment}`
+}

package/src/notifications/NotificationBadge.vue

@@ -2,23 +2,35 @@
 /**
  * NotificationBadge - Clickable overlay for the sidebar footer logo
  *
- * Always rendered as a transparent click zone over the logo.
- * When there are alerts, the parent layout applies an opacity blink
- * on the logo wrapper via :has(.notification-badge-zone--alert).
+ * Always rendered as a transparent click zone over the logo. It says three
+ * things (#2677):
+ * - something needs attention: the parent layout blinks the logo via
+ *   :has(.notification-badge-zone--alert);
+ * - how many entries are unread: a count;
+ * - work is in progress: a ring, once tracked work has lasted `activityDelayMs`.
  *
  * Click toggles the notification panel open/close.
  */
+import { computed } from 'vue'
 import { useNotifications } from './NotificationStore'
 
 const store = useNotifications()
+
+const unread = computed(() => store.unreadCount.value)
+const unreadLabel = computed(() => (unread.value > 99 ? '99+' : String(unread.value)))
 </script>
 
 <template>
   <div
     class="notification-badge-zone"
-    :class="{ 'notification-badge-zone--alert': store.hasAlert.value || store.unreadCount.value > 0 }"
+    :class="{ 'notification-badge-zone--alert': store.hasAlert.value || unread > 0 }"
+    role="button"
+    :aria-label="unread > 0 ? `Notifications, ${unread} unread` : 'Notifications'"
     @click.stop.prevent="store.toggle()"
-  />
+  >
+    <span v-if="store.isBusy.value" class="notification-badge-ring" role="progressbar" aria-label="Loading" />
+    <span v-if="unread > 0" class="notification-badge-count">{{ unreadLabel }}</span>
+  </div>
 </template>
 
 <style scoped>
@@ -32,4 +44,45 @@ const store = useNotifications()
   cursor: pointer;
   z-index: 1;
 }
+
+.notification-badge-count {
+  position: absolute;
+  top: -0.35rem;
+  right: -0.35rem;
+  min-width: 1.1rem;
+  height: 1.1rem;
+  padding: 0 0.3rem;
+  border-radius: 999px;
+  background: var(--p-primary-color, #3b82f6);
+  color: var(--p-primary-contrast-color, #fff);
+  font-size: 0.65rem;
+  font-weight: 600;
+  line-height: 1.1rem;
+  text-align: center;
+  pointer-events: none;
+}
+
+/* Work in progress: a ring around the logo. */
+.notification-badge-ring {
+  position: absolute;
+  inset: -0.25rem;
+  border-radius: 50%;
+  border: 2px solid transparent;
+  border-top-color: var(--p-primary-color, #3b82f6);
+  border-right-color: var(--p-primary-color, #3b82f6);
+  animation: notification-badge-spin 0.9s linear infinite;
+  pointer-events: none;
+}
+
+@keyframes notification-badge-spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .notification-badge-ring {
+    animation: none;
+    border-color: var(--p-primary-color, #3b82f6);
+    opacity: 0.5;
+  }
+}
 </style>

package/src/notifications/NotificationModule.ts

@@ -2,14 +2,13 @@
  * NotificationModule - Optional notification panel system
  *
  * When loaded, this module:
- * - Replaces the default ToastListener with NotificationListener
- *   (captures toasts to notification store instead of ephemeral PrimeVue toasts)
  * - Registers NotificationBadge for the sidebar footer logo overlay
  * - Registers NotificationPanel zone for the panel component
  *
- * Without this module, classic toast behavior is unchanged (ToastBridgeModule).
- * With this module, toasts are captured. Use `forceToast: true` in signal data
- * to also show a classic PrimeVue toast.
+ * Toasts keep showing as pop-ups; the kernel's ToastListener also records each
+ * one in the store, for as long as its keep level says (#2677). This module used
+ * to swap the listener inside the `_app:toasts` zone, which nothing renders — so
+ * no toast was ever recorded. See docs/notifications.md.
  *
  * @example
  * // In kernel config
@@ -20,8 +19,6 @@
 
 import { Module } from '../kernel/Module'
 import type { KernelContext } from '../kernel/KernelContext'
-import { TOAST_ZONE } from '../toast/ToastBridgeModule'
-import NotificationListener from './NotificationListener.vue'
 import NotificationBadge from './NotificationBadge.vue'
 import NotificationPanel from './NotificationPanel.vue'
 
@@ -45,18 +42,6 @@ export class NotificationModule extends Module {
     ctx.zone(NOTIFICATION_BADGE_ZONE)
     ctx.zone(NOTIFICATION_STATUS_ZONE)
 
-    // Replace the toast-listener block in the toast zone with our NotificationListener.
-    // This intercepts toast signals and captures them to the notification store.
-    // The toast zone is defined by ToastBridgeModule - we replace its listener block.
-    ctx.zone(TOAST_ZONE) // Ensure the zone exists
-    ctx.block(TOAST_ZONE, {
-      id: 'toast-listener',
-      component: NotificationListener,
-      weight: 0,
-      operation: 'replace',
-      replaces: 'toast-listener',
-    })
-
     // Register badge component for sidebar footer overlay
     ctx.block(NOTIFICATION_BADGE_ZONE, {
       id: 'notification-badge',

package/src/notifications/NotificationPanel.vue

@@ -13,11 +13,21 @@
  * - Notification list (most recent first)
  * - Empty state
  */
-import { RouterLink } from 'vue-router'
+import { RouterLink, useRouter, type RouteLocationRaw } from 'vue-router'
 import { useNotifications } from './NotificationStore'
-import type { NotificationSeverity } from './NotificationStore'
+import type { Notification, NotificationSeverity } from './NotificationStore'
 
 const store = useNotifications()
+const router = useRouter()
+
+/** An entry is read when clicked; one with a `to` also takes the user there (#2677). */
+function openNotification(notif: Notification): void {
+  store.markRead(notif.id)
+  if (!notif.to) return
+  store.close()
+  // NotificationTarget mirrors StatusItem.to: a vue-router location, typed loosely for app code.
+  void router.push(notif.to as RouteLocationRaw)
+}
 
 const severityIcons: Record<NotificationSeverity, string> = {
   success: 'pi pi-check-circle',
@@ -113,9 +123,11 @@ function formatTime(timestamp: number): string {
           class="notification-item"
           :class="{
             'notification-item--unread': !notif.read,
+            'notification-item--link': !!notif.to,
             [`notification-item--${notif.severity}`]: true,
           }"
-          @click="store.markRead(notif.id)"
+          :role="notif.to ? 'link' : undefined"
+          @click="openNotification(notif)"
         >
           <div class="notification-item-icon">
             <i :class="severityIcons[notif.severity]" />

package/src/notifications/NotificationStore.ts

@@ -34,6 +34,16 @@ const NOTIFICATION_KEY: InjectionKey<NotificationStore> = Symbol('qdadm-notifica
 
 export type NotificationSeverity = 'success' | 'info' | 'warn' | 'error'
 
+/**
+ * How long an entry stays in the list (#2677): `none` is not recorded, `short`
+ * is dropped after `shortKeepMs` (read or not), `long` stays until cleared or
+ * pushed out by the cap.
+ */
+export type NotificationKeep = 'none' | 'short' | 'long'
+
+/** Where an entry leads when clicked: a vue-router location. */
+export type NotificationTarget = { name: string; params?: Record<string, unknown>; query?: Record<string, unknown> } | string
+
 export interface Notification {
   id: string
   severity: NotificationSeverity
@@ -42,6 +52,20 @@ export interface Notification {
   emitter?: string
   timestamp: number
   read: boolean
+  keep: Exclude<NotificationKeep, 'none'>
+  /** When a `short` entry leaves the list; null for `long`. */
+  expiresAt: number | null
+  to?: NotificationTarget
+}
+
+/** What `addNotification` takes: `keep` defaults by severity, see `NotificationStoreConfig.keep`. */
+export interface NewNotification {
+  severity: NotificationSeverity
+  summary: string
+  detail?: string
+  emitter?: string
+  keep?: NotificationKeep
+  to?: NotificationTarget
 }
 
 export interface StatusItem {
@@ -56,6 +80,19 @@ export interface StatusItem {
 
 export interface NotificationStoreConfig {
   maxNotifications?: number
+  /** Keep level per severity. Default: success and info `short`, warn and error `long`. */
+  keep?: Partial<Record<NotificationSeverity, NotificationKeep>>
+  /** How long a `short` entry stays, in ms. Default 5 minutes. */
+  shortKeepMs?: number
+  /** Ongoing activity shorter than this shows nothing on the badge, in ms. Default 400. */
+  activityDelayMs?: number
+}
+
+const DEFAULT_KEEP: Record<NotificationSeverity, NotificationKeep> = {
+  success: 'short',
+  info: 'short',
+  warn: 'long',
+  error: 'long',
 }
 
 export interface NotificationStore {
@@ -63,7 +100,8 @@ export interface NotificationStore {
   notifications: ComputedRef<Notification[]>
   unreadCount: ComputedRef<number>
   hasAlert: ComputedRef<boolean>
-  addNotification(n: Omit<Notification, 'id' | 'timestamp' | 'read'>): string
+  /** Records an entry and returns its id — `''` when its keep level is `none`. */
+  addNotification(n: NewNotification): string
   markRead(id: string): void
   markAllRead(): void
   removeNotification(id: string): void
@@ -75,6 +113,12 @@ export interface NotificationStore {
   updateStatus(id: string, updates: Partial<StatusItem>): void
   removeStatus(id: string): void
 
+  // Activity (#2677)
+  /** Counts `work` as in progress until it settles, and returns it unchanged. */
+  track<T>(work: Promise<T>): Promise<T>
+  /** True once tracked work has been in progress for `activityDelayMs`. */
+  isBusy: ComputedRef<boolean>
+
   // Panel state
   isOpen: Ref<boolean>
   open(): void
@@ -102,6 +146,9 @@ let _idCounter = 0
  */
 export function createNotificationStore(config: NotificationStoreConfig = {}): NotificationStore {
   const maxNotifications = config.maxNotifications ?? 50
+  const keepBySeverity = { ...DEFAULT_KEEP, ...(config.keep ?? {}) }
+  const shortKeepMs = config.shortKeepMs ?? 5 * 60 * 1000
+  const activityDelayMs = config.activityDelayMs ?? 400
 
   const state = reactive<NotificationState>({
     notifications: [],
@@ -112,13 +159,46 @@ export function createNotificationStore(config: NotificationStoreConfig = {}): N
 
   // ── Notifications ──────────────────────────────────────────────────────
 
-  function addNotification(n: Omit<Notification, 'id' | 'timestamp' | 'read'>): string {
+  // A `short` entry leaves when it expires; one timer, set for the soonest.
+  let pruneTimer: ReturnType<typeof setTimeout> | null = null
+
+  function schedulePrune(): void {
+    if (pruneTimer) clearTimeout(pruneTimer)
+    pruneTimer = null
+    const soonest = state.notifications.reduce<number | null>(
+      (min, n) => (n.expiresAt !== null && (min === null || n.expiresAt < min) ? n.expiresAt : min),
+      null
+    )
+    if (soonest === null) return
+    pruneTimer = setTimeout(prune, Math.max(0, soonest - Date.now()))
+  }
+
+  function prune(): void {
+    const now = Date.now()
+    for (let i = state.notifications.length - 1; i >= 0; i--) {
+      const expiresAt = state.notifications[i]!.expiresAt
+      if (expiresAt !== null && expiresAt <= now) state.notifications.splice(i, 1)
+    }
+    schedulePrune()
+  }
+
+  function addNotification(n: NewNotification): string {
+    const keep = n.keep ?? keepBySeverity[n.severity] ?? 'long'
+    if (keep === 'none') return ''
+
     const id = `notif-${++_idCounter}-${Date.now()}`
+    const timestamp = Date.now()
     const notification: Notification = {
-      ...n,
+      severity: n.severity,
+      summary: n.summary,
+      ...(n.detail !== undefined ? { detail: n.detail } : {}),
+      ...(n.emitter !== undefined ? { emitter: n.emitter } : {}),
+      ...(n.to !== undefined ? { to: n.to } : {}),
       id,
-      timestamp: Date.now(),
+      timestamp,
       read: false,
+      keep,
+      expiresAt: keep === 'short' ? timestamp + shortKeepMs : null,
     }
 
     // Add to front (most recent first)
@@ -129,6 +209,7 @@ export function createNotificationStore(config: NotificationStoreConfig = {}): N
       state.notifications.length = maxNotifications
     }
 
+    if (notification.expiresAt !== null) schedulePrune()
     return id
   }
 
@@ -181,6 +262,32 @@ export function createNotificationStore(config: NotificationStoreConfig = {}): N
     }
   }
 
+  // ── Activity ───────────────────────────────────────────────────────────
+
+  const inFlight = ref(0)
+  const busy = ref(false)
+  let busyTimer: ReturnType<typeof setTimeout> | null = null
+
+  function track<T>(work: Promise<T>): Promise<T> {
+    inFlight.value++
+    if (inFlight.value === 1) {
+      // Only work that lasts shows: a fast reload leaves the badge alone.
+      busyTimer = setTimeout(() => {
+        busyTimer = null
+        if (inFlight.value > 0) busy.value = true
+      }, activityDelayMs)
+    }
+    const settle = (): void => {
+      inFlight.value = Math.max(0, inFlight.value - 1)
+      if (inFlight.value > 0) return
+      if (busyTimer) clearTimeout(busyTimer)
+      busyTimer = null
+      busy.value = false
+    }
+    work.then(settle, settle)
+    return work
+  }
+
   // ── Panel state ────────────────────────────────────────────────────────
 
   function open(): void {
@@ -229,6 +336,8 @@ export function createNotificationStore(config: NotificationStoreConfig = {}): N
     registerStatus,
     updateStatus,
     removeStatus,
+    track,
+    isBusy: computed(() => busy.value),
     isOpen,
     open,
     close,
@@ -272,6 +381,8 @@ export function useNotifications(): NotificationStore {
       registerStatus: () => {},
       updateStatus: () => {},
       removeStatus: () => {},
+      track: (work) => work,
+      isBusy: computed(() => false),
       isOpen: ref(false),
       open: () => {},
       close: () => {},

package/src/notifications/index.ts

@@ -32,6 +32,9 @@ export {
   NOTIFICATION_KEY,
   type Notification,
   type NotificationSeverity,
+  type NotificationKeep,
+  type NotificationTarget,
+  type NewNotification,
   type StatusItem,
   type NotificationStore,
   type NotificationStoreConfig,

package/src/orchestrator/Orchestrator.ts

@@ -59,6 +59,10 @@ export type EntityFactory = (
 export interface ToastOptions {
   life?: number
   emitter?: string
+  /** How long the notification history keeps it (#2677); default by severity. */
+  keep?: 'none' | 'short' | 'long'
+  /** Where its history entry leads: a vue-router location. */
+  to?: { name: string; params?: Record<string, unknown>; query?: Record<string, unknown> } | string
 }
 
 /**
@@ -196,6 +200,8 @@ export class Orchestrator {
             detail,
             life: opts.life ?? defaults[severity],
             emitter: opts.emitter,
+            ...(opts.keep !== undefined ? { keep: opts.keep } : {}),
+            ...(opts.to !== undefined ? { to: opts.to } : {}),
           })
         }
       }

package/src/toast/ToastListener.vue

@@ -11,15 +11,26 @@ import { onMounted, onUnmounted, inject } from 'vue'
 import { useToast } from 'primevue/usetoast'
 import type { SignalBus } from '../kernel/SignalBus'
 import { explainMissingToast } from '../kernel/vitePluginCheck'
+import {
+  NOTIFICATION_KEY,
+  type NotificationKeep,
+  type NotificationSeverity,
+  type NotificationTarget,
+} from '../notifications/NotificationStore'
 
 interface ToastEventData {
   summary?: string
   detail?: string
   life?: number
+  emitter?: string
+  keep?: NotificationKeep
+  to?: NotificationTarget
 }
 
 const toast = explainMissingToast(useToast)
 const signals = inject<SignalBus | null>('qdadmSignals', null)
+// Provided when `notifications.enabled`: every toast also leaves a trace (#2677).
+const notifications = inject(NOTIFICATION_KEY, null)
 
 let unsubscribe: (() => void) | null = null
 
@@ -39,6 +50,15 @@ onMounted(() => {
       detail: data?.detail,
       life: data?.life ?? 3000
     })
+    // The pop-up is unchanged; the history keeps it, for as long as its keep level says.
+    notifications?.addNotification({
+      severity: severity as NotificationSeverity,
+      summary: data?.summary ?? '',
+      ...(data?.detail !== undefined ? { detail: data.detail } : {}),
+      ...(data?.emitter !== undefined ? { emitter: data.emitter } : {}),
+      ...(data?.keep !== undefined ? { keep: data.keep } : {}),
+      ...(data?.to !== undefined ? { to: data.to } : {}),
+    })
   })
 })
 

package/src/toast/useSignalToast.ts

@@ -19,6 +19,7 @@
 
 import { inject, getCurrentInstance } from 'vue'
 import type { SignalBus } from '../kernel/SignalBus'
+import type { NotificationKeep, NotificationTarget } from '../notifications/NotificationStore'
 
 /**
  * Toast severity types
@@ -33,16 +34,24 @@ export interface ToastOptions {
   summary: string
   detail?: string
   life?: number
-  /** Force classic PrimeVue toast even when NotificationModule is active */
+  /** @deprecated Toasts always pop up now (#2677); kept for compatibility, it does nothing. */
   forceToast?: boolean
+  /** How long the notification history keeps it (#2677); default by severity. */
+  keep?: NotificationKeep
+  /** Where its history entry leads: a vue-router location. */
+  to?: NotificationTarget
 }
 
 /**
  * Toast method options
  */
 export interface ToastMethodOptions {
-  /** Force classic PrimeVue toast even when NotificationModule is active */
+  /** @deprecated Toasts always pop up now (#2677); kept for compatibility, it does nothing. */
   forceToast?: boolean
+  /** How long the notification history keeps it (#2677); default by severity. */
+  keep?: NotificationKeep
+  /** Where its history entry leads: a vue-router location. */
+  to?: NotificationTarget
 }
 
 /**
@@ -90,10 +99,18 @@ export function useSignalToast(emitter?: string): SignalToastAPI {
    * @param summary - Toast title
    * @param detail - Toast detail message
    * @param life - Duration in ms (0 for sticky)
-   * @param forceToast - Force classic PrimeVue toast when NotificationModule is active
+   * @param options - keep and to, for the notification history (#2677)
    */
-  function addToast(severity: ToastSeverity, summary: string, detail?: string, life: number = 3000, forceToast?: boolean): void {
-    signals.emit(`toast:${severity}`, { summary, detail, life, emitter: resolvedEmitter, forceToast })
+  function addToast(severity: ToastSeverity, summary: string, detail?: string, life: number = 3000, options?: ToastMethodOptions): void {
+    signals.emit(`toast:${severity}`, {
+      summary,
+      detail,
+      life,
+      emitter: resolvedEmitter,
+      ...(options?.forceToast !== undefined ? { forceToast: options.forceToast } : {}),
+      ...(options?.keep !== undefined ? { keep: options.keep } : {}),
+      ...(options?.to !== undefined ? { to: options.to } : {}),
+    })
   }
 
   return {
@@ -105,7 +122,7 @@ export function useSignalToast(emitter?: string): SignalToastAPI {
      * @param options - Additional options
      */
     success(summary: string, detail?: string, life: number = 3000, options?: ToastMethodOptions): void {
-      addToast('success', summary, detail, life, options?.forceToast)
+      addToast('success', summary, detail, life, options)
     },
 
     /**
@@ -116,7 +133,7 @@ export function useSignalToast(emitter?: string): SignalToastAPI {
      * @param options - Additional options
      */
     error(summary: string, detail?: string, life: number = 5000, options?: ToastMethodOptions): void {
-      addToast('error', summary, detail, life, options?.forceToast)
+      addToast('error', summary, detail, life, options)
     },
 
     /**
@@ -127,7 +144,7 @@ export function useSignalToast(emitter?: string): SignalToastAPI {
      * @param options - Additional options
      */
     info(summary: string, detail?: string, life: number = 3000, options?: ToastMethodOptions): void {
-      addToast('info', summary, detail, life, options?.forceToast)
+      addToast('info', summary, detail, life, options)
     },
 
     /**
@@ -138,7 +155,7 @@ export function useSignalToast(emitter?: string): SignalToastAPI {
      * @param options - Additional options
      */
     warn(summary: string, detail?: string, life: number = 4000, options?: ToastMethodOptions): void {
-      addToast('warn', summary, detail, life, options?.forceToast)
+      addToast('warn', summary, detail, life, options)
     },
 
     /**
@@ -146,7 +163,7 @@ export function useSignalToast(emitter?: string): SignalToastAPI {
      * @param options - Toast options
      */
     add(options: ToastOptions): void {
-      addToast(options.severity || 'info', options.summary, options.detail, options.life, options.forceToast)
+      addToast(options.severity || 'info', options.summary, options.detail, options.life, options)
     },
   }
 }