From aaf31f26b73245749652175f1eb4aa09226d3df9 Mon Sep 17 00:00:00 2001
From: jtricerolph <info@tricerolph.com>
Date: Thu, 6 Aug 2026 14:12:12 +0000
Subject: [PATCH] Add iOS install hint + Apple PWA meta tags

iOS Safari has no beforeinstallprompt API, so the portal's Install
button (?install=1) silently did nothing there. IosInstallHint now
shows Share -> Add to Home Screen steps on Safari, or a prompt to
switch to Safari first if opened in another iOS browser/in-app
webview (those can't install PWAs on iOS at all).

Also added apple-mobile-web-app-title + apple-touch-icon so the
home screen icon isn't a page screenshot.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 frontend/index.html                        |  2 +
 frontend/src/App.tsx                       |  2 +
 frontend/src/components/IosInstallHint.tsx | 89 ++++++++++++++++++++++
 3 files changed, 93 insertions(+)
 create mode 100644 frontend/src/components/IosInstallHint.tsx

diff --git a/frontend/index.html b/frontend/index.html
index dd06a7d..229ae1d 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -6,6 +6,8 @@
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="default" />
+    <meta name="apple-mobile-web-app-title" content="Maintenance" />
+    <link rel="apple-touch-icon" href="/maintenance/icons/icon-192.png" />
     <meta name="theme-color" content="#b45309" />
     <title>Maintenance</title>
   </head>
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 94e1ea6..247c863 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,6 +1,7 @@
 import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
 import AuthGate from './components/AuthGate'
 import { UpdateBanner } from './components/UpdateBanner'
+import IosInstallHint from './components/IosInstallHint'
 import { useVersionCheck } from './hooks/useVersionCheck'
 import Layout from './components/Layout'
 import Summary from './pages/Summary'
@@ -33,6 +34,7 @@ export default function App() {
         </AuthGate>
       </BrowserRouter>
       <UpdateBanner visible={updateAvailable} />
+      <IosInstallHint />
     </>
   )
 }
diff --git a/frontend/src/components/IosInstallHint.tsx b/frontend/src/components/IosInstallHint.tsx
new file mode 100644
index 0000000..da58dd2
--- /dev/null
+++ b/frontend/src/components/IosInstallHint.tsx
@@ -0,0 +1,89 @@
+import { useEffect, useState } from 'react'
+import { Share, ExternalLink, X } from 'lucide-react'
+
+function isIos() {
+  return /iPad|iPhone|iPod/.test(navigator.userAgent) ||
+    // iPadOS 13+ reports as 'MacIntel' but has touch support, unlike a real Mac
+    (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1)
+}
+
+function isStandalone() {
+  return window.matchMedia('(display-mode: standalone)').matches ||
+    (window.navigator as unknown as { standalone?: boolean }).standalone === true
+}
+
+// Safari's UA also matches "Safari", so this checks for the other iOS
+// browsers/in-app webviews that spoof it — none of them can add to the
+// home screen; only Safari itself can.
+function isNonSafariIosBrowser() {
+  return /CriOS|FxiOS|EdgiOS|OPiOS|mercury|GSA|DuckDuckGo|Instagram|FBAN|FBAV|Line\//.test(navigator.userAgent)
+}
+
+/**
+ * iOS has no `beforeinstallprompt` API — Safari never fires it, so the
+ * portal's Install button (?install=1) does nothing there. This shows the
+ * manual steps instead: Share -> Add to Home Screen in Safari, or a prompt
+ * to switch to Safari first if the page was opened in another browser/app.
+ */
+export default function IosInstallHint() {
+  const [mode, setMode] = useState<'safari' | 'other' | null>(null)
+
+  useEffect(() => {
+    if (!isIos() || isStandalone()) return
+    if (!new URLSearchParams(window.location.search).has('install')) return
+    setMode(isNonSafariIosBrowser() ? 'other' : 'safari')
+  }, [])
+
+  if (!mode) return null
+
+  return (
+    <div style={{
+      position: 'fixed', inset: 0, zIndex: 9999,
+      background: 'rgba(15,15,32,0.55)',
+      display: 'flex', alignItems: 'flex-end', justifyContent: 'center',
+      padding: '0 16px 24px',
+    }}>
+      <div style={{
+        position: 'relative',
+        width: '100%', maxWidth: '360px',
+        background: 'var(--card-bg)', borderRadius: 'var(--radius)',
+        border: '1px solid var(--card-border)', boxShadow: 'var(--shadow-md)',
+        padding: '20px', textAlign: 'center',
+      }}>
+        <button
+          onClick={() => setMode(null)}
+          aria-label="Dismiss"
+          style={{
+            position: 'absolute', top: '10px', right: '10px',
+            background: 'none', border: 'none', color: 'var(--text-mid)',
+            padding: '4px', cursor: 'pointer', lineHeight: 0,
+          }}
+        >
+          <X size={16} strokeWidth={1.75} />
+        </button>
+
+        <div style={{
+          width: '44px', height: '44px', margin: '0 auto 12px',
+          borderRadius: '50%', background: 'var(--gold)',
+          display: 'flex', alignItems: 'center', justifyContent: 'center',
+        }}>
+          {mode === 'safari'
+            ? <Share size={22} strokeWidth={1.75} color="var(--navy)" />
+            : <ExternalLink size={22} strokeWidth={1.75} color="var(--navy)" />}
+        </div>
+
+        {mode === 'safari' ? (
+          <p style={{ fontSize: '14px', color: 'var(--text-dark)', lineHeight: 1.5, margin: 0 }}>
+            To install this app, tap the <strong>Share</strong> icon in Safari's
+            toolbar, then choose <strong>Add to Home Screen</strong>.
+          </p>
+        ) : (
+          <p style={{ fontSize: '14px', color: 'var(--text-dark)', lineHeight: 1.5, margin: 0 }}>
+            iOS only allows installing apps from <strong>Safari</strong>. Open this
+            page in Safari, then tap Share → <strong>Add to Home Screen</strong>.
+          </p>
+        )}
+      </div>
+    </div>
+  )
+}