From 7bb86b20f0c9967887f7fea3f6e4f3db0fc23954 Mon Sep 17 00:00:00 2001
From: quartune <123062848+quartune@users.noreply.github.com>
Date: Sat, 27 Jun 2026 17:22:00 +0000
Subject: [PATCH] feat(#321): add PWA install prompt with 30s delay and 7-day
 dismiss suppression

- InstallBanner component captures beforeinstallprompt and shows after 30s
- Dismiss suppresses banner for 7 days via localStorage
- manifest.json extended with orientation and categories for Lighthouse
- layout.tsx cleaned up duplicate CommandPalette import
---
 public/manifest.json             |  2 +
 src/app/layout.tsx               |  3 +-
 src/components/InstallBanner.tsx | 94 ++++++++++++++++++++++++++++++++
 3 files changed, 98 insertions(+), 1 deletion(-)
 create mode 100644 src/components/InstallBanner.tsx

diff --git a/public/manifest.json b/public/manifest.json
index 5af349f..b39335d 100644
--- a/public/manifest.json
+++ b/public/manifest.json
@@ -7,6 +7,8 @@
   "display": "standalone",
   "background_color": "#030712",
   "theme_color": "#4f46e5",
+  "orientation": "any",
+  "categories": ["finance", "productivity"],
   "icons": [
     {
       "src": "/icons/icon-192.png",
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index f4b026e..5af195a 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -13,8 +13,8 @@ import RecipientOnboarding from "@/components/RecipientOnboarding";
 import HeaderShortcutsButton from "@/components/HeaderShortcutsButton";
 import CommandPalette from "@/components/CommandPalette";
 import { SessionLockProvider } from "@/contexts/SessionLockContext";
-import CommandPalette from "@/components/CommandPalette";
 import { ToastProvider } from "@/contexts/ToastContext";
+import InstallBanner from "@/components/InstallBanner";
 
 const accessibilityBootstrap = `
 (function () {
@@ -84,6 +84,7 @@ export default function RootLayout({
             <CommandPalette />
             <OnboardingFlow />
             <RecipientOnboarding />
+            <InstallBanner />
             </ToastProvider>
             </SessionLockProvider>
             <Script id="register-sw" strategy="afterInteractive">
diff --git a/src/components/InstallBanner.tsx b/src/components/InstallBanner.tsx
new file mode 100644
index 0000000..66ef8d7
--- /dev/null
+++ b/src/components/InstallBanner.tsx
@@ -0,0 +1,94 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+const DISMISS_KEY = "pwa_install_dismissed_until";
+const SUPPRESS_DAYS = 7;
+const SHOW_DELAY_MS = 30_000;
+
+export default function InstallBanner() {
+  const [prompt, setPrompt] = useState<Event | null>(null);
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    const dismissed = localStorage.getItem(DISMISS_KEY);
+    if (dismissed && Date.now() < Number(dismissed)) return;
+
+    const handler = (e: Event) => {
+      e.preventDefault();
+      setPrompt(e);
+    };
+
+    window.addEventListener("beforeinstallprompt", handler);
+    return () => window.removeEventListener("beforeinstallprompt", handler);
+  }, []);
+
+  useEffect(() => {
+    if (!prompt) return;
+    const id = setTimeout(() => setVisible(true), SHOW_DELAY_MS);
+    return () => clearTimeout(id);
+  }, [prompt]);
+
+  const handleInstall = async () => {
+    if (!prompt) return;
+    const deferredPrompt = prompt as BeforeInstallPromptEvent;
+    setVisible(false);
+    await deferredPrompt.prompt();
+  };
+
+  const handleDismiss = () => {
+    setVisible(false);
+    const until = Date.now() + SUPPRESS_DAYS * 24 * 60 * 60 * 1000;
+    localStorage.setItem(DISMISS_KEY, String(until));
+  };
+
+  if (!visible) return null;
+
+  return (
+    <div
+      role="banner"
+      className="fixed bottom-4 left-4 right-4 sm:left-auto sm:right-4 sm:w-80 z-50 flex items-start gap-3 rounded-xl bg-gray-900 border border-gray-700 shadow-2xl p-4"
+    >
+      <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-indigo-600 text-white text-lg select-none">
+        ✦
+      </div>
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-semibold text-white">Install StellarSplit</p>
+        <p className="text-xs text-gray-400 mt-0.5">
+          Add to your home screen for faster access and offline browsing.
+        </p>
+        <div className="flex gap-2 mt-3">
+          <button
+            type="button"
+            onClick={handleInstall}
+            className="px-3 py-1.5 rounded-md bg-indigo-600 hover:bg-indigo-500 text-xs font-semibold text-white transition-colors"
+          >
+            Install App
+          </button>
+          <button
+            type="button"
+            onClick={handleDismiss}
+            className="px-3 py-1.5 rounded-md bg-gray-700 hover:bg-gray-600 text-xs font-medium text-gray-300 transition-colors"
+          >
+            Not now
+          </button>
+        </div>
+      </div>
+      <button
+        type="button"
+        onClick={handleDismiss}
+        className="shrink-0 text-gray-500 hover:text-gray-300 transition-colors"
+        aria-label="Close install banner"
+      >
+        ✕
+      </button>
+    </div>
+  );
+}
+
+declare global {
+  interface BeforeInstallPromptEvent extends Event {
+    prompt(): Promise<void>;
+    userChoice: Promise<{ outcome: "accepted" | "dismissed" }>;
+  }
+}