@checkstack/notification-frontend 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,176 @@
 # @checkstack/notification-frontend
 
+## 0.4.6
+
+### Patch Changes
+
+- Updated dependencies [e2d6f25]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [4832e33]
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+- Updated dependencies [c39ee69]
+  - @checkstack/frontend-api@0.6.0
+  - @checkstack/ui@1.11.0
+  - @checkstack/common@0.12.0
+  - @checkstack/auth-frontend@0.6.6
+  - @checkstack/tips-frontend@0.2.6
+  - @checkstack/notification-common@1.2.1
+  - @checkstack/signal-frontend@0.1.5
+
+## 0.4.5
+
+### Patch Changes
+
+- f23f3c9: Add per-channel notification delivery-attempt tracking
+  (Phase 8 of the v1 polishing plan). The external dispatch loop now
+  persists one row per `strategy.send(...)` call into a new
+  `notification_delivery_attempts` table - both successes and
+  failures - so silent delivery breakage (misconfigured webhooks, dead
+  channels) becomes queryable instead of buried in logs.
+
+  - `@checkstack/notification-backend` adds the
+    `notification_delivery_attempts` table, the matching Drizzle
+    migration, and a new `dispatchWithAttempt` helper that wraps every
+    external `strategy.send(...)` with duration measurement and
+    best-effort row persistence. The insert is intentionally
+    fire-and-forget: if writing the attempt row itself errors, the
+    dispatch loop logs and continues so visibility tracking can never
+    introduce a _new_ silent failure.
+  - `@checkstack/notification-common` exports a new
+    `DeliveryAttemptSchema` zod schema, the
+    `ListDeliveryAttemptsInputSchema =
+PaginationInput.extend({ notificationId })` input, and a new
+    `getDeliveryAttempts` procedure on the contract. The procedure is
+    gated by the existing `notificationAccess.admin`
+    (`notification:manage`) access rule - no new permission was
+    introduced.
+  - `@checkstack/notification-frontend` adds a minimal admin-only
+    `DeliveryAttemptsPage` (route id `notification.deliveryAttempts`,
+    path `/notifications/delivery-attempts`) and an "Open inspector"
+    link from the Notification Settings page for users with
+    `notification:manage`. No client-side `isAdmin` gate - the FORBIDDEN
+    case is rendered via the standard error-state branch on the page,
+    enforced by the contract.
+
+  Visibility only: there is no retry mechanism in this phase. A
+  `failure` row is a final outcome an admin actions manually
+  (re-trigger the source event, fix the misconfigured channel).
+  Automated retries are deferred to v1.1.
+
+  Strategy errors thrown during `send(...)` are persisted via
+  `extractErrorMessage(error)` so secrets potentially embedded in raw
+  error objects (webhook URLs, OAuth tokens reachable from the strategy
+  send context) are not stored verbatim.
+
+  See the new
+  `docs/src/content/docs/backend/notification-delivery.md` page for the
+  full surface description.
+
+- f23f3c9: Establish the canonical optimistic-UI pattern for oRPC mutations
+  (`onMutate` snapshot / patch, `onError` rollback, `onSettled`
+  invalidate) and apply it to the two highest-frequency toggles where
+  perceived latency was most visible:
+
+  - `markAsRead` on the Notifications page — clicking the check on a
+    notification card now flips the read state immediately instead of
+    waiting for the round-trip.
+  - `pauseConfiguration` / `resumeConfiguration` on the Health Check
+    Config page — pause/resume now flip the row's badge instantly,
+    rolling back on server error.
+
+  The wrapper type for `useMutation` on each plugin client gained an
+  optional `TContext` generic so optimistic sites can return a snapshot
+  from `onMutate` and consume it in `onError` without `unknown` casts.
+  The runtime behaviour and the auto-invalidation on success are
+  unchanged; the change is additive on the type surface only.
+
+  Full pattern and "when NOT to use it" guidance live in
+  `docs/frontend/optimistic-updates.md`.
+
+- f23f3c9: Sweep every paginated `*-common` contract onto the canonical
+  `PaginationInput` / `PaginatedResult` from `@checkstack/common` and
+  remove the now-unused legacy exports.
+
+  **BREAKING CHANGE** - `@checkstack/common` drops the deprecated
+  `PaginationInputSchema`, `paginatedOutput`, and `PaginatedResponse`
+  symbols. Callers must consume `PaginationInput` (input) and
+  `PaginatedResult(itemSchema)` (output) instead. The canonical input is
+  `{ limit (1-100, default 20), offset (>= 0, default 0) }`; the
+  canonical output envelope is
+  `{ items, total, limit, offset }`.
+
+  **BREAKING CHANGE** - `@checkstack/notification-common` migrates
+  `getNotifications` off the legacy `PaginationInputSchema`
+  (`{ limit, offset, unreadOnly }` with output `{ notifications, total }`)
+  onto `ListNotificationsInputSchema =
+PaginationInput.extend({ unreadOnly })` and
+  `PaginatedResult(NotificationSchema)`. The output key changes from
+  `notifications` to `items`, and `limit` / `offset` are now echoed on
+  the response. The `PaginationInput` type alias previously exported
+  from `notification-common` is removed - use `ListNotificationsInput`
+  or the canonical `PaginationInput` from `@checkstack/common`.
+
+  **BREAKING CHANGE** - `@checkstack/integration-common` migrates
+  `listSubscriptions` (inline `{ page, pageSize, ... }` -> output
+  `{ subscriptions, total }`) and `getDeliveryLogs` (via
+  `DeliveryLogQueryInputSchema` `{ subscriptionId?, eventType?, status?,
+page, pageSize }` -> output `{ logs, total }`) onto the canonical
+  `PaginationInput.extend({...})` input and
+  `PaginatedResult(itemSchema)` output. External callers must switch
+  from `{ page, pageSize }` to `{ limit, offset }` and read response
+  items from `data.items` (no more `data.subscriptions` / `data.logs`).
+
+  The matching `*-backend` handlers were updated to consume the new
+  input shape (`offset` arithmetic in lieu of `(page - 1) * pageSize`)
+  and to echo `limit` / `offset` on the response. The `*-frontend` call
+  sites in `NotificationsPage`, `NotificationBell`, `IntegrationsPage`,
+  and `DeliveryLogsPage` were updated to send the new input shape and
+  read `data.items`.
+
+- f23f3c9: Gate decorative motion and blur effects behind
+  `usePerformance().isLowPower` on a focused set of high-traffic plugin
+  pages (Dashboard, Dependency map, System node, Notification bell,
+  Announcement banner / cards, Anomaly field overrides editor, SLO
+  attribution chart, Catalog droppable group). Hover scales, backdrop
+  blurs, `animate-pulse`/`animate-ping` accents, and entry transitions
+  now drop to static states on low-power devices; functional UX
+  transitions (Drawer/Dialog open-close, colour transitions) are left
+  alone.
+
+  Standardise the post-mutation error-toast voice on plugin pages by
+  migrating multi-clause `toast.error(extractErrorMessage(error, "Failed
+to X"))` call sites onto the `toastError(toast, "Failed to X", error)`
+  helper from `@checkstack/ui`. The helper applies the canonical
+  `"action: message"` prefix and 100-character truncation in one place,
+  and the now-orphaned `extractErrorMessage` imports are dropped from
+  the affected files. No business logic or component APIs changed.
+
+- f23f3c9: Standardise the empty / loading / error story on key list pages using
+  the shared `ListEmptyState`, `QueryErrorState`, and `Skeleton`
+  primitives from `@checkstack/ui`. Each affected page now branches
+  through the same `isLoading -> isError -> empty -> data` ladder, so
+  failed queries surface a retry-able inline error instead of silently
+  rendering an empty table, and loading states match the final layout
+  rather than flashing a generic spinner. No layout, business logic, or
+  query input shapes changed.
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+  - @checkstack/common@0.11.0
+  - @checkstack/auth-frontend@0.6.5
+  - @checkstack/notification-common@1.2.0
+  - @checkstack/frontend-api@0.5.2
+  - @checkstack/ui@1.10.0
+  - @checkstack/tips-frontend@0.2.5
+  - @checkstack/signal-frontend@0.1.4
+
 ## 0.4.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-frontend",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.tsx",
@@ -13,13 +13,13 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/auth-frontend": "0.6.3",
-    "@checkstack/common": "0.10.0",
-    "@checkstack/frontend-api": "0.5.1",
-    "@checkstack/notification-common": "1.1.0",
-    "@checkstack/signal-frontend": "0.1.3",
-    "@checkstack/tips-frontend": "0.2.3",
-    "@checkstack/ui": "1.8.3",
+    "@checkstack/auth-frontend": "0.6.5",
+    "@checkstack/common": "0.11.0",
+    "@checkstack/frontend-api": "0.5.2",
+    "@checkstack/notification-common": "1.2.0",
+    "@checkstack/signal-frontend": "0.1.4",
+    "@checkstack/tips-frontend": "0.2.5",
+    "@checkstack/ui": "1.10.0",
     "lucide-react": "^0.344.0",
     "react": "^18.2.0",
     "react-router-dom": "^6.22.0"
@@ -28,6 +28,6 @@
     "typescript": "^5.0.0",
     "@types/react": "^18.2.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.2"
+    "@checkstack/scripts": "0.3.3"
   }
 }

package/src/components/NotificationBell.tsx

@@ -15,6 +15,8 @@ import {
   stripMarkdown,
   useToast,
   useIsMobile,
+  usePerformance,
+  cn,
 } from "@checkstack/ui";
 import { useApi, usePluginClient } from "@checkstack/frontend-api";
 import { resolveRoute } from "@checkstack/common";
@@ -29,6 +31,7 @@ import { ChevronDown, ChevronUp } from "lucide-react";
 import { authApiRef } from "@checkstack/auth-frontend/api";
 
 export const NotificationBell = () => {
+  const { isLowPower } = usePerformance();
   const authApi = useApi(authApiRef);
   const { data: session, isPending: isAuthLoading } = authApi.useSession();
   const notificationClient = usePluginClient(NotificationApi);
@@ -72,7 +75,7 @@ export const NotificationBell = () => {
   const markAsReadMutation = notificationClient.markAsRead.useMutation();
 
   const unreadCount = unreadData?.count ?? 0;
-  const recentNotifications = notificationsData?.notifications ?? [];
+  const recentNotifications = notificationsData?.items ?? [];
 
   const handleMarkAllAsRead = async () => {
     try {
@@ -102,10 +105,17 @@ export const NotificationBell = () => {
 
   const trigger = (
     <Button variant="ghost" size="icon" className="relative group">
-      <Bell className="h-5 w-5 transition-transform group-hover:scale-110" />
+      <Bell
+        className={cn(
+          "h-5 w-5",
+          !isLowPower && "transition-transform group-hover:scale-110",
+        )}
+      />
       {unreadCount > 0 && (
         <span className="absolute -top-1 -right-1 flex h-5 min-w-[20px] items-center justify-center">
-          <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-destructive opacity-75" />
+          {!isLowPower && (
+            <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-destructive opacity-75" />
+          )}
           <Badge
             variant="destructive"
             className="relative h-5 min-w-[20px] flex items-center justify-center p-0 text-xs font-bold"

package/src/index.tsx

@@ -11,6 +11,7 @@ import {
 import { NotificationBell } from "./components/NotificationBell";
 import { NotificationsPage } from "./pages/NotificationsPage";
 import { NotificationSettingsPage } from "./pages/NotificationSettingsPage";
+import { DeliveryAttemptsPage } from "./pages/DeliveryAttemptsPage";
 import { NotificationUserMenuItems } from "./components/UserMenuItems";
 
 // Plugin-extensible kind registry — domain frontends call `registerSubjectKind`
@@ -47,6 +48,10 @@ export const notificationPlugin = createFrontendPlugin({
       route: notificationRoutes.routes.settings,
       element: <NotificationSettingsPage />,
     },
+    {
+      route: notificationRoutes.routes.deliveryAttempts,
+      element: <DeliveryAttemptsPage />,
+    },
   ],
   extensions: [
     {

package/src/pages/DeliveryAttemptsPage.tsx

@@ -0,0 +1,197 @@
+import { useState } from "react";
+import { Send } from "lucide-react";
+import {
+  PageLayout,
+  Badge,
+  Button,
+  Card,
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+  Alert,
+  LoadingSpinner,
+  EmptyState,
+} from "@checkstack/ui";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { NotificationApi } from "@checkstack/notification-common";
+import type { DeliveryAttempt } from "@checkstack/notification-common";
+import { extractErrorMessage } from "@checkstack/common";
+
+const PAGE_SIZE = 25;
+const ERROR_MESSAGE_MAX = 120;
+
+/**
+ * Truncate a sanitised error message to keep the table column tidy.
+ * The full message is still available on hover via `title`.
+ */
+const truncate = (value: string, max: number): string =>
+  value.length > max ? `${value.slice(0, max - 1)}…` : value;
+
+/**
+ * Format an attempt timestamp as local-time with a relative hint.
+ * Mirrors `NotificationsPage`'s `formatDate` voice without depending
+ * on it (a tiny helper, not worth a shared util yet).
+ */
+const formatAttemptedAt = (raw: Date | string): string => {
+  const d = new Date(raw);
+  return d.toLocaleString();
+};
+
+const StatusBadge = ({ status }: { status: DeliveryAttempt["status"] }) => {
+  if (status === "success") {
+    return <Badge variant="success">Success</Badge>;
+  }
+  return <Badge variant="destructive">Failure</Badge>;
+};
+
+/**
+ * Admin-only visibility surface for per-channel notification delivery
+ * attempts. Shows the most recent attempts (newest first); failures
+ * expose the silent-failure mode the dispatch loop swallowed pre-v1.
+ *
+ * Scope is intentionally minimal — no filter chips, charts, or
+ * exports. Retries are deferred to v1.1; this is visibility only.
+ */
+export const DeliveryAttemptsPage = () => {
+  const notificationClient = usePluginClient(NotificationApi);
+  const [page, setPage] = useState(0);
+
+  const {
+    data,
+    isLoading,
+    isError,
+    error,
+    refetch,
+  } = notificationClient.getDeliveryAttempts.useQuery({
+    limit: PAGE_SIZE,
+    offset: page * PAGE_SIZE,
+  });
+
+  const attempts = data?.items ?? [];
+  const total = data?.total ?? 0;
+  const pageCount = Math.max(1, Math.ceil(total / PAGE_SIZE));
+
+  // No client-side `isAdmin` gate: the `getDeliveryAttempts` procedure
+  // is locked behind `notificationAccess.admin` at the contract layer
+  // (see `core/notification-common/src/rpc-contract.ts`). A caller
+  // without the `notification:manage` access rule receives FORBIDDEN
+  // from the server, which we render below via the standard
+  // error-state branch. The nav entry is hidden cosmetically by the
+  // existing access check on `NotificationSettingsPage` — security is
+  // enforced by the contract, not the UI.
+  return (
+    <PageLayout title="Delivery Attempts" icon={Send}>
+      <div className="space-y-4">
+        <p className="text-sm text-muted-foreground">
+          Per-channel outcomes from the external notification dispatch
+          loop. Failures are surfaced here so silent delivery breakage
+          (misconfigured webhooks, dead channels) becomes actionable.
+          Retries are not implemented yet - this is visibility only.
+        </p>
+
+        {isLoading ? (
+          <Card className="p-8">
+            <div className="flex justify-center">
+              <LoadingSpinner size="md" />
+            </div>
+          </Card>
+        ) : isError ? (
+          <Alert variant="error">
+            <div className="flex items-center justify-between gap-4">
+              <span>
+                Failed to load delivery attempts:{" "}
+                {extractErrorMessage(error, "Unknown error")}
+              </span>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => {
+                  void refetch();
+                }}
+              >
+                Retry
+              </Button>
+            </div>
+          </Alert>
+        ) : attempts.length === 0 ? (
+          <EmptyState
+            icon={<Send className="h-12 w-12" />}
+            title="No delivery attempts yet"
+            description="Once notifications are dispatched via an external channel, each attempt will appear here."
+          />
+        ) : (
+          <Card className="p-0 overflow-hidden">
+            <Table>
+              <TableHeader>
+                <TableRow>
+                  <TableHead>Attempted at</TableHead>
+                  <TableHead>Strategy</TableHead>
+                  <TableHead>Status</TableHead>
+                  <TableHead>Duration</TableHead>
+                  <TableHead>Error</TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                {attempts.map((attempt) => (
+                  <TableRow key={attempt.id}>
+                    <TableCell className="whitespace-nowrap">
+                      {formatAttemptedAt(attempt.attemptedAt)}
+                    </TableCell>
+                    <TableCell className="font-mono text-xs">
+                      {attempt.strategyQualifiedId}
+                    </TableCell>
+                    <TableCell>
+                      <StatusBadge status={attempt.status} />
+                    </TableCell>
+                    <TableCell className="whitespace-nowrap text-muted-foreground">
+                      {attempt.durationMs}ms
+                    </TableCell>
+                    <TableCell
+                      className="max-w-md text-xs text-muted-foreground"
+                      title={attempt.errorMessage ?? undefined}
+                    >
+                      {attempt.errorMessage
+                        ? truncate(attempt.errorMessage, ERROR_MESSAGE_MAX)
+                        : "-"}
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+          </Card>
+        )}
+
+        {total > PAGE_SIZE && (
+          <div className="flex items-center justify-center gap-2">
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={page === 0}
+              onClick={() => {
+                setPage((p) => Math.max(0, p - 1));
+              }}
+            >
+              Previous
+            </Button>
+            <span className="text-sm text-muted-foreground">
+              Page {page + 1} of {pageCount}
+            </span>
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={(page + 1) * PAGE_SIZE >= total}
+              onClick={() => {
+                setPage((p) => p + 1);
+              }}
+            >
+              Next
+            </Button>
+          </div>
+        )}
+      </div>
+    </PageLayout>
+  );
+};

package/src/pages/NotificationSettingsPage.tsx

@@ -1,5 +1,6 @@
 import { useState, useEffect } from "react";
-import { Bell, Clock, Zap, Send } from "lucide-react";
+import { Link } from "react-router-dom";
+import { Bell, Clock, Zap, Send, Activity } from "lucide-react";
 import {
   PageLayout,
   Card,
@@ -17,8 +18,10 @@ import type { EnrichedSubscription } from "@checkstack/notification-common";
 import {
   NotificationApi,
   notificationAccess,
+  notificationRoutes,
   pluginMetadata as notificationPluginMetadata,
 } from "@checkstack/notification-common";
+import { resolveRoute } from "@checkstack/common";
 import { TipBanner } from "@checkstack/tips-frontend";
 import {
   StrategyCard,
@@ -389,6 +392,34 @@ export const NotificationSettingsPage = () => {
           </section>
         )}
 
+        {/* Delivery Attempts inspector link - Admin only */}
+        {isAdmin && (
+          <section>
+            <SectionHeader
+              title="Delivery Attempts"
+              description="Inspect per-channel delivery outcomes for recent notifications (admin only)."
+              icon={<Activity className="h-5 w-5" />}
+            />
+            <Card className="p-4">
+              <div className="flex items-center justify-between gap-4">
+                <p className="text-sm text-muted-foreground">
+                  See every external `strategy.send(...)` outcome - useful
+                  for debugging silent failures on misconfigured channels.
+                </p>
+                <Button asChild variant="outline" size="sm">
+                  <Link
+                    to={resolveRoute(
+                      notificationRoutes.routes.deliveryAttempts,
+                    )}
+                  >
+                    Open inspector
+                  </Link>
+                </Button>
+              </div>
+            </Card>
+          </section>
+        )}
+
         {/* Retention Policy - Admin only */}
         {isAdmin && retentionSchema && (
           <section>

package/src/pages/NotificationsPage.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback } from "react";
+import { useState, useCallback, useMemo } from "react";
 import { Link } from "react-router-dom";
 import { Bell, Check, Trash2, ChevronDown, ChevronUp } from "lucide-react";
 import {
@@ -6,7 +6,11 @@ import {
   Badge,
   Button,
   Card,
+  ListEmptyState,
+  QueryErrorState,
+  Skeleton,
   useToast,
+  toastError,
   Popover,
   PopoverContent,
   PopoverTrigger,
@@ -14,16 +18,27 @@ import {
   MenuCloseContext,
   Markdown,
 } from "@checkstack/ui";
-import { usePluginClient } from "@checkstack/frontend-api";
+import { usePluginClient, useQueryClient } from "@checkstack/frontend-api";
 import type { Notification } from "@checkstack/notification-common";
 import { NotificationApi } from "@checkstack/notification-common";
-import { extractErrorMessage } from "@checkstack/common";
+import { extractErrorMessage, type InferClient } from "@checkstack/common";
 import { NotificationSubjects } from "../components/NotificationSubjects";
 import { groupByCollapseKey } from "../components/collapse";
 import { CollapsedGroupTimeline } from "../components/CollapsedGroupTimeline";
 
+/**
+ * Cached output of the `notification.getNotifications` query, derived
+ * directly from the contract so a future change to the procedure's
+ * output shape surfaces as a typecheck error in this file rather than
+ * a runtime mismatch between the cache and the optimistic patch.
+ */
+type NotificationsQueryData = Awaited<
+  ReturnType<InferClient<typeof NotificationApi>["getNotifications"]>
+>;
+
 export const NotificationsPage = () => {
   const notificationClient = usePluginClient(NotificationApi);
+  const queryClient = useQueryClient();
   const toast = useToast();
 
   const [filter, setFilter] = useState<"all" | "unread">("all");
@@ -46,30 +61,79 @@ export const NotificationsPage = () => {
   const [filterDropdownOpen, setFilterDropdownOpen] = useState(false);
   const pageSize = 20;
 
+  // Query input — captured once so the loader and the optimistic
+  // `markAsRead` patch agree on the exact query-key oRPC builds. Changes
+  // to filter/page rebuild the memo, which rebuilds the key, which keeps
+  // the optimistic write aimed at the cache entry the user is looking at.
+  const notificationsQueryInput = useMemo(
+    () => ({
+      limit: pageSize,
+      offset: page * pageSize,
+      unreadOnly: filter === "unread",
+    }),
+    [page, pageSize, filter],
+  );
+
+  // Mirrors oRPC's `generateOperationKey([path], { type, input })` shape;
+  // see `docs/frontend/optimistic-updates.md` for the contract.
+  const notificationsQueryKey = useMemo(
+    () =>
+      [
+        ["notification", "getNotifications"],
+        { input: notificationsQueryInput, type: "query" },
+      ] as const,
+    [notificationsQueryInput],
+  );
+
   // Query: Fetch notifications
+  const notificationsQuery =
+    notificationClient.getNotifications.useQuery(notificationsQueryInput);
   const {
     data: notificationsData,
     isLoading: loading,
     refetch,
-  } = notificationClient.getNotifications.useQuery({
-    limit: pageSize,
-    offset: page * pageSize,
-    unreadOnly: filter === "unread",
-  });
+  } = notificationsQuery;
 
-  const notifications = notificationsData?.notifications ?? [];
+  const notifications = notificationsData?.items ?? [];
   const total = notificationsData?.total ?? 0;
 
-  // Mutation: Mark as read
+  // Mutation: Mark as read — optimistic.
+  //
+  // High-frequency click; the perceived latency win matters. Four-step
+  // pattern per `docs/frontend/optimistic-updates.md`:
+  // 1. onMutate: cancel in-flight refetches, snapshot, patch.
+  // 2. onError: roll back from the snapshot, surface a toast.
+  // 3. onSettled: invalidate the exact key so the cache reconciles
+  //    with server truth on both branches.
+  // 4. No success toast — the row fades; that IS the feedback.
   const markAsReadMutation = notificationClient.markAsRead.useMutation({
-    onSuccess: () => {
-      void refetch();
-      toast.success("Notification marked as read");
+    onMutate: async ({ notificationId }) => {
+      await queryClient.cancelQueries({ queryKey: notificationsQueryKey });
+      const previous =
+        queryClient.getQueryData<NotificationsQueryData>(notificationsQueryKey);
+      if (previous) {
+        queryClient.setQueryData<NotificationsQueryData>(
+          notificationsQueryKey,
+          {
+            ...previous,
+            items: previous.items.map((n) =>
+              notificationId === undefined || n.id === notificationId
+                ? { ...n, isRead: true }
+                : n,
+            ),
+          },
+        );
+      }
+      return { previous };
     },
-    onError: (error) => {
-      toast.error(
-        extractErrorMessage(error, "Failed to mark as read"),
-      );
+    onError: (error, _vars, ctx) => {
+      if (ctx?.previous) {
+        queryClient.setQueryData(notificationsQueryKey, ctx.previous);
+      }
+      toastError(toast, "Failed to mark as read", error);
+    },
+    onSettled: () => {
+      void queryClient.invalidateQueries({ queryKey: notificationsQueryKey });
     },
   });
 
@@ -149,7 +213,7 @@ export const NotificationsPage = () => {
   };
 
   return (
-    <PageLayout title="Notifications" icon={Bell} loading={loading}>
+    <PageLayout title="Notifications" icon={Bell}>
       <div className="space-y-4">
         {/* Header with filters */}
         <div className="flex items-center justify-between">
@@ -204,11 +268,40 @@ export const NotificationsPage = () => {
         </div>
 
         {/* Notifications list */}
-        {notifications.length === 0 ? (
-          <Card className="p-8 text-center text-muted-foreground">
-            <Bell className="h-12 w-12 mx-auto mb-4 opacity-50" />
-            <p>No notifications</p>
-          </Card>
+        {loading ? (
+          <div className="space-y-2">
+            {Array.from({ length: 3 }, (_, index) => (
+              <Card key={index} className="p-4">
+                <div className="flex items-start justify-between gap-4">
+                  <div className="flex-1 min-w-0 space-y-2">
+                    <div className="flex items-center gap-2">
+                      <Skeleton className="h-5 w-16 rounded-full" />
+                      <Skeleton className="h-3 w-20" />
+                    </div>
+                    <Skeleton className="h-5 w-2/3" />
+                    <Skeleton className="h-4 w-full" />
+                    <Skeleton className="h-4 w-1/2" />
+                  </div>
+                  <div className="flex items-center gap-1">
+                    <Skeleton className="h-8 w-8" />
+                    <Skeleton className="h-8 w-8" />
+                  </div>
+                </div>
+              </Card>
+            ))}
+          </div>
+        ) : notificationsQuery.isError ? (
+          <QueryErrorState
+            error={notificationsQuery.error}
+            onRetry={() => void notificationsQuery.refetch()}
+            resource="notifications"
+          />
+        ) : notifications.length === 0 ? (
+          <ListEmptyState
+            resource="notifications"
+            description="You're all caught up. New notifications about systems you're subscribed to will show up here."
+            icon={<Bell className="h-10 w-10" />}
+          />
         ) : (
           <div className="space-y-2">
             {groupByCollapseKey(notifications).map((group) => {