From d4708d6973127e95ab52084eb7fd6583f52294a0 Mon Sep 17 00:00:00 2001
From: Zen0space <tartnenas_kai@outlook.com>
Date: Sat, 11 Apr 2026 19:56:50 +0800
Subject: [PATCH 1/2] feat: PWA push notifications, install tracking, jotai
 refactor & branded splash screen

Add web push notification system with VAPID keys, subscription management,
and auto-prompt for PWA users. Track PWA installs with anonymous-to-authenticated
claim flow. Refactor useEffect/useState patterns to jotai atoms for breakpoints
and push state (eliminating duplicate resize listeners and capability checks).
Add server-rendered branded splash screen with breathing icon animation for
zero-flicker PWA cold start, with instant redirect to dashboard.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
---
 .../src/app/dashboard/notifications/page.tsx  | 762 ++++++++++++++++++
 packages/kal-admin/src/components/Sidebar.tsx |  22 +
 packages/kal-backend/.env.example             |   8 +-
 packages/kal-backend/package.json             |   2 +
 packages/kal-backend/src/index.ts             |   2 +-
 packages/kal-backend/src/lib/pwa-installs.ts  |  23 +
 packages/kal-backend/src/lib/web-push.ts      | 186 +++++
 packages/kal-backend/src/routers/index.ts     |   4 +
 packages/kal-backend/src/routers/push.ts      | 187 +++++
 packages/kal-backend/src/routers/pwa.ts       | 138 ++++
 ...0260411000001_create_push_subscriptions.js |  61 ++
 .../20260411000002_create_pwa_installs.js     |  62 ++
 packages/kal-frontend/.env.example            |   4 +
 packages/kal-frontend/next.config.mjs         |   1 +
 .../public/apple-touch-icon-precomposed.png   | Bin 0 -> 5368 bytes
 .../kal-frontend/public/apple-touch-icon.png  | Bin 0 -> 5368 bytes
 .../src/app/dashboard/settings/client.tsx     | 150 +++-
 packages/kal-frontend/src/app/globals.css     |   6 +
 packages/kal-frontend/src/app/layout.tsx      |  17 +-
 packages/kal-frontend/src/app/page.tsx        |  52 ++
 packages/kal-frontend/src/app/sw.ts           |  62 ++
 packages/kal-frontend/src/atoms/breakpoint.ts |  85 ++
 .../kal-frontend/src/atoms/push-prompt.ts     |  11 +
 packages/kal-frontend/src/atoms/push-state.ts |  20 +
 packages/kal-frontend/src/atoms/pwa.ts        |  41 +
 .../src/components/BreakpointProvider.tsx     |  32 +
 .../src/components/PushPermissionPrompt.tsx   | 210 +++++
 .../src/components/PushStateProvider.tsx      |  58 ++
 .../src/components/PwaAuthRedirect.tsx        |  59 ++
 .../src/components/PwaInstallTracker.tsx      | 132 +++
 .../kal-frontend/src/hooks/useBreakpoint.ts   | 106 +--
 .../src/lib/push-notifications.ts             | 191 +++++
 .../src/lib/push-prompt-storage.ts            |  86 ++
 .../src/lib/pwa-install-tracker.ts            | 136 ++++
 packages/kal-frontend/tailwind.config.ts      |   5 +
 pnpm-lock.yaml                                | 100 +++
 36 files changed, 2919 insertions(+), 102 deletions(-)
 create mode 100644 packages/kal-admin/src/app/dashboard/notifications/page.tsx
 create mode 100644 packages/kal-backend/src/lib/pwa-installs.ts
 create mode 100644 packages/kal-backend/src/lib/web-push.ts
 create mode 100644 packages/kal-backend/src/routers/push.ts
 create mode 100644 packages/kal-backend/src/routers/pwa.ts
 create mode 100644 packages/kal-db/migrations/20260411000001_create_push_subscriptions.js
 create mode 100644 packages/kal-db/migrations/20260411000002_create_pwa_installs.js
 create mode 100644 packages/kal-frontend/public/apple-touch-icon-precomposed.png
 create mode 100644 packages/kal-frontend/public/apple-touch-icon.png
 create mode 100644 packages/kal-frontend/src/atoms/breakpoint.ts
 create mode 100644 packages/kal-frontend/src/atoms/push-prompt.ts
 create mode 100644 packages/kal-frontend/src/atoms/push-state.ts
 create mode 100644 packages/kal-frontend/src/atoms/pwa.ts
 create mode 100644 packages/kal-frontend/src/components/BreakpointProvider.tsx
 create mode 100644 packages/kal-frontend/src/components/PushPermissionPrompt.tsx
 create mode 100644 packages/kal-frontend/src/components/PushStateProvider.tsx
 create mode 100644 packages/kal-frontend/src/components/PwaAuthRedirect.tsx
 create mode 100644 packages/kal-frontend/src/components/PwaInstallTracker.tsx
 create mode 100644 packages/kal-frontend/src/lib/push-notifications.ts
 create mode 100644 packages/kal-frontend/src/lib/push-prompt-storage.ts
 create mode 100644 packages/kal-frontend/src/lib/pwa-install-tracker.ts

diff --git a/packages/kal-admin/src/app/dashboard/notifications/page.tsx b/packages/kal-admin/src/app/dashboard/notifications/page.tsx
new file mode 100644
index 0000000..5d26885
--- /dev/null
+++ b/packages/kal-admin/src/app/dashboard/notifications/page.tsx
@@ -0,0 +1,762 @@
+"use client";
+
+import { useState } from "react";
+
+import { trpc } from "@/lib/trpc";
+
+// ─── Stat Card ───────────────────────────────────────────────────────────────
+
+function StatCard({
+  label,
+  value,
+  icon,
+  color = "primary",
+}: {
+  label: string;
+  value: string | number;
+  icon: React.ReactNode;
+  color?: "primary" | "success" | "warning" | "info";
+}) {
+  const colorMap: Record<string, string> = {
+    primary: "text-primary-light bg-primary/10 border-primary/15",
+    success:
+      "text-status-success bg-status-success/10 border-status-success/15",
+    warning:
+      "text-status-warning bg-status-warning/10 border-status-warning/15",
+    info: "text-status-info bg-status-info/10 border-status-info/15",
+  };
+
+  return (
+    <div className="bg-admin-surface border border-admin-border rounded-xl p-4 flex items-center gap-3">
+      <div
+        className={`w-10 h-10 rounded-lg border flex items-center justify-center shrink-0 ${colorMap[color]}`}
+      >
+        {icon}
+      </div>
+      <div>
+        <p className="text-xs font-medium text-text-muted uppercase tracking-wide">
+          {label}
+        </p>
+        <p className="text-xl font-semibold text-text-primary">{value}</p>
+      </div>
+    </div>
+  );
+}
+
+// ─── Send Result Banner ──────────────────────────────────────────────────────
+
+function ResultBanner({
+  result,
+  onDismiss,
+}: {
+  result: { sent: number; failed: number; expired: number };
+  onDismiss: () => void;
+}) {
+  const total = result.sent + result.failed + result.expired;
+  const isSuccess = result.sent > 0 && result.failed === 0;
+
+  return (
+    <div
+      className={`mb-6 relative overflow-hidden rounded-xl p-4 flex items-center justify-between gap-3 ${
+        isSuccess
+          ? "bg-status-success/[0.06] border border-status-success/20"
+          : "bg-status-warning/[0.06] border border-status-warning/20"
+      }`}
+    >
+      <div
+        className={`absolute left-0 top-0 bottom-0 w-1 rounded-l-xl ${
+          isSuccess ? "bg-status-success" : "bg-status-warning"
+        }`}
+      />
+      <div className="ml-2">
+        <p
+          className={`font-medium text-sm ${
+            isSuccess ? "text-status-success" : "text-status-warning"
+          }`}
+        >
+          Notification sent to {result.sent} of {total} device
+          {total !== 1 ? "s" : ""}
+        </p>
+        {(result.failed > 0 || result.expired > 0) && (
+          <p
+            className={`text-xs mt-0.5 ${
+              isSuccess ? "text-status-success/60" : "text-status-warning/60"
+            }`}
+          >
+            {result.failed > 0 && `${result.failed} failed`}
+            {result.failed > 0 && result.expired > 0 && ", "}
+            {result.expired > 0 && `${result.expired} expired (auto-cleaned)`}
+          </p>
+        )}
+      </div>
+      <button
+        onClick={onDismiss}
+        className="text-text-muted hover:text-text-primary transition-colors p-1"
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+          <path
+            d="M18 6L6 18M6 6l12 12"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+          />
+        </svg>
+      </button>
+    </div>
+  );
+}
+
+// ─── Main Page ───────────────────────────────────────────────────────────────
+
+export default function NotificationsPage() {
+  // Form state
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [url, setUrl] = useState("");
+  const [target, setTarget] = useState<"all" | "user">("all");
+  const [selectedUserId, setSelectedUserId] = useState("");
+  const [sendResult, setSendResult] = useState<{
+    sent: number;
+    failed: number;
+    expired: number;
+  } | null>(null);
+
+  // Data queries
+  const { data: stats, isLoading: statsLoading } =
+    trpc.push.getStats.useQuery();
+  const { data: pwaStats, isLoading: pwaStatsLoading } =
+    trpc.pwa.getStats.useQuery();
+  const { data: usersData } = trpc.user.list.useQuery();
+
+  // Mutations
+  const sendToAll = trpc.push.sendToAll.useMutation({
+    onSuccess: (data) => {
+      setSendResult(data);
+      setTitle("");
+      setBody("");
+      setUrl("");
+    },
+  });
+
+  const sendToUser = trpc.push.sendToUser.useMutation({
+    onSuccess: (data) => {
+      setSendResult(data);
+      setTitle("");
+      setBody("");
+      setUrl("");
+      setSelectedUserId("");
+    },
+  });
+
+  const isSending = sendToAll.isPending || sendToUser.isPending;
+  const error = sendToAll.error || sendToUser.error;
+
+  const canSend =
+    title.trim() &&
+    body.trim() &&
+    !isSending &&
+    (target === "all" || selectedUserId);
+
+  const handleSend = () => {
+    if (!canSend) return;
+
+    const payload = {
+      title: title.trim(),
+      body: body.trim(),
+      url: url.trim() || undefined,
+    };
+
+    if (target === "all") {
+      sendToAll.mutate(payload);
+    } else {
+      sendToUser.mutate({ ...payload, userId: selectedUserId });
+    }
+  };
+
+  return (
+    <div className="p-6 max-w-4xl mx-auto animate-fade-in">
+      {/* Header */}
+      <div className="mb-6">
+        <h1 className="text-xl font-semibold text-text-primary">
+          Push Notifications
+        </h1>
+        <p className="text-sm text-text-muted mt-1">
+          Send push notifications to subscribed PWA users
+        </p>
+      </div>
+
+      {/* Push Stats */}
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4 mb-6">
+        <StatCard
+          label="Subscribed Devices"
+          value={statsLoading ? "..." : (stats?.totalSubscriptions ?? 0)}
+          color="primary"
+          icon={
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+              <path
+                d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M13.73 21a2 2 0 0 1-3.46 0"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+            </svg>
+          }
+        />
+        <StatCard
+          label="Unique Users"
+          value={statsLoading ? "..." : (stats?.uniqueUsers ?? 0)}
+          color="info"
+          icon={
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+              <path
+                d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+              />
+              <circle
+                cx="9"
+                cy="7"
+                r="4"
+                stroke="currentColor"
+                strokeWidth="2"
+              />
+            </svg>
+          }
+        />
+      </div>
+
+      {/* Push Prompt Analytics */}
+      {!statsLoading &&
+        ((stats?.promptsConverted ?? 0) > 0 ||
+          (stats?.promptsDismissed ?? 0) > 0) && (
+          <div className="bg-admin-surface border border-admin-border rounded-xl p-6 mb-6">
+            <h2 className="text-sm font-semibold text-text-primary mb-4 flex items-center gap-2">
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+                <path
+                  d="M22 12h-4l-3 9L9 3l-3 9H2"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+              </svg>
+              Push Prompt Analytics
+            </h2>
+            <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
+              <StatCard
+                label="Subscribed via Prompt"
+                value={stats?.promptsConverted ?? 0}
+                color="success"
+                icon={
+                  <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+                    <path
+                      d="M22 11.08V12a10 10 0 1 1-5.93-9.14"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                    />
+                    <path
+                      d="M22 4L12 14.01l-3-3"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                }
+              />
+              <StatCard
+                label="Dismissed"
+                value={stats?.promptsDismissed ?? 0}
+                color="warning"
+                icon={
+                  <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+                    <path
+                      d="M18 6L6 18M6 6l12 12"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                    />
+                  </svg>
+                }
+              />
+              <StatCard
+                label="Conversion Rate"
+                value={
+                  (() => {
+                    const total =
+                      (stats?.promptsConverted ?? 0) +
+                      (stats?.promptsDismissed ?? 0);
+                    if (total === 0) return "—";
+                    return `${Math.round(((stats?.promptsConverted ?? 0) / total) * 100)}%`;
+                  })()
+                }
+                color="info"
+                icon={
+                  <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+                    <path
+                      d="M23 6l-9.5 9.5-5-5L1 18"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                    <path
+                      d="M17 6h6v6"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                }
+              />
+            </div>
+          </div>
+        )}
+
+      {/* PWA Install Stats */}
+      <div className="bg-admin-surface border border-admin-border rounded-xl p-6 mb-6">
+        <h2 className="text-sm font-semibold text-text-primary mb-4 flex items-center gap-2">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+            <path
+              d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+            <polyline
+              points="7 10 12 15 17 10"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+            <line
+              x1="12"
+              y1="15"
+              x2="12"
+              y2="3"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+          PWA Installs
+        </h2>
+
+        <div className="grid grid-cols-1 sm:grid-cols-3 gap-4 mb-4">
+          <StatCard
+            label="Total Installs"
+            value={pwaStatsLoading ? "..." : (pwaStats?.totalInstalls ?? 0)}
+            color="success"
+            icon={
+              <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+                <rect
+                  x="5"
+                  y="2"
+                  width="14"
+                  height="20"
+                  rx="2"
+                  ry="2"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                />
+                <line
+                  x1="12"
+                  y1="18"
+                  x2="12.01"
+                  y2="18"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            }
+          />
+          <StatCard
+            label="Authenticated"
+            value={
+              pwaStatsLoading ? "..." : (pwaStats?.authenticatedInstalls ?? 0)
+            }
+            color="info"
+            icon={
+              <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+                <path
+                  d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+              </svg>
+            }
+          />
+          <StatCard
+            label="Anonymous"
+            value={pwaStatsLoading ? "..." : (pwaStats?.anonymousInstalls ?? 0)}
+            color="warning"
+            icon={
+              <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+                <path
+                  d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+                <circle
+                  cx="9"
+                  cy="7"
+                  r="4"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                />
+                <line
+                  x1="17"
+                  y1="8"
+                  x2="23"
+                  y2="8"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            }
+          />
+        </div>
+
+        {/* Platform & Browser Breakdown */}
+        {pwaStats &&
+          (pwaStats.platformBreakdown.length > 0 ||
+            pwaStats.browserBreakdown.length > 0) && (
+            <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+              {/* Platform Breakdown */}
+              {pwaStats.platformBreakdown.length > 0 && (
+                <div className="bg-admin-elevated border border-admin-border-subtle rounded-lg p-4">
+                  <p className="text-xs font-medium text-text-muted uppercase tracking-wide mb-3">
+                    By Platform
+                  </p>
+                  <div className="space-y-2">
+                    {pwaStats.platformBreakdown.map((p) => (
+                      <div
+                        key={p.platform}
+                        className="flex items-center justify-between"
+                      >
+                        <span className="text-sm text-text-secondary capitalize">
+                          {p.platform}
+                        </span>
+                        <div className="flex items-center gap-2">
+                          <div className="w-24 h-1.5 bg-admin-border rounded-full overflow-hidden">
+                            <div
+                              className="h-full bg-primary rounded-full"
+                              style={{
+                                width: `${pwaStats.totalInstalls > 0 ? (p.count / pwaStats.totalInstalls) * 100 : 0}%`,
+                              }}
+                            />
+                          </div>
+                          <span className="text-xs font-medium text-text-muted w-6 text-right">
+                            {p.count}
+                          </span>
+                        </div>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              )}
+
+              {/* Browser Breakdown */}
+              {pwaStats.browserBreakdown.length > 0 && (
+                <div className="bg-admin-elevated border border-admin-border-subtle rounded-lg p-4">
+                  <p className="text-xs font-medium text-text-muted uppercase tracking-wide mb-3">
+                    By Browser
+                  </p>
+                  <div className="space-y-2">
+                    {pwaStats.browserBreakdown.map((b) => (
+                      <div
+                        key={b.browser}
+                        className="flex items-center justify-between"
+                      >
+                        <span className="text-sm text-text-secondary capitalize">
+                          {b.browser}
+                        </span>
+                        <div className="flex items-center gap-2">
+                          <div className="w-24 h-1.5 bg-admin-border rounded-full overflow-hidden">
+                            <div
+                              className="h-full bg-status-info rounded-full"
+                              style={{
+                                width: `${pwaStats.totalInstalls > 0 ? (b.count / pwaStats.totalInstalls) * 100 : 0}%`,
+                              }}
+                            />
+                          </div>
+                          <span className="text-xs font-medium text-text-muted w-6 text-right">
+                            {b.count}
+                          </span>
+                        </div>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+
+        {/* Daily Installs */}
+        {pwaStats && pwaStats.dailyInstalls.length > 0 && (
+          <div className="mt-4 bg-admin-elevated border border-admin-border-subtle rounded-lg p-4">
+            <p className="text-xs font-medium text-text-muted uppercase tracking-wide mb-3">
+              Last 30 Days
+            </p>
+            <div className="flex items-end gap-[2px] h-16">
+              {pwaStats.dailyInstalls.map((d) => {
+                const max = Math.max(
+                  ...pwaStats.dailyInstalls.map((i) => i.count)
+                );
+                const heightPct = max > 0 ? (d.count / max) * 100 : 0;
+                return (
+                  <div
+                    key={d.date}
+                    className="flex-1 bg-primary/60 hover:bg-primary rounded-t transition-colors group relative"
+                    style={{
+                      height: `${Math.max(heightPct, 4)}%`,
+                    }}
+                  >
+                    <div className="absolute -top-7 left-1/2 -translate-x-1/2 bg-admin-surface border border-admin-border rounded px-1.5 py-0.5 text-[10px] text-text-secondary whitespace-nowrap opacity-0 group-hover:opacity-100 transition-opacity pointer-events-none z-10">
+                      {d.date}: {d.count}
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        )}
+
+        {!pwaStatsLoading && pwaStats?.totalInstalls === 0 && (
+          <p className="text-sm text-text-muted text-center py-4">
+            No PWA installs recorded yet. Installs are tracked automatically
+            when users add the app to their home screen.
+          </p>
+        )}
+      </div>
+
+      {/* Send Result */}
+      {sendResult && (
+        <ResultBanner
+          result={sendResult}
+          onDismiss={() => setSendResult(null)}
+        />
+      )}
+
+      {/* Compose Form */}
+      <div className="bg-admin-surface border border-admin-border rounded-xl p-6">
+        <h2 className="text-sm font-semibold text-text-primary mb-4 flex items-center gap-2">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+            <path
+              d="M11 5H6a2 2 0 0 0-2 2v11a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2v-5m-1.414-9.414a2 2 0 1 1 2.828 2.828L11.828 15H9v-2.828l8.586-8.586z"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+          Compose Notification
+        </h2>
+
+        <div className="space-y-4">
+          {/* Target selection */}
+          <div>
+            <label className="block text-xs font-medium text-text-muted uppercase tracking-wide mb-1.5">
+              Send To
+            </label>
+            <div className="flex gap-2">
+              <button
+                onClick={() => setTarget("all")}
+                className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
+                  target === "all"
+                    ? "bg-primary/10 text-primary-light border border-primary/20"
+                    : "text-text-secondary hover:text-text-primary bg-admin-elevated border border-admin-border"
+                }`}
+              >
+                All Users ({stats?.totalSubscriptions ?? 0} devices)
+              </button>
+              <button
+                onClick={() => setTarget("user")}
+                className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
+                  target === "user"
+                    ? "bg-primary/10 text-primary-light border border-primary/20"
+                    : "text-text-secondary hover:text-text-primary bg-admin-elevated border border-admin-border"
+                }`}
+              >
+                Specific User
+              </button>
+            </div>
+          </div>
+
+          {/* User selector (when target = user) */}
+          {target === "user" && (
+            <div>
+              <label className="block text-xs font-medium text-text-muted uppercase tracking-wide mb-1.5">
+                Select User
+              </label>
+              <select
+                value={selectedUserId}
+                onChange={(e) => setSelectedUserId(e.target.value)}
+                className="w-full bg-admin-elevated border border-admin-border rounded-lg px-3 py-2 text-sm text-text-primary
+                  focus:outline-none focus:ring-2 focus:ring-primary/50 focus:border-primary/30"
+              >
+                <option value="">Choose a user...</option>
+                {usersData?.map((user) => (
+                  <option key={user._id} value={user._id}>
+                    {user.name} ({user.email})
+                  </option>
+                ))}
+              </select>
+            </div>
+          )}
+
+          {/* Title */}
+          <div>
+            <label className="block text-xs font-medium text-text-muted uppercase tracking-wide mb-1.5">
+              Title
+            </label>
+            <input
+              type="text"
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+              placeholder="e.g. New Feature Available!"
+              maxLength={100}
+              className="w-full bg-admin-elevated border border-admin-border rounded-lg px-3 py-2 text-sm text-text-primary placeholder:text-text-muted/50
+                focus:outline-none focus:ring-2 focus:ring-primary/50 focus:border-primary/30"
+            />
+            <p className="text-xs text-text-muted mt-1 text-right">
+              {title.length}/100
+            </p>
+          </div>
+
+          {/* Body */}
+          <div>
+            <label className="block text-xs font-medium text-text-muted uppercase tracking-wide mb-1.5">
+              Body
+            </label>
+            <textarea
+              value={body}
+              onChange={(e) => setBody(e.target.value)}
+              placeholder="e.g. We've added new halal food categories. Check it out!"
+              maxLength={500}
+              rows={3}
+              className="w-full bg-admin-elevated border border-admin-border rounded-lg px-3 py-2 text-sm text-text-primary placeholder:text-text-muted/50
+                focus:outline-none focus:ring-2 focus:ring-primary/50 focus:border-primary/30 resize-none"
+            />
+            <p className="text-xs text-text-muted mt-1 text-right">
+              {body.length}/500
+            </p>
+          </div>
+
+          {/* URL (optional) */}
+          <div>
+            <label className="block text-xs font-medium text-text-muted uppercase tracking-wide mb-1.5">
+              Click URL{" "}
+              <span className="normal-case tracking-normal">(optional)</span>
+            </label>
+            <input
+              type="text"
+              value={url}
+              onChange={(e) => setUrl(e.target.value)}
+              placeholder="/dashboard/changelog"
+              className="w-full bg-admin-elevated border border-admin-border rounded-lg px-3 py-2 text-sm text-text-primary placeholder:text-text-muted/50
+                focus:outline-none focus:ring-2 focus:ring-primary/50 focus:border-primary/30"
+            />
+            <p className="text-xs text-text-muted mt-1">
+              Where users go when they tap the notification. Defaults to
+              /dashboard.
+            </p>
+          </div>
+
+          {/* Preview */}
+          {(title || body) && (
+            <div>
+              <label className="block text-xs font-medium text-text-muted uppercase tracking-wide mb-1.5">
+                Preview
+              </label>
+              <div className="bg-admin-bg border border-admin-border-subtle rounded-xl p-4 flex items-start gap-3">
+                <div className="w-10 h-10 rounded-lg bg-primary/15 border border-primary/25 flex items-center justify-center shrink-0 mt-0.5">
+                  <svg
+                    width="18"
+                    height="18"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    className="text-primary-light"
+                  >
+                    <path
+                      d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                </div>
+                <div className="flex-1 min-w-0">
+                  <p className="text-sm font-semibold text-text-primary">
+                    {title || "Notification Title"}
+                  </p>
+                  <p className="text-xs text-text-secondary mt-0.5 line-clamp-3">
+                    {body || "Notification body text..."}
+                  </p>
+                  <p className="text-xs text-text-muted mt-1.5">Kalori</p>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {/* Error */}
+          {error && (
+            <div className="bg-status-danger-muted/20 border border-status-danger/20 rounded-lg p-3">
+              <p className="text-sm text-status-danger">{error.message}</p>
+            </div>
+          )}
+
+          {/* Send Button */}
+          <div className="pt-2 flex items-center justify-between">
+            <p className="text-xs text-text-muted">
+              {target === "all"
+                ? `Will send to ${stats?.totalSubscriptions ?? 0} subscribed devices`
+                : selectedUserId
+                  ? "Will send to all devices of the selected user"
+                  : "Select a user to send to"}
+            </p>
+            <button
+              onClick={handleSend}
+              disabled={!canSend}
+              className="px-5 py-2.5 bg-primary text-white font-semibold rounded-xl text-sm
+                hover:bg-primary/90 hover:shadow-[0_0_24px_rgba(16,185,129,0.25)] transition-all duration-200
+                disabled:opacity-50 disabled:cursor-not-allowed disabled:hover:shadow-none
+                flex items-center gap-2"
+            >
+              <svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+                <path
+                  d="M22 2L11 13M22 2l-7 20-4-9-9-4 20-7z"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+              </svg>
+              {isSending ? "Sending..." : "Send Notification"}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/kal-admin/src/components/Sidebar.tsx b/packages/kal-admin/src/components/Sidebar.tsx
index 1b24db3..ca36e52 100644
--- a/packages/kal-admin/src/components/Sidebar.tsx
+++ b/packages/kal-admin/src/components/Sidebar.tsx
@@ -152,6 +152,28 @@ const navItems = [
       </svg>
     ),
   },
+  {
+    label: "Notifications",
+    href: "/dashboard/notifications",
+    icon: (
+      <svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+        <path
+          d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M13.73 21a2 2 0 0 1-3.46 0"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </svg>
+    ),
+  },
   {
     label: "Rate Limits",
     href: "/dashboard/settings",
diff --git a/packages/kal-backend/.env.example b/packages/kal-backend/.env.example
index 97efa32..dffb2e5 100644
--- a/packages/kal-backend/.env.example
+++ b/packages/kal-backend/.env.example
@@ -31,4 +31,10 @@ STRIPE_SECRET_KEY=sk_test_...
 STRIPE_WEBHOOK_SECRET=whsec_...
 STRIPE_TIER1_PRICE_ID=price_...
 STRIPE_TIER2_PRICE_ID=price_...
-FRONTEND_URL=http://localhost:3000
\ No newline at end of file
+FRONTEND_URL=http://localhost:3000
+
+# Web Push (VAPID keys)
+# Generate with: npx web-push generate-vapid-keys
+VAPID_PUBLIC_KEY=your-vapid-public-key
+VAPID_PRIVATE_KEY=your-vapid-private-key
+VAPID_SUBJECT=mailto:your-email@example.com
\ No newline at end of file
diff --git a/packages/kal-backend/package.json b/packages/kal-backend/package.json
index fa89024..8db39b0 100644
--- a/packages/kal-backend/package.json
+++ b/packages/kal-backend/package.json
@@ -43,6 +43,7 @@
     "swagger-ui-express": "^5.0.1",
     "ws": "^8.18.3",
     "stripe": "^17.7.0",
+    "web-push": "^3.6.7",
     "zod": "^3.24.1"
   },
   "devDependencies": {
@@ -52,6 +53,7 @@
     "@types/express-session": "^1.18.2",
     "@types/node": "^22.10.2",
     "@types/swagger-ui-express": "^4.1.8",
+    "@types/web-push": "^3.6.4",
     "@types/ws": "^8.18.1",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
diff --git a/packages/kal-backend/src/index.ts b/packages/kal-backend/src/index.ts
index e49396f..631b05a 100644
--- a/packages/kal-backend/src/index.ts
+++ b/packages/kal-backend/src/index.ts
@@ -12,7 +12,7 @@ import { API_BASE_PATH } from "kal-shared";
 import swaggerUi from "swagger-ui-express";
 
 import { createContext } from "./lib/context.js";
-import { connectDB } from "./lib/db.js";
+import { connectDB, getDB } from "./lib/db.js";
 import { logtoConfig, validateLogtoConfig } from "./lib/logto.js";
 import { openApiSpec } from "./lib/openapi.js";
 import {
diff --git a/packages/kal-backend/src/lib/pwa-installs.ts b/packages/kal-backend/src/lib/pwa-installs.ts
new file mode 100644
index 0000000..891ac15
--- /dev/null
+++ b/packages/kal-backend/src/lib/pwa-installs.ts
@@ -0,0 +1,23 @@
+import type { Db } from "mongodb";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface PwaInstallDoc {
+  userId: string | null;
+  platform: "ios" | "android" | "desktop" | "unknown";
+  browser: string;
+  userAgent: string;
+  screenResolution: string;
+  displayMode: string;
+  fingerprint: string;
+  installedAt: Date;
+  updatedAt: Date;
+}
+
+// ─── Collection Helper ───────────────────────────────────────────────────────
+
+const COLLECTION = "pwa_installs";
+
+export function getPwaInstallsCollection(db: Db) {
+  return db.collection<PwaInstallDoc>(COLLECTION);
+}
diff --git a/packages/kal-backend/src/lib/web-push.ts b/packages/kal-backend/src/lib/web-push.ts
new file mode 100644
index 0000000..2a06c98
--- /dev/null
+++ b/packages/kal-backend/src/lib/web-push.ts
@@ -0,0 +1,186 @@
+import webpush from "web-push";
+import type { PushSubscription, SendResult } from "web-push";
+import type { Db } from "mongodb";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface PushSubscriptionDoc {
+  userId: string;
+  endpoint: string;
+  keys: {
+    p256dh: string;
+    auth: string;
+  };
+  userAgent?: string;
+  createdAt: Date;
+}
+
+export interface PushPayload {
+  title: string;
+  body: string;
+  url?: string;
+  icon?: string;
+  badge?: string;
+  tag?: string;
+}
+
+// ─── Initialization ──────────────────────────────────────────────────────────
+
+const VAPID_PUBLIC_KEY = process.env.VAPID_PUBLIC_KEY || "";
+const VAPID_PRIVATE_KEY = process.env.VAPID_PRIVATE_KEY || "";
+const VAPID_SUBJECT = process.env.VAPID_SUBJECT || "mailto:admin@kalori.app";
+
+let initialized = false;
+
+function ensureInitialized(): void {
+  if (initialized) return;
+
+  if (!VAPID_PUBLIC_KEY || !VAPID_PRIVATE_KEY) {
+    console.warn(
+      "[Web Push] VAPID_PUBLIC_KEY or VAPID_PRIVATE_KEY not set. Push notifications will not work."
+    );
+    return;
+  }
+
+  webpush.setVapidDetails(VAPID_SUBJECT, VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY);
+  initialized = true;
+  console.log("[Web Push] Initialized with VAPID credentials");
+}
+
+// ─── Collection Helper ───────────────────────────────────────────────────────
+
+const COLLECTION = "push_subscriptions";
+
+export function getPushCollection(db: Db) {
+  return db.collection<PushSubscriptionDoc>(COLLECTION);
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export function getVapidPublicKey(): string {
+  return VAPID_PUBLIC_KEY;
+}
+
+/**
+ * Send a push notification to a single subscription.
+ * Returns true if sent successfully, false if the subscription is expired/invalid (and was deleted).
+ */
+export async function sendPushNotification(
+  db: Db,
+  subscription: PushSubscriptionDoc,
+  payload: PushPayload
+): Promise<boolean> {
+  ensureInitialized();
+
+  if (!initialized) {
+    console.warn("[Web Push] Not initialized — skipping notification");
+    return false;
+  }
+
+  const pushSubscription: PushSubscription = {
+    endpoint: subscription.endpoint,
+    keys: subscription.keys,
+  };
+
+  const jsonPayload = JSON.stringify({
+    title: payload.title,
+    body: payload.body,
+    url: payload.url || "/dashboard",
+    icon: payload.icon || "/assets/icon-logo-192x192.png",
+    badge: payload.badge || "/assets/icon-logo-192x192.png",
+    tag: payload.tag,
+  });
+
+  try {
+    await webpush.sendNotification(pushSubscription, jsonPayload);
+    return true;
+  } catch (error) {
+    const statusCode = (error as SendResult & { statusCode?: number })
+      .statusCode;
+
+    // 410 Gone or 404 Not Found = subscription expired, remove it
+    if (statusCode === 410 || statusCode === 404) {
+      console.log(
+        `[Web Push] Subscription expired (${statusCode}), removing: ${subscription.endpoint.slice(0, 60)}...`
+      );
+      await getPushCollection(db).deleteOne({
+        endpoint: subscription.endpoint,
+      });
+      return false;
+    }
+
+    console.error("[Web Push] Failed to send notification:", error);
+    return false;
+  }
+}
+
+/**
+ * Broadcast a push notification to all subscribed users.
+ * Returns { sent, failed, expired } counts.
+ */
+export async function broadcastPushNotification(
+  db: Db,
+  payload: PushPayload
+): Promise<{ sent: number; failed: number; expired: number }> {
+  const col = getPushCollection(db);
+  const subscriptions = await col.find({}).toArray();
+
+  let sent = 0;
+  let failed = 0;
+  let expired = 0;
+
+  // Send in batches of 50 to avoid overwhelming the push service
+  const BATCH_SIZE = 50;
+  for (let i = 0; i < subscriptions.length; i += BATCH_SIZE) {
+    const batch = subscriptions.slice(i, i + BATCH_SIZE);
+    const results = await Promise.allSettled(
+      batch.map((sub) => sendPushNotification(db, sub, payload))
+    );
+
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        if (result.value) sent++;
+        else expired++;
+      } else {
+        failed++;
+      }
+    }
+  }
+
+  console.log(
+    `[Web Push] Broadcast complete: ${sent} sent, ${failed} failed, ${expired} expired`
+  );
+  return { sent, failed, expired };
+}
+
+/**
+ * Send a push notification to all devices of a specific user.
+ * Returns { sent, failed, expired } counts.
+ */
+export async function sendPushToUser(
+  db: Db,
+  userId: string,
+  payload: PushPayload
+): Promise<{ sent: number; failed: number; expired: number }> {
+  const col = getPushCollection(db);
+  const subscriptions = await col.find({ userId }).toArray();
+
+  let sent = 0;
+  let failed = 0;
+  let expired = 0;
+
+  const results = await Promise.allSettled(
+    subscriptions.map((sub) => sendPushNotification(db, sub, payload))
+  );
+
+  for (const result of results) {
+    if (result.status === "fulfilled") {
+      if (result.value) sent++;
+      else expired++;
+    } else {
+      failed++;
+    }
+  }
+
+  return { sent, failed, expired };
+}
diff --git a/packages/kal-backend/src/routers/index.ts b/packages/kal-backend/src/routers/index.ts
index 3ef4d64..2921bc2 100644
--- a/packages/kal-backend/src/routers/index.ts
+++ b/packages/kal-backend/src/routers/index.ts
@@ -7,6 +7,8 @@ import { feedbackRouter } from "./feedback.js";
 import { foodRouter } from "./food.js";
 import { halalRouter } from "./halal.js";
 import { platformSettingsRouter } from "./platform-settings.js";
+import { pushRouter } from "./push.js";
+import { pwaRouter } from "./pwa.js";
 import { requestLogsRouter } from "./request-logs.js";
 import { subscriptionRouter } from "./subscription.js";
 import { userRouter } from "./user.js";
@@ -22,6 +24,8 @@ export const appRouter = router({
   requestLogs: requestLogsRouter,
   adminLogs: adminLogsRouter,
   subscription: subscriptionRouter,
+  push: pushRouter,
+  pwa: pwaRouter,
 });
 
 // Export type for client
diff --git a/packages/kal-backend/src/routers/push.ts b/packages/kal-backend/src/routers/push.ts
new file mode 100644
index 0000000..0409885
--- /dev/null
+++ b/packages/kal-backend/src/routers/push.ts
@@ -0,0 +1,187 @@
+import { z } from "zod";
+
+import { protectedProcedure, publicProcedure, router } from "../lib/trpc.js";
+import {
+  broadcastPushNotification,
+  getPushCollection,
+  getVapidPublicKey,
+  sendPushToUser,
+} from "../lib/web-push.js";
+
+// ─── Input Schemas ───────────────────────────────────────────────────────────
+
+const subscribeInput = z.object({
+  endpoint: z.string().url(),
+  keys: z.object({
+    p256dh: z.string().min(1),
+    auth: z.string().min(1),
+  }),
+  userAgent: z.string().optional(),
+});
+
+const unsubscribeInput = z.object({
+  endpoint: z.string().url(),
+});
+
+const sendNotificationInput = z.object({
+  title: z.string().min(1).max(100),
+  body: z.string().min(1).max(500),
+  url: z.string().optional(),
+  tag: z.string().optional(),
+});
+
+const sendToUserInput = sendNotificationInput.extend({
+  userId: z.string().min(1),
+});
+
+const trackPromptEventInput = z.object({
+  action: z.enum(["dismissed", "subscribed"]),
+});
+
+// ─── Router ──────────────────────────────────────────────────────────────────
+
+export const pushRouter = router({
+  /**
+   * Get the VAPID public key (needed by the frontend to subscribe).
+   * Public — no auth required.
+   */
+  getVapidPublicKey: publicProcedure.query(() => {
+    return { vapidPublicKey: getVapidPublicKey() };
+  }),
+
+  /**
+   * Subscribe the current user's device to push notifications.
+   * Requires the user to be logged in.
+   */
+  subscribe: protectedProcedure
+    .input(subscribeInput)
+    .mutation(async ({ ctx, input }) => {
+      const col = getPushCollection(ctx.db);
+
+      // Upsert by endpoint — if same device re-subscribes, update keys
+      await col.updateOne(
+        { endpoint: input.endpoint },
+        {
+          $set: {
+            userId: ctx.userId,
+            endpoint: input.endpoint,
+            keys: input.keys,
+            userAgent: input.userAgent,
+          },
+          $setOnInsert: {
+            createdAt: new Date(),
+          },
+        },
+        { upsert: true }
+      );
+
+      return { success: true };
+    }),
+
+  /**
+   * Unsubscribe a specific device (by endpoint) for the current user.
+   */
+  unsubscribe: protectedProcedure
+    .input(unsubscribeInput)
+    .mutation(async ({ ctx, input }) => {
+      const col = getPushCollection(ctx.db);
+
+      // Only allow users to remove their own subscriptions
+      const result = await col.deleteOne({
+        endpoint: input.endpoint,
+        userId: ctx.userId,
+      });
+
+      return { success: result.deletedCount > 0 };
+    }),
+
+  /**
+   * Check if the current user has any push subscriptions.
+   */
+  getSubscriptionStatus: protectedProcedure.query(async ({ ctx }) => {
+    const col = getPushCollection(ctx.db);
+    const count = await col.countDocuments({ userId: ctx.userId });
+    return { subscribed: count > 0, deviceCount: count };
+  }),
+
+  // ─── Admin-Only Endpoints ────────────────────────────────────────────────
+  // These use publicProcedure because admin auth is handled via x-admin-secret
+  // header in the context layer (same pattern as admin-logs, platform-settings).
+
+  /**
+   * Broadcast a push notification to ALL subscribed users.
+   */
+  sendToAll: publicProcedure
+    .input(sendNotificationInput)
+    .mutation(async ({ ctx, input }) => {
+      const result = await broadcastPushNotification(ctx.db, {
+        title: input.title,
+        body: input.body,
+        url: input.url,
+        tag: input.tag,
+      });
+
+      return result;
+    }),
+
+  /**
+   * Send a push notification to a specific user (all their devices).
+   */
+  sendToUser: publicProcedure
+    .input(sendToUserInput)
+    .mutation(async ({ ctx, input }) => {
+      const result = await sendPushToUser(ctx.db, input.userId, {
+        title: input.title,
+        body: input.body,
+        url: input.url,
+        tag: input.tag,
+      });
+
+      return result;
+    }),
+
+  /**
+   * Track a push prompt interaction (dismissed or subscribed).
+   * Used by PushPermissionPrompt for analytics.
+   */
+  trackPromptEvent: protectedProcedure
+    .input(trackPromptEventInput)
+    .mutation(async ({ ctx, input }) => {
+      const col = ctx.db.collection("push_prompt_events");
+
+      await col.insertOne({
+        userId: ctx.userId,
+        action: input.action,
+        timestamp: new Date(),
+      });
+
+      return { success: true };
+    }),
+
+  /**
+   * Get push notification stats (admin dashboard).
+   */
+  getStats: publicProcedure.query(async ({ ctx }) => {
+    const col = getPushCollection(ctx.db);
+    const promptCol = ctx.db.collection("push_prompt_events");
+
+    const [
+      totalSubscriptions,
+      uniqueUsers,
+      promptsDismissed,
+      promptsConverted,
+    ] = await Promise.all([
+      col.countDocuments(),
+      col.distinct("userId").then((ids) => ids.length),
+      promptCol.countDocuments({ action: "dismissed" }),
+      promptCol.countDocuments({ action: "subscribed" }),
+    ]);
+
+    return {
+      totalSubscriptions,
+      uniqueUsers,
+      promptsDismissed,
+      promptsConverted,
+    };
+  }),
+});
diff --git a/packages/kal-backend/src/routers/pwa.ts b/packages/kal-backend/src/routers/pwa.ts
new file mode 100644
index 0000000..442c293
--- /dev/null
+++ b/packages/kal-backend/src/routers/pwa.ts
@@ -0,0 +1,138 @@
+import { z } from "zod";
+
+import { getPwaInstallsCollection } from "../lib/pwa-installs.js";
+import { publicProcedure, router } from "../lib/trpc.js";
+
+// ─── Input Schemas ───────────────────────────────────────────────────────────
+
+const trackInstallInput = z.object({
+  platform: z.enum(["ios", "android", "desktop", "unknown"]),
+  browser: z.string().min(1).max(50),
+  userAgent: z.string().max(500),
+  screenResolution: z.string().max(20),
+  displayMode: z.string().max(30),
+  fingerprint: z.string().min(1).max(128),
+});
+
+// ─── Router ──────────────────────────────────────────────────────────────────
+
+export const pwaRouter = router({
+  /**
+   * Track a PWA install event.
+   * Public — works for both anonymous and authenticated users.
+   * Upserts by fingerprint to deduplicate same-device installs.
+   */
+  trackInstall: publicProcedure
+    .input(trackInstallInput)
+    .mutation(async ({ ctx, input }) => {
+      const col = getPwaInstallsCollection(ctx.db);
+      const now = new Date();
+
+      // userId is available if the user is logged in (from context)
+      const userId = ctx.userId ?? null;
+
+      await col.updateOne(
+        { fingerprint: input.fingerprint },
+        {
+          $set: {
+            // Update userId if user is now logged in (was previously anonymous)
+            ...(userId ? { userId } : {}),
+            userAgent: input.userAgent,
+            updatedAt: now,
+          },
+          $setOnInsert: {
+            // Only set these on first insert
+            ...(userId ? {} : { userId: null }),
+            platform: input.platform,
+            browser: input.browser,
+            screenResolution: input.screenResolution,
+            displayMode: input.displayMode,
+            fingerprint: input.fingerprint,
+            installedAt: now,
+          },
+        },
+        { upsert: true }
+      );
+
+      return { success: true };
+    }),
+
+  /**
+   * Get PWA install statistics (admin dashboard).
+   * Uses publicProcedure — admin auth is handled via x-admin-secret header.
+   */
+  getStats: publicProcedure.query(async ({ ctx }) => {
+    const col = getPwaInstallsCollection(ctx.db);
+
+    // Run aggregations in parallel
+    const [totalInstalls, platformBreakdown, browserBreakdown, dailyInstalls] =
+      await Promise.all([
+        // Total installs
+        col.countDocuments(),
+
+        // Breakdown by platform
+        col
+          .aggregate<{
+            _id: string;
+            count: number;
+          }>([{ $group: { _id: "$platform", count: { $sum: 1 } } }, { $sort: { count: -1 } }])
+          .toArray(),
+
+        // Breakdown by browser
+        col
+          .aggregate<{
+            _id: string;
+            count: number;
+          }>([{ $group: { _id: "$browser", count: { $sum: 1 } } }, { $sort: { count: -1 } }])
+          .toArray(),
+
+        // Daily installs for last 30 days
+        col
+          .aggregate<{ _id: string; count: number }>([
+            {
+              $match: {
+                installedAt: {
+                  $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+                },
+              },
+            },
+            {
+              $group: {
+                _id: {
+                  $dateToString: {
+                    format: "%Y-%m-%d",
+                    date: "$installedAt",
+                  },
+                },
+                count: { $sum: 1 },
+              },
+            },
+            { $sort: { _id: 1 } },
+          ])
+          .toArray(),
+      ]);
+
+    // Count unique authenticated users (non-null userId)
+    const authenticatedInstalls = await col.countDocuments({
+      userId: { $ne: null },
+    });
+
+    return {
+      totalInstalls,
+      authenticatedInstalls,
+      anonymousInstalls: totalInstalls - authenticatedInstalls,
+      platformBreakdown: platformBreakdown.map((p) => ({
+        platform: p._id,
+        count: p.count,
+      })),
+      browserBreakdown: browserBreakdown.map((b) => ({
+        browser: b._id,
+        count: b.count,
+      })),
+      dailyInstalls: dailyInstalls.map((d) => ({
+        date: d._id,
+        count: d.count,
+      })),
+    };
+  }),
+});
diff --git a/packages/kal-db/migrations/20260411000001_create_push_subscriptions.js b/packages/kal-db/migrations/20260411000001_create_push_subscriptions.js
new file mode 100644
index 0000000..908958c
--- /dev/null
+++ b/packages/kal-db/migrations/20260411000001_create_push_subscriptions.js
@@ -0,0 +1,61 @@
+/**
+ * Migration: Create push_subscriptions collection
+ *
+ * Stores Web Push API subscriptions for each user/device.
+ * Used by the push notification system to send OS-level notifications.
+ *
+ * Indexes:
+ * - endpoint_unique: fast lookup + deduplication by push endpoint URL
+ * - user_id: find all subscriptions for a given user
+ */
+
+export const up = async (db, _client) => {
+  // Create push_subscriptions collection
+  const collections = await db
+    .listCollections({ name: "push_subscriptions" })
+    .toArray();
+  if (collections.length === 0) {
+    await db.createCollection("push_subscriptions");
+    console.log("✅ Created push_subscriptions collection");
+  } else {
+    console.log("ℹ️  push_subscriptions collection already exists");
+  }
+
+  // Drop any pre-existing auto-named indexes (from ensurePushIndexes at startup)
+  // so we can recreate them with proper names
+  const col = db.collection("push_subscriptions");
+  try {
+    await col.dropIndex("endpoint_1");
+    console.log("ℹ️  Dropped legacy endpoint_1 index");
+  } catch (_) {
+    // Index doesn't exist — that's fine
+  }
+  try {
+    await col.dropIndex("userId_1");
+    console.log("ℹ️  Dropped legacy userId_1 index");
+  } catch (_) {
+    // Index doesn't exist — that's fine
+  }
+
+  // Unique index on endpoint — each push endpoint is globally unique
+  await col.createIndex(
+    { endpoint: 1 },
+    { unique: true, name: "endpoint_unique" }
+  );
+  console.log("✅ Created endpoint_unique index");
+
+  // Index for finding all subscriptions by user
+  await col.createIndex({ userId: 1 }, { name: "user_id" });
+  console.log("✅ Created user_id index");
+};
+
+export const down = async (db, _client) => {
+  try {
+    await db.collection("push_subscriptions").drop();
+    console.log("✅ Dropped push_subscriptions collection");
+  } catch (e) {
+    console.log(
+      "ℹ️  push_subscriptions collection may not exist, skipping drop"
+    );
+  }
+};
diff --git a/packages/kal-db/migrations/20260411000002_create_pwa_installs.js b/packages/kal-db/migrations/20260411000002_create_pwa_installs.js
new file mode 100644
index 0000000..a0e9c27
--- /dev/null
+++ b/packages/kal-db/migrations/20260411000002_create_pwa_installs.js
@@ -0,0 +1,62 @@
+/**
+ * Migration: Create pwa_installs collection
+ *
+ * Tracks when users install the PWA (add to home screen).
+ * Captures platform, browser, and device info for analytics.
+ * Uses a fingerprint field to deduplicate installs from the same device.
+ *
+ * Indexes:
+ * - fingerprint_unique: prevent duplicate installs from the same device
+ * - user_id: find installs by user (nullable — anonymous installs allowed)
+ * - installed_at_desc: chronological queries / recent installs
+ * - platform: filter/aggregate by platform (ios, android, desktop)
+ */
+
+export const up = async (db, _client) => {
+  // Create pwa_installs collection
+  const collections = await db
+    .listCollections({ name: "pwa_installs" })
+    .toArray();
+  if (collections.length === 0) {
+    await db.createCollection("pwa_installs");
+    console.log("✅ Created pwa_installs collection");
+  } else {
+    console.log("ℹ️  pwa_installs collection already exists");
+  }
+
+  // Unique index on fingerprint — deduplicate same-device installs
+  await db
+    .collection("pwa_installs")
+    .createIndex(
+      { fingerprint: 1 },
+      { unique: true, name: "fingerprint_unique" }
+    );
+  console.log("✅ Created fingerprint_unique index");
+
+  // Index for finding installs by user
+  await db
+    .collection("pwa_installs")
+    .createIndex({ userId: 1 }, { name: "user_id" });
+  console.log("✅ Created user_id index");
+
+  // Index for chronological queries (newest first)
+  await db
+    .collection("pwa_installs")
+    .createIndex({ installedAt: -1 }, { name: "installed_at_desc" });
+  console.log("✅ Created installed_at_desc index");
+
+  // Index for platform breakdown queries
+  await db
+    .collection("pwa_installs")
+    .createIndex({ platform: 1 }, { name: "platform" });
+  console.log("✅ Created platform index");
+};
+
+export const down = async (db, _client) => {
+  try {
+    await db.collection("pwa_installs").drop();
+    console.log("✅ Dropped pwa_installs collection");
+  } catch (e) {
+    console.log("ℹ️  pwa_installs collection may not exist, skipping drop");
+  }
+};
diff --git a/packages/kal-frontend/.env.example b/packages/kal-frontend/.env.example
index 8f7d18d..b012ab2 100644
--- a/packages/kal-frontend/.env.example
+++ b/packages/kal-frontend/.env.example
@@ -19,3 +19,7 @@ NEXT_PUBLIC_DEMO_API_KEY=kal_660e99df8cb78a60d8cc90dcb1228b1a812283d1393f0e49918
 
 # Stripe
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# Web Push (VAPID public key only — private key stays on backend)
+# Must match VAPID_PUBLIC_KEY in kal-backend .env
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=your-vapid-public-key
diff --git a/packages/kal-frontend/next.config.mjs b/packages/kal-frontend/next.config.mjs
index c3ea5ec..5595993 100644
--- a/packages/kal-frontend/next.config.mjs
+++ b/packages/kal-frontend/next.config.mjs
@@ -11,6 +11,7 @@ const withSerwist = withSerwistInit({
 const nextConfig = {
   reactStrictMode: true,
   transpilePackages: ["kal-shared"],
+  allowedDevOrigins: ["192.168.100.69"],
   async headers() {
     return [
       {
diff --git a/packages/kal-frontend/public/apple-touch-icon-precomposed.png b/packages/kal-frontend/public/apple-touch-icon-precomposed.png
new file mode 100644
index 0000000000000000000000000000000000000000..fbe5076a8cd4d86f3eed76db9aa07f5a0c8e9d7b
GIT binary patch
literal 5368
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
Q{Xu7P!ptB~&oTIa08#ZYHvj+t

literal 0
HcmV?d00001

diff --git a/packages/kal-frontend/public/apple-touch-icon.png b/packages/kal-frontend/public/apple-touch-icon.png
new file mode 100644
index 0000000000000000000000000000000000000000..fbe5076a8cd4d86f3eed76db9aa07f5a0c8e9d7b
GIT binary patch
literal 5368
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
Q{Xu7P!ptB~&oTIa08#ZYHvj+t

literal 0
HcmV?d00001

diff --git a/packages/kal-frontend/src/app/dashboard/settings/client.tsx b/packages/kal-frontend/src/app/dashboard/settings/client.tsx
index 106f931..184a9e7 100644
--- a/packages/kal-frontend/src/app/dashboard/settings/client.tsx
+++ b/packages/kal-frontend/src/app/dashboard/settings/client.tsx
@@ -1,11 +1,13 @@
 "use client";
 
 import { RATE_LIMITS } from "kal-shared";
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import Link from "next/link";
 import { useSearchParams } from "next/navigation";
-import { useEffect, useMemo } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import {
   AlertTriangle,
+  Bell,
   Clock,
   CreditCard,
   ExternalLink,
@@ -19,7 +21,19 @@ import {
   Zap,
 } from "react-feather";
 
+import {
+  pushIosNotInstalledAtom,
+  pushPermissionAtom,
+  pushSubscribedAtom,
+  pushSupportedAtom,
+} from "@/atoms/push-state";
 import { AuthUpdater, useAuth } from "@/lib/auth-context";
+import {
+  getPermissionState,
+  subscribeToPush,
+  unsubscribeFromPush,
+  serializeSubscription,
+} from "@/lib/push-notifications";
 import { trpc } from "@/lib/trpc";
 
 interface SettingsClientProps {
@@ -521,6 +535,9 @@ function SettingsContent({
           </div>
         </div>
 
+        {/* ─── ROW 4: Push Notifications (spans full width) ─── */}
+        <PushNotificationCard />
+
         {/* ─── MOBILE ONLY: Resources Card (Changelog + Feedback) ─── */}
         <div className="md:hidden md:col-span-2 bg-white/[0.02] border border-white/[0.06] rounded-xl p-5 hover:border-white/[0.1] transition-all duration-200">
           {/* Card header */}
@@ -565,3 +582,134 @@ function SettingsContent({
     </div>
   );
 }
+
+/* ================================================================
+   Push Notification Card — toggle subscription
+   ================================================================ */
+function PushNotificationCard() {
+  // Read shared push state from PushStateProvider atoms
+  const supported = useAtomValue(pushSupportedAtom);
+  const [subscribed, setSubscribed] = useAtom(pushSubscribedAtom);
+  const [permission, setPermission] = useAtom(pushPermissionAtom);
+  const iosNotInstalled = useAtomValue(pushIosNotInstalledAtom);
+  const [loading, setLoading] = useState(false);
+
+  const { data: vapidData } = trpc.push.getVapidPublicKey.useQuery(undefined, {
+    enabled: supported,
+  });
+  const subscribeMutation = trpc.push.subscribe.useMutation();
+  const unsubscribeMutation = trpc.push.unsubscribe.useMutation();
+
+  const handleToggle = useCallback(async () => {
+    if (loading) return;
+    setLoading(true);
+
+    try {
+      if (subscribed) {
+        // Unsubscribe
+        const endpoint = await unsubscribeFromPush();
+        if (endpoint) {
+          await unsubscribeMutation.mutateAsync({ endpoint });
+        }
+        setSubscribed(false);
+      } else {
+        // Subscribe
+        if (!vapidData?.vapidPublicKey) {
+          console.error("[Push] No VAPID public key available");
+          return;
+        }
+
+        const subscription = await subscribeToPush(vapidData.vapidPublicKey);
+        if (subscription) {
+          const serialized = serializeSubscription(subscription);
+          await subscribeMutation.mutateAsync({
+            endpoint: serialized.endpoint,
+            keys: serialized.keys,
+            userAgent: navigator.userAgent,
+          });
+          setSubscribed(true);
+        }
+
+        // Update permission state after request
+        setPermission(getPermissionState());
+      }
+    } catch (error) {
+      console.error("[Push] Toggle failed:", error);
+    } finally {
+      setLoading(false);
+    }
+  }, [loading, subscribed, vapidData, subscribeMutation, unsubscribeMutation, setSubscribed, setPermission]);
+
+  // Don't render if push is not supported at all
+  if (!supported) return null;
+
+  const isDenied = permission === "denied";
+
+  return (
+    <div className="md:col-span-2 bg-white/[0.02] border border-white/[0.06] rounded-xl p-5 md:p-6 hover:border-white/[0.1] transition-all duration-200">
+      {/* Card header */}
+      <div className="flex items-center gap-2 mb-5">
+        <div className="w-7 h-7 rounded-lg bg-accent/[0.08] flex items-center justify-center">
+          <Bell size={14} className="text-accent/70" />
+        </div>
+        <h2 className="text-xs font-semibold text-content-muted uppercase tracking-wider">
+          Push Notifications
+        </h2>
+      </div>
+
+      <div className="flex items-center justify-between gap-4">
+        <div className="flex items-center gap-3 flex-1">
+          <div className="w-10 h-10 rounded-xl bg-accent/[0.06] flex items-center justify-center flex-shrink-0">
+            <Bell
+              size={18}
+              className={subscribed ? "text-accent" : "text-content-secondary"}
+            />
+          </div>
+          <div>
+            <p className="text-content-primary text-sm font-medium">
+              {subscribed
+                ? "Notifications enabled"
+                : "Enable push notifications"}
+            </p>
+            <p className="text-content-muted text-xs mt-0.5">
+              {isDenied
+                ? "Notifications are blocked. Please allow them in your browser settings."
+                : iosNotInstalled
+                  ? "On iOS, install the app to your Home Screen first to enable notifications."
+                  : subscribed
+                    ? "You will receive important updates even when the app is closed."
+                    : "Get notified about important updates and announcements."}
+            </p>
+          </div>
+        </div>
+
+        {/* Toggle switch */}
+        <button
+          onClick={handleToggle}
+          disabled={loading || isDenied || iosNotInstalled}
+          className={`relative inline-flex h-7 w-12 items-center rounded-full transition-colors duration-200 focus:outline-none focus:ring-2 focus:ring-accent/40 focus:ring-offset-2 focus:ring-offset-transparent
+            ${subscribed ? "bg-accent" : "bg-white/[0.1]"}
+            ${loading || isDenied || iosNotInstalled ? "opacity-50 cursor-not-allowed" : "cursor-pointer"}`}
+          aria-label={
+            subscribed ? "Disable notifications" : "Enable notifications"
+          }
+        >
+          <span
+            className={`inline-block h-5 w-5 rounded-full bg-white shadow-md transition-transform duration-200
+              ${subscribed ? "translate-x-6" : "translate-x-1"}`}
+          />
+        </button>
+      </div>
+
+      {/* Status indicator */}
+      {subscribed && (
+        <div className="mt-4 pt-3 border-t border-white/[0.06] flex items-center gap-2">
+          <div className="w-2 h-2 rounded-full bg-green-500 animate-pulse" />
+          <span className="text-xs text-content-muted">
+            This device is receiving notifications
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/kal-frontend/src/app/globals.css b/packages/kal-frontend/src/app/globals.css
index c6e1d10..025beef 100644
--- a/packages/kal-frontend/src/app/globals.css
+++ b/packages/kal-frontend/src/app/globals.css
@@ -1205,3 +1205,9 @@ html {
     0 0 40px rgba(16, 185, 129, 0.1),
     0 0 80px rgba(16, 185, 129, 0.05);
 }
+
+/* PWA splash — breathing icon animation */
+@keyframes breathe {
+  0%, 100% { transform: scale(1); opacity: 0.7; }
+  50% { transform: scale(1.08); opacity: 1; }
+}
diff --git a/packages/kal-frontend/src/app/layout.tsx b/packages/kal-frontend/src/app/layout.tsx
index 94727b2..c68e01a 100644
--- a/packages/kal-frontend/src/app/layout.tsx
+++ b/packages/kal-frontend/src/app/layout.tsx
@@ -2,7 +2,11 @@ import type { Metadata, Viewport } from "next";
 import { JetBrains_Mono, Space_Grotesk } from "next/font/google";
 
 import "./globals.css";
+import { BreakpointProvider } from "@/components/BreakpointProvider";
 import { ChatWidget } from "@/components/chat/ChatWidget";
+import { PushPermissionPrompt } from "@/components/PushPermissionPrompt";
+import { PushStateProvider } from "@/components/PushStateProvider";
+import { PwaInstallTracker } from "@/components/PwaInstallTracker";
 import { ScrollProvider } from "@/components/ScrollProvider";
 import { ToastContainer } from "@/components/ui/Toast";
 import { ToastProvider } from "@/contexts/ToastContext";
@@ -71,21 +75,12 @@ export const metadata: Metadata = {
     title: "Kalori API - Malaysian Food Nutrition Database",
     description:
       "Free API for Malaysian food nutrition data. 1000+ foods with calories, protein, carbs & fat. Build amazing health apps!",
-    images: [
-      {
-        url: "/og-image.png",
-        width: 1200,
-        height: 630,
-        alt: "Kalori API - Malaysian Food Nutrition Database",
-      },
-    ],
   },
   twitter: {
     card: "summary_large_image",
     title: "Kalori API - Malaysian Food Nutrition Database",
     description:
       "Free API for Malaysian food nutrition data. 1000+ foods with calories, protein, carbs & fat.",
-    images: ["/og-image.png"],
   },
   robots: {
     index: true,
@@ -117,6 +112,10 @@ export default function RootLayout({
         <ToastProvider>
           <AuthProvider logtoId={null}>
             <TRPCProvider>
+              <BreakpointProvider />
+              <PushStateProvider />
+              <PwaInstallTracker />
+              <PushPermissionPrompt />
               <div className="flex h-screen overflow-hidden">
                 {/* Main content — scrollable, takes remaining space */}
                 <ScrollProvider>{children}</ScrollProvider>
diff --git a/packages/kal-frontend/src/app/page.tsx b/packages/kal-frontend/src/app/page.tsx
index 846e34a..aafd7ff 100644
--- a/packages/kal-frontend/src/app/page.tsx
+++ b/packages/kal-frontend/src/app/page.tsx
@@ -1,3 +1,4 @@
+import { getLogtoContext } from "@logto/next/server-actions";
 import { signIn } from "@logto/next/server-actions";
 
 import { FinalCTA } from "@/components/landing/CTA";
@@ -8,17 +9,68 @@ import { Hero } from "@/components/landing/Hero";
 import { HowItWorks } from "@/components/landing/HowItWorks";
 import { Navbar } from "@/components/landing/Navbar";
 import { ProblemSolution } from "@/components/landing/ProblemSolution";
+import { PwaAuthRedirect } from "@/components/PwaAuthRedirect";
 import { SampleFoods } from "@/components/landing/SampleFoods";
 import { Testimonials } from "@/components/landing/Testimonials";
 import { getLogtoConfig } from "@/lib/logto";
 
 export default async function LandingPage() {
+  const config = getLogtoConfig();
+  const { isAuthenticated } = await getLogtoContext(config);
+
   const onSignIn = async () => {
     "use server";
     const config = getLogtoConfig();
     await signIn(config);
   };
 
+  // Authenticated users: server-render the splash screen (breathing icon)
+  // so it's visible from first paint — before any JS loads.
+  // PwaAuthRedirect layers on top after hydration:
+  //   - PWA (standalone): keeps splash visible, redirects to /dashboard
+  //   - Desktop/browser: hides splash, reveals the landing page fallback
+  if (isAuthenticated) {
+    return (
+      <main className="min-h-screen bg-dark relative overflow-hidden">
+        {/* Server-rendered splash — visible from first paint, no JS needed */}
+        <div className="fixed inset-0 z-40 flex items-center justify-center bg-dark">
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img
+            src="/assets/icon-svg.svg"
+            alt=""
+            width={80}
+            height={80}
+            className="animate-breathe"
+            style={{ filter: "drop-shadow(0 0 24px rgba(16,185,129,0.3))" }}
+          />
+        </div>
+
+        {/* Client component takes over after hydration (z-50 sits above z-40) */}
+        <PwaAuthRedirect isAuthenticated fallback={
+          <>
+            {/* Background Effects */}
+            <div className="fixed inset-0 pointer-events-none">
+              <div className="absolute top-0 transform -translate-x-1/2 left-1/2 w-[1000px] h-[500px] bg-accent/5 blur-[120px] rounded-full animate-float-slow" />
+              <div className="absolute bottom-0 transform translate-x-1/2 right-1/2 w-[800px] h-[600px] bg-accent/5 blur-[120px] rounded-full animate-float-slower" />
+              <div className="absolute inset-0 dot-grid" />
+              <div className="absolute top-0 bottom-0 left-1/2 w-px bg-gradient-to-b from-transparent via-accent/[0.07] to-transparent" />
+            </div>
+            <Navbar onSignIn={onSignIn} />
+            <Hero />
+            <ProblemSolution />
+            <HowItWorks />
+            <Features />
+            <SampleFoods />
+            <Testimonials />
+            <FAQ />
+            <FinalCTA />
+            <Footer />
+          </>
+        } />
+      </main>
+    );
+  }
+
   return (
     <main className="min-h-screen bg-dark relative overflow-hidden">
       {/* Background Effects */}
diff --git a/packages/kal-frontend/src/app/sw.ts b/packages/kal-frontend/src/app/sw.ts
index f9cf617..3a1b187 100644
--- a/packages/kal-frontend/src/app/sw.ts
+++ b/packages/kal-frontend/src/app/sw.ts
@@ -21,3 +21,65 @@ const serwist = new Serwist({
 });
 
 serwist.addEventListeners();
+
+// ─── Push Notification Handlers ──────────────────────────────────────────────
+
+self.addEventListener("push", (event) => {
+  if (!event.data) return;
+
+  let data: {
+    title?: string;
+    body?: string;
+    url?: string;
+    icon?: string;
+    badge?: string;
+    tag?: string;
+  };
+
+  try {
+    data = event.data.json();
+  } catch {
+    data = { title: "Kalori", body: event.data.text() };
+  }
+
+  const title = data.title || "Kalori";
+  // eslint-disable-next-line no-undef
+  const options: NotificationOptions & { vibrate?: number[] } = {
+    body: data.body || "",
+    icon: data.icon || "/assets/icon-logo-192x192.png",
+    badge: data.badge || "/assets/icon-logo-192x192.png",
+    tag: data.tag || "kalori-notification",
+    data: {
+      url: data.url || "/dashboard",
+    },
+    // Vibrate pattern for mobile: vibrate 200ms, pause 100ms, vibrate 200ms
+    vibrate: [200, 100, 200],
+  };
+
+  event.waitUntil(self.registration.showNotification(title, options));
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+
+  const targetUrl =
+    (event.notification.data as { url?: string })?.url || "/dashboard";
+
+  // Focus an existing window if possible, otherwise open a new one
+  event.waitUntil(
+    self.clients
+      .matchAll({ type: "window", includeUncontrolled: true })
+      .then((clientList) => {
+        // Try to find an existing window/tab and focus it
+        for (const client of clientList) {
+          if (client.url.includes(self.location.origin) && "focus" in client) {
+            client.focus();
+            client.navigate(targetUrl);
+            return;
+          }
+        }
+        // No existing window, open a new one
+        return self.clients.openWindow(targetUrl);
+      })
+  );
+});
diff --git a/packages/kal-frontend/src/atoms/breakpoint.ts b/packages/kal-frontend/src/atoms/breakpoint.ts
new file mode 100644
index 0000000..4e2930c
--- /dev/null
+++ b/packages/kal-frontend/src/atoms/breakpoint.ts
@@ -0,0 +1,85 @@
+import { atom } from "jotai";
+
+// ---------------------------------------------------------------------------
+// Breakpoint Definitions
+// ---------------------------------------------------------------------------
+
+export type Breakpoint = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
+export type ScreenCategory = "mobile" | "tablet" | "desktop" | "wide" | "ultrawide";
+
+export const BREAKPOINTS: Record<Breakpoint, number> = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536,
+  "3xl": 1920,
+  "4xl": 2560,
+};
+
+// ---------------------------------------------------------------------------
+// Primitive Atoms (written by BreakpointProvider)
+// ---------------------------------------------------------------------------
+
+/** Current window.innerWidth — default 1024 for SSR-safe desktop fallback */
+export const windowWidthAtom = atom(1024);
+
+/** Whether the client has mounted (hydrated) */
+export const breakpointMountedAtom = atom(false);
+
+// ---------------------------------------------------------------------------
+// Derived: Breakpoint Info (read-only)
+// ---------------------------------------------------------------------------
+
+function getBreakpoint(width: number): Breakpoint | "xs" {
+  if (width >= BREAKPOINTS["4xl"]) return "4xl";
+  if (width >= BREAKPOINTS["3xl"]) return "3xl";
+  if (width >= BREAKPOINTS["2xl"]) return "2xl";
+  if (width >= BREAKPOINTS.xl) return "xl";
+  if (width >= BREAKPOINTS.lg) return "lg";
+  if (width >= BREAKPOINTS.md) return "md";
+  if (width >= BREAKPOINTS.sm) return "sm";
+  return "xs";
+}
+
+function getScreenCategory(width: number): ScreenCategory {
+  if (width >= BREAKPOINTS["4xl"]) return "ultrawide";
+  if (width >= BREAKPOINTS["3xl"]) return "wide";
+  if (width >= BREAKPOINTS.lg) return "desktop";
+  if (width >= BREAKPOINTS.md) return "tablet";
+  return "mobile";
+}
+
+/** Full breakpoint state — same shape as the old useBreakpoint() return */
+export const breakpointAtom = atom((get) => {
+  const width = get(windowWidthAtom);
+  const isMounted = get(breakpointMountedAtom);
+
+  return {
+    breakpoint: getBreakpoint(width),
+    isMobile: isMounted && width < BREAKPOINTS.md,
+    isTablet: isMounted && width >= BREAKPOINTS.md && width < BREAKPOINTS.lg,
+    isDesktop: !isMounted || width >= BREAKPOINTS.lg, // Default to desktop for SSR
+    isWideScreen: isMounted && width >= BREAKPOINTS["3xl"],
+    isUltraWide: isMounted && width >= BREAKPOINTS["4xl"],
+    screenCategory: isMounted ? getScreenCategory(width) : ("desktop" as ScreenCategory),
+    width,
+    isMounted,
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Derived: Sidebar Layout (read-only)
+// ---------------------------------------------------------------------------
+
+/** Sidebar-specific layout state — same shape as the old useSidebarLayout() return */
+export const sidebarLayoutAtom = atom((get) => {
+  const { isMobile, isTablet, isMounted } = get(breakpointAtom);
+
+  return {
+    isMobile,
+    shouldAutoCollapse: isMounted && (isMobile || isTablet),
+    defaultCollapsed: isTablet,
+    isMounted,
+  };
+});
diff --git a/packages/kal-frontend/src/atoms/push-prompt.ts b/packages/kal-frontend/src/atoms/push-prompt.ts
new file mode 100644
index 0000000..e297912
--- /dev/null
+++ b/packages/kal-frontend/src/atoms/push-prompt.ts
@@ -0,0 +1,11 @@
+import { atom } from "jotai";
+
+// ---------------------------------------------------------------------------
+// Push Permission Prompt State
+// ---------------------------------------------------------------------------
+
+/** Whether the push permission bottom sheet is visible */
+export const pushPromptVisibleAtom = atom(false);
+
+/** Whether we've already evaluated prompt conditions this session */
+export const pushPromptCheckedAtom = atom(false);
diff --git a/packages/kal-frontend/src/atoms/push-state.ts b/packages/kal-frontend/src/atoms/push-state.ts
new file mode 100644
index 0000000..2c60d93
--- /dev/null
+++ b/packages/kal-frontend/src/atoms/push-state.ts
@@ -0,0 +1,20 @@
+import { atom } from "jotai";
+
+// ---------------------------------------------------------------------------
+// Push Notification State (shared between PushPermissionPrompt + Settings)
+// ---------------------------------------------------------------------------
+
+/** Whether the browser supports push notifications (PushManager + Notification APIs) */
+export const pushSupportedAtom = atom(false);
+
+/** Current notification permission state */
+export const pushPermissionAtom = atom<NotificationPermission | "unsupported">("default");
+
+/** Whether the user is currently subscribed to push notifications */
+export const pushSubscribedAtom = atom(false);
+
+/** iOS-specific: PWA not installed to home screen (push won't work) */
+export const pushIosNotInstalledAtom = atom(false);
+
+/** Whether the initial async capability check has completed */
+export const pushStateCheckedAtom = atom(false);
diff --git a/packages/kal-frontend/src/atoms/pwa.ts b/packages/kal-frontend/src/atoms/pwa.ts
new file mode 100644
index 0000000..5e1f5bc
--- /dev/null
+++ b/packages/kal-frontend/src/atoms/pwa.ts
@@ -0,0 +1,41 @@
+import { atom } from "jotai";
+
+import { breakpointMountedAtom } from "@/atoms/breakpoint";
+import { isStandaloneMode } from "@/lib/pwa-install-tracker";
+
+// ---------------------------------------------------------------------------
+// Standalone Mode Detection (derived from BreakpointProvider hydration)
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether the app is running in PWA standalone mode.
+ *
+ * - `null` before client hydration (breakpointMountedAtom is false)
+ * - `true` / `false` after hydration
+ *
+ * Reads breakpointMountedAtom so it waits for the BreakpointProvider
+ * to signal that the client has mounted before calling isStandaloneMode().
+ */
+export const pwaStandaloneAtom = atom<boolean | null>((get) => {
+  const mounted = get(breakpointMountedAtom);
+  if (!mounted) return null; // SSR / pre-hydration
+  return isStandaloneMode();
+});
+
+// ---------------------------------------------------------------------------
+// PWA Install Tracking State
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether the PWA install has been tracked in this session.
+ * Separate from localStorage — this prevents duplicate calls within a single
+ * React lifecycle while allowing re-tracking when auth state changes.
+ */
+export const pwaInstallTrackedAtom = atom(false);
+
+/**
+ * The userId that was used for the last track call.
+ * null = tracked as anonymous, undefined = never tracked.
+ * When auth changes from null → string, we know to re-track.
+ */
+export const pwaTrackedUserIdAtom = atom<string | null | undefined>(undefined);
diff --git a/packages/kal-frontend/src/components/BreakpointProvider.tsx b/packages/kal-frontend/src/components/BreakpointProvider.tsx
new file mode 100644
index 0000000..d55533b
--- /dev/null
+++ b/packages/kal-frontend/src/components/BreakpointProvider.tsx
@@ -0,0 +1,32 @@
+"use client";
+
+import { useSetAtom } from "jotai";
+import { useEffect } from "react";
+
+import { breakpointMountedAtom, windowWidthAtom } from "@/atoms/breakpoint";
+
+/**
+ * BreakpointProvider
+ *
+ * Invisible component that sets up a single global resize listener
+ * and writes the current window width to jotai atoms.
+ *
+ * Render once in layout.tsx — all consumers read from shared atoms
+ * via useBreakpoint() / useSidebarLayout(), eliminating duplicate listeners.
+ */
+export function BreakpointProvider() {
+  const setWidth = useSetAtom(windowWidthAtom);
+  const setMounted = useSetAtom(breakpointMountedAtom);
+
+  useEffect(() => {
+    setMounted(true);
+    setWidth(window.innerWidth);
+
+    const handleResize = () => setWidth(window.innerWidth);
+    window.addEventListener("resize", handleResize);
+
+    return () => window.removeEventListener("resize", handleResize);
+  }, [setWidth, setMounted]);
+
+  return null;
+}
diff --git a/packages/kal-frontend/src/components/PushPermissionPrompt.tsx b/packages/kal-frontend/src/components/PushPermissionPrompt.tsx
new file mode 100644
index 0000000..dcc1b02
--- /dev/null
+++ b/packages/kal-frontend/src/components/PushPermissionPrompt.tsx
@@ -0,0 +1,210 @@
+"use client";
+
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Bell } from "react-feather";
+
+import { pushPromptCheckedAtom, pushPromptVisibleAtom } from "@/atoms/push-prompt";
+import {
+  pushPermissionAtom,
+  pushStateCheckedAtom,
+  pushSubscribedAtom,
+  pushSupportedAtom,
+} from "@/atoms/push-state";
+import { useAuth } from "@/lib/auth-context";
+import { serializeSubscription, subscribeToPush } from "@/lib/push-notifications";
+import {
+  recordDismissal,
+  recordSubscription,
+  shouldShowPrompt,
+} from "@/lib/push-prompt-storage";
+import { isStandaloneMode } from "@/lib/pwa-install-tracker";
+import { trpc } from "@/lib/trpc";
+
+const SHOW_DELAY_MS = 2000;
+
+/**
+ * PushPermissionPrompt
+ *
+ * Bottom-sheet overlay that prompts PWA users to enable push notifications.
+ * Reads push capability from shared atoms (set by PushStateProvider).
+ *
+ * Renders nothing unless ALL conditions are met:
+ * - Running in standalone mode (installed PWA)
+ * - User is authenticated
+ * - Push is supported (requires HTTPS — won't work on HTTP LAN IPs)
+ * - Permission is "default" (not granted/denied)
+ * - localStorage throttle passes (7-day cooldown, max 3 dismissals)
+ * - Not already subscribed
+ *
+ * Must be rendered inside <AuthProvider> and <TRPCProvider>.
+ */
+export function PushPermissionPrompt() {
+  const { logtoId } = useAuth();
+  const [visible, setVisible] = useAtom(pushPromptVisibleAtom);
+  const [promptChecked, setPromptChecked] = useAtom(pushPromptCheckedAtom);
+  const [animateIn, setAnimateIn] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Shared push state from PushStateProvider
+  const pushStateReady = useAtomValue(pushStateCheckedAtom);
+  const supported = useAtomValue(pushSupportedAtom);
+  const permission = useAtomValue(pushPermissionAtom);
+  const subscribed = useAtomValue(pushSubscribedAtom);
+  const setSubscribed = useSetAtom(pushSubscribedAtom);
+  const setPermission = useSetAtom(pushPermissionAtom);
+
+  const { data: vapidData } = trpc.push.getVapidPublicKey.useQuery(undefined, {
+    enabled: visible,
+  });
+  const subscribeMutation = trpc.push.subscribe.useMutation();
+  const trackEvent = trpc.push.trackPromptEvent.useMutation();
+
+  // ── Condition check: should we show the prompt? ───────────────────────────
+  useEffect(() => {
+    if (typeof window === "undefined" || promptChecked) return;
+    if (!logtoId) return;
+    if (!pushStateReady) return;
+
+    // Mark as checked immediately to prevent re-runs
+    setPromptChecked(true);
+
+    const standalone = isStandaloneMode();
+    const throttleOk = shouldShowPrompt();
+
+    if (!standalone) return;
+    if (!supported) return;
+    if (permission !== "default") return;
+    if (!throttleOk) return;
+    if (subscribed) return;
+
+    // All passed — show after delay
+    timerRef.current = setTimeout(() => {
+      setVisible(true);
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          setAnimateIn(true);
+        });
+      });
+    }, SHOW_DELAY_MS);
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [logtoId, promptChecked, pushStateReady, supported, permission, subscribed, setVisible, setPromptChecked]);
+
+  // ── Dismiss handler ──────────────────────────────────────────────────────
+  const handleDismiss = useCallback(() => {
+    setAnimateIn(false);
+    setTimeout(() => setVisible(false), 300);
+
+    recordDismissal();
+    trackEvent.mutate({ action: "dismissed" });
+  }, [setVisible, trackEvent]);
+
+  // ── Enable handler ───────────────────────────────────────────────────────
+  const handleEnable = useCallback(async () => {
+    if (loading || !vapidData?.vapidPublicKey) return;
+    setLoading(true);
+
+    try {
+      const subscription = await subscribeToPush(vapidData.vapidPublicKey);
+
+      if (subscription) {
+        const serialized = serializeSubscription(subscription);
+        await subscribeMutation.mutateAsync({
+          endpoint: serialized.endpoint,
+          keys: serialized.keys,
+          userAgent: navigator.userAgent,
+        });
+
+        // Update shared atoms so Settings toggle reflects immediately
+        setSubscribed(true);
+        setPermission("granted");
+
+        recordSubscription();
+        trackEvent.mutate({ action: "subscribed" });
+      }
+
+      setAnimateIn(false);
+      setTimeout(() => setVisible(false), 300);
+    } catch (err) {
+      console.warn("[PushPrompt] Failed to subscribe:", err);
+      setAnimateIn(false);
+      setTimeout(() => setVisible(false), 300);
+    } finally {
+      setLoading(false);
+    }
+  }, [loading, vapidData, subscribeMutation, trackEvent, setVisible, setSubscribed, setPermission]);
+
+  if (!visible) return null;
+
+  return (
+    <>
+      {/* Backdrop */}
+      <div
+        className={`fixed inset-0 z-[9998] bg-black/60 backdrop-blur-sm transition-opacity duration-300 ${
+          animateIn ? "opacity-100" : "opacity-0"
+        }`}
+        onClick={handleDismiss}
+      />
+
+      {/* Bottom Sheet */}
+      <div
+        className={`fixed bottom-0 left-0 right-0 z-[9999] transition-transform duration-300 ease-out ${
+          animateIn ? "translate-y-0" : "translate-y-full"
+        }`}
+      >
+        <div className="mx-auto max-w-lg">
+          <div className="bg-[#141414] border border-white/[0.08] rounded-t-2xl p-6 shadow-[0_-4px_32px_rgba(0,0,0,0.4)]">
+            {/* Icon */}
+            <div className="flex justify-center mb-4">
+              <div className="w-14 h-14 rounded-2xl bg-emerald-500/[0.1] border border-emerald-500/20 flex items-center justify-center">
+                <Bell size={24} className="text-emerald-400" />
+              </div>
+            </div>
+
+            {/* Text */}
+            <div className="text-center mb-6">
+              <h3 className="text-lg font-semibold text-white mb-1.5">
+                Stay Updated
+              </h3>
+              <p className="text-sm text-white/50 leading-relaxed">
+                Get notified about new features, updates, and important
+                announcements — even when the app is closed.
+              </p>
+            </div>
+
+            {/* Buttons */}
+            <div className="flex flex-col gap-3">
+              <button
+                onClick={handleEnable}
+                disabled={loading}
+                className="w-full py-3 px-4 bg-emerald-500 hover:bg-emerald-400 text-white font-semibold rounded-xl text-sm
+                  transition-all duration-200 hover:shadow-[0_0_24px_rgba(16,185,129,0.25)]
+                  disabled:opacity-50 disabled:cursor-not-allowed
+                  flex items-center justify-center gap-2"
+              >
+                <Bell size={16} />
+                {loading ? "Enabling..." : "Enable Notifications"}
+              </button>
+
+              <button
+                onClick={handleDismiss}
+                disabled={loading}
+                className="w-full py-3 px-4 text-white/40 hover:text-white/60 font-medium rounded-xl text-sm
+                  transition-colors duration-200"
+              >
+                Not Now
+              </button>
+            </div>
+
+            {/* Bottom safe area spacer for iOS */}
+            <div className="h-[env(safe-area-inset-bottom,0px)]" />
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}
diff --git a/packages/kal-frontend/src/components/PushStateProvider.tsx b/packages/kal-frontend/src/components/PushStateProvider.tsx
new file mode 100644
index 0000000..6e7199f
--- /dev/null
+++ b/packages/kal-frontend/src/components/PushStateProvider.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { useSetAtom } from "jotai";
+import { useEffect } from "react";
+
+import {
+  pushIosNotInstalledAtom,
+  pushPermissionAtom,
+  pushStateCheckedAtom,
+  pushSubscribedAtom,
+  pushSupportedAtom,
+} from "@/atoms/push-state";
+import {
+  getPermissionState,
+  isIOS,
+  isPushSupported,
+  isStandalone,
+  isSubscribed,
+} from "@/lib/push-notifications";
+
+/**
+ * PushStateProvider
+ *
+ * Invisible component that runs push notification capability checks once
+ * on mount and writes results to shared jotai atoms.
+ *
+ * Both PushPermissionPrompt and Settings PushNotificationCard read
+ * from these atoms instead of running their own duplicate checks.
+ *
+ * Render once in layout.tsx.
+ */
+export function PushStateProvider() {
+  const setSupported = useSetAtom(pushSupportedAtom);
+  const setPermission = useSetAtom(pushPermissionAtom);
+  const setSubscribed = useSetAtom(pushSubscribedAtom);
+  const setIosNotInstalled = useSetAtom(pushIosNotInstalledAtom);
+  const setChecked = useSetAtom(pushStateCheckedAtom);
+
+  useEffect(() => {
+    const check = async () => {
+      const supported = isPushSupported();
+      setSupported(supported);
+      setPermission(getPermissionState());
+      setIosNotInstalled(isIOS() && !isStandalone());
+
+      if (supported) {
+        const sub = await isSubscribed();
+        setSubscribed(sub);
+      }
+
+      setChecked(true);
+    };
+
+    check();
+  }, [setSupported, setPermission, setSubscribed, setIosNotInstalled, setChecked]);
+
+  return null;
+}
diff --git a/packages/kal-frontend/src/components/PwaAuthRedirect.tsx b/packages/kal-frontend/src/components/PwaAuthRedirect.tsx
new file mode 100644
index 0000000..4aba1ef
--- /dev/null
+++ b/packages/kal-frontend/src/components/PwaAuthRedirect.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import { useAtomValue } from "jotai";
+import { useRouter } from "next/navigation";
+import { useEffect, useRef, type ReactNode } from "react";
+
+import { pwaStandaloneAtom } from "@/atoms/pwa";
+
+/**
+ * PwaAuthRedirect
+ *
+ * Works with the server-rendered splash in page.tsx for a seamless cold start.
+ *
+ * page.tsx (server) renders the breathing icon at z-40 — visible from first paint.
+ * This client component renders at z-50 — sits on top after hydration:
+ *
+ *   - standalone === null  → still hydrating, render nothing (server splash shows through)
+ *   - standalone === true  → PWA: render nothing (server splash shows), fire redirect
+ *   - standalone === false → desktop: render fallback (covers server splash)
+ *   - !isAuthenticated     → render fallback immediately
+ *
+ * State is derived entirely from jotai atoms — no useState needed.
+ * The only useEffect handles the imperative router.replace() call.
+ */
+export function PwaAuthRedirect({
+  isAuthenticated,
+  fallback,
+}: {
+  isAuthenticated: boolean;
+  fallback?: ReactNode;
+}) {
+  const router = useRouter();
+  const standalone = useAtomValue(pwaStandaloneAtom);
+  const redirected = useRef(false);
+
+  // Imperative redirect — can't be done in render, needs useEffect
+  useEffect(() => {
+    if (!isAuthenticated) return;
+    if (standalone !== true) return;
+    if (redirected.current) return;
+
+    redirected.current = true;
+    router.replace("/dashboard");
+  }, [isAuthenticated, standalone, router]);
+
+  // Unauthenticated: show fallback (covers server splash with z-50)
+  if (!isAuthenticated) {
+    return <div className="relative z-50">{fallback}</div>;
+  }
+
+  // Hydrating (standalone === null): render nothing — server splash at z-40 shows through
+  if (standalone === null) return null;
+
+  // PWA standalone: render nothing — server splash stays visible while redirect fires
+  if (standalone === true) return null;
+
+  // Desktop/browser: show the landing page (covers server splash with z-50)
+  return <div className="relative z-50">{fallback}</div>;
+}
diff --git a/packages/kal-frontend/src/components/PwaInstallTracker.tsx b/packages/kal-frontend/src/components/PwaInstallTracker.tsx
new file mode 100644
index 0000000..f40d52c
--- /dev/null
+++ b/packages/kal-frontend/src/components/PwaInstallTracker.tsx
@@ -0,0 +1,132 @@
+"use client";
+
+import { useAtom } from "jotai";
+import { useCallback, useEffect, useRef } from "react";
+
+import { pwaInstallTrackedAtom, pwaTrackedUserIdAtom } from "@/atoms/pwa";
+import { useAuth } from "@/lib/auth-context";
+import {
+  detectBrowser,
+  detectPlatform,
+  generateFingerprint,
+  getDisplayMode,
+  getScreenResolution,
+  isStandaloneMode,
+  PWA_INSTALL_TRACKED_KEY,
+} from "@/lib/pwa-install-tracker";
+import { trpc } from "@/lib/trpc";
+
+/**
+ * PwaInstallTracker
+ *
+ * Invisible component that detects PWA installs and reports them to the backend.
+ * Must be rendered inside <TRPCProvider> and <AuthProvider>.
+ *
+ * Detection strategies:
+ * 1. On mount: check if running in standalone mode (covers iOS + Chromium)
+ * 2. Listen for `appinstalled` event (Chromium browsers fire this at install time)
+ * 3. On auth change: re-track to claim anonymous installs for the logged-in user
+ *
+ * Uses a jotai atom to track the userId used for the last call, so when auth
+ * transitions from null → userId we re-call trackInstall (the backend upserts
+ * by fingerprint and updates the userId).
+ *
+ * localStorage is used only to persist across page reloads — it stores the
+ * userId that was last tracked so we know whether a re-track is needed.
+ */
+export function PwaInstallTracker() {
+  const trackInstall = trpc.pwa.trackInstall.useMutation();
+  const { logtoId } = useAuth();
+  const [installTracked, setInstallTracked] = useAtom(pwaInstallTrackedAtom);
+  const [trackedUserId, setTrackedUserId] = useAtom(pwaTrackedUserIdAtom);
+  const isTracking = useRef(false);
+
+  const track = useCallback(async () => {
+    if (typeof window === "undefined" || isTracking.current) return;
+
+    isTracking.current = true;
+
+    try {
+      const ua = navigator.userAgent;
+      const fingerprint = await generateFingerprint();
+
+      await trackInstall.mutateAsync({
+        platform: detectPlatform(ua),
+        browser: detectBrowser(ua),
+        userAgent: ua.slice(0, 500),
+        screenResolution: getScreenResolution(),
+        displayMode: getDisplayMode(),
+        fingerprint,
+      });
+
+      // Persist: store which userId we tracked with
+      localStorage.setItem(
+        PWA_INSTALL_TRACKED_KEY,
+        JSON.stringify({ userId: logtoId ?? null })
+      );
+
+      setInstallTracked(true);
+      setTrackedUserId(logtoId ?? null);
+    } catch (err) {
+      console.warn("[PWA Install Tracker] Failed to track install:", err);
+    } finally {
+      isTracking.current = false;
+    }
+  }, [trackInstall, logtoId, setInstallTracked, setTrackedUserId]);
+
+  // ── Strategy 1 & 2: Initial detect + appinstalled event ─────────────────
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    // Hydrate atom state from localStorage on first mount
+    const stored = localStorage.getItem(PWA_INSTALL_TRACKED_KEY);
+    if (stored) {
+      try {
+        const parsed = JSON.parse(stored) as { userId: string | null };
+        setInstallTracked(true);
+        setTrackedUserId(parsed.userId);
+      } catch {
+        // Legacy format ("true") — treat as anonymous tracked
+        setInstallTracked(true);
+        setTrackedUserId(null);
+      }
+    }
+
+    // Detect standalone mode on mount
+    if (isStandaloneMode() && !stored) {
+      track();
+    }
+
+    // Listen for Chromium appinstalled event
+    const handleAppInstalled = () => {
+      track();
+    };
+    window.addEventListener("appinstalled", handleAppInstalled);
+
+    return () => {
+      window.removeEventListener("appinstalled", handleAppInstalled);
+    };
+    // Only run on mount for initial detection + event listener setup
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // ── Strategy 3: Claim anonymous install when user logs in ───────────────
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    // Only re-track if:
+    // 1. We have an authenticated user now
+    // 2. The install was previously tracked as anonymous (trackedUserId is null)
+    // 3. We're in standalone mode (it's a real PWA install)
+    if (
+      logtoId &&
+      installTracked &&
+      trackedUserId === null &&
+      isStandaloneMode()
+    ) {
+      track();
+    }
+  }, [logtoId, installTracked, trackedUserId, track]);
+
+  return null;
+}
diff --git a/packages/kal-frontend/src/hooks/useBreakpoint.ts b/packages/kal-frontend/src/hooks/useBreakpoint.ts
index 24468f3..6cf1f6e 100644
--- a/packages/kal-frontend/src/hooks/useBreakpoint.ts
+++ b/packages/kal-frontend/src/hooks/useBreakpoint.ts
@@ -1,29 +1,20 @@
 "use client";
 
+import { useAtomValue } from "jotai";
 import { useState, useEffect } from "react";
 
-type Breakpoint = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
-type ScreenCategory = "mobile" | "tablet" | "desktop" | "wide" | "ultrawide";
-
-const breakpoints: Record<Breakpoint, number> = {
-  sm: 640,
-  md: 768,
-  lg: 1024,
-  xl: 1280,
-  "2xl": 1536,
-  "3xl": 1920,  // Full HD / 2K with scaling
-  "4xl": 2560,  // 2K native / 4K with scaling
-};
+import { breakpointAtom, sidebarLayoutAtom } from "@/atoms/breakpoint";
 
 /**
- * Hook to detect if the viewport matches a media query
+ * Hook to detect if the viewport matches a media query.
+ * Standalone — does NOT use the breakpoint atoms (different concern).
  */
 export function useMediaQuery(query: string): boolean {
   const [matches, setMatches] = useState(false);
 
   useEffect(() => {
     const media = window.matchMedia(query);
-    
+
     // Set initial value
     setMatches(media.matches);
 
@@ -38,9 +29,11 @@ export function useMediaQuery(query: string): boolean {
 }
 
 /**
- * Hook to detect current breakpoint
- * Returns default desktop values on server, updates on client after mount
- * 
+ * Hook to detect current breakpoint.
+ *
+ * Reads from shared jotai atoms (set by BreakpointProvider in layout.tsx).
+ * No local useState or useEffect — all consumers share a single resize listener.
+ *
  * Breakpoints:
  * - xs: < 640px (mobile portrait)
  * - sm: 640px+ (mobile landscape)
@@ -51,81 +44,14 @@ export function useMediaQuery(query: string): boolean {
  * - 3xl: 1920px+ (1080p full / 2K scaled)
  * - 4xl: 2560px+ (2K native / 4K scaled)
  */
-export function useBreakpoint(): {
-  breakpoint: Breakpoint | "xs";
-  isMobile: boolean;
-  isTablet: boolean;
-  isDesktop: boolean;
-  isWideScreen: boolean;   // 1920px+ (3xl)
-  isUltraWide: boolean;    // 2560px+ (4xl)
-  screenCategory: ScreenCategory;
-  width: number;
-  isMounted: boolean;
-} {
-  const [isMounted, setIsMounted] = useState(false);
-  const [width, setWidth] = useState(1024); // Default to desktop width for SSR
-
-  useEffect(() => {
-    // Mark as mounted first
-    setIsMounted(true);
-    
-    // Set actual width
-    setWidth(window.innerWidth);
-
-    const handleResize = () => setWidth(window.innerWidth);
-    window.addEventListener("resize", handleResize);
-    return () => window.removeEventListener("resize", handleResize);
-  }, []);
-
-  const getBreakpoint = (): Breakpoint | "xs" => {
-    if (width >= breakpoints["4xl"]) return "4xl";
-    if (width >= breakpoints["3xl"]) return "3xl";
-    if (width >= breakpoints["2xl"]) return "2xl";
-    if (width >= breakpoints.xl) return "xl";
-    if (width >= breakpoints.lg) return "lg";
-    if (width >= breakpoints.md) return "md";
-    if (width >= breakpoints.sm) return "sm";
-    return "xs";
-  };
-
-  const getScreenCategory = (): ScreenCategory => {
-    if (width >= breakpoints["4xl"]) return "ultrawide";
-    if (width >= breakpoints["3xl"]) return "wide";
-    if (width >= breakpoints.lg) return "desktop";
-    if (width >= breakpoints.md) return "tablet";
-    return "mobile";
-  };
-
-  const breakpoint = getBreakpoint();
-
-  return {
-    breakpoint,
-    isMobile: isMounted && width < breakpoints.md,
-    isTablet: isMounted && width >= breakpoints.md && width < breakpoints.lg,
-    isDesktop: !isMounted || width >= breakpoints.lg, // Default to desktop for SSR
-    isWideScreen: isMounted && width >= breakpoints["3xl"],
-    isUltraWide: isMounted && width >= breakpoints["4xl"],
-    screenCategory: isMounted ? getScreenCategory() : "desktop",
-    width,
-    isMounted,
-  };
+export function useBreakpoint() {
+  return useAtomValue(breakpointAtom);
 }
 
 /**
- * Hook specifically for sidebar/layout behavior
+ * Hook specifically for sidebar/layout behavior.
+ * Reads from shared jotai atoms.
  */
-export function useSidebarLayout(): {
-  isMobile: boolean;
-  shouldAutoCollapse: boolean;
-  defaultCollapsed: boolean;
-  isMounted: boolean;
-} {
-  const { isMobile, isTablet, isMounted } = useBreakpoint();
-
-  return {
-    isMobile,
-    shouldAutoCollapse: isMounted && (isMobile || isTablet),
-    defaultCollapsed: isTablet,
-    isMounted,
-  };
+export function useSidebarLayout() {
+  return useAtomValue(sidebarLayoutAtom);
 }
diff --git a/packages/kal-frontend/src/lib/push-notifications.ts b/packages/kal-frontend/src/lib/push-notifications.ts
new file mode 100644
index 0000000..2da29a1
--- /dev/null
+++ b/packages/kal-frontend/src/lib/push-notifications.ts
@@ -0,0 +1,191 @@
+/**
+ * Push Notifications Utility
+ *
+ * Handles the full lifecycle of PWA push notification subscription:
+ * - Check browser support
+ * - Request permission
+ * - Subscribe via PushManager (using VAPID key)
+ * - Send subscription to backend via tRPC
+ * - Unsubscribe
+ */
+
+// ─── Feature Detection ──────────────────────────────────────────────────────
+
+/** Check if the browser supports push notifications */
+export function isPushSupported(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    "serviceWorker" in navigator &&
+    "PushManager" in window &&
+    "Notification" in window
+  );
+}
+
+/** Check if we're on iOS (requires PWA to be installed to Home Screen) */
+export function isIOS(): boolean {
+  if (typeof navigator === "undefined") return false;
+  return (
+    /iPad|iPhone|iPod/.test(navigator.userAgent) && !("MSStream" in window)
+  );
+}
+
+/** Check if the PWA is running in standalone mode (installed) */
+export function isStandalone(): boolean {
+  if (typeof window === "undefined") return false;
+  return (
+    window.matchMedia("(display-mode: standalone)").matches ||
+    ("standalone" in navigator &&
+      (navigator as unknown as { standalone: boolean }).standalone === true)
+  );
+}
+
+/** Get the current notification permission state */
+// eslint-disable-next-line no-undef
+export function getPermissionState(): NotificationPermission | "unsupported" {
+  if (!isPushSupported()) return "unsupported";
+  return Notification.permission;
+}
+
+// ─── VAPID Key ───────────────────────────────────────────────────────────────
+
+/**
+ * Convert a base64 URL-encoded VAPID public key to a Uint8Array
+ * (required by PushManager.subscribe)
+ */
+function urlBase64ToUint8Array(base64String: string): ArrayBuffer {
+  const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const rawData = window.atob(base64);
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; ++i) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+  return outputArray.buffer as ArrayBuffer;
+}
+
+// ─── Subscription Management ─────────────────────────────────────────────────
+
+/** Get the active push subscription (if any) */
+export async function getExistingSubscription(): Promise<PushSubscription | null> {
+  if (!isPushSupported()) return null;
+
+  try {
+    const registration = await navigator.serviceWorker.ready;
+    return await registration.pushManager.getSubscription();
+  } catch {
+    return null;
+  }
+}
+
+/** Check if the user is currently subscribed to push notifications */
+export async function isSubscribed(): Promise<boolean> {
+  const sub = await getExistingSubscription();
+  return sub !== null;
+}
+
+/**
+ * Request notification permission from the user.
+ * Returns the resulting permission state.
+ */
+// eslint-disable-next-line no-undef
+export async function requestPermission(): Promise<NotificationPermission> {
+  if (!isPushSupported()) return "denied";
+  return Notification.requestPermission();
+}
+
+/**
+ * Subscribe to push notifications.
+ *
+ * Flow:
+ * 1. Request notification permission
+ * 2. Wait for service worker to be ready
+ * 3. Subscribe via PushManager with VAPID public key
+ * 4. Return the PushSubscription object (caller sends to backend)
+ *
+ * @param vapidPublicKey - The VAPID public key from the backend
+ * @returns The PushSubscription, or null if the user denied permission
+ */
+export async function subscribeToPush(
+  vapidPublicKey: string
+): Promise<PushSubscription | null> {
+  if (!isPushSupported()) {
+    console.warn("[Push] Push notifications not supported in this browser");
+    return null;
+  }
+
+  // iOS check: must be installed as PWA
+  if (isIOS() && !isStandalone()) {
+    console.warn(
+      "[Push] On iOS, push notifications require the PWA to be installed to the Home Screen"
+    );
+    return null;
+  }
+
+  // Request permission
+  const permission = await requestPermission();
+  if (permission !== "granted") {
+    console.info("[Push] Permission not granted:", permission);
+    return null;
+  }
+
+  try {
+    const registration = await navigator.serviceWorker.ready;
+
+    // Check if already subscribed
+    const existingSub = await registration.pushManager.getSubscription();
+    if (existingSub) {
+      console.info(
+        "[Push] Already subscribed, returning existing subscription"
+      );
+      return existingSub;
+    }
+
+    // Subscribe with VAPID key
+    const subscription = await registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: urlBase64ToUint8Array(vapidPublicKey),
+    });
+
+    console.info("[Push] Successfully subscribed");
+    return subscription;
+  } catch (error) {
+    console.error("[Push] Failed to subscribe:", error);
+    return null;
+  }
+}
+
+/**
+ * Unsubscribe from push notifications.
+ * Returns the endpoint that was unsubscribed (for backend cleanup).
+ */
+export async function unsubscribeFromPush(): Promise<string | null> {
+  try {
+    const subscription = await getExistingSubscription();
+    if (!subscription) return null;
+
+    const endpoint = subscription.endpoint;
+    await subscription.unsubscribe();
+    console.info("[Push] Successfully unsubscribed");
+    return endpoint;
+  } catch (error) {
+    console.error("[Push] Failed to unsubscribe:", error);
+    return null;
+  }
+}
+
+/**
+ * Extract the subscription data in the format the backend expects.
+ */
+export function serializeSubscription(sub: PushSubscription): {
+  endpoint: string;
+  keys: { p256dh: string; auth: string };
+} {
+  const json = sub.toJSON();
+  return {
+    endpoint: sub.endpoint,
+    keys: {
+      p256dh: json.keys?.p256dh || "",
+      auth: json.keys?.auth || "",
+    },
+  };
+}
diff --git a/packages/kal-frontend/src/lib/push-prompt-storage.ts b/packages/kal-frontend/src/lib/push-prompt-storage.ts
new file mode 100644
index 0000000..951a388
--- /dev/null
+++ b/packages/kal-frontend/src/lib/push-prompt-storage.ts
@@ -0,0 +1,86 @@
+/**
+ * Push Prompt Storage
+ *
+ * Manages localStorage state for the push notification permission prompt.
+ * Controls throttling so we don't nag users:
+ * - 7-day cooldown after each dismissal
+ * - Max 3 lifetime dismissals, then stop permanently
+ * - Track if user subscribed via prompt (never show again)
+ */
+
+const STORAGE_KEY = "push-prompt-state";
+
+interface PushPromptState {
+  dismissCount: number;
+  lastDismissedAt: number | null;
+  subscribedViaPrompt: boolean;
+}
+
+const DEFAULT_STATE: PushPromptState = {
+  dismissCount: 0,
+  lastDismissedAt: null,
+  subscribedViaPrompt: false,
+};
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const MAX_DISMISSALS = 3;
+const COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// ─── Read / Write ───────────────────────────────────────────────────────────
+
+function getState(): PushPromptState {
+  if (typeof window === "undefined") return DEFAULT_STATE;
+
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return DEFAULT_STATE;
+    return { ...DEFAULT_STATE, ...JSON.parse(raw) };
+  } catch {
+    return DEFAULT_STATE;
+  }
+}
+
+function setState(state: PushPromptState): void {
+  if (typeof window === "undefined") return;
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/** Check if the push prompt should be shown (passes all throttle checks) */
+export function shouldShowPrompt(): boolean {
+  const state = getState();
+
+  // Already subscribed via this prompt — never show again
+  if (state.subscribedViaPrompt) return false;
+
+  // Hit lifetime dismissal cap
+  if (state.dismissCount >= MAX_DISMISSALS) return false;
+
+  // Within 7-day cooldown
+  if (state.lastDismissedAt && Date.now() - state.lastDismissedAt < COOLDOWN_MS) {
+    return false;
+  }
+
+  return true;
+}
+
+/** Record that the user dismissed the prompt */
+export function recordDismissal(): void {
+  const state = getState();
+  setState({
+    ...state,
+    dismissCount: state.dismissCount + 1,
+    lastDismissedAt: Date.now(),
+  });
+}
+
+/** Record that the user subscribed via the prompt */
+export function recordSubscription(): void {
+  const state = getState();
+  setState({
+    ...state,
+    subscribedViaPrompt: true,
+  });
+}
diff --git a/packages/kal-frontend/src/lib/pwa-install-tracker.ts b/packages/kal-frontend/src/lib/pwa-install-tracker.ts
new file mode 100644
index 0000000..7e27469
--- /dev/null
+++ b/packages/kal-frontend/src/lib/pwa-install-tracker.ts
@@ -0,0 +1,136 @@
+/**
+ * PWA Install Tracking Utilities
+ *
+ * Detects standalone/installed mode, identifies platform and browser,
+ * and generates a device fingerprint for deduplication.
+ */
+
+// ─── Platform Detection ──────────────────────────────────────────────────────
+
+export function detectPlatform(
+  ua: string
+): "ios" | "android" | "desktop" | "unknown" {
+  const lower = ua.toLowerCase();
+
+  if (/iphone|ipad|ipod/.test(lower)) return "ios";
+  if (/android/.test(lower)) return "android";
+  if (/windows|macintosh|mac os|linux/.test(lower)) return "desktop";
+
+  return "unknown";
+}
+
+// ─── Browser Detection ───────────────────────────────────────────────────────
+
+export function detectBrowser(ua: string): string {
+  const lower = ua.toLowerCase();
+
+  // Order matters — more specific checks first
+  if (/samsungbrowser/.test(lower)) return "samsung";
+  if (/edg(e|a|ios)?\//.test(lower)) return "edge";
+  if (/opr\/|opera/.test(lower)) return "opera";
+  if (/firefox|fxios/.test(lower)) return "firefox";
+  if (/crios/.test(lower)) return "chrome"; // Chrome on iOS
+  if (/chrome|chromium/.test(lower)) return "chrome";
+  if (/safari/.test(lower)) return "safari";
+
+  return "unknown";
+}
+
+// ─── Standalone Mode Detection ───────────────────────────────────────────────
+
+export function isStandaloneMode(): boolean {
+  if (typeof window === "undefined") return false;
+
+  // iOS Safari: navigator.standalone
+  if (
+    "standalone" in navigator &&
+    (navigator as { standalone?: boolean }).standalone === true
+  ) {
+    return true;
+  }
+
+  // Chromium-based: display-mode media query
+  if (window.matchMedia("(display-mode: standalone)").matches) {
+    return true;
+  }
+
+  // Also check fullscreen and minimal-ui (other PWA display modes)
+  if (window.matchMedia("(display-mode: fullscreen)").matches) {
+    return true;
+  }
+
+  if (window.matchMedia("(display-mode: minimal-ui)").matches) {
+    return true;
+  }
+
+  return false;
+}
+
+// ─── Display Mode Detection ──────────────────────────────────────────────────
+
+export function getDisplayMode(): string {
+  if (typeof window === "undefined") return "unknown";
+
+  if (
+    "standalone" in navigator &&
+    (navigator as { standalone?: boolean }).standalone === true
+  ) {
+    return "standalone"; // iOS
+  }
+
+  if (window.matchMedia("(display-mode: fullscreen)").matches)
+    return "fullscreen";
+  if (window.matchMedia("(display-mode: standalone)").matches)
+    return "standalone";
+  if (window.matchMedia("(display-mode: minimal-ui)").matches)
+    return "minimal-ui";
+
+  return "browser";
+}
+
+// ─── Screen Resolution ───────────────────────────────────────────────────────
+
+export function getScreenResolution(): string {
+  if (typeof window === "undefined") return "unknown";
+  return `${window.screen.width}x${window.screen.height}`;
+}
+
+// ─── Fingerprint Generation ──────────────────────────────────────────────────
+
+/**
+ * Generate a simple device fingerprint for deduplication.
+ * Uses a hash of user agent + screen dimensions + platform + pixel ratio.
+ * Not meant to be cryptographically secure — just unique enough
+ * to prevent the same device from being counted twice.
+ */
+export async function generateFingerprint(): Promise<string> {
+  const parts = [
+    navigator.userAgent,
+    `${window.screen.width}x${window.screen.height}`,
+    `${window.devicePixelRatio}`,
+    detectPlatform(navigator.userAgent),
+    navigator.language,
+  ].join("|");
+
+  // Use SubtleCrypto for hashing (available in secure contexts / localhost)
+  if (crypto?.subtle) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(parts);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+
+  // Fallback: simple string hash
+  let hash = 0;
+  for (let i = 0; i < parts.length; i++) {
+    const char = parts.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash |= 0; // Convert to 32bit integer
+  }
+  return `fallback-${Math.abs(hash).toString(36)}`;
+}
+
+// ─── LocalStorage Key ────────────────────────────────────────────────────────
+
+export const PWA_INSTALL_TRACKED_KEY = "pwa-install-tracked";
diff --git a/packages/kal-frontend/tailwind.config.ts b/packages/kal-frontend/tailwind.config.ts
index 7309b04..df76a77 100644
--- a/packages/kal-frontend/tailwind.config.ts
+++ b/packages/kal-frontend/tailwind.config.ts
@@ -48,6 +48,7 @@ const config: Config = {
         "float-slow": "floatSlow 20s ease-in-out infinite",
         "float-slower": "floatSlower 25s ease-in-out infinite",
         "gradient-border": "gradientBorder 3s linear infinite",
+        breathe: "breathe 2s ease-in-out infinite",
       },
       keyframes: {
         fadeIn: {
@@ -91,6 +92,10 @@ const config: Config = {
           "50%": { backgroundPosition: "100% 50%" },
           "100%": { backgroundPosition: "0% 50%" },
         },
+        breathe: {
+          "0%, 100%": { transform: "scale(1)", opacity: "0.7" },
+          "50%": { transform: "scale(1.08)", opacity: "1" },
+        },
       },
     },
   },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dacc025..20998ab 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -156,6 +156,9 @@ importers:
       swagger-ui-express:
         specifier: ^5.0.1
         version: 5.0.1(express@4.22.1)
+      web-push:
+        specifier: ^3.6.7
+        version: 3.6.7
       ws:
         specifier: ^8.18.3
         version: 8.18.3
@@ -181,6 +184,9 @@ importers:
       '@types/swagger-ui-express':
         specifier: ^4.1.8
         version: 4.1.8
+      '@types/web-push':
+        specifier: ^3.6.4
+        version: 3.6.4
       '@types/ws':
         specifier: ^8.18.1
         version: 8.18.1
@@ -1241,6 +1247,9 @@ packages:
   '@types/unist@3.0.3':
     resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
 
+  '@types/web-push@3.6.4':
+    resolution: {integrity: sha512-GnJmSr40H3RAnj0s34FNTcJi1hmWFV5KXugE0mYWnYhgTAHLJ/dJKAwDmvPJYMke0RplY2XE9LnM4hqSqKIjhQ==}
+
   '@types/webidl-conversions@7.0.3':
     resolution: {integrity: sha512-CiJJvcRtIgzadHCYXw7dqEnMNRjhGZlYK05Mj9OyktqV8uVT8fD2BFOB7S1uwBE3Kj2Z+4UyPmFw/Ixgw/LAlA==}
 
@@ -1355,6 +1364,10 @@ packages:
     engines: {node: '>=0.4.0'}
     hasBin: true
 
+  agent-base@7.1.4:
+    resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+    engines: {node: '>= 14'}
+
   ajv@6.12.6:
     resolution: {integrity: sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==}
 
@@ -1422,6 +1435,9 @@ packages:
     resolution: {integrity: sha512-BNoCY6SXXPQ7gF2opIP4GBE+Xw7U+pHMYKuzjgCN3GwiaIR09UUeKfheyIry77QtrCBlC0KK0q5/TER/tYh3PQ==}
     engines: {node: '>= 0.4'}
 
+  asn1.js@5.4.1:
+    resolution: {integrity: sha512-+I//4cYPccV8LdmBLiX8CYvf9Sp3vQsrqu2QNXRcrbiWvcx/UdlFiqUJJzxRQxgsZmvhXhn4cSKeSmoFjVdupA==}
+
   assertion-error@2.0.1:
     resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
     engines: {node: '>=12'}
@@ -1458,6 +1474,9 @@ packages:
     resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==}
     engines: {node: '>=8'}
 
+  bn.js@4.12.3:
+    resolution: {integrity: sha512-fGTi3gxV/23FTYdAoUtLYp6qySe2KE3teyZitipKNRuVYcBkoP/bB3guXN/XVKUe9mxCHXnc9C4ocyz8OmgN0g==}
+
   body-parser@1.20.4:
     resolution: {integrity: sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA==}
     engines: {node: '>= 0.8', npm: 1.2.8000 || >= 1.4.16}
@@ -1481,6 +1500,9 @@ packages:
     resolution: {integrity: sha512-WIsKqkSC0ABoBJuT1LEX+2HEvNmNKKgnTAyd0fL8qzK4SH2i9NXg+t08YtdZp/V9IZ33cxe3iV4yM0qg8lMQng==}
     engines: {node: '>=16.20.1'}
 
+  buffer-equal-constant-time@1.0.1:
+    resolution: {integrity: sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==}
+
   bytes@3.1.2:
     resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
     engines: {node: '>= 0.8'}
@@ -1744,6 +1766,9 @@ packages:
   eastasianwidth@0.2.0:
     resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
 
+  ecdsa-sig-formatter@1.0.11:
+    resolution: {integrity: sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==}
+
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
@@ -2132,6 +2157,14 @@ packages:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
 
+  http_ece@1.2.0:
+    resolution: {integrity: sha512-JrF8SSLVmcvc5NducxgyOrKXe3EsyHMgBFgSaIUGmArKe+rwr0uphRkRXvwiom3I+fpIfoItveHrfudL8/rxuA==}
+    engines: {node: '>=16'}
+
+  https-proxy-agent@7.0.6:
+    resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+    engines: {node: '>= 14'}
+
   iconv-lite@0.4.24:
     resolution: {integrity: sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==}
     engines: {node: '>=0.10.0'}
@@ -2379,6 +2412,12 @@ packages:
     resolution: {integrity: sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ==}
     engines: {node: '>=4.0'}
 
+  jwa@2.0.1:
+    resolution: {integrity: sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==}
+
+  jws@4.0.1:
+    resolution: {integrity: sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==}
+
   keyv@4.5.4:
     resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
 
@@ -2613,6 +2652,9 @@ packages:
     engines: {node: '>=4'}
     hasBin: true
 
+  minimalistic-assert@1.0.1:
+    resolution: {integrity: sha512-UtJcAD4yEaGtjPezWuO9wC4nwUnVH/8/Im3yEHQP4b67cXlD/Qr9hdITCU1xDbSEXg2XKNaP8jsReV7vQd00/A==}
+
   minimatch@3.1.2:
     resolution: {integrity: sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==}
 
@@ -3528,6 +3570,11 @@ packages:
       jsdom:
         optional: true
 
+  web-push@3.6.7:
+    resolution: {integrity: sha512-OpiIUe8cuGjrj3mMBFWY+e4MMIkW3SVT+7vEIjvD9kejGUypv8GPDf84JdPWskK8zMRIJ6xYGm+Kxr8YkPyA0A==}
+    engines: {node: '>= 16'}
+    hasBin: true
+
   webidl-conversions@4.0.2:
     resolution: {integrity: sha512-YQ+BmxuTgd6UXZW3+ICGfyqRyHXVlD5GtQr5+qjiNW7bF0cqrzX500HVXPBOvgXb5YnzDd+h0zqyv61KUD7+Sg==}
 
@@ -4396,6 +4443,10 @@ snapshots:
 
   '@types/unist@3.0.3': {}
 
+  '@types/web-push@3.6.4':
+    dependencies:
+      '@types/node': 22.19.3
+
   '@types/webidl-conversions@7.0.3': {}
 
   '@types/whatwg-url@11.0.5':
@@ -4552,6 +4603,8 @@ snapshots:
 
   acorn@8.15.0: {}
 
+  agent-base@7.1.4: {}
+
   ajv@6.12.6:
     dependencies:
       fast-deep-equal: 3.1.3
@@ -4649,6 +4702,13 @@ snapshots:
       get-intrinsic: 1.3.0
       is-array-buffer: 3.0.5
 
+  asn1.js@5.4.1:
+    dependencies:
+      bn.js: 4.12.3
+      inherits: 2.0.4
+      minimalistic-assert: 1.0.1
+      safer-buffer: 2.1.2
+
   assertion-error@2.0.1: {}
 
   async-function@1.0.0: {}
@@ -4679,6 +4739,8 @@ snapshots:
 
   binary-extensions@2.3.0: {}
 
+  bn.js@4.12.3: {}
+
   body-parser@1.20.4:
     dependencies:
       bytes: 3.1.2
@@ -4719,6 +4781,8 @@ snapshots:
 
   bson@6.10.4: {}
 
+  buffer-equal-constant-time@1.0.1: {}
+
   bytes@3.1.2: {}
 
   cac@6.7.14: {}
@@ -4947,6 +5011,10 @@ snapshots:
 
   eastasianwidth@0.2.0: {}
 
+  ecdsa-sig-formatter@1.0.11:
+    dependencies:
+      safe-buffer: 5.2.1
+
   ee-first@1.1.1: {}
 
   electron-to-chromium@1.5.267: {}
@@ -5528,6 +5596,15 @@ snapshots:
       statuses: 2.0.2
       toidentifier: 1.0.1
 
+  http_ece@1.2.0: {}
+
+  https-proxy-agent@7.0.6:
+    dependencies:
+      agent-base: 7.1.4
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
   iconv-lite@0.4.24:
     dependencies:
       safer-buffer: 2.1.2
@@ -5762,6 +5839,17 @@ snapshots:
       object.assign: 4.1.7
       object.values: 1.2.1
 
+  jwa@2.0.1:
+    dependencies:
+      buffer-equal-constant-time: 1.0.1
+      ecdsa-sig-formatter: 1.0.11
+      safe-buffer: 5.2.1
+
+  jws@4.0.1:
+    dependencies:
+      jwa: 2.0.1
+      safe-buffer: 5.2.1
+
   keyv@4.5.4:
     dependencies:
       json-buffer: 3.0.1
@@ -6186,6 +6274,8 @@ snapshots:
 
   mime@1.6.0: {}
 
+  minimalistic-assert@1.0.1: {}
+
   minimatch@3.1.2:
     dependencies:
       brace-expansion: 1.1.12
@@ -7246,6 +7336,16 @@ snapshots:
       - tsx
       - yaml
 
+  web-push@3.6.7:
+    dependencies:
+      asn1.js: 5.4.1
+      http_ece: 1.2.0
+      https-proxy-agent: 7.0.6
+      jws: 4.0.1
+      minimist: 1.2.8
+    transitivePeerDependencies:
+      - supports-color
+
   webidl-conversions@4.0.2: {}
 
   webidl-conversions@7.0.0: {}

From c5dcc0c55e204d89e015ee075a2bbd2a56d652b6 Mon Sep 17 00:00:00 2001
From: Zen0space <tartnenas_kai@outlook.com>
Date: Sat, 11 Apr 2026 20:37:34 +0800
Subject: [PATCH 2/2] fix: resolve ESLint lint errors and ignore generated
 service worker

- Merge duplicate @logto/next imports in page.tsx
- Fix import ordering (PwaAuthRedirect after landing components)
- Remove unused useSetAtom import in settings/client.tsx
- Use globalThis.NotificationPermission to fix no-undef in push-state
- Remove unnecessary eslint-disable comment for @next/next/no-img-element
- Ignore generated public/sw.js in ESLint config

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
---
 eslint.config.mjs                                           | 1 +
 packages/kal-frontend/src/app/dashboard/settings/client.tsx | 2 +-
 packages/kal-frontend/src/app/page.tsx                      | 6 ++----
 packages/kal-frontend/src/atoms/push-state.ts               | 2 +-
 4 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/eslint.config.mjs b/eslint.config.mjs
index 65af17d..e22a741 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -26,6 +26,7 @@ export default [
       "**/postcss.config.js",
       "**/tailwind.config.ts",
       "**/baml_client/**",
+      "**/public/sw.js",
     ],
   },
 
diff --git a/packages/kal-frontend/src/app/dashboard/settings/client.tsx b/packages/kal-frontend/src/app/dashboard/settings/client.tsx
index 184a9e7..e00771e 100644
--- a/packages/kal-frontend/src/app/dashboard/settings/client.tsx
+++ b/packages/kal-frontend/src/app/dashboard/settings/client.tsx
@@ -1,7 +1,7 @@
 "use client";
 
+import { useAtom, useAtomValue } from "jotai";
 import { RATE_LIMITS } from "kal-shared";
-import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import Link from "next/link";
 import { useSearchParams } from "next/navigation";
 import { useCallback, useEffect, useMemo, useState } from "react";
diff --git a/packages/kal-frontend/src/app/page.tsx b/packages/kal-frontend/src/app/page.tsx
index aafd7ff..e3076a6 100644
--- a/packages/kal-frontend/src/app/page.tsx
+++ b/packages/kal-frontend/src/app/page.tsx
@@ -1,5 +1,4 @@
-import { getLogtoContext } from "@logto/next/server-actions";
-import { signIn } from "@logto/next/server-actions";
+import { getLogtoContext, signIn } from "@logto/next/server-actions";
 
 import { FinalCTA } from "@/components/landing/CTA";
 import { FAQ } from "@/components/landing/FAQ";
@@ -9,9 +8,9 @@ import { Hero } from "@/components/landing/Hero";
 import { HowItWorks } from "@/components/landing/HowItWorks";
 import { Navbar } from "@/components/landing/Navbar";
 import { ProblemSolution } from "@/components/landing/ProblemSolution";
-import { PwaAuthRedirect } from "@/components/PwaAuthRedirect";
 import { SampleFoods } from "@/components/landing/SampleFoods";
 import { Testimonials } from "@/components/landing/Testimonials";
+import { PwaAuthRedirect } from "@/components/PwaAuthRedirect";
 import { getLogtoConfig } from "@/lib/logto";
 
 export default async function LandingPage() {
@@ -34,7 +33,6 @@ export default async function LandingPage() {
       <main className="min-h-screen bg-dark relative overflow-hidden">
         {/* Server-rendered splash — visible from first paint, no JS needed */}
         <div className="fixed inset-0 z-40 flex items-center justify-center bg-dark">
-          {/* eslint-disable-next-line @next/next/no-img-element */}
           <img
             src="/assets/icon-svg.svg"
             alt=""
diff --git a/packages/kal-frontend/src/atoms/push-state.ts b/packages/kal-frontend/src/atoms/push-state.ts
index 2c60d93..8a316c8 100644
--- a/packages/kal-frontend/src/atoms/push-state.ts
+++ b/packages/kal-frontend/src/atoms/push-state.ts
@@ -8,7 +8,7 @@ import { atom } from "jotai";
 export const pushSupportedAtom = atom(false);
 
 /** Current notification permission state */
-export const pushPermissionAtom = atom<NotificationPermission | "unsupported">("default");
+export const pushPermissionAtom = atom<globalThis.NotificationPermission | "unsupported">("default");
 
 /** Whether the user is currently subscribed to push notifications */
 export const pushSubscribedAtom = atom(false);